AwadyLab.MoreExtensions 1.5.0

AwadyLab.MoreExtensions

Extension methods for .NET that the BCL doesn't ship: allocation-free span-based string slicing, lazy LINQ operators, calendar and workday helpers, a first-class DateTimeRange value type, generic-math numerics, fast type conversions, and utilities for enums, reflection, Guid, tasks and certificates.

Built on C# 14 extension members, so most of these appear as ordinary instance members on the type they extend.

dotnet add package AwadyLab.MoreExtensions

Target framework: net10.0

Contents

Strings

The slicing members are declared on ReadOnlySpan<char> and return spans, so none of them allocate. Thanks to first-class span conversions you can call them directly on a string.

using AwadyLab.MoreExtensions;

const string cs = "Server=db.example.com;Database=Orders;Encrypt=True";

cs.LeftOf(";")           // "Server=db.example.com"      (ReadOnlySpan<char>, 0 allocations)
cs.RightOfLast("=")      // "True"
cs.Between("Database=", ";")  // "Orders"
cs.Left(6)               // "Server"
cs.Right(4)              // "True"

IsLike runs in O(n·m) worst case with O(1) memory and no recursion, so patterns like "*a*a*a*b" cannot cause catastrophic backtracking.

"order-2024-01-02.json".IsLike("order-*.json");   // true
"Report.PDF".IsLike("*.pdf", ignoreCase: true);   // true

String members

CollapseWhitespace returns the original instance when nothing needs changing, and otherwise builds the result in a single allocation using a stack or pooled buffer.

string? name = GetName();
if (!name.IsNullOrWhiteSpace())
    Console.WriteLine(name.Length);  // no null-forgiving operator needed

"  a\t\tb \n c  ".CollapseWhitespace();          // "a b c"
using var sha = SHA256.Create();
"payload".Hash(sha);                              // "5B3C..." hex

Enumerable

Every operator validates its arguments eagerly — an ArgumentNullException is thrown at the call site, not deferred to the first MoveNext() — and then streams lazily.

int[] readings = [3, 5, 4, 8, 6];

readings.Window(3);                            // [3,5,4], [5,4,8], [4,8,6]
readings.Lag(1, (now, prev) => now - prev);    // 3, 2, -1, 4, -2
readings.TakeUntil(x => x > 5);                // 3, 5, 4, 8   (inclusive)
readings.IsSorted();                           // false

Duplicate keys are resolved by DuplicateKeyBehavior.KeepFirst (the default) or KeepLast:

var byId = orders.ToDictionarySafe(o => o.Id, o => o, DuplicateKeyBehavior.KeepLast);

Window allocates one array per window, so each element is copied size times. That is what makes every yielded window independently safe to keep. For a hot loop over a large sequence, prefer Lag/Lead or index into an array directly.

Collections

AddRange dispatches to List<T>.AddRange or ISet<T>.UnionWith where available, pre-sizing when the source count is known, and falls back to a per-item loop otherwise.

WithRange is a non-mutating companion that allocates an exactly-sized array (using ICollection<T>.CopyTo when counts are known) and works for arrays or read-only sequences without modifying the receiver.

IEnumerable<int>? maybe = GetItems();
if (!maybe.IsNullOrEmpty())
    Process(maybe);              // narrowed to non-null

ICollection<string> target = new HashSet<string>();
target.AddRange(["a", "b", "c"]);

int[] baseItems = [1, 2, 3];
int[] combined = baseItems.WithRange([4, 5, 6]);   // [1, 2, 3, 4, 5, 6]

IsNullOrEmpty on a sequence whose count isn't known advances the enumerator by one element to answer. Don't call it on a single-use iterator you intend to enumerate afterwards.

Dictionaries

var cache = new Dictionary<string, Config>();
var config = cache.GetOrAdd("orders", LoadConfig);

var removed = cache.RemoveWhere(e => e.Value.IsExpired);

GetOrAdd's factory must not mutate the dictionary — only the requested key is ever written, and only by GetOrAdd itself once the factory returns.

These are not thread-safe. For concurrent access use ConcurrentDictionary<TKey, TValue>, which has its own GetOrAdd.

Date and time

Every member below exists for DateTime, DateTimeOffset and DateOnly where it makes sense. DateTime overloads preserve Kind; DateTimeOffset overloads preserve Offset.

var t = new DateTime(2024, 6, 12, 14, 32, 17);

t.StartOfMonth();                     // 2024-06-01 00:00:00
t.Floor(TimeSpan.FromMinutes(15));    // 2024-06-12 14:30:00
t.AddWorkdays(10);                    // skips weekends

AddWorkdays is O(1) for the whole-week portion rather than walking day by day, and handles negative values (-1 moves to the previous working day).

Weekend configuration

Weekends default to Saturday/Sunday, or Friday/Saturday for Arabic, Hebrew, Persian and Bangladeshi cultures. Override per culture:

CultureInfo.CurrentCulture.SetWeekendDays(DayOfWeek.Friday, DayOfWeek.Saturday);
// or
culture.WeekendDays = new HashSet<DayOfWeek> { DayOfWeek.Friday };

Configuration is stored per culture name and shared process-wide, so it applies to every CultureInfo with that name — including the fresh instances ASP.NET Core request localization creates per request. Set it once during start-up. An empty set, or one containing all seven days, is rejected.

DateTimeRange

An immutable interval over DateTimeOffset, implementing IEquatable, IComparable, IFormattable, ISpanFormattable, IParsable and ISpanParsable. Overlaps and Intersect use half-open [Start, End) semantics, while Contains and IsIn default to the inclusive-end [Start, End] reading unless inclusiveEnd: false is passed.

var window = new DateTimeRange(start, end);
var hour   = DateTimeRange.FromDuration(start, TimeSpan.FromHours(1));
var bounds = DateTimeRange.FromCollection(timestamps);

window.Duration;                              // TimeSpan
window.IsEmpty;                               // bool (Start == End)
window.Contains(instant);                     // end-inclusive by default: [Start, End]
window.Contains(instant, inclusiveEnd: false);// end-exclusive: [Start, End)
window.Contains(otherRange);                  // range containment (both bounds within window)
window.Overlaps(other);                       // touching ranges do NOT overlap ([Start, End) semantics)
window.GetOverlapType(other);                 // RangeOverlapType (Before, After, Overlapping, Contains, ContainedBy, Equal)
window.Intersect(other);                      // DateTimeRange? — null when they share no instant
window.Union(other);                          // smallest range covering both
window.Enumerate(TimeSpan.FromDays(1));       // every step while still before End
var (from, to) = window;                      // deconstruction

window.ToString();                            // ISO 8601 interval: "start/end"
DateTimeRange.Parse("2024-01-01T00:00:00Z/2024-02-01T00:00:00Z");

instant.IsIn(window);                         // extension on DateTimeOffset and DateTime

Overlaps and Intersect agree: ranges that merely touch share no instant under half-open semantics, so Overlaps is false and Intersect returns null. In contrast, Contains(instant) and instant.IsIn(range) default to inclusiveEnd: true ([Start, End]). Ranges sort by Start, then End. ToString(format, provider) formats both bounds with the given format (default "O"); only the default round-trips through Parse. The delimiter can be configured process-wide via DateTimeRange.Separator (defaults to '/'). It can only be set once per process — set it during start-up, before any formatting or parsing happens; a second assignment throws InvalidOperationException.

Numerics

Generic-math based, so these work for every numeric type.

5.IsBetween(1, 10);              // true  (inclusive by default)
5.IsBetween(5, 10, inclusive: false);   // false
25.PercentOf(200);               // 12.5
(0.1 + 0.2).ApproximatelyEquals(0.3, 1e-9);  // true

Conversions

General extension methods for converting and parsing loosely-typed values or strings to a target type without allocating exceptions on failure.

Target types can be supplied explicitly (e.g. value.ConvertTo<int>()). Target Nullable<T> types are automatically unwrapped (null maps to null for reference and nullable types, and throws for non-nullable value types).

Supported conversions include:

• All numeric and Boolean primitives (via fast non-throwing TryParse paths that eliminate exception overhead)
• Enums by member name (case-insensitive) or underlying integer value
• Guid, DateOnly, TimeOnly, DateTimeOffset, TimeSpan, Uri, and Version
• General types via Convert.ChangeType with invariant culture

"123".ConvertTo<int>();                          // 123
"true".ConvertTo<bool>();                        // true
"Active".ConvertTo<Status>();                    // Status.Active
"2024-01-15".ConvertTo<DateOnly>();              // DateOnly(2024, 1, 15)

"invalid".ConvertToOrDefault(fallback: -1);      // -1
null.ConvertToOrDefault<int?>();                 // null

if (input.TryConvertTo<Guid>(out var id))
{
    // Fast path: no FormatException allocated if input is not a Guid
}

Guid

Encodes the raw 16 bytes as unpadded base64url — 22 characters instead of the 32 of ToString("N"), and safe in URLs and file names.

var id = Guid.NewGuid();

id.ToBase64UrlString();                        // "3Zf0xQ7rTEGm1gWq9kPzXA"
Guid.FromBase64UrlString(text);                // throws FormatException when invalid
Guid.TryParseBase64Url(text, out var parsed);  // non-throwing

Span<char> buffer = stackalloc char[22];
id.TryFormatBase64Url(buffer, out var written);  // no allocation

Enums

enum Status { [Description("In progress")] Active, Done }

Status.Active.GetDescription();                       // "In progress"
Status.Active.GetAttribute<DescriptionAttribute>();   // the attribute, or null
Status.Active.IsDefined();                            // true
Status.GetEnumNameFromDescription("In progress");     // Status.Active, or null

(FileAccess.Read | FileAccess.Write).GetFlags();      // Read, Write

Attribute and description lookups are cached per enum type, so only the first call pays for reflection.

Tasks

Task<int> count = GetCountAsync();

count.Then(n => n * 2);                    // Task<int>
count.Then(n => LoadAsync(n));             // Task<T>, flattened

BackgroundWork().FireAndForget(ex => logger.LogError(ex, "background work failed"));

Then completes synchronously when the source task already has, without allocating a state machine. FireAndForget always observes the fault — with or without a handler — so it can never surface as an unobserved-task exception. Cancellation is swallowed. Available on Task, Task<T>, ValueTask and ValueTask<T>.

Expressions

Composes predicate expression trees, so the result is still translatable by EF Core and other providers.

Expression<Func<Order, bool>> isOpen = o => o.Status == Status.Open;
Expression<Func<Order, bool>> isLarge = o => o.Total > 1000;

var query = db.Orders.Where(isOpen.AndAlso(isLarge));

// Or fold a whole collection:
var combined = filters.CombineAndAlso();   // empty => always true
var anyOf    = filters.CombineOrElse();    // empty => always false

For the untyped overloads, targetType must be the expression's own parameter type or derive from it — a Expression<Func<Base, bool>> can be retargeted to Derived, not the other way round.

Reflection

var handlers = assembly.GetClassesImplementing<IHandler>();
var generic  = assembly.GetClassesImplementsGenericInterface(typeof(IHandler<>));
var derived  = assembly.GetClassesImplementGenericBaseClass(typeof(EntityBase<>));

typeof(int?).IsNullable();              // true
typeof(int?).GetUnderlyingTypeOrSelf(); // typeof(int)
propertyInfo.IsNullable();

Types that fail to load are skipped by default, so scanning an assembly with missing optional dependencies returns what it could resolve. Pass throwOnLoadError: true to get the ReflectionTypeLoadException instead.

Random

Random.Shared.GenerateNumericString(6);        // "480913"
Random.Shared.GenerateAlphaNumericString(12);  // "a7Kp2Qm9Xz1B"

⚠️ Random is not cryptographically secure and its output is predictable from observed values. Never use these for one-time passwords, password-reset codes, session tokens, or anything else security-sensitive — use the secure counterparts in Security instead.

Security

using var cert = StoreLocation.CurrentUser.Find(
    StoreName.My, X509FindType.FindBySubjectName, "api.example.com");

foreach (var uri in cert.Extensions
             .OfType<X509SubjectAlternativeNameExtension>()
             .SelectMany(e => e.EnumerateUriSans()))
    Console.WriteLine(uri);

Secure random strings

The counterparts of the Random generators, backed by RandomNumberGenerator and free of modulo bias. These are the ones to reach for whenever an attacker must not be able to predict the value.

SecurityExtensions.GenerateSecureNumericString(6);         // one-time password
SecurityExtensions.GenerateSecureAlphaNumericString(32);   // session token / API key

Find returns a non-null certificate that the caller owns and must dispose; certificates it examined but did not select are disposed for you. It throws InvalidOperationException when nothing matched or the match has no private key, and CryptographicException when the private key exists but cannot be opened.

TryFind only swallows those two expected "no usable match" outcomes; a genuine infrastructure failure (e.g. the store itself cannot be opened) still propagates instead of being reported as "not found".

Benchmarks

(BenchmarkDotNet) compares each extension against the straightforward code a caller would otherwise write. Run it yourself with:

All results below are .NET 10.0.12, X64 RyuJIT, ShortRun job (3 iterations); treat the absolute numbers as indicative, not lab-grade — re-run on your own hardware for anything you're optimizing against.

Strings (StringSlicingBenchmarks)

Takeaway: the span-returning members are consistently 2–7× faster and allocation-free versus the string equivalent, exactly the point of slicing without copying. CollapseWhitespace beats Regex.Replace by ~9× using a stack/pooled buffer instead of regex overhead.

Enumerable (EnumerableBenchmarks)

Takeaway: IsSorted's single-pass comparison is ~6× faster than Zip+Any (which allocates an enumerator pair per element). RandomSubset's reservoir sampling trades raw speed for O(count) memory — the naive shuffle-then-take is faster only because it materializes the whole 100k-element source, which the reservoir approach is specifically built to avoid for sources too large to buffer. Lag's delegate-based API costs ~10× over a hand-written indexed loop — expected LINQ-style overhead for the flexibility.

Conversions (ConversionBenchmarks)

Takeaway: the failure path — the one that mattered for the 2.0.0 fix — stays within ~2× of the raw native TryParse, confirming the primitive fast path avoids the old throw/catch-FormatException cost inside Convert.ChangeType.

Guid and DateTime (GuidAndDateBenchmarks)

Takeaway: TryFormatBase64Url is the one to reach for in a hot path — it matches ToString("N")'s speed with zero allocation, versus ToBase64UrlString()'s extra string allocation. AddWorkdays's closed-form calculation is ~5× faster than looping a day at a time to skip weekends.

DictionaryExtensions, CollectionExtensions, DateTimeRange (DictionaryCollectionRangeBenchmarks)

Takeaways: GetOrAdd's single-lookup fast path (CollectionsMarshal.GetValueRefOrAddDefault) matches the naive two-step version on time while keeping the same allocation profile — the win is behavioural (one dictionary operation, not the API shape). RemoveWhere's pooled buffer meaningfully beats a List<T> buffer on both time and allocations, since it never grows/reallocates. WithRange's exact-size allocation performs the same as Concat+spread — BCL's ToArray on Concat is already well-optimized, so the manual version buys correctness/clarity (array-specific overloads, no IEnumerable boxing) rather than raw speed here. DateTimeRange's comparison-based members carry no measurable overhead.