ktsu.StrongStrings 1.4.3-pre.17

Prefix Reserved
This is a prerelease version of ktsu.StrongStrings.
dotnet add package ktsu.StrongStrings --version 1.4.3-pre.17
                    
NuGet\Install-Package ktsu.StrongStrings -Version 1.4.3-pre.17
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ktsu.StrongStrings" Version="1.4.3-pre.17" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ktsu.StrongStrings" Version="1.4.3-pre.17" />
                    
Directory.Packages.props
<PackageReference Include="ktsu.StrongStrings" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ktsu.StrongStrings --version 1.4.3-pre.17
                    
#r "nuget: ktsu.StrongStrings, 1.4.3-pre.17"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ktsu.StrongStrings@1.4.3-pre.17
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ktsu.StrongStrings&version=1.4.3-pre.17&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=ktsu.StrongStrings&version=1.4.3-pre.17&prerelease
                    
Install as a Cake Tool

ktsu.StrongStrings

A transparent wrapper around strings that provides strong typing, compile-time feedback, and runtime validation.

License NuGet NuGet Downloads Build Status GitHub Stars

Introduction

ktsu.StrongStrings is a .NET library that provides a way to create strongly-typed wrappers around standard strings. It gives you the benefits of strong typing, compile-time feedback, and runtime validation while maintaining full compatibility with string operations. The intention is to provide usage context and validation to naked strings in a similar way that Enums do for integers.

Features

  • Strong Typing: Create distinct types for different string usages (e.g., EmailAddress, UserId, Url)
  • Compile-Time Safety: Prevent mixing of semantically different strings
  • Runtime Validation: Apply custom validation rules that throw exceptions for invalid data
  • Transparent Usage: Works with existing string APIs through implicit conversion
  • String Operation Support: Full access to standard string methods and properties
  • Immutability: Implemented as records for value semantics and immutability

Installation

Package Manager Console

Install-Package ktsu.StrongStrings

.NET CLI

dotnet add package ktsu.StrongStrings

Package Reference

<PackageReference Include="ktsu.StrongStrings" Version="x.y.z" />

Usage Examples

Basic Example

using ktsu.StrongStrings;

// Create a strong type by deriving a record class from StrongStringAbstract<TDerived>:
public record class MyStrongString : StrongStringAbstract<MyStrongString> { }

public class MyDemoClass
{
    public MyStrongString Stronk { get; set; } = new();

    public static void Demo(MyStrongString inStrongString, string inSystemString, out MyStrongString outStrongString, out string outSystemString)
    {
        // You can implicitly cast down to a System.String
        outSystemString = inStrongString;

        // You must explicitly cast up to a StrongString
        outStrongString = (MyStrongString)inSystemString;

        //You can provide a StrongString to a method that expects a System.String
        Path.Combine(inStrongString, inSystemString);

        // You can use the .WeakString property or the .ToString() method to get the value of the underlying System.String
        outSystemString = inStrongString.WeakString;
        outSystemString = inStrongString.ToString();

        // You can not implicitly cast up to a StrongString
        // outStrongString = inSystemString; // This will not compile

        // You can not cast from one StrongString to another
        // OtherStrongString other = inStrongString; // This will not compile
        // OtherStrongString other = (OtherStrongString)inStrongString; // This will not compile either
    }
}

Validation Example

public abstract class StartsWithHttp : IValidator
{
    public static bool IsValid(AnyStrongString? strongString)
    {
        ArgumentNullException.ThrowIfNull(strongString);

        return strongString.StartsWith("http", StringComparison.InvariantCultureIgnoreCase);
    }
}

public abstract class EndsWithDotCom : IValidator
{
    public static bool IsValid(AnyStrongString? strongString)
    {
        ArgumentNullException.ThrowIfNull(strongString);

        return strongString.EndsWith(".com", StringComparison.InvariantCultureIgnoreCase);
    }
}

public record class MyValidatedString : StrongStringAbstract<MyValidatedString, StartsWithHttp, EndsWithDotCom> { }

// This will work:
MyValidatedString valid = (MyValidatedString)"http://example.com";

// This will throw a FormatException:
MyValidatedString invalid = (MyValidatedString)"ftp://example.net";

Advanced Usage

Creating Domain-Specific String Types

using ktsu.StrongStrings;

// Define validators
public abstract class ValidEmail : IValidator
{
    private static readonly Regex EmailRegex = new Regex(@"^[^@\s]+@[^@\s]+\.[^@\s]+$");
    
    public static bool IsValid(AnyStrongString? strongString)
    {
        ArgumentNullException.ThrowIfNull(strongString);
        return EmailRegex.IsMatch(strongString.ToString());
    }
}

// Create domain-specific types
public record class EmailAddress : StrongStringAbstract<EmailAddress, ValidEmail> { }
public record class Username : StrongStringAbstract<Username> { }
public record class UserId : StrongStringAbstract<UserId> { }

// Use in a service
public class UserService
{
    public User GetUser(UserId id) { /* ... */ }
    
    public void SendEmail(EmailAddress to, string subject) { /* ... */ }
    
    // Type safety ensures you can't pass a Username where UserId is expected
}

Modifying Strong Strings

// Strong strings are immutable, but you can create new ones with modifications
public record class Path : StrongStringAbstract<Path> { }

Path basePath = (Path)"/home/user";

// Add prefixes or suffixes
Path documentsPath = basePath.WithSuffix("/documents");  // "/home/user/documents"
Path etcPath = (Path)"/etc".WithSuffix("/config");       // "/etc/config"

// Combine with standard string methods
Path combined = (Path)(basePath + "/downloads");         // "/home/user/downloads"

API Reference

StrongStringAbstract<TDerived>

The base class for creating strongly-typed strings.

Properties
Name Type Description
WeakString string The underlying string value
Length int Length of the string
Methods
Name Return Type Description
IsEmpty() bool Checks if the string is empty
IsValid() bool Validates the string against defined validators
WithPrefix(string) TDerived Creates a new instance with the specified prefix
WithSuffix(string) TDerived Creates a new instance with the specified suffix
* * All standard string methods are available

IValidator Interface

Interface for implementing custom validation rules.

Methods
Name Return Type Description
IsValid(AnyStrongString?) bool Static method that validates a string

Contributing

Contributions are welcome! Here's how you can help:

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Please make sure to update tests as appropriate.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net8.0

    • No dependencies.
  • net9.0

    • No dependencies.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on ktsu.StrongStrings:

Package Downloads
ktsu.Extensions

A collection of useful extension methods for .NET types including strings, collections, dictionaries, enumerables, and reflection.

ktsu.AppDataStorage

Application data management library using JSON serialization to save and load data in the user's app data folder.

ktsu.StrongPaths

A library that provides strong typing for common filesystem paths providing compile time feedback and runtime validation.

ktsu.CredentialCache

CredentialCache

ktsu.GitIntegration

Git Integration

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.4.3-pre.17 121 5/20/2025
1.4.3-pre.15 81 5/17/2025
1.4.3-pre.14 129 5/16/2025
1.4.3-pre.13 195 5/15/2025
1.4.3-pre.12 197 5/14/2025
1.4.3-pre.11 201 5/13/2025
1.4.3-pre.10 227 5/12/2025
1.4.3-pre.9 170 5/11/2025
1.4.3-pre.8 107 5/10/2025
1.4.3-pre.7 53 5/9/2025
1.4.3-pre.6 128 5/8/2025
1.4.3-pre.5 124 5/7/2025
1.4.3-pre.4 119 5/6/2025
1.4.3-pre.3 120 5/5/2025
1.4.3-pre.2 116 5/4/2025
1.4.3-pre.1 119 5/4/2025
1.4.2 3,351 5/4/2025
1.4.2-pre.1 59 4/26/2025
1.4.1 400 4/26/2025
1.4.1-pre.1 121 4/4/2025
1.4.0 3,034 3/30/2025
1.3.1-pre.2 74 3/29/2025
1.3.1-pre.1 460 3/25/2025
1.3.0 5,248 2/17/2025
1.2.27-pre.3 79 2/6/2025
1.2.27-pre.2 62 2/5/2025
1.2.27-pre.1 72 2/5/2025
1.2.26 6,862 12/28/2024
1.2.26-pre.26 66 2/4/2025
1.2.26-pre.25 69 2/3/2025
1.2.26-pre.24 68 2/2/2025
1.2.26-pre.23 65 1/31/2025
1.2.26-pre.22 58 1/29/2025
1.2.26-pre.21 61 1/27/2025
1.2.26-pre.20 71 1/25/2025
1.2.26-pre.19 65 1/23/2025
1.2.26-pre.18 60 1/21/2025
1.2.26-pre.17 60 1/20/2025
1.2.26-pre.16 64 1/19/2025
1.2.26-pre.15 53 1/17/2025
1.2.26-pre.14 52 1/15/2025
1.2.26-pre.13 56 1/13/2025
1.2.26-pre.12 60 1/11/2025
1.2.26-pre.11 60 1/10/2025
1.2.26-pre.10 60 1/10/2025
1.2.26-pre.9 53 1/8/2025
1.2.26-pre.8 64 1/7/2025
1.2.26-pre.7 64 1/6/2025
1.2.26-pre.6 83 1/4/2025
1.2.26-pre.5 65 1/3/2025
1.2.26-pre.4 66 1/3/2025
1.2.26-pre.3 78 1/3/2025
1.2.26-pre.2 76 1/1/2025
1.2.26-pre.1 70 12/27/2024
1.2.25 1,831 12/26/2024
1.2.24 100 12/26/2024
1.2.23 100 12/26/2024
1.2.22 97 12/26/2024
1.2.21 94 12/26/2024
1.2.20 115 12/26/2024
1.2.19 109 12/26/2024
1.2.18 2,273 12/23/2024
1.2.17 102 12/23/2024
1.2.16 104 12/23/2024
1.2.15 1,969 12/4/2024
1.2.14 582 12/2/2024
1.2.13 589 11/30/2024
1.2.12 106 11/30/2024
1.2.11 713 11/20/2024
1.2.10 1,146 11/13/2024
1.2.9 926 11/1/2024
1.2.8 1,644 10/4/2024
1.2.7 906 9/19/2024
1.2.6 339 9/19/2024
1.2.5 269 9/19/2024
1.2.4 126 9/18/2024
1.2.3 124 9/18/2024
1.2.2 231 9/18/2024
1.2.1 428 9/18/2024
1.2.0 554 9/18/2024
1.1.1 434 9/14/2024
1.1.0 117 9/14/2024

## v1.4.3-pre.17

Initial release or repository with no prior history.