Expand SearchValues remarks with cached-instance guidance and worked examples

[Copilot]

The SearchValues and SearchValues<T> remarks were thin on when the type is actually the right tool. This adds use-case guidance and compilable samples covering char, byte, and string sets, plus clarification on when not to reach for SearchValues.

SearchValues<T> remarks

• Added a method table mapping each MemoryExtensions search API to what it's for, and a "Common use cases" section covering escaping, validation, UTF-8 data, and multi-substring search.
• Emphasized caching in a static readonly field, since instance creation is where the analysis cost is paid.
• Noted that the benefit grows with set size: the ContainsAny/IndexOfAny overloads taking individual values stop at three, and passing a longer span of values is slower than a cached instance.
• Added a thread-safety note.

SearchValues<T>.Contains remarks

• Steered readers toward the span-searching methods; Contains in a loop can't vectorize. Listed the cases where a single-value test is legitimate.
• For SearchValues<string>, clarified that Contains tests the whole value against the set — it's not a substring search — and that FrozenSet<string>.Contains is faster for that. SearchValues<string> is for multi-substring searching.

SearchValues.Create overload remarks

• Byte overload: pointed at UTF-8 literals ("..."u8) to build the set without allocating a string.
• String overload: documented that a single-value instance is a faster alternative to IndexOf(value, StringComparison), because the value is analyzed once at creation rather than per search.

private static readonly SearchValues<string> s_chunked =
    SearchValues.Create(["chunked"], StringComparison.OrdinalIgnoreCase);

// Equivalent to text.IndexOf("chunked", StringComparison.OrdinalIgnoreCase),
// but faster because the value is analyzed once when the instance is created.
public static int IndexOfChunked(ReadOnlySpan<char> text) => text.IndexOfAny(s_chunked);

Snippets

New compilable project at snippets/csharp/System.Buffers/SearchValues/Overview/ with five regions: an escaping loop driven by IndexOfAny, allowed-character validation via ContainsAnyExcept, UTF-8 delimiter search, multi-substring and single-substring SearchValues<string> search, and a \uXXXX decoder demonstrating the narrow case where Contains is correct.

Samples deliberately avoid anything that reads as a copy-pastable security check (no HTML/output escaping predicate), and each region is chosen so the API shown is genuinely the best fit — e.g. the escaping loop can't be expressed with SplitAny or ReplaceAny.

---

Internal previews

File	Preview link
snippets/csharp/System.Buffers/SearchValues/Overview/searchvalues.cs	Preview published page
xml/System.Buffers/SearchValues.xml	Preview published page
[xml/System.Buffers/SearchValues1.xml](https://github.com/dotnet/dotnet-api-docs/blob/685783748bf6f8531c12eaf199a614ad78d2af20/xml/System.Buffers/SearchValues1.xml)	Preview published page

[MihaZupan]

@copilot Replace the Host example with a method that checks if the input is a hex string.

[Copilot]

@copilot Replace the Host example with a method that checks if the input is a hex string.

Done in 2f843d8 — the validation sample is now IsHexString using ContainsAnyExcept over SearchValues.Create("0123456789ABCDEFabcdef").

[MihaZupan]

@copilot Drop the "or example when escaping JSON, JavaScript, or console output" part. Let's avoid suggesting that any sample is doing sufficient validation for any specific use case.

Swap the sample order such that the hex example is before the encoding one.

[Copilot]

@copilot Drop the "or example when escaping JSON, JavaScript, or console output" part. Let's avoid suggesting that any sample is doing sufficient validation for any specific use case.

Swap the samp...

Done in e0a83b9 — dropped the "escaping JSON, JavaScript, or console output" phrasing and moved the hex validation sample ahead of the escaping one (in both the remarks and the snippet file).

[Copilot]

Pull request overview

This PR expands the API reference remarks for System.Buffers.SearchValues and System.Buffers.SearchValues<T> to provide clearer guidance on when to use cached SearchValues instances, which span-search APIs to prefer, and how to apply the APIs in common scenarios. It also adds a compilable snippet project with worked examples across char, byte, and string sets.

Changes:

• Expanded SearchValues<T> and SearchValues remarks with usage guidance, method mapping, caching recommendations, and thread-safety notes.
• Added detailed remarks for SearchValues<T>.Contains (including guidance for SearchValues<string> semantics).
• Introduced a new snippet project with multiple regions demonstrating recommended patterns.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
xml/System.Buffers/SearchValues`1.xml	Adds extensive markdown remarks for SearchValues<T> and its Contains method, with multiple referenced examples.
xml/System.Buffers/SearchValues.xml	Updates remarks for the factory methods and adds example references for byte/char/string creation guidance.
snippets/csharp/System.Buffers/SearchValues/Overview/searchvalues.cs	New snippet source containing multiple regions illustrating span searching, validation, UTF-8 delimiter search, substring search, and the narrow Contains use case.
snippets/csharp/System.Buffers/SearchValues/Overview/Project.csproj	New snippet project to ensure examples compile in CI.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[BillWagner]

This LGTM.

Thanks @MihaZupan