Namespace: go.std.net.netip

v1.0

Summary
Index
Constants
Variables
Functions, Macros, and Special Forms
Types

Summary

Provides a low-level interface to the net/netip package.

Package netip defines an IP address type that's a small value type.
Building on that Addr type, the package also defines AddrPort (an
IP address and a port), and Prefix (an IP address and a bit length
prefix).

Compared to the net.IP type, this package's Addr type takes less
memory, is immutable, and is comparable (supports == and being a
map key).

Index

Legend

Constant

Variable

Function

Macro

Special form

Type

GoVar

Receiver/Method

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

(None.)

Variables

(None.)

Functions, Macros, and Special Forms

AddrFrom4
Function v1.0
```
(AddrFrom4 addr)
```
AddrFrom4 returns the address of the IPv4 address given by the bytes in addr.

Go input arguments: (addr [4]byte)

Go returns: Addr

Joker input arguments: [^array4OfByte addr]

Joker returns: ^Addr
AddrFromSlice
Function v1.0
```
(AddrFromSlice slice)
```
AddrFromSlice parses the 4- or 16-byte byte slice as an IPv4 or IPv6 address.
Note that a net.IP can be passed directly as the []byte argument.
If slice's length is not 4 or 16, AddrFromSlice returns Addr{}, false.

Go input arguments: (slice []byte)

Go returns: (ip Addr, ok bool)

Joker input arguments: [^arrayOfByte slice]

Joker returns: [^Addr ip, ^Boolean ok]
AddrPortFrom
Function v1.0
```
(AddrPortFrom ip port)
```
AddrPortFrom returns an AddrPort with the provided IP and port.
It does not allocate.

Go input arguments: (ip Addr, port uint16)

Go returns: AddrPort

Joker input arguments: [^Addr ip, ^Int port]

Joker returns: ^AddrPort
IPv4Unspecified
Function v1.0
```
(IPv4Unspecified)
```
IPv4Unspecified returns the IPv4 unspecified address "0.0.0.0".

Go returns: Addr

Joker input arguments: []

Joker returns: ^Addr
IPv6LinkLocalAllNodes
Function v1.0
```
(IPv6LinkLocalAllNodes)
```
IPv6LinkLocalAllNodes returns the IPv6 link-local all nodes multicast
address ff02::1.

Go returns: Addr

Joker input arguments: []

Joker returns: ^Addr
IPv6Unspecified
Function v1.0
```
(IPv6Unspecified)
```
IPv6Unspecified returns the IPv6 unspecified address "::".

Go returns: Addr

Joker input arguments: []

Joker returns: ^Addr
MustParseAddr
Function v1.0
```
(MustParseAddr s)
```
MustParseAddr calls ParseAddr(s) and panics on error.
It is intended for use in tests with hard-coded strings.

Go input arguments: (s string)

Go returns: Addr

Joker input arguments: [^String s]

Joker returns: ^Addr
MustParseAddrPort
Function v1.0
```
(MustParseAddrPort s)
```
MustParseAddrPort calls ParseAddrPort(s) and panics on error.
It is intended for use in tests with hard-coded strings.

Go input arguments: (s string)

Go returns: AddrPort

Joker input arguments: [^String s]

Joker returns: ^AddrPort
MustParsePrefix
Function v1.0
```
(MustParsePrefix s)
```
MustParsePrefix calls ParsePrefix(s) and panics on error.
It is intended for use in tests with hard-coded strings.

Go input arguments: (s string)

Go returns: Prefix

Joker input arguments: [^String s]

Joker returns: ^Prefix
ParseAddr
Function v1.0
```
(ParseAddr s)
```
ParseAddr parses s as an IP address, returning the result. The string
s can be in dotted decimal ("192.0.2.1"), IPv6 ("2001:db8::68"),
or IPv6 with a scoped addressing zone ("fe80::1cc0:3e8c:119f:c2e1%ens18").

Go input arguments: (s string)

Go returns: (Addr, error)

Joker input arguments: [^String s]

Joker returns: [^Addr, ^Error]
ParseAddrPort
Function v1.0
```
(ParseAddrPort s)
```
ParseAddrPort parses s as an AddrPort.

It doesn't do any name resolution: both the address and the port
must be numeric.

Go input arguments: (s string)

Go returns: (AddrPort, error)

Joker input arguments: [^String s]

Joker returns: [^AddrPort, ^Error]
ParsePrefix
Function v1.0
```
(ParsePrefix s)
```
ParsePrefix parses s as an IP address prefix.
The string can be in the form "192.168.1.0/24" or "2001:db8::/32",
the CIDR notation defined in RFC 4632 and RFC 4291.
IPv6 zones are not permitted in prefixes, and an error will be returned if a
zone is present.

Note that masked address bits are not zeroed. Use Masked for that.

Go input arguments: (s string)

Go returns: (Prefix, error)

Joker input arguments: [^String s]

Joker returns: [^Prefix, ^Error]
PrefixFrom
Function v1.0
```
(PrefixFrom ip bits)
```
PrefixFrom returns a Prefix with the provided IP address and bit
prefix length.

It does not allocate. Unlike Addr.Prefix, PrefixFrom does not mask
off the host bits of ip.

If bits is less than zero or greater than ip.BitLen, Prefix.Bits
will return an invalid value -1.

Go input arguments: (ip Addr, bits int)

Go returns: Prefix

Joker input arguments: [^Addr ip, ^Int bits]

Joker returns: ^Prefix

Types

*Addr
Concrete Type v1.0
Addr represents an IPv4 or IPv6 address (with or without a scoped
addressing zone), similar to net.IP or net.IPAddr.

Unlike net.IP or net.IPAddr, Addr is a comparable value
type (it supports == and can be a map key) and is immutable.

The zero Addr is not a valid IP address.
Addr{} is distinct from both 0.0.0.0 and ::.
UnmarshalBinary
Receiver for *Addr v1.0
```
([b])
```
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
It expects data in the form generated by MarshalBinary.
UnmarshalText
Receiver for *Addr v1.0
```
([text])
```
UnmarshalText implements the encoding.TextUnmarshaler interface.
The IP address is expected in a form accepted by ParseAddr.

If text is empty, UnmarshalText sets *ip to the zero Addr and
returns no error.
*AddrPort
Concrete Type v1.0
AddrPort is an IP and a port number.
UnmarshalBinary
Receiver for *AddrPort v1.0
```
([b])
```
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
It expects data in the form generated by MarshalBinary.
UnmarshalText
Receiver for *AddrPort v1.0
```
([text])
```
UnmarshalText implements the encoding.TextUnmarshaler
interface. The AddrPort is expected in a form
generated by MarshalText or accepted by ParseAddrPort.
*Prefix
Concrete Type v1.0
Prefix is an IP address prefix (CIDR) representing an IP network.

The first Bits() of Addr() are specified. The remaining bits match any address.
The range of Bits() is [0,32] for IPv4 or [0,128] for IPv6.
UnmarshalBinary
Receiver for *Prefix v1.0
```
([b])
```
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
It expects data in the form generated by MarshalBinary.
UnmarshalText
Receiver for *Prefix v1.0
```
([text])
```
UnmarshalText implements the encoding.TextUnmarshaler interface.
The IP address is expected in a form accepted by ParsePrefix
or generated by MarshalText.
Addr
Concrete Type v1.0
Addr represents an IPv4 or IPv6 address (with or without a scoped
addressing zone), similar to net.IP or net.IPAddr.

Unlike net.IP or net.IPAddr, Addr is a comparable value
type (it supports == and can be a map key) and is immutable.

The zero Addr is not a valid IP address.
Addr{} is distinct from both 0.0.0.0 and ::.
AppendTo
Receiver for Addr v1.0
```
([b])
```
AppendTo appends a text encoding of ip,
as generated by MarshalText,
to b and returns the extended buffer.
As16
Receiver for Addr v1.0
```
([])
```
As16 returns the IP address in its 16-byte representation.
IPv4 addresses are returned as IPv4-mapped IPv6 addresses.
IPv6 addresses with zones are returned without their zone (use the
Zone method to get it).
The ip zero value returns all zeroes.
As4
Receiver for Addr v1.0
```
([])
```
As4 returns an IPv4 or IPv4-in-IPv6 address in its 4-byte representation.
If ip is the zero Addr or an IPv6 address, As4 panics.
Note that 0.0.0.0 is not the zero Addr.
AsSlice
Receiver for Addr v1.0
```
([])
```
AsSlice returns an IPv4 or IPv6 address in its respective 4-byte or 16-byte representation.
BitLen
Receiver for Addr v1.0
```
([])
```
BitLen returns the number of bits in the IP address:
128 for IPv6, 32 for IPv4, and 0 for the zero Addr.

Note that IPv4-mapped IPv6 addresses are considered IPv6 addresses
and therefore have bit length 128.
Compare
Receiver for Addr v1.0
```
([ip2])
```
Compare returns an integer comparing two IPs.
The result will be 0 if ip == ip2, -1 if ip < ip2, and +1 if ip > ip2.
The definition of "less than" is the same as the Less method.
Is4
Receiver for Addr v1.0
```
([])
```
Is4 reports whether ip is an IPv4 address.

It returns false for IPv4-mapped IPv6 addresses. See Addr.Unmap.
Is4In6
Receiver for Addr v1.0
```
([])
```
Is4In6 reports whether ip is an IPv4-mapped IPv6 address.
Is6
Receiver for Addr v1.0
```
([])
```
Is6 reports whether ip is an IPv6 address, including IPv4-mapped
IPv6 addresses.
IsGlobalUnicast
Receiver for Addr v1.0
```
([])
```
IsGlobalUnicast reports whether ip is a global unicast address.

It returns true for IPv6 addresses which fall outside of the current
IANA-allocated 2000::/3 global unicast space, with the exception of the
link-local address space. It also returns true even if ip is in the IPv4
private address space or IPv6 unique local address space.
It returns false for the zero Addr.

For reference, see RFC 1122, RFC 4291, and RFC 4632.
IsInterfaceLocalMulticast
Receiver for Addr v1.0
```
([])
```
IsInterfaceLocalMulticast reports whether ip is an IPv6 interface-local
multicast address.
IsLinkLocalMulticast
Receiver for Addr v1.0
```
([])
```
IsLinkLocalMulticast reports whether ip is a link-local multicast address.
IsLinkLocalUnicast
Receiver for Addr v1.0
```
([])
```
IsLinkLocalUnicast reports whether ip is a link-local unicast address.
IsLoopback
Receiver for Addr v1.0
```
([])
```
IsLoopback reports whether ip is a loopback address.
IsMulticast
Receiver for Addr v1.0
```
([])
```
IsMulticast reports whether ip is a multicast address.
IsPrivate
Receiver for Addr v1.0
```
([])
```
IsPrivate reports whether ip is a private address, according to RFC 1918
(IPv4 addresses) and RFC 4193 (IPv6 addresses). That is, it reports whether
ip is in 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, or fc00::/7. This is the
same as net.IP.IsPrivate.
IsUnspecified
Receiver for Addr v1.0
```
([])
```
IsUnspecified reports whether ip is an unspecified address, either the IPv4
address "0.0.0.0" or the IPv6 address "::".

Note that the zero Addr is not an unspecified address.
IsValid
Receiver for Addr v1.0
```
([])
```
IsValid reports whether the Addr is an initialized address (not the zero Addr).

Note that "0.0.0.0" and "::" are both valid values.
Less
Receiver for Addr v1.0
```
([ip2])
```
Less reports whether ip sorts before ip2.
IP addresses sort first by length, then their address.
IPv6 addresses with zones sort just after the same address without a zone.
MarshalBinary
Receiver for Addr v1.0
```
([])
```
MarshalBinary implements the encoding.BinaryMarshaler interface.
It returns a zero-length slice for the zero Addr,
the 4-byte form for an IPv4 address,
and the 16-byte form with zone appended for an IPv6 address.
MarshalText
Receiver for Addr v1.0
```
([])
```
MarshalText implements the encoding.TextMarshaler interface,
The encoding is the same as returned by String, with one exception:
If ip is the zero Addr, the encoding is the empty string.
Next
Receiver for Addr v1.0
```
([])
```
Next returns the address following ip.
If there is none, it returns the zero Addr.
Prefix
Receiver for Addr v1.0
```
([b])
```
Prefix keeps only the top b bits of IP, producing a Prefix
of the specified length.
If ip is a zero Addr, Prefix always returns a zero Prefix and a nil error.
Otherwise, if bits is less than zero or greater than ip.BitLen(),
Prefix returns an error.
Prev
Receiver for Addr v1.0
```
([])
```
Prev returns the IP before ip.
If there is none, it returns the IP zero value.
String
Receiver for Addr v1.0
```
([])
```
String returns the string form of the IP address ip.
It returns one of 5 forms:

- "invalid IP", if ip is the zero Addr
- IPv4 dotted decimal ("192.0.2.1")
- IPv6 ("2001:db8::1")
- "::ffff:1.2.3.4" (if Is4In6)
- IPv6 with zone ("fe80:db8::1%eth0")

Note that unlike package net's IP.String method,
IPv4-mapped IPv6 addresses format with a "::ffff:"
prefix before the dotted quad.
StringExpanded
Receiver for Addr v1.0
```
([])
```
StringExpanded is like String but IPv6 addresses are expanded with leading
zeroes and no "::" compression. For example, "2001:db8::1" becomes
"2001:0db8:0000:0000:0000:0000:0000:0001".
Unmap
Receiver for Addr v1.0
```
([])
```
Unmap returns ip with any IPv4-mapped IPv6 address prefix removed.

That is, if ip is an IPv6 address wrapping an IPv4 address, it
returns the wrapped IPv4 address. Otherwise it returns ip unmodified.
WithZone
Receiver for Addr v1.0
```
([zone])
```
WithZone returns an IP that's the same as ip but with the provided
zone. If zone is empty, the zone is removed. If ip is an IPv4
address, WithZone is a no-op and returns ip unchanged.
Zone
Receiver for Addr v1.0
```
([])
```
Zone returns ip's IPv6 scoped addressing zone, if any.
AddrPort
Concrete Type v1.0
AddrPort is an IP and a port number.
Addr
Receiver for AddrPort v1.0
```
([])
```
Addr returns p's IP address.
AppendTo
Receiver for AddrPort v1.0
```
([b])
```
AppendTo appends a text encoding of p,
as generated by MarshalText,
to b and returns the extended buffer.
IsValid
Receiver for AddrPort v1.0
```
([])
```
IsValid reports whether p.IP() is valid.
All ports are valid, including zero.
MarshalBinary
Receiver for AddrPort v1.0
```
([])
```
MarshalBinary implements the encoding.BinaryMarshaler interface.
It returns Addr.MarshalBinary with an additional two bytes appended
containing the port in little-endian.
MarshalText
Receiver for AddrPort v1.0
```
([])
```
MarshalText implements the encoding.TextMarshaler interface. The
encoding is the same as returned by String, with one exception: if
p.Addr() is the zero Addr, the encoding is the empty string.
Port
Receiver for AddrPort v1.0
```
([])
```
Port returns p's port.
String
Receiver for AddrPort v1.0
```
([])
```
Prefix
Concrete Type v1.0
Prefix is an IP address prefix (CIDR) representing an IP network.

The first Bits() of Addr() are specified. The remaining bits match any address.
The range of Bits() is [0,32] for IPv4 or [0,128] for IPv6.
Addr
Receiver for Prefix v1.0
```
([])
```
Addr returns p's IP address.
AppendTo
Receiver for Prefix v1.0
```
([b])
```
AppendTo appends a text encoding of p,
as generated by MarshalText,
to b and returns the extended buffer.
Bits
Receiver for Prefix v1.0
```
([])
```
Bits returns p's prefix length.

It reports -1 if invalid.
Contains
Receiver for Prefix v1.0
```
([ip])
```
Contains reports whether the network p includes ip.

An IPv4 address will not match an IPv6 prefix.
An IPv4-mapped IPv6 address will not match an IPv4 prefix.
A zero-value IP will not match any prefix.
If ip has an IPv6 zone, Contains returns false,
because Prefixes strip zones.
IsSingleIP
Receiver for Prefix v1.0
```
([])
```
IsSingleIP reports whether p contains exactly one IP.
IsValid
Receiver for Prefix v1.0
```
([])
```
IsValid reports whether p.Bits() has a valid range for p.IP().
If p.Addr() is the zero Addr, IsValid returns false.
Note that if p is the zero Prefix, then p.IsValid() == false.
MarshalBinary
Receiver for Prefix v1.0
```
([])
```
MarshalBinary implements the encoding.BinaryMarshaler interface.
It returns Addr.MarshalBinary with an additional byte appended
containing the prefix bits.
MarshalText
Receiver for Prefix v1.0
```
([])
```
MarshalText implements the encoding.TextMarshaler interface,
The encoding is the same as returned by String, with one exception:
If p is the zero value, the encoding is the empty string.
Masked
Receiver for Prefix v1.0
```
([])
```
Masked returns p in its canonical form, with all but the high
p.Bits() bits of p.Addr() masked off.

If p is zero or otherwise invalid, Masked returns the zero Prefix.
Overlaps
Receiver for Prefix v1.0
```
([o])
```
Overlaps reports whether p and o contain any IP addresses in common.

If p and o are of different address families or either have a zero
IP, it reports false. Like the Contains method, a prefix with an
IPv4-mapped IPv6 address is still treated as an IPv6 mask.
String
Receiver for Prefix v1.0
```
([])
```
String returns the CIDR notation of p: "<ip>/<bits>".
arrayOfAddr
Concrete Type v1.0
Addr represents an IPv4 or IPv6 address (with or without a scoped
addressing zone), similar to net.IP or net.IPAddr.

Unlike net.IP or net.IPAddr, Addr is a comparable value
type (it supports == and can be a map key) and is immutable.

The zero Addr is not a valid IP address.
Addr{} is distinct from both 0.0.0.0 and ::.
arrayOfAddrPort
Concrete Type v1.0
AddrPort is an IP and a port number.
arrayOfPrefix
Concrete Type v1.0
Prefix is an IP address prefix (CIDR) representing an IP network.

The first Bits() of Addr() are specified. The remaining bits match any address.
The range of Bits() is [0,32] for IPv4 or [0,128] for IPv6.

Namespace: go.std.net.netip

Contents

Summary

Index

Legend

Constants

Variables

Functions, Macros, and Special Forms

AddrFrom4

AddrFromSlice

AddrPortFrom

IPv4Unspecified

IPv6LinkLocalAllNodes

IPv6Unspecified

MustParseAddr

MustParseAddrPort

MustParsePrefix

ParseAddr

ParseAddrPort

ParsePrefix

PrefixFrom

Types

*Addr

UnmarshalBinary

UnmarshalText

*AddrPort

UnmarshalBinary

UnmarshalText

*Prefix

UnmarshalBinary

UnmarshalText

Addr

AppendTo

As16

As4

AsSlice

BitLen

Compare

Is4

Is4In6

Is6

IsGlobalUnicast

IsInterfaceLocalMulticast

IsLinkLocalMulticast

IsLinkLocalUnicast

IsLoopback

IsMulticast

IsPrivate

IsUnspecified

IsValid

Less

MarshalBinary

MarshalText

Next

Prefix

Prev

String

StringExpanded

Unmap

WithZone

Zone

AddrPort

Addr

AppendTo

IsValid

MarshalBinary

MarshalText

Port

String

Prefix

Addr

AppendTo

Bits

Contains

IsSingleIP

IsValid

MarshalBinary

MarshalText

Masked

Overlaps