AsciiStr and AsciiString APIs should be similar to str and String APIs

[osa1]

Ideally the APIs should be the same, except the UTF-related bits (like str's utf16_units) and porting programs should be very easy. Currently lots of methods are missing in AsciiStr and AsciiString. (like str.lines(), str.bytes(). str.parse() ...)

[tormol]

Is there any work in progress here or can I work on this?

[tomprogrammer]

I did some work already and got stuck at the implementation of the custom iterators. I'm currently not at home and will push a new branch soon.

[tormol]

What should be done with methods with "str" in the name? It can refer both to ASCII str and UTF-8 str, but specifying breaks the API, and we might want both for interoperability.

From into_boxed_str() and from_boxed_str() we want to return Box<AsciiStr>/AsciiString, but from FromStrs from_str() we don't have a choice but to return str. And then there is AsciiString::as_str() which could return either.

[tomprogrammer]

The most methods returning an ascii string already use the ascii_str suffix, for example AsciiStr::to_ascii_string(). It also applies to all conversion traits, which return ascii strings (AsAsciiStr::as_ascii_str()). If the suffix is only str, like AsciiStr::as_str(), a UTF-8 string slice is returned.

I would like to follow this naming convention because it explicitly states whether the method works on ascii strings or UTF-8 strings.

That means the existing AsciiString::push_str() should be changed to AsciiString::push_ascii_str(). Of course that breaks the one-to-one mapping of the methods from String to AsciiString, but is it really that important? Changing these method calls should be fairly easy.

Using the example AsciiString::push_str() I see an ambiguity. Should this method take a str, push it onto the AsciiString and return a Result<AsciiString, FromAsciiError<Self>> or rather return a String? Mixing strings of different encoding should be handled by converting them into a common type before pushing, like ascii_string.push_ascii_str(string.as_ascii_str()?) or ascii_string.into_string().push_str(string).

I would call the methods into_boxed_ascii_str() and from_boxed_ascii_str() if they return Box<AsciiStr> or AsciiString. A method called into_boxed_str() should return Box<str> following the naming convention.

What do you think about it?

[PatrickNorton]

On a similar note, could we get Arc::<AsciiStr>::from(AsciiString) to mirror Arc::<str>::from(String)?