Tracking Issue for str::{floor, ceil}_char_boundary

[clarfonthey]

Feature gate: #![feature(round_char_boundary)]

This is a tracking issue for str::{floor, ceil}_char_boundary.

Public API

impl str {
    // Returns the character boundary at or immediately before `index`
    const fn floor_char_boundary(&self, index: usize) -> usize;

    // Returns the character boundary at or immediately after `index`
    const fn ceil_char_boundary(&self, index: usize) -> usize;
}

Steps / History

• Implementation: Add {floor,ceil}_char_boundary methods to str #86497
  • Don't panic in ceil_char_boundary: Don't panic in ceil_char_boundary #112387
  • Made const: str: Mark unstable round_char_boundary feature functions as const #144472
• Final comment period (FCP)
• Stabilization PR

Unresolved Questions

• Should ceil_char_boundary panic when indices are out of bounds? Don't panic in ceil_char_boundary #112387 updated this to return len instead.

[nagisa]

Have methods that return str slices instead of indices been considered as an alternative? I didn't really see any discussion to that effect in the issue. Given that these indices are only really usable for slicing into the containing string these were calculated from, it isn't all that obvious to me if this is the right API, as opposed to split_at_???_char_boundary_{,mut}.

[clarfonthey]

So, that would work for purely code-based splitting, but if a user were to perform more-complicated splitting by something like graphemes or words, they'd want to be able to look at the string both before and after the truncation point, not just at that point.

Since some cases required the index specifically, I decided to keep the API surface small. But adding extra variants that directly slice the string could be very useful too, like the ones you offered.

[Stargateur]

I don't see why choice to panic instead of return Option<usize> or Result<usize, ()>

[clarfonthey]

The main reason I chose that was that floor_char_boundary can never panic, and I wanted parity for the API with ceil_char_boundary. Do you have a case that would benefit from such an API?

[Stargateur]

One can panic the other not is not parity either. I advice to avoid panic when possible, while there is already a number of method that panic instead of return an Option or a Result, adding new item should probably follow better guide line, specially since Rust could be use in Kernel linux, having method that panic on primitive type would automatically ban them from use.

On this case I wonder if floor_char_boundary make sense, char_indices doesn't include the "last" boundary cause there is no character. I would advice to change method floor_char_boundary to return None when the index would result in len and remove panic of other method too using option instead.

Or something else that remove the panic.

[clarfonthey]

So, the reason why one can panic and one can't is basically because of the fact that indexes can't go below zero, and so you can always round down to 0, which is always a valid char boundary. Here, the context is that if you want to limit the size of a string in bytes, you can "round down" from that to a valid index, such that you can slice up to that.

For ceil... the general idea, if I'm being honest, is to round "up" the recommended number of bytes. So, for example, if you want to limit to 1000 bytes, but are fine allowing up to 1004 to include the last character. I guess in this case, it would be okay to return len instead of panicking, but I don't know it this would make sense in all cases.

Definitely open to suggestions on what you think is best, but IMHO the flooring version should definitely never panic, and always return a valid index.

[angelorodem]

I think that removal of panic from this function is a must, the usage is to correctly find the bounds of a char and prevent panicking when doing string processing, it seems not good that a function to prevent that can indeed panic.

[clarfonthey]

So, I was poking around the uses of ceil_char_boundary on GitHub: https://github.com/search?q=ceil_char_boundary+lang%253Arust

and am thinking that maybe the solution to a non-panicking version of ceil_char_boundary is to just return the length of the string if the provided index is out of bounds. The semantics feel a bit muddy, but this feels like the most logical way based upon how people are using it. What do people think about this idea?

Effectively, if you pass an index past the end of the string, it's treated as the end of the string, and rounds "up" to the end of the string.

[eddyb]

So, that would work for purely code-based splitting, but if a user were to perform more-complicated splitting by something like graphemes or words, they'd want to be able to look at the string both before and after the truncation point, not just at that point.

Since some cases required the index specifically, I decided to keep the API surface small. But adding extra variants that directly slice the string could be very useful too, like the ones you offered.

I believe there is some confusion here. The "(split) index" is not lost during split_at.

s.split_at(i) returns (&s[..i], &s[i..]) and so:

• s.split_at(i).0.len() == i
• s.split_at(i).1.len() == s.len() - i

That is, it's strictly more information than the original i, and for the methods @nagisa suggested (which I'd call split_at_char_boundary_{before,after}), since you can keep the original s yourself, and get the split position by .0.len(), it's just more ergonomic to also have the two &str parts.

---

Also because {floor,ceil}_char_boundary already do all the checks split_at require, it should be 100% free to have split_at_char_boundary_{before,after} which return (&str, &str) instead of usize (with the first &str containing verbatim the usize of {floor,ceil}_char_boundary, as its length, as explained above).