ktsu.Semantics.Cpp 5.4.2

ktsu.Semantics

A .NET family of libraries for replacing primitive obsession with strongly-typed, self-validating domain models. Each pillar ships as its own NuGet package, so you take only what you need.

• Semantic Strings: type-safe wrappers like EmailAddress, UserId, BlogSlug with attribute-driven validation, plus a batteries-included identifiers package (Uuid, Ulid, Iban, Isbn, CreditCardNumber, JwtToken).
• Semantic Paths: a polymorphic IPath hierarchy for files, directories, absolute, relative, and combinations.
• Semantic Quantities: a metadata-generated, type-safe quantity system with a unified IVector0..IVector4 model covering 60+ physical dimensions and 200+ generated types. Optional per-storage-type alias packages let you write Mass instead of Mass<double>.
• Semantic Music: immutable musical value types (Pitch, Interval, Scale, Chord, Key, Duration, TimeSignature), with chord-symbol parsing and voicing, plus a harmonic and structural analysis layer.
• Semantic Color: a physically-grounded Color type with linear-RGB math, perceptual Oklab operations, and built-in WCAG accessibility checks.

Packages

Each package has its own README with the full API surface, examples, and reference tables. This document is the family overview.

All packages target net8.0–net10.0. Strings, Identifiers, Paths, Music, and Color additionally target netstandard2.0/netstandard2.1. Quantities and its alias packages are net8.0+ (they require INumber<T>).

Semantic strings

Define a string-shaped domain type, attach validation attributes, and get a compile-time-distinct type that validates on construction.

using ktsu.Semantics.Strings;

[IsEmailAddress]
public sealed record EmailAddress : SemanticString<EmailAddress> { }

[StartsWith("USER_"), HasNonWhitespaceContent]
public sealed record UserId : SemanticString<UserId> { }

EmailAddress email = EmailAddress.Create("user@example.com");
UserId userId = UserId.Create("USER_12345");

public void SendWelcomeEmail(EmailAddress to, UserId who) { /* ... */ }
// SendWelcomeEmail(userId, email);   // does not compile

The ktsu.Semantics.Strings.Identifiers package adds ready-made identifier types with real check-digit and structural validation:

using ktsu.Semantics.Strings.Identifiers;

Uuid id = Uuid.Create("123E4567-E89B-12D3-A456-426614174000"); // canonicalised to lowercase
Iban iban = Iban.Create("GB82 WEST 1234 5698 7654 32");        // whitespace stripped, mod-97 validated

Full detail: Semantics.Strings README and Semantics.Strings.Identifiers README.

Semantic paths

A path is a type that encodes whether it names a file or a directory and whether it is absolute or relative. Compose them with /, decompose with typed properties, and hold mixed paths behind IPath.

using ktsu.Semantics.Paths;

AbsoluteDirectoryPath projectDir = AbsoluteDirectoryPath.Create(@"C:\repos\app");
AbsoluteFilePath source = projectDir / RelativeFilePath.Create(@"src\Program.cs");

FileName name = source.FileName;              // Program.cs
FileExtension ext = source.FileExtension;     // .cs
RelativeFilePath rel = source.AsRelative(projectDir);

Full detail: Semantics.Paths README.

Semantic quantities

Every quantity is a vector whose direction-space dimensionality is part of the type. Operators flow from a metadata definition, so Force · Displacement yields Energy at compile time.

using ktsu.Semantics.Quantities;

Mass<double> m = Mass<double>.FromKilogram(2.0);
Speed<double> v = Speed<double>.FromMeterPerSecond(3.0);
MomentumMagnitude<double> p = m * v;          // Mass * Speed -> MomentumMagnitude

Force3D<double> f = new() { X = 3.0, Y = 4.0, Z = 0.0 };
ForceMagnitude<double> mag = f.Magnitude();   // 5.0

If a project uses one storage type throughout, reference an alias package and drop the generic argument entirely:

using ktsu.Semantics.Quantities;   // with ktsu.Semantics.Quantities.Double referenced

Mass mass = Mass.FromKilogram(10.0);
Speed speed = Speed.FromMeterPerSecond(15.0);

Full detail: Semantics.Quantities README. The unified vector model and generator are documented in docs/strategy-unified-vector-quantities.md and docs/physics-generator.md.

Semantic music

Immutable, validated musical value types plus an analysis layer that models harmony nested inside structure. Pure logic, no I/O. The pitch convention is MIDI 60 = C4.

using ktsu.Semantics.Music;

Progression prog = Progression.Parse("| Dm7 | G7 | Cmaj7 |");
Key key = prog.InferKey()!;                             // C major
IReadOnlyList<string> roman = prog.RomanNumerals(key);  // ii7, V7, Imaj7

Chord cmaj7 = Chord.Parse("Cmaj7");
IReadOnlyList<Pitch> voicing = cmaj7.Voice(octave: 4);  // C4, E4, G4, B4

Full detail: Semantics.Music README.

Semantic color

The canonical Color stores linear RGBA, so mixing, interpolation, and luminance are physically correct. Perceptual work happens in Oklab, and WCAG accessibility tooling is built in.

using ktsu.Semantics.Color;

Color text = Color.FromHex("#777777");
Color background = NamedColors.White;

if (text.AccessibilityLevelAgainst(background) < AccessibilityLevel.AA)
{
    text = text.AdjustForContrast(background, AccessibilityLevel.AA);
}

IReadOnlyList<Color> ramp = NamedColors.Red.Gradient(NamedColors.Blue, 5); // Oklab gradient

Full detail: Semantics.Color README.

Dependency injection

services.AddTransient<ISemanticStringFactory<EmailAddress>, SemanticStringFactory<EmailAddress>>();

public class UserService(ISemanticStringFactory<EmailAddress> emails)
{
    public User CreateUser(string raw) =>
        emails.TryFromString(raw, out EmailAddress? email)
            ? new User(email!)
            : throw new ArgumentException("invalid email");
}

Performance

Every release measures a fixed set of benchmarks and adds a point to a chart per library. The numbers behind them are in docs/benchmarks/, and the suite is Semantics.Benchmarks.

Read the two halves of every chart differently. Allocation is exact — the same code allocates the same bytes on any machine, so a step in the top row is always a real change. Time is measured on shared CI runners, where the host a job happens to land on varies more than most releases do, so each time is divided by a reference workload measured in the same job. That cancels most of the difference between machines; what is left is indicative rather than precise. One caveat on the paths chart: its inputs are built per platform, because whether a path is absolute is a question the operating system answers differently, so its allocation row can step when the measuring host changes rather than when the library does. The other two charts take their inputs from compile-time constants and do not have that exposure.

Quantities

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/benchmarks/performance-dark.svg"> <img alt="Allocated bytes per operation, and time relative to a fixed reference workload, for each Semantics.Quantities release" src="docs/benchmarks/performance.svg"> </picture>

The grid is one operation per storage type rather than every operation at one storage type. A quantity is a readonly record struct over its T and does almost nothing of its own — a value is held in the SI base unit, so an operator is the storage type's arithmetic and a struct initialiser — so the same line of user code costs different things depending on the T it was written against, and a release changes it per T.

Strings

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/benchmarks/strings-performance-dark.svg"> <img alt="Allocated bytes per operation, and time relative to a fixed reference workload, for each Semantics.Strings release" src="docs/benchmarks/strings-performance.svg"> </picture>

The axis here is validation weight, because that is where a semantic string spends. Create goes through Activator.CreateInstance, a PropertyInfo.SetValue, and a reflective walk of the type's validation attributes on every call, so the top row walks from that machinery alone up through a character set check, a format check, and a mod-97 check. The bottom row is what surrounds it: both failure paths, the cross-type conversion that is a full creation in disguise, and the hash a dictionary of semantic strings pays on every lookup.

This is a different answer from the quantities one, and worth stating plainly rather than leaving to be inferred from a chart: a quantity's wrapper is free, and a semantic string's is not. What it buys is that an invalid value cannot exist, checked once at the boundary instead of everywhere the value is used.

Paths

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/benchmarks/paths-performance-dark.svg"> <img alt="Allocated bytes per operation, and time relative to a fixed reference workload, for each Semantics.Paths release" src="docs/benchmarks/paths-performance.svg"> </picture>

Building each kind of path, then operating on one. The two file name panels sit next to each other deliberately: FileNameWithoutExtension caches into a field, FileName rebuilds and revalidates on every read, and both look like field access at a call site.

Architecture

The quantity system is metadata-driven. The single source of truth is Semantics.SourceGenerators/Metadata/dimensions.json (with units.json, magnitudes.json, conversions.json, domains.json, and logarithmic.json alongside it), and a Roslyn incremental generator emits the quantity records, unit-conversion factories, cross-dimensional operators, and physical constants. Generated output is committed to Semantics.Quantities/Generated/ so the project compiles without first running the generator.

The string and path systems share an attribute → strategy → rule → factory validation pipeline. See docs/architecture.md.

Documentation

• Complete library guide (start here for a feature tour).
• Architecture (strings/paths/validation)
• Architecture (physics, unified vector model)
• Source-generator workflow
• Physics domains tour
• Validation attributes reference
• Advanced usage patterns

Per-package API detail lives in each package's own README, linked from the Packages table above.

Contributing

Contributions are welcome. Please open an issue first for major changes so we can discuss the direction. The branch's open work items are tracked as GitHub issues.

License

MIT. See LICENSE.md.