Diamond.Utility 2026.0.0

Diamond.Utility Package

Diamond.Utility is a comprehensive, lightweight library of utilities, helper classes, and extended functionalities for the .NET ecosystem. It is designed for use in Web, WPF, Windows Services, Console and any other .NET application type.

• Key Features

• Framework-independent (compatible with .NET Standard 2.0+)

• Zero third-party dependencies

• Memory-efficient and performance-optimized

• Suitable for multi-layered and modern architectures

Some Components

1. WeakReference Collections

These collections use WeakReference to store object references, preventing memory leaks and allowing proper garbage collection. Ideal for caching, event handling, and memory-sensitive scenarios.

WeakReferenceDictionary<TKey, TValue>

A dictionary that stores values as weak references.

var cache = new WeakReferenceDictionary<string, MyClass>();
cache["key"] = new MyClass();
var value = cache["key"]; // May return null if GC has collected it

WeakReferenceCollection<T>

A collection of objects with weak references.

var list = new WeakReferenceCollection<MyClass>();
list.Add(new MyClass());
foreach (var item in list)
{
    // item may be null if garbage collected
}

2. Dynamic Values with HotValue

HotValue is an intelligent data type that stores a Func<T> instead of the actual value. This ensures your values are always up-to-date and reflect changes from the source immediately.

Basic Example:

var hotNow = new Func<DateTime>(() => DateTime.Now);
var hotNow2000 = HotValue.Min(hotNow, HotValue.Const(new DateTime(2000, 1, 1)));
var hotNowCache = HotValue.Cache(hotNow2000, TimeSpan.FromSeconds(30));

Console.WriteLine(hotNow()); // Current time
Console.WriteLine(hotNowCache()); // Current time
Thread.Sleep(5000);
Console.WriteLine(hotNow()); // Updated time
Console.WriteLine(hotNowCache()); // Cached time

var c = new CacheSingleTime<string, string>();
string? v1 = c["key"]; //null
Func<string?> alwaysUpdateValue = c.GetHotValue("key");

3. Lazy Caching - Diamond.LazyCache

Combines Lazy Loading and Caching concepts, allowing you to cache data and easily mark it as Dirty to regenerate on next access.

var cache = LazyCache.Create(() => DateTime.Now, TimeSpan.FromSeconds(30));

Thread.Sleep(5000);

// First access: LoadExpensiveDataFromDatabase executes
Console.WriteLine(cache.Value); // Current time

Thread.Sleep(5000);
// Second access: Returns cached value (no function execution)
Console.WriteLine(cache.Value); // Cached time

// Mark cache as dirty
cache.SetDirty();

Thread.Sleep(5000);

// Next access: Function executes again
Console.WriteLine(cache.Value); // Current time

4. Stream Utilities

StreamDecorator

A base class for implementing the Decorator Pattern with streams, providing easy inheritance and stream decoration.

UnionStream

Concatenates multiple streams into a single ReadOnly stream. Perfect when reading from multiple data sources sequentially.

var stream1 = File.OpenRead("file1.bin");
var stream2 = File.OpenRead("file2.bin");
var stream3 = new MemoryStream(data);

using var union = new UnionStream(stream1, stream2, stream3);
// All three streams are read sequentially

Stream mainForwardStream = ...
var buffer = new byte[1024];
mainForwardStream.Read(buffer);

// any proccess

var header = new MemoryStream(buffer);

using var union = new UnionStream(header, mainForwardStream);
// All two streams are read sequentially

MultiProcessWriterStream

Enables multiple independent processes to write to the same file. Ideal for inter-process logging scenarios.

using var writer = MultiProcessWriterStream.Create("log.txt");
using var sw = new StreamWriter(writer);
sw.WriteLine($"[{DateTime.Now}] Process {Process.GetCurrentProcess().Id} wrote this");

5. LINQ Extensions

Powerful extension methods for IQueryable and IEnumerable:

HasOverlap

Check if two range overlap:

DateTime? dt1 = new DateTime(2020, 1, 1);
DateTime? dt2 = new DateTime(2020, 5, 1);
var query = dbContext.Rules.HasOverlap(r => r.BeginDate, r => r.EndDate, dt1, dt2);
var list = query.ToList();

SelectPage

Easy pagination with comprehensive result:

var paging = dbContext.Products.Where(r => r.Price > 1000).SelectPage();
paging.PageSize = 40;
paging.ExpectedPageIndex = 1;
paging.OrderKey(r => r.Price);

// Returns: DataSource, AllCount, PageCount, ActualPageIndex, ...

6. Observer Pattern Implementation - ConcurrentObservable<T>

A thread-safe implementation of IObserver and IObservable interfaces:

var bus = new ConcurrentObservable<int>();

// Subscribe
var subscription = bus.Observable.Subscribe(value => 
{
    Console.WriteLine($"Received: {value}");
});

// Publish data
bus.Observers.OnNext(42);

// Unsubscribe
subscription.Dispose();

7. Text Normalization - Normalizer

A fast and comprehensive class for text cleaning and normalization with:

• Persian/Arabic character unification (normalizing ی, ک, ة, etc.)
• Number normalization (converting Arabic/Persian digits to English or vice versa)
• Whitespace normalization (removing extra spaces, unifying whitespace types)
• Control character removal

var n = new Normalizer();
n.LineOption = Normalizer.LineOptions.MultiLine_CRLF_Windows;
n.TrimOption = Normalizer.TrimOptions.AnyLine;
n.Add(Normalizer.Persian());
n.Add(Normalizer.ReplaceDigits(Normalizer.DigitCulture.Ascii));
n.Add(Normalizer.ReplaceWhiteSpace(true, ' ', true));
n.Add(Normalizer.RemoveDuplicate(" "));
n.Add(Normalizer.ToLower());
n.Add(Normalizer.RemoveCategory(System.Globalization.UnicodeCategory.Control));

var corrector = n.CreateTextCorrector();

string text = "Abc\t\t 1௨൩٤۵ ﻙﻱ";
string normalized = corrector.Correct(text, 0, int.MaxValue);
// Output: "abc 12345 کی"

8. Dynamic Text Search - Text.Search

Static class for tokenizing search phrases and converting them to Expression<Func<T, bool>> for use with IQueryable:

var searchTerm = "book +c# -'java script'";
var tokens = Search.GetParts(searchTerm);

// Build filter for multiple fields
Expression<Func<Product, bool>>? filter = Search.GetExpression<Product>(
    tokens,
    p => p.Name,
    p => p.Description,
    p => p.Brand
);

var results = dbContext.Products.Where(filter).ToList();

9. Persian Date Parsing - PersianDateParse

Static function for parsing Persian (Shamsi/Hijri) dates in various text and numeric formats:

// Supports multiple input formats
DateTime? date1 = DateParser.PersianDateParse("1403 /04/15");
DateTime? date2 = DateParser.PersianDateParse("1403-04- 15");
DateTime? date3 = DateParser.PersianDateParse("14030415");
DateTime? date4 = DateParser.PersianDateParse("15. 04-1403");
DateTime? date5 = DateParser.PersianDateParse("۱۵ تیر ۱۴۰۳");
DateTime? date6 = DateParser.PersianDateParse("1403/4/15 14:30:00");

10. Additional Utilities

Diamond.Text.StringParse.TryParse Diamond.Text.StringParse.ToHex Diamond.Text.StringParse.FromHex Diamond.Text.LikeOperator.Like Diamond.Collections.Generic.Functions.GetNameValue Diamond.Collections.Generic.IFeatureSet Diamond.Net.Functions.GetIPScope Diamond.IReferenceTracker Diamond.PlatformRuntimeEnvironment etc...

License

Apache-2.0 license