[API Proposal]: Add SearchValues.CreateRange

[Neme12]

Background and motivation

I'm proposing a new way of creating SearchValues - instead of some values, it would represent all values except that value (CreateExcept), or a range of values. I know I can achieve this via IndexOfAnyExcept, IndexOfAnyInRange and IndexOfAnyExceptInRange, but encapsulating the search inside SearchValues seems like a much better design to me than method explosions like this, and the three methods I mentioned would be now unnecessary and effectively obsolete. It would be convenient to be able to always store SearchValues<T>, even in case of ranges, and then use the one method that uses it.

API Proposal

namespace System.Buffers;

public static partial class SearchValues
{
	public static SearchValues<T> CreateExcept<T>(params ReadOnlySpan<T> values);

	public static SearchValues<T> CreateRange<T>(T lowInclusive, T highInclusive);
	public static SearchValues<T> CreateExceptRange<T>(T lowInclusive, T highInclusive);

	public static SearchValues<T> CreateRanges<T>(params ReadOnlySpan<Range<T>> ranges);
	public static SearchValues<T> CreateExceptRanges<T>(params ReadOnlySpan<Range<T>> ranges);

	public readonly struct Range<T> : IEquatable<Range<T>>
	{
		public Range(T value);
		public Range(T lowInclusive, T highInclusive);

		public T LowInclusive { get; }
		public T HighInclusive { get; }

		public void Deconstruct(out T lowInclusive, out T highInclusive);

		public static implicit operator Range<T>(T value);
		public static implicit operator Range<T>((T lowInclusive, T highInclusive) range);
	}
}

Note: The T might have to be expanded to a list of overloads for concrete types instead of being generic.

Also, if I'm unsure whether to use CreateRange with 2 or 3 sequential elements or Create with those elements, no matter what I pick, it would be nice if the implementation chose the right and fastest form of searching for such a set no matter which method I choose, so I don't have to worry about it. Tbat's the benefit of using SearchValues, even for ranges.

API Usage

var searchValues = SearchValues.CreateExceptRange<char>('a', 'z');
var index = span.IndexOfAny(searchValues);

var invalidChars = SearchValues.CreateRanges<char>(((char)0, (char)31), '@', '#', '|');
var index2 = span.IndexOfAny(invalidChars);

// or, get all control characters except for newline
var invalidChars2 = SearchValues.CreateRanges<char>(((char)0, (char)9), ((char)11, (char)31));

Alternative Designs

As an alternative, only the CreateRange and CreateRanges APIs could be added - those are the ones I'd like to use.

Risks

Idk. cc @stephentoub

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-memory
See info in area-owners.md if you want to be subscribed.

[MihaZupan]

CreateExcept is a duplicate of #96844.

I know I can achieve this via IndexOfAnyExcept, IndexOfAnyInRange and IndexOfAnyExceptInRange, but encapsulating the search inside SearchValues seems like a much better design to me than method explosions like this, and the three methods I mentioned would be now unnecessary and effectively obsolete. It would be convenient to be able to always store SearchValues, even in case of ranges, and then use the one method that uses it.

I get that it may sometimes be simpler to just store a single field if the set of values is unknown to you at compile time. But it's not clear to me in what scenario you'd get that information sometimes in the form of a set and sometimes in the form of a range.

If you know that it'll be a range, then using the dedicated InRange helpers you mentioned is already an option that'd perform optimally.

Can you please expand on the intended use case where this would be helpful, and using range helpers would be less convenient?

[Neme12]

It's not sometimes this, sometimes that with the same SearchValues. It's - sometimes I need to search for specific values - so I save them as SearchValues, and sometimes I need to look for a range, so I save it differently, instead of conveniently using SearchValues in both places.

[MihaZupan]

And both places are going through the same helpers that happen to accept SearchValues?
Or are you talking about two separate use cases and just prefer to have a SearchValues field over the range start/end?

[Neme12]

The second I think.

[Neme12]

How do I know whether it's more efficient to create a SearchValues with the separate values of 1 and 2 or use IndexOfAnyInRange with 1 and 2? I don't. SearchValues could encapsulate all of this for me and pick the best searching strategy, no matter whether I use 1 and 2 or a range betweeen 1 and 2.

[MihaZupan]

Is that actually a common scenario you run into when you're given an arbitrary range at runtime?
In your use case, where are the ranges coming from?

FWIW both IndexOfAny('1', '2') and IndexOfAnyInRange('1', '2') are perfectly fine choices in this case and the perf would be very close anyway. If I knew my input were always a range, even if it was sometimes a very small one, I'd use the InRange helper even just for readability's sake.

[Neme12]

At runtime? As opposed to compile time? I don't understand.

[MihaZupan]

If the values are already known to you at compile time, then I don't see why you wouldn't just use IndexOfAnyInRange(const, const)?
Tt's the most readable option and has optimal perf.

[Neme12]

I don't know, I'm not an expert on the perf here, I just know that always having SearchValues for what I'm searching for is convenient. And if this existed before, there would have been no need for IndexOfAnyInRange and the other tons of methods, only one, as everything would have been encapsulated in the SearchValues. As I said, that seems like a much better design to me - a single type that stores the type of search I'm doing, and one method to search for it.

[MihaZupan]

Dedicated APIs for various types of searches on span are still valuable for readability, and because you don't always have the option to cache the SearchValues - allocating a new one every time has significant overhead compared to the search itself.

IMO the only argument for adding a helper such as CreateFromRange would be to help in a scenario where:

• your ranges are potentially large, such that it's not feasible/readable to just write them out, AND
• you have shared helpers that accept arbitrary SearchValues<T> arguments, such that you aren't able to just use the dedicated IndexOfAnyInRange method, AND
• materializing Enumerable.Range(...).ToArray() to pass to Create would meaningfully impact performance, or you care about the added readability of the dedicated helper

I haven't seen that come up enough to judge if it's worth it.
Since the API & implementation is trivial, I'd keep this issue open to see if there's more demand for this (if this applies to you, upvote the issue/comments to help us prioritize).