The good thing about the Swift API is that it gives you all the building blocks needed to actually having a chance at getting this right. Many other languages sweep those things under a rug and you're screwed or you'll have a much, much harder job to get it right if you need to.
Giving the wrong choice for most situations (and number of UTF-16 code units isn't what people want most of the time) the easy convenient name is just a recipe for broken code. It's bad API design, or at least unfortunate historical accident, and it's good to improve things when there is an opportunity to do so.
The correct way to solve this would be to design the API so that the distinction between what you're getting and what you want is clear, and the place to go to get what you actually want is also clear. Including nothing is an admission that they couldn't do this.
Which functions have they excluded? You mentioned counting characters, but you haven't actually specified which definition of characters you want it to use.
>The correct way to solve this would be to design the API so that the distinction between what you're getting and what you want is clear, and the place to go to get what you actually want is also clear
This is what they have done.
The typical human definition of characters. Humans usually don't think about bits or bytes and they shouldn't have to. A character is a single independent glyph, a separate unit that would be taught to a human whilst learning to write, regardless of the internal representation in the computer.
If I need something else, I should ask for something else.
Hypothetical API calls that may address this:
"String".length()
"String".lengthInBytes()
"String".lengthInCodePoints()
This would provide standard implementations for these common functions (circumventing the issue of copying a random chunk of code from SO and all its attendant problems), make it obvious that there is a difference to anyone browsing the docs and/or using autocomplete, and make it easy to select and use the one you actually want in a particular situation. This type of discoverability is an important component in a usable API.
"String".characters.count
"String".utf8.count
"String".unicodeScalars.count
If most people (let's say 99% for argument's sake) expect "string".length to refer to character count and only 1% need something like "string".utf8.count why not just accommodate them and make the language more accessible? This reminds me a bit of UX design. I've seen people time and again make the mistake over the years of designing their UX in a vacuum. What they produced wasn't bad or hard to use, it just broke expectations.
All that said, sometimes breaking expectations is exactly what you should do because someone has to for things to change and move in the right direction. And sometimes when you do that you're taking one for the team, so to speak. Of course I don't know shit, but if I were looking at making a language popular I'd weigh doing what's "right" against my desire to increase the popularity carefully.
Most people are not going to read through the entire list of methods of String and thereby discover .characters, .utf8, and .unicodeScalars when they want the character count of a string.
I acknowledge that it may not be difficult to find this information with a quick Google search, but the more that can be done without having to switch to the browser or docs to look something up, the better. Injecting these so that they appear more frequently on the most likely UX path is better.
And they probably indeed were.
Still VERY basic, and all should be provided by the standard library.
("basic" as: very basic and frequent needs. They are of course quite complicated to write. Which is even more of a reason to have them written for developers in the standard library).