Imports #
"math/bits"
"cmp"
"errors"
"internal/bytealg"
"internal/byteorder"
"internal/itoa"
"math"
"strconv"
"unique"
netip
Imports
Constants & Variables
digits const #
digits is a string of the hex digits from 0 to f. It's used in appendDecimal and appendHex to format IP addresses.
const digits = "0123456789abcdef"z0 var #
z0, z4, and z6noz are sentinel Addr.z values. See the Addr type's field docs.
var z0 *ast.IndexExprz4 var #
z0, z4, and z6noz are sentinel Addr.z values. See the Addr type's field docs.
var z4 = *ast.CallExprz6noz var #
z0, z4, and z6noz are sentinel Addr.z values. See the Addr type's field docs.
var z6noz = *ast.CallExprStructs
Addr struct #
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 ::.
type Addr struct {
addr uint128
z *ast.IndexExpr
}AddrPort struct #
AddrPort is an IP and a port number.
type AddrPort struct {
ip Addr
port uint16
}Prefix struct #
Prefix is an IP address prefix (CIDR) representing an IP network. The first [Prefix.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.
type Prefix struct {
ip Addr
bitsPlusOne uint8
}addrDetail struct #
addrDetail represents the details of an Addr, like address family and IPv6 zone.
type addrDetail struct {
isV6 bool
zoneV6 string
}parseAddrError struct #
type parseAddrError struct {
in string
msg string
at string
}parsePrefixError struct #
type parsePrefixError struct {
in string
msg string
}uint128 struct #
uint128 represents a uint128 using two uint64s. When the methods below mention a bit number, bit 0 is the most significant bit (in hi) and bit 127 is the lowest (lo&1).
type uint128 struct {
hi uint64
lo uint64
}Functions
Addr method #
Addr returns p's IP address.
func (p AddrPort) Addr() AddrAddr method #
Addr returns p's IP address.
func (p Prefix) Addr() AddrAddrFrom16 function #
AddrFrom16 returns the IPv6 address given by the bytes in addr. An IPv4-mapped IPv6 address is left as an IPv6 address. (Use Unmap to convert them if needed.)
func AddrFrom16(addr [16]byte) AddrAddrFrom4 function #
AddrFrom4 returns the address of the IPv4 address given by the bytes in addr.
func AddrFrom4(addr [4]byte) AddrAddrFromSlice function #
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.
func AddrFromSlice(slice []byte) (ip Addr, ok bool)AddrPortFrom function #
AddrPortFrom returns an [AddrPort] with the provided IP and port. It does not allocate.
func AddrPortFrom(ip Addr, port uint16) AddrPortAppendBinary method #
AppendBinary implements the [encoding.AppendMarshaler] interface. It returns [Addr.AppendBinary] with an additional byte appended containing the prefix bits.
func (p Prefix) AppendBinary(b []byte) ([]byte, error)AppendBinary method #
AppendBinary implements the [encoding.BinaryAppender] interface.
func (ip Addr) AppendBinary(b []byte) ([]byte, error)AppendBinary method #
AppendBinary implements the [encoding.BinaryAppendler] interface. It returns [Addr.AppendBinary] with an additional two bytes appended containing the port in little-endian.
func (p AddrPort) AppendBinary(b []byte) ([]byte, error)AppendText method #
AppendText implements the [encoding.TextAppender] interface. It is the same as [Prefix.AppendTo].
func (p Prefix) AppendText(b []byte) ([]byte, error)AppendText method #
AppendText implements the [encoding.TextAppender] interface. The encoding is the same as returned by [AddrPort.AppendTo].
func (p AddrPort) AppendText(b []byte) ([]byte, error)AppendText method #
AppendText implements the [encoding.TextAppender] interface, It is the same as [Addr.AppendTo].
func (ip Addr) AppendText(b []byte) ([]byte, error)AppendTo method #
AppendTo appends a text encoding of p, as generated by [Prefix.MarshalText], to b and returns the extended buffer.
func (p Prefix) AppendTo(b []byte) []byteAppendTo method #
AppendTo appends a text encoding of ip, as generated by [Addr.MarshalText], to b and returns the extended buffer.
func (ip Addr) AppendTo(b []byte) []byteAppendTo method #
AppendTo appends a text encoding of p, as generated by [AddrPort.MarshalText], to b and returns the extended buffer.
func (p AddrPort) AppendTo(b []byte) []byteAs16 method #
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 [Addr.Zone] method to get it). The ip zero value returns all zeroes.
func (ip Addr) As16() (a16 [16]byte)As4 method #
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.
func (ip Addr) As4() (a4 [4]byte)AsSlice method #
AsSlice returns an IPv4 or IPv6 address in its respective 4-byte or 16-byte representation.
func (ip Addr) AsSlice() []byteBitLen method #
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.
func (ip Addr) BitLen() intBits method #
Bits returns p's prefix length. It reports -1 if invalid.
func (p Prefix) Bits() intCompare method #
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 [Addr.Less] method.
func (ip Addr) Compare(ip2 Addr) intCompare method #
Compare returns an integer comparing two AddrPorts. The result will be 0 if p == p2, -1 if p < p2, and +1 if p > p2. AddrPorts sort first by IP address, then port.
func (p AddrPort) Compare(p2 AddrPort) intContains method #
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.
func (p Prefix) Contains(ip Addr) boolError method #
func (err parsePrefixError) Error() stringError method #
func (err parseAddrError) Error() stringIPv4Unspecified function #
IPv4Unspecified returns the IPv4 unspecified address "0.0.0.0".
func IPv4Unspecified() AddrIPv6LinkLocalAllNodes function #
IPv6LinkLocalAllNodes returns the IPv6 link-local all nodes multicast address ff02::1.
func IPv6LinkLocalAllNodes() AddrIPv6LinkLocalAllRouters function #
IPv6LinkLocalAllRouters returns the IPv6 link-local all routers multicast address ff02::2.
func IPv6LinkLocalAllRouters() AddrIPv6Loopback function #
IPv6Loopback returns the IPv6 loopback address ::1.
func IPv6Loopback() AddrIPv6Unspecified function #
IPv6Unspecified returns the IPv6 unspecified address "::".
func IPv6Unspecified() AddrIs4 method #
Is4 reports whether ip is an IPv4 address. It returns false for IPv4-mapped IPv6 addresses. See [Addr.Unmap].
func (ip Addr) Is4() boolIs4In6 method #
Is4In6 reports whether ip is an "IPv4-mapped IPv6 address" as defined by RFC 4291. That is, it reports whether ip is in ::ffff:0:0/96.
func (ip Addr) Is4In6() boolIs6 method #
Is6 reports whether ip is an IPv6 address, including IPv4-mapped IPv6 addresses.
func (ip Addr) Is6() boolIsGlobalUnicast method #
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.
func (ip Addr) IsGlobalUnicast() boolIsInterfaceLocalMulticast method #
IsInterfaceLocalMulticast reports whether ip is an IPv6 interface-local multicast address.
func (ip Addr) IsInterfaceLocalMulticast() boolIsLinkLocalMulticast method #
IsLinkLocalMulticast reports whether ip is a link-local multicast address.
func (ip Addr) IsLinkLocalMulticast() boolIsLinkLocalUnicast method #
IsLinkLocalUnicast reports whether ip is a link-local unicast address.
func (ip Addr) IsLinkLocalUnicast() boolIsLoopback method #
IsLoopback reports whether ip is a loopback address.
func (ip Addr) IsLoopback() boolIsMulticast method #
IsMulticast reports whether ip is a multicast address.
func (ip Addr) IsMulticast() boolIsPrivate method #
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].
func (ip Addr) IsPrivate() boolIsSingleIP method #
IsSingleIP reports whether p contains exactly one IP.
func (p Prefix) IsSingleIP() boolIsUnspecified method #
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.
func (ip Addr) IsUnspecified() boolIsValid method #
IsValid reports whether the [Addr] is an initialized address (not the zero Addr). Note that "0.0.0.0" and "::" are both valid values.
func (ip Addr) IsValid() boolIsValid method #
IsValid reports whether p.Addr() is valid. All ports are valid, including zero.
func (p AddrPort) IsValid() boolIsValid method #
IsValid reports whether p.Bits() has a valid range for p.Addr(). If p.Addr() is the zero [Addr], IsValid returns false. Note that if p is the zero [Prefix], then p.IsValid() == false.
func (p Prefix) IsValid() boolLess method #
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.
func (ip Addr) Less(ip2 Addr) boolMarshalBinary method #
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.
func (ip Addr) MarshalBinary() ([]byte, error)MarshalBinary method #
MarshalBinary implements the [encoding.BinaryMarshaler] interface. It returns [Addr.MarshalBinary] with an additional two bytes appended containing the port in little-endian.
func (p AddrPort) MarshalBinary() ([]byte, error)MarshalBinary method #
MarshalBinary implements the [encoding.BinaryMarshaler] interface. It returns [Addr.MarshalBinary] with an additional byte appended containing the prefix bits.
func (p Prefix) MarshalBinary() ([]byte, error)MarshalText method #
MarshalText implements the [encoding.TextMarshaler] interface, The encoding is the same as returned by [Addr.String], with one exception: If ip is the zero [Addr], the encoding is the empty string.
func (ip Addr) MarshalText() ([]byte, error)MarshalText method #
MarshalText implements the [encoding.TextMarshaler] interface, The encoding is the same as returned by [Prefix.String], with one exception: If p is the zero value, the encoding is the empty string.
func (p Prefix) MarshalText() ([]byte, error)MarshalText method #
MarshalText implements the [encoding.TextMarshaler] interface. The encoding is the same as returned by [AddrPort.String], with one exception: if p.Addr() is the zero [Addr], the encoding is the empty string.
func (p AddrPort) MarshalText() ([]byte, error)Masked method #
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].
func (p Prefix) Masked() PrefixMustParseAddr function #
MustParseAddr calls [ParseAddr](s) and panics on error. It is intended for use in tests with hard-coded strings.
func MustParseAddr(s string) AddrMustParseAddrPort function #
MustParseAddrPort calls [ParseAddrPort](s) and panics on error. It is intended for use in tests with hard-coded strings.
func MustParseAddrPort(s string) AddrPortMustParsePrefix function #
MustParsePrefix calls [ParsePrefix](s) and panics on error. It is intended for use in tests with hard-coded strings.
func MustParsePrefix(s string) PrefixNext method #
Next returns the address following ip. If there is none, it returns the zero [Addr].
func (ip Addr) Next() AddrOverlaps method #
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.
func (p Prefix) Overlaps(o Prefix) boolParseAddr function #
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").
func ParseAddr(s string) (Addr, error)ParseAddrPort function #
ParseAddrPort parses s as an [AddrPort]. It doesn't do any name resolution: both the address and the port must be numeric.
func ParseAddrPort(s string) (AddrPort, error)ParsePrefix function #
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.
func ParsePrefix(s string) (Prefix, error)Port method #
Port returns p's port.
func (p AddrPort) Port() uint16Prefix method #
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.
func (ip Addr) Prefix(b int) (Prefix, error)PrefixFrom function #
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.
func PrefixFrom(ip Addr, bits int) PrefixPrev method #
Prev returns the IP before ip. If there is none, it returns the IP zero value.
func (ip Addr) Prev() AddrString method #
func (p AddrPort) String() stringString method #
String returns the CIDR notation of p: "
func (p Prefix) String() stringString method #
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 [Addr.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.
func (ip Addr) String() stringStringExpanded method #
StringExpanded is like [Addr.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".
func (ip Addr) StringExpanded() stringUnmap method #
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.
func (ip Addr) Unmap() AddrUnmarshalBinary method #
UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface. It expects data in the form generated by MarshalBinary.
func (ip *Addr) UnmarshalBinary(b []byte) errorUnmarshalBinary method #
UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface. It expects data in the form generated by [AddrPort.MarshalBinary].
func (p *AddrPort) UnmarshalBinary(b []byte) errorUnmarshalBinary method #
UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface. It expects data in the form generated by [Prefix.MarshalBinary].
func (p *Prefix) UnmarshalBinary(b []byte) errorUnmarshalText method #
UnmarshalText implements the encoding.TextUnmarshaler interface. The IP address is expected in a form accepted by [ParsePrefix] or generated by [Prefix.MarshalText].
func (p *Prefix) UnmarshalText(text []byte) errorUnmarshalText method #
UnmarshalText implements the encoding.TextUnmarshaler interface. The [AddrPort] is expected in a form generated by [AddrPort.MarshalText] or accepted by [ParseAddrPort].
func (p *AddrPort) UnmarshalText(text []byte) errorUnmarshalText method #
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.
func (ip *Addr) UnmarshalText(text []byte) errorWithZone method #
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.
func (ip Addr) WithZone(zone string) AddrZone method #
Zone returns ip's IPv6 scoped addressing zone, if any.
func (ip Addr) Zone() stringaddOne method #
addOne returns u + 1.
func (u uint128) addOne() uint128and method #
and returns the bitwise AND of u and m (u&m).
func (u uint128) and(m uint128) uint128appendDecimal function #
appendDecimal appends the decimal string representation of x to b.
func appendDecimal(b []byte, x uint8) []byteappendHex function #
appendHex appends the hex string representation of x to b.
func appendHex(b []byte, x uint16) []byteappendHexPad function #
appendHexPad appends the fully padded hex string representation of x to b.
func appendHexPad(b []byte, x uint16) []byteappendTo4 method #
func (ip Addr) appendTo4(ret []byte) []byteappendTo4In6 method #
func (ip Addr) appendTo4In6(ret []byte) []byteappendTo6 method #
func (ip Addr) appendTo6(ret []byte) []bytebitsClearedFrom method #
bitsClearedFrom returns a copy of u with the given bit and all subsequent ones cleared.
func (u uint128) bitsClearedFrom(bit uint8) uint128bitsSetFrom method #
bitsSetFrom returns a copy of u with the given bit and all subsequent ones set.
func (u uint128) bitsSetFrom(bit uint8) uint128compare method #
compare returns an integer comparing two prefixes. The result will be 0 if p == p2, -1 if p < p2, and +1 if p > p2. Prefixes sort first by validity (invalid before valid), then address family (IPv4 before IPv6), then prefix length, then address. Unexported for Go 1.22 because we may want to compare by p.Addr first. See post-acceptance discussion on go.dev/issue/61642.
func (p Prefix) compare(p2 Prefix) inthalves method #
halves returns the two uint64 halves of the uint128. Logically, think of it as returning two uint64s. It only returns pointers for inlining reasons on 32-bit platforms.
func (u *uint128) halves() [2]*uint64hasZone method #
hasZone reports whether ip has an IPv6 zone.
func (ip Addr) hasZone() boolisZero method #
isZero reports whether u == 0. It's faster than u == (uint128{}) because the compiler (as of Go 1.15/1.16b1) doesn't do this trick and instead inserts a branch in its eq alg's generated code.
func (u uint128) isZero() boolisZero method #
isZero reports whether ip is the zero value of the IP type. The zero value is not a valid IP address of any type. Note that "0.0.0.0" and "::" are not the zero value. Use IsUnspecified to check for these values instead.
func (ip Addr) isZero() boolisZero method #
func (p Prefix) isZero() boolmarshalBinarySize method #
func (ip Addr) marshalBinarySize() intmask6 function #
mask6 returns a uint128 bitmask with the topmost n bits of a 128-bit number.
func mask6(n int) uint128not method #
not returns the bitwise NOT of u.
func (u uint128) not() uint128or method #
or returns the bitwise OR of u and m (u|m).
func (u uint128) or(m uint128) uint128parseIPv4 function #
parseIPv4 parses s as an IPv4 address (in form "192.168.0.1").
func parseIPv4(s string) (ip Addr, err error)parseIPv4Fields function #
func parseIPv4Fields(in string, off int, end int, fields []uint8) errorparseIPv6 function #
parseIPv6 parses s as an IPv6 address (in form "2001:db8::68").
func parseIPv6(in string) (Addr, error)splitAddrPort function #
splitAddrPort splits s into an IP address string and a port string. It splits strings shaped like "foo:bar" or "[foo]:bar", without further validating the substrings. v6 indicates whether the ip string should parse as an IPv6 address or an IPv4 address, in order for s to be a valid ip:port string.
func splitAddrPort(s string) (ip string, port string, v6 bool, err error)string4 method #
func (ip Addr) string4() stringstring4In6 method #
func (ip Addr) string4In6() stringstring6 method #
string6 formats ip in IPv6 textual representation. It follows the guidelines in section 4 of RFC 5952 (https://tools.ietf.org/html/rfc5952#section-4): no unnecessary zeros, use :: to elide the longest run of zeros, and don't use :: to compact a single zero field.
func (ip Addr) string6() stringsubOne method #
subOne returns u - 1.
func (u uint128) subOne() uint128v4 method #
v4 returns the i'th byte of ip. If ip is not an IPv4, v4 returns unspecified garbage.
func (ip Addr) v4(i uint8) uint8v6 method #
v6 returns the i'th byte of ip. If ip is an IPv4 address, this accesses the IPv4-mapped IPv6 address form of the IP.
func (ip Addr) v6(i uint8) uint8v6u16 method #
v6u16 returns the i'th 16-bit word of ip. If ip is an IPv4 address, this accesses the IPv4-mapped IPv6 address form of the IP.
func (ip Addr) v6u16(i uint8) uint16withoutZone method #
withoutZone unconditionally strips the zone from ip. It's similar to WithZone, but small enough to be inlinable.
func (ip Addr) withoutZone() Addrxor method #
xor returns the bitwise XOR of u and m (u^m).
func (u uint128) xor(m uint128) uint128Generated with Arrow