Strings and Text

Choose the right layer for native UTF-8 values, familiar String algorithms, incremental construction, and explicit encoding conversion.

UTF-8 storageCore.Base + TextPorting guide

The three layers

Layer	Role	Use it for
`SharpRuntime::String` / `std::string`	Owning UTF-8 byte value	Storage, native APIs, containers, value passing
`System::String`	Static compatibility algorithms	Search, split/join, trim, format, compare, replace, substring
`System::Text`	Builders, encodings, Unicode-shaped helpers	Incremental construction and explicit byte/text conversion

This separation preserves native interoperability without pretending that a mutable UTF-8 std::string is a managed immutable UTF-16 object.

Core rules

Lengths and positions in the common string helpers are UTF-8 storage bytes.
An ordinary string is owned and non-null; use an optional or pointer when absence matters.
Helper operations usually return new values, but native std::string mutation remains possible.
Comparison modes currently reduce to case-sensitive bytes or per-byte native lowercasing.
Hashes are native process/container values, not persistent or .NET-compatible identifiers.
Normalization, grapheme segmentation, and full culture collation require a dedicated Unicode implementation.

Common C# translations

C# / .NET	Sharp Runtime / C++	Difference to review
`string s = "x";`	`std::string s = "x";`	Native value, UTF-8 bytes
`s.Length`	`s.size()`	Bytes, not UTF-16 units
`s.Substring(i, n)`	`System::String::Substring(s, i, n)`	Byte range and owning copy
`string.IsNullOrEmpty(s)`	`System::String::IsNullOrEmpty(s)`	Reference cannot be null
`string.Join`	`System::String::Join`	Curated overload set
`StringBuilder`	`System::Text::StringBuilder`	Positions and length are bytes
`Encoding.UTF8`	`System::Text::Encoding::UTF8()`	Shared mutable factory instance

Choose the detailed document

System::String referenceConstruction model, method families, examples, comparison, formatting, and deviations. String internalsStorage, lifetime, encoding, builder, normalization, hashing, and interop. Strings tutorialA focused path through UTF-8 and StringBuilder. Type systemHow string values relate to Object, nullable values, arrays, and native ownership.

Component selection

The native value and System::String helper are owned by Core.Base. Builders and encoding families are owned by Text. JSON and regular expressions are separate physical components.

set(SHARP_RUNTIME_COMPONENTS
    Text
    Text.Json
)
set(SHARP_RUNTIME_BUILD_TESTS OFF CACHE BOOL "" FORCE)
add_subdirectory(sharp-runtime)

target_link_libraries(app PRIVATE
    SharpRuntime::Text
    SharpRuntime::Text.Json
)

Unicode boundary

UTF-8 is a storage encoding, not a complete text-processing policy. Define whether an operation works in bytes, Unicode scalar values, normalized text, grapheme clusters, or display cells. Sharp Runtime is strong at native byte ownership and familiar helpers; it deliberately does not supply full ICU-class normalization, collation, casing, or grapheme data.