Reading IPv6 addresses

Eight groups, 128 bits

IPv6 writes a 128-bit address as eight colon-separated groups. Each group contains 16 bits, written with one to four hexadecimal digits: 0–9 and a–f. Uppercase letters have the same value. These are the address notation rules in RFC 4291 §2.2.

2001:0db8:0042:0000:0000:0000:0000:0007

We use 2001:db8::/32 for examples because it is reserved for documentation by RFC 3849.

Shortening the address

Remove leading zeros within each group, then replace a run of zero groups with ::. All three lines below identify the same address.

To expand ::, count the visible groups and insert enough zero groups to reach eight. Here there are four visible groups, so :: stands for four zero groups. It can occur only once: 2001::42::7 leaves the position of those zeros ambiguous.

For consistent output, RFC 5952 uses lowercase, compresses the longest zero run, and chooses the first run when lengths tie. A single zero group stays 0. A parser can accept more spellings than a formatter emits.

Prefixes describe a range

The decimal number after / counts the leading bits in a prefix. In 2001:db8:42::/48, the first three groups are fixed: 3 × 16 = 48 bits. /128 fixes every bit; /0 fixes none. See RFC 4291 §2.3.

2001:db8:42::/48       a prefix
2001:db8:42::7/48      an address with a prefix length

In this library the prefix length is called mask. Parsing the second line retains the 7; it does not calculate a network address or check subnet membership.

Addresses you will recognize

These forms come from RFC 4291. The parser checks address syntax; it does not determine whether a destination is assigned or reachable.

Brackets separate an address from a port

A port identifies a service endpoint and sits outside the 128 address bits. Because IPv6 already uses colons, bracket the address before adding a port:

[2001:db8::7]:443

Without brackets, a final :443 could be another hexadecimal address group. RFC 5952 §6 discusses this ambiguity. In ipv6-parse, IPv6 ports require brackets and the port is a decimal number from 0 to 65535.

A zone ID supplies local context

A machine can have several links with link-local addresses. In fe80::1%eth0, the suffix %eth0 identifies which zone to use, commonly a network interface. A numeric form such as fe80::1%3 is also possible.

Zone IDs have local meaning: another machine may use different names or numbers. They are separate from the address bits. This notation is defined in RFC 4007 §11.

The library records a zone ID without looking up the interface. It accepts identifiers shorter than 16 characters; that is a library limit. With a port, use [fe80::1%eth0]:8080.

IPv4 inside IPv6

A dotted-decimal ending occupies the last 32 bits, replacing two hexadecimal groups. ::ffff:192.0.2.1 is an IPv4-mapped address, equivalent to ::ffff:c000:201. See RFC 4291 §2.5.5.2.

The library also accepts plain IPv4, such as 192.0.2.1:443, and shortened forms such as 10.1, which it expands to 10.0.0.1. Its API flag named “IPv4 compatible” means plain IPv4 input. The C guide explains the storage and comparison rules.

Read a combined input

[fe80::7/64%eth0]:8080

fe80::7

The IPv6 address.

/64

The prefix length, stored as the mask.

%eth0

The local zone ID.

:8080

The port, outside the brackets.

This combined syntax is supported by ipv6-parse: mask first, then zone, with both inside the brackets. It is a library input format, not a URL. The library parses the pieces; your application decides how to use them.

Use the API in your language

Start with installation and a working example, then learn how to inspect fields and handle invalid input.

• C guide: building, parsing, formatting, diagnostics, and comparison.
• JavaScript guide: Node.js, browser setup, and synchronous parsing.
• TypeScript guide: typed results, nullable fields, and errors.
• Development guide: tests, benchmarks, and documentation publishing.