Class Ranges<T>

Namespace

Utils.Range

Assembly

Utils.dll

Represents a set of intervals (ranges) for an ordered type T. Provides set-like operations (union, intersection, difference, symmetric difference) via operators: | => Union, & => Intersection, ^ => Symmetric Difference,

• => Difference (Except).

There is deliberately no complement operation: T is only constrained by IComparable<T>, and IRange<T> carries no notion of a domain, a minimum/maximum value, or infinite bounds, so a complement relative to "the entire domain" cannot be computed in general (an empty Ranges<T> would not even have a domain to recover it from). Types that explicitly model their complete domain, such as IntRange<T>, can define their own well-defined complement instead.

The intervals are stored internally as disjoint, sorted Range<T> objects.

public class Ranges<T> : IFormattable, IEquatable<Ranges<T>>, ISubtractionOperators<Ranges<T>, Ranges<T>, Ranges<T>>, IEqualityOperators<Ranges<T>, Ranges<T>, bool> where T : IComparable<T>

Type Parameters

T

A comparable type that supports ordering.

Inheritance

object

Ranges<T>

Implements

IFormattable

IEquatable<Ranges<T>>

ISubtractionOperators<Ranges<T>, Ranges<T>, Ranges<T>>

IEqualityOperators<Ranges<T>, Ranges<T>, bool>

Derived

DateTimeRanges

DoubleRanges

SingleRanges

Inherited Members

object.Equals(object, object)

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Extension Methods

DataUtils.ToDbValue(object?)

MathEx.Clamp<T>(T, T, T, IComparer<T>)

FluentExtensions.Failure<T>(T)

FluentExtensions.IsEqualTo<T, CT>(T, CT)

FluentExtensions.IsGreaterOrEqualsThan<T, CT>(T, CT)

FluentExtensions.IsGreaterThan<T, CT>(T, CT)

FluentExtensions.IsIn<T>(T, params T[])

FluentExtensions.IsLowerOrEqualsThan<T, CT>(T, CT)

FluentExtensions.IsLowerThan<T, CT>(T, CT)

FluentExtensions.IsNotIn<T>(T, params T[])

FluentExtensions.IsNotNull<T>(T)

FluentExtensions.IsNull<T>(T)

FluentExtensions.Success<T>(T)

FluentExtensions.Test<T>(T, Func<T, bool>)

ObjectUtils.Between<T>(T, IComparer<T>, T, T)

ObjectUtils.Between<T>(T, IComparer<T>, T, T, bool, bool)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Task<Result>>, Func<Task<Result>>)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Task<Result>>, Result)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Result>, Func<Result>)

ObjectUtils.DoAsync<T, Result>(T, Func<T, Result>, Result)

ObjectUtils.Do<T, Result>(T, Func<T, Result>, Func<Result>)

ObjectUtils.Do<T, Result>(T, Func<T, Result>, Result)

ObjectUtils.In<T>(T, params T[])

ObjectUtils.NotIn<T>(T, params T[])

Validations.ArgMustBe<T>(T, Func<T, bool>, string, string)

Validations.ArgMustNotBe<T>(T, Func<T, bool>, string, string)

Validations.Arg<T>(T, string)

Validations.ValueMustNotBeNull<T>(T, string)

Validations.Variable<T>(T, string)

Constructors

Ranges()

Creates an empty set of intervals.

public Ranges()

Ranges(IEnumerable<IRange<T>>)

Creates a set of intervals from the provided collection of Range<T>. Overlapping intervals are merged into disjoint intervals.

public Ranges(IEnumerable<IRange<T>> intervals)

Parameters

intervals IEnumerable<IRange<T>>

Ranges(IEnumerable<Range<T>>)

Creates a set of intervals from the provided collection of Range<T>. Overlapping intervals are merged into disjoint intervals.

public Ranges(IEnumerable<Range<T>> intervals)

Parameters

intervals IEnumerable<Range<T>>

Ranges(params IRange<T>[])

Creates a set of intervals from one or more Range<T>. Overlapping intervals are merged into disjoint intervals.

public Ranges(params IRange<T>[] intervals)

Parameters

intervals IRange<T>[]

Ranges(Ranges<T>)

Creates a new set of intervals by copying all intervals from other.

public Ranges(Ranges<T> other)

Parameters

other Ranges<T>

Ranges(params Range<T>[])

Creates a set of intervals from one or more Range<T>. Overlapping intervals are merged into disjoint intervals.

public Ranges(params Range<T>[] intervals)

Parameters

intervals Range<T>[]

Properties

Count

Returns the total count of disjoint intervals stored.

public int Count { get; }

Property Value

int

Intervals

Returns a read-only snapshot of the underlying intervals (disjoint, sorted).

public IReadOnlyList<IRange<T>> Intervals { get; }

Property Value

IReadOnlyList<IRange<T>>

Methods

Add(IRange<T>)

Adds a single interval, merging with existing intervals if they overlap or touch.

public void Add(IRange<T> interval)

Parameters

interval IRange<T>

Add(T)

Adds a single interval, merging with existing intervals if they overlap or touch.

public void Add(T singleValue)

Parameters

singleValue T

Add(T, T, bool, bool)

Adds a single interval, merging with existing intervals if they overlap or touch.

public void Add(T start, T end, bool includeStart = true, bool includeEnd = true)

Parameters

start T

end T

includeStart bool

includeEnd bool

AddAll(IEnumerable<IRange<T>>)

Adds multiple intervals, merging overlaps.

public void AddAll(IEnumerable<IRange<T>> intervals)

Parameters

intervals IEnumerable<IRange<T>>

Clear()

Removes all intervals, resulting in an empty set.

public void Clear()

Contains(IRange<T>)

Checks if the entire range is contained in this set.

public bool Contains(IRange<T> range)

Parameters

range IRange<T>

Returns

bool

Contains(T)

Checks if the specified value value is contained in any of the intervals of this set.

public bool Contains(T value)

Parameters

value T

Returns

bool

Equals(object?)

Determines whether the specified object is equal to the current object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

Equals(Ranges<T>?)

Determines whether the specified Ranges<T> represents the same set of intervals.

public bool Equals(Ranges<T>? other)

Parameters

other Ranges<T>

The other range collection to compare with.

Returns

bool

true when both collections contain the same ranges; otherwise, false.

Except(Ranges<T>, Ranges<T>)

Returns a new set representing all intervals in left that are not in right. (Set difference).

public static Ranges<T> Except(Ranges<T> left, Ranges<T> right)

Parameters

left Ranges<T>

right Ranges<T>

Returns

Ranges<T>

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

InnerParse<T1>(string, string, IEnumerable<string>, Func<string, T1>)

protected static IEnumerable<IRange<T1>> InnerParse<T1>(string range, string itemSearchPattern, IEnumerable<string> separators, Func<string, T1> valueParser) where T1 : IComparable<T1>

Parameters

range string

The string containing the ranges.

itemSearchPattern string

The regex pattern to match the elements in the range.

separators IEnumerable<string>

The separator strings used to delimit the start and end values.

valueParser Func<string, T1>

A function to parse the string into type T1.

Returns

IEnumerable<IRange<T1>>

An enumerable collection of parsed Range objects. An empty or whitespace-only range is a legitimate representation of an empty set and yields no ranges without throwing.

Type Parameters

T1

The type of the elements in the range.

Exceptions

FormatException

Thrown when range contains non-whitespace content that is not part of a recognized range expression (only whitespace is allowed between, before, or after matched ranges). This is a strict parser: it requires the entire input to be consumed, unlike an extraction API that would intentionally skip over surrounding text.

Intersect(Ranges<T>, Ranges<T>)

Returns a new set representing the intersection of left and right.

public static Ranges<T> Intersect(Ranges<T> left, Ranges<T> right)

Parameters

left Ranges<T>

right Ranges<T>

Returns

Ranges<T>

Remove(IRange<T>)

Removes a single interval from this set, splitting or trimming intervals.

public void Remove(IRange<T> toRemove)

Parameters

toRemove IRange<T>

Remove(T)

Removes a single interval from this set, splitting or trimming intervals.

public void Remove(T singleValue)

Parameters

singleValue T

Remove(T, T, bool, bool)

Removes a single interval from this set, splitting or trimming intervals.

public void Remove(T start, T end, bool includeStart = true, bool includeEnd = true)

Parameters

start T

end T

includeStart bool

includeEnd bool

RemoveAll(IEnumerable<IRange<T>>)

Removes multiple intervals from this set.

public void RemoveAll(IEnumerable<IRange<T>> intervals)

Parameters

intervals IEnumerable<IRange<T>>

SymmetricDifference(Ranges<T>, Ranges<T>)

Returns a new set representing the symmetric difference of left and right. (Elements in left or right, but not both).

public static Ranges<T> SymmetricDifference(Ranges<T> left, Ranges<T> right)

Parameters

left Ranges<T>

right Ranges<T>

Returns

Ranges<T>

ToString()

Converts the current Ranges<T> to its string representation using default formatting.

public override string ToString()

Returns

string

A string representation of the stored ranges.

ToString(IFormatProvider?)

Converts the current Ranges<T> to its string representation using the provided format provider.

public string ToString(IFormatProvider? formatProvider)

Parameters

formatProvider IFormatProvider

Culture used when formatting the numeric boundaries.

Returns

string

A string representation of the stored ranges.

ToString(string?)

Converts the current Ranges<T> to its string representation using the provided format string.

public string ToString(string? format)

Parameters

format string

Custom format applied to each interval boundary.

Returns

string

A string representation of the stored ranges.

ToString(string?, IFormatProvider?)

Converts all stored intervals to string, joined by a union symbol " ∪ ". E.g. "[1..2] ∪ (3..5)"

public string ToString(string? format, IFormatProvider? formatProvider)

Parameters

format string

formatProvider IFormatProvider

Returns

string

Union(Ranges<T>, Ranges<T>)

Returns a new set representing the union of left and right.

public static Ranges<T> Union(Ranges<T> left, Ranges<T> right)

Parameters

left Ranges<T>

right Ranges<T>

Returns

Ranges<T>

Operators

operator &(Ranges<T>, Ranges<T>)

Intersection => bitwise AND operator.

public static Ranges<T> operator &(Ranges<T> left, Ranges<T> right)

Parameters

left Ranges<T>

right Ranges<T>

Returns

Ranges<T>

operator |(Ranges<T>, Ranges<T>)

Union => bitwise OR operator.

public static Ranges<T> operator |(Ranges<T> left, Ranges<T> right)

Parameters

left Ranges<T>

right Ranges<T>

Returns

Ranges<T>

operator ==(Ranges<T>?, Ranges<T>?)

Determines whether two Ranges<T> instances are equal.

public static bool operator ==(Ranges<T>? left, Ranges<T>? right)

Parameters

left Ranges<T>

The first Ranges<T> instance to compare, or null.

right Ranges<T>

The second Ranges<T> instance to compare, or null.

Returns

bool

true if the two Ranges<T> instances are equal; otherwise, false.

operator ^(Ranges<T>, Ranges<T>)

Symmetric Difference => bitwise XOR operator.

public static Ranges<T> operator ^(Ranges<T> left, Ranges<T> right)

Parameters

left Ranges<T>

right Ranges<T>

Returns

Ranges<T>

operator !=(Ranges<T>?, Ranges<T>?)

Determines whether two Ranges<T> instances are not equal.

public static bool operator !=(Ranges<T>? left, Ranges<T>? right)

Parameters

left Ranges<T>

The first Ranges<T> instance to compare, or null.

right Ranges<T>

The second Ranges<T> instance to compare, or null.

Returns

bool

true if the two instances are not equal; otherwise, false.

operator -(Ranges<T>, Ranges<T>)

Difference => set except operator.

public static Ranges<T> operator -(Ranges<T> left, Ranges<T> right)

Parameters

left Ranges<T>

right Ranges<T>

Returns

Ranges<T>