rust-ascii
rust-ascii copied to clipboard
tomprogrammer
AsciiStr and AsciiString APIs should be similar to str and String APIs
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() ...)
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.
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.
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?
On a similar note, could we get Arc::<AsciiStr>::from(AsciiString) to mirror Arc::<str>::from(String)?
