Class IpRangeOrderedList

Namespace

VpnHood.Net.Toolkit.Net

Assembly

VpnHood.Net.Toolkit.dll

Represents a sorted set of IP ranges of both families, in which the ranges of a family that overlap or touch are merged into one.

public class IpRangeOrderedList : IOrderedEnumerable<IpRange>, IReadOnlyList<IpRange>, IReadOnlyCollection<IpRange>, IEnumerable<IpRange>, IEnumerable

Inheritance

object

IpRangeOrderedList

Implements

IOrderedEnumerable<IpRange>

IReadOnlyList<IpRange>

IReadOnlyCollection<IpRange>

IEnumerable<IpRange>

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The list cannot be changed: Union(IEnumerable<IpRange>), Exclude(IpRangeOrderedList), Intersect(IpRangeOrderedList) and Invert(bool, bool) return another list, or this one where nothing changes. The ranges are in the order of their first addresses, the IPv4 ranges before the IPv6 ones, and Contains(IpAddressValue) finds an address by binary search.

An IPv4-mapped IPv6 address is an IPv4 address in IPv6's form: IpRange makes a range of such addresses the range of their IPv4 addresses, and Contains(IpAddressValue) asks about one as its IPv4 address. A range that only reaches into the mapped addresses, as that of ::/80 does, is a range of IPv6 addresses like any other, which holds none of them for a lookup. So two IPv6 ranges with nothing between them but mapped addresses are one range, and what an intersection would leave wholly among them is left out.

Constructors

IpRangeOrderedList()

Initializes a new instance of the IpRangeOrderedList class that holds no range.

public IpRangeOrderedList()

IpRangeOrderedList(IEnumerable<IpRange>)

Initializes a new instance of the IpRangeOrderedList class that holds the given ranges, sorted, with those of a family that overlap or touch merged.

public IpRangeOrderedList(IEnumerable<IpRange> ipRanges)

Parameters

ipRanges IEnumerable<IpRange>

The ranges, in any order.

Exceptions

ArgumentNullException

ipRanges is null.

Properties

Count

Gets the number of ranges, after merging.

public int Count { get; }

Property Value

int

Empty

Gets an empty list.

public static IpRangeOrderedList Empty { get; }

Property Value

IpRangeOrderedList

this[int]

Gets the range at an index.

public IpRange this[int index] { get; }

Parameters

index int

The index, from 0 to Count - 1.

Property Value

IpRange

Exceptions

ArgumentOutOfRangeException

index is negative, or not below Count.

Methods

Contains(IPAddress)

Determines whether an address is in one of the ranges.

public bool Contains(IPAddress ipAddress)

Parameters

ipAddress IPAddress

The address. An IPv4-mapped IPv6 address is looked up as its IPv4 address, and a scope id is ignored.

Returns

bool

true if a range holds the address; otherwise, false.

Exceptions

ArgumentNullException

ipAddress is null.

Contains(IpAddressValue)

Determines whether an address is in one of the ranges, with no object made.

public bool Contains(IpAddressValue ipAddress)

Parameters

ipAddress IpAddressValue

The address. An IPv4-mapped IPv6 address is looked up as its IPv4 address, and a scope id is ignored; the default value is in no range.

Returns

bool

true if a range holds the address; otherwise, false.

CreateOrderedEnumerable<TKey>(Func<IpRange, TKey>, IComparer<TKey>?, bool)

Adds a key to the list's order, for ThenBy and ThenByDescending.

public IOrderedEnumerable<IpRange> CreateOrderedEnumerable<TKey>(Func<IpRange, TKey> keySelector, IComparer<TKey>? comparer, bool descending)

Parameters

keySelector Func<IpRange, TKey>

The function that gets a range's key.

comparer IComparer<TKey>

The comparer of keys, or null for the default one.

descending bool

true to sort by the key in descending order; false for ascending.

Returns

IOrderedEnumerable<IpRange>

The ranges, in this list's order, then the key's.

Type Parameters

TKey

The type of the key.

Remarks

As with any ordered sequence, this list's order comes first, and the key orders only what it leaves equal; the list's ranges never start at the same address, so list.ThenBy(key) keeps the list's order.

Exceptions

ArgumentNullException

keySelector is null.

Deserialize(Stream)

Reads ranges that Serialize(Stream) wrote.

public static IpRangeOrderedList Deserialize(Stream stream)

Parameters

stream Stream

The stream, at the start of the data. It is left open.

Returns

IpRangeOrderedList

The list, sorted and merged again.

Exceptions

ArgumentNullException

stream is null.

EndOfStreamException

The stream ends before the last range's end.

InvalidDataException

The number of ranges is negative, or an address is neither 4 nor 16 bytes long.

ArgumentException

stream cannot be read, or a range's addresses are of different families, or out of order.

DeserializeRaw(Stream)

Reads ranges that Serialize(Stream) wrote as their addresses' bytes, with no IpRange or IPAddress made, and no sorting.

public static IEnumerable<(byte[] Start, byte[] End)> DeserializeRaw(Stream stream)

Parameters

stream Stream

The stream, at the start of the data. It is left open.

Returns

IEnumerable<(byte[] Start, byte[] End)>

Each range's first and last address bytes, 4 for IPv4 and 16 for IPv6, in the stream's order, which Serialize(Stream) wrote sorted and merged. Nothing is read until the result is enumerated.

Remarks

For a caller that only stores the ranges, such as a bulk insert into a database.

Exceptions

ArgumentNullException

stream is null, when the enumeration starts.

ArgumentException

stream cannot be read, when the enumeration starts.

EndOfStreamException

The stream ends before the last range's end.

InvalidDataException

The number of ranges is negative, or an address is neither 4 nor 16 bytes long.

Exclude(IEnumerable<IpRange>)

Returns a list of this list's addresses outside other ranges.

public IpRangeOrderedList Exclude(IEnumerable<IpRange> ipRanges)

Parameters

ipRanges IEnumerable<IpRange>

The ranges to leave out, in any order.

Returns

IpRangeOrderedList

The new list, which may be this list itself when ipRanges is empty.

Exceptions

ArgumentNullException

ipRanges is null.

Exclude(IPAddress)

Returns a list of this list's addresses but one.

public IpRangeOrderedList Exclude(IPAddress ipAddress)

Parameters

ipAddress IPAddress

The address to leave out.

Returns

IpRangeOrderedList

The new list.

Exclude(IpRange)

Returns a list of this list's addresses outside a range.

public IpRangeOrderedList Exclude(IpRange ipRange)

Parameters

ipRange IpRange

The range to leave out.

Returns

IpRangeOrderedList

The new list.

Exclude(IpRangeOrderedList)

Returns a list of this list's addresses outside another list.

public IpRangeOrderedList Exclude(IpRangeOrderedList ipRanges)

Parameters

ipRanges IpRangeOrderedList

The ranges to leave out.

Returns

IpRangeOrderedList

The new list, which may be this list itself when ipRanges is empty.

GetEnumerator()

Returns an enumerator that iterates through the collection.

public IEnumerator<IpRange> GetEnumerator()

Returns

IEnumerator<IpRange>

An enumerator that can be used to iterate through the collection.

Intersect(IEnumerable<IpRange>)

Returns a list of the addresses that this list and other ranges both hold.

public IpRangeOrderedList Intersect(IEnumerable<IpRange> ipRanges)

Parameters

ipRanges IEnumerable<IpRange>

The other ranges, in any order.

Returns

IpRangeOrderedList

The new list; this list itself when the other ranges hold every address and this list does not.

Exceptions

ArgumentNullException

ipRanges is null.

Intersect(IpRangeOrderedList)

Returns a list of the addresses that this list and another both hold.

public IpRangeOrderedList Intersect(IpRangeOrderedList ipRanges)

Parameters

ipRanges IpRangeOrderedList

The other list.

Returns

IpRangeOrderedList

The new list; ipRanges itself when this list holds every address, or else this list itself when ipRanges does.

Invert(bool, bool)

Returns a list of the addresses this list does not hold.

public IpRangeOrderedList Invert(bool includeIPv4 = true, bool includeIPv6 = true)

Parameters

includeIPv4 bool

true to include the IPv4 addresses outside this list; false to leave IPv4 out of the result.

includeIPv6 bool

true to include the IPv6 addresses outside this list; false to leave IPv6 out of the result.

Returns

IpRangeOrderedList

The new list. A family this list holds no range of comes back whole, when included.

IsAll()

Determines whether the list holds every address, IPv4 and IPv6.

public bool IsAll()

Returns

bool

true if it does; otherwise, false.

IsAllV4()

Determines whether the list holds every IPv4 address and no IPv6 one.

public bool IsAllV4()

Returns

bool

true if it does; otherwise, false.

IsAllV6()

Determines whether the list holds every IPv6 address and no IPv4 one.

public bool IsAllV6()

Returns

bool

true if it does; otherwise, false.

IsNone()

Determines whether the list holds no range.

public bool IsNone()

Returns

bool

true if it holds none; otherwise, false.

Serialize(Stream)

Writes the ranges to a stream in a compact binary form, which Deserialize(Stream) reads.

public void Serialize(Stream stream)

Parameters

stream Stream

The stream, which is left open.

Remarks

The form is the number of ranges, as a 32-bit little-endian integer, then for each range the length (4 or 16) and bytes of its first address, then those of its last. Scope ids are not written.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream cannot be written.

ToIpNetworks()

Converts each range to the fewest networks that hold its addresses.

public IOrderedEnumerable<IpNetwork> ToIpNetworks()

Returns

IOrderedEnumerable<IpNetwork>

The networks, in the order of their first addresses, the IPv4 networks before the IPv6 ones.

Union(IEnumerable<IpRange>)

Returns a list of this list's addresses and those of other ranges.

public IpRangeOrderedList Union(IEnumerable<IpRange> ipRanges)

Parameters

ipRanges IEnumerable<IpRange>

The ranges to add, in any order.

Returns

IpRangeOrderedList

The new list; this list itself when ipRanges is empty.

Exceptions

ArgumentNullException

ipRanges is null.

Union(IPAddress)

Returns a list of this list's addresses and one more.

public IpRangeOrderedList Union(IPAddress ipAddress)

Parameters

ipAddress IPAddress

The address to add.

Returns

IpRangeOrderedList

The new list.

Union(IpRange)

Returns a list of this list's addresses and those of a range.

public IpRangeOrderedList Union(IpRange ipRange)

Parameters

ipRange IpRange

The range to add.

Returns

IpRangeOrderedList

The new list.