NetworkInspector.Values 0.20.0

NetworkInspector.Values

Small, fast value types for network identifiers and time: MacAddress, IPv4Address, IPv6Address, Eui64, Uuid, and Timestamp. They are the value types of the whole NetworkInspector stack and work just as well on their own.

Highlights

• Value semantics. Every type is a readonly record struct: no allocation, equality and ordering built in (IEquatable<T>, IComparable<T>, <, >, <=, >=).
• Allocation-free formatting and parsing. ISpanFormattable, IUtf8SpanFormattable, and ISpanParsable<T> let you format into and parse from spans without strings.
• Stable text forms for logs and exports: RFC 5952 IPv6, colon-separated MAC, ISO-8601 timestamps with nanoseconds.
• Address classification: broadcast, multicast, private, loopback, link-local, IPv4-mapped, and more.
• Nanosecond timestamps with TimeSpan arithmetic.
• Standalone. No dependency on the rest of NetworkInspector.

Install

dotnet add package NetworkInspector.Values

Quick Start

using NetworkInspector.Values;

MacAddress mac = MacAddress.FromBytes([0x00, 0x1A, 0x2B, 0x3C, 0x4D, 0x5E]);
IPv4Address ip4 = IPv4Address.FromBytes([192, 168, 1, 10]);
if (!IPv6Address.TryParse("2001:db8::1", out IPv6Address ip6))
{
    throw new FormatException("Invalid IPv6 address.");
}

Timestamp ts = Timestamp.FromSecs(1_700_000_000);

Console.WriteLine(mac); // 00:1A:2B:3C:4D:5E
Console.WriteLine(ip4); // 192.168.1.10
Console.WriteLine(ip6); // 2001:DB8::1
Console.WriteLine(ts);  // 2023-11-14T22:13:20.000000000Z

Types

Text output of MacAddress, Eui64, Uuid, and IPv6Address uses uppercase hex by default; TryParse accepts either case. Lower case is a per-call choice (see "Choose The Letter Case"). Parse is available through the generic IParsable<T> / ISpanParsable<T> interfaces; call TryParse directly for untrusted text.

Common Tasks

Classify Addresses

if (ip4.IsPrivate || ip4.IsLoopback)
{
    Console.WriteLine("internal traffic");
}

Format Without Allocating

Span<char> buffer = stackalloc char[64];
if (ip6.TryFormat(buffer, out int written, default, null))
{
    Console.Out.Write(buffer[..written]);
}

Choose The Letter Case

Upper case is the default, so existing exports and filters keep matching. Lower case (the spelling RFC 5952 recommends for IPv6) is selected per call, with the HexCase enumeration or with the format specifier x; X and the empty format give upper case. Any other specifier throws FormatException, so a specifier that would have no effect is never ignored silently.

string upper = mac.Format();                 // "AB:CD:EF:01:23:45"
string lower = mac.Format(HexCase.Lower);    // "ab:cd:ef:01:23:45"
string text = $"{ip6:x}";                    // "2001:db8::1"
int written = uuid.FormatInto(buffer, HexCase.Lower);

Use As Keys

The types are equatable and comparable values, so they work as dictionary keys, in sorted sets, and in ORDER BY-style reports without custom comparers.

Limits And Thread-Safety Notes

• Immutable values: safe to share across threads.
• Timestamp.FromSecs and the other factories throw OverflowException outside the representable range.
• Validate external text with TryParse instead of catching exceptions.

Learn More

• Core · FrameBuilder · Root overview
• GitHub repository · Issue tracker

License

MIT License