netip

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 26, 2026 License: BSD-3-Clause Imports: 8 Imported by: 0

Documentation

Overview

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).

Index

Constants

View Source 
const (
	MaxZoneLen     = 10 // 4294967295
	MaxAddr4Len    = 15 // 255.255.255.255
	MaxAddr4In6Len = 29 // ::ffff:255.255.255.255%enp5s0
	MaxAddr6Len    = 46 // ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0
	MaxAddrLen     = MaxAddr6Len
)

Maximum length of an IP address string.

View Source 
const (
	MaxPortLen         = 5                                   // 65535
	MaxAddrPort4Len    = MaxAddr4Len + 1 + MaxPortLen        // ip:port
	MaxAddrPort4In6Len = MaxAddr4In6Len + 2 + 1 + MaxPortLen // [ip]:port
	MaxAddrPort6Len    = MaxAddr6Len + 2 + 1 + MaxPortLen    // [ip]:port
	MaxAddrPortLen     = MaxAddrPort6Len
)

Maximum length of an ip:port string.

View Source 
const (
	MaxPrefix4Len = MaxAddr4Len + 1 + 2 // ip/32
	MaxPrefix6Len = MaxAddr6Len + 1 + 3 // ip/128
	MaxPrefixLen  = MaxPrefix6Len
)

Maximum length of a prefix string.

Variables

View Source 
var ErrIP = errors.New("netip: invalid IP address")
View Source 
var ErrIPPort = errors.New("netip: invalid ip-port")
View Source 
var ErrIPv4 = errors.New("netip: invalid IPv4 address")
View Source 
var ErrIPv6 = errors.New("netip: invalid IPv6 address")
View Source 
var ErrLargePrefix = errors.New("netip: prefix length too large for IP type")
View Source 
var ErrNegativePrefix = errors.New("netip: negative Prefix bits")
View Source 
var ErrPort = errors.New("netip: invalid port")
View Source 
var ErrPrefix = errors.New("netip: invalid prefix")

Functions

This section is empty.

Types

type Addr 

type Addr struct {
	// contains filtered or unexported fields
}

Addr represents an IPv4 or IPv6 address (with or without a scoped addressing zone).

The zero Addr is not a valid IP address. Addr{} is distinct from both 0.0.0.0 and ::.

func AddrFrom4 

func AddrFrom4(addr [4]byte) Addr

AddrFrom4 returns the address of the IPv4 address given by the bytes in addr.

func AddrFrom16 

func AddrFrom16(addr [16]byte) Addr

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 AddrFromSlice 

func AddrFromSlice(slice []byte) Addr

AddrFromSlice parses the 4- or 16-byte byte slice as an IPv4 or IPv6 address. If slice's length is not 4 or 16, returns a zero Addr.

func IPv4Unspecified 

func IPv4Unspecified() Addr

IPv4Unspecified returns the IPv4 unspecified address "0.0.0.0".

func IPv6LinkLocalAllNodes 

func IPv6LinkLocalAllNodes() Addr

IPv6LinkLocalAllNodes returns the IPv6 link-local all nodes multicast address ff02::1.

func IPv6LinkLocalAllRouters 

func IPv6LinkLocalAllRouters() Addr

IPv6LinkLocalAllRouters returns the IPv6 link-local all routers multicast address ff02::2.

func IPv6Loopback 

func IPv6Loopback() Addr

IPv6Loopback returns the IPv6 loopback address ::1.

func IPv6Unspecified 

func IPv6Unspecified() Addr

IPv6Unspecified returns the IPv6 unspecified address "::".

func MustParseAddr 

func MustParseAddr(s string) Addr

MustParseAddr calls ParseAddr(s) and panics on error. It is intended for use in tests with hard-coded strings.

func ParseAddr 

func ParseAddr(s string) (Addr, error)

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 (Addr) AppendText 

func (ip Addr) AppendText(b []byte) ([]byte, error)

AppendText implements the encoding.TextAppender interface. Requires at least MaxAddrLen bytes of spare capacity in b. Always returns a nil error.

func (Addr) As4 

func (ip Addr) As4(a4 [4]byte) [4]byte

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 (Addr) As16 

func (ip Addr) As16(a16 [16]byte) [16]byte

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 (Addr) AsSlice 

func (ip Addr) AsSlice(b []byte) []byte

AsSlice returns an IPv4 or IPv6 address in its respective 4-byte or 16-byte representation.

func (Addr) BitLen 

func (ip Addr) BitLen() int

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 (Addr) Compare 

func (ip Addr) Compare(ip2 Addr) int

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 (Addr) Equal 

func (ip Addr) Equal(ip2 Addr) bool

Equal reports whether ip and ip2 are the same IP address.

func (Addr) Is4 

func (ip Addr) Is4() bool

Is4 reports whether ip is an IPv4 address.

It returns false for IPv4-mapped IPv6 addresses. See Addr.Unmap.

func (Addr) Is4In6 

func (ip Addr) Is4In6() bool

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 (Addr) Is6 

func (ip Addr) Is6() bool

Is6 reports whether ip is an IPv6 address, including IPv4-mapped IPv6 addresses.

func (Addr) IsGlobalUnicast 

func (ip Addr) IsGlobalUnicast() bool

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 (Addr) IsInterfaceLocalMulticast 

func (ip Addr) IsInterfaceLocalMulticast() bool

IsInterfaceLocalMulticast reports whether ip is an IPv6 interface-local multicast address.

func (Addr) IsLinkLocalMulticast 

func (ip Addr) IsLinkLocalMulticast() bool

IsLinkLocalMulticast reports whether ip is a link-local multicast address.

func (Addr) IsLinkLocalUnicast 

func (ip Addr) IsLinkLocalUnicast() bool

IsLinkLocalUnicast reports whether ip is a link-local unicast address.

func (Addr) IsLoopback 

func (ip Addr) IsLoopback() bool

IsLoopback reports whether ip is a loopback address.

func (Addr) IsMulticast 

func (ip Addr) IsMulticast() bool

IsMulticast reports whether ip is a multicast address.

func (Addr) IsPrivate 

func (ip Addr) IsPrivate() bool

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.

func (Addr) IsUnspecified 

func (ip Addr) IsUnspecified() bool

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 (Addr) IsValid 

func (ip Addr) IsValid() bool

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 (Addr) Less 

func (ip Addr) Less(ip2 Addr) bool

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 (Addr) Next 

func (ip Addr) Next() Addr

Next returns the address following ip. If there is none, it returns the zero Addr.

func (Addr) Prefix 

func (ip Addr) Prefix(b int) (Prefix, error)

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 (Addr) Prev 

func (ip Addr) Prev() Addr

Prev returns the IP before ip. If there is none, it returns the IP zero value.

func (Addr) String 

func (ip Addr) String(buf []byte) string

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.

buf length must be at least MaxAddr4Len for IPv4 addresses and MaxAddr6Len for IPv6 addresses.

func (Addr) Unmap 

func (ip Addr) Unmap() Addr

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 (Addr) WithZone 

func (ip Addr) WithZone(zone string) Addr

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 (Addr) Zone 

func (ip Addr) Zone(buf []byte) string

Zone returns ip's IPv6 scoped addressing zone, if any. buf length must be at least MaxZoneLen.

type AddrPort 

type AddrPort struct {
	// contains filtered or unexported fields
}

AddrPort is an IP and a port number.

func AddrPortFrom 

func AddrPortFrom(ip Addr, port uint16) AddrPort

AddrPortFrom returns an AddrPort with the provided IP and port. It does not allocate.

func MustParseAddrPort 

func MustParseAddrPort(s string) AddrPort

MustParseAddrPort calls ParseAddrPort(s) and panics on error. It is intended for use in tests with hard-coded strings.

func ParseAddrPort 

func ParseAddrPort(s string) (AddrPort, error)

ParseAddrPort parses s as an AddrPort.

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

func (AddrPort) Addr 

func (p AddrPort) Addr() Addr

Addr returns p's IP address.

func (AddrPort) AppendText 

func (p AddrPort) AppendText(b []byte) ([]byte, error)

AppendText implements the encoding.TextAppender interface. Requires at least MaxAddrPortLen bytes of spare capacity in b.

func (AddrPort) Compare 

func (p AddrPort) Compare(p2 AddrPort) int

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 (AddrPort) IsValid 

func (p AddrPort) IsValid() bool

IsValid reports whether p.Addr() is valid. All ports are valid, including zero.

func (AddrPort) Port 

func (p AddrPort) Port() uint16

Port returns p's port.

func (AddrPort) String 

func (p AddrPort) String(buf []byte) string

String returns a string representation of p. buf length must be at least MaxAddrPortLen.

type Prefix 

type Prefix struct {
	// contains filtered or unexported fields
}

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.

func MustParsePrefix 

func MustParsePrefix(s string) Prefix

MustParsePrefix calls ParsePrefix(s) and panics on error. It is intended for use in tests with hard-coded strings.

func ParsePrefix 

func ParsePrefix(s string) (Prefix, error)

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 PrefixFrom 

func PrefixFrom(ip Addr, bits int) Prefix

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 (Prefix) Addr 

func (p Prefix) Addr() Addr

Addr returns p's IP address.

func (Prefix) AppendText 

func (p Prefix) AppendText(b []byte) ([]byte, error)

AppendText implements the encoding.TextAppender interface. Requires at least MaxPrefixLen bytes of spare capacity in b.

func (Prefix) Bits 

func (p Prefix) Bits() int

Bits returns p's prefix length.

It reports -1 if invalid.

func (Prefix) Compare 

func (p Prefix) Compare(p2 Prefix) int

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 masked prefix address, then prefix length, then unmasked address.

func (Prefix) Contains 

func (p Prefix) Contains(ip Addr) bool

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 (Prefix) Equal 

func (p Prefix) Equal(p2 Prefix) bool

Equal reports whether p and p2 are the same prefix.

func (Prefix) IsSingleIP 

func (p Prefix) IsSingleIP() bool

IsSingleIP reports whether p contains exactly one IP.

func (Prefix) IsValid 

func (p Prefix) IsValid() bool

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 (Prefix) Masked 

func (p Prefix) Masked() Prefix

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 (Prefix) Overlaps 

func (p Prefix) Overlaps(o Prefix) bool

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 (Prefix) String 

func (p Prefix) String(buf []byte) string

String returns the CIDR notation of p: "<ip>/<bits>". buf length must be at least MaxPrefixLen.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.