`std/ip/address`

std/ip/src/address.trb

IP addresses and socket addresses: values like any other, parsed from text and shown as text (docs/design/OS.md section 5.5, docs/design/NETWORK.md section 4, docs/design/URI.md section 8a). Nothing here touches the network.

type AddressError

type AddressError with Show, Error

Text that is not an address of the kind it was read as, and why.

field text

text: String

The text that was read.

field reason

reason: String

What is wrong with it.

fn show

fn show(): String

"not an IP address: 300.1.2.3 (the part 300 is larger than 255)".

type Ipv4Address

type Ipv4Address with Show, Equals, Hash, Compare, TryFrom<String, AddressError>

An IPv4 address: four octets, held as one number from 0 to 4294967295.

const loopback

static loopback = Self 2130706433

127.0.0.1.

const unspecified

static unspecified = Self 0

0.0.0.0, which a listener binds to for every interface.

fn of

static fn of(first: UInt8, second: UInt8, third: UInt8, fourth: UInt8): Self

The address of four octets, most significant first: Ipv4Address.of(127, 0, 0, 1).

fn number

fn number(): Int

The address as the number it is, from 0 to 4294967295: what the runtime is handed.

fn octets

fn octets(): List<Int>

The four octets, most significant first.

fn isLoopback

fn isLoopback(): Bool

Inside 127.0.0.0/8.

fn isUnspecified

fn isUnspecified(): Bool

0.0.0.0.

fn isPrivate

fn isPrivate(): Bool

Inside 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16 (RFC 1918).

fn isLinkLocal

fn isLinkLocal(): Bool

Inside 169.254.0.0/16.

fn isMulticast

fn isMulticast(): Bool

Inside 224.0.0.0/4.

fn show

fn show(): String

192.168.1.23.

fn compare

fn compare(other: Self): Ordering

In the order of their numbers.

fn tryFrom

static fn tryFrom(text: String): Result<Self, AddressError>

Four decimal parts from 0 to 255, separated by dots. A part with a leading zero is refused, because some systems read 010 as octal and some as decimal, and an address two readers disagree on is no address.

type Ipv6Address

type Ipv6Address with Show, Equals, Hash, Compare, TryFrom<String, AddressError>

An IPv6 address: eight 16-bit segments, held as two 64-bit halves. show() is the RFC 5952 form: lower case, no leading zeros, the longest run of zero segments collapsed to ::.

const loopback

static loopback = Self 0, 1

::1.

const unspecified

static unspecified = Self 0, 0

::, which a listener binds to for every interface.

fn of

static fn of(segments: List<Int>): Result<Self, AddressError>

The address of eight segments, most significant first. Each is taken modulo 65536.

fn ofHalves

static fn ofHalves(high: Int, low: Int): Self

The address of its two halves, as the runtime hands them over.

fn high

fn high(): Int

Segments 0 to 3 as the bits of an Int: what the runtime is handed.

fn low

fn low(): Int

Segments 4 to 7 as the bits of an Int.

fn segments

fn segments(): List<Int>

The eight segments, most significant first, each from 0 to 65535.

fn isLoopback

fn isLoopback(): Bool

::1.

fn isUnspecified

fn isUnspecified(): Bool

::.

fn isLinkLocal

fn isLinkLocal(): Bool

Inside fe80::/10.

fn isUniqueLocal

fn isUniqueLocal(): Bool

Inside fc00::/7.

fn isMulticast

fn isMulticast(): Bool

Inside ff00::/8.

fn mappedVersion4

fn mappedVersion4(): Ipv4Address?

The IPv4 address inside an IPv4-mapped one: ::ffff:192.0.2.1.

fn show

fn show(): String

The RFC 5952 form: 2001:db8::1, ::1, ::ffff:192.0.2.1.

fn compare

fn compare(other: Self): Ordering

Half by half, as the numbers they are without a sign.

fn tryFrom

static fn tryFrom(text: String): Result<Self, AddressError>

RFC 4291 section 2.2: up to eight segments of one to four hexadecimal digits, one :: for a run of zeros, and an IPv4 address in place of the last two. A zone (fe80::1%eth0) is not part of an address and is refused.

type IpAddress

type IpAddress with Show, Equals, Hash, Compare, TryFrom<String, AddressError>

Either version. Reading tells them apart by the text: a colon is IPv6.

case Version4

case Version4(address: Ipv4Address)

An IPv4 address: 192.0.2.1.

case Version6

case Version6(address: Ipv6Address)

An IPv6 address: 2001:db8::1.

const loopback

static loopback = Self.Version4 Ipv4Address.loopback

127.0.0.1.

fn isLoopback

fn isLoopback(): Bool

The loopback address of either version.

fn isUnspecified

fn isUnspecified(): Bool

The unspecified address of either version, which a listener binds to for every interface.

fn version

fn version(): Int

4 or 6.

fn show

fn show(): String

As the version writes it: 127.0.0.1 for IPv4, ::1 for IPv6.

fn compare

fn compare(other: Self): Ordering

Every IPv4 address before every IPv6 address, and each version in the order of its numbers.

fn tryFrom

static fn tryFrom(text: String): Result<Self, AddressError>

The address text writes: IPv6 where it contains a colon, IPv4 otherwise. A text the version's own reading refuses is the AddressError of that reading.

type SocketAddress

type SocketAddress with Show, Equals, Hash, TryFrom<String, AddressError>

An IP address and a port: where a listener listens and where a connection goes.

field address

address: IpAddress

The host: 127.0.0.1 or ::1.

field port

port: Int

From 0 to 65535; 0 asks the system to choose a free port where a listener binds.

fn show

fn show(): String

127.0.0.1:8080, or [::1]:8080 - the brackets tell the port from the address.

fn tryFrom

static fn tryFrom(text: String): Result<Self, AddressError>

host:port with an IPv4 address, [host]:port with an IPv6 one.

type Subnet

type Subnet with Show, Equals, Hash, TryFrom<String, AddressError>

A network: the address of its first host and the number of leading bits that every address in it shares. The address is always the network's own: its bits after the prefix are zero, so 192.168.1.23/24 is refused and 192.168.1.0/24 is the value. It is a capsule so that no value of it breaks that: Subnet.of and tryFrom are the ways in.

fn of

static fn of(address: IpAddress, prefixLength: Int): Result<Self, AddressError>

The network of address and prefixLength. A prefix outside 0..32 (version 4) or 0..128 (version 6) and an address with bits set after the prefix are refused.

fn address

fn address(): IpAddress

The first address of the network.

fn prefixLength

fn prefixLength(): Int

The number of leading bits every address of the network shares.

fn contains

fn contains(address: IpAddress): Bool

Whether address is in the network. An address of the other version never is, a mapped one included.

fn show

fn show(): String

10.0.0.0/8, fe80::/64.

fn tryFrom

static fn tryFrom(text: String): Result<Self, AddressError>

address/prefix: the address as IpAddress reads it, a /, and a prefix of decimal digits without a sign.