std.mem: introduce cut functions; rename "index of" to "find"

[andrewrk]

1. Introduce cut functions: cut, cutPrefix, cutSuffix, cutScalar, cutLast, cutLastScalar

2. Moving towards our function naming convention of having one word per concept and constructing function names out of concatenated concepts.

In std.mem the concepts are:
* "find" - return index of substring
* "pos" - starting index parameter
* "last" - search from the end
* "linear" - simple for loop rather than fancy algo
* "scalar" - substring is a single element

[matklad]

We have similar cut, cut_prefix, and cut_suffix functions in TigerBeetle, though not generic.

/// Splits the `haystack` around the first occurrence of `needle`, returning parts before and after.
///
/// This is a Zig version of Go's `string.Cut` / Rust's `str::split_once`. Cut turns out to be a
/// surprisingly versatile primitive for ad-hoc string processing. Often `std.mem.indexOf` and
/// `std.mem.split` can be replaced with a shorter and clearer code using  `cut`.
pub fn cut(haystack: []const u8, needle: []const u8) ?struct { []const u8, []const u8 } {
    const index = std.mem.indexOf(u8, haystack, needle) orelse return null;

    return .{ haystack[0..index], haystack[index + needle.len ..] };
}

pub fn cut_prefix(haystack: []const u8, needle: []const u8) ?[]const u8 {
    if (std.mem.startsWith(u8, haystack, needle)) {
        return haystack[needle.len..];
    }
    return null;
}

pub fn cut_suffix(haystack: []const u8, needle: []const u8) ?[]const u8 {
    if (std.mem.endsWith(u8, haystack, needle)) {
        return haystack[haystack.len - needle.len ..];
    }
    return null;
}

I have a strong opinion that cut in particular is just awesome, it's a swiss-army knife of add-hoc string processin. golang/go#46336 has a bunch of examples demonstrating Cut's utility. For the reference, rust-lang/rust#74707 added equivalent function to Rust (I now regret not coming up with the "cut" name at that time).

Specific suggestions:

• Consider adding "chomp the middle away" variant, in addition to prefix/suffix
• Consider using cut name, I think Go got it right!

[matklad]

const mod_name, const root_src_orig = mem.cut(u8, rest, "=") orelse .{ rest, null };

would be one example of cut being useful.

[andrewrk]

it would need to be cutScalar in order to match performance characteristics

[andrewrk]

• switched to "cut" naming
• renamed all "index of" names to "find"
• added "cut" along with "scalar" and "last" variants

[andrewrk]

I now regret not coming up with the "cut" name at that time

tagging 1.0 will be a bittersweet moment, indeed

[linux-user36]

What about the order of these "concepts" in the identifier? If I saw correctly, there's now

• findLastAny and findLastNone ("last" comes first), but
• findScalarLast ("last" comes last).

Since "any", "none", and "scalar" are all describing the same thing, namely the kind of needle the function takes, I would assume them all to be positioned the same relative to other "concepts". This would aid both discoverability as well as ease of memorizing and editing (i.e., if I notice I actually needed findLastAny instead of findScalarLast, I only need to change one term, and not also the order).

I can imagine both orders as sensible, namely:

• The kind of needle could come first, because it's mandatory in comparison to the other "concepts" and changes the actual argument types, not just the behavior. (That could be a simple convention.)
• last could come first, to aid greppability. When I look for findLast, I don't care whether the string format I'm implementing only uses one separator ("scalar") or multiple ("any").

[linux-user36]

@andrewrk Pinging since I believe my comment might have been overlooked. It'd just be a pity to have to breaking-change these names again if the inconsistency is only noticed after the next release. Feel free to ignore if I've simply misunderstood the naming. :-)