Struct IpAddressValue
Represents an IP address as a value: what an IPAddress holds, with no object on the heap.
public readonly struct IpAddressValue : IEquatable<IpAddressValue>, IComparable<IpAddressValue>- Implements
- Inherited Members
Remarks
Two values are equal when the two IPAddress objects would be: in the version, the address and the IPv6 scope id. So 10.0.0.2, ::10.0.0.2 and ::ffff:10.0.0.2 are three addresses, and fe80::1%3 is not fe80::1. The default value holds no address: it is neither IPv4 nor IPv6, it is written as an empty string, and converting it throws.
A value is 24 bytes, which a field takes in more than one write, where an IPAddress field takes one reference: a thread that reads a field while another replaces it can get half of each address. So a field that several threads read is set before its object is shared and never replaced, or its values sit in an object that is replaced as one reference.
Constructors
IpAddressValue(IPAddress)
Initializes a new instance of the IpAddressValue structure from an IPAddress, with its scope id.
public IpAddressValue(IPAddress ipAddress)Parameters
ipAddressIPAddressThe address.
Exceptions
- ArgumentNullException
ipAddressis null.
IpAddressValue(ReadOnlySpan<byte>)
Initializes a new instance of the IpAddressValue structure from the bytes of an address, as an IP header holds them.
public IpAddressValue(ReadOnlySpan<byte> address)Parameters
addressReadOnlySpan<byte>The address in network byte order: 4 bytes for IPv4, 16 bytes for IPv6.
Exceptions
- ArgumentException
addressis neither 4 nor 16 bytes long.
Properties
IsIPv4MappedToIPv6
Gets whether the address is an IPv4-mapped IPv6 address, such as ::ffff:10.0.0.2.
public bool IsIPv4MappedToIPv6 { get; }Property Value
IsV4
Gets whether the address is an IPv4 address.
public bool IsV4 { get; }Property Value
IsV6
Gets whether the address is an IPv6 address.
public bool IsV6 { get; }Property Value
ScopeId
Gets the address's IPv6 scope id, the interface a link-local address belongs to.
public uint ScopeId { get; }Property Value
- uint
The scope id; 0 for an IPv4 address, an IPv6 address without one, and the default value.
Methods
CompareTo(IpAddressValue)
Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.
public int CompareTo(IpAddressValue other)Parameters
otherIpAddressValueAn object to compare with this instance.
Returns
- int
A value that indicates the relative order of the objects being compared. The return value has these meanings:
Value Meaning Less than zero This instance precedes otherin the sort order.Zero This instance occurs in the same position in the sort order as other.Greater than zero This instance follows otherin the sort order.
Remarks
Every IPv4 address comes before every IPv6 address; then addresses go by number, and equal numbers by scope id, so the result is zero only for equal values. An IPv4-mapped address is IPv6 here, so ::ffff:10.0.0.2 comes after 255.255.255.255; Compare(IpAddressValue, IpAddressValue) compares it as its IPv4 address. The default value comes first.
Equals(IPAddress?)
Throws NotSupportedException: an IPAddress is compared with a value once it is converted to one.
[Obsolete("Convert the address to a value once, with ToValue(), and compare the two values.", true)]
public bool Equals(IPAddress? other)Parameters
otherIPAddressThe address.
Returns
- bool
Never returns.
Exceptions
- NotSupportedException
Always.
Equals(object?)
Indicates whether this instance and a specified object are equal.
public override bool Equals(object? obj)Parameters
objobjectThe object to compare with the current instance.
Returns
- bool
true if
objand this instance are the same type and represent the same value; otherwise, false.
Equals(IpAddressValue)
Indicates whether the current object is equal to another object of the same type.
public bool Equals(IpAddressValue other)Parameters
otherIpAddressValueAn object to compare with this object.
Returns
GetHashCode()
Returns the hash code for this instance.
public override int GetHashCode()Returns
- int
A 32-bit signed integer that is the hash code for this instance.
MapToIPv4()
Maps the address to IPv4, as MapToIPv4() does: an IPv4 address stays as it is, and an IPv6 address gives its last 4 bytes.
public IpAddressValue MapToIPv4()Returns
- IpAddressValue
An IPv4 address.
Exceptions
- InvalidOperationException
The value holds no address.
ToIPAddress()
Converts the value to an IPAddress, with its scope id.
public IPAddress ToIPAddress()Returns
- IPAddress
A new address.
Exceptions
- InvalidOperationException
The value holds no address.
ToString()
Returns the fully qualified type name of this instance.
public override string ToString()Returns
- string
The fully qualified type name.
Remarks
Written as ToString() writes the address; the default value gives an empty string.
TryWriteBytes(Span<byte>, out int)
Tries to write the address to a span of bytes in network byte order, as an IP header holds it.
public bool TryWriteBytes(Span<byte> destination, out int bytesWritten)Parameters
destinationSpan<byte>The span to write to.
bytesWrittenintWhen this method returns, the number of bytes written: 4 for IPv4, 16 for IPv6, or 0 when
destinationis too short.
Returns
Exceptions
- InvalidOperationException
The value holds no address.
Operators
operator ==(IpAddressValue, IpAddressValue)
Determines whether two values hold the same address.
public static bool operator ==(IpAddressValue left, IpAddressValue right)Parameters
leftIpAddressValueThe first value to compare.
rightIpAddressValueThe second value to compare.
Returns
operator >(IpAddressValue, IpAddressValue)
Determines whether one value comes after another, in the order CompareTo(IpAddressValue) gives.
public static bool operator >(IpAddressValue left, IpAddressValue right)Parameters
leftIpAddressValueThe first value to compare.
rightIpAddressValueThe second value to compare.
Returns
operator >=(IpAddressValue, IpAddressValue)
Determines whether one value comes after another or equals it, in the order CompareTo(IpAddressValue) gives.
public static bool operator >=(IpAddressValue left, IpAddressValue right)Parameters
leftIpAddressValueThe first value to compare.
rightIpAddressValueThe second value to compare.
Returns
operator !=(IpAddressValue, IpAddressValue)
Determines whether two values hold different addresses.
public static bool operator !=(IpAddressValue left, IpAddressValue right)Parameters
leftIpAddressValueThe first value to compare.
rightIpAddressValueThe second value to compare.
Returns
operator <(IpAddressValue, IpAddressValue)
Determines whether one value comes before another, in the order CompareTo(IpAddressValue) gives.
public static bool operator <(IpAddressValue left, IpAddressValue right)Parameters
leftIpAddressValueThe first value to compare.
rightIpAddressValueThe second value to compare.
Returns
operator <=(IpAddressValue, IpAddressValue)
Determines whether one value comes before another or equals it, in the order CompareTo(IpAddressValue) gives.
public static bool operator <=(IpAddressValue left, IpAddressValue right)Parameters
leftIpAddressValueThe first value to compare.
rightIpAddressValueThe second value to compare.