Documentation on Dotnet Util

Collections

Mon, 01 Jan 0001 00:00:00 +0000

Features

AnsiColors: static class with ANSI escape code string constants for console foreground colors (DarkGray, Cyan, White, Yellow, Red, Magenta, BrightRed, Green) plus Reset, which returns the terminal to its default colors.
Characters: static class with string constants for character pools — digits, lowercase letters, uppercase letters, special characters, and the union All. Special is the complete set of ASCII punctuation, so a character counts as special exactly when it is printable ASCII and not alphanumeric.

Class Diagram

classDiagram
 namespace Collections {
 class AnsiColors {
 <<static>>
 +string Reset
 +string DarkGray
 +string Cyan
 +string White
 +string Yellow
 +string Red
 +string Magenta
 +string BrightRed
 +string Green
 }
 class Characters {
 <<static>>
 +string Digits
 +string LowerLetters
 +string UpperLetters
 +string Special
 +string All
 }
 }

Usage

ANSI Colors

Wrap text in a color constant and reset with AnsiColors.Reset:

Console

Mon, 01 Jan 0001 00:00:00 +0000

Features

CustomConsole: static helpers for writing formatted output to the system console — currently a separator line built from a single repeated character.

Class Diagram

classDiagram
 namespace Console {
 class CustomConsole {
 <<static>>
 +void WriteCharLine(char c, int quantity)
 }
 }

Usage

Write a separator line

using ArturRios.Util.Console;

// Defaults: 100 dashes
CustomConsole.WriteCharLine();
// ----------------------------------------------------------------------------------------------------

Choose the character and the length

CustomConsole.WriteCharLine('=', 40);
// ========================================

CustomConsole.WriteCharLine('*'); // 100 asterisks
CustomConsole.WriteCharLine('-', 0); // empty line

A negative quantity throws ArgumentOutOfRangeException.

Flow Control

Mon, 01 Jan 0001 00:00:00 +0000

Features

Condition: fluent condition aggregator; collects failure messages in order — repeats included — and can throw ConditionFailedException or convert to a process output. FailsWith throws InvalidOperationException when no True/False precedes it.
ConditionFailedException: exception carrying all collected error messages as string[].
Retry: simple retry with configurable max attempts and fixed delay; supports Action, Func<T> and the asynchronous ExecuteAsync overloads, a When predicate to restrict which exceptions are retried, and JitteredBackoff to space attempts with the same exponential-plus-jitter schedule as JitteredWaiter. MaxAttempts(n) runs the operation at most n times in total, and a configured instance is reusable.
JitteredWaiter: exponential backoff with jitter, capped at maxWaitMilliseconds (30 s by default); WaitAsync accepts a CancellationToken, exposes CanRetry and throws MaxRetriesReachedException when retries are exhausted.
MaxRetriesReachedException: exception thrown when JitteredWaiter exceeds its retry limit.

Class Diagram

classDiagram
 namespace FlowControl {
 class Condition {
 -List~string~ _failedConditions
 -bool? _expression
 +static Condition Create
 +string[] FailedConditions
 +bool IsSatisfied
 +Condition True(bool expression)
 +Condition False(bool expression)
 +Condition FailsWith(string error)
 +void ThrowIfNotSatisfied()
 +ProcessOutput ToProcessOutput()
 }
 class ConditionFailedException {
 +string[] Errors
 }
 class Retry {
 -int _delayMilliseconds
 -int _maxAttempts
 +static Retry New
 +Retry MaxAttempts(int maxAttempts)
 +Retry DelayMilliseconds(int delayMilliseconds)
 +Retry JitteredBackoff(int maxWaitMilliseconds)
 +Retry When(Func~Exception, bool~ predicate)
 +Retry When~TException~()
 +void Execute(Action action)
 +T Execute~T~(Func~T~ func)
 +Task ExecuteAsync(Func~CancellationToken, Task~ operation, CancellationToken)
 +Task~T~ ExecuteAsync~T~(Func~CancellationToken, Task~T~~ operation, CancellationToken)
 }
 }
 namespace FlowControl_Waiter {
 class JitteredWaiter {
 -const int FixedWaitDelay
 +int MaxRetryCount
 -int Count
 +bool CanRetry
 +Task WaitAsync(CancellationToken)
 }
 class MaxRetriesReachedException
 }
 Condition ..> ConditionFailedException : throws
 JitteredWaiter ..> MaxRetriesReachedException : throws

Usage

Condition

Chain boolean assertions — all failures are collected before throwing:

Hashing

Mon, 01 Jan 0001 00:00:00 +0000

Features

Hash: static helpers for Argon2id password hashing — encode with a provided or randomly generated salt, and verify plaintext against a stored hash. Verification is constant time and accepts the same optional HashConfiguration used to produce the hash, so non-default cost parameters can be verified. Salts must be at least 8 bytes.
HashConfiguration: configures Argon2id cost parameters — degree of parallelism, number of iterations, and memory usage in KB; each must be at least 1. The defaults are deliberately expensive (600 MB across 16 lanes per hash), which suits a login path but not a service hashing many secrets at once. Changing them invalidates existing hashes.

Class Diagram

classDiagram
 namespace Hashing {
 class Hash {
 <<static>>
 -const int Argon2IdKeyBytes
 -const int SaltByteSize
 -byte[] CreateSalt()
 +byte[] EncodeWithSalt(string text, byte[] salt, HashConfiguration? configuration)
 +byte[] EncodeWithRandomSalt(string text, out byte[] salt, HashConfiguration? configuration)
 +bool TextMatches(string text, byte[] hash, byte[] salt, HashConfiguration?)
 }
 class HashConfiguration {
 +const int DefaultDegreeOfParallelism
 +const int DefaultNumberOfIterations
 +const int DefaultMemoryToUseInKb
 +int DegreeOfParallelism
 +int NumberOfIterations
 +int MemoryToUseInKb
 }
 }
 Hash ..> HashConfiguration : uses

Usage

Hash a password with a random salt

using ArturRios.Util.Hashing;

// Encode — store both hash and salt
byte[] hash = Hash.EncodeWithRandomSalt("my-secret-password", out byte[] salt);

// Verify later
bool matches = Hash.TextMatches("my-secret-password", hash, salt); // true
bool wrong = Hash.TextMatches("wrong-password", hash, salt); // false

Hash with a known salt

byte[] salt = GetSaltFromStorage();
byte[] hash = Hash.EncodeWithSalt("my-secret-password", salt);

Custom cost parameters

var config = new HashConfiguration
{
 DegreeOfParallelism = 4,
 NumberOfIterations = 3,
 MemoryToUseInKb = 65536
};

byte[] hash = Hash.EncodeWithRandomSalt("my-secret-password", out byte[] salt, config);

Http

Mon, 01 Jan 0001 00:00:00 +0000

Features

HttpGateway: wraps HttpClient with typed async methods for GET, POST, PUT, PATCH, and DELETE. Each takes a CancellationToken, buffers the response body into an HttpOutput<TBody>, and disposes the underlying HttpResponseMessage before returning.
HttpOutput<TBody>: typed HTTP response container carrying the status code, response and content headers, the raw body text, an IsSuccess flag, and the deserialized body. A payload that cannot be bound to TBody — malformed JSON, an array where an object was expected, an HTML error page — leaves Body at its default rather than throwing.
HttpExtensions: generic extension providing ToJsonStringContent() to serialize a payload into a StringContent suitable for request payloads. Serialization uses System.Text.Json; property matching on the way back in is case insensitive.
HttpStatusCodes: static constants for common HTTP status codes (200, 201, 202, 204, 301, 302, 304, 307, 308, 400, 401, 403, 404, 405, 409, 422, 429, 500, 501, 502, 503, 504) plus grouped ImmutableArray<int> collections (Success, Redirection, ClientError, ServerError, All). The groups are singletons, so reading one allocates nothing.

Class Diagram

classDiagram
 namespace Http {
 class HttpGateway {
 +HttpClient Client
 +Task~HttpOutput~TBody~~ GetAsync~TBody~(string route)
 +Task~HttpOutput~TBody~~ PostAsync~TBody~(string route, object? payloadObject)
 +Task~HttpOutput~TBody~~ PutAsync~TBody~(string route, object? payloadObject)
 +Task~HttpOutput~TBody~~ PatchAsync~TBody~(string route, object? payloadObject)
 +Task~HttpOutput~TBody~~ DeleteAsync~TBody~(string route)
 }
 class HttpOutput~TBody~ {
 +HttpStatusCode StatusCode
 +HttpResponseHeaders Headers
 +TBody? Body
 +Task ReadContentAsync(CancellationToken)
 }
 class HttpExtensions {
 <<static>>
 +StringContent ToJsonStringContent(object @object)
 }
 class HttpStatusCodes {
 <<static>>
 +const int Ok
 +const int Created
 +const int Accepted
 +const int NoContent
 +const int MovedPermanently
 +const int Found
 +const int NotModified
 +const int TemporaryRedirect
 +const int PermanentRedirect
 +const int BadRequest
 +const int Unauthorized
 +const int Forbidden
 +const int NotFound
 +const int MethodNotAllowed
 +const int Conflict
 +const int UnprocessableEntity
 +const int TooManyRequests
 +const int InternalServerError
 +const int NotImplemented
 +const int BadGateway
 +const int ServiceUnavailable
 +const int GatewayTimeout
 +int[] Success
 +int[] Redirection
 +int[] ClientError
 +int[] ServerError
 +int[] All
 }
 }
 HttpGateway --> HttpOutput : returns
 HttpGateway ..> HttpExtensions : uses

Usage

Basic GET request

using ArturRios.Util.Http;

var client = new HttpClient { BaseAddress = new Uri("https://api.example.com") };
var gateway = new HttpGateway(client);

var output = await gateway.GetAsync<List<Product>>("/products");

if ((int)output.StatusCode == HttpStatusCodes.Ok)
{
 foreach (var product in output.Body!)
 Console.WriteLine(product.Name);
}

POST with a payload

var newProduct = new { Name = "Widget", Price = 9.99 };

var output = await gateway.PostAsync<Product>("/products", newProduct);

if ((int)output.StatusCode == HttpStatusCodes.Created)
 Console.WriteLine($"Created: {output.Body!.Id}");

PUT and PATCH

var update = new { Name = "Updated Widget" };

await gateway.PutAsync<Product>("/products/42", update);
await gateway.PatchAsync<Product>("/products/42", update);

DELETE

var output = await gateway.DeleteAsync<object>("/products/42");

if ((int)output.StatusCode == HttpStatusCodes.NoContent)
 Console.WriteLine("Deleted.");

Status code groups

int code = (int)output.StatusCode;

if (HttpStatusCodes.Success.Contains(code))
 Console.WriteLine("Request succeeded.");
else if (HttpStatusCodes.ClientError.Contains(code))
 Console.WriteLine("Client error — check your request.");
else if (HttpStatusCodes.ServerError.Contains(code))
 Console.WriteLine("Server error — try again later.");

Serialize a payload manually

var payload = new UpdateRequest { Name = "New Name" };
StringContent content = payload.ToJsonStringContent();
// UTF-8, application/json

IO

Mon, 01 Jan 0001 00:00:00 +0000

Features

FileReader (synchronous): read a file as a string, as an array of lines, as a separator-delimited dictionary, or deserialize its JSON content into a typed object. Deserialization throws JsonException for an empty, malformed or mismatched payload, and returns null only for the JSON literal null.
FileReaderAsync (asynchronous): the same four operations as FileReader, returning Task-wrapped results and accepting a CancellationToken. Behavior is identical to the synchronous reader.
The delimited reader is a plain split on the separator, not an RFC 4180 parser: quoting is not interpreted, so a quoted field containing the separator or a line break is split like any other. It throws InvalidOperationException on a duplicate header name rather than silently dropping the column.

Class Diagram

classDiagram
 namespace IO {
 class FileReader {
 <<static>>
 +string Read(string path)
 +string[] ReadLines(string path)
 +Dictionary~string, string[]~ ReadAsDictionary(string path, char separator)
 +T ReadAndDeserialize~T~(string path)
 }
 class FileReaderAsync {
 <<static>>
 +Task~string~ ReadAsync(string path)
 +Task~string[]~ ReadLinesAsync(string path)
 +Task~Dictionary~string, string[]~~ ReadAsDictionaryAsync(string path, char separator)
 +Task~T~ ReadAndDeserializeAsync~T~(string path, CancellationToken)
 }
 }

Usage

Synchronous

using ArturRios.Util.IO;

// Entire file as a single string
string content = FileReader.Read("/data/notes.txt");

// Array of lines
string[] lines = FileReader.ReadLines("/data/notes.txt");

// Separator-delimited file → dictionary
// Key = first column value, Value = remaining columns as string[]
Dictionary<string, string[]> table = FileReader.ReadAsDictionary("/data/config.csv", ',');

// JSON file → typed object (uses System.Text.Json)
AppConfig config = FileReader.ReadAndDeserialize<AppConfig>("/data/config.json");

Asynchronous

using ArturRios.Util.IO;

string content = await FileReaderAsync.ReadAsync("/data/notes.txt");

string[] lines = await FileReaderAsync.ReadLinesAsync("/data/notes.txt");

Dictionary<string, string[]> table =
 await FileReaderAsync.ReadAsDictionaryAsync("/data/config.csv", ',');

AppConfig config =
 await FileReaderAsync.ReadAndDeserializeAsync<AppConfig>("/data/config.json");

Math

Mon, 01 Jan 0001 00:00:00 +0000

Features

PrimeUtils: static primality tests for all standard integer types (sbyte, byte, short, ushort, int, uint, long, ulong) and BigInteger. Uses trial division for 32-bit values and deterministic Miller-Rabin witnesses up to 2^64, where the answer is exact. Beyond 2^64 a BigInteger is settled by 40 random Miller-Rabin rounds, so a “prime” verdict is probabilistic (error below 4^-40) while a “not prime” verdict is exact. Negative values are never prime. Also exposes BigIntegerSqrt for computing the integer (floor) square root of a BigInteger.
PrimeGenerator<T>: generates an ascending, infinite sequence of prime numbers of the chosen integer type. Thread-safe; each instance maintains its own independent counter. T is constrained to IBinaryInteger<T>, so sbyte, byte, short, ushort, int, uint, long, ulong, nint, nuint, Int128, UInt128 and BigInteger all work, and anything else is a compile error rather than a run-time exception. Running past the largest prime a fixed-width T can hold throws OverflowException.

Class Diagram

classDiagram
 namespace Math {
 class PrimeUtils {
 <<static>>
 +bool IsPrimeNumber(sbyte value)
 +bool IsPrimeNumber(byte value)
 +bool IsPrimeNumber(short value)
 +bool IsPrimeNumber(ushort value)
 +bool IsPrimeNumber(int value)
 +bool IsPrimeNumber(uint value)
 +bool IsPrimeNumber(long value)
 +bool IsPrimeNumber(ulong value)
 +bool IsPrimeNumber(BigInteger value)
 +BigInteger BigIntegerSqrt(BigInteger n)
 }
 class PrimeGenerator~T~ {
 -T _current
 -Lock _lock
 +T Next()
 }
 }
 PrimeGenerator~T~ ..> PrimeUtils : uses

Usage

Primality checks

using ArturRios.Util.Math;

bool a = PrimeUtils.IsPrimeNumber(7919); // true
bool b = PrimeUtils.IsPrimeNumber(7920); // false
bool c = PrimeUtils.IsPrimeNumber(1_000_000_007); // true
bool d = PrimeUtils.IsPrimeNumber(9_223_372_036_854_775_783L); // true (near long.MaxValue)
bool e = PrimeUtils.IsPrimeNumber(new BigInteger(999983));// true

Generating primes in sequence

using ArturRios.Util.Math;

var generator = new PrimeGenerator<int>();

Console.WriteLine(generator.Next()); // 2
Console.WriteLine(generator.Next()); // 3
Console.WriteLine(generator.Next()); // 5
Console.WriteLine(generator.Next()); // 7

Using other integer types

// byte — sequence ends when next prime would exceed 255
var byteGen = new PrimeGenerator<byte>();
byte first = byteGen.Next(); // 2

// BigInteger — unbounded
var bigGen = new PrimeGenerator<BigInteger>();
BigInteger p = bigGen.Next(); // 2

Integer square root

BigInteger root = PrimeUtils.BigIntegerSqrt(new BigInteger(99)); // 9 (floor)
BigInteger exact = PrimeUtils.BigIntegerSqrt(new BigInteger(100)); // 10 (exact)

Thread-safe independent generators

var g1 = new PrimeGenerator<int>();
var g2 = new PrimeGenerator<int>();

g1.Next(); // 2
g1.Next(); // 3

g2.Next(); // 2 ← independent — starts from the beginning
g2.Next(); // 3

Random

Mon, 01 Jan 0001 00:00:00 +0000

Features

CustomRandom: static class for generating random integers via cryptographic RNG or System.Random, and constrained random strings. Both integer helpers treat start and end as inclusive, and both support the full 32-bit range.
RandomStringOptions: configuration for random string generation — controls length and which character sets to include (lowercase letters, uppercase letters, digits, special characters). Every flag defaults to true, so disabling a set means setting it to false explicitly.

CustomRandom.Text draws from RandomNumberGenerator, so its output is suitable for security tokens. It guarantees that:

Regular Expressions

Mon, 01 Jan 0001 00:00:00 +0000

Features

RegexCollection: source-generated compiled regex methods for common patterns — email address, contains a digit, contains a lowercase letter, contains an uppercase letter, contains all three (digit + lowercase + uppercase).
RegexExtensions: Remove extension method on Regex that strips all pattern matches from a string.

Every pattern is ASCII only, anchored with \z where it is anchored at all, and compiled with a MatchTimeoutMilliseconds ceiling so no input can make a match run unbounded. For faster character class checks, results that name which requirement failed, or email normalization, see Text.

Text

Mon, 01 Jan 0001 00:00:00 +0000

Features

CharacterChecks: vectorized SearchValues-backed checks for digits, lowercase, uppercase and special characters over string and ReadOnlySpan<char>, plus Classify and Missing for reporting which character classes a value contains.
CharacterClasses: [Flags] enum naming the ASCII character classes — Digit, Lower, Upper, Special.
EmailAddress: TryNormalize and IsValid, which canonicalize an address (lowercased domain, punycoded internationalized domain) before validating it with RegexCollection.EmailPattern.

These are alternatives to the patterns in Regular Expressions, not replacements: the regexes remain supported and unchanged in behavior.