ipaddr

package
v1.5.5 Latest Latest
Warning

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

 Go to latest Published: Sep 22, 2023 License: Apache-2.0, Apache-2.0 Imports: 21 Imported by: 21

Documentation

Overview

IPAddress is a library for handling IP addresses and subnets, both IPv4 and IPv6.

Benefits of this Library

The primary goals are:

  • Parse all IPv4 and IPv6 address formats and host name formats in common usage, plus some additional formats.
  • Parse and represent subnets, either those specified by network prefix length or those specified with ranges of segment values.
  • Allow the separation of address parsing from host parsing.
  • Allow control over which formats are allowed when parsing, whether IPv4, IPv6, subnet formats, inet_aton formats, or other.
  • Produce all common address strings of different formats for a given IPv4 or IPv6 address and produce collections of such strings.
  • Parse all common MAC Address formats in usage and produce all common MAC address strings of different formats.
  • Integrate MAC addresses with IPv6 with standard conversions.
  • Integrate IPv4 Addresses with IPv6 through common address conversions.
  • Polymorphism is a key goal. The library maintains an address framework of interfaces that allow most library functionality to be independent of address type or version, whether IPv4, IPv6 or MAC. This allows for code which supports both IPv4 and IPv6 transparently.
  • Thread-safety and immutability. The core types (host names, address strings, addresses, address sections, address segments, address ranges) are all immutable. They do not change their underlying value. For sharing amongst goroutines this is valuable.
  • Modify addresses, such as altering prefix lengths, masking, splitting into sections and segments, splitting into network and host sections, reconstituting from sections and segments.
  • Provide address operations and subnetting, such as obtaining the prefix block subnet for a prefixed address, iterating through subnets, iterating through prefixes, prefix blocks, or segment blocks of subnets, incrementing and decrementing addresses by integer values, reversing address bits for endianness or DNS lookup, set-subtracting subnets from other subnets, subnetting, intersections of subnets, merging subnets, checking containment of addresses in subnets, listing subnets covering a span of addresses.
  • Sorting and comparison of host names, addresses, address strings and subnets. All the address component types are compararable.
  • Integrate with the Go language primitive types and the standard library types net.IP, net.IPAddr, net.IPMask, net.IPNet, net.TCPAddr, net.UDPAddr, net/netip.Addr, net/netip.Prefix, net/netip.AddrPort, and math/big.Int.
  • Make address manipulations easy, so you do not have to worry about longs/ints/shorts/bytes/bits, signed/unsigned, sign extension, ipv4/v6, masking, iterating, and other implementation details.

Design Overview

The core types are IPAddressString, HostName, and MACAddressString along with the Address base type and its associated types IPAddress, IPv4Address, IPv6Address, and MACAddress, as well as the sequential address type SequentialRange. If you have a textual representation of an IP address, then start with IPAddressString or HostName. If you have a textual representation of a MAC address, then start with MACAddressString. Note that address instances can represent either a single address or a subnet. If you have either an address or host name, or you have something with a port or service name, then use HostName. If you have numeric bytes or integers, then start with IPv4Address, IPv6Address, IPAddress, or MACAddress.

This library allows you to scale down from more specific address types to more generic address types, and then to scale back up again. The polymorphism is useful for IP-version ambiguous code. The most-specific types allow for method sets tailored to the address version or type. You can only scale up to a specific version or address type if the lower level instance was originally derived from an instance of the specific type. So, for instance, an IPv6Address can be converted to an IPAddress using IPv6Address.ToIP, or to an Address using IPv6Address.ToAddressBase, which can then be converted back to IPAddress or an IPv6Address using Address.ToIP or Address.ToIPv6. But that IPv6Address cannot be scaled back to IPv4. If you wish to convert that IPv6Address to IPv4, you would need to use an implementation of IPv4AddressConverter.

This library has similarities in design to the Java IPAddress library. Notable divergences derive from the differences between the Java and Go languages, such as the differences in error handling and the lack of inheritance in Go, amongst many other differences. Other divergences derive from common Go language idioms and practices which differ from standard Java idioms and practices.

Code Examples

For common use-cases, you may wish to go straight to the wiki code examples which cover a wide breadth of common use-cases.

Further Documentation

You can read further documentation with more depth.

Index

Constants

View Source 
const (
	HexPrefix                    = "0x"
	OctalPrefix                  = "0"
	BinaryPrefix                 = "0b"
	RangeSeparator               = '-'
	RangeSeparatorStr            = "-"
	AlternativeRangeSeparator    = '\u00bb'
	AlternativeRangeSeparatorStr = "\u00bb" // '»'

	ExtendedDigitsRangeSeparatorStr = AlternativeRangeSeparatorStr

	SegmentWildcard    = '*'
	SegmentWildcardStr = "*"

	SegmentSqlWildcard          = '%'
	SegmentSqlWildcardStr       = "%"
	SegmentSqlSingleWildcard    = '_'
	SegmentSqlSingleWildcardStr = "_"
)
View Source 
const (
	PortSeparator    = ':'
	LabelSeparator   = '.'
	IPv6StartBracket = '['
	IPv6EndBracket   = ']'
)
View Source 
const (
	PrefixLenSeparator    = '/'
	PrefixLenSeparatorStr = "/"
)
View Source 
const (
	IPv4SegmentSeparator    = '.'
	IPv4SegmentSeparatorStr = "."
	IPv4BitsPerSegment      = 8
	IPv4BytesPerSegment     = 1
	IPv4SegmentCount        = 4
	IPv4ByteCount           = 4
	IPv4BitCount            = 32
	IPv4DefaultTextualRadix = 10
	IPv4MaxValuePerSegment  = 0xff
	IPv4MaxValue            = 0xffffffff
	IPv4ReverseDnsSuffix    = ".in-addr.arpa"
	IPv4SegmentMaxChars     = 3
)
View Source 
const (
	IPv6SegmentSeparator            = ':'
	IPv6SegmentSeparatorStr         = ":"
	IPv6ZoneSeparator               = '%'
	IPv6ZoneSeparatorStr            = "%"
	IPv6AlternativeZoneSeparator    = '\u00a7'
	IPv6AlternativeZoneSeparatorStr = "\u00a7" //'§'
	IPv6BitsPerSegment              = 16
	IPv6BytesPerSegment             = 2
	IPv6SegmentCount                = 8
	IPv6MixedReplacedSegmentCount   = 2
	IPv6MixedOriginalSegmentCount   = 6
	IPv6MixedOriginalByteCount      = 12
	IPv6ByteCount                   = 16
	IPv6BitCount                    = 128
	IPv6DefaultTextualRadix         = 16
	IPv6MaxValuePerSegment          = 0xffff
	IPv6ReverseDnsSuffix            = ".ip6.arpa"
	IPv6ReverseDnsSuffixDeprecated  = ".ip6.int"

	IPv6UncSegmentSeparator    = '-'
	IPv6UncSegmentSeparatorStr = "-"
	IPv6UncZoneSeparator       = 's'
	IPv6UncZoneSeparatorStr    = "s"
	IPv6UncRangeSeparator      = AlternativeRangeSeparator
	IPv6UncRangeSeparatorStr   = AlternativeRangeSeparatorStr
	IPv6UncSuffix              = ".ipv6-literal.net"

	IPv6SegmentMaxChars = 4

	IPv6AlternativeRangeSeparatorStr = AlternativeRangeSeparatorStr
)
View Source 
const (
	MACBitsPerSegment           = 8
	MACBytesPerSegment          = 1
	MACDefaultTextualRadix      = 16
	MACMaxValuePerSegment       = 0xff
	MACMaxValuePerDottedSegment = 0xffff

	MediaAccessControlSegmentCount         = 6
	MediaAccessControlDottedSegmentCount   = 3
	MediaAccessControlDotted64SegmentCount = 4
	ExtendedUniqueIdentifier48SegmentCount = MediaAccessControlSegmentCount
	ExtendedUniqueIdentifier64SegmentCount = 8

	MACOrganizationalUniqueIdentifierSegmentCount = 3

	MACSegmentMaxChars = 2

	MACDashSegmentSeparator   = '-'
	MACColonSegmentSeparator  = ':'
	MacSpaceSegmentSeparator  = ' '
	MacDottedSegmentSeparator = '.'

	MacDashedSegmentRangeSeparator    = '|'
	MacDashedSegmentRangeSeparatorStr = "|"
)
View Source 
const (
	SmtpIPv6Identifier = "IPv6:"
	IPvFuture          = 'v'
)
View Source 
const DefaultSeqRangeSeparator = " -> "

DefaultSeqRangeSeparator is the low to high value separator used when creating strings for IP ranges.

View Source 
const DivIntSize = 64
View Source 
const NoZone = ""
View Source 
const SegIntSize = 32 // must match the bit count of SegInt
View Source 
const SegmentValueDelimiter = ','

Variables

View Source 
var (
	// CountComparator compares by count first, then by value.
	CountComparator = AddressComparator{countComparator{}}

	// HighValueComparator compares by high value first, then low.
	HighValueComparator = AddressComparator{valueComparator{/* contains filtered or unexported fields */}}

	// LowValueComparator compares by low value first, then high.
	LowValueComparator = AddressComparator{valueComparator{}}

	// ReverseHighValueComparator is like HighValueComparator but when comparing the low value, reverses the comparison.
	ReverseHighValueComparator = AddressComparator{valueComparator{/* contains filtered or unexported fields */}}

	// ReverseLowValueComparator is like LowValueComparator but when comparing the high value, reverses the comparison.
	ReverseLowValueComparator = AddressComparator{valueComparator{/* contains filtered or unexported fields */}}
)
View Source 
var IPv4Network = &IPv4AddressNetwork{ipv4Network}
View Source 
var IPv6LinkLocalPrefix = createLinkLocalPrefix()
View Source 
var IPv6Network = &IPv6AddressNetwork{ipv6Network}

Functions

func AddrsMatchOrdered 

func AddrsMatchOrdered[T, U AddressType](addrs1 []T, addrs2 []U) (result bool)

AddrsMatchOrdered checks if the two slices share the same ordered list of addresses, subnets, or address collections, using address equality. Duplicates and nil addresses are allowed.

func AddrsMatchUnordered 

func AddrsMatchUnordered[T, U AddressType](addrs1 []T, addrs2 []U) (result bool)

AddrsMatchUnordered checks if the two slices share the same list of addresses, subnets, or address collections, in any order, using address equality. The function can handle duplicates and nil addresses.

func AssociativeTreesString added in v1.5.0 

func AssociativeTreesString[T TrieKeyConstraint[T], V any](withNonAddedKeys bool, tries ...*AssociativeTrie[T, V]) string

AssociativeTreesString merges the trie strings (as shown by the TreeString method) of multiple associative tries into a single merged trie string.

func TreesString added in v1.1.0 

func TreesString[T TrieKeyConstraint[T]](withNonAddedKeys bool, tries ...*Trie[T]) string

TreesString merges the tree strings (as shown by the TreeString method) of multiple tries into a single merged tree string.

Types

type AddedTree added in v1.5.0 

type AddedTree[T TrieKeyConstraint[T]] struct {
	// contains filtered or unexported fields
}

AddedTree is an alternative non-binary tree data structure originating from a binary trie in which the nodes of this tree are the "added" nodes of the original trie, with the possible exception of the root, which matches the root node of the original. The root may or may not be an added node from the original trie. This tree is also read-only and is generated from the originating trie, but does not change in concert with changes to the original trie.

func (AddedTree[T]) GetRoot added in v1.5.0 

func (atree AddedTree[T]) GetRoot() AddedTreeNode[T]

GetRoot returns the root of this tree, which corresponds to the root of the originating trie.

func (AddedTree[T]) String added in v1.5.0 

func (atree AddedTree[T]) String() string

String returns a string representation of the tree, which is the same as the string obtained from the AddedNodesTreeString method of the originating trie.

type AddedTreeNode added in v1.5.0 

type AddedTreeNode[T TrieKeyConstraint[T]] struct {
	// contains filtered or unexported fields
}

AddedTreeNode represents a node in an AddedTree

func (AddedTreeNode[T]) GetKey added in v1.5.0 

func (node AddedTreeNode[T]) GetKey() T

GetKey returns the key of this node, which is the same as the key of the corresponding node in the originating trie.

func (AddedTreeNode[T]) GetSubNodes added in v1.5.0 

func (node AddedTreeNode[T]) GetSubNodes() []AddedTreeNode[T]

GetSubNodes returns the sub-nodes of this node, which are not the same as the 0, 1 or 2 direct sub-nodes of the originating binary trie. Instead, these are all the direct or indirect added sub-nodes of the node in the originating trie. If you can traverse from this node to another node in the originating trie, using a sequence of sub-nodes, without any intervening sub-node being an added node, then that other node will appear as a sub-node here.

func (AddedTreeNode[T]) IsAdded added in v1.5.3 

func (node AddedTreeNode[T]) IsAdded() bool

IsAdded returns if the node was an added node in the original trie. This returns true for all nodes except possibly the root, since only added nodes are added to this tree, apart from the root.

func (AddedTreeNode[T]) String added in v1.5.0 

func (node AddedTreeNode[T]) String() string

String returns a visual representation of this node including the key. If this is the root, it will have an open circle if the root is not an added node. Otherwise, the node will have a closed circle.

func (AddedTreeNode[T]) TreeString added in v1.5.0 

func (node AddedTreeNode[T]) TreeString() string

TreeString returns a visual representation of the sub-tree originating from this node, with one node per line.

type Address 

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

Address represents a single address, or a collection of multiple addresses, such as with an IP subnet or a set of MAC addresses.

Addresses consist of a sequence of segments, each of equal bit-size. The number of such segments and the bit-size are determined by the underlying version or type of the address, whether IPv4, IPv6, MAC, or other. Each segment can represent a single value or a sequential range of values. Addresses can also have an associated prefix length, which is the number of consecutive bits comprising the prefix, the most significant bits of an address.

To construct one from a string, use NewIPAddressString or NewMACAddressString, then use the ToAddress or GetAddress methods to get an IPAddress or MACAddress, and then you can convert to this type using the ToAddressBase method.

Any given specific address types can be converted to Address with the ToAddressBase method, and then back again to their original types with methods like ToIPv6, ToIP, ToIPv4, and ToMAC. When calling such a method on a given address, if the address was not originally constructed as the type returned from the method, then the method will return nil. Conversion methods work with nil pointers (returning nil) so that they can be chained together safely.

This allows for polymorphic code that works with all addresses, such as with the address trie code in this library, while still allowing for methods and code specific to each address version or type.

You can also use the methods IsIPv6, IsIP, IsIPv4, and IsMAC, which will return true if and only if the corresponding method ToIPv6, ToIP, ToIPv4, and ToMAC returns non-nil, respectively.

The zero value for an Address is an address with no segments and no associated address version or type, also known as the adaptive zero.

func (*Address) AdjustPrefixLen 

func (addr *Address) AdjustPrefixLen(prefixLen BitCount) *Address

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*Address) AdjustPrefixLenZeroed 

func (addr *Address) AdjustPrefixLenZeroed(prefixLen BitCount) (*Address, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

For example, "1.2.0.0/16" adjusted by -8 becomes "1.0.0.0/8". "1.2.0.0/16" adjusted by 8 becomes "1.2.0.0/24".

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*Address) AssignMinPrefixForBlock 

func (addr *Address) AssignMinPrefixForBlock() *Address

AssignMinPrefixForBlock returns an equivalent subnet, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this subnet.

In other words, this method assigns a prefix length to this subnet matching the largest prefix block in this subnet.

Examples:

  • 1.2.3.4 returns 1.2.3.4/32
  • 1.2.*.* returns 1.2.0.0/16
  • 1.2.*.0/24 returns 1.2.0.0/16
  • 1.2.*.4 returns 1.2.*.4/32
  • 1.2.0-1.* returns 1.2.0.0/23
  • 1.2.1-2.* returns 1.2.1-2.0/24
  • 1.2.252-255.* returns 1.2.252.0/22
  • 1.2.3.4/16 returns 1.2.3.4/32

func (*Address) AssignPrefixForSingleBlock 

func (addr *Address) AssignPrefixForSingleBlock() *Address

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address - it is required that the range of values match the range of a prefix block. If there is no such address, then nil is returned.

Examples:

  • 1.2.3.4 returns 1.2.3.4/32
  • 1.2.*.* returns 1.2.0.0/16
  • 1.2.*.0/24 returns 1.2.0.0/16
  • 1.2.*.4 returns nil
  • 1.2.0-1.* returns 1.2.0.0/23
  • 1.2.1-2.* returns nil
  • 1.2.252-255.* returns 1.2.252.0/22
  • 1.2.3.4/16 returns 1.2.3.4/32

func (*Address) BlockIterator 

func (addr *Address) BlockIterator(segmentCount int) Iterator[*Address]

BlockIterator iterates through the addresses that can be obtained by iterating through all the upper segments up to the given segment count. The segments following remain the same in all iterated addresses.

For instance, given the IPv4 subnet "1-2.3-4.5-6.7" and the count argument 2, BlockIterator will iterate through "1.3.5-6.7", "1.4.5-6.7", "2.3.5-6.7" and "2.4.5-6.7".

func (*Address) Bytes 

func (addr *Address) Bytes() []byte

Bytes returns the lowest address in this subnet or address collection as a byte slice.

func (*Address) Compare 

func (addr *Address) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address or subnet is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*Address) CompareSize 

func (addr *Address) CompareSize(other AddressItem) int

CompareSize compares the counts of two subnets or addresses or other address items, the number of individual items within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one subnet or collection represents more individual items than another.

CompareSize returns a positive integer if this address or subnet has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*Address) Contains 

func (addr *Address) Contains(other AddressType) bool

Contains returns whether this is the same type and version as the given address or subnet and whether it contains all addresses in the given address or subnet.

func (*Address) ContainsPrefixBlock 

func (addr *Address) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or subnet contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*Address) ContainsSinglePrefixBlock 

func (addr *Address) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*Address) CopyBytes 

func (addr *Address) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address in the subnet into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*Address) CopySegments 

func (addr *Address) CopySegments(segs []*AddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*Address) CopySubSegments 

func (addr *Address) CopySubSegments(start, end int, segs []*AddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*Address) CopyUpperBytes 

func (addr *Address) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address in the subnet into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*Address) Equal 

func (addr *Address) Equal(other AddressType) bool

Equal returns whether the given address or subnet is equal to this address or subnet. Two address instances are equal if they represent the same set of addresses.

func (*Address) ForEachSegment added in v1.2.0 

func (addr *Address) ForEachSegment(consumer func(segmentIndex int, segment *AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (Address) Format 

func (addr Address) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*Address) GetBitCount 

func (addr *Address) GetBitCount() BitCount

GetBitCount returns the number of bits comprising this address, or each address in the range if a subnet.

func (*Address) GetBitsPerSegment 

func (addr *Address) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this address or subnet. Segments in the same address are equal length.

func (*Address) GetBlockCount 

func (addr *Address) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*Address) GetByteCount 

func (addr *Address) GetByteCount() int

GetByteCount returns the number of bytes required for this address, or each address in the range if a subnet.

func (*Address) GetBytesPerSegment 

func (addr *Address) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this address or subnet. Segments in the same address are equal length.

func (*Address) GetCount 

func (addr *Address) GetCount() *big.Int

GetCount returns the count of addresses that this address or subnet represents.

If just a single address, not a collection nor subnet of multiple addresses, returns 1.

For instance, the IP address subnet "2001:db8::/64" has the count of 2 to the power of 64.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*Address) GetDivisionCount 

func (addr *Address) GetDivisionCount() int

GetDivisionCount returns the division count, which is the same as the segment count, since the divisions of an address are the segments.

func (*Address) GetGenericDivision 

func (addr *Address) GetGenericDivision(index int) DivisionType

GetGenericDivision returns the segment at the given index as a DivisionType. The first segment is at index 0. GetGenericDivision will panic given a negative index or index larger than the division count.

func (*Address) GetGenericSegment 

func (addr *Address) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (*Address) GetLeadingBitCount added in v1.1.0 

func (addr *Address) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower address of the range if this is a subnet representing multiple values.

func (*Address) GetLower 

func (addr *Address) GetLower() *Address

GetLower returns the address in the subnet or address collection with the lowest numeric value, which will be the receiver if it represents a single address. For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned.

func (*Address) GetMaxSegmentValue 

func (addr *Address) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*Address) GetMinPrefixLenForBlock 

func (addr *Address) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

func (*Address) GetPrefixCount 

func (addr *Address) GetPrefixCount() *big.Int

GetPrefixCount returns the count of prefixes in this address or subnet.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the count of the range of values in the prefix.

If this has a nil prefix length, returns the same value as GetCount.

func (*Address) GetPrefixCountLen 

func (addr *Address) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the count of prefixes in this address or subnet for the given prefix length.

If not a subnet of multiple addresses, or a subnet with just single prefix of the given length, returns 1.

func (*Address) GetPrefixLen 

func (addr *Address) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part (most significant bits) of the address that comprise the prefix.

A prefix is a part of the address that is not specific to that address but common amongst a group of addresses, such as a CIDR prefix block subnet.

For IP addresses, the prefix is explicitly defined when the address is created. For example, "1.2.0.0/16" has a prefix length of 16, while "1.2.*.*" has no prefix length, even though they both represent the same set of addresses and are considered equal. Prefixes can be considered variable for a given IP address and can depend on routing.

The methods GetMinPrefixLenForBlock and GetPrefixLenForSingleBlock can help you to obtain or define a prefix length if one does not exist already. The method ToPrefixBlockLen allows you to create the subnet consisting of the block of addresses for any given prefix length.

For MAC addresses, the prefix is initially inferred from the range, so "1:2:3:*:*:*" has a prefix length of 24. MAC addresses derived from an address with a prefix length may retain the prefix length regardless of their own range of values.

func (*Address) GetPrefixLenForSingleBlock 

func (addr *Address) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address subnet matches exactly the block of addresses for that prefix.

If the range can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix exists, returns nil.

If this segment grouping represents a single value, returns the bit length of this address.

IP address examples:

  • 1.2.3.4 returns 32
  • 1.2.3.4/16 returns 32
  • 1.2.*.* returns 16
  • 1.2.*.0/24 returns 16
  • 1.2.0.0/16 returns 16
  • 1.2.*.4 returns nil
  • 1.2.252-255.* returns 22

func (*Address) GetSection 

func (addr *Address) GetSection() *AddressSection

GetSection returns the backing section for this address or subnet, comprising all segments.

func (*Address) GetSegment 

func (addr *Address) GetSegment(index int) *AddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (*Address) GetSegmentCount 

func (addr *Address) GetSegmentCount() int

GetSegmentCount returns the segment count, the number of segments in this address. For example, IPv4 addresses have 4, IPv6 addresses have 8.

func (*Address) GetSegmentStrings 

func (addr *Address) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*Address) GetSegments 

func (addr *Address) GetSegments() []*AddressSegment

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*Address) GetSequentialBlockCount 

func (addr *Address) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential subnets that comprise this subnet.

func (*Address) GetSequentialBlockIndex 

func (addr *Address) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full subnet to be sequential, the preceding segments must be single-valued.

func (*Address) GetSubSection 

func (addr *Address) GetSubSection(index, endIndex int) *AddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*Address) GetTrailingBitCount added in v1.1.0 

func (addr *Address) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies to the lower value of the range if this is a subnet representing multiple values.

func (*Address) GetTrailingSection 

func (addr *Address) GetTrailingSection(index int) *AddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*Address) GetUpper 

func (addr *Address) GetUpper() *Address

GetUpper returns the address in the subnet or address collection with the highest numeric value, which will be the receiver if it represents a single address. For example, for the subnet "1.2-3.4.5-6", the address "1.3.4.6" is returned.

func (*Address) GetUpperValue 

func (addr *Address) GetUpperValue() *big.Int

GetUpperValue returns the highest address in this subnet or address collection as an integer value.

func (*Address) GetValue 

func (addr *Address) GetValue() *big.Int

GetValue returns the lowest address in this subnet or address collection as an integer value.

func (*Address) IncludesMax 

func (addr *Address) IncludesMax() bool

IncludesMax returns whether this address includes the max address, the address whose bits are all ones, within its range.

func (*Address) IncludesZero 

func (addr *Address) IncludesZero() bool

IncludesZero returns whether this address includes the zero address within its range.

func (*Address) Increment 

func (addr *Address) Increment(increment int64) *Address

Increment returns the address from the subnet that is the given increment upwards into the subnet range, with the increment of 0 returning the first address in the range.

If the increment i matches or exceeds the subnet size count c, then i - c + 1 is added to the upper address of the range. An increment matching the subnet count gives you the address just above the highest address in the subnet.

If the increment is negative, it is added to the lower address of the range. To get the address just below the lowest address of the subnet, use the increment -1.

If this is just a single address value, the address is simply incremented by the given increment, positive or negative.

If this is a subnet with multiple values, a positive increment i is equivalent i + 1 values from the subnet iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the subnet count is equivalent to the same number of iterator values preceding the upper bound of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On address overflow or underflow, Increment returns nil.

func (*Address) IncrementBoundary 

func (addr *Address) IncrementBoundary(increment int64) *Address

IncrementBoundary returns the address that is the given increment from the range boundaries of this subnet or address collection.

If the given increment is positive, adds the value to the upper address (GetUpper) in the range to produce a new address. If the given increment is negative, adds the value to the lower address (GetLower) in the range to produce a new address. If the increment is zero, returns this address.

If this is a single address value, that address is simply incremented by the given increment value, positive or negative.

On address overflow or underflow, IncrementBoundary returns nil.

func (*Address) IsFullRange 

func (addr *Address) IsFullRange() bool

IsFullRange returns whether this address covers the entire address space of this address version or type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*Address) IsIP 

func (addr *Address) IsIP() bool

IsIP returns true if this address or subnet originated as an IPv4 or IPv6 address or subnet, or an implicitly zero-valued IP. If so, use ToIP to convert back to the IP-specific type.

func (*Address) IsIPv4 

func (addr *Address) IsIPv4() bool

IsIPv4 returns true if this address or subnet originated as an IPv4 address or subnet. If so, use ToIPv4 to convert back to the IPv4-specific type.

func (*Address) IsIPv6 

func (addr *Address) IsIPv6() bool

IsIPv6 returns true if this address or subnet originated as an IPv6 address or subnet. If so, use ToIPv6 to convert back to the IPv6-specific type.

func (*Address) IsLocal 

func (addr *Address) IsLocal() bool

IsLocal returns whether the address can be considered a local address (as opposed to a global one).

func (*Address) IsMAC 

func (addr *Address) IsMAC() bool

IsMAC returns true if this address or address collection originated as a MAC address or address collection. If so, use ToMAC to convert back to the MAC-specific type.

func (*Address) IsMax 

func (addr *Address) IsMax() bool

IsMax returns whether this address matches exactly the maximum possible value, the address whose bits are all ones.

func (*Address) IsMulticast 

func (addr *Address) IsMulticast() bool

IsMulticast returns whether this address is multicast.

func (*Address) IsMultiple 

func (addr *Address) IsMultiple() bool

IsMultiple returns true if this represents more than a single individual address, whether it is a collection or subnet of multiple addresses.

func (*Address) IsOneBit 

func (addr *Address) IsOneBit(bitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*Address) IsPrefixBlock 

func (addr *Address) IsPrefixBlock() bool

IsPrefixBlock returns whether the address has a prefix length and the address range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

To create a prefix block from any address, use ToPrefixBlock.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*Address) IsPrefixed 

func (addr *Address) IsPrefixed() bool

IsPrefixed returns whether this address has an associated prefix length.

func (*Address) IsSequential 

func (addr *Address) IsSequential() bool

IsSequential returns whether the address or subnet represents a range of addresses that are sequential.

Generally, for a subnet this means that any segment covering a range of values must be followed by segments that are full range, covering all values.

Individual addresses are sequential and CIDR prefix blocks are sequential. The subnet "1.2.3-4.5" is not sequential, since the two addresses it represents, "1.2.3.5" and "1.2.4.5", are not ("1.2.3.6" is in-between the two but not in the subnet).

With any IP address subnet, you can use SequentialBlockIterator to convert any subnet to a collection of sequential subnets.

func (*Address) IsSinglePrefixBlock 

func (addr *Address) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the address range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

For instance, "1.*.*.* /16" returns false from this method and returns true from IsPrefixBlock.

func (*Address) IsZero 

func (addr *Address) IsZero() bool

IsZero returns whether this address matches exactly the value of zero.

func (*Address) Iterator 

func (addr *Address) Iterator() Iterator[*Address]

Iterator provides an iterator to iterate through the individual addresses of this address or subnet.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual addresses.

Call IsMultiple to determine if this instance represents multiple addresses, or GetCount for the count.

func (*Address) PrefixBlockIterator 

func (addr *Address) PrefixBlockIterator() Iterator[*Address]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address or subnet. Each iterated address or subnet will be a prefix block with the same prefix length as this address or subnet.

If this address has no prefix length, then this is equivalent to Iterator.

func (*Address) PrefixContains 

func (addr *Address) PrefixContains(other AddressType) bool

PrefixContains returns whether the prefix values in the given address or subnet are prefix values in this address or subnet, using the prefix length of this address or subnet. If this address has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

func (*Address) PrefixEqual 

func (addr *Address) PrefixEqual(other AddressType) bool

PrefixEqual determines if the given address matches this address up to the prefix length of this address. It returns whether the two addresses share the same range of prefix values.

func (*Address) PrefixIterator 

func (addr *Address) PrefixIterator() Iterator[*Address]

PrefixIterator provides an iterator to iterate through the individual prefixes of this subnet, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this subnet.

If the subnet has no prefix length, then this is equivalent to Iterator.

func (*Address) ReverseBits 

func (addr *Address) ReverseBits(perByte bool) (*Address, addrerr.IncompatibleAddressError)

ReverseBits returns a new address with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*Address) ReverseBytes 

func (addr *Address) ReverseBytes() (*Address, addrerr.IncompatibleAddressError)

ReverseBytes returns a new address with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (*Address) ReverseSegments 

func (addr *Address) ReverseSegments() *Address

ReverseSegments returns a new address with the segments reversed.

func (*Address) SequentialBlockIterator 

func (addr *Address) SequentialBlockIterator() Iterator[*Address]

SequentialBlockIterator iterates through the sequential subnets or addresses that make up this address or subnet.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

For instance, given the IPv4 subnet "1-2.3-4.5-6.7-8", it will iterate through "1.3.5.7-8", "1.3.6.7-8", "1.4.5.7-8", "1.4.6.7-8", "2.3.5.7-8", "2.3.6.7-8", "2.4.6.7-8" and "2.4.6.7-8".

Use GetSequentialBlockCount to get the number of iterated elements.

func (*Address) SetPrefixLen 

func (addr *Address) SetPrefixLen(prefixLen BitCount) *Address

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address. The provided prefix length will be adjusted to these boundaries if necessary.

func (*Address) SetPrefixLenZeroed 

func (addr *Address) SetPrefixLenZeroed(prefixLen BitCount) (*Address, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address. The provided prefix length will be adjusted to these boundaries if necessary.

If this address has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*Address) String 

func (addr *Address) String() string

String implements the fmt.Stringer interface, returning the canonical string provided by ToCanonicalString, or "<nil>" if the receiver is a nil pointer.

func (*Address) TestBit 

func (addr *Address) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this address. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*Address) ToAddressBase 

func (addr *Address) ToAddressBase() *Address

ToAddressBase is an identity method.

ToAddressBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*Address) ToAddressString 

func (addr *Address) ToAddressString() HostIdentifierString

ToAddressString retrieves or generates a HostIdentifierString instance for this Address object.

This same Address instance can be retrieved from the resulting HostIdentifierString object using the GetAddress method.

In general, users create Address instances from IPAddressString or MACAddressString instances, while the reverse direction is generally not common and not useful.

However, the reverse direction can be useful under certain circumstances, such as when maintaining a collection of HostIdentifierString instances.

func (*Address) ToBinaryString 

func (addr *Address) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*Address) ToBlock 

func (addr *Address) ToBlock(segmentIndex int, lower, upper SegInt) *Address

ToBlock creates a new block of addresses by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*Address) ToCanonicalString 

func (addr *Address) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address.

For IPv4, dotted octet format, also known as dotted decimal format, is used. https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

For MAC, it uses the canonical standardized IEEE 802 MAC address representation of xx-xx-xx-xx-xx-xx. An example is "01-23-45-67-89-ab". For range segments, '|' is used: "11-22-33|44-55-66".

Each address has a unique canonical string, not counting the prefix length. With IP addresses, the prefix length is included in the string, and the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use the IPAddress method ToCanonicalWildcardString for a unique string for each IP address and subnet.

func (*Address) ToCompressedString 

func (addr *Address) ToCompressedString() string

ToCompressedString produces a short representation of this address while remaining within the confines of standard representation(s) of the address.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.

For MAC, it differs from the canonical string. It produces a shorter string for the address that has no leading zeros.

func (*Address) ToCustomString 

func (addr *Address) ToCustomString(stringOptions addrstr.StringOptions) string

ToCustomString creates a customized string from this address or subnet according to the given string option parameters.

func (*Address) ToGenericKey added in v1.5.1 

func (addr *Address) ToGenericKey() Key[*Address]

ToGenericKey produces a generic Key[*Address] that can be used with generic code working with Address, IPAddress, IPv4Address, IPv6Address and MACAddress.

func (*Address) ToHexString 

func (addr *Address) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If an address collection cannot be written as a single prefix block or a range of two values, an error is returned.

func (*Address) ToIP 

func (addr *Address) ToIP() *IPAddress

ToIP converts to an IPAddress if this address or subnet originated as an IPv4 or IPv6 address or subnet, or an implicitly zero-valued IP. If not, ToIP returns nil.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*Address) ToIPv4 

func (addr *Address) ToIPv4() *IPv4Address

ToIPv4 converts to an IPv4Address if this address or subnet originated as an IPv4 address or subnet. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*Address) ToIPv6 

func (addr *Address) ToIPv6() *IPv6Address

ToIPv6 converts to an IPv6Address if this address or subnet originated as an IPv6 address or subnet. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*Address) ToKey added in v1.1.0 

func (addr *Address) ToKey() Key[*Address]

ToKey creates the associated address key. While addresses can be compared with the Compare, TrieCompare or Equal methods as well as various provided instances of AddressComparator, they are not comparable with Go operators. However, AddressKey instances are comparable with Go operators, and thus can be used as map keys.

func (*Address) ToMAC 

func (addr *Address) ToMAC() *MACAddress

ToMAC converts to a MACAddress if this address or subnet originated as a MAC address or subnet. If not, ToMAC returns nil.

ToMAC can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*Address) ToNormalizedString 

func (addr *Address) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. Zero-segments are not compressed.

For MAC, it differs from the canonical string. It uses the most common representation of MAC addresses: "xx:xx:xx:xx:xx:xx". An example is "01:23:45:67:89:ab". For range segments, '-' is used: "11:22:33-44:55:66".

Each address has a unique normalized string, not counting the prefix length. With IP addresses, the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use the IPAddress method ToNormalizedWildcardString for a unique string for each IP address and subnet.

func (*Address) ToNormalizedWildcardString added in v1.5.0 

func (addr *Address) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length in IP addresses. Multi-valued segments will be shown with wildcards and ranges (denoted by '*' and '-').

func (*Address) ToOctalString 

func (addr *Address) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address as a single octal value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0" prefix.

If an address collection cannot be written as a single prefix block or a range of two values, an error is returned.

func (*Address) ToPrefixBlock 

func (addr *Address) ToPrefixBlock() *Address

ToPrefixBlock returns the address collection associated with the prefix of this address or address collection, the address whose prefix matches the prefix of this address, and the remaining bits span all values. If this address has no prefix length, this address is returned.

The returned address collection will include all addresses with the same prefix as this one, the prefix "block".

func (*Address) ToPrefixBlockLen added in v1.1.0 

func (addr *Address) ToPrefixBlockLen(prefLen BitCount) *Address

ToPrefixBlockLen returns the address associated with the prefix length provided, the address collection whose prefix of that length matches the prefix of this address, and the remaining bits span all values.

The returned address will include all addresses with the same prefix as this one, the prefix "block".

func (*Address) ToSinglePrefixBlockOrAddress added in v1.1.0 

func (addr *Address) ToSinglePrefixBlockOrAddress() *Address

ToSinglePrefixBlockOrAddress converts to a single prefix block or address. If the given address is a single prefix block, it is returned. If it can be converted to a single prefix block by assigning a prefix length, the converted block is returned. If it is a single address, any prefix length is removed and the address is returned. Otherwise, nil is returned. This method provides the address formats used by tries. ToSinglePrefixBlockOrAddress is quite similar to AssignPrefixForSingleBlock, which always returns prefixed addresses, while this does not.

func (*Address) TrieCompare added in v1.1.0 

func (addr *Address) TrieCompare(other *Address) (int, addrerr.IncompatibleAddressError)

TrieCompare compares two addresses according to address trie ordering. It returns a number less than zero, zero, or a number greater than zero if the first address argument is less than, equal to, or greater than the second.

The comparison is intended for individual addresses and CIDR prefix blocks. If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*Address) TrieDecrement added in v1.1.0 

func (addr *Address) TrieDecrement() *Address

TrieDecrement returns the previous or block address according to address trie ordering.

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*Address) TrieIncrement added in v1.1.0 

func (addr *Address) TrieIncrement() *Address

TrieIncrement returns the next address or block according to address trie ordering.

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*Address) UpperBytes 

func (addr *Address) UpperBytes() []byte

UpperBytes returns the highest address in this subnet or address collection as a byte slice.

func (*Address) WithoutPrefixLen 

func (addr *Address) WithoutPrefixLen() *Address

WithoutPrefixLen provides the same address but with no prefix length. The values remain unchanged.

func (*Address) Wrap 

func (addr *Address) Wrap() WrappedAddress

Wrap wraps this address, returning a WrappedAddress, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections.

type AddressComparator 

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

AddressComparator has methods to compare addresses, or sections, or division series, or segments, or divisions, or sequential ranges. AddressComparator also allows you to compare any two instances of any such address items, using the Compare method. The zero value acts like CountComparator, the default comparator.

func (AddressComparator) Compare 

func (comp AddressComparator) Compare(one, two AddressItem) int

Compare returns a negative integer, zero, or a positive integer if address item one is less than, equal, or greater than address item two. Any address item is comparable to any other.

func (AddressComparator) CompareAddressSections 

func (comp AddressComparator) CompareAddressSections(one, two AddressSectionType) int

CompareAddressSections compares any two address sections (including from different versions or address types). It returns a negative integer, zero, or a positive integer if address item one is less than, equal, or greater than address item two.

func (AddressComparator) CompareAddresses 

func (comp AddressComparator) CompareAddresses(one, two AddressType) int

CompareAddresses compares any two addresses (including different versions or address types) It returns a negative integer, zero, or a positive integer if address item one is less than, equal, or greater than address item two.

func (AddressComparator) CompareDivisions 

func (comp AddressComparator) CompareDivisions(one, two DivisionType) int

CompareDivisions compares any two address divisions (including from different versions or address types). It returns a negative integer, zero, or a positive integer if address item one is less than, equal, or greater than address item two.

func (AddressComparator) CompareRanges 

func (comp AddressComparator) CompareRanges(one, two IPAddressSeqRangeType) int

CompareRanges compares any two IP address sequential ranges (including from different IP versions). It returns a negative integer, zero, or a positive integer if address item one is less than, equal, or greater than address item two.

func (AddressComparator) CompareSegments 

func (comp AddressComparator) CompareSegments(one, two AddressSegmentType) int

CompareSegments compares any two address segments (including from different versions or address types). It returns a negative integer, zero, or a positive integer if address item one is less than, equal, or greater than address item two.

func (AddressComparator) CompareSeries 

func (comp AddressComparator) CompareSeries(one, two AddressDivisionSeries) int

CompareSeries compares any two address division series (including from different versions or address types). It returns a negative integer, zero, or a positive integer if address item one is less than, equal, or greater than address item two.

type AddressComponent 

type AddressComponent interface {
	// TestBit returns true if the bit in the lower value of the address component at the given index is 1, where index 0 refers to the least significant bit.
	// In other words, it computes (bits & (1 << n)) != 0), using the lower value of this address component.
	// TestBit will panic if n < 0, or if it matches or exceeds the bit count of this address component.
	TestBit(index BitCount) bool

	// IsOneBit returns true if the bit in the lower value of this address component at the given index is 1, where index 0 refers to the most significant bit.
	// IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this address component.
	IsOneBit(index BitCount) bool

	// ToHexString writes this address component as a single hexadecimal value (possibly two values if a range that is not a prefixed block),
	// the number of digits according to the bit count, with or without a preceding "0x" prefix.
	//
	// If a multiple-valued component cannot be written as a single prefix block or a range of two values, an error is returned.
	ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

	// ToNormalizedString produces a string that is consistent for all address components of the same type and version.
	ToNormalizedString() string
}

AddressComponent represents all addresses, address sections, and address segments.

type AddressDivision 

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

AddressDivision represents an arbitrary division in an address or address division grouping. It can contain a single value or a range of sequential values and it has an assigned bit length. Like all address components, it is immutable. Divisions that were converted from IPv4, IPv6 or MAC segments can be converted back to the same segment type and version. Divisions that were not converted from IPv4, IPv6 or MAC cannot be converted to segments.

func NewDivision 

func NewDivision(val DivInt, bitCount BitCount) *AddressDivision

NewDivision creates a division of the given bit length, assigning it the given value. If the value's bit length exceeds the given bit length, it is truncated.

func NewPrefixDivision 

func NewPrefixDivision(val DivInt, prefixLen PrefixLen, bitCount BitCount) *AddressDivision

NewPrefixDivision creates a division of the given bit length, assigning it the given value and prefix length. If the value's bit length exceeds the given bit length, it is truncated. If the prefix length exceeds the bit length, it is adjusted to the bit length. If the prefix length is negative, it is adjusted to zero.

func NewRangeDivision 

func NewRangeDivision(val, upperVal DivInt, bitCount BitCount) *AddressDivision

NewRangeDivision creates a division of the given bit length, assigning it the given value range. If a value's bit length exceeds the given bit length, it is truncated.

func NewRangePrefixDivision 

func NewRangePrefixDivision(val, upperVal DivInt, prefixLen PrefixLen, bitCount BitCount) *AddressDivision

NewRangePrefixDivision creates a division of the given bit length, assigning it the given value range and prefix length. If a value's bit length exceeds the given bit length, it is truncated. If the prefix length exceeds the bit length, it is adjusted to the bit length. If the prefix length is negative, it is adjusted to zero.

func (*AddressDivision) Bytes 

func (div *AddressDivision) Bytes() []byte

Bytes returns the lowest value in the address division range as a byte slice.

func (*AddressDivision) Compare 

func (div *AddressDivision) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address division is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*AddressDivision) CompareSize added in v1.3.0 

func (div *AddressDivision) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual values within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one represents more individual values than another.

CompareSize returns a positive integer if this division has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.

func (*AddressDivision) ContainsPrefixBlock 

func (div *AddressDivision) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the division range includes the block of values for the given prefix length.

func (*AddressDivision) ContainsSinglePrefixBlock 

func (div *AddressDivision) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the division range matches exactly the block of values for the given prefix length and has just a single prefix for that prefix length.

func (*AddressDivision) CopyBytes 

func (div *AddressDivision) CopyBytes(bytes []byte) []byte

CopyBytes copies the lowest value in the address division range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*AddressDivision) CopyUpperBytes 

func (div *AddressDivision) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the highest value in the address division range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (AddressDivision) Format 

func (div AddressDivision) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*AddressDivision) GetBitCount 

func (div *AddressDivision) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (*AddressDivision) GetByteCount 

func (div *AddressDivision) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item, rounding up if the bit count is not a multiple of 8.

func (*AddressDivision) GetCount 

func (div *AddressDivision) GetCount() *big.Int

GetCount returns the count of possible distinct values for this division. If not representing multiple values, the count is 1.

For instance, a division with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*AddressDivision) GetDivisionValue 

func (div *AddressDivision) GetDivisionValue() DivInt

GetDivisionValue returns the lower division value in the range.

func (*AddressDivision) GetMaxValue 

func (div *AddressDivision) GetMaxValue() DivInt

GetMaxValue gets the maximum possible value for this type of division, determined by the number of bits.

For the highest range value of this particular segment, use GetUpperDivisionValue.

func (*AddressDivision) GetMinPrefixLenForBlock 

func (div *AddressDivision) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this division includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this division represents a single value, this returns the bit count.

func (*AddressDivision) GetPrefixCountLen 

func (div *AddressDivision) GetPrefixCountLen(divisionPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefixes in the division value range for the given prefix length.

func (*AddressDivision) GetPrefixLenForSingleBlock 

func (div *AddressDivision) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this division, and the range of values in this division matches the block of all values for that prefix.

If the range of division values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this division represents a single value, this returns the bit count of the segment.

func (*AddressDivision) GetString 

func (div *AddressDivision) GetString() string

GetString produces a normalized string to represent the segment. If the segment is an IP segment string with CIDR network prefix block for its prefix length, then the string contains only the lower value of the block range. Otherwise, the explicit range will be printed. If the segment is not an IP segment, then the string is the same as that produced by GetWildcardString.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*AddressDivision) GetUpperDivisionValue 

func (div *AddressDivision) GetUpperDivisionValue() DivInt

GetUpperDivisionValue returns the upper division value in the range.

func (*AddressDivision) GetUpperValue 

func (div *AddressDivision) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address division range as a big integer.

func (*AddressDivision) GetValue 

func (div *AddressDivision) GetValue() *BigDivInt

GetValue returns the lowest value in the address division range as a big integer.

func (*AddressDivision) GetWildcardString 

func (div *AddressDivision) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters regardless of any network prefix length. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*AddressDivision) IncludesMax 

func (div *AddressDivision) IncludesMax() bool

IncludesMax returns whether this division includes the max value, the value whose bits are all ones, within its range.

func (*AddressDivision) IncludesZero 

func (div *AddressDivision) IncludesZero() bool

IncludesZero returns whether this item includes the value of zero within its range.

func (*AddressDivision) IsFullRange 

func (div *AddressDivision) IsFullRange() bool

IsFullRange returns whether the division range includes all possible values for its bit length.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*AddressDivision) IsIP 

func (div *AddressDivision) IsIP() bool

IsIP returns true if this division originated as an IPv4 or IPv6 segment, or an implicitly zero-valued IP segment. If so, use ToIP to convert back to the IP-specific type.

func (*AddressDivision) IsIPv4 

func (div *AddressDivision) IsIPv4() bool

IsIPv4 returns true if this division originated as an IPv4 segment. If so, use ToIPv4 to convert back to the IPv4-specific type.

func (*AddressDivision) IsIPv6 

func (div *AddressDivision) IsIPv6() bool

IsIPv6 returns true if this division originated as an IPv6 segment. If so, use ToIPv6 to convert back to the IPv6-specific type.

func (*AddressDivision) IsMAC 

func (div *AddressDivision) IsMAC() bool

IsMAC returns true if this division originated as a MAC segment. If so, use ToMAC to convert back to the MAC-specific type.

func (*AddressDivision) IsMax 

func (div *AddressDivision) IsMax() bool

IsMax returns whether this division matches exactly the maximum possible value, the value whose bits are all ones.

func (*AddressDivision) IsMultiple 

func (div *AddressDivision) IsMultiple() bool

IsMultiple returns whether this division represents a sequential range of values, vs a single value.

func (*AddressDivision) IsSegmentBase 

func (div *AddressDivision) IsSegmentBase() bool

IsSegmentBase returns true if this division originated as an address segment, and this can be converted back with ToSegmentBase.

func (*AddressDivision) IsSinglePrefix 

func (div *AddressDivision) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix returns true if the division value range spans just a single prefix value for the given prefix length.

func (*AddressDivision) IsZero 

func (div *AddressDivision) IsZero() bool

IsZero returns whether this division matches exactly the value of zero.

func (*AddressDivision) Matches 

func (div *AddressDivision) Matches(value DivInt) bool

Matches returns true if the division range matches the given single value.

func (*AddressDivision) MatchesValsWithMask 

func (div *AddressDivision) MatchesValsWithMask(lowerValue, upperValue, mask DivInt) bool

MatchesValsWithMask applies the mask to this division and then compares the result with the given values, returning true if the range of the resulting division matches the given range.

func (*AddressDivision) MatchesWithMask 

func (div *AddressDivision) MatchesWithMask(value, mask DivInt) bool

MatchesWithMask applies the mask to this division and then compares the result with the given value, returning true if the range of the resulting division matches that single value.

func (*AddressDivision) String 

func (div *AddressDivision) String() string

String produces a string that is useful when a division string is provided with no context. It uses a string prefix for octal or hex ("0" or "0x"), and does not use the wildcard '*', because division size is variable, and so '*' is ambiguous. GetWildcardString is more appropriate in context with other segments or divisions. It does not use a string prefix and uses '*' for full-range segments. GetString is more appropriate in context with prefix lengths, it uses zeros instead of wildcards for prefix block ranges.

func (*AddressDivision) ToDiv 

func (div *AddressDivision) ToDiv() *AddressDivision

ToDiv is an identity method.

ToDiv can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivision) ToIP 

func (div *AddressDivision) ToIP() *IPAddressSegment

ToIP converts to an IPAddressSegment if this division originated as an IPv4 or IPv6 segment, or an implicitly zero-valued IP segment. If not, ToIP returns nil.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivision) ToIPv4 

func (div *AddressDivision) ToIPv4() *IPv4AddressSegment

ToIPv4 converts to an IPv4AddressSegment if this division originated as an IPv4 segment. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivision) ToIPv6 

func (div *AddressDivision) ToIPv6() *IPv6AddressSegment

ToIPv6 converts to an IPv6AddressSegment if this division originated as an IPv6 segment. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivision) ToMAC 

func (div *AddressDivision) ToMAC() *MACAddressSegment

ToMAC converts to a MACAddressSegment if this division originated as a MAC segment. If not, ToMAC returns nil.

ToMAC can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivision) ToSegmentBase 

func (div *AddressDivision) ToSegmentBase() *AddressSegment

ToSegmentBase converts to an AddressSegment if this division originated as a segment. If not, ToSegmentBase returns nil.

ToSegmentBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivision) UpperBytes 

func (div *AddressDivision) UpperBytes() []byte

UpperBytes returns the highest value in the address division range as a byte slice.

type AddressDivisionGrouping 

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

AddressDivisionGrouping objects consist of a series of AddressDivision objects, each division containing a sequential range of values.

AddressDivisionGrouping objects are immutable. This also makes them concurrency-safe.

AddressDivision objects use uint64 to represent their values, so this places a cap on the size of the divisions in AddressDivisionGrouping.

AddressDivisionGrouping objects are similar to address sections and addresses, except that groupings can have divisions of differing bit-length, including divisions that are not an exact number of bytes, whereas all segments in an address or address section must be equal bit size and an exact number of bytes.

func NewDivisionGrouping 

func NewDivisionGrouping(divs []*AddressDivision) *AddressDivisionGrouping

NewDivisionGrouping creates an arbitrary grouping of divisions. To create address sections or addresses, use the constructors that are specific to the address version or type. The AddressDivision instances can be created with the NewDivision, NewRangeDivision, NewPrefixDivision or NewRangePrefixDivision functions.

func (*AddressDivisionGrouping) Bytes 

func (grouping *AddressDivisionGrouping) Bytes() []byte

Bytes returns the lowest individual division grouping in this grouping as a byte slice.

func (*AddressDivisionGrouping) Compare 

func (grouping *AddressDivisionGrouping) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address division grouping is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*AddressDivisionGrouping) CompareSize 

func (grouping *AddressDivisionGrouping) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual items represented in each.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether this grouping represents more individual items than another.

CompareSize returns a positive integer if this address division grouping has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*AddressDivisionGrouping) ContainsPrefixBlock 

func (grouping *AddressDivisionGrouping) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*AddressDivisionGrouping) ContainsSinglePrefixBlock 

func (grouping *AddressDivisionGrouping) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this grouping contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*AddressDivisionGrouping) CopyBytes 

func (grouping *AddressDivisionGrouping) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest division grouping in the range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

You can use GetByteCount to determine the required array length for the bytes.

func (*AddressDivisionGrouping) CopyDivisions 

func (grouping *AddressDivisionGrouping) CopyDivisions(divs []*AddressDivision) (count int)

CopyDivisions copies the existing divisions from the given start index until but not including the division at the given end index, into the given slice, as much as can be fit into the slice, returning the number of divisions copied.

func (*AddressDivisionGrouping) CopySubDivisions 

func (grouping *AddressDivisionGrouping) CopySubDivisions(start, end int, divs []*AddressDivision) (count int)

CopySubDivisions copies the existing divisions from the given start index until but not including the division at the given end index, into the given slice, as much as can be fit into the slice, returning the number of divisions copied.

func (*AddressDivisionGrouping) CopyUpperBytes 

func (grouping *AddressDivisionGrouping) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest division grouping in the range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

You can use GetByteCount to determine the required array length for the bytes.

func (*AddressDivisionGrouping) ForEachDivision added in v1.2.0 

func (grouping *AddressDivisionGrouping) ForEachDivision(consumer func(divisionIndex int, division *AddressDivision) (stop bool)) int

ForEachDivision visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. ForEachDivision returns the number of visited segments.

func (AddressDivisionGrouping) Format 

func (grouping AddressDivisionGrouping) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*AddressDivisionGrouping) GetBitCount 

func (grouping *AddressDivisionGrouping) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (*AddressDivisionGrouping) GetBlockCount 

func (grouping *AddressDivisionGrouping) GetBlockCount(divisionCount int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) divisions.

func (*AddressDivisionGrouping) GetByteCount 

func (grouping *AddressDivisionGrouping) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item, rounding up if the bit count is not a multiple of 8.

func (*AddressDivisionGrouping) GetCount 

func (grouping *AddressDivisionGrouping) GetCount() *big.Int

GetCount returns the count of possible distinct values for this division grouping. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*AddressDivisionGrouping) GetDivision 

func (grouping *AddressDivisionGrouping) GetDivision(index int) *AddressDivision

GetDivision returns the division at the given index.

func (*AddressDivisionGrouping) GetDivisionCount 

func (grouping *AddressDivisionGrouping) GetDivisionCount() int

GetDivisionCount returns the number of divisions in this grouping.

func (*AddressDivisionGrouping) GetDivisionStrings 

func (grouping *AddressDivisionGrouping) GetDivisionStrings() []string

GetDivisionStrings returns a slice containing each string returned from the String method of each division in the grouping.

func (*AddressDivisionGrouping) GetGenericDivision 

func (grouping *AddressDivisionGrouping) GetGenericDivision(index int) DivisionType

GetGenericDivision returns the division at the given index as a DivisionType implementation.

func (*AddressDivisionGrouping) GetMinPrefixLenForBlock 

func (grouping *AddressDivisionGrouping) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this grouping includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this grouping represents a single value, this returns the bit count.

func (*AddressDivisionGrouping) GetPrefixCount 

func (grouping *AddressDivisionGrouping) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetCount.

func (*AddressDivisionGrouping) GetPrefixCountLen 

func (grouping *AddressDivisionGrouping) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length.

func (*AddressDivisionGrouping) GetPrefixLenForSingleBlock 

func (grouping *AddressDivisionGrouping) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this division grouping matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this division grouping represents a single value, returns the bit length.

func (*AddressDivisionGrouping) GetSequentialBlockCount 

func (grouping *AddressDivisionGrouping) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address division groupings that comprise this address division grouping.

func (*AddressDivisionGrouping) GetSequentialBlockIndex 

func (grouping *AddressDivisionGrouping) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal division index for which all following divisions are full-range blocks.

The division at this index is not a full-range block unless all divisions are full-range. The division at this index and all following divisions form a sequential range. For the full grouping to be sequential, the preceding divisions must be single-valued.

func (*AddressDivisionGrouping) GetUpperValue 

func (grouping *AddressDivisionGrouping) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address division grouping in this address division grouping as an integer value.

func (*AddressDivisionGrouping) GetValue 

func (grouping *AddressDivisionGrouping) GetValue() *big.Int

GetValue returns the lowest individual address division grouping in this address division grouping as an integer value.

func (*AddressDivisionGrouping) IncludesMax 

func (grouping *AddressDivisionGrouping) IncludesMax() bool

IncludesMax returns whether this grouping includes the max value, the value whose bits are all ones, within its range.

func (*AddressDivisionGrouping) IncludesZero 

func (grouping *AddressDivisionGrouping) IncludesZero() bool

IncludesZero returns whether this grouping includes the value of zero within its range.

func (*AddressDivisionGrouping) IsAdaptiveZero 

func (grouping *AddressDivisionGrouping) IsAdaptiveZero() bool

IsAdaptiveZero returns true if this is an adaptive zero grouping. The adaptive zero grouping, produced by zero sections like IPv4AddressSection{} or AddressDivisionGrouping{}, can represent a zero-length section of any address type. It is not considered equal to constructions of specific zero length sections or groupings like NewIPv4Section(nil) which can only represent a zero-length section of a single address type.

func (*AddressDivisionGrouping) IsFullRange 

func (grouping *AddressDivisionGrouping) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*AddressDivisionGrouping) IsIP 

func (grouping *AddressDivisionGrouping) IsIP() bool

IsIP returns true if this address division grouping originated as an IPv4 or IPv6 section, or a zero-length IP section. If so, use ToIP to convert back to the IP-specific type.

func (*AddressDivisionGrouping) IsIPv4 

func (grouping *AddressDivisionGrouping) IsIPv4() bool

IsIPv4 returns true if this grouping originated as an IPv4 section. If so, use ToIPv4 to convert back to the IPv4-specific type.

func (*AddressDivisionGrouping) IsIPv6 

func (grouping *AddressDivisionGrouping) IsIPv6() bool

IsIPv6 returns true if this grouping originated as an IPv6 section. If so, use ToIPv6 to convert back to the IPv6-specific type.

func (*AddressDivisionGrouping) IsMAC 

func (grouping *AddressDivisionGrouping) IsMAC() bool

IsMAC returns true if this grouping originated as a MAC section. If so, use ToMAC to convert back to the MAC-specific type.

func (*AddressDivisionGrouping) IsMax 

func (grouping *AddressDivisionGrouping) IsMax() bool

IsMax returns whether this grouping matches exactly the maximum possible value, the value whose bits are all ones.

func (*AddressDivisionGrouping) IsMixedIPv6v4 

func (grouping *AddressDivisionGrouping) IsMixedIPv6v4() bool

IsMixedIPv6v4 returns true if this grouping originated as a mixed IPv6-IPv4 grouping. If so, use ToMixedIPv6v4 to convert back to the more specific grouping type.

func (*AddressDivisionGrouping) IsMultiple 

func (grouping *AddressDivisionGrouping) IsMultiple() bool

IsMultiple returns whether this grouping represents multiple values rather than a single value

func (*AddressDivisionGrouping) IsPrefixBlock 

func (grouping *AddressDivisionGrouping) IsPrefixBlock() bool

IsPrefixBlock returns whether this address division series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*AddressDivisionGrouping) IsPrefixed 

func (grouping *AddressDivisionGrouping) IsPrefixed() bool

IsPrefixed returns whether this grouping has an associated prefix length.

func (*AddressDivisionGrouping) IsSectionBase 

func (grouping *AddressDivisionGrouping) IsSectionBase() bool

IsSectionBase returns true if this address division grouping originated as an address section. If so, use ToSectionBase to convert back to the section type.

func (*AddressDivisionGrouping) IsSinglePrefixBlock 

func (grouping *AddressDivisionGrouping) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range of values matches a single subnet block for the prefix length.

What distinguishes this method with ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*AddressDivisionGrouping) IsZero 

func (grouping *AddressDivisionGrouping) IsZero() bool

IsZero returns whether this grouping matches exactly the value of zero.

func (*AddressDivisionGrouping) String 

func (grouping *AddressDivisionGrouping) String() string

String implements the fmt.Stringer interface. It returns "<nil>" if the receiver is a nil pointer. It returns the normalized string provided by ToNormalizedString if this grouping originated as an address section. Otherwise, the string is printed like a slice, with each division converted to a string by its own String method (like "[ div0 div1 ... ]").

func (*AddressDivisionGrouping) ToDivGrouping 

func (grouping *AddressDivisionGrouping) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping is an identity method.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivisionGrouping) ToIP 

func (grouping *AddressDivisionGrouping) ToIP() *IPAddressSection

ToIP converts to an IPAddressSection if this grouping originated as an IPv4 or IPv6 section, or an implicitly zero-valued IP section. If not, ToIP returns nil.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivisionGrouping) ToIPv4 

func (grouping *AddressDivisionGrouping) ToIPv4() *IPv4AddressSection

ToIPv4 converts to an IPv4AddressSection if this grouping originated as an IPv4 section. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivisionGrouping) ToIPv6 

func (grouping *AddressDivisionGrouping) ToIPv6() *IPv6AddressSection

ToIPv6 converts to an IPv6AddressSection if this grouping originated as an IPv6 section. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivisionGrouping) ToMAC 

func (grouping *AddressDivisionGrouping) ToMAC() *MACAddressSection

ToMAC converts to a MACAddressSection if this grouping originated as a MAC section. If not, ToMAC returns nil.

ToMAC can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivisionGrouping) ToMixedIPv6v4 

func (grouping *AddressDivisionGrouping) ToMixedIPv6v4() *IPv6v4MixedAddressGrouping

ToMixedIPv6v4 converts to a mixed IPv6/4 address section if this grouping originated as a mixed IPv6/4 address section. Otherwise, the result will be nil.

ToMixedIPv6v4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivisionGrouping) ToSectionBase 

func (grouping *AddressDivisionGrouping) ToSectionBase() *AddressSection

ToSectionBase converts to an address section if this grouping originated as an address section. Otherwise, the result will be nil.

ToSectionBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressDivisionGrouping) UpperBytes 

func (grouping *AddressDivisionGrouping) UpperBytes() []byte

UpperBytes returns the highest individual division grouping in this grouping as a byte slice.

type AddressDivisionSeries 

type AddressDivisionSeries interface {
	AddressItem

	// GetDivisionCount returns the number of divisions.
	GetDivisionCount() int

	// GetPrefixCount returns the count of prefixes in this series for its prefix length, or the total count if it has no prefix length
	GetPrefixCount() *big.Int

	// GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.
	GetBlockCount(divisionCount int) *big.Int

	// GetSequentialBlockIndex gets the minimal division index for which all following divisions are full-range blocks.
	//
	// The division at this index is not a full-range block unless all divisions are full-range.
	// The division at this index and all following divisions form a sequential range.
	// For the full series to be sequential, the preceding divisions must be single-valued.
	GetSequentialBlockIndex() int

	// GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address division series that comprise this address division series.
	GetSequentialBlockCount() *big.Int

	// IsSequential returns  whether the series represents a range of values that are sequential.
	//
	// Generally, this means that any division covering a range of values must be followed by divisions that are full range, covering all values.
	IsSequential() bool

	Prefixed

	// GetGenericDivision returns the division at the given index as a DivisionType.
	// The first division is at index 0.
	// GetGenericDivision will panic given a negative index or index larger than the division count.
	GetGenericDivision(index int) DivisionType // useful for comparisons
}

AddressDivisionSeries serves as a common interface to all division groupings, address sections, and addresses.

type AddressItem 

type AddressItem interface {
	BitItem

	// GetValue returns the lowest individual address item in the address item range as an integer value.
	GetValue() *big.Int

	// GetUpperValue returns the highest individual address item in the address item range as an integer value.
	GetUpperValue() *big.Int

	// CopyBytes copies the value of the lowest individual address item in this address item range into a byte slice.
	//
	// If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned.
	// Otherwise, a new slice is created and returned with the value.
	CopyBytes(bytes []byte) []byte

	// CopyUpperBytes copies the value of the highest individual address item in this address item range into a byte slice.
	//
	// If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned.
	// Otherwise, a new slice is created and returned with the value.
	CopyUpperBytes(bytes []byte) []byte

	// Bytes returns the lowest individual address item in the address item range as a byte slice.
	Bytes() []byte

	// UpperBytes returns the highest individual address item in the address item range as a byte slice.
	UpperBytes() []byte

	// GetCount provides the number of address items represented by this AddressItem, for example the subnet size for IP addresses
	GetCount() *big.Int

	// IsMultiple returns whether this item represents multiple values (the count is larger than 1)
	IsMultiple() bool

	// IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.
	//
	// This is true if and only if both IncludesZero and IncludesMax return true.
	IsFullRange() bool

	// IncludesZero returns whether this item includes the value of zero within its range.
	IncludesZero() bool

	// IncludesMax returns whether this item includes the max value, the value whose bits are all ones, within its range.
	IncludesMax() bool

	// IsZero returns whether this address item matches exactly the value of zero.
	IsZero() bool

	// IsMax returns whether this address item matches exactly the maximum possible value, the value whose bits are all ones.
	IsMax() bool

	// ContainsPrefixBlock returns whether the values of this item contains the prefix block for the given prefix length.
	// Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values for the given prefix length makes no difference.
	ContainsPrefixBlock(BitCount) bool

	// ContainsSinglePrefixBlock returns whether the values of this series contains a single prefix block for the given prefix length.
	// This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix, all items with that same prefix.
	ContainsSinglePrefixBlock(BitCount) bool

	// GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix of that length in this item,
	// and the range of this item matches the block of all values for that prefix.
	//
	// If the entire range can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.
	//
	// If no such prefix length exists, returns nil.
	//
	// If this item represents a single value, this returns the bit count.
	GetPrefixLenForSingleBlock() PrefixLen

	// GetMinPrefixLenForBlock returns the smallest prefix length possible such that this item includes the block of all values for that prefix length.
	//
	// If the entire range can be dictated this way, then this method returns the same value as GetPrefixLenForSingleBlock.
	//
	// There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length.
	// Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.
	//
	// If this item represents a single value, this returns the bit count.
	GetMinPrefixLenForBlock() BitCount

	// GetPrefixCountLen returns the count of the number of distinct values within the prefix part of the range of values for this item
	GetPrefixCountLen(BitCount) *big.Int

	// Compare returns a negative integer, zero, or a positive integer if this address item is less than, equal, or greater than the given item.
	// Any address item is comparable to any other.  All address items use CountComparator to compare.
	Compare(AddressItem) int

	// CompareSize compares the counts of two address items,
	// whether addresses in the subnet or address range, whether individual sections in the collection of sections, whether individual segments in the segment's range.
	// It compares the number of individual elements within each.
	//
	// Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one item represents more individual addresses than another.
	//
	// CompareSize returns a positive integer if this item has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.
	CompareSize(AddressItem) int

	fmt.Stringer
	fmt.Formatter
}

AddressItem represents all addresses, division groupings, divisions, and sequential ranges. Any address item can be compared to any other.

type AddressKey added in v1.1.0 

type AddressKey = Key[*Address]

type AddressSection 

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

An AddressSection is section of an address, containing a certain number of consecutive segments.

It is a series of individual address segments. Each segment has equal bit-length. Each address is backed by an address section that contains all the segments of the address.

AddressSection instances are immutable. This also makes them concurrency-safe.

Most operations that can be performed on Address instances can also be performed on AddressSection instances and vice-versa.

func (*AddressSection) AdjustPrefixLen 

func (section *AddressSection) AdjustPrefixLen(prefixLen BitCount) *AddressSection

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*AddressSection) AdjustPrefixLenZeroed 

func (section *AddressSection) AdjustPrefixLenZeroed(prefixLen BitCount) (*AddressSection, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*AddressSection) AssignMinPrefixForBlock 

func (section *AddressSection) AssignMinPrefixForBlock() *AddressSection

AssignMinPrefixForBlock returns an equivalent address section, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this address section.

In other words, this method assigns a prefix length to this address section matching the largest prefix block in this address section.

func (*AddressSection) AssignPrefixForSingleBlock 

func (section *AddressSection) AssignPrefixForSingleBlock() *AddressSection

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address section. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address section - it is required that the range of values match the range of a prefix block. If there is no such address section, then nil is returned.

func (*AddressSection) Bytes 

func (section *AddressSection) Bytes() []byte

Bytes returns the lowest individual address section in this address section as a byte slice.

func (*AddressSection) Compare 

func (section *AddressSection) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address section is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*AddressSection) CompareSize 

func (section *AddressSection) CompareSize(other AddressItem) int

CompareSize compares the counts of two address sections, the number of individual sections represented.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one section represents more individual address sections than another.

CompareSize returns a positive integer if this address section has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.

func (*AddressSection) Contains 

func (section *AddressSection) Contains(other AddressSectionType) bool

Contains returns whether this is same type and version as the given address section and whether it contains all values in the given section.

Sections must also have the same number of segments to be comparable, otherwise false is returned.

func (*AddressSection) ContainsPrefixBlock 

func (section *AddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*AddressSection) ContainsSinglePrefixBlock 

func (section *AddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this grouping contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*AddressSection) CopyBytes 

func (section *AddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*AddressSection) CopySegments 

func (section *AddressSection) CopySegments(segs []*AddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*AddressSection) CopySubSegments 

func (section *AddressSection) CopySubSegments(start, end int, segs []*AddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*AddressSection) CopyUpperBytes 

func (section *AddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*AddressSection) Equal 

func (section *AddressSection) Equal(other AddressSectionType) bool

Equal returns whether the given address section is equal to this address section. Two address sections are equal if they represent the same set of sections. They must match:

  • type/version (IPv4, IPv6, MAC, etc)
  • segment counts
  • bits per segment
  • segment value ranges

Prefix lengths are ignored.

func (*AddressSection) ForEachSegment added in v1.2.0 

func (section *AddressSection) ForEachSegment(consumer func(segmentIndex int, segment *AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (AddressSection) Format 

func (section AddressSection) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*AddressSection) GetBitCount 

func (section *AddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (*AddressSection) GetBitsPerSegment 

func (section *AddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (*AddressSection) GetBlockCount 

func (section *AddressSection) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*AddressSection) GetByteCount 

func (section *AddressSection) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item.

func (*AddressSection) GetBytesPerSegment 

func (section *AddressSection) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this section. Segments in the same address section are equal length.

func (*AddressSection) GetCount 

func (section *AddressSection) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*AddressSection) GetGenericSegment 

func (section *AddressSection) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment as an AddressSegmentType, allowing all segment types to be represented by a single type. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (*AddressSection) GetLeadingBitCount added in v1.1.0 

func (section *AddressSection) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower value of the range if this section represents multiple values.

func (*AddressSection) GetLower 

func (section *AddressSection) GetLower() *AddressSection

GetLower returns the section in the range with the lowest numeric value, which will be the same section if it represents a single value. For example, for "1.2-3.4.5-6", the section "1.2.4.5" is returned.

func (*AddressSection) GetMaxSegmentValue 

func (section *AddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*AddressSection) GetMinPrefixLenForBlock 

func (section *AddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (*AddressSection) GetPrefixCount 

func (section *AddressSection) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetCount.

func (*AddressSection) GetPrefixCountLen 

func (section *AddressSection) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length.

func (*AddressSection) GetPrefixLen 

func (section *AddressSection) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (*AddressSection) GetPrefixLenForSingleBlock 

func (section *AddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (*AddressSection) GetSegment 

func (section *AddressSection) GetSegment(index int) *AddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (*AddressSection) GetSegmentCount 

func (section *AddressSection) GetSegmentCount() int

GetSegmentCount returns the segment count.

func (*AddressSection) GetSegmentStrings 

func (section *AddressSection) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*AddressSection) GetSegments 

func (section *AddressSection) GetSegments() (res []*AddressSegment)

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*AddressSection) GetSequentialBlockCount 

func (section *AddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section.

func (*AddressSection) GetSequentialBlockIndex 

func (section *AddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (*AddressSection) GetSubSection 

func (section *AddressSection) GetSubSection(index, endIndex int) *AddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*AddressSection) GetTrailingBitCount added in v1.1.0 

func (section *AddressSection) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies to the lower value of the range if this section represents multiple values.

func (*AddressSection) GetTrailingSection 

func (section *AddressSection) GetTrailingSection(index int) *AddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*AddressSection) GetUpper 

func (section *AddressSection) GetUpper() *AddressSection

GetUpper returns the section in the range with the highest numeric value, which will be the same section if it represents a single value. For example, for "1.2-3.4.5-6", the section "1.3.4.6" is returned.

func (*AddressSection) GetUpperValue 

func (section *AddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value.

func (*AddressSection) GetValue 

func (section *AddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value.

func (*AddressSection) IncludesMax 

func (section *AddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range.

func (*AddressSection) IncludesZero 

func (section *AddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range.

func (*AddressSection) Increment 

func (section *AddressSection) Increment(increment int64) *AddressSection

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (*AddressSection) IncrementBoundary 

func (section *AddressSection) IncrementBoundary(increment int64) *AddressSection

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (*AddressSection) IsAdaptiveZero 

func (section *AddressSection) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the division grouping was originally created as an implicitly zero-valued section or grouping (e.g. IPv4AddressSection{}), meaning it was not constructed using a constructor function. Such a grouping, which has no divisions or segments, is convertible to an implicitly zero-valued grouping of any type or version, whether IPv6, IPv4, MAC, or other. In other words, when a section or grouping is the zero-value, then it is equivalent and convertible to the zero value of any other section or grouping type.

func (*AddressSection) IsFullRange 

func (section *AddressSection) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*AddressSection) IsIP 

func (section *AddressSection) IsIP() bool

IsIP returns true if this address section originated as an IPv4 or IPv6 section, or a zero-length IP section. If so, use ToIP to convert back to the IP-specific type.

func (*AddressSection) IsIPv4 

func (section *AddressSection) IsIPv4() bool

IsIPv4 returns true if this address section originated as an IPv4 section. If so, use ToIPv4 to convert back to the IPv4-specific type.

func (*AddressSection) IsIPv6 

func (section *AddressSection) IsIPv6() bool

IsIPv6 returns true if this address section originated as an IPv6 section. If so, use ToIPv6 to convert back to the IPv6-specific type.

func (*AddressSection) IsMAC 

func (section *AddressSection) IsMAC() bool

IsMAC returns true if this address section originated as a MAC section. If so, use ToMAC to convert back to the MAC-specific type.

func (*AddressSection) IsMax 

func (section *AddressSection) IsMax() bool

IsMax returns whether this section matches exactly the maximum possible value, the value whose bits are all ones.

func (*AddressSection) IsMultiple 

func (section *AddressSection) IsMultiple() bool

IsMultiple returns whether this section represents multiple values.

func (*AddressSection) IsOneBit 

func (section *AddressSection) IsOneBit(prefixBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*AddressSection) IsPrefixBlock 

func (section *AddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*AddressSection) IsPrefixed 

func (section *AddressSection) IsPrefixed() bool

IsPrefixed returns whether this section has an associated prefix length.

func (*AddressSection) IsSequential 

func (section *AddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (*AddressSection) IsSinglePrefixBlock 

func (section *AddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from a prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*AddressSection) IsZero 

func (section *AddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero.

func (*AddressSection) Iterator 

func (section *AddressSection) Iterator() Iterator[*AddressSection]

Iterator provides an iterator to iterate through the individual address sections of this address section.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address sections.

Call IsMultiple to determine if this instance represents multiple address sections, or GetCount for the count.

func (*AddressSection) PrefixBlockIterator 

func (section *AddressSection) PrefixBlockIterator() Iterator[*AddressSection]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address section. Each iterated address section will be a prefix block with the same prefix length as this address section.

If this address section has no prefix length, then this is equivalent to Iterator.

func (*AddressSection) PrefixContains 

func (section *AddressSection) PrefixContains(other AddressSectionType) (res bool)

PrefixContains returns whether the prefix values in the given address section are prefix values in this address section, using the prefix length of this section. If this address section has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

All prefix bits of this section must be present in the other section to be comparable.

func (*AddressSection) PrefixEqual 

func (section *AddressSection) PrefixEqual(other AddressSectionType) (res bool)

PrefixEqual determines if the given section matches this section up to the prefix length of this section. It returns whether the argument section has the same address section prefix values as this.

All prefix bits of this section must be present in the other section to be comparable, otherwise false is returned.

func (*AddressSection) PrefixIterator 

func (section *AddressSection) PrefixIterator() Iterator[*AddressSection]

PrefixIterator provides an iterator to iterate through the individual prefixes of this address section, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this address section.

If the series has no prefix length, then this is equivalent to Iterator.

func (*AddressSection) ReverseBits 

func (section *AddressSection) ReverseBits(perByte bool) (*AddressSection, addrerr.IncompatibleAddressError)

ReverseBits returns a new section with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*AddressSection) ReverseBytes 

func (section *AddressSection) ReverseBytes() (*AddressSection, addrerr.IncompatibleAddressError)

ReverseBytes returns a new section with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (*AddressSection) ReverseSegments 

func (section *AddressSection) ReverseSegments() *AddressSection

ReverseSegments returns a new section with the segments reversed.

func (*AddressSection) SetPrefixLen 

func (section *AddressSection) SetPrefixLen(prefixLen BitCount) *AddressSection

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

func (*AddressSection) SetPrefixLenZeroed 

func (section *AddressSection) SetPrefixLenZeroed(prefixLen BitCount) (*AddressSection, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

If this address section has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address section has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*AddressSection) String 

func (section *AddressSection) String() string

String implements the fmt.Stringer interface, returning the normalized string provided by ToNormalizedString, or "<nil>" if the receiver is a nil pointer.

func (*AddressSection) TestBit 

func (section *AddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*AddressSection) ToBinaryString 

func (section *AddressSection) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address section as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*AddressSection) ToBlock 

func (section *AddressSection) ToBlock(segmentIndex int, lower, upper SegInt) *AddressSection

ToBlock creates a new block of address sections by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*AddressSection) ToCanonicalString 

func (section *AddressSection) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address section.

For IPv4, dotted octet format, also known as dotted decimal format, is used. https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

For MAC, it uses the canonical standardized IEEE 802 MAC address representation of xx-xx-xx-xx-xx-xx. An example is "01-23-45-67-89-ab". For range segments, '|' is used: "11-22-33|44-55-66".

func (*AddressSection) ToCompressedString 

func (section *AddressSection) ToCompressedString() string

ToCompressedString produces a short representation of this address section while remaining within the confines of standard representation(s) of the address.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.

For MAC, it differs from the canonical string. It produces a shorter string for the address that has no leading zeros.

func (*AddressSection) ToCustomString 

func (section *AddressSection) ToCustomString(stringOptions addrstr.StringOptions) string

ToCustomString creates a customized string from this address section according to the given string option parameters.

func (*AddressSection) ToDivGrouping 

func (section *AddressSection) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToSectionBase.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSection) ToHexString 

func (section *AddressSection) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address section as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*AddressSection) ToIP 

func (section *AddressSection) ToIP() *IPAddressSection

ToIP converts to an IPAddressSection if this address section originated as an IPv4 or IPv6 section, or an implicitly zero-valued IP section. If not, ToIP returns nil.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSection) ToIPv4 

func (section *AddressSection) ToIPv4() *IPv4AddressSection

ToIPv4 converts to an IPv4AddressSection if this section originated as an IPv4 section. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSection) ToIPv6 

func (section *AddressSection) ToIPv6() *IPv6AddressSection

ToIPv6 converts to an IPv6AddressSection if this section originated as an IPv6 section. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSection) ToMAC 

func (section *AddressSection) ToMAC() *MACAddressSection

ToMAC converts to a MACAddressSection if this section originated as a MAC section. If not, ToMAC returns nil.

ToMAC can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSection) ToNormalizedString 

func (section *AddressSection) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address section.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. Zero-segments are not compressed.

For MAC, it differs from the canonical string. It uses the most common representation of MAC addresses: "xx:xx:xx:xx:xx:xx". An example is "01:23:45:67:89:ab". For range segments, '-' is used: "11:22:33-44:55:66".

func (*AddressSection) ToNormalizedWildcardString added in v1.5.0 

func (section *AddressSection) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but for IP address sections it avoids the CIDR prefix length. Multiple-valued segments will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*AddressSection) ToOctalString 

func (section *AddressSection) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address section as a single octal value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*AddressSection) ToPrefixBlock 

func (section *AddressSection) ToPrefixBlock() *AddressSection

ToPrefixBlock returns the section with the same prefix as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

If this section has no prefix, this section is returned.

func (*AddressSection) ToPrefixBlockLen 

func (section *AddressSection) ToPrefixBlockLen(prefLen BitCount) *AddressSection

ToPrefixBlockLen returns the section with the same prefix of the given length as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

func (*AddressSection) ToSectionBase 

func (section *AddressSection) ToSectionBase() *AddressSection

ToSectionBase is an identity method.

ToSectionBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSection) UpperBytes 

func (section *AddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice.

func (*AddressSection) WithoutPrefixLen 

func (section *AddressSection) WithoutPrefixLen() *AddressSection

WithoutPrefixLen provides the same address section but with no prefix length. The values remain unchanged.

func (*AddressSection) Wrap 

func (section *AddressSection) Wrap() WrappedAddressSection

Wrap wraps this address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections.

type AddressSectionType 

type AddressSectionType interface {
	StandardDivGroupingType

	// Equal returns whether the given address section is equal to this address section.
	// Two address sections are equal if they represent the same set of sections.
	// They must match:
	//  - type/version (IPv4, IPv6, MAC, etc.)
	//  - segment counts
	//  - bits per segment
	//  - segment value ranges
	// Prefix lengths are ignored.
	Equal(AddressSectionType) bool

	// Contains returns whether this is same type and version as the given address section and whether it contains all values in the given section.
	//
	// Sections must also have the same number of segments to be comparable, otherwise false is returned.
	Contains(AddressSectionType) bool

	// PrefixEqual determines if the given section matches this section up to the prefix length of this section.
	// It returns whether the argument section has the same address section prefix values as this.
	//
	// The entire prefix of this section must be present in the other section to be comparable.
	PrefixEqual(AddressSectionType) bool

	// PrefixContains returns whether the prefix values in the given address section
	// are prefix values in this address section, using the prefix length of this section.
	// If this address section has no prefix length, the entire address is compared.
	//
	// It returns whether the prefix of this address contains all values of the same prefix length in the given address.
	//
	// All prefix bits of this section must be present in the other section to be comparable.
	PrefixContains(AddressSectionType) bool

	// ToSectionBase converts to an AddressSection, a polymorphic type usable with all address sections.
	//
	// ToSectionBase implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToSectionBase() *AddressSection
}

AddressSectionType represents any address section that can be converted to/from the base type AddressSection, including AddressSection, IPAddressSection, IPv4AddressSection, IPv6AddressSection, and MACAddressSection.

type AddressSegment 

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

AddressSegment represents a single segment of an address. A segment contains a single value or a range of sequential values and it has an assigned bit length.

The current implementations of this type are the most common representations of IPv4, IPv6 and MAC; segments are 1 byte for Ipv4, they are two bytes for Ipv6, and they are 1 byte for MAC addresses.

There are alternative forms of dividing addresses into divisions, such as the dotted representation for MAC like "1111.2222.3333", the embedded IPv4 representation for IPv6 like "f:f:f:f:f:f:1.2.3.4", the inet_aton formats like "1.2" for IPv4, and so on.

The general rules are that segments have a whole number of bytes, and in a given address all segments have the same length.

When alternatives forms do not follow the general rules for segments, you can use AddressDivision instead. Divisions do not have the restriction that divisions of an address are equal length and a whole number of bytes. Divisions can be grouped using AddressDivisionGrouping.

AddressSegment objects are immutable and thus are also concurrency-safe.

func (*AddressSegment) Bytes 

func (seg *AddressSegment) Bytes() []byte

Bytes returns the lowest value in the address segment range as a byte slice.

func (*AddressSegment) Compare 

func (seg *AddressSegment) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address segment is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*AddressSegment) CompareSize added in v1.3.0 

func (seg *AddressSegment) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual values within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one represents more individual values than another.

CompareSize returns a positive integer if this segment has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*AddressSegment) Contains 

func (seg *AddressSegment) Contains(other AddressSegmentType) bool

Contains returns whether this is same type and version as the given segment and whether it contains all values in the given segment.

func (*AddressSegment) ContainsPrefixBlock 

func (seg *AddressSegment) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the segment range includes the block of values for the given prefix length.

func (*AddressSegment) ContainsSinglePrefixBlock 

func (seg *AddressSegment) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the segment range matches exactly the block of values for the given prefix length and has just a single prefix for that prefix length.

func (*AddressSegment) CopyBytes 

func (seg *AddressSegment) CopyBytes(bytes []byte) []byte

CopyBytes copies the lowest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*AddressSegment) CopyUpperBytes 

func (seg *AddressSegment) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the highest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*AddressSegment) Equal 

func (seg *AddressSegment) Equal(other AddressSegmentType) bool

Equal returns whether the given segment is equal to this segment. Two segments are equal if they match:

  • type/version (IPv4, IPv6, MAC)
  • value range

Prefix lengths are ignored.

func (*AddressSegment) GetBitCount 

func (seg *AddressSegment) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (*AddressSegment) GetByteCount 

func (seg *AddressSegment) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item.

func (*AddressSegment) GetCount 

func (seg *AddressSegment) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1.

For instance, a segment with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*AddressSegment) GetLeadingBitCount added in v1.1.0 

func (seg *AddressSegment) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*AddressSegment) GetLower 

func (seg *AddressSegment) GetLower() *AddressSegment

GetLower returns a segment representing just the lowest value in the range, which will be the same segment if it represents a single value.

func (*AddressSegment) GetMaxValue 

func (seg *AddressSegment) GetMaxValue() SegInt

GetMaxValue gets the maximum possible value for this type or version of segment, determined by the number of bits.

For the highest range value of this particular segment, use GetUpperSegmentValue.

func (*AddressSegment) GetMinPrefixLenForBlock 

func (seg *AddressSegment) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this segment includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this segment represents a single value, this returns the bit count.

func (*AddressSegment) GetPrefixCountLen 

func (seg *AddressSegment) GetPrefixCountLen(segmentPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct prefix values for the given prefix length in the range of values of this segment.

func (*AddressSegment) GetPrefixLenForSingleBlock 

func (seg *AddressSegment) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this segment, and the range of values in this segment matches the block of all values for that prefix.

If the range of segment values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this segment represents a single value, this returns the bit count of the segment.

func (*AddressSegment) GetPrefixValueCountLen 

func (seg *AddressSegment) GetPrefixValueCountLen(segmentPrefixLength BitCount) SegIntCount

GetPrefixValueCountLen returns the same value as GetPrefixCountLen as an integer.

func (*AddressSegment) GetSegmentHostMask added in v1.1.0 

func (seg *AddressSegment) GetSegmentHostMask(networkBits BitCount) SegInt

GetSegmentHostMask returns a value comprising the same number of total bits as the bit-length of this segment, the value that is all zero-bits for the given number of bits followed by all one-bits.

func (*AddressSegment) GetSegmentNetworkMask added in v1.1.0 

func (seg *AddressSegment) GetSegmentNetworkMask(networkBits BitCount) SegInt

GetSegmentNetworkMask returns a value comprising the same number of total bits as the bit-length of this segment, the value that is all one-bits for the given number of bits followed by all zero-bits.

func (*AddressSegment) GetSegmentValue 

func (seg *AddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the segment value range.

func (*AddressSegment) GetString 

func (seg *AddressSegment) GetString() string

GetString produces a normalized string to represent the segment. If the segment is an IP segment string with CIDR network prefix block for its prefix length, then the string contains only the lower value of the block range. Otherwise, the explicit range will be printed. If the segment is not an IP segment, then the string is the same as that produced by GetWildcardString.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*AddressSegment) GetTrailingBitCount added in v1.1.0 

func (seg *AddressSegment) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*AddressSegment) GetUpper 

func (seg *AddressSegment) GetUpper() *AddressSegment

GetUpper returns a segment representing just the highest value in the range, which will be the same segment if it represents a single value.

func (*AddressSegment) GetUpperSegmentValue 

func (seg *AddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the segment value range.

func (*AddressSegment) GetUpperValue 

func (seg *AddressSegment) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address segment range as a big integer.

func (*AddressSegment) GetValue 

func (seg *AddressSegment) GetValue() *BigDivInt

GetValue returns the lowest value in the address segment range as a big integer.

func (*AddressSegment) GetValueCount 

func (seg *AddressSegment) GetValueCount() SegIntCount

GetValueCount returns the same value as GetCount as an integer.

func (*AddressSegment) GetWildcardString 

func (seg *AddressSegment) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters while ignoring any network prefix length. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*AddressSegment) IncludesMax 

func (seg *AddressSegment) IncludesMax() bool

IncludesMax returns whether this segment includes the max value, the value whose bits are all ones, within its range.

func (*AddressSegment) IncludesZero 

func (seg *AddressSegment) IncludesZero() bool

IncludesZero returns whether this segment includes the value of zero within its range.

func (*AddressSegment) IsFullRange 

func (seg *AddressSegment) IsFullRange() bool

IsFullRange returns whether the segment range includes all possible values for its bit length.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*AddressSegment) IsIP 

func (seg *AddressSegment) IsIP() bool

IsIP returns true if this segment originated as an IPv4 or IPv6 segment, or an implicitly zero-valued IP segment. If so, use ToIP to convert back to the IP-specific type.

func (*AddressSegment) IsIPv4 

func (seg *AddressSegment) IsIPv4() bool

IsIPv4 returns true if this segment originated as an IPv4 segment. If so, use ToIPv4 to convert back to the IPv4-specific type.

func (*AddressSegment) IsIPv6 

func (seg *AddressSegment) IsIPv6() bool

IsIPv6 returns true if this segment originated as an IPv6 segment. If so, use ToIPv6 to convert back to the IPv6-specific type.

func (*AddressSegment) IsMAC 

func (seg *AddressSegment) IsMAC() bool

IsMAC returns true if this segment originated as a MAC segment. If so, use ToMAC to convert back to the MAC-specific type.

func (*AddressSegment) IsMax 

func (seg *AddressSegment) IsMax() bool

IsMax returns whether this segment matches exactly the maximum possible value, the value whose bits are all ones.

func (*AddressSegment) IsMultiple 

func (seg *AddressSegment) IsMultiple() bool

IsMultiple returns whether this segment represents multiple values.

func (*AddressSegment) IsOneBit 

func (seg *AddressSegment) IsOneBit(segmentBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*AddressSegment) IsSinglePrefix 

func (seg *AddressSegment) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix determines if the segment has a single prefix value for the given prefix length. You can call GetPrefixCountLen to get the count of prefixes.

func (*AddressSegment) IsZero 

func (seg *AddressSegment) IsZero() bool

IsZero returns whether this segment matches exactly the value of zero.

func (*AddressSegment) Iterator 

func (seg *AddressSegment) Iterator() Iterator[*AddressSegment]

Iterator provides an iterator to iterate through the individual address segments of this address segment.

Call IsMultiple to determine if this instance represents multiple address segments, or GetValueCount for the count.

func (*AddressSegment) Matches 

func (seg *AddressSegment) Matches(value SegInt) bool

Matches returns true if the segment range matches the given single value.

func (*AddressSegment) MatchesValsWithMask 

func (seg *AddressSegment) MatchesValsWithMask(lowerValue, upperValue, mask SegInt) bool

MatchesValsWithMask applies the mask to this segment and then compares the result with the given values, returning true if the range of the resulting segment matches the given range.

func (*AddressSegment) MatchesWithMask 

func (seg *AddressSegment) MatchesWithMask(value, mask SegInt) bool

MatchesWithMask applies the mask to this segment and then compares the result with the given value, returning true if the range of the resulting segment matches that single value.

func (*AddressSegment) PrefixContains 

func (seg *AddressSegment) PrefixContains(other AddressSegmentType, prefixLength BitCount) bool

PrefixContains returns whether the prefix values in the prefix of the given segment are also prefix values in this segment. It returns whether the prefix of this segment contains the prefix of the given segment.

func (*AddressSegment) PrefixEqual 

func (seg *AddressSegment) PrefixEqual(other AddressSegmentType, prefixLength BitCount) bool

PrefixEqual returns whether the prefix bits of this segment match the same bits of the given segment. It returns whether the two segments share the same range of prefix values using the given prefix length.

func (*AddressSegment) ReverseBits 

func (seg *AddressSegment) ReverseBits(perByte bool) (res *AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBits returns a segment with the bits reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*AddressSegment) ReverseBytes 

func (seg *AddressSegment) ReverseBytes() (res *AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBytes returns a segment with the bytes reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

func (*AddressSegment) String 

func (seg *AddressSegment) String() string

String produces a string that is useful when a segment string is provided with no context. If the segment was originally constructed as an IPv4 address segment it uses decimal, otherwise hexadecimal. It uses a string prefix for hex ("0x"), and does not use the wildcard '*', because division size is variable, so '*' is ambiguous. GetWildcardString is more appropriate in context with other segments or divisions. It does not use a string prefix and uses '*' for full-range segments. GetString is more appropriate in context with prefix lengths, it uses zeros instead of wildcards with full prefix block ranges alongside prefix lengths.

func (*AddressSegment) TestBit 

func (seg *AddressSegment) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*AddressSegment) ToDiv 

func (seg *AddressSegment) ToDiv() *AddressDivision

ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions. Afterwards, you can convert back with ToSegmentBase.

ToDiv can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSegment) ToHexString 

func (seg *AddressSegment) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address segment as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

For segments, the error is always nil.

func (*AddressSegment) ToIP 

func (seg *AddressSegment) ToIP() *IPAddressSegment

ToIP converts to an IPAddressSegment if this division originated as an IPv4 or IPv6 segment, or an implicitly zero-valued IP segment. If not, ToIP returns nil.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSegment) ToIPv4 

func (seg *AddressSegment) ToIPv4() *IPv4AddressSegment

ToIPv4 converts to an IPv4AddressSegment if this segment originated as an IPv4 segment. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSegment) ToIPv6 

func (seg *AddressSegment) ToIPv6() *IPv6AddressSegment

ToIPv6 converts to an IPv6AddressSegment if this segment originated as an IPv6 segment. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSegment) ToMAC 

func (seg *AddressSegment) ToMAC() *MACAddressSegment

ToMAC converts to a MACAddressSegment if this segment originated as a MAC segment. If not, ToMAC returns nil.

ToMAC can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSegment) ToNormalizedString 

func (seg *AddressSegment) ToNormalizedString() string

ToNormalizedString produces a string that is consistent for all address segments of the same type and version. IPv4 segments use base 10, while other segment types use base 16.

func (*AddressSegment) ToSegmentBase 

func (seg *AddressSegment) ToSegmentBase() *AddressSegment

ToSegmentBase is an identity method.

ToSegmentBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*AddressSegment) UpperBytes 

func (seg *AddressSegment) UpperBytes() []byte

UpperBytes returns the highest value in the address segment range as a byte slice.

type AddressSegmentSeries 

type AddressSegmentSeries interface {
	AddressComponent

	AddressDivisionSeries

	// GetMaxSegmentValue returns the maximum possible segment value for this type of series.
	//
	// Note this is not the maximum of the range of segment values in this specific series,
	// this is the maximum value of any segment for this series type and version, determined by the number of bits per segment.
	GetMaxSegmentValue() SegInt

	// GetSegmentCount returns the number of segments, which is the same as the division count since the segments are also the divisions
	GetSegmentCount() int

	// GetBitsPerSegment returns the number of bits comprising each segment in this series.  Segments in the same series are equal length.
	GetBitsPerSegment() BitCount

	// GetBytesPerSegment returns the number of bytes comprising each segment in this series.  Segments in the same series are equal length.
	GetBytesPerSegment() int

	// ToCanonicalString produces a canonical string for the address series.
	//
	// For IPv4, dotted octet format, also known as dotted decimal format, is used.
	// https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1
	//
	// For IPv6, RFC 5952 describes the canonical string representation.
	// https://en.wikipedia.org/wiki/IPv6_address#Representation
	// http://tools.ietf.org/html/rfc5952
	//
	// For MAC, it uses the canonical standardized IEEE 802 MAC address representation of xx-xx-xx-xx-xx-xx.  An example is "01-23-45-67-89-ab".
	// For range segments, '|' is used: "11-22-33|44-55-66".
	//
	// Each address has a unique canonical string, not counting the prefix length.
	// With IP addresses and sections, the prefix length is included in the string, and the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4".
	// It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*".
	ToCanonicalString() string

	// ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length in the case of IP addresses.
	// Multiple-valued segments will be shown with wildcards and ranges (denoted by '*' and '-').
	ToNormalizedWildcardString() string

	// ToCompressedString produces a short representation of this series while remaining within the confines of standard representation(s) of the series.
	//
	// For IPv4, it is the same as the canonical string.
	//
	// For IPv6, it differs from the canonical string.  It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.
	//
	// For MAC, it differs from the canonical string.  It produces a shorter string for the address that has no leading zeros.
	ToCompressedString() string

	// ToBinaryString writes this address series as a single binary value (possibly two values if a range that is not a prefixed block),
	// the number of digits according to the bit count, with or without a preceding "0b" prefix.
	//
	// If a multiple-valued series cannot be written as a single prefix block or a range of two values, an error is returned.
	ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

	// ToOctalString writes this address series as a single octal value (possibly two values if a range that is not a prefixed block),
	// the number of digits according to the bit count, with or without a preceding "0" prefix.
	//
	// If a multiple-valued series cannot be written as a single prefix block or a range of two values, an error is returned.
	ToOctalString(withPrefix bool) (string, addrerr.IncompatibleAddressError)

	// GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.
	GetSegmentStrings() []string

	// GetGenericSegment returns the segment at the given index as an AddressSegmentType.
	// The first segment is at index 0.
	// GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.
	GetGenericSegment(index int) AddressSegmentType
}

AddressSegmentSeries serves as a common interface to all address sections and addresses.

type AddressSegmentType 

type AddressSegmentType interface {
	AddressComponent

	StandardDivisionType

	// Equal returns whether the given segment is equal to this segment.
	// Two segments are equal if they match:
	//  - type/version (IPv4, IPv6, MAC)
	//  - value range
	// Prefix lengths are ignored.
	Equal(AddressSegmentType) bool

	// Contains returns whether this segment is same type and version as the given segment and whether it contains all values in the given segment.
	Contains(AddressSegmentType) bool

	// GetSegmentValue returns the lower value of the segment value range as a SegInt.
	GetSegmentValue() SegInt

	// GetUpperSegmentValue returns the upper value of the segment value range as a SegInt.
	GetUpperSegmentValue() SegInt

	// ToSegmentBase converts to an AddressSegment, a polymorphic type usable with all address segments.
	//
	// ToSegmentBase implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToSegmentBase() *AddressSegment
}

AddressSegmentType serves as a common interface to all segments, including AddressSegment, IPAddressSegment, IPv6AddressSegment, IPv4AddressSegment and MACAddressSegment.

type AddressTrie added in v1.1.0 

type AddressTrie = Trie[*Address]

type AddressType 

type AddressType interface {
	AddressSegmentSeries

	// Equal returns whether the given address or subnet is equal to this address or subnet.
	// Two address instances are equal if they represent the same set of addresses.
	Equal(AddressType) bool

	// Contains returns whether this is same type and version as the given address or subnet and whether it contains all addresses in the given address or subnet.
	Contains(AddressType) bool

	// PrefixEqual determines if the given address matches this address up to the prefix length of this address.
	// If this address has no prefix length, the entire address is compared.
	//
	// It returns whether the two addresses share the same range of prefix values.
	PrefixEqual(AddressType) bool

	// PrefixContains returns whether the prefix values in the given address or subnet
	// are prefix values in this address or subnet, using the prefix length of this address or subnet.
	// If this address has no prefix length, the entire address is compared.
	//
	// It returns whether the prefix of this address contains all values of the same prefix length in the given address.
	PrefixContains(AddressType) bool

	// ToAddressBase converts to an Address, a polymorphic type usable with all addresses and subnets.
	//
	// ToAddressBase implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToAddressBase() *Address
}

AddressType represents any address, all of which can be represented by the base type Address. This includes IPAddress, IPv4Address, IPv6Address, and MACAddress. You must use the pointer types *Address, *IPAddress, *IPv4Address, *IPv6Address, and *MACAddress when implementing AddressType. It can be useful as a parameter for functions to take any address type, while inside the function you can convert to Address using ToAddressBase.

type AddressValueProvider 

type AddressValueProvider interface {
	GetSegmentCount() int

	GetValues() SegmentValueProvider

	GetUpperValues() SegmentValueProvider
}

AddressValueProvider provides values for addresses.

type AllocatedBlock added in v1.5.0 

type AllocatedBlock[T AddressType] struct {
	// contains filtered or unexported fields
}

AllocatedBlock represents a block of addresses allocated for assignment to hosts.

func (AllocatedBlock[T]) GetAddress added in v1.5.0 

func (alloc AllocatedBlock[T]) GetAddress() T

GetAddress returns the block.

func (AllocatedBlock[T]) GetCount added in v1.5.0 

func (alloc AllocatedBlock[T]) GetCount() *big.Int

GetCount returns the total number of addresses within the block.

func (AllocatedBlock[T]) GetReservedCount added in v1.5.0 

func (alloc AllocatedBlock[T]) GetReservedCount() int

GetReservedCount returns the number of reserved addresses with the block.

func (AllocatedBlock[T]) GetSize added in v1.5.0 

func (alloc AllocatedBlock[T]) GetSize() *big.Int

GetSize returns the number of hosts for which this block was allocated.

func (AllocatedBlock[T]) String added in v1.5.0 

func (alloc AllocatedBlock[T]) String() string

String returns a string representation of the allocated block.

type AssociativeAddedTree added in v1.5.0 

type AssociativeAddedTree[T TrieKeyConstraint[T], V any] struct {
	// contains filtered or unexported fields
}

AssociativeAddedTree is similar to AddedTree but originates from an AssociativeTrie. The nodes of this tree have the same values as the corresponding nodes in the original trie.

func (AssociativeAddedTree[T, V]) GetRoot added in v1.5.0 

func (atree AssociativeAddedTree[T, V]) GetRoot() AssociativeAddedTreeNode[T, V]

GetRoot returns the root of this tree, which corresponds to the root of the originating trie.

func (AssociativeAddedTree[T, V]) String added in v1.5.0 

func (atree AssociativeAddedTree[T, V]) String() string

String returns a string representation of the tree, which is the same as the string obtained from the AddedNodesTreeString method of the originating trie.

type AssociativeAddedTreeNode added in v1.5.0 

type AssociativeAddedTreeNode[T TrieKeyConstraint[T], V any] struct {
	// contains filtered or unexported fields
}

AssociativeAddedTreeNode represents a node in an AssociativeAddedTree.

func (AssociativeAddedTreeNode[T, V]) GetKey added in v1.5.0 

func (node AssociativeAddedTreeNode[T, V]) GetKey() T

GetKey returns the key of this node, which is the same as the key of the corresponding node in the originating trie.

func (AssociativeAddedTreeNode[T, V]) GetSubNodes added in v1.5.0 

func (node AssociativeAddedTreeNode[T, V]) GetSubNodes() []AssociativeAddedTreeNode[T, V]

GetSubNodes returns the sub-nodes of this node, which are not the same as the 0, 1 or 2 direct sub-nodes of the originating binary trie. Instead, these are all direct or indirect added sub-nodes of the node. If you can traverse from this node to another node in the originating trie, using a sequence of sub-nodes, without any intervening sub-node being an added node, then that other node will appear as a sub-node here.

func (AssociativeAddedTreeNode[T, V]) GetValue added in v1.5.0 

func (node AssociativeAddedTreeNode[T, V]) GetValue() V

GetValue returns the value of this node, which is the same as the value of the corresponding node in the originating trie.

func (AssociativeAddedTreeNode[T, V]) IsAdded added in v1.5.3 

func (node AssociativeAddedTreeNode[T, V]) IsAdded() bool

IsAdded returns if the node was an added node in the original trie. This returns true for all nodes except possibly the root, since only added nodes are added to this tree, apart from the root.

func (AssociativeAddedTreeNode[T, V]) String added in v1.5.0 

func (node AssociativeAddedTreeNode[T, V]) String() string

String returns a visual representation of this node including the key and the value. If this is the root, it will have an open circle if the root is not an added node. Otherwise, the node will have a closed circle.

func (AssociativeAddedTreeNode[T, V]) TreeString added in v1.5.0 

func (node AssociativeAddedTreeNode[T, V]) TreeString() string

TreeString returns a visual representation of the sub-tree originating from this node, with one node per line.

type AssociativeAddressTrie added in v1.1.0 

type AssociativeAddressTrie = AssociativeTrie[*Address, any]

type AssociativeTrie added in v1.5.0 

type AssociativeTrie[T TrieKeyConstraint[T], V any] struct {
	// contains filtered or unexported fields
}

AssociativeTrie represents a binary address trie in which each added node can be associated with a value. It is an instance of Trie that can also function as a key-value map. The keys are addresses or prefix blocks. Each can be mapped to a value with type specified by the generic type V.

For the generic type T, you can choose *Address, *IPAddress, *IPv4Address, *IPv6Address, or *MACAddress. The generic value type V can be any type of your choosing.

All the characteristics of Trie are common to AssociativeTrie.

The zero value is a binary trie ready for use.

func NewAssociativeTrie added in v1.5.0 

func NewAssociativeTrie[T TrieKeyConstraint[T], V any]() *AssociativeTrie[T, V]

NewAssociativeTrie constructs an associative address trie for the given types, without a root.

func NewIPv4AddressAssociativeTrie added in v1.1.0 

func NewIPv4AddressAssociativeTrie() *AssociativeTrie[*IPv4Address, any]

NewIPv4AddressAssociativeTrie constructs an IPv4 associative address trie with the root as the 0.0.0.0/0 prefix block This is here for backwards compatibility. Using NewAssociativeTrie is recommended instead.

func NewIPv6AddressAssociativeTrie added in v1.1.0 

func NewIPv6AddressAssociativeTrie() *AssociativeTrie[*IPv6Address, any]

NewIPv6AddressAssociativeTrie constructs an IPv6 associative address trie with the root as the ::/0 prefix block This is here for backwards compatibility. Using NewAssociativeTrie is recommended instead.

func NewMACAddressAssociativeTrie added in v1.1.0 

func NewMACAddressAssociativeTrie(extended bool) *AssociativeTrie[*MACAddress, any]

NewMACAddressAssociativeTrie constructs a MAC associative address trie with the root as the zero-prefix prefix block This is here for backwards compatibility. Using NewAssociativeTrie is recommended instead.

func (*AssociativeTrie[T, V]) Add added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Add(addr T) bool

Add adds the address to this trie. Returns true if the address did not already exist in the trie.

func (*AssociativeTrie[T, V]) AddNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) AddNode(addr T) *AssociativeTrieNode[T, V]

AddNode adds the address key to this trie. The new or existing node for the address is returned.

func (*AssociativeTrie[T, V]) AddTrie added in v1.5.0 

func (trie *AssociativeTrie[T, V]) AddTrie(added *AssociativeTrieNode[T, V]) *AssociativeTrieNode[T, V]

AddTrie adds nodes for the keys in the trie with the root node as the passed in node. To add both keys and values, use PutTrie. AddTrie returns the sub-node in the trie where the added trie begins, where the first node of the added trie is located.

func (*AssociativeTrie[T, V]) AddedNodesTreeString added in v1.5.0 

func (trie *AssociativeTrie[T, V]) AddedNodesTreeString() string

AddedNodesTreeString provides a flattened version of the trie showing only the contained added nodes and their containment structure, which is non-binary. The root node is included, which may or may not be added.

func (*AssociativeTrie[T, V]) AllNodeIterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) AllNodeIterator(forward bool) IteratorWithRemove[*AssociativeTrieNode[T, V]]

AllNodeIterator returns an iterator that iterates through all the nodes in the trie in forward or reverse tree order.

func (*AssociativeTrie[T, V]) BlockSizeAllNodeIterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IteratorWithRemove[*AssociativeTrieNode[T, V]]

BlockSizeAllNodeIterator returns an iterator that iterates all nodes in the trie, ordered by keys from largest prefix blocks to smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*AssociativeTrie[T, V]) BlockSizeCachingAllNodeIterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) BlockSizeCachingAllNodeIterator() CachingTrieIterator[*AssociativeTrieNode[T, V]]

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from largest prefix blocks to smallest, and then to individual addresses.

func (*AssociativeTrie[T, V]) BlockSizeNodeIterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) BlockSizeNodeIterator(lowerSubNodeFirst bool) IteratorWithRemove[*AssociativeTrieNode[T, V]]

BlockSizeNodeIterator returns an iterator that iterates the added nodes in the trie, ordered by keys from largest prefix blocks to smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*AssociativeTrie[T, V]) CeilingAddedNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) CeilingAddedNode(addr T) *AssociativeTrieNode[T, V]

CeilingAddedNode returns the added node whose address is the lowest address greater than or equal to the given address, or nil if there are no added entries in this trie.

func (*AssociativeTrie[T, V]) Clear added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Clear()

Clear removes all added nodes from the trie, after which IsEmpty will return true.

func (*AssociativeTrie[T, V]) Clone added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Clone() *AssociativeTrie[T, V]

Clone clones this trie.

func (*AssociativeTrie[T, V]) ConstructAddedNodesTree added in v1.5.0 

func (trie *AssociativeTrie[T, V]) ConstructAddedNodesTree() AssociativeAddedTree[T, V]

ConstructAddedNodesTree provides an associative trie in which the root and each added node are mapped to a list of their respective direct added sub-nodes. This trie provides an alternative non-binary tree structure of the added nodes. It is used by ToAddedNodesTreeString to produce a string showing the alternative structure. The returned AddedTree instance wraps the associative trie, presenting it as a non-binary tree with the alternative tree structure, the structure in which each node's child nodes are the list of direct and indirect added child nodes in the original trie. If there are no non-added nodes in this trie, then the alternative tree structure provided by this method is the same as the original trie.

func (*AssociativeTrie[T, V]) ContainedFirstAllNodeIterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) Iterator[*AssociativeTrieNode[T, V]]

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary trie traversal. All sub-nodes will be visited before their parent nodes. For an address trie this means contained addresses and subnets will be visited before their containing subnet blocks.

func (*AssociativeTrie[T, V]) ContainedFirstIterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) ContainedFirstIterator(forwardSubNodeOrder bool) IteratorWithRemove[*AssociativeTrieNode[T, V]]

ContainedFirstIterator returns an iterator that does a post-order binary trie traversal of the added nodes. All added sub-nodes will be visited before their parent nodes. For an address trie this means contained addresses and subnets will be visited before their containing subnet blocks.

func (*AssociativeTrie[T, V]) ContainingFirstAllNodeIterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingTrieIterator[*AssociativeTrieNode[T, V]]

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary trie traversal. All nodes will be visited before their sub-nodes. For an address trie this means containing subnet blocks will be visited before their contained addresses and subnet blocks.

Once a given node is visited, the iterator allows you to cache an object corresponding to the lower or upper sub-node that can be retrieved when you later visit that sub-node. That allows you to provide iteration context from a parent to its sub-nodes when iterating. The caching and retrieval is done in constant-time.

func (*AssociativeTrie[T, V]) ContainingFirstIterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) ContainingFirstIterator(forwardSubNodeOrder bool) CachingTrieIterator[*AssociativeTrieNode[T, V]]

ContainingFirstIterator returns an iterator that does a pre-order binary trie traversal of the added nodes. All added nodes will be visited before their added sub-nodes. For an address trie this means added containing subnet blocks will be visited before their added contained addresses and subnet blocks.

Once a given node is visited, the iterator allows you to cache an object corresponding to the lower or upper sub-node that can be retrieved when you later visit that sub-node.

Objects are cached only with nodes to be visited. So for this iterator that means an object will be cached with the first added lower or upper sub-node, the next lower or upper sub-node to be visited, which is not necessarily the direct lower or upper sub-node of a given node.

The caching allows you to provide iteration context from a parent to its sub-nodes when iterating. The caching and retrieval is done in constant-time.

func (*AssociativeTrie[T, V]) Contains added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Contains(addr T) bool

Contains returns whether the given address or prefix block subnet is in the trie as an added element.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the prefix block or address exists already in the trie, false otherwise.

Use GetAddedNode to get the node for the address rather than just checking for its existence.

func (*AssociativeTrie[T, V]) DeepEqual added in v1.5.0 

func (trie *AssociativeTrie[T, V]) DeepEqual(other *AssociativeTrie[T, V]) bool

DeepEqual returns whether the given argument is a trie with a set of nodes with the same keys and values as in this trie, the values being compared with reflect.DeepEqual.

func (*AssociativeTrie[T, V]) DescendingIterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) DescendingIterator() Iterator[T]

DescendingIterator returns an iterator that iterates through the added addresses and prefix blocks in the trie. The iteration is in reverse sorted element order.

func (*AssociativeTrie[T, V]) ElementContains added in v1.5.0 

func (trie *AssociativeTrie[T, V]) ElementContains(addr T) bool

ElementContains checks if a prefix block subnet or address in the trie contains the given subnet or address.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the subnet or address is contained by a trie element, false otherwise.

To get all the containing addresses, use ElementsContaining.

func (*AssociativeTrie[T, V]) ElementsContainedBy added in v1.5.0 

func (trie *AssociativeTrie[T, V]) ElementsContainedBy(addr T) *AssociativeTrieNode[T, V]

ElementsContainedBy checks if a part of this trie is contained by the given prefix block subnet or individual address.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the root node of the contained sub-trie, or nil if no sub-trie is contained. The node returned need not be an "added" node, see IsAdded for more details on added nodes. The returned sub-trie is backed by this trie, so changes in this trie are reflected in those nodes and vice-versa.

func (*AssociativeTrie[T, V]) ElementsContaining added in v1.5.0 

func (trie *AssociativeTrie[T, V]) ElementsContaining(addr T) *ContainmentValuesPath[T, V]

ElementsContaining finds the trie nodes in the trie containing the given key and returns them as a linked list. Only added nodes are added to the linked list.

If the argument is not a single address nor prefix block, this method will panic.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

func (*AssociativeTrie[T, V]) Equal added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Equal(other *AssociativeTrie[T, V]) bool

Equal returns whether the given argument is a trie with a set of nodes with the same keys as in this trie.

func (*AssociativeTrie[T, V]) FirstAddedNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) FirstAddedNode() *AssociativeTrieNode[T, V]

FirstAddedNode returns the first (lowest-valued) added node in the trie or nil if there are no added entries in this trie.

func (*AssociativeTrie[T, V]) FirstNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) FirstNode() *AssociativeTrieNode[T, V]

FirstNode returns the first (lowest-valued) node in the trie or nil if the trie is empty.

func (*AssociativeTrie[T, V]) FloorAddedNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) FloorAddedNode(addr T) *AssociativeTrieNode[T, V]

FloorAddedNode returns the added node whose address is the highest address less than or equal to the given address, or nil if there are no added entries in this trie.

func (AssociativeTrie[T, V]) Format added in v1.5.0 

func (trie AssociativeTrie[T, V]) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface.

func (*AssociativeTrie[T, V]) Get added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Get(addr T) (V, bool)

Get gets the value for the specified key in this mapped trie or sub-trie.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the value for the given key. Returns nil if the contains no mapping for that key or if the mapped value is nil.

func (*AssociativeTrie[T, V]) GetAddedNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) GetAddedNode(addr T) *AssociativeTrieNode[T, V]

GetAddedNode gets trie nodes representing added elements.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Use Contains to check for the existence of a given address in the trie, as well as GetNode to search for all nodes including those not added but also auto-generated nodes for subnet blocks.

func (*AssociativeTrie[T, V]) GetNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) GetNode(addr T) *AssociativeTrieNode[T, V]

GetNode gets the node in the trie corresponding to the given address, or returns nil if not such element exists.

It returns any node, whether added or not, including any prefix block node that was not added.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

func (*AssociativeTrie[T, V]) GetRoot added in v1.5.0 

func (trie *AssociativeTrie[T, V]) GetRoot() *AssociativeTrieNode[T, V]

GetRoot returns the root node of this trie, which can be nil for an implicitly zero-valued uninitialized trie, but not for any other trie.

func (*AssociativeTrie[T, V]) HigherAddedNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) HigherAddedNode(addr T) *AssociativeTrieNode[T, V]

HigherAddedNode returns the added node whose address is the lowest address strictly greater than the given address, or nil if there are no added entries in this trie.

func (*AssociativeTrie[T, V]) IsEmpty added in v1.5.0 

func (trie *AssociativeTrie[T, V]) IsEmpty() bool

IsEmpty returns true if there are not any added nodes within this tree.

func (*AssociativeTrie[T, V]) Iterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Iterator() Iterator[T]

Iterator returns an iterator that iterates through the added addresses and prefix blocks in the trie. The iteration is in sorted element order.

func (*AssociativeTrie[T, V]) LastAddedNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) LastAddedNode() *AssociativeTrieNode[T, V]

LastAddedNode returns the last (highest-valued) added node in the sub-trie originating from this node, or nil if there are no added entries in this trie.

func (*AssociativeTrie[T, V]) LastNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) LastNode() *AssociativeTrieNode[T, V]

LastNode returns the last (highest-valued) node in the trie or nil if the trie is empty.

func (*AssociativeTrie[T, V]) LongestPrefixMatch added in v1.5.0 

func (trie *AssociativeTrie[T, V]) LongestPrefixMatch(addr T) T

LongestPrefixMatch returns the address with the longest matching prefix compared to the provided address.

func (*AssociativeTrie[T, V]) LongestPrefixMatchNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) LongestPrefixMatchNode(addr T) *AssociativeTrieNode[T, V]

LongestPrefixMatchNode returns the node of the address with the longest matching prefix compared to the provided address.

func (*AssociativeTrie[T, V]) LowerAddedNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) LowerAddedNode(addr T) *AssociativeTrieNode[T, V]

LowerAddedNode returns the added node whose address is the highest address strictly less than the given address, or nil if there are no added entries in this trie.

func (*AssociativeTrie[T, V]) NodeIterator added in v1.5.0 

func (trie *AssociativeTrie[T, V]) NodeIterator(forward bool) IteratorWithRemove[*AssociativeTrieNode[T, V]]

NodeIterator returns an iterator that iterates through all the added nodes in the trie in forward or reverse tree order.

func (*AssociativeTrie[T, V]) NodeSize added in v1.5.0 

func (trie *AssociativeTrie[T, V]) NodeSize() int

NodeSize returns the number of nodes in the tree, which is always more than the number of elements.

func (*AssociativeTrie[T, V]) Put added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Put(addr T, value V) (V, bool)

Put associates the specified value with the specified key in this map.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

If this map previously contained a mapping for a key, the old value is replaced by the specified value, and false is returned along with the old value. If this map did not previously contain a mapping for the key, true is returned along with a nil value. The boolean return value allows you to distinguish whether the address was previously mapped to nil or not mapped at all.

func (*AssociativeTrie[T, V]) PutNode added in v1.5.0 

func (trie *AssociativeTrie[T, V]) PutNode(addr T, value V) *AssociativeTrieNode[T, V]

PutNode associates the specified value with the specified key in this map.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the node for the added address, whether it was already in the trie or not.

If you wish to know whether the node was already there when adding, use PutNew, or before adding you can use GetAddedNode.

func (*AssociativeTrie[T, V]) PutTrie added in v1.5.0 

func (trie *AssociativeTrie[T, V]) PutTrie(added *AssociativeTrieNode[T, V]) *AssociativeTrieNode[T, V]

PutTrie adds nodes for the address keys and values in the trie with the root node as the passed in node. To add only the keys, use AddTrie.

For each added in the given node that does not exist in the trie, a copy of each node will be made, the copy including the associated value, and the copy will be inserted into the trie.

The address type/version of the keys must match.

When adding one trie to another, this method is more efficient than adding each node of the first trie individually. When using this method, searching for the location to add sub-nodes starts from the inserted parent node.

Returns the node corresponding to the given sub-root node, whether it was already in the trie or not.

func (*AssociativeTrie[T, V]) Remap added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Remap(addr T, remapper func(existingValue V, found bool) (mapped V, mapIt bool)) *AssociativeTrieNode[T, V]

Remap remaps node values in the trie.

This will look up the node corresponding to the given key. It will call the remapping function, regardless of whether the node is found or not.

If the node is not found, or the node is not an "added" node, the existingValue argument will be the zero value. If the node is found, the existingValue argument will be the node's value, which can also be the zero value. The boolean "found" argument will be true if the node was found and it is an "added" node. If the node was not found or was not an "added" node, then the boolean "found" argument will be false.

If the remapping function returns false as the "mapIt" argument, then the matched node will be removed or converted to a "non-added" node, if any. If it returns true, then either the existing node will be set to an "added" node with the "mapped" value given as the first argument, or if there was no matched node, it will create a new added node with the "mapped" value.

The method will return the node involved, which is either the matched node, or the newly created node, or nil if there was no matched node nor newly created node.

If the remapping function modifies the trie during its computation, and the returned values from the remapper requires changes to be made to the trie, then the trie will not be changed as required by the remapper, and Remap will panic.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

func (*AssociativeTrie[T, V]) RemapIfAbsent added in v1.5.0 

func (trie *AssociativeTrie[T, V]) RemapIfAbsent(addr T, supplier func() V) *AssociativeTrieNode[T, V]

RemapIfAbsent remaps node values in the trie, but only for nodes that do not exist or are not "added".

This will look up the node corresponding to the given key. If the node is not found or not "added", then RemapIfAbsent will call the supplier function. It will create a new node with the value returned from the supplier function. If the node is found and "added", then RemapIfAbsent will not call the supplier function.

The method will return the node involved, which is either the matched node, the newly created node, or nil if there was no matched node nor newly created node.

If the supplier function modifies the trie during its computation, then the trie will not be changed and RemapIfAbsent will panic.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

func (*AssociativeTrie[T, V]) Remove added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Remove(addr T) bool

Remove removes the given single address or prefix block subnet from the trie.

Removing an element will not remove contained elements (nodes for contained blocks and addresses).

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the prefix block or address was removed, false if not already in the trie.

You can also remove by calling GetAddedNode to get the node and then calling Remove on the node.

When an address is removed, the corresponding node may remain in the trie if it remains a subnet block for two sub-nodes. If the corresponding node can be removed from the trie, it will be removed.

func (*AssociativeTrie[T, V]) RemoveElementsContainedBy added in v1.5.0 

func (trie *AssociativeTrie[T, V]) RemoveElementsContainedBy(addr T) *AssociativeTrieNode[T, V]

RemoveElementsContainedBy removes any single address or prefix block subnet from the trie that is contained in the given individual address or prefix block subnet.

This goes further than Remove, not requiring a match to an inserted node, and also removing all the sub-nodes of any removed node or sub-node.

For example, after inserting 1.2.3.0 and 1.2.3.1, passing 1.2.3.0/31 to RemoveElementsContainedBy will remove them both, while the Remove method will remove nothing. After inserting 1.2.3.0/31, then Remove will remove 1.2.3.0/31, but will leave 1.2.3.0 and 1.2.3.1 in the trie.

It cannot partially delete a node, such as deleting a single address from a prefix block represented by a node. It can only delete the whole node if the whole address or block represented by that node is contained in the given address or block.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the root node of the sub-trie that was removed from the trie, or nil if nothing was removed.

func (*AssociativeTrie[T, V]) Size added in v1.5.0 

func (trie *AssociativeTrie[T, V]) Size() int

Size returns the number of elements in the tree. It does not return the number of nodes. Only nodes for which IsAdded returns true are counted (those nodes corresponding to added addresses and prefix blocks). When zero is returned, IsEmpty returns true.

func (*AssociativeTrie[T, V]) String added in v1.5.0 

func (trie *AssociativeTrie[T, V]) String() string

String returns a visual representation of the tree with one node per line.

func (*AssociativeTrie[T, V]) TreeString added in v1.5.0 

func (trie *AssociativeTrie[T, V]) TreeString(withNonAddedKeys bool) string

TreeString returns a visual representation of the tree with one node per line, with or without the non-added keys.

type AssociativeTrieNode added in v1.5.0 

type AssociativeTrieNode[T TrieKeyConstraint[T], V any] struct {
	// contains filtered or unexported fields
}

AssociativeTrieNode represents a node of an associative compact binary prefix trie. Each key is a prefix block subnet or address. Each node also has an associated value.

func (*AssociativeTrieNode[T, V]) AllNodeIterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) AllNodeIterator(forward bool) IteratorWithRemove[*AssociativeTrieNode[T, V]]

AllNodeIterator returns an iterator that iterates through all the nodes of the sub-trie with this node as the root, in forward or reverse trie order.

func (*AssociativeTrieNode[T, V]) AsNewTrie added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) AsNewTrie() *AssociativeTrie[T, V]

AsNewTrie creates a new sub-trie, copying the nodes starting with this node as the root. The nodes are copies of the nodes in this sub-trie, but their keys and values are not copies.

func (*AssociativeTrieNode[T, V]) BlockSizeAllNodeIterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IteratorWithRemove[*AssociativeTrieNode[T, V]]

BlockSizeAllNodeIterator returns an iterator that iterates all the nodes, ordered by keys from largest prefix blocks to smallest and then to individual addresses, in the sub-trie with this node as the root.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order.

func (*AssociativeTrieNode[T, V]) BlockSizeCachingAllNodeIterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) BlockSizeCachingAllNodeIterator() CachingTrieIterator[*AssociativeTrieNode[T, V]]

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from largest prefix blocks to smallest and then to individual addresses, in the sub-trie with this node as the root.

func (*AssociativeTrieNode[T, V]) BlockSizeNodeIterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) BlockSizeNodeIterator(lowerSubNodeFirst bool) IteratorWithRemove[*AssociativeTrieNode[T, V]]

BlockSizeNodeIterator returns an iterator that iterates the added nodes, ordered by keys from largest prefix blocks to smallest and then to individual addresses, in the sub-trie with this node as the root.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order is taken.

func (*AssociativeTrieNode[T, V]) CeilingAddedNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) CeilingAddedNode(addr T) *AssociativeTrieNode[T, V]

CeilingAddedNode returns the added node, in this sub-trie with this node as the root, whose address is the lowest address greater than or equal to the given address.

func (*AssociativeTrieNode[T, V]) Clear added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) Clear()

Clear removes this node and all sub-nodes from the tree, after which isEmpty will return true.

func (*AssociativeTrieNode[T, V]) ClearValue added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) ClearValue()

ClearValue makes the value associated with this node the zero-value of V.

func (*AssociativeTrieNode[T, V]) Clone added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) Clone() *AssociativeTrieNode[T, V]

Clone clones the node. Keys remain the same, but the parent node and the lower and upper sub-nodes are all set to nil.

func (*AssociativeTrieNode[T, V]) CloneTree added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) CloneTree() *AssociativeTrieNode[T, V]

CloneTree clones the sub-trie starting with this node as the root. The nodes are cloned, but their keys and values are not cloned.

func (*AssociativeTrieNode[T, V]) Compare added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) Compare(other *AssociativeTrieNode[T, V]) int

Compare returns a negative integer, zero, or a positive integer if this node is less than, equal, or greater than the other, according to the key and the trie order.

func (*AssociativeTrieNode[T, V]) ContainedFirstAllNodeIterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) Iterator[*AssociativeTrieNode[T, V]]

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary trie traversal of all the nodes of the sub-trie with this node as the root. All sub-nodes will be visited before their parent nodes. For an address trie this means contained addresses and subnets will be visited before their containing subnet blocks.

func (*AssociativeTrieNode[T, V]) ContainedFirstIterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) ContainedFirstIterator(forwardSubNodeOrder bool) IteratorWithRemove[*AssociativeTrieNode[T, V]]

ContainedFirstIterator returns an iterator that does a post-order binary trie traversal of the added nodes of the sub-trie with this node as the root. All added sub-nodes will be visited before their parent nodes. For an address trie this means contained addresses and subnets will be visited before their containing subnet blocks.

func (*AssociativeTrieNode[T, V]) ContainingFirstAllNodeIterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingTrieIterator[*AssociativeTrieNode[T, V]]

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary trie traversal of all the nodes of the sub-trie with this node as the root.

All nodes will be visited before their sub-nodes. For an address trie this means containing subnet blocks will be visited before their contained addresses and subnet blocks.

Once a given node is visited, the iterator allows you to cache an object corresponding to the lower or upper sub-node that can be retrieved when you later visit that sub-node. That allows you to provide iteration context from a parent to its sub-nodes when iterating. The caching and retrieval is done in constant-time.

func (*AssociativeTrieNode[T, V]) ContainingFirstIterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) ContainingFirstIterator(forwardSubNodeOrder bool) CachingTrieIterator[*AssociativeTrieNode[T, V]]

ContainingFirstIterator returns an iterator that does a pre-order binary trie traversal of the added nodes of the sub-trie with this node as the root.

All added nodes will be visited before their added sub-nodes. For an address trie this means added containing subnet blocks will be visited before their added contained addresses and subnet blocks.

Once a given node is visited, the iterator allows you to cache an object corresponding to the lower or upper sub-node that can be retrieved when you later visit that sub-node.

Objects are cached only with nodes to be visited. So for this iterator that means an object will be cached with the first added lower or upper sub-node, the next lower or upper sub-node to be visited, which is not necessarily the direct lower or upper sub-node of a given node.

The caching allows you to provide iteration context from a parent to its sub-nodes when iterating. The caching and retrieval is done in constant-time.

func (*AssociativeTrieNode[T, V]) Contains added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) Contains(addr T) bool

Contains returns whether the given address or prefix block subnet is in the sub-trie, as an added element, with this node as the root.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the prefix block or address address exists already in the trie, false otherwise.

Use GetAddedNode to get the node for the address rather than just checking for its existence.

func (*AssociativeTrieNode[T, V]) DeepEqual added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) DeepEqual(other *AssociativeTrieNode[T, V]) bool

DeepEqual returns whether the key is equal to that of the given node and the value is deep equal to that of the given node.

func (*AssociativeTrieNode[T, V]) DescendingIterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) DescendingIterator() Iterator[T]

DescendingIterator returns an iterator that iterates through the elements of the subtrie with this node as the root. The iteration is in reverse sorted element order.

func (*AssociativeTrieNode[T, V]) ElementContains added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) ElementContains(addr T) bool

ElementContains checks if a prefix block subnet or address in the trie, with this node as the root, contains the given subnet or address.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the subnet or address is contained by a trie element, false otherwise.

To get all the containing addresses, use ElementsContaining.

func (*AssociativeTrieNode[T, V]) ElementsContainedBy added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) ElementsContainedBy(addr T) *AssociativeTrieNode[T, V]

ElementsContainedBy checks if a part of this trie, with this node as the root, is contained by the given prefix block subnet or individual address.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the root node of the contained subtrie, or nil if no subtrie is contained. The node returned need not be an "added" node, see IsAdded for more details on added nodes. The returned subtrie is backed by this trie, so changes in this trie are reflected in those nodes and vice-versa.

func (*AssociativeTrieNode[T, V]) ElementsContaining added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) ElementsContaining(addr T) *ContainmentValuesPath[T, V]

ElementsContaining finds the trie nodes in the trie, with this sub-node as the root, containing the given key and returns them as a linked list. Only added nodes are added to the linked list.

If the argument is not a single address nor prefix block, this method will panic.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

func (*AssociativeTrieNode[T, V]) Equal added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) Equal(other *AssociativeTrieNode[T, V]) bool

Equal returns whether the key and mapped value match those of the given node.

func (*AssociativeTrieNode[T, V]) FirstAddedNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) FirstAddedNode() *AssociativeTrieNode[T, V]

FirstAddedNode returns the first (the lowest valued) added node in the sub-trie originating from this node, or nil if there are no added entries in this trie or sub-trie.

func (*AssociativeTrieNode[T, V]) FirstNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) FirstNode() *AssociativeTrieNode[T, V]

FirstNode returns the first (the lowest valued) node in the sub-trie originating from this node.

func (*AssociativeTrieNode[T, V]) FloorAddedNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) FloorAddedNode(addr T) *AssociativeTrieNode[T, V]

FloorAddedNode returns the added node, in this sub-trie with this node as the root, whose address is the highest address less than or equal to the given address.

func (AssociativeTrieNode[T, V]) Format added in v1.5.0 

func (node AssociativeTrieNode[T, V]) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface.

func (*AssociativeTrieNode[T, V]) Get added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) Get(addr T) (V, bool)

Get gets the value for the specified key in this mapped trie or subtrie.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the value for the given key. Returns nil if the contains no mapping for that key or if the mapped value is nil.

func (*AssociativeTrieNode[T, V]) GetAddedNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) GetAddedNode(addr T) *AssociativeTrieNode[T, V]

GetAddedNode gets trie nodes representing added elements.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Use Contains to check for the existence of a given address in the trie, as well as GetNode to search for all nodes including those not-added but also auto-generated nodes for subnet blocks.

func (*AssociativeTrieNode[T, V]) GetKey added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) GetKey() T

GetKey gets the key used for placing the node in the trie.

func (*AssociativeTrieNode[T, V]) GetLowerSubNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) GetLowerSubNode() *AssociativeTrieNode[T, V]

GetLowerSubNode gets the direct child node whose key is smallest in value.

func (*AssociativeTrieNode[T, V]) GetNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) GetNode(addr T) *AssociativeTrieNode[T, V]

GetNode gets the node in the trie, with this subnode as the root, corresponding to the given address, or returns nil if not such element exists.

It returns any node, whether added or not, including any prefix block node that was not added.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

func (*AssociativeTrieNode[T, V]) GetParent added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) GetParent() *AssociativeTrieNode[T, V]

GetParent gets the node from which this node is a direct child node, or nil if this is the root.

func (*AssociativeTrieNode[T, V]) GetUpperSubNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) GetUpperSubNode() *AssociativeTrieNode[T, V]

GetUpperSubNode gets the direct child node whose key is largest in value.

func (*AssociativeTrieNode[T, V]) GetValue added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) GetValue() V

GetValue returns whather there is a value associated with the node, and returns that value.

func (*AssociativeTrieNode[T, V]) HigherAddedNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) HigherAddedNode(addr T) *AssociativeTrieNode[T, V]

HigherAddedNode returns the added node, in this sub-trie with this node as the root, whose address is the lowest address strictly greater than the given address.

func (*AssociativeTrieNode[T, V]) IsAdded added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) IsAdded() bool

IsAdded returns whether the node was "added". Some binary trie nodes are considered "added" and others are not. Those nodes created for key elements added to the trie are "added" nodes. Those that are not added are those nodes created to serve as junctions for the added nodes. Only added elements contribute to the size of a trie. When removing nodes, non-added nodes are removed automatically whenever they are no longer needed, which is when an added node has less than two added sub-nodes.

func (*AssociativeTrieNode[T, V]) IsEmpty added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) IsEmpty() bool

IsEmpty returns whether the size is zero.

func (*AssociativeTrieNode[T, V]) IsLeaf added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) IsLeaf() bool

IsLeaf returns whether this node is in the tree (a node for which IsAdded is true) and there are no elements in the sub-tree with this node as the root.

func (*AssociativeTrieNode[T, V]) IsRoot added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) IsRoot() bool

IsRoot returns whether this is the root of the backing trie.

func (*AssociativeTrieNode[T, V]) Iterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) Iterator() Iterator[T]

Iterator returns an iterator that iterates through the elements of the sub-trie with this node as the root. The iteration is in sorted element order.

func (*AssociativeTrieNode[T, V]) LastAddedNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) LastAddedNode() *AssociativeTrieNode[T, V]

LastAddedNode returns the last (the highest valued) added node in the sub-trie originating from this node, or nil if there are no added entries in this trie or sub-trie.

func (*AssociativeTrieNode[T, V]) LastNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) LastNode() *AssociativeTrieNode[T, V]

LastNode returns the last (the highest valued) node in the sub-trie originating from this node.

func (*AssociativeTrieNode[T, V]) LongestPrefixMatch added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) LongestPrefixMatch(addr T) T

LongestPrefixMatch returns the address or subnet with the longest prefix of all the added subnets or the address whose prefix matches the given address. This is equivalent to finding the containing subnet or address with the smallest subnet size.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns nil if no added subnet or address contains the given argument.

Use ElementContains to check for the existence of a containing address. To get all the containing addresses (subnets with matching prefix), use ElementsContaining. To get the node corresponding to the result of this method, use LongestPrefixMatchNode.

func (*AssociativeTrieNode[T, V]) LongestPrefixMatchNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) LongestPrefixMatchNode(addr T) *AssociativeTrieNode[T, V]

LongestPrefixMatchNode finds the containing subnet or address in the trie with the smallest subnet size, which is equivalent to finding the subnet or address with the longest matching prefix. Returns the node corresponding to that subnet.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns nil if no added subnet or address contains the given argument.

Use ElementContains to check for the existence of a containing address. To get all the containing addresses, use ElementsContaining. Use LongestPrefixMatch to get only the address corresponding to the result of this method.

func (*AssociativeTrieNode[T, V]) LowerAddedNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) LowerAddedNode(addr T) *AssociativeTrieNode[T, V]

LowerAddedNode returns the added node, in this sub-trie with this node as the root, whose address is the highest address strictly less than the given address.

func (*AssociativeTrieNode[T, V]) NextAddedNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) NextAddedNode() *AssociativeTrieNode[T, V]

NextAddedNode returns the first added node that follows this node following the trie order.

func (*AssociativeTrieNode[T, V]) NextNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) NextNode() *AssociativeTrieNode[T, V]

NextNode returns the node that follows this node following the trie order.

func (*AssociativeTrieNode[T, V]) NodeIterator added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) NodeIterator(forward bool) IteratorWithRemove[*AssociativeTrieNode[T, V]]

NodeIterator returns an iterator that iterates through the added nodes of the sub-trie with this node as the root, in forward or reverse trie order.

func (*AssociativeTrieNode[T, V]) NodeSize added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) NodeSize() int

NodeSize returns the number of nodes in the trie with this node as the root, which is more than the number of added addresses or blocks.

func (*AssociativeTrieNode[T, V]) PreviousAddedNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) PreviousAddedNode() *AssociativeTrieNode[T, V]

PreviousAddedNode returns the first added node that precedes this node following the trie order.

func (*AssociativeTrieNode[T, V]) PreviousNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) PreviousNode() *AssociativeTrieNode[T, V]

PreviousNode returns the node that precedes this node following the trie order.

func (*AssociativeTrieNode[T, V]) Remove added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) Remove()

Remove removes this node from the collection of added nodes, and also from the trie if possible. If it has two sub-nodes, it cannot be removed from the trie, in which case it is marked as not "added", nor is it counted in the trie size. Only added nodes can be removed from the trie. If this node is not added, this method does nothing.

func (*AssociativeTrieNode[T, V]) RemoveElementsContainedBy added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) RemoveElementsContainedBy(addr T) *AssociativeTrieNode[T, V]

RemoveElementsContainedBy removes any single address or prefix block subnet from the trie, with this node as the root, that is contained in the given individual address or prefix block subnet.

Goes further than Remove, not requiring a match to an inserted node, and also removing all the sub-nodes of any removed node or sub-node.

For example, after inserting 1.2.3.0 and 1.2.3.1, passing 1.2.3.0/31 to RemoveElementsContainedBy will remove them both, while the Remove method will remove nothing. After inserting 1.2.3.0/31, then Remove(Address) will remove 1.2.3.0/31, but will leave 1.2.3.0 and 1.2.3.1 in the trie.

It cannot partially delete a node, such as deleting a single address from a prefix block represented by a node. It can only delete the whole node if the whole address or block represented by that node is contained in the given address or block.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the root node of the subtrie that was removed from the trie, or nil if nothing was removed.

func (*AssociativeTrieNode[T, V]) RemoveNode added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) RemoveNode(addr T) bool

RemoveNode removes the given single address or prefix block subnet from the trie with this node as the root.

Removing an element will not remove contained elements (nodes for contained blocks and addresses).

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the prefix block or address was removed, false if not already in the trie.

You can also remove by calling GetAddedNode to get the node and then calling Remove on the node.

When an address is removed, the corresponding node may remain in the trie if it remains a subnet block for two sub-nodes. If the corresponding node can be removed from the trie, it will be removed.

func (*AssociativeTrieNode[T, V]) SetAdded added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) SetAdded()

SetAdded makes this node an added node, which is equivalent to adding the corresponding key to the trie. If the node is already an added node, this method has no effect. You cannot set an added node to non-added, for that you should Remove the node from the trie by calling Remove. A non-added node will only remain in the trie if it needs to be in the trie.

func (*AssociativeTrieNode[T, V]) SetValue added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) SetValue(val V)

SetValue sets the value associated with this node.

func (*AssociativeTrieNode[T, V]) Size added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) Size() int

Size returns the number of elements in the trie. Only nodes for which IsAdded returns true are counted. When zero is returned, IsEmpty returns true.

func (*AssociativeTrieNode[T, V]) String added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) String() string

String returns a visual representation of this node including the key, with an open circle indicating this node is not an added node, a closed circle indicating this node is an added node.

func (*AssociativeTrieNode[T, V]) TreeDeepEqual added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) TreeDeepEqual(other *AssociativeTrieNode[T, V]) bool

TreeDeepEqual returns whether the sub-trie represented by this node as the root node matches the given sub-trie, matching with Compare on the keys and reflect.DeepEqual on the values.

func (*AssociativeTrieNode[T, V]) TreeEqual added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) TreeEqual(other *AssociativeTrieNode[T, V]) bool

TreeEqual returns whether the sub-trie represented by this node as the root node matches the given sub-trie.

func (*AssociativeTrieNode[T, V]) TreeString added in v1.5.0 

func (node *AssociativeTrieNode[T, V]) TreeString(withNonAddedKeys, withSizes bool) string

TreeString returns a visual representation of the sub-trie with this node as the root, with one node per line.

  • withNonAddedKeys: whether to show nodes that are not added nodes
  • withSizes: whether to include the counts of added nodes in each sub-trie

type BigDivInt 

type BigDivInt = big.Int

BigDivInt is an unsigned integer type for unlimited size division values.

type BitCount 

type BitCount = int // using signed integers allows for easier arithmetic

BitCount represents a count of bits in an address, section, grouping, segment, or division. Using signed integers allows for easier arithmetic, avoiding bugs. However, all methods adjust bit counts to match address size, so negative bit counts or bit counts larger than address size are meaningless.

type BitItem added in v1.5.3 

type BitItem interface {
	// GetByteCount returns the number of bytes required for each value comprising this address item,
	// rounding up if the bit count is not a multiple of 8.
	GetByteCount() int

	// GetBitCount returns the number of bits in each value comprising this address item.
	GetBitCount() BitCount
}

type BitwiseOrer 

type BitwiseOrer interface {
	// GetOredLower provides the lowest value after the disjunction, which is not necessarily the lowest value apriori.
	GetOredLower(value, maskValue uint64) uint64

	// GetOredUpper provides the highest value after the disjunction, which is not necessarily the highest value apriori.
	GetOredUpper(upperValue, maskValue uint64) uint64

	// IsSequential returns whether applying bitwise disjunction to all values in the range results in a sequential set of values.
	IsSequential() bool
}

BitwiseOrer is used for bitwise disjunction applied to division and segment values.

type Cached added in v1.5.0 

type Cached = tree.C

type CachingTrieIterator added in v1.5.0 

type CachingTrieIterator[T any] interface {
	IteratorWithRemove[T]

	// GetCached returns an object previously cached with the current iterated node.
	// After Next has returned a node,
	// if an object was cached by a call to CacheWithLowerSubNode or CacheWithUpperSubNode
	// was called when that node's parent was previously returned by Next,
	// then this returns that cached object.
	GetCached() Cached

	// CacheWithLowerSubNode caches an object with the lower sub-node of the current iterated node.
	// After Next has returned a node,
	// calling this method caches the provided object with the lower sub-node so that it can
	// be retrieved with GetCached when the lower sub-node is visited later.
	//
	// Returns false if it could not be cached, either because the node has since been removed with a call to Remove,
	// because Next has not been called yet, or because there is no lower sub node for the node previously returned by  Next.
	//
	// The caching and retrieval is done in constant time.
	CacheWithLowerSubNode(Cached) bool

	// CacheWithUpperSubNode caches an object with the upper sub-node of the current iterated node.
	// After Next has returned a node,
	// calling this method caches the provided object with the upper sub-node so that it can
	// be retrieved with GetCached when the upper sub-node is visited later.
	//
	// Returns false if it could not be cached, either because the node has since been removed with a call to Remove,
	// because Next has not been called yet, or because there is no upper sub node for the node previously returned by Next.
	//
	// The caching and retrieval is done in constant time.
	CacheWithUpperSubNode(Cached) bool
}

CachingTrieIterator is an iterator of a tree that allows you to cache an object with the lower or upper sub-node of the currently visited node. The cached object can be retrieved later when iterating the sub-node. That allows you to provide iteration context from a parent to its sub-nodes when iterating, but can only be provided with iterators in which parent nodes are visited before their sub-nodes. The caching and retrieval is done in constant-time.

type ContainmentPath added in v1.2.0 

type ContainmentPath[T TrieKeyConstraint[T]] struct {
	// contains filtered or unexported fields
}

ContainmentPath represents a path through the trie of containing subnets, each node in the path contained by the previous node, the first node corresponding to the shortest prefix match, the last element corresponding to the longest prefix match.

func (*ContainmentPath[T]) Count added in v1.2.0 

func (path *ContainmentPath[T]) Count() int

Count returns the count of containing subnets in the path of containing subnets, starting from this node and moving downwards to sub-nodes. This is a constant-time operation since the size is maintained in each node and adjusted with each add and Remove operation in the sub-tree.

func (*ContainmentPath[T]) LongestPrefixMatch added in v1.2.0 

func (path *ContainmentPath[T]) LongestPrefixMatch() *ContainmentPathNode[T]

LongestPrefixMatch returns the end of the Path of containing subnets, which may or may not match a leaf in the originating tree. If there are no containing elements (prefix matches) this returns nil.

func (*ContainmentPath[T]) ShortestPrefixMatch added in v1.2.0 

func (path *ContainmentPath[T]) ShortestPrefixMatch() *ContainmentPathNode[T]

ShortestPrefixMatch returns the beginning of the Path of containing subnets, which may or may not match the tree root of the originating tree. If there are no containing elements (prefix matches) this returns nil.

func (*ContainmentPath[T]) String added in v1.2.0 

func (path *ContainmentPath[T]) String() string

String returns a visual representation of the Path with one node per line.

type ContainmentPathNode added in v1.2.0 

type ContainmentPathNode[T TrieKeyConstraint[T]] struct {
	// contains filtered or unexported fields
}

ContainmentPathNode is a node in a ContainmentPath

func (*ContainmentPathNode[T]) Count added in v1.2.0 

func (node *ContainmentPathNode[T]) Count() int

Count returns the count of containing subnets in the path of containing subnets, starting from this node and moving downwards to sub-nodes. This is a constant-time operation since the size is maintained in each node and adjusted with each add and Remove operation in the sub-tree.

func (*ContainmentPathNode[T]) GetKey added in v1.2.0 

func (node *ContainmentPathNode[T]) GetKey() T

GetKey gets the containing block or matching address corresponding to this node

func (*ContainmentPathNode[T]) ListString added in v1.2.0 

func (node *ContainmentPathNode[T]) ListString() string

ListString returns a visual representation of the containing subnets starting from this node and moving downwards to sub-nodes.

func (*ContainmentPathNode[T]) Next added in v1.2.0 

func (node *ContainmentPathNode[T]) Next() *ContainmentPathNode[T]

Next gets the node contained by this node

func (*ContainmentPathNode[T]) Previous added in v1.2.0 

func (node *ContainmentPathNode[T]) Previous() *ContainmentPathNode[T]

Previous gets the node containing this node

func (*ContainmentPathNode[T]) String added in v1.2.0 

func (node *ContainmentPathNode[T]) String() string

String returns a visual representation of this node including the address key

type ContainmentValuesPath added in v1.5.0 

type ContainmentValuesPath[T TrieKeyConstraint[T], V any] struct {
	// contains filtered or unexported fields
}

ContainmentValuesPath represents a path through the associative trie of containing subnets, each node in the path contained by the previous node, the first node corresponding to the shortest prefix match, the last element corresponding to the longest prefix match.

func (*ContainmentValuesPath[T, V]) Count added in v1.5.0 

func (path *ContainmentValuesPath[T, V]) Count() int

Count returns the count of containing subnets in the path of containing subnets, starting from this node and moving downwards to sub-nodes. This is a constant-time operation since the size is maintained in each node and adjusted with each add and Remove operation in the sub-tree.

func (*ContainmentValuesPath[T, V]) LongestPrefixMatch added in v1.5.0 

func (path *ContainmentValuesPath[T, V]) LongestPrefixMatch() *ContainmentValuesPathNode[T, V]

LongestPrefixMatch returns the end of the Path of containing subnets, which may or may not match a leaf in the originating tree. If there are no containing elements (prefix matches) this returns nil.

func (*ContainmentValuesPath[T, V]) ShortestPrefixMatch added in v1.5.0 

func (path *ContainmentValuesPath[T, V]) ShortestPrefixMatch() *ContainmentValuesPathNode[T, V]

ShortestPrefixMatch returns the beginning of the Path of containing subnets, which may or may not match the tree root of the originating tree. If there are no containing elements (prefix matches) this returns nil.

func (*ContainmentValuesPath[T, V]) String added in v1.5.0 

func (path *ContainmentValuesPath[T, V]) String() string

String returns a visual representation of the Path with one node per line.

type ContainmentValuesPathNode added in v1.5.0 

type ContainmentValuesPathNode[T TrieKeyConstraint[T], V any] struct {
	// contains filtered or unexported fields
}

ContainmentValuesPathNode is a node in a ContainmentPath

func (*ContainmentValuesPathNode[T, V]) Count added in v1.5.0 

func (node *ContainmentValuesPathNode[T, V]) Count() int

Count returns the count of containing subnets in the path of containing subnets, starting from this node and moving downwards to sub-nodes. This is a constant-time operation since the size is maintained in each node and adjusted with each add and Remove operation in the sub-tree.

func (*ContainmentValuesPathNode[T, V]) GetKey added in v1.5.0 

func (node *ContainmentValuesPathNode[T, V]) GetKey() T

GetKey gets the containing block or matching address corresponding to this node

func (*ContainmentValuesPathNode[T, V]) GetValue added in v1.5.0 

func (node *ContainmentValuesPathNode[T, V]) GetValue() V

GetValue returns the value assigned to the block or address, if the node was an associative node from an associative trie. Otherwise, it returns the zero value.

func (*ContainmentValuesPathNode[T, V]) ListString added in v1.5.0 

func (node *ContainmentValuesPathNode[T, V]) ListString() string

ListString returns a visual representation of the containing subnets starting from this node and moving downwards to sub-nodes.

func (*ContainmentValuesPathNode[T, V]) Next added in v1.5.0 

func (node *ContainmentValuesPathNode[T, V]) Next() *ContainmentValuesPathNode[T, V]

Next gets the node contained by this node

func (*ContainmentValuesPathNode[T, V]) Previous added in v1.5.0 

func (node *ContainmentValuesPathNode[T, V]) Previous() *ContainmentValuesPathNode[T, V]

Previous gets the node containing this node

func (*ContainmentValuesPathNode[T, V]) String added in v1.5.0 

func (node *ContainmentValuesPathNode[T, V]) String() string

String returns a visual representation of this node including the address key

type DefaultAddressConverter 

type DefaultAddressConverter struct{}

DefaultAddressConverter converts to/from IPv4-mapped addresses, which maps IPv4 "a.b.c.d" to/from the IPv4-mapped IPv6 "::ffff:a.b.c.d". Converting from IPv6 to IPv4 requires that the IPV6 address have the prefix "0:0:0:0:0:ffff".

Note that with some subnets, the mapping is not possible due to the range of values in segments. For example, "::ffff:0-100:0" cannot be mapped to an IPv4 address because the range 0-0x100 cannot be split into two smaller ranges. Similarly, "1-2.0.0.0" cannot be converted to an IPv4-mapped IPv6 address, because the two segments "1-2.0" cannot be joined into a single IPv6 segment with the same range of values, namely the two values 0x100 and 0x200.

func (DefaultAddressConverter) IsIPv4Convertible 

func (converter DefaultAddressConverter) IsIPv4Convertible(address *IPAddress) bool

IsIPv4Convertible returns true if ToIPv4 returns non-nil.

func (DefaultAddressConverter) IsIPv6Convertible 

func (converter DefaultAddressConverter) IsIPv6Convertible(address *IPAddress) bool

IsIPv6Convertible returns true if ToIPv6 returns non-nil.

func (DefaultAddressConverter) ToIPv4 

func (converter DefaultAddressConverter) ToIPv4(address *IPAddress) *IPv4Address

ToIPv4 converts IPv4-mapped IPv6 addresses to IPv4, or returns the original address if IPv4 already, or returns nil if the address cannot be converted.

func (DefaultAddressConverter) ToIPv6 

func (converter DefaultAddressConverter) ToIPv6(address *IPAddress) *IPv6Address

ToIPv6 converts to an IPv4-mapped IPv6 address or returns the original address if IPv6 already.

type DelimitedAddressString added in v1.5.0 

type DelimitedAddressString string

func (DelimitedAddressString) CountDelimitedAddresses added in v1.5.0 

func (str DelimitedAddressString) CountDelimitedAddresses() int

CountDelimitedAddresses will count the possible combinations, given a string with comma delimiters separating segment elements. It is a counterpart to ParseDelimitedSegments, indicating the number of iterated elements from ParseDelimitedSegments.

For example, given "1,2.3.4,5.6" this method will return 4 for the possible combinations: "1.3.4.6", "1.3.5.6", "2.3.4.6" and "2.3.5.6".

func (DelimitedAddressString) ParseDelimitedIPAddrSegments added in v1.5.0 

func (str DelimitedAddressString) ParseDelimitedIPAddrSegments() Iterator[*IPAddressString]

ParseDelimitedIPAddrSegments will provide an iterator to iterate through the possible combinations, given a string with comma delimiters to denote segment elements.

func (DelimitedAddressString) ParseDelimitedSegments added in v1.5.0 

func (str DelimitedAddressString) ParseDelimitedSegments() Iterator[string]

ParseDelimitedSegments will provide an iterator to iterate through the possible combinations, given a string with comma delimiters to denote segment elements,

For example, given "1,2.3.4,5.6" this will iterate through "1.3.4.6", "1.3.5.6", "2.3.4.6" and "2.3.5.6"

Another example: "1-2,3.4.5.6" will iterate through "1-2.4.5.6" and "1-3.4.5.6".

This method will not validate strings. Each string produced can be validated using an instance of IPAddressString. Use CountDelimitedAddresses for the count of elements in the iterator.

type DivInt 

type DivInt = uint64

DivInt is an integer type for holding generic division values, which can be larger than segment values

type DivisionType 

type DivisionType interface {
	AddressItem

	// GetString produces a string that avoids wildcards when a prefix length is part of the string.  Equivalent to GetWildcardString when the prefix length is not part of the string.
	GetString() string

	// GetWildcardString produces a string that uses wildcards and avoids prefix length.
	GetWildcardString() string

	// IsSinglePrefix determines if the division has a single prefix for the given prefix length.  You can call GetPrefixCountLen to get the count of prefixes.
	IsSinglePrefix(BitCount) bool
	// contains filtered or unexported methods
}

DivisionType serves as a common interface to all divisions

type EmbeddedIPv6AddressSection 

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

EmbeddedIPv6AddressSection represents the initial IPv6 section of an IPv6v4MixedAddressGrouping.

func (*EmbeddedIPv6AddressSection) IsPrefixBlock 

func (section *EmbeddedIPv6AddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

type ExtendedIPSegmentSeries 

type ExtendedIPSegmentSeries interface {
	IPAddressSegmentSeries

	// Unwrap returns the wrapped IP address or IP address section as an interface, IPAddressSegmentSeries.
	Unwrap() IPAddressSegmentSeries

	// Equal returns whether the given address series is equal to this address series.
	// Two address series are equal if they represent the same set of series.
	// Both must be equal addresses or both must be equal sections.
	Equal(ExtendedIPSegmentSeries) bool

	// Contains returns whether this is same type and version as the given address series and whether it contains all values in the given series.
	//
	// Series must also have the same number of segments to be comparable, otherwise false is returned.
	Contains(ExtendedIPSegmentSeries) bool

	// GetSection returns the backing section for this series, comprising all segments.
	GetSection() *IPAddressSection

	// GetTrailingSection returns an ending subsection of the full address section.
	GetTrailingSection(index int) *IPAddressSection

	// GetSubSection returns a subsection of the full address section.
	GetSubSection(index, endIndex int) *IPAddressSection

	// GetNetworkSection returns an address section containing the segments with the network of the series, the prefix bits.
	// The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.
	//
	// If this series has no CIDR prefix length, the returned network section will
	// be the entire series as a prefixed section with prefix length matching the address bit length.
	GetNetworkSection() *IPAddressSection

	// GetHostSection returns a section containing the segments with the host of the series, the bits beyond the CIDR network prefix length.
	// The returned section will have only as many segments as needed to contain the host.
	//
	// If this series has no prefix length, the returned host section will be the full section.
	GetHostSection() *IPAddressSection

	// GetNetworkSectionLen returns a section containing the segments with the network of the series, the prefix bits according to the given prefix length.
	// The returned section will have only as many segments as needed to contain the network.
	//
	// The new section will be assigned the given prefix length,
	// unless the existing prefix length is smaller, in which case the existing prefix length will be retained.
	GetNetworkSectionLen(BitCount) *IPAddressSection

	// GetHostSectionLen returns a section containing the segments with the host of the series, the bits beyond the given CIDR network prefix length.
	// The returned section will have only as many segments as needed to contain the host.
	GetHostSectionLen(BitCount) *IPAddressSection

	// GetNetworkMask returns the network mask associated with the CIDR network prefix length of this series.
	// If this series has no prefix length, then the all-ones mask is returned.
	GetNetworkMask() ExtendedIPSegmentSeries

	// GetHostMask returns the host mask associated with the CIDR network prefix length of this series.
	// If this series has no prefix length, then the all-ones mask is returned.
	GetHostMask() ExtendedIPSegmentSeries

	// GetSegment returns the segment at the given index.
	// The first segment is at index 0.
	// GetSegment will panic given a negative index or an index matching or larger than the segment count.
	GetSegment(index int) *IPAddressSegment

	// GetSegments returns a slice with the address segments.  The returned slice is not backed by the same array as this section.
	GetSegments() []*IPAddressSegment

	// CopySegments copies the existing segments into the given slice,
	// as much as can be fit into the slice, returning the number of segments copied.
	CopySegments(segs []*IPAddressSegment) (count int)

	// CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index,
	// into the given slice, as much as can be fit into the slice, returning the number of segments copied.
	CopySubSegments(start, end int, segs []*IPAddressSegment) (count int)

	// IsIPv4 returns true if this series originated as an IPv4 series.  If so, use ToIPv4 to convert back to the IPv4-specific type.
	IsIPv4() bool

	// IsIPv6 returns true if this series originated as an IPv6 series.  If so, use ToIPv6 to convert back to the IPv6-specific type.
	IsIPv6() bool

	// ToIPv4 converts to an IPv4AddressSegmentSeries if this series originated as an IPv4 series.
	// If not, ToIPv4 returns nil.
	//
	// ToIPv4 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToIPv4() IPv4AddressSegmentSeries

	// ToIPv6 converts to an IPv4AddressSegmentSeries if this series originated as an IPv6 series.
	// If not, ToIPv6 returns nil.
	//
	// ToIPv6 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToIPv6() IPv6AddressSegmentSeries

	// ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value,
	// and changing the following segments to be full-range.
	ToBlock(segmentIndex int, lower, upper SegInt) ExtendedIPSegmentSeries

	// ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values.
	// The series will be the block of all series with the same prefix.
	//
	// If this series has no prefix, this series is returned.
	ToPrefixBlock() ExtendedIPSegmentSeries

	// ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values.
	// The returned series will be the block of all series with the same prefix.
	ToPrefixBlockLen(BitCount) ExtendedIPSegmentSeries

	// ToZeroHostLen converts the series to one in which all individual series have a host of zero,
	// the host being the bits following the given prefix length.
	// If this series has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.
	//
	// This returns an error if the series is a range which cannot be converted to a range in which all series have zero hosts,
	// because the conversion results in a segment that is not a sequential range of values.
	ToZeroHostLen(BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ToZeroHost converts the series to one in which all individual series have a host of zero,
	// the host being the bits following the prefix length.
	// If the series has no prefix length, then it returns an all-zero series.
	//
	// The returned series will have the same prefix length.
	//
	// For instance, the zero host of "1.2.3.4/16" is the individual address "1.2.0.0/16".
	//
	// This returns an error if the series is a range which cannot be converted to a range in which all individual elements have zero hosts,
	// because the conversion results in a series segment that is not a sequential range of values.
	ToZeroHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ToMaxHostLen converts the series to one in which all individual series have a host of all one-bits, the max host,
	// the host being the bits following the given prefix length.
	// If this series has the same prefix length, then the resulting series will too, otherwise the resulting series will have no prefix length.
	//
	// For instance, the zero host of "1.2.3.4" for the prefix length of 16 is the address "1.2.255.255".
	//
	// This returns an error if the series is a range which cannot be converted to a range in which all individual elements have max hosts,
	// because the conversion results in a series segment that is not a sequential range of values.
	ToMaxHostLen(BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ToMaxHost converts the series to one in which all individual series have a host of all one-bits, the max value,
	// the host being the bits following the prefix length.
	// If the series has no prefix length, then it returns an all-ones series, the max series.
	//
	// The returned series will have the same prefix length.
	//
	// For instance, the max host of "1.2.3.4/16" gives the broadcast address "1.2.255.255/16".
	//
	// This returns an error if the series is a range which cannot be converted to a range in which all individual elements have max hosts,
	// because the conversion results in a series segment that is not a sequential range of values.
	ToMaxHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ToZeroNetwork converts the series to one in which all individual addresses or address sections have a network of zero,
	// the network being the bits within the prefix length.
	// If the series has no prefix length, then it returns an all-zero series.
	//
	// The returned series will have the same prefix length.
	ToZeroNetwork() ExtendedIPSegmentSeries

	// Increment returns the item that is the given increment upwards into the range,
	// with the increment of 0 returning the first in the range.
	//
	// If the increment i matches or exceeds the range count c, then i - c + 1
	// is added to the upper item of the range.
	// An increment matching the count gives you the item just above the highest in the range.
	//
	// If the increment is negative, it is added to the lowest of the range.
	// To get the item just below the lowest of the range, use the increment -1.
	//
	// If this represents just a single value, the item is simply incremented by the given increment, positive or negative.
	//
	// If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond.
	// For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on.
	// An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator.
	// For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.
	//
	// On overflow or underflow, Increment returns nil.
	Increment(int64) ExtendedIPSegmentSeries

	// IncrementBoundary returns the item that is the given increment from the range boundaries of this item.
	//
	// If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item.
	// If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item.
	// If the increment is zero, returns this.
	//
	// If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.
	//
	// On overflow or underflow, IncrementBoundary returns nil.
	IncrementBoundary(int64) ExtendedIPSegmentSeries

	// GetLower returns the series in the range with the lowest numeric value,
	// which will be the same series if it represents a single value.
	// For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned.
	GetLower() ExtendedIPSegmentSeries

	// GetUpper returns the series in the range with the highest numeric value,
	// which will be the same series if it represents a single value.
	// For example, for the subnet "1.2-3.4.5-6", the address "1.3.4.6" is returned.
	GetUpper() ExtendedIPSegmentSeries

	// AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this series.
	// The returned block will have an assigned prefix length indicating the prefix length for the block.
	//
	// There may be no such series - it is required that the range of values match the range of a prefix block.
	// If there is no such series, then nil is returned.
	AssignPrefixForSingleBlock() ExtendedIPSegmentSeries

	// AssignMinPrefixForBlock returns an equivalent series, assigned the smallest prefix length possible,
	// such that the prefix block for that prefix length is in this series.
	//
	// In other words, this method assigns a prefix length to this series matching the largest prefix block in this series.
	AssignMinPrefixForBlock() ExtendedIPSegmentSeries

	// Iterator provides an iterator to iterate through the individual series of this series.
	//
	// When iterating, the prefix length is preserved.  Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual series.
	//
	// Call IsMultiple to determine if this instance represents multiple series, or GetCount for the count.
	Iterator() Iterator[ExtendedIPSegmentSeries]

	// PrefixIterator provides an iterator to iterate through the individual prefixes of this series,
	// each iterated element spanning the range of values for its prefix.
	//
	// It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks,
	// instead constraining themselves to values from this series.
	//
	// If the series has no prefix length, then this is equivalent to Iterator.
	PrefixIterator() Iterator[ExtendedIPSegmentSeries]

	// PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this series.
	// Each iterated series will be a prefix block with the same prefix length as this series.
	//
	// If this series has no prefix length, then this is equivalent to Iterator.
	PrefixBlockIterator() Iterator[ExtendedIPSegmentSeries]

	// SequentialBlockIterator iterates through the sequential series that make up this series.
	//
	// Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.
	//
	// Use GetSequentialBlockCount to get the number of iterated elements.
	SequentialBlockIterator() Iterator[ExtendedIPSegmentSeries]

	// BlockIterator Iterates through the series that can be obtained by iterating through all the upper segments up to the given segment count.
	// The segments following remain the same in all iterated series.
	BlockIterator(segmentCount int) Iterator[ExtendedIPSegmentSeries]

	// SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual series as this address series.
	SpanWithPrefixBlocks() []ExtendedIPSegmentSeries

	// SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of individual series as this series.
	//
	// This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.
	SpanWithSequentialBlocks() []ExtendedIPSegmentSeries

	// CoverWithPrefixBlock returns the minimal-size prefix block that covers all the values in this series.
	// The resulting block will have a larger series count than this, unless this series is already a prefix block.
	CoverWithPrefixBlock() ExtendedIPSegmentSeries

	// AdjustPrefixLen increases or decreases the prefix length by the given increment.
	//
	// A prefix length will not be adjusted lower than zero or beyond the bit length of the series.
	//
	// If this series has no prefix length, then the prefix length will be set to the adjustment if positive,
	// or it will be set to the adjustment added to the bit count if negative.
	AdjustPrefixLen(BitCount) ExtendedIPSegmentSeries

	// AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.
	//
	// A prefix length will not be adjusted lower than zero or beyond the bit length of the series.
	//
	// If this series has no prefix length, then the prefix length will be set to the adjustment if positive,
	// or it will be set to the adjustment added to the bit count if negative.
	//
	// When prefix length is increased, the bits moved within the prefix become zero.
	// When a prefix length is decreased, the bits moved outside the prefix become zero.
	//
	// If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.
	AdjustPrefixLenZeroed(BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// SetPrefixLen sets the prefix length.
	//
	// A prefix length will not be set to a value lower than zero or beyond the bit length of the series.
	// The provided prefix length will be adjusted to these boundaries if necessary.
	SetPrefixLen(BitCount) ExtendedIPSegmentSeries

	// SetPrefixLenZeroed sets the prefix length.
	//
	// A prefix length will not be set to a value lower than zero or beyond the bit length of the series.
	// The provided prefix length will be adjusted to these boundaries if necessary.
	//
	// If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero.
	// If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.
	//
	// In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.
	//
	// If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.
	SetPrefixLenZeroed(BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// WithoutPrefixLen provides the same address series but with no prefix length.  The values remain unchanged.
	WithoutPrefixLen() ExtendedIPSegmentSeries

	// ReverseBytes returns a new segment series with the bytes reversed.  Any prefix length is dropped.
	//
	// If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range,
	// and reversing the segment values results in a range that is not contiguous, then this returns an error.
	//
	// In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.
	ReverseBytes() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ReverseBits returns a new segment series with the bits reversed.  Any prefix length is dropped.
	//
	// If the bits within a single segment cannot be reversed because the segment represents a range,
	// and reversing the segment values results in a range that is not contiguous, this returns an error.
	//
	// In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.
	//
	// If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.
	ReverseBits(perByte bool) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ReverseSegments returns a new series with the segments reversed.
	ReverseSegments() ExtendedIPSegmentSeries

	// ToCustomString creates a customized string from this series according to the given string option parameters.
	ToCustomString(stringOptions addrstr.IPStringOptions) string
}

ExtendedIPSegmentSeries wraps either an IPAddress or IPAddressSection. ExtendedIPSegmentSeries can be used to write code that works with both IP addresses and IP address sections, going further than IPAddressSegmentSeries to offer additional methods, methods with the series types in their signature.

type ExtendedIdentifierString 

type ExtendedIdentifierString interface {
	HostIdentifierString

	// GetAddress returns the identified address or nil if none.
	GetAddress() AddressType

	// ToAddress returns the identified address or an error.
	ToAddress() (AddressType, error)

	// Unwrap returns the wrapped IPAddressString, MACAddressString or HostName as an interface, HostIdentifierString.
	Unwrap() HostIdentifierString
}

ExtendedIdentifierString is a common interface for strings that identify hosts, namely IPAddressString, MACAddressString, and HostName.

type ExtendedMasker 

type ExtendedMasker interface {
	Masker

	GetExtendedMaskedLower(extendedValue, extendedMaskValue uint64) uint64

	GetExtendedMaskedUpper(extendedUpperValue, extendedMaskValue uint64) uint64
}

ExtendedMasker handles value masking for divisions with bit counts larger than 64 bits.

func MaskExtendedRange added in v1.3.0 

func MaskExtendedRange(
	value, extendedValue,
	upperValue, extendedUpperValue,
	maskValue, extendedMaskValue,
	maxValue, extendedMaxValue uint64) ExtendedMasker

MaskExtendedRange masks divisions with bit counts larger than 64 bits. Use MaskRange for smaller divisions.

type ExtendedSegmentSeries 

type ExtendedSegmentSeries interface {
	AddressSegmentSeries

	// Unwrap returns the wrapped address or address section as an interface, AddressSegmentSeries.
	Unwrap() AddressSegmentSeries

	// Equal returns whether the given address series is equal to this address series.
	// Two address series are equal if they represent the same set of series.
	// Both must be equal addresses or both must be equal sections.
	Equal(ExtendedSegmentSeries) bool

	// Contains returns whether this is same type and version as the given address series and whether it contains all values in the given series.
	//
	// Series must also have the same number of segments to be comparable, otherwise false is returned.
	Contains(ExtendedSegmentSeries) bool

	// GetSection returns the backing section for this series, comprising all segments.
	GetSection() *AddressSection

	// GetTrailingSection returns an ending subsection of the full address section.
	GetTrailingSection(index int) *AddressSection

	// GetSubSection returns a subsection of the full address section.
	GetSubSection(index, endIndex int) *AddressSection

	// GetSegment returns the segment at the given index.
	// The first segment is at index 0.
	// GetSegment will panic given a negative index or an index matching or larger than the segment count.
	GetSegment(index int) *AddressSegment

	// GetSegments returns a slice with the address segments.  The returned slice is not backed by the same array as this section.
	GetSegments() []*AddressSegment

	// CopySegments copies the existing segments into the given slice,
	// as much as can be fit into the slice, returning the number of segments copied.
	CopySegments(segs []*AddressSegment) (count int)

	// CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index,
	// into the given slice, as much as can be fit into the slice, returning the number of segments copied.
	CopySubSegments(start, end int, segs []*AddressSegment) (count int)

	// IsIP returns true if this series originated as an IPv4 or IPv6 series, or a zero-length IP series.  If so, use ToIP to convert back to the IP-specific type.
	IsIP() bool

	// IsIPv4 returns true if this series originated as an IPv4 series.  If so, use ToIPv4 to convert back to the IPv4-specific type.
	IsIPv4() bool

	// IsIPv6 returns true if this series originated as an IPv6 series.  If so, use ToIPv6 to convert back to the IPv6-specific type.
	IsIPv6() bool

	// IsMAC returns true if this series originated as a MAC series.  If so, use ToMAC to convert back to the MAC-specific type.
	IsMAC() bool

	// ToIP converts to an IPAddressSegmentSeries if this series originated as IPv4 or IPv6, or an implicitly zero-valued IP.
	// If not, ToIP returns nil.
	ToIP() IPAddressSegmentSeries

	// ToIPv4 converts to an IPv4AddressSegmentSeries if this series originated as an IPv4 series.
	// If not, ToIPv4 returns nil.
	//
	// ToIPv4 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToIPv4() IPv4AddressSegmentSeries

	// ToIPv6 converts to an IPv4AddressSegmentSeries if this series originated as an IPv6 series.
	// If not, ToIPv6 returns nil.
	//
	// ToIPv6 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToIPv6() IPv6AddressSegmentSeries

	// ToMAC converts to a MACAddressSegmentSeries if this series originated as a MAC series.
	// If not, ToMAC returns nil.
	//
	// ToMAC implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToMAC() MACAddressSegmentSeries

	// ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value,
	// and changing the following segments to be full-range.
	ToBlock(segmentIndex int, lower, upper SegInt) ExtendedSegmentSeries

	// ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values.
	// The series will be the block of all series with the same prefix.
	//
	// If this series has no prefix, this series is returned.
	ToPrefixBlock() ExtendedSegmentSeries

	// ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values.
	// The returned series will be the block of all series with the same prefix.
	ToPrefixBlockLen(prefLen BitCount) ExtendedSegmentSeries

	// Increment returns the item that is the given increment upwards into the range,
	// with the increment of 0 returning the first in the range.
	//
	// If the increment i matches or exceeds the range count c, then i - c + 1
	// is added to the upper item of the range.
	// An increment matching the count gives you the item just above the highest in the range.
	//
	// If the increment is negative, it is added to the lowest of the range.
	// To get the item just below the lowest of the range, use the increment -1.
	//
	// If this represents just a single value, the item is simply incremented by the given increment, positive or negative.
	//
	// If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond.
	// For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on.
	// An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator.
	// For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.
	//
	// On overflow or underflow, Increment returns nil.
	Increment(int64) ExtendedSegmentSeries

	// IncrementBoundary returns the item that is the given increment from the range boundaries of this item.
	//
	// If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item.
	// If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item.
	// If the increment is zero, returns this.
	//
	// If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.
	//
	// On overflow or underflow, IncrementBoundary returns nil.
	IncrementBoundary(int64) ExtendedSegmentSeries

	// GetLower returns the series in the range with the lowest numeric value,
	// which will be the same series if it represents a single value.
	GetLower() ExtendedSegmentSeries

	// GetUpper returns the series in the range with the highest numeric value,
	// which will be the same series if it represents a single value.
	GetUpper() ExtendedSegmentSeries

	// AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this series.
	// The returned block will have an assigned prefix length indicating the prefix length for the block.
	//
	// There may be no such series - it is required that the range of values match the range of a prefix block.
	// If there is no such series, then nil is returned.
	AssignPrefixForSingleBlock() ExtendedSegmentSeries

	// AssignMinPrefixForBlock returns an equivalent series, assigned the smallest prefix length possible,
	// such that the prefix block for that prefix length is in this series.
	//
	// In other words, this method assigns a prefix length to this series matching the largest prefix block in this series.
	AssignMinPrefixForBlock() ExtendedSegmentSeries

	// Iterator provides an iterator to iterate through the individual series of this series.
	//
	// When iterating, the prefix length is preserved.  Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual series.
	//
	// Call IsMultiple to determine if this instance represents multiple series, or GetCount for the count.
	Iterator() Iterator[ExtendedSegmentSeries]

	// PrefixIterator provides an iterator to iterate through the individual prefixes of this series,
	// each iterated element spanning the range of values for its prefix.
	//
	// It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks,
	// instead constraining themselves to values from this series.
	//
	// If the series has no prefix length, then this is equivalent to Iterator.
	PrefixIterator() Iterator[ExtendedSegmentSeries]

	// PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this series.
	// Each iterated series will be a prefix block with the same prefix length as this series.
	//
	// If this series has no prefix length, then this is equivalent to Iterator.
	PrefixBlockIterator() Iterator[ExtendedSegmentSeries]

	// AdjustPrefixLen increases or decreases the prefix length by the given increment.
	//
	// A prefix length will not be adjusted lower than zero or beyond the bit length of the series.
	//
	// If this series has no prefix length, then the prefix length will be set to the adjustment if positive,
	// or it will be set to the adjustment added to the bit count if negative.
	AdjustPrefixLen(BitCount) ExtendedSegmentSeries

	// AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.
	//
	// A prefix length will not be adjusted lower than zero or beyond the bit length of the series.
	//
	// If this series has no prefix length, then the prefix length will be set to the adjustment if positive,
	// or it will be set to the adjustment added to the bit count if negative.
	//
	// When prefix length is increased, the bits moved within the prefix become zero.
	// When a prefix length is decreased, the bits moved outside the prefix become zero.
	AdjustPrefixLenZeroed(BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

	// SetPrefixLen sets the prefix length.
	//
	// A prefix length will not be set to a value lower than zero or beyond the bit length of the series.
	// The provided prefix length will be adjusted to these boundaries if necessary.
	SetPrefixLen(BitCount) ExtendedSegmentSeries

	// SetPrefixLenZeroed sets the prefix length.
	//
	// A prefix length will not be set to a value lower than zero or beyond the bit length of the series.
	// The provided prefix length will be adjusted to these boundaries if necessary.
	//
	// If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero.
	// If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.
	//
	// In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.
	//
	// If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.
	SetPrefixLenZeroed(BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

	// WithoutPrefixLen provides the same address series but with no prefix length.  The values remain unchanged.
	WithoutPrefixLen() ExtendedSegmentSeries

	// ReverseBytes returns a new segment series with the bytes reversed.  Any prefix length is dropped.
	//
	// If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range,
	// and reversing the segment values results in a range that is not contiguous, then this returns an error.
	//
	// In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.
	ReverseBytes() (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

	// ReverseBits returns a new segment series with the bits reversed.  Any prefix length is dropped.
	//
	// If the bits within a single segment cannot be reversed because the segment represents a range,
	// and reversing the segment values results in a range that is not contiguous, this returns an error.
	//
	// In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.
	ReverseBits(perByte bool) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

	// ReverseSegments returns a new series with the segments reversed.
	ReverseSegments() ExtendedSegmentSeries

	// ToCustomString creates a customized string from this series according to the given string option parameters.
	ToCustomString(stringOptions addrstr.StringOptions) string
}

ExtendedSegmentSeries wraps either an Address or AddressSection. ExtendedSegmentSeries can be used to write code that works with both addresses and address sections, going further than AddressSegmentSeries to offer additional methods with the series types in their signature.

type GenericKeyConstraint added in v1.5.1 

type GenericKeyConstraint[T KeyConstraint[T]] interface {
	KeyGeneratorConstraint[T]
	KeyConstraint[T]
}

GenericKeyConstraint is the generic type constraint for an address type that can generate and be generated from a generic address key.

type HostBitCount added in v1.5.0 

type HostBitCount uint8

HostBitCount is the count of bits in a host. For arithmetic, you may wish to use the signed integer type BitCount instead, which you can get from a HostBitCount using the Len method.

func BitsForCount added in v1.4.0 

func BitsForCount(count uint64) (result *HostBitCount)

BitsForCount returns the number of bits required outside the prefix length for a single prefix block to span at least as many addresses as the given count. Mathematically, it is the ceiling of the base 2 logarithm of the given count. A count of zero returns nil.

func (*HostBitCount) BlockSize added in v1.5.0 

func (hostBitCount *HostBitCount) BlockSize() *big.Int

BlockSize is the reverse of BitsForCount, giving the total number of values when ranging across the number of host bits. The nil *HostBitCount returns 0.

func (*HostBitCount) IsNil added in v1.5.0 

func (hostBitCount *HostBitCount) IsNil() bool

IsNil returns true if this is nil, meaning it represents having no identified host length.

func (*HostBitCount) Len added in v1.5.0 

func (hostBitCount *HostBitCount) Len() BitCount

Len returns the length of the host. If the receiver is nil, representing the absence of a host length, returns 0. It will also return 0 if the receiver has a host length of 0. To distinguish the two, compare the receiver with nil.

func (*HostBitCount) String added in v1.5.0 

func (hostBitCount *HostBitCount) String() string

String returns the bit count as a base-10 positive integer string, or "<nil>" if the receiver is a nil pointer.

type HostIdentifierString 

type HostIdentifierString interface {

	// ToNormalizedString provides a normalized String representation for the host identified by this HostIdentifierString instance.
	ToNormalizedString() string

	// IsValid returns whether the wrapped string is a valid identifier for a host.
	IsValid() bool

	// Wrap wraps the identifier string into the extended type that is polymorphic with other identifier strings.
	Wrap() ExtendedIdentifierString

	fmt.Stringer
	fmt.Formatter
}

HostIdentifierString represents a string that is used to identify a host.

type HostName 

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

HostName represents an internet host name. Can be a fully qualified domain name, a simple host name, or an ip address string. It can also include a port number or service name (which maps to a port). It can include a prefix length or mask for either an ipaddress or host name string. An IPv6 address can have an IPv6 zone.

Supported Formats

You can use all host or address formats supported by nmap and all address formats supported by IPAddressString. All manners of domain names are supported. When adding a prefix length or mask to a host name string, it is to denote the subnet of the resolved address.

Validation is done separately from DNS resolution to avoid unnecessary DNS lookups.

See RFC 3513, RFC 2181, RFC 952, RFC 1035, RFC 1034, RFC 1123, RFC 5890 or the list of rfcs for IPAddress. For IPv6 addresses in host, see RFC 2732 specifying "[]" notation and RFC 3986 and RFC 4038 (combining IPv6 "[]" notation with prefix or zone) and SMTP RFC 2821 for alternative uses of "[]" notation for both IPv4 and IPv6.

func NewHostName 

func NewHostName(str string) *HostName

NewHostName constructs a HostName that will parse the given string according to the default parameters.

func NewHostNameFromAddr 

func NewHostNameFromAddr(addr *IPAddress) *HostName

NewHostNameFromAddr constructs a HostName from an IP address.

func NewHostNameFromAddrPort 

func NewHostNameFromAddrPort(addr *IPAddress, port uint16) *HostName

NewHostNameFromAddrPort constructs a HostName from an IP address and a port.

func NewHostNameFromNetIP 

func NewHostNameFromNetIP(bytes net.IP) (hostName *HostName, err addrerr.AddressValueError)

NewHostNameFromNetIP constructs a HostName from a net.IP.

func NewHostNameFromNetIPAddr 

func NewHostNameFromNetIPAddr(addr *net.IPAddr) (hostName *HostName, err addrerr.AddressValueError)

NewHostNameFromNetIPAddr constructs a HostName from a net.IPAddr.

func NewHostNameFromNetNetIPAddr added in v1.5.0 

func NewHostNameFromNetNetIPAddr(addr netip.Addr) *HostName

NewHostNameFromNetNetIPAddr constructs a host name from a netip.Addr.

func NewHostNameFromNetNetIPAddrPort added in v1.5.0 

func NewHostNameFromNetNetIPAddrPort(addrPort netip.AddrPort) *HostName

NewHostNameFromNetNetIPAddrPort constructs a host name from a netip.AddrPort.

func NewHostNameFromNetNetIPPrefix added in v1.5.0 

func NewHostNameFromNetNetIPPrefix(addr netip.Prefix) (hostName *HostName, err addrerr.AddressValueError)

NewHostNameFromNetNetIPPrefix constructs a host name from a netip.Prefix.

func NewHostNameFromNetTCPAddr 

func NewHostNameFromNetTCPAddr(addr *net.TCPAddr) (*HostName, addrerr.AddressValueError)

NewHostNameFromNetTCPAddr constructs a HostName from a net.TCPAddr.

func NewHostNameFromNetUDPAddr 

func NewHostNameFromNetUDPAddr(addr *net.UDPAddr) (*HostName, addrerr.AddressValueError)

NewHostNameFromNetUDPAddr constructs a HostName from a net.UDPAddr.

func NewHostNameFromPrefixedNetIP 

func NewHostNameFromPrefixedNetIP(bytes net.IP, prefixLen PrefixLen) (hostName *HostName, err addrerr.AddressValueError)

NewHostNameFromPrefixedNetIP constructs a HostName from a net.IP paired with a prefix length.

func NewHostNameFromPrefixedNetIPAddr 

func NewHostNameFromPrefixedNetIPAddr(addr *net.IPAddr, prefixLen PrefixLen) (hostName *HostName, err addrerr.AddressValueError)

NewHostNameFromPrefixedNetIPAddr constructs a HostName from a net.IPAddr paired with a prefix length.

func NewHostNameParams 

func NewHostNameParams(str string, params addrstrparam.HostNameParams) *HostName

NewHostNameParams constructs a HostName that will parse the given string according to the given parameters.

func (*HostName) AsAddress 

func (host *HostName) AsAddress() *IPAddress

AsAddress returns the address if this host name represents an ip address. Otherwise, this returns nil. Note that the translation includes prefix lengths and IPv6 zones.

This does not resolve addresses or return resolved addresses. Call ToAddress or GetAddress to get the resolved address.

In cases such as IPv6 literals and reverse-DNS hosts, you can check the relevant methods isIpv6Literal or isReverseDNS, in which case this method should return the associated address.

func (*HostName) AsAddressString 

func (host *HostName) AsAddressString() *IPAddressString

AsAddressString returns the address string if this host name represents an ip address or an ip address string. Otherwise, this returns nil. Note that translation includes prefix lengths and IPv6 zones. This does not resolve host names. Call ToAddress or GetAddress to get the resolved address.

func (*HostName) Compare 

func (host *HostName) Compare(other *HostName) int

Compare returns a negative integer, zero, or a positive integer if this host name is less than, equal, or greater than the given host name. Any address item is comparable to any other.

func (*HostName) Equal 

func (host *HostName) Equal(other *HostName) bool

Equal returns true if the given host name matches this one. For hosts to match, they must represent the same addresses or have the same host names. Hosts are not resolved when matching. Also, hosts must have the same port or service. They must have the same masks if they are host names. Even if two hosts are invalid, they match if they have the same invalid string.

func (HostName) Format added in v1.5.4 

func (addrStr HostName) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface. It accepts the verbs hat are applicable to strings, namely the verbs %s, %q, %x and %X.

func (*HostName) GetAddress 

func (host *HostName) GetAddress() *IPAddress

GetAddress attempts to convert this host name to an IP address. If this represents an ip address, returns that address. If this represents a host, returns the resolved ip address of that host. Otherwise, returns nil. GetAddress is similar to ToAddress but does not return any errors.

If you wish to get the represented address while avoiding DNS resolution, use AsAddress or AsAddressString.

func (*HostName) GetHost 

func (host *HostName) GetHost() string

GetHost returns the host string normalized but without port, service, prefix or mask.

If an address, returns the address string normalized, but without port, service, prefix, mask, or brackets for IPv6.

To get a normalized string encompassing all details, use ToNormalizedString.

If not a valid host, returns the zero string.

func (*HostName) GetMask 

func (host *HostName) GetMask() *IPAddress

GetMask returns the resulting mask value if a mask was provided with this host name.

func (*HostName) GetNetworkPrefixLen 

func (host *HostName) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, if a prefix length was supplied, either as part of an address or as part of a domain (in which case the prefix applies to any resolved address). Otherwise, GetNetworkPrefixLen returns nil.

func (*HostName) GetNormalizedLabels 

func (host *HostName) GetNormalizedLabels() []string

GetNormalizedLabels returns an array of normalized strings for this host name instance.

If this represents an IP address, the address segments are separated into the returned array. If this represents a host name string, the domain name segments are separated into the returned array, with the top-level domain name (right-most segment) as the last array element.

The individual segment strings are normalized in the same way as ToNormalizedString.

Ports, service name strings, prefix lengths, and masks are all omitted from the returned array.

func (*HostName) GetPort 

func (host *HostName) GetPort() Port

GetPort returns the port if a port was supplied, otherwise it returns nil.

func (*HostName) GetService 

func (host *HostName) GetService() string

GetService returns the service name if a service name was supplied (which is typically mapped to a port), otherwise it returns an empty string.

func (*HostName) GetValidationOptions 

func (host *HostName) GetValidationOptions() addrstrparam.HostNameParams

GetValidationOptions returns the validation options supplied when constructing the HostName, or the default validation options if none were supplied. It returns nil if no options were used to construct.

func (*HostName) IsAddress 

func (host *HostName) IsAddress() bool

IsAddress returns whether this host name is a string representing a valid specific IP address or subnet.

func (*HostName) IsAddressString 

func (host *HostName) IsAddressString() bool

IsAddressString returns whether this host name is a string representing an IP address or subnet.

func (*HostName) IsAllAddresses 

func (host *HostName) IsAllAddresses() bool

IsAllAddresses returns whether this is an IP address that represents the set all all valid IP addresses (as opposed to an empty string, a specific address, or an invalid format).

func (*HostName) IsEmpty 

func (host *HostName) IsEmpty() bool

IsEmpty returns true if the host name is empty (zero-length).

func (*HostName) IsLocalHost 

func (host *HostName) IsLocalHost() bool

IsLocalHost returns whether this host is "localhost".

func (*HostName) IsLoopback 

func (host *HostName) IsLoopback() bool

IsLoopback returns whether this host has the loopback address, such as "::1" or "127.0.0.1".

Also see IsSelf.

func (*HostName) IsReverseDNS added in v1.3.0 

func (host *HostName) IsReverseDNS() bool

IsReverseDNS returns whether this host name is a reverse-DNS string host name.

func (*HostName) IsSelf 

func (host *HostName) IsSelf() bool

IsSelf returns whether this represents a host or address representing the same host. Also see IsLocalHost and IsLoopback.

func (*HostName) IsUncIPv6Literal added in v1.3.0 

func (host *HostName) IsUncIPv6Literal() bool

IsUncIPv6Literal returns whether this host name is an Uniform Naming Convention IPv6 literal host name.

func (*HostName) IsValid 

func (host *HostName) IsValid() bool

IsValid returns whether this represents a valid host name or IP address format.

func (*HostName) ResolvesToSelf 

func (host *HostName) ResolvesToSelf() bool

ResolvesToSelf returns whether this represents, or resolves to, a host or address representing the same host.

func (*HostName) String 

func (host *HostName) String() string

String implements the fmt.Stringer interface, returning the original string used to create this HostName (altered by strings.TrimSpace if a host name and not an address), or "<nil>" if the receiver is a nil pointer.

func (*HostName) ToAddress 

func (host *HostName) ToAddress() (addr *IPAddress, err addrerr.AddressError)

ToAddress resolves to an address. This method can potentially return a list of resolved addresses and an error as well, if some resolved addresses were invalid.

func (*HostName) ToAddresses 

func (host *HostName) ToAddresses() (addrs []*IPAddress, err addrerr.AddressError)

ToAddresses resolves to one or more addresses. The error can be addrerr.AddressStringError,addrerr.IncompatibleAddressError, or addrerr.HostNameError. This method can potentially return a list of resolved addresses and an error as well if some resolved addresses were invalid.

func (*HostName) ToNetIP 

func (host *HostName) ToNetIP() net.IP

ToNetIP is similar to ToAddress but returns the resulting address as a net.IP.

func (*HostName) ToNetIPAddr 

func (host *HostName) ToNetIPAddr() *net.IPAddr

ToNetIPAddr is similar to ToAddress but returns the resulting address as a net.IPAddr.

func (*HostName) ToNetTCPAddr 

func (host *HostName) ToNetTCPAddr() *net.TCPAddr

ToNetTCPAddr returns the TCPAddr if this HostName both resolves to an address and has an associated port. Otherwise, it returns nil.

func (*HostName) ToNetTCPAddrService 

func (host *HostName) ToNetTCPAddrService(serviceMapper func(string) Port) *net.TCPAddr

ToNetTCPAddrService returns the TCPAddr if this HostName both resolves to an address and has an associated service or port, otherwise returns nil.

func (*HostName) ToNetUDPAddr 

func (host *HostName) ToNetUDPAddr(serviceMapper func(string) Port) *net.UDPAddr

ToNetUDPAddr returns the UDPAddr if this HostName both resolves to an address and has an associated port.

func (*HostName) ToNetUDPAddrService 

func (host *HostName) ToNetUDPAddrService(serviceMapper func(string) Port) *net.UDPAddr

ToNetUDPAddrService returns the UDPAddr if this HostName both resolves to an address and has an associated service or port.

func (*HostName) ToNormalizedString 

func (host *HostName) ToNormalizedString() string

ToNormalizedString provides a normalized string which is lowercase for host strings, and which is the normalized string for addresses.

func (*HostName) ToNormalizedWildcardString 

func (host *HostName) ToNormalizedWildcardString() string

ToNormalizedWildcardString provides a normalized string which is lowercase for host strings, and which is a normalized string for addresses.

func (*HostName) ToQualifiedString 

func (host *HostName) ToQualifiedString() string

ToQualifiedString provides a normalized string which is lowercase for host strings, and which is a normalized string for addresses.

func (*HostName) Validate 

func (host *HostName) Validate() addrerr.HostNameError

Validate validates that this string is a valid address, and if not, returns an error with a descriptive message indicating why it is not.

func (*HostName) Wrap 

func (host *HostName) Wrap() ExtendedIdentifierString

Wrap wraps this host name, returning a WrappedHostName, an implementation of ExtendedIdentifierString, which can be used to write code that works with a host identifier string including IPAddressString, MACAddressString, and HostName.

type IPAddress 

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

IPAddress represents an IP address or subnet, either IPv4 or IPv6 (except for the zero-valued IPAddress which is neither). An IP address is composed of range-valued segments and can optionally have an associated prefix length. The zero value IPAddress has no segments, neither IPv4 nor IPv6, which is not compatible with zero value for IPv4 or IPv6, those being 0.0.0.0 and :: respectively. The zero value is also known as the adaptive zero.

To construct one from a string, use NewIPAddressString, then use the ToAddress or GetAddress method of IPAddressString.

func NewIPAddressFromBytes added in v1.2.0 

func NewIPAddressFromBytes(ip net.IP) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromBytes constructs an address from a slice of bytes. An error is returned when the IP has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromNetIP 

func NewIPAddressFromNetIP(ip net.IP) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromNetIP constructs an address from a net.IP. An error is returned when the IP has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromNetIPAddr 

func NewIPAddressFromNetIPAddr(addr *net.IPAddr) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromNetIPAddr constructs an address or subnet from a net.IPAddr. An error is returned when the IP has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromNetIPMask 

func NewIPAddressFromNetIPMask(ip net.IPMask) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromNetIPMask constructs an address from a net.IPMask. An error is returned when the mask has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromNetIPNet 

func NewIPAddressFromNetIPNet(ipnet *net.IPNet) (*IPAddress, addrerr.AddressError)

NewIPAddressFromNetIPNet constructs a subnet from a net.IPNet. The error can be either addrerr.AddressValueError, when the net.IPNet IP or mask has an invalid number of bytes, or addrerr.IncompatibleAddressError when the mask and the IP from net.IPNet are different IP versions.

func NewIPAddressFromNetNetIPAddr added in v1.5.0 

func NewIPAddressFromNetNetIPAddr(addr netip.Addr) *IPAddress

func NewIPAddressFromNetNetIPPrefix added in v1.5.0 

func NewIPAddressFromNetNetIPPrefix(prefixedAddr netip.Prefix) (*IPAddress, addrerr.AddressError)

func NewIPAddressFromPrefixedNetIP 

func NewIPAddressFromPrefixedNetIP(ip net.IP, prefixLength PrefixLen) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromPrefixedNetIP constructs an address or subnet from a net.IP with a prefix length. An error is returned when the IP has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromPrefixedNetIPAddr 

func NewIPAddressFromPrefixedNetIPAddr(addr *net.IPAddr, prefixLength PrefixLen) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromPrefixedNetIPAddr constructs an address or subnet from a net.IPAddr with a prefix length. An error is returned when the IP has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromPrefixedSegments 

func NewIPAddressFromPrefixedSegments(segs []*IPAddressSegment, prefixLength PrefixLen) (res *IPAddress, err addrerr.AddressValueError)

NewIPAddressFromPrefixedSegments constructs an address from the given segments and prefix length. If the segments are not consistently IPv4 or IPv6, or if there is not the correct number of segments for the IP version (4 for IPv4, 8 for IPv6), then an error is returned.

func NewIPAddressFromPrefixedVals 

func NewIPAddressFromPrefixedVals(version IPVersion, lowerValueProvider, upperValueProvider SegmentValueProvider, prefixLength PrefixLen) *IPAddress

NewIPAddressFromPrefixedVals constructs an IPAddress from the provided segment values and prefix length. If the given version is indeterminate, then nil is returned. The prefix length is adjusted to 0 if negative or to the bit count if larger.

func NewIPAddressFromPrefixedZonedVals 

func NewIPAddressFromPrefixedZonedVals(version IPVersion, lowerValueProvider, upperValueProvider SegmentValueProvider, prefixLength PrefixLen, zone string) *IPAddress

NewIPAddressFromPrefixedZonedVals constructs an IPAddress from the provided segment values, prefix length, and zone. If the given version is indeterminate, then nil is returned. If the version is IPv4, then the zone is ignored. The prefix length is adjusted to 0 if negative or to the bit count if larger.

func NewIPAddressFromSegs added in v1.2.0 

func NewIPAddressFromSegs(segments []*IPAddressSegment) (res *IPAddress, err addrerr.AddressValueError)

NewIPAddressFromSegs constructs an address from the given segments. If the segments are not consistently IPv4 or IPv6, or if there is not the correct number of segments for the IP version (4 for IPv4, 8 for IPv6), then an error is returned.

func NewIPAddressFromVals 

func NewIPAddressFromVals(version IPVersion, lowerValueProvider SegmentValueProvider) *IPAddress

NewIPAddressFromVals constructs an IPAddress from the provided segment values. If the given version is indeterminate, then nil is returned.

func NewIPAddressFromValueProvider 

func NewIPAddressFromValueProvider(valueProvider IPAddressValueProvider) *IPAddress

NewIPAddressFromValueProvider constructs an IPAddress from the provided segment values, prefix length, and zone, all of which are supplied by the implementation of IPAddressValueProvider. If the given version is indeterminate, then nil is returned. If the version is IPv4, then the zone is ignored. The prefix length is adjusted to 0 if negative or to the bit count if larger.

func (*IPAddress) AdjustPrefixLen 

func (addr *IPAddress) AdjustPrefixLen(prefixLen BitCount) *IPAddress

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*IPAddress) AdjustPrefixLenZeroed 

func (addr *IPAddress) AdjustPrefixLenZeroed(prefixLen BitCount) (*IPAddress, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

For example, "1.2.0.0/16" adjusted by -8 becomes "1.0.0.0/8". "1.2.0.0/16" adjusted by 8 becomes "1.2.0.0/24".

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPAddress) AssignMinPrefixForBlock 

func (addr *IPAddress) AssignMinPrefixForBlock() *IPAddress

AssignMinPrefixForBlock returns an equivalent subnet, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this subnet.

In other words, this method assigns a prefix length to this subnet matching the largest prefix block in this subnet.

Examples:

  • 1.2.3.4 returns 1.2.3.4/32
  • 1.2.*.* returns 1.2.0.0/16
  • 1.2.*.0/24 returns 1.2.0.0/16
  • 1.2.*.4 returns 1.2.*.4/32
  • 1.2.0-1.* returns 1.2.0.0/23
  • 1.2.1-2.* returns 1.2.1-2.0/24
  • 1.2.252-255.* returns 1.2.252.0/22
  • 1.2.3.4/16 returns 1.2.3.4/32

func (*IPAddress) AssignPrefixForSingleBlock 

func (addr *IPAddress) AssignPrefixForSingleBlock() *IPAddress

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address - it is required that the range of values match the range of a prefix block. If there is no such address, then nil is returned.

Examples:

  • 1.2.3.4 returns 1.2.3.4/32
  • 1.2.*.* returns 1.2.0.0/16
  • 1.2.*.0/24 returns 1.2.0.0/16
  • 1.2.*.4 returns nil
  • 1.2.0-1.* returns 1.2.0.0/23
  • 1.2.1-2.* returns nil
  • 1.2.252-255.* returns 1.2.252.0/22
  • 1.2.3.4/16 returns 1.2.3.4/32

func (*IPAddress) BitwiseOr 

func (addr *IPAddress) BitwiseOr(other *IPAddress) (masked *IPAddress, err addrerr.IncompatibleAddressError)

BitwiseOr does the bitwise disjunction with this address or subnet, useful when subnetting. It is similar to Mask which does the bitwise conjunction.

The operation is applied to all individual addresses and the result is returned.

If the given address is a different version than this, then an error is returned.

If this is a subnet representing multiple addresses, and applying the operations to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned.

func (*IPAddress) BlockIterator 

func (addr *IPAddress) BlockIterator(segmentCount int) Iterator[*IPAddress]

BlockIterator iterates through the addresses that can be obtained by iterating through all the upper segments up to the given segment count. The segments following remain the same in all iterated addresses.

For instance, given the IPv4 subnet "1-2.3-4.5-6.7" and the count argument 2, BlockIterator will iterate through "1.3.5-6.7", "1.4.5-6.7", "2.3.5-6.7" and "2.4.5-6.7".

func (*IPAddress) Bytes 

func (addr *IPAddress) Bytes() []byte

Bytes returns the lowest address in this subnet or address as a byte slice.

func (*IPAddress) Compare 

func (addr *IPAddress) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address or subnet is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPAddress) CompareSize 

func (addr *IPAddress) CompareSize(other AddressItem) int

CompareSize compares the counts of two subnets or addresses or other items, the number of individual items within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one subnet represents more individual addresses than another.

CompareSize returns a positive integer if this address or subnet has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPAddress) Contains 

func (addr *IPAddress) Contains(other AddressType) bool

Contains returns whether this is the same type and version as the given address or subnet and whether it contains all addresses in the given address or subnet.

func (*IPAddress) ContainsPrefixBlock 

func (addr *IPAddress) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or subnet contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPAddress) ContainsSinglePrefixBlock 

func (addr *IPAddress) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPAddress) CopyBytes 

func (addr *IPAddress) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address in the subnet into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddress) CopyNetIP 

func (addr *IPAddress) CopyNetIP(ip net.IP) net.IP

CopyNetIP copies the value of the lowest individual address in the subnet into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddress) CopySegments 

func (addr *IPAddress) CopySegments(segs []*IPAddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPAddress) CopySubSegments 

func (addr *IPAddress) CopySubSegments(start, end int, segs []*IPAddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPAddress) CopyUpperBytes 

func (addr *IPAddress) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address in the subnet into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddress) CopyUpperNetIP 

func (addr *IPAddress) CopyUpperNetIP(ip net.IP) net.IP

CopyUpperNetIP copies the value of the highest individual address in the subnet into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddress) CoverWithPrefixBlock 

func (addr *IPAddress) CoverWithPrefixBlock() *IPAddress

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the addresses in this subnet. The resulting block will have a larger subnet size than this, unless this subnet is already a prefix block.

func (*IPAddress) CoverWithPrefixBlockTo 

func (addr *IPAddress) CoverWithPrefixBlockTo(other *IPAddress) *IPAddress

CoverWithPrefixBlockTo returns the minimal-size prefix block that covers all the addresses spanning from this subnet to the given subnet.

If the argument is not the same IP version as the receiver, the argument is ignored, and the result is the same as CoverWithPrefixBlock.

func (*IPAddress) Equal 

func (addr *IPAddress) Equal(other AddressType) bool

Equal returns whether the given address or subnet is equal to this address or subnet. Two address instances are equal if they represent the same set of addresses.

func (*IPAddress) ForEachSegment added in v1.2.0 

func (addr *IPAddress) ForEachSegment(consumer func(segmentIndex int, segment *IPAddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (IPAddress) Format 

func (addr IPAddress) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*IPAddress) GetBitCount 

func (addr *IPAddress) GetBitCount() BitCount

GetBitCount returns the number of bits comprising this address, or each address in the range if a subnet, which is 32 for IPv4 and 128 for IPv6.

func (*IPAddress) GetBlockCount 

func (addr *IPAddress) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*IPAddress) GetBlockMaskPrefixLen 

func (addr *IPAddress) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address with all ones in the network section and then all zeros in the host section. A CIDR host mask is an address with all zeros in the network section and then all ones in the host section. The prefix length is the bit-length of the network section.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this instance, indicating the network and host section of this address. The prefix length returned here indicates the whether the value of this address can be used as a mask for the network and host section of any other address. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this address represents multiple values.

func (*IPAddress) GetByteCount 

func (addr *IPAddress) GetByteCount() int

GetByteCount returns the number of bytes required for this address, or each address in the range if a subnet, which is 4 for IPv4 and 16 for IPv6.

func (*IPAddress) GetCount 

func (addr *IPAddress) GetCount() *big.Int

GetCount returns the count of addresses that this address or subnet represents.

If just a single address, not a subnet of multiple addresses, returns 1.

For instance, the IP address subnet "2001:db8::/64" has the count of 2 to the power of 64.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPAddress) GetDivisionCount 

func (addr *IPAddress) GetDivisionCount() int

GetDivisionCount returns the segment count.

func (*IPAddress) GetGenericDivision 

func (addr *IPAddress) GetGenericDivision(index int) DivisionType

GetGenericDivision returns the segment at the given index as a DivisionType.

func (*IPAddress) GetGenericSegment 

func (addr *IPAddress) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPAddress) GetHostMask 

func (addr *IPAddress) GetHostMask() *IPAddress

GetHostMask returns the host mask associated with the CIDR network prefix length of this address or subnet. If this address or subnet has no prefix length, then the all-ones mask is returned.

func (*IPAddress) GetHostSection 

func (addr *IPAddress) GetHostSection() *IPAddressSection

GetHostSection returns a section containing the segments with the host of the address or subnet, the bits beyond the CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

If this series has no prefix length, the returned host section will be the full section.

func (*IPAddress) GetHostSectionLen 

func (addr *IPAddress) GetHostSectionLen(prefLen BitCount) *IPAddressSection

GetHostSectionLen returns a section containing the segments with the host of the address or subnet, the bits beyond the given CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

func (*IPAddress) GetIPVersion 

func (addr *IPAddress) GetIPVersion() IPVersion

GetIPVersion returns the IP version of this IP address.

func (*IPAddress) GetLeadingBitCount 

func (addr *IPAddress) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower value of the range if this is a subnet representing multiple values.

func (*IPAddress) GetLower 

func (addr *IPAddress) GetLower() *IPAddress

GetLower returns the lowest address in the subnet range, which will be the receiver if it represents a single address. For example, for the subnet "1.2-3.4.5-6", the address "1.2.4.5" is returned.

func (*IPAddress) GetLowerIPAddress 

func (addr *IPAddress) GetLowerIPAddress() *IPAddress

GetLowerIPAddress returns the address in the subnet or address collection with the lowest numeric value, which will be the receiver if it represents a single address. For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned. GetLowerIPAddress implements the IPAddressRange interface, and is equivalent to GetLower.

func (*IPAddress) GetMaxSegmentValue 

func (addr *IPAddress) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPAddress) GetMinPrefixLenForBlock 

func (addr *IPAddress) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

See AssignMinPrefixForBlock for some examples.

func (*IPAddress) GetNetIP 

func (addr *IPAddress) GetNetIP() net.IP

GetNetIP returns the lowest address in this subnet or address as a net.IP.

func (*IPAddress) GetNetIPAddr 

func (addr *IPAddress) GetNetIPAddr() *net.IPAddr

GetNetIPAddr returns the lowest address in this subnet or address as a net.IPAddr.

func (*IPAddress) GetNetNetIPAddr added in v1.5.0 

func (addr *IPAddress) GetNetNetIPAddr() netip.Addr

GetNetNetIPAddr returns the lowest address in this subnet or address range as a netip.Addr.

func (*IPAddress) GetNetwork 

func (addr *IPAddress) GetNetwork() IPAddressNetwork

GetNetwork returns the singleton network instance for the IP version of this address or subnet.

func (*IPAddress) GetNetworkMask 

func (addr *IPAddress) GetNetworkMask() *IPAddress

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address or subnet. If this address or subnet has no prefix length, then the all-ones mask is returned.

func (*IPAddress) GetNetworkPrefixLen 

func (addr *IPAddress) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. GetNetworkPrefixLen is equivalent to the method GetPrefixLen.

func (*IPAddress) GetNetworkSection 

func (addr *IPAddress) GetNetworkSection() *IPAddressSection

GetNetworkSection returns an address section containing the segments with the network of the address or subnet, the prefix bits. The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.

If this series has no CIDR prefix length, the returned network section will be the entire series as a prefixed section with prefix length matching the address bit length.

func (*IPAddress) GetNetworkSectionLen 

func (addr *IPAddress) GetNetworkSectionLen(prefLen BitCount) *IPAddressSection

GetNetworkSectionLen returns a section containing the segments with the network of the address or subnet, the prefix bits according to the given prefix length. The returned section will have only as many segments as needed to contain the network.

The new section will be assigned the given prefix length, unless the existing prefix length is smaller, in which case the existing prefix length will be retained.

func (*IPAddress) GetPrefixCount 

func (addr *IPAddress) GetPrefixCount() *big.Int

GetPrefixCount returns the count of prefixes in this address or subnet.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the count of the range of values in the prefix.

If this has a nil prefix length, returns the same value as GetCount.

func (*IPAddress) GetPrefixCountLen 

func (addr *IPAddress) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the count of prefixes in this address or subnet for the given prefix length.

If not a subnet of multiple addresses, or a subnet with just single prefix of the given length, returns 1.

func (*IPAddress) GetPrefixLen 

func (addr *IPAddress) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part of the address that comprise the prefix.

A prefix is a part of the address that is not specific to that address but common amongst a group of addresses, such as a CIDR prefix block subnet.

For IP addresses, the prefix is explicitly defined when the address is created. For example, "1.2.0.0/16" has a prefix length of 16, while "1.2.*.*" has no prefix length, even though they both represent the same set of addresses and are considered equal. Prefixes can be considered variable for a given IP address and can depend on routing.

The methods GetMinPrefixLenForBlock and GetPrefixLenForSingleBlock can help you to obtain or define a prefix length if one does not exist already. The method ToPrefixBlockLen allows you to create the subnet consisting of the block of addresses for any given prefix length.

func (*IPAddress) GetPrefixLenForSingleBlock 

func (addr *IPAddress) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address subnet matches exactly the block of addresses for that prefix.

If the range can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix exists, returns nil.

If this segment grouping represents a single value, returns the bit length of this address division series.

IP address examples:

  • 1.2.3.4 returns 32
  • 1.2.3.4/16 returns 32
  • 1.2.*.* returns 16
  • 1.2.*.0/24 returns 16
  • 1.2.0.0/16 returns 16
  • 1.2.*.4 returns nil
  • 1.2.252-255.* returns 22

func (*IPAddress) GetSection 

func (addr *IPAddress) GetSection() *IPAddressSection

GetSection returns the backing section for this address or subnet, comprising all segments.

func (*IPAddress) GetSegment 

func (addr *IPAddress) GetSegment(index int) *IPAddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPAddress) GetSegmentCount 

func (addr *IPAddress) GetSegmentCount() int

GetSegmentCount returns the segment count, the number of segments in this address.

func (*IPAddress) GetSegmentStrings 

func (addr *IPAddress) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*IPAddress) GetSegments 

func (addr *IPAddress) GetSegments() []*IPAddressSegment

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*IPAddress) GetSequentialBlockCount 

func (addr *IPAddress) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential subnets that comprise this subnet.

func (*IPAddress) GetSequentialBlockIndex 

func (addr *IPAddress) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full subnet to be sequential, the preceding segments must be single-valued.

func (*IPAddress) GetSubSection 

func (addr *IPAddress) GetSubSection(index, endIndex int) *IPAddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*IPAddress) GetTrailingBitCount 

func (addr *IPAddress) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies to the lower value of the range if this is a subnet representing multiple values.

func (*IPAddress) GetTrailingSection 

func (addr *IPAddress) GetTrailingSection(index int) *IPAddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*IPAddress) GetUpper 

func (addr *IPAddress) GetUpper() *IPAddress

GetUpper returns the highest address in the subnet range, which will be the receiver if it represents a single address. For example, for "1.2-3.4.5-6", the series "1.3.4.6" is returned.

func (*IPAddress) GetUpperIPAddress 

func (addr *IPAddress) GetUpperIPAddress() *IPAddress

GetUpperIPAddress returns the address in the subnet or address collection with the highest numeric value, which will be the receiver if it represents a single address. For example, for the subnet "1.2-3.4.5-6", the address "1.3.4.6" is returned. GetUpperIPAddress implements the IPAddressRange interface, and is equivalent to GetUpper.

func (*IPAddress) GetUpperNetIP 

func (addr *IPAddress) GetUpperNetIP() net.IP

GetUpperNetIP returns the highest address in this subnet or address as a net.IP.

func (*IPAddress) GetUpperNetIPAddr added in v1.2.0 

func (addr *IPAddress) GetUpperNetIPAddr() *net.IPAddr

GetUpperNetIPAddr returns the highest address in this subnet or address as a net.IPAddr.

func (*IPAddress) GetUpperNetNetIPAddr added in v1.5.0 

func (addr *IPAddress) GetUpperNetNetIPAddr() netip.Addr

GetUpperNetNetIPAddr returns the highest address in this subnet or address range as a netip.Addr.

func (*IPAddress) GetUpperValue 

func (addr *IPAddress) GetUpperValue() *big.Int

GetUpperValue returns the highest address in this subnet or address as an integer value.

func (*IPAddress) GetValue 

func (addr *IPAddress) GetValue() *big.Int

GetValue returns the lowest address in this subnet or address as an integer value.

func (*IPAddress) IncludesMax 

func (addr *IPAddress) IncludesMax() bool

IncludesMax returns whether this address includes the max address, the address whose bits are all ones, within its range.

func (*IPAddress) IncludesMaxHost 

func (addr *IPAddress) IncludesMaxHost() bool

IncludesMaxHost returns whether the subnet contains an individual address with a host of all one-bits. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are one.

func (*IPAddress) IncludesMaxHostLen 

func (addr *IPAddress) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the subnet contains an individual address with a host of all one-bits, an individual address for which all bits past the given prefix length are all ones.

func (*IPAddress) IncludesZeroHost 

func (addr *IPAddress) IncludesZeroHost() bool

IncludesZeroHost returns whether the subnet contains an individual address with a host of zero. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are zero.

func (*IPAddress) IncludesZeroHostLen 

func (addr *IPAddress) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the subnet contains an individual address with a host of zero, an individual address for which all bits past the given prefix length are zero.

func (*IPAddress) Increment 

func (addr *IPAddress) Increment(increment int64) *IPAddress

Increment returns the address from the subnet that is the given increment upwards into the subnet range, with the increment of 0 returning the first address in the range.

If the increment i matches or exceeds the subnet size count c, then i - c + 1 is added to the upper address of the range. An increment matching the subnet count gives you the address just above the highest address in the subnet.

If the increment is negative, it is added to the lower address of the range. To get the address just below the lowest address of the subnet, use the increment -1.

If this is just a single address value, the address is simply incremented by the given increment, positive or negative.

If this is a subnet with multiple values, a positive increment i is equivalent i + 1 values from the subnet iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the subnet count is equivalent to the same number of iterator values preceding the upper bound of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On address overflow or underflow, Increment returns nil.

func (*IPAddress) IncrementBoundary 

func (addr *IPAddress) IncrementBoundary(increment int64) *IPAddress

IncrementBoundary returns the address that is the given increment from the range boundaries of this subnet.

If the given increment is positive, adds the value to the upper address (GetUpper) in the subnet range to produce a new address. If the given increment is negative, adds the value to the lower address (GetLower) in the subnet range to produce a new address. If the increment is zero, returns this address.

If this is a single address value, that address is simply incremented by the given increment value, positive or negative.

On address overflow or underflow, IncrementBoundary returns nil.

func (*IPAddress) Intersect 

func (addr *IPAddress) Intersect(other *IPAddress) *IPAddress

Intersect returns the subnet whose addresses are found in both this and the given subnet argument, or nil if no such addresses exist.

This is also known as the conjunction of the two sets of addresses.

func (*IPAddress) IsAnyLocal 

func (addr *IPAddress) IsAnyLocal() bool

IsAnyLocal returns whether this address is the address which binds to any address on the local host. This is the address that has the value of 0, aka the unspecified address.

func (*IPAddress) IsIPv4 

func (addr *IPAddress) IsIPv4() bool

IsIPv4 returns true if this address or subnet originated as an IPv4 address or subnet. If so, use ToIPv4 to convert back to the IPv4-specific type.

func (*IPAddress) IsIPv6 

func (addr *IPAddress) IsIPv6() bool

IsIPv6 returns true if this address or subnet originated as an IPv6 address or subnet. If so, use ToIPv6 to convert back to the IPv6-specific type.

func (*IPAddress) IsLinkLocal 

func (addr *IPAddress) IsLinkLocal() bool

IsLinkLocal returns whether the address or subnet is entirely link local, whether unicast or multicast.

func (*IPAddress) IsLocal 

func (addr *IPAddress) IsLocal() bool

IsLocal returns true if the address is link local, site local, organization local, administered locally, or unspecified. This includes both unicast and multicast.

func (*IPAddress) IsLoopback 

func (addr *IPAddress) IsLoopback() bool

IsLoopback returns whether this address is a loopback address, such as "::1" or "127.0.0.1".

func (*IPAddress) IsMax 

func (addr *IPAddress) IsMax() bool

IsMax returns whether this address matches exactly the maximum possible value, the address whose bits are all ones.

func (*IPAddress) IsMaxHost 

func (addr *IPAddress) IsMaxHost() bool

IsMaxHost returns whether this section has a prefix length and if so, whether the host section is always all one-bits, the max value, for all individual addresses in this subnet.

If the host section is zero length (there are zero host bits), IsMaxHost returns true.

func (*IPAddress) IsMaxHostLen 

func (addr *IPAddress) IsMaxHostLen(prefLen BitCount) bool

IsMaxHostLen returns whether the host is all one-bits, the max value, for all individual addresses in this subnet, for the given prefix length, the host being the bits following the prefix.

If the host section is zero length (there are zero host bits), IsMaxHostLen returns true.

func (*IPAddress) IsMulticast 

func (addr *IPAddress) IsMulticast() bool

IsMulticast returns whether this address or subnet is entirely multicast.

func (*IPAddress) IsMultiple 

func (addr *IPAddress) IsMultiple() bool

IsMultiple returns true if this represents more than a single individual address, whether it is a subnet of multiple addresses.

func (*IPAddress) IsOneBit 

func (addr *IPAddress) IsOneBit(bitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*IPAddress) IsPrefixBlock 

func (addr *IPAddress) IsPrefixBlock() bool

IsPrefixBlock returns whether the address has a prefix length and the address range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

To create a prefix block from any address, use ToPrefixBlock.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*IPAddress) IsPrefixed 

func (addr *IPAddress) IsPrefixed() bool

IsPrefixed returns whether this address has an associated prefix length.

func (*IPAddress) IsSingleNetwork 

func (addr *IPAddress) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address.

func (*IPAddress) IsSinglePrefixBlock 

func (addr *IPAddress) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the address range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

For instance, "1.*.*.* /16" returns false from this method and returns true from IsPrefixBlock.

func (*IPAddress) IsUnspecified 

func (addr *IPAddress) IsUnspecified() bool

IsUnspecified returns true if exactly zero. The unspecified address is the address that is all zeros.

func (*IPAddress) IsZeroHost 

func (addr *IPAddress) IsZeroHost() bool

IsZeroHost returns whether this subnet has a prefix length and if so, whether the host section is always zero for all individual addresses in this subnet.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (*IPAddress) IsZeroHostLen 

func (addr *IPAddress) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual addresses in this subnet, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (*IPAddress) Iterator 

func (addr *IPAddress) Iterator() Iterator[*IPAddress]

Iterator provides an iterator to iterate through the individual addresses of this address or subnet.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual addresses.

Call IsMultiple to determine if this instance represents multiple addresses, or GetCount for the count.

func (*IPAddress) Mask 

func (addr *IPAddress) Mask(other *IPAddress) (masked *IPAddress, err addrerr.IncompatibleAddressError)

Mask applies the given mask to all addresses represented by this IPAddress. The mask is applied to all individual addresses.

If the mask is a different version than this, then an error is returned.

If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned.

func (*IPAddress) MatchesWithMask 

func (addr *IPAddress) MatchesWithMask(other *IPAddress, mask *IPAddress) bool

MatchesWithMask applies the mask to this address and then compares the result with the given address, returning true if they match, false otherwise.

func (*IPAddress) MergeToPrefixBlocks 

func (addr *IPAddress) MergeToPrefixBlocks(addrs ...*IPAddress) []*IPAddress

MergeToPrefixBlocks merges this subnet with the list of subnets to produce the smallest array of prefix blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block. Arguments that are not the same IP version are ignored.

func (*IPAddress) MergeToSequentialBlocks 

func (addr *IPAddress) MergeToSequentialBlocks(addrs ...*IPAddress) []*IPAddress

MergeToSequentialBlocks merges this with the list of addresses to produce the smallest array of sequential blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block. Arguments that are not the same IP version are ignored.

func (*IPAddress) PrefixBlockIterator 

func (addr *IPAddress) PrefixBlockIterator() Iterator[*IPAddress]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address or subnet. Each iterated address or subnet will be a prefix block with the same prefix length as this address or subnet.

If this address has no prefix length, then this is equivalent to Iterator.

func (*IPAddress) PrefixContains 

func (addr *IPAddress) PrefixContains(other AddressType) bool

PrefixContains returns whether the prefix values in the given address or subnet are prefix values in this address or subnet, using the prefix length of this address or subnet. If this address has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

func (*IPAddress) PrefixEqual 

func (addr *IPAddress) PrefixEqual(other AddressType) bool

PrefixEqual determines if the given address matches this address up to the prefix length of this address. It returns whether the two addresses share the same range of prefix values.

func (*IPAddress) PrefixIterator 

func (addr *IPAddress) PrefixIterator() Iterator[*IPAddress]

PrefixIterator provides an iterator to iterate through the individual prefixes of this subnet, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this subnet.

If the subnet has no prefix length, then this is equivalent to Iterator.

func (*IPAddress) ReverseBits 

func (addr *IPAddress) ReverseBits(perByte bool) (*IPAddress, addrerr.IncompatibleAddressError)

ReverseBits returns a new address with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPAddress) ReverseBytes 

func (addr *IPAddress) ReverseBytes() (*IPAddress, addrerr.IncompatibleAddressError)

ReverseBytes returns a new address with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (*IPAddress) ReverseSegments 

func (addr *IPAddress) ReverseSegments() *IPAddress

ReverseSegments returns a new address with the segments reversed.

func (*IPAddress) SequentialBlockIterator 

func (addr *IPAddress) SequentialBlockIterator() Iterator[*IPAddress]

SequentialBlockIterator iterates through the sequential subnets or addresses that make up this address or subnet.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

For instance, given the IPv4 subnet "1-2.3-4.5-6.7-8", it will iterate through "1.3.5.7-8", "1.3.6.7-8", "1.4.5.7-8", "1.4.6.7-8", "2.3.5.7-8", "2.3.6.7-8", "2.4.6.7-8" and "2.4.6.7-8".

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPAddress) SetPrefixLen 

func (addr *IPAddress) SetPrefixLen(prefixLen BitCount) *IPAddress

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPAddress) SetPrefixLenZeroed 

func (addr *IPAddress) SetPrefixLenZeroed(prefixLen BitCount) (*IPAddress, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address. The provided prefix length will be adjusted to these boundaries if necessary.

If this address has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPAddress) SpanWithPrefixBlocks 

func (addr *IPAddress) SpanWithPrefixBlocks() []*IPAddress

SpanWithPrefixBlocks returns an array of prefix blocks that cover the same set of addresses as this subnet.

Unlike SpanWithPrefixBlocksTo, the result only includes addresses that are a part of this subnet.

func (*IPAddress) SpanWithPrefixBlocksTo 

func (addr *IPAddress) SpanWithPrefixBlocksTo(other *IPAddress) []*IPAddress

SpanWithPrefixBlocksTo returns the smallest slice of prefix block subnets that span from this subnet to the given subnet.

If the given address is a different version than this, then the given address is ignored, and the result is equivalent to calling SpanWithPrefixBlocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

From the list of returned subnets you can recover the original range (this to other) by converting each to IPAddressRange with ToSequentialRange and them joining them into a single range with the Join method of IPAddressSeqRange.

func (*IPAddress) SpanWithRange 

func (addr *IPAddress) SpanWithRange(other *IPAddress) *SequentialRange[*IPAddress]

SpanWithRange returns an IPAddressSeqRange instance that spans this subnet to the given subnet. If the other address is a different version than this, then the other is ignored, and the result is equivalent to calling ToSequentialRange.

func (*IPAddress) SpanWithSequentialBlocks 

func (addr *IPAddress) SpanWithSequentialBlocks() []*IPAddress

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of addresses as this subnet.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

Unlike SpanWithSequentialBlocksTo, this method only includes addresses that are a part of this subnet.

func (*IPAddress) SpanWithSequentialBlocksTo 

func (addr *IPAddress) SpanWithSequentialBlocksTo(other *IPAddress) []*IPAddress

SpanWithSequentialBlocksTo produces the smallest slice of sequential block subnets that span all values from this subnet to the given subnet. The span will cover all addresses in both subnets and everything in between.

Individual block subnets come in the form "1-3.1-4.5.6-8", however that particular subnet is not sequential since address "1.1.5.8" is in the subnet, the next sequential address "1.1.5.9" is not in the subnet, and a higher address "1.2.5.6" is in the subnet. Blocks are sequential when the first segment with a range of values is followed by segments that span all values.

If the other address is a different version than this, then this is equivalent to calling SpanWithSequentialBlocks on this subnet.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPAddress) String 

func (addr *IPAddress) String() string

String implements the fmt.Stringer interface, returning the canonical string provided by ToCanonicalString, or "<nil>" if the receiver is a nil pointer.

func (*IPAddress) Subtract 

func (addr *IPAddress) Subtract(other *IPAddress) []*IPAddress

Subtract subtracts the given subnet from this subnet, returning an array of subnets for the result (the subnets will not be contiguous so an array is required). Subtract computes the subnet difference, the set of addresses in this address subnet but not in the provided subnet. This is also known as the relative complement of the given argument in this subnet. This is set subtraction, not subtraction of address values (use Increment for the latter). We have a subnet of addresses and we are removing those addresses found in the argument subnet. If there are no remaining addresses, nil is returned.

func (*IPAddress) TestBit 

func (addr *IPAddress) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this address. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPAddress) ToAddressBase 

func (addr *IPAddress) ToAddressBase() *Address

ToAddressBase converts to an Address, a polymorphic type usable with all addresses and subnets. Afterwards, you can convert back with ToIP.

ToAddressBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddress) ToAddressString 

func (addr *IPAddress) ToAddressString() *IPAddressString

ToAddressString retrieves or generates an IPAddressString instance for this IPAddress instance. This may be the IPAddressString this instance was generated from, if it was generated from an IPAddressString.

In general, users are intended to create IPAddress instances from IPAddressString instances, while the reverse direction is generally not common and not useful, except under specific circumstances.

However, the reverse direction can be useful under certain circumstances, such as when maintaining a collection of HostIdentifierString or IPAddressString instances.

func (*IPAddress) ToBinaryString 

func (addr *IPAddress) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPAddress) ToBlock 

func (addr *IPAddress) ToBlock(segmentIndex int, lower, upper SegInt) *IPAddress

ToBlock creates a new block of addresses by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPAddress) ToCanonicalHostName 

func (addr *IPAddress) ToCanonicalHostName() (*HostName, error)

ToCanonicalHostName does a reverse name lookup to get the canonical host name. Note that the canonical host name may differ on different systems.

This returns an error if this address is a subnet multiple values.

func (*IPAddress) ToCanonicalString 

func (addr *IPAddress) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address.

For IPv4, dotted octet format, also known as dotted decimal format, is used. https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

For MAC, it uses the canonical standardized IEEE 802 MAC address representation of xx-xx-xx-xx-xx-xx. An example is "01-23-45-67-89-ab". For range segments, '|' is used: "11-22-33|44-55-66".

Each address has a unique canonical string, not counting the prefix length. With IP addresses, the prefix length is included in the string, and the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use ToCanonicalWildcardString for a unique string for each IP address and subnet.

func (*IPAddress) ToCanonicalWildcardString 

func (addr *IPAddress) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string and avoids the CIDR prefix length. Addresses and subnets with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. IPv6 addresses will be compressed according to the canonical representation. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPAddress) ToCompressedString 

func (addr *IPAddress) ToCompressedString() string

ToCompressedString produces a short representation of this address while remaining within the confines of standard representation(s) of the address.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.

func (*IPAddress) ToCompressedWildcardString 

func (addr *IPAddress) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, avoiding the CIDR prefix, but with full IPv6 segment compression as well, including single zero-segments. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPAddress) ToCustomString 

func (addr *IPAddress) ToCustomString(stringOptions addrstr.IPStringOptions) string

ToCustomString creates a customized string from this address or subnet according to the given string option parameters.

func (*IPAddress) ToFullString 

func (addr *IPAddress) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 4 characters for IPv6 segments and 3 characters for IPv4 segments.

func (*IPAddress) ToGenericKey added in v1.5.1 

func (addr *IPAddress) ToGenericKey() Key[*IPAddress]

ToGenericKey produces a generic Key[*IPAddress] that can be used with generic code working with Address, IPAddress, IPv4Address, IPv6Address and MACAddress.

func (*IPAddress) ToHexString 

func (addr *IPAddress) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPAddress) ToHostName 

func (addr *IPAddress) ToHostName() *HostName

ToHostName returns the HostName used to resolve, if this address was resolved from a host. Otherwise, if this address represents a subnet of multiple addresses, returns a HostName for that subnet. Otherwise, it does a reverse name lookup to obtain the proper HostName.

func (*IPAddress) ToIP 

func (addr *IPAddress) ToIP() *IPAddress

ToIP is an identity method.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddress) ToIPv4 

func (addr *IPAddress) ToIPv4() *IPv4Address

ToIPv4 converts to an IPv4Address if this address or subnet originated as an IPv4 address or subnet. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddress) ToIPv6 

func (addr *IPAddress) ToIPv6() *IPv6Address

ToIPv6 converts to an IPv6Address if this address or subnet originated as an IPv6 address or subnet. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddress) ToKey added in v1.1.0 

func (addr *IPAddress) ToKey() Key[*IPAddress]

ToKey creates the associated address key. While addresses can be compared with the Compare, TrieCompare or Equal methods as well as various provided instances of AddressComparator, they are not comparable with Go operators. However, AddressKey instances are comparable with Go operators, and thus can be used as map keys.

func (*IPAddress) ToMaxHost 

func (addr *IPAddress) ToMaxHost() (*IPAddress, addrerr.IncompatibleAddressError)

ToMaxHost converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-ones address, the max address.

The returned address or subnet will have the same prefix and prefix length.

For instance, the max host of "1.2.3.4/16" gives the broadcast address "1.2.255.255/16".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPAddress) ToMaxHostLen 

func (addr *IPAddress) ToMaxHostLen(prefixLength BitCount) (*IPAddress, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the resulting one will too, otherwise the resulting address or subnet will have no prefix length.

For instance, the zero host of "1.2.3.4" for the prefix length of 16 is the address "1.2.255.255".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPAddress) ToNormalizedString 

func (addr *IPAddress) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. Zero-segments are not compressed.

Each address has a unique normalized string, not counting the prefix length. With IP addresses, the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use the method ToNormalizedWildcardString for a unique string for each IP address and subnet.

func (*IPAddress) ToNormalizedWildcardString 

func (addr *IPAddress) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPAddress) ToOctalString 

func (addr *IPAddress) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPAddress) ToPrefixBlock 

func (addr *IPAddress) ToPrefixBlock() *IPAddress

ToPrefixBlock returns the subnet associated with the prefix length of this address. If this address has no prefix length, this address is returned.

The subnet will include all addresses with the same prefix as this one, the prefix "block". The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is "1.2.3.4/16" it returns the subnet "1.2.0.0/16", which can also be written as "1.2.*.*/16".

func (*IPAddress) ToPrefixBlockLen 

func (addr *IPAddress) ToPrefixBlockLen(prefLen BitCount) *IPAddress

ToPrefixBlockLen returns the subnet associated with the given prefix length.

The subnet will include all addresses with the same prefix as this one, the prefix "block" for that prefix length. The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is "1.2.3.4" and the prefix length provided is 16, it returns the subnet "1.2.0.0/16", which can also be written as "1.2.*.*/16".

func (*IPAddress) ToPrefixLenString 

func (addr *IPAddress) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, a zero host section will be compressed with "::". For IPv4 the string is equivalent to the canonical string.

func (*IPAddress) ToReverseDNSString 

func (addr *IPAddress) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse-DNS lookup string, returning an error if this address is an IPv6 multiple-valued subnet for which the range cannot be represented. For "8.255.4.4" it is "4.4.255.8.in-addr.arpa". For "2001:db8::567:89ab" it is "b.a.9.8.7.6.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa".

func (*IPAddress) ToSQLWildcardString 

func (addr *IPAddress) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the wildcard '_'.

func (*IPAddress) ToSegmentedBinaryString 

func (addr *IPAddress) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this IP address segment series as segments of binary values preceded by the "0b" prefix.

func (*IPAddress) ToSequentialRange 

func (addr *IPAddress) ToSequentialRange() *SequentialRange[*IPAddress]

ToSequentialRange creates a sequential range instance from the lowest and highest addresses in this subnet.

The two will represent the same set of individual addresses if and only if IsSequential is true. To get a series of ranges that represent the same set of individual addresses use the SequentialBlockIterator (or PrefixIterator), and apply this method to each iterated subnet.

If this represents just a single address then the returned instance covers just that single address as well.

func (*IPAddress) ToSinglePrefixBlockOrAddress added in v1.1.0 

func (addr *IPAddress) ToSinglePrefixBlockOrAddress() *IPAddress

ToSinglePrefixBlockOrAddress converts to a single prefix block or address. If the given address is a single prefix block, it is returned. If it can be converted to a single prefix block by assigning a prefix length, the converted block is returned. If it is a single address, any prefix length is removed and the address is returned. Otherwise, nil is returned. This method provides the address formats used by tries. ToSinglePrefixBlockOrAddress is quite similar to AssignPrefixForSingleBlock, which always returns prefixed addresses, while this does not.

func (*IPAddress) ToSubnetString 

func (addr *IPAddress) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like "1.2.*.*" or "1:2::/16".

In the case of IPv4, this means that wildcards are used instead of a network prefix when a network prefix has been supplied. In the case of IPv6, when a network prefix has been supplied, the prefix will be shown and the host section will be compressed with "::".

func (*IPAddress) ToUNCHostName added in v1.3.0 

func (addr *IPAddress) ToUNCHostName() string

ToUNCHostName Generates the Microsoft UNC path component for this address. See https://ipv6-literal.com/

For IPv4 it is the canonical string. For IPv6, it is the canonical string but with colons replaced by dashes, percent signs with the letter “s”, and then appended with the root domain ".ipv6-literal.net".

func (*IPAddress) ToZeroHost 

func (addr *IPAddress) ToZeroHost() (*IPAddress, addrerr.IncompatibleAddressError)

ToZeroHost converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix and prefix length.

For instance, the zero host of "1.2.3.4/16" is the individual address "1.2.0.0/16".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPAddress) ToZeroHostLen 

func (addr *IPAddress) ToZeroHostLen(prefixLength BitCount) (*IPAddress, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.

For instance, the zero host of "1.2.3.4" for the prefix length of 16 is the address "1.2.0.0".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPAddress) ToZeroNetwork 

func (addr *IPAddress) ToZeroNetwork() *IPAddress

ToZeroNetwork converts the address or subnet to one in which all individual addresses have a network of zero, the network being the bits within the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix length.

func (*IPAddress) TrieCompare added in v1.1.0 

func (addr *IPAddress) TrieCompare(other *IPAddress) (int, addrerr.IncompatibleAddressError)

TrieCompare compares two addresses according to address trie ordering. It returns a number less than zero, zero, or a number greater than zero if the first address argument is less than, equal to, or greater than the second.

The comparison is intended for individual addresses and CIDR prefix blocks. If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPAddress) TrieDecrement added in v1.1.0 

func (addr *IPAddress) TrieDecrement() *IPAddress

TrieDecrement returns the previous address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPAddress) TrieIncrement added in v1.1.0 

func (addr *IPAddress) TrieIncrement() *IPAddress

TrieIncrement returns the next address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPAddress) UpperBytes 

func (addr *IPAddress) UpperBytes() []byte

UpperBytes returns the highest address in this subnet or address as a byte slice.

func (*IPAddress) WithoutPrefixLen 

func (addr *IPAddress) WithoutPrefixLen() *IPAddress

WithoutPrefixLen provides the same address but with no prefix length. The values remain unchanged.

func (*IPAddress) Wrap 

func (addr *IPAddress) Wrap() WrappedIPAddress

Wrap wraps this IP address, returning a WrappedIPAddress, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address.

func (*IPAddress) WrapAddress added in v1.2.0 

func (addr *IPAddress) WrapAddress() WrappedAddress

WrapAddress wraps this IP address, returning a WrappedAddress, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapAddress can be called with a nil receiver, wrapping a nil address.

type IPAddressConverter 

type IPAddressConverter interface {
	IPv4AddressConverter

	IPv6AddressConverter

	// IsIPv4Convertible returns whether the address is IPv4 or can be converted to IPv4.  If true, ToIPv4 returns non-nil.
	IsIPv4Convertible(address *IPAddress) bool

	// IsIPv6Convertible returns whether the address is IPv6 or can be converted to IPv6.  If true, ToIPv6 returns non-nil.
	IsIPv6Convertible(address *IPAddress) bool
}

IPAddressConverter converts IP addresses to either IPv4 or IPv6.

type IPAddressCreator 

type IPAddressCreator struct {
	IPVersion
}

IPAddressCreator is a polymporphic type providing constructor methods to construct IP addresses corresponding to its contained IP version

func (IPAddressCreator) CreatePrefixSegment 

func (creator IPAddressCreator) CreatePrefixSegment(value SegInt, segmentPrefixLength PrefixLen) *IPAddressSegment

CreatePrefixSegment creates an IPv4 or IPv6 segment with a prefix length depending on the IP version assigned to this IPAddressCreator instance. If the IP version is indeterminate, then nil is returned.

func (IPAddressCreator) CreateRangeSegment 

func (creator IPAddressCreator) CreateRangeSegment(lower, upper SegInt) *IPAddressSegment

CreateRangeSegment creates an IPv4 or IPv6 range-valued segment depending on the IP version assigned to this IPAddressCreator instance. If the IP version is indeterminate, then nil is returned.

func (IPAddressCreator) CreateSegment 

func (creator IPAddressCreator) CreateSegment(lower, upper SegInt, segmentPrefixLength PrefixLen) *IPAddressSegment

CreateSegment creates an IPv4 or IPv6 segment depending on the IP version assigned to this IPAddressCreator instance. If the IP version is indeterminate, then nil is returned.

func (IPAddressCreator) NewIPAddressFromPrefixedVals 

func (creator IPAddressCreator) NewIPAddressFromPrefixedVals(lowerValueProvider, upperValueProvider SegmentValueProvider, prefixLength PrefixLen) *IPAddress

NewIPAddressFromPrefixedVals constructs an IPAddress from the provided segment values and prefix length. If the IP version of this IPAddressCreator is indeterminate, then nil is returned. The prefix length is adjusted to 0 if negative or to the bit count if larger.

func (IPAddressCreator) NewIPAddressFromPrefixedZonedVals 

func (creator IPAddressCreator) NewIPAddressFromPrefixedZonedVals(lowerValueProvider, upperValueProvider SegmentValueProvider, prefixLength PrefixLen, zone string) *IPAddress

NewIPAddressFromPrefixedZonedVals constructs an IPAddress from the provided segment values, prefix length, and zone. If the IP version of this IPAddressCreator is indeterminate, then nil is returned. If the version is IPv4, then the zone is ignored. The prefix length is adjusted to 0 if negative or to the bit count if larger.

func (IPAddressCreator) NewIPAddressFromVals 

func (creator IPAddressCreator) NewIPAddressFromVals(lowerValueProvider SegmentValueProvider) *IPAddress

NewIPAddressFromVals constructs an IPAddress from the provided segment values. If the IP version of this IPAddressCreator is indeterminate, then nil is returned.

func (IPAddressCreator) NewIPSectionFromBytes 

func (creator IPAddressCreator) NewIPSectionFromBytes(bytes []byte) *IPAddressSection

NewIPSectionFromBytes creates an address section from the given bytes, It is IPv4 or IPv6 depending on the IP version assigned to this IPAddressCreator instance. The number of segments is determined by the length of the byte array. If the IP version is indeterminate, then nil is returned.

func (IPAddressCreator) NewIPSectionFromPrefixedBytes 

func (creator IPAddressCreator) NewIPSectionFromPrefixedBytes(bytes []byte, segmentCount int, prefLen PrefixLen) (*IPAddressSection, addrerr.AddressValueError)

NewIPSectionFromPrefixedBytes creates an address section from the given bytes and prefix length. It is IPv4 or IPv6 depending on the IP version assigned to this IPAddressCreator instance. The number of segments is given. An error is returned when the byte slice has too many bytes to match the segment count. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated. If the IP version is indeterminate, then nil is returned.

func (IPAddressCreator) NewIPSectionFromSegmentedBytes added in v1.2.0 

func (creator IPAddressCreator) NewIPSectionFromSegmentedBytes(bytes []byte, segmentCount int) (*IPAddressSection, addrerr.AddressValueError)

NewIPSectionFromSegmentedBytes creates an address section from the given bytes. It is IPv4 or IPv6 depending on the IP version assigned to this IPAddressCreator instance. The number of segments is given. An error is returned when the byte slice has too many bytes to match the segment count. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated. If the IP version is indeterminate, then nil is returned.

type IPAddressKey added in v1.1.1 

type IPAddressKey = Key[*IPAddress]

type IPAddressLargeDivision added in v1.3.0 

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

IPAddressLargeDivision represents an arbitrary division of arbitrary bit-size in an address or address division grouping. It can contain a single value or a range of sequential values and it has an assigned bit length. Like all address components, it is immutable.

func NewIPAddressLargeDivision added in v1.3.0 

func NewIPAddressLargeDivision(val []byte, bitCount BitCount, defaultRadix int) *IPAddressLargeDivision

NewIPAddressLargeDivision creates a division of the given arbitrary bit-length, assigning it the given value. If the value's bit length exceeds the given bit length, it is truncated.

func NewIPAddressLargePrefixDivision added in v1.3.0 

func NewIPAddressLargePrefixDivision(val []byte, prefixLen PrefixLen, bitCount BitCount, defaultRadix int) *IPAddressLargeDivision

NewIPAddressLargePrefixDivision creates a division of the given arbitrary bit-length, assigning it the given value and prefix length. If the value's bit length exceeds the given bit length, it is truncated. If the prefix length exceeds the bit length, it is adjusted to the bit length. If the prefix length is negative, it is adjusted to zero.

func NewIPAddressLargeRangeDivision added in v1.3.0 

func NewIPAddressLargeRangeDivision(val, upperVal []byte, bitCount BitCount, defaultRadix int) *IPAddressLargeDivision

NewIPAddressLargeRangeDivision creates a division of the given arbitrary bit-length, assigning it the given value range. If a value's bit length exceeds the given bit length, it is truncated.

func NewIPAddressLargeRangePrefixDivision added in v1.3.0 

func NewIPAddressLargeRangePrefixDivision(val, upperVal []byte, prefixLen PrefixLen, bitCount BitCount, defaultRadix int) *IPAddressLargeDivision

NewIPAddressLargeRangePrefixDivision creates a division of the given arbitrary bit-length, assigning it the given value range and prefix length. If a value's bit length exceeds the given bit length, it is truncated. If the prefix length exceeds the bit length, it is adjusted to the bit length. If the prefix length is negative, it is adjusted to zero.

func (*IPAddressLargeDivision) Compare added in v1.3.0 

func (div *IPAddressLargeDivision) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address division is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPAddressLargeDivision) CompareSize added in v1.3.0 

func (div *IPAddressLargeDivision) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual values within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one represents more individual values than another.

CompareSize returns a positive integer if this division has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPAddressLargeDivision) ContainsPrefixBlock added in v1.3.0 

func (div *IPAddressLargeDivision) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the division range includes the block of values for the given prefix length.

func (*IPAddressLargeDivision) ContainsSinglePrefixBlock added in v1.3.0 

func (div *IPAddressLargeDivision) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the division range matches exactly the block of values for the given prefix length and has just a single prefix for that prefix length.

func (IPAddressLargeDivision) Format added in v1.3.0 

func (div IPAddressLargeDivision) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*IPAddressLargeDivision) GetCount added in v1.3.0 

func (div *IPAddressLargeDivision) GetCount() *big.Int

GetCount returns the count of possible distinct values for this division. If not representing multiple values, the count is 1.

For instance, a division with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPAddressLargeDivision) GetDivisionPrefixLen added in v1.3.0 

func (div *IPAddressLargeDivision) GetDivisionPrefixLen() PrefixLen

GetDivisionPrefixLen returns the network prefix for the division.

The network prefix is 16 for an address like "1.2.0.0/16".

When it comes to each address division or segment, the prefix for the division is the prefix obtained when applying the address or section prefix.

For instance, consider the address "1.2.0.0/20". The first segment has no prefix because the address prefix 20 extends beyond the 8 bits in the first segment, it does not even apply to the segment. The second segment has no prefix because the address prefix extends beyond bits 9 to 16 which lie in the second segment, it does not apply to that segment either. The third segment has the prefix 4 because the address prefix 20 corresponds to the first 4 bits in the 3rd segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment has the prefix 0 because not a single bit is in the network section of the address or segment

The division prefixes applied across the address are: nil ... nil (1 to segment bit length) 0 ... 0.

If the division has no prefix then nil is returned.

func (*IPAddressLargeDivision) GetMinPrefixLenForBlock added in v1.3.0 

func (div *IPAddressLargeDivision) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this division includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this division represents a single value, this returns the bit count.

func (*IPAddressLargeDivision) GetPrefixLen added in v1.3.0 

func (div *IPAddressLargeDivision) GetPrefixLen() PrefixLen

GetPrefixLen returns the network prefix for the division.

The network prefix is 16 for an address like "1.2.0.0/16".

When it comes to each address division or segment, the prefix for the division is the prefix obtained when applying the address or section prefix.

For instance, consider the address "1.2.0.0/20". The first segment has no prefix because the address prefix 20 extends beyond the 8 bits in the first segment, it does not even apply to the segment. The second segment has no prefix because the address prefix extends beyond bits 9 to 16 which lie in the second segment, it does not apply to that segment either. The third segment has the prefix 4 because the address prefix 20 corresponds to the first 4 bits in the 3rd segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment has the prefix 0 because not a single bit is in the network section of the address or segment

The division prefixes applied across the address are: nil ... nil (1 to segment bit length) 0 ... 0.

If the segment has no prefix then nil is returned.

func (*IPAddressLargeDivision) GetPrefixLenForSingleBlock added in v1.3.0 

func (div *IPAddressLargeDivision) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this division, and the range of values in this division matches the block of all values for that prefix.

If the range of division values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this division represents a single value, this returns the bit count of the segment.

func (*IPAddressLargeDivision) GetString added in v1.3.0 

func (div *IPAddressLargeDivision) GetString() string

GetString produces a normalized string to represent the segment. If the segment is an IP segment string with CIDR network prefix block for its prefix length, then the string contains only the lower value of the block range. Otherwise, the explicit range will be printed. If the segment is not an IP segment, then the string is the same as that produced by GetWildcardString.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPAddressLargeDivision) GetUpperValue added in v1.3.0 

func (div *IPAddressLargeDivision) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address division range as a big integer.

func (*IPAddressLargeDivision) GetValue added in v1.3.0 

func (div *IPAddressLargeDivision) GetValue() *BigDivInt

GetValue returns the lowest value in the address division range as a big integer.

func (*IPAddressLargeDivision) GetWildcardString added in v1.3.0 

func (div *IPAddressLargeDivision) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters regardless of any network prefix length. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPAddressLargeDivision) IsMultiple added in v1.3.0 

func (div *IPAddressLargeDivision) IsMultiple() bool

IsMultiple returns whether this division represents a sequential range of values, vs a single value

func (*IPAddressLargeDivision) IsPrefixBlock added in v1.3.0 

func (div *IPAddressLargeDivision) IsPrefixBlock() bool

IsPrefixBlock returns whether the division has a prefix length and the division range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

func (*IPAddressLargeDivision) IsPrefixed added in v1.3.0 

func (div *IPAddressLargeDivision) IsPrefixed() bool

IsPrefixed returns whether this division has an associated prefix length. If so, the prefix length is given by GetDivisionPrefixLen()

func (*IPAddressLargeDivision) IsSinglePrefix added in v1.3.0 

func (div *IPAddressLargeDivision) IsSinglePrefix(divisionPrefixLen BitCount) bool

IsSinglePrefix returns true if the division value range spans just a single prefix value for the given prefix length.

func (*IPAddressLargeDivision) IsSinglePrefixBlock added in v1.3.0 

func (div *IPAddressLargeDivision) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the division range matches the block of values for its prefix length

func (*IPAddressLargeDivision) String added in v1.3.0 

func (div *IPAddressLargeDivision) String() string

String produces a string that is useful when a division string is provided with no context. It uses a string prefix for octal or hex ("0" or "0x"), and does not use the wildcard '*', because division size is variable, so '*' is ambiguous. GetWildcardString is more appropriate in context with other segments or divisions. It does not use a string prefix and uses '*' for full-range segments. GetString is more appropriate in context with prefix lengths, it uses zeros instead of wildcards for prefix block ranges.

type IPAddressLargeDivisionGrouping added in v1.3.0 

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

func NewIPAddressLargeDivGrouping added in v1.3.0 

func NewIPAddressLargeDivGrouping(divs []*IPAddressLargeDivision) *IPAddressLargeDivisionGrouping

NewIPAddressLargeDivGrouping creates an arbitrary grouping of divisions of arbitrary size, each division can have an arbitrarily large bit-length. To create address sections or addresses, use the constructors that are specific to the address version or type. The IPAddressLargeDivision instances can be created with the NewLargeIPDivision, NewLargeIPRangeDivision, NewLargeIPPrefixDivision, NewLargeIPRangePrefixDivision functions.

func (*IPAddressLargeDivisionGrouping) Bytes added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) Bytes() []byte

Bytes returns the lowest individual division grouping in this grouping as a byte slice.

func (*IPAddressLargeDivisionGrouping) Compare added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address division grouping is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPAddressLargeDivisionGrouping) CompareSize added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual values within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one represents more individual values than another.

CompareSize returns a positive integer if this division has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPAddressLargeDivisionGrouping) ContainsPrefixBlock added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPAddressLargeDivisionGrouping) ContainsSinglePrefixBlock added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this grouping contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPAddressLargeDivisionGrouping) CopyBytes added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest division grouping in the range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

You can use GetByteCount to determine the required array length for the bytes.

func (*IPAddressLargeDivisionGrouping) CopyDivisions added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) CopyDivisions(divs []*IPAddressLargeDivision) (count int)

CopyDivisions copies the existing divisions from the given start index until but not including the division at the given end index, into the given slice, as much as can be fit into the slice, returning the number of divisions copied.

func (*IPAddressLargeDivisionGrouping) CopySubDivisions added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) CopySubDivisions(start, end int, divs []*IPAddressLargeDivision) (count int)

CopySubDivisions copies the existing divisions from the given start index until but not including the division at the given end index, into the given slice, as much as can be fit into the slice, returning the number of divisions copied.

func (*IPAddressLargeDivisionGrouping) CopyUpperBytes added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest division grouping in the range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

You can use GetByteCount to determine the required array length for the bytes.

func (*IPAddressLargeDivisionGrouping) ForEachDivision added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) ForEachDivision(consumer func(divisionIndex int, division *IPAddressLargeDivision) (stop bool)) int

ForEachDivision visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. ForEachDivision returns the number of visited segments.

func (IPAddressLargeDivisionGrouping) Format added in v1.5.4 

func (grouping IPAddressLargeDivisionGrouping) Format(state fmt.State, verb rune)

divisions are printed like slices of *IPAddressLargeDivision (which are Stringers) with division separated by spaces and enclosed in square brackets, sections are printed like addresses with segments separated by segment separators

func (*IPAddressLargeDivisionGrouping) GetCount added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) GetCount() *big.Int

GetCount returns the count of possible distinct values for this division grouping. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPAddressLargeDivisionGrouping) GetDivision added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) GetDivision(index int) *IPAddressLargeDivision

GetDivision returns the division at the given index.

func (*IPAddressLargeDivisionGrouping) GetMinPrefixLenForBlock added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this grouping includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this grouping represents a single value, this returns the bit count.

func (*IPAddressLargeDivisionGrouping) GetPrefixLenForSingleBlock added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this division grouping matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this division grouping represents a single value, returns the bit length.

func (*IPAddressLargeDivisionGrouping) GetUpperValue added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address division grouping in this address division grouping as an integer value.

func (*IPAddressLargeDivisionGrouping) GetValue added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) GetValue() *big.Int

GetValue returns the lowest individual address division grouping in this address division grouping as an integer value.

func (*IPAddressLargeDivisionGrouping) IsMultiple added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) IsMultiple() bool

IsMultiple returns whether this grouping represents multiple values rather than a single value.

func (*IPAddressLargeDivisionGrouping) IsPrefixBlock added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) IsPrefixBlock() bool

IsPrefixBlock returns whether this division grouping has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*IPAddressLargeDivisionGrouping) IsPrefixed added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) IsPrefixed() bool

IsPrefixed returns whether this division grouping has an associated prefix length. If so, the prefix length is given by GetPrefixLen.

func (*IPAddressLargeDivisionGrouping) IsSinglePrefixBlock added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range of values matches a single subnet block for the prefix length.

What distinguishes this method with ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPAddressLargeDivisionGrouping) String added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) String() string

String implements the fmt.Stringer interface. It returns "<nil>" if the receiver is a nil pointer. Otherwise, the string is printed like a slice, with each division converted to a string by its own String method (like "[ div0 div1 ... ]").

func (*IPAddressLargeDivisionGrouping) UpperBytes added in v1.3.0 

func (grouping *IPAddressLargeDivisionGrouping) UpperBytes() []byte

UpperBytes returns the highest individual division grouping in this grouping as a byte slice.

type IPAddressNetwork 

type IPAddressNetwork interface {
	GetLoopback() *IPAddress

	GetNetworkMask(prefixLength BitCount) *IPAddress

	GetPrefixedNetworkMask(prefixLength BitCount) *IPAddress

	GetHostMask(prefixLength BitCount) *IPAddress

	GetPrefixedHostMask(prefixLength BitCount) *IPAddress
	// contains filtered or unexported methods
}

IPAddressNetwork represents a network of addresses of a single IP version providing a collection of standard address components for that version, such as masks and loopbacks.

type IPAddressRange 

type IPAddressRange interface {
	// GetIPVersion returns the IP version of this IP address range
	GetIPVersion() IPVersion

	// GetLowerIPAddress returns the address in the subnet or address range with the lowest numeric value,
	// which will be the receiver if it represents a single address.
	// For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned.
	GetLowerIPAddress() *IPAddress

	// GetUpperIPAddress returns the address in the subnet or address range with the highest numeric value,
	// which will be the receiver if it represents a single address.
	// For example, for the subnet "1.2-3.4.5-6", the address "1.3.4.6" is returned.
	GetUpperIPAddress() *IPAddress

	// CopyNetIP copies the value of the lowest individual address in the subnet or address range into a net.IP.
	//
	// If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned.
	// Otherwise, a new slice is created and returned with the value.
	CopyNetIP(bytes net.IP) net.IP

	// CopyUpperNetIP copies the value of the highest individual address in the subnet or address range into a net.IP.
	//
	// If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned.
	// Otherwise, a new slice is created and returned with the value.
	CopyUpperNetIP(bytes net.IP) net.IP

	// GetNetIP returns the lowest address in this subnet or address range as a net.IP.
	GetNetIP() net.IP

	// GetUpperNetIP returns the highest address in this subnet or address range as a net.IP.
	GetUpperNetIP() net.IP

	// GetNetNetIPAddr returns the lowest address in this subnet or address range as a netip.Addr.
	GetNetNetIPAddr() netip.Addr

	// GetUpperNetNetIPAddr returns the highest address in this subnet or address range as a netip.Addr.
	GetUpperNetNetIPAddr() netip.Addr

	// IsSequential returns whether the address item represents a range of addresses that are sequential.
	//
	// IP Address sequential ranges are sequential by definition.
	//
	// Generally, for a subnet this means that any segment covering a range of values must be followed by segments that are full range, covering all values.
	//
	// Individual addresses are sequential and CIDR prefix blocks are sequential.
	// The subnet "1.2.3-4.5" is not sequential, since the two addresses it represents, "1.2.3.5" and "1.2.4.5", are not ("1.2.3.6" is in-between the two but not in the subnet).
	IsSequential() bool
}

IPAddressRange represents all IPAddress instances and all IPAddress sequential range instances.

type IPAddressSection 

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

An IPAddressSection is an address section of an IP address, containing a certain number of consecutive segments of an IP address.

It is a series of individual address segments. Each segment has equal bit-length. Each address is backed by an address section that contains all the segments of the address.

IPAddressSection objects are immutable. This also makes them concurrency-safe.

Most operations that can be performed on IPAddress instances can also be performed on IPAddressSection instances and vice-versa.

func (*IPAddressSection) AdjustPrefixLen 

func (section *IPAddressSection) AdjustPrefixLen(prefixLen BitCount) *IPAddressSection

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*IPAddressSection) AdjustPrefixLenZeroed 

func (section *IPAddressSection) AdjustPrefixLenZeroed(prefixLen BitCount) (*IPAddressSection, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPAddressSection) AssignMinPrefixForBlock 

func (section *IPAddressSection) AssignMinPrefixForBlock() *IPAddressSection

AssignMinPrefixForBlock returns an equivalent address section, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this address section.

In other words, this method assigns a prefix length to this address section matching the largest prefix block in this address section.

func (*IPAddressSection) AssignPrefixForSingleBlock 

func (section *IPAddressSection) AssignPrefixForSingleBlock() *IPAddressSection

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address section. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address section - it is required that the range of values match the range of a prefix block. If there is no such address section, then nil is returned.

func (*IPAddressSection) BlockIterator 

func (section *IPAddressSection) BlockIterator(segmentCount int) Iterator[*IPAddressSection]

BlockIterator Iterates through the address sections that can be obtained by iterating through all the upper segments up to the given segment count. The segments following remain the same in all iterated sections.

func (*IPAddressSection) Bytes 

func (section *IPAddressSection) Bytes() []byte

Bytes returns the lowest individual address section in this address section as a byte slice.

func (*IPAddressSection) Compare 

func (section *IPAddressSection) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address section is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPAddressSection) CompareSize 

func (section *IPAddressSection) CompareSize(other AddressItem) int

CompareSize compares the counts of two address sections or other items, the number of individual items represented.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether this section represents more individual address sections than another item.

CompareSize returns a positive integer if this address section has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPAddressSection) Contains 

func (section *IPAddressSection) Contains(other AddressSectionType) bool

Contains returns whether this is same type and version as the given address section and whether it contains all values in the given section.

Sections must also have the same number of segments to be comparable, otherwise false is returned.

func (*IPAddressSection) ContainsPrefixBlock 

func (section *IPAddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPAddressSection) ContainsSinglePrefixBlock 

func (section *IPAddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this section contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPAddressSection) CopyBytes 

func (section *IPAddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddressSection) CopySegments 

func (section *IPAddressSection) CopySegments(segs []*IPAddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPAddressSection) CopySubSegments 

func (section *IPAddressSection) CopySubSegments(start, end int, segs []*IPAddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPAddressSection) CopyUpperBytes 

func (section *IPAddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddressSection) CoverWithPrefixBlock 

func (section *IPAddressSection) CoverWithPrefixBlock() *IPAddressSection

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the individual address sections in this section. The resulting block will have a larger count than this, unless this section is already a prefix block.

func (*IPAddressSection) Equal 

func (section *IPAddressSection) Equal(other AddressSectionType) bool

Equal returns whether the given address section is equal to this address section. Two address sections are equal if they represent the same set of sections. They must match:

  • type/version: IPv4, IPv6
  • segment counts
  • segment value ranges

Prefix lengths are ignored.

func (*IPAddressSection) ForEachSegment added in v1.2.0 

func (section *IPAddressSection) ForEachSegment(consumer func(segmentIndex int, segment *IPAddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (*IPAddressSection) GetBitCount 

func (section *IPAddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (*IPAddressSection) GetBitsPerSegment 

func (section *IPAddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (*IPAddressSection) GetBlockCount 

func (section *IPAddressSection) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*IPAddressSection) GetBlockMaskPrefixLen 

func (section *IPAddressSection) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address section is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address section with all ones in the network section and then all zeros in the host section. A CIDR host mask is an address section with all zeros in the network section and then all ones in the host section. The prefix length is the bit-length of the network section.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this instance, indicating the network and host section of this address section. The prefix length returned here indicates the whether the value of this address can be used as a mask for the network and host section of any other address. Therefore the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this section represents multiple values.

func (*IPAddressSection) GetByteCount 

func (section *IPAddressSection) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item.

func (*IPAddressSection) GetBytesPerSegment 

func (section *IPAddressSection) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this section. Segments in the same address section are equal length.

func (*IPAddressSection) GetCount 

func (section *IPAddressSection) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPAddressSection) GetGenericSegment 

func (section *IPAddressSection) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPAddressSection) GetHostMask 

func (section *IPAddressSection) GetHostMask() *IPAddressSection

GetHostMask returns the host mask associated with the CIDR network prefix length of this address section. If this section has no prefix length, then the all-ones mask is returned.

func (*IPAddressSection) GetHostSection 

func (section *IPAddressSection) GetHostSection() *IPAddressSection

GetHostSection returns a subsection containing the segments with the host of the address section, the bits beyond the CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

If this series has no prefix length, the returned host section will be the full section.

func (*IPAddressSection) GetHostSectionLen 

func (section *IPAddressSection) GetHostSectionLen(prefLen BitCount) *IPAddressSection

GetHostSectionLen returns a subsection containing the segments with the host of the address section, the bits beyond the given CIDR network prefix length. The returned section will have only as many segments as needed to contain the host. The returned section will have an assigned prefix length indicating the beginning of the host.

func (*IPAddressSection) GetIPVersion 

func (section *IPAddressSection) GetIPVersion() IPVersion

GetIPVersion returns the IP version of this IP address section.

func (*IPAddressSection) GetLower 

func (section *IPAddressSection) GetLower() *IPAddressSection

GetLower returns the section in the range with the lowest numeric value, which will be the same section if it represents a single value. For example, for "1.2-3.4.5-6", the section "1.2.4.5" is returned.

func (*IPAddressSection) GetMaxSegmentValue 

func (section *IPAddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPAddressSection) GetMinPrefixLenForBlock 

func (section *IPAddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (*IPAddressSection) GetNetworkMask 

func (section *IPAddressSection) GetNetworkMask() *IPAddressSection

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address section. If this section has no prefix length, then the all-ones mask is returned.

func (*IPAddressSection) GetNetworkPrefixLen 

func (section *IPAddressSection) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. It is equivalent to GetPrefixLen.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (*IPAddressSection) GetNetworkSection 

func (section *IPAddressSection) GetNetworkSection() *IPAddressSection

GetNetworkSection returns a subsection containing the segments with the network bits of the address section. The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.

If this series has no CIDR prefix length, the returned network section will be the entire series as a prefixed section with prefix length matching the address bit length.

func (*IPAddressSection) GetNetworkSectionLen 

func (section *IPAddressSection) GetNetworkSectionLen(prefLen BitCount) *IPAddressSection

GetNetworkSectionLen returns a subsection containing the segments with the network of the address section, the prefix bits according to the given prefix length. The returned section will have only as many segments as needed to contain the network.

The new section will be assigned the given prefix length, unless the existing prefix length is smaller, in which case the existing prefix length will be retained.

func (*IPAddressSection) GetPrefixCount 

func (section *IPAddressSection) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, it returns the same value as GetCount.

func (*IPAddressSection) GetPrefixCountLen 

func (section *IPAddressSection) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length.

func (*IPAddressSection) GetPrefixLenForSingleBlock 

func (section *IPAddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (*IPAddressSection) GetSegment 

func (section *IPAddressSection) GetSegment(index int) *IPAddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPAddressSection) GetSegmentCount 

func (section *IPAddressSection) GetSegmentCount() int

GetSegmentCount returns the segment/division count.

func (*IPAddressSection) GetSegmentStrings 

func (section *IPAddressSection) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*IPAddressSection) GetSegments 

func (section *IPAddressSection) GetSegments() (res []*IPAddressSegment)

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*IPAddressSection) GetSequentialBlockCount 

func (section *IPAddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section.

func (*IPAddressSection) GetSequentialBlockIndex 

func (section *IPAddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (*IPAddressSection) GetSubSection 

func (section *IPAddressSection) GetSubSection(index, endIndex int) *IPAddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*IPAddressSection) GetTrailingSection 

func (section *IPAddressSection) GetTrailingSection(index int) *IPAddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*IPAddressSection) GetUpper 

func (section *IPAddressSection) GetUpper() *IPAddressSection

GetUpper returns the section in the range with the highest numeric value, which will be the same section if it represents a single value. For example, for "1.2-3.4.5-6", the section "1.3.4.6" is returned.

func (*IPAddressSection) GetUpperValue 

func (section *IPAddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value.

func (*IPAddressSection) GetValue 

func (section *IPAddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value.

func (*IPAddressSection) IncludesMax 

func (section *IPAddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range.

func (*IPAddressSection) IncludesMaxHost 

func (section *IPAddressSection) IncludesMaxHost() bool

IncludesMaxHost returns whether the address section contains an individual address section with a host of all one-bits. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are one.

func (*IPAddressSection) IncludesMaxHostLen 

func (section *IPAddressSection) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the address section contains an individual address section with a host of all one-bits, an address section for which all bits past the given prefix length are all ones.

func (*IPAddressSection) IncludesZero 

func (section *IPAddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range.

func (*IPAddressSection) IncludesZeroHost 

func (section *IPAddressSection) IncludesZeroHost() bool

IncludesZeroHost returns whether the address section contains an individual address section with a host of zero. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are zero.

func (*IPAddressSection) IncludesZeroHostLen 

func (section *IPAddressSection) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the address section contains an individual section with a host of zero, a section for which all bits past the given prefix length are zero.

func (*IPAddressSection) Increment 

func (section *IPAddressSection) Increment(increment int64) *IPAddressSection

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (*IPAddressSection) IncrementBoundary 

func (section *IPAddressSection) IncrementBoundary(increment int64) *IPAddressSection

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (*IPAddressSection) IsAdaptiveZero 

func (section *IPAddressSection) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the division grouping was originally created as an implicitly zero-valued section or grouping (e.g. IPv4AddressSection{}), meaning it was not constructed using a constructor function. Such a grouping, which has no divisions or segments, is convertible to an implicitly zero-valued grouping of any type or version, whether IPv6, IPv4, MAC, or other. In other words, when a section or grouping is the zero-value, then it is equivalent and convertible to the zero value of any other section or grouping type.

func (*IPAddressSection) IsFullRange 

func (section *IPAddressSection) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPAddressSection) IsIPv4 

func (section *IPAddressSection) IsIPv4() bool

IsIPv4 returns true if this address section originated as an IPv4 section. If so, use ToIPv4 to convert back to the IPv4-specific type.

func (*IPAddressSection) IsIPv6 

func (section *IPAddressSection) IsIPv6() bool

IsIPv6 returns true if this address section originated as an IPv6 section. If so, use ToIPv6 to convert back to the IPv6-specific type.

func (*IPAddressSection) IsMax 

func (section *IPAddressSection) IsMax() bool

IsMax returns whether this section matches exactly the maximum possible value, the value whose bits are all ones.

func (*IPAddressSection) IsMaxHost 

func (section *IPAddressSection) IsMaxHost() bool

IsMaxHost returns whether this section has a prefix length and if so, whether the host is all all one-bits, the max value, for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsMaxHost returns true.

func (*IPAddressSection) IsMaxHostLen 

func (section *IPAddressSection) IsMaxHostLen(prefLen BitCount) bool

IsMaxHostLen returns whether the host host is all one-bits, the max value, for all individual sections in this address section, for the given prefix length, the host being the bits following the prefix.

If the host section is zero length (there are zero host bits), IsMaxHostLen returns true.

func (*IPAddressSection) IsMultiple 

func (section *IPAddressSection) IsMultiple() bool

IsMultiple returns whether this section represents multiple values.

func (*IPAddressSection) IsOneBit 

func (section *IPAddressSection) IsOneBit(prefixBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*IPAddressSection) IsPrefixBlock 

func (section *IPAddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*IPAddressSection) IsPrefixed 

func (section *IPAddressSection) IsPrefixed() bool

IsPrefixed returns whether this section has an associated prefix length.

func (*IPAddressSection) IsSequential 

func (section *IPAddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (*IPAddressSection) IsSingleNetwork 

func (section *IPAddressSection) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address section.

func (*IPAddressSection) IsSinglePrefixBlock 

func (section *IPAddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPAddressSection) IsZero 

func (section *IPAddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero.

func (*IPAddressSection) IsZeroHost 

func (section *IPAddressSection) IsZeroHost() bool

IsZeroHost returns whether this section has a prefix length and if so, whether the host section is always zero for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (*IPAddressSection) IsZeroHostLen 

func (section *IPAddressSection) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual sections in this address section, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (*IPAddressSection) Iterator 

func (section *IPAddressSection) Iterator() Iterator[*IPAddressSection]

Iterator provides an iterator to iterate through the individual address sections of this address section.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address sections.

Call IsMultiple to determine if this instance represents multiple address sections, or GetCount for the count.

func (*IPAddressSection) PrefixBlockIterator 

func (section *IPAddressSection) PrefixBlockIterator() Iterator[*IPAddressSection]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address section. Each iterated address section will be a prefix block with the same prefix length as this address section.

If this address section has no prefix length, then this is equivalent to Iterator.

func (*IPAddressSection) PrefixContains 

func (section *IPAddressSection) PrefixContains(other AddressSectionType) bool

PrefixContains returns whether the prefix values in the given address section are prefix values in this address section, using the prefix length of this section. If this address section has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

All prefix bits of this section must be present in the other section to be comparable.

func (*IPAddressSection) PrefixEqual 

func (section *IPAddressSection) PrefixEqual(other AddressSectionType) bool

PrefixEqual determines if the given section matches this section up to the prefix length of this section. It returns whether the argument section has the same address section prefix values as this.

All prefix bits of this section must be present in the other section to be comparable, otherwise false is returned.

func (*IPAddressSection) PrefixIterator 

func (section *IPAddressSection) PrefixIterator() Iterator[*IPAddressSection]

PrefixIterator provides an iterator to iterate through the individual prefixes of this address section, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this address section.

If the series has no prefix length, then this is equivalent to Iterator.

func (*IPAddressSection) ReverseBits 

func (section *IPAddressSection) ReverseBits(perByte bool) (*IPAddressSection, addrerr.IncompatibleAddressError)

ReverseBits returns a new section with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPAddressSection) ReverseBytes 

func (section *IPAddressSection) ReverseBytes() (*IPAddressSection, addrerr.IncompatibleAddressError)

ReverseBytes returns a new section with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (*IPAddressSection) ReverseSegments 

func (section *IPAddressSection) ReverseSegments() *IPAddressSection

ReverseSegments returns a new section with the segments reversed.

func (*IPAddressSection) SequentialBlockIterator 

func (section *IPAddressSection) SequentialBlockIterator() Iterator[*IPAddressSection]

SequentialBlockIterator iterates through the sequential address sections that make up this address section.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPAddressSection) SetPrefixLen 

func (section *IPAddressSection) SetPrefixLen(prefixLen BitCount) *IPAddressSection

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPAddressSection) SetPrefixLenZeroed 

func (section *IPAddressSection) SetPrefixLenZeroed(prefixLen BitCount) (*IPAddressSection, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

If this address section has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address section has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPAddressSection) SpanWithPrefixBlocks 

func (section *IPAddressSection) SpanWithPrefixBlocks() []*IPAddressSection

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual address sections as this section.

Unlike SpanWithPrefixBlocksTo, the result only includes blocks that are a part of this section.

func (*IPAddressSection) SpanWithSequentialBlocks 

func (section *IPAddressSection) SpanWithSequentialBlocks() []*IPAddressSection

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of sections as this.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

func (*IPAddressSection) String 

func (section *IPAddressSection) String() string

String implements the fmt.Stringer interface, returning the normalized string provided by ToNormalizedString, or "<nil>" if the receiver is a nil pointer.

func (*IPAddressSection) TestBit 

func (section *IPAddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPAddressSection) ToBinaryString 

func (section *IPAddressSection) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address section as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPAddressSection) ToBlock 

func (section *IPAddressSection) ToBlock(segmentIndex int, lower, upper SegInt) *IPAddressSection

ToBlock creates a new block of address sections by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPAddressSection) ToCanonicalString 

func (section *IPAddressSection) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address section.

For IPv4, dotted octet format, also known as dotted decimal format, is used. https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

With IP addresses, the prefix length is included in the string.

func (*IPAddressSection) ToCanonicalWildcardString 

func (section *IPAddressSection) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string but avoids the CIDR prefix length. Address sections with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. IPv6 sections will be compressed according to the canonical representation. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPAddressSection) ToCompressedString 

func (section *IPAddressSection) ToCompressedString() string

ToCompressedString produces a short representation of this address section while remaining within the confines of standard representation(s) of the address.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.

func (*IPAddressSection) ToCompressedWildcardString 

func (section *IPAddressSection) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, avoiding the CIDR prefix, but with full IPv6 segment compression as well, including single zero-segments. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPAddressSection) ToCustomString 

func (section *IPAddressSection) ToCustomString(stringOptions addrstr.IPStringOptions) string

ToCustomString creates a customized string from this address section according to the given string option parameters.

func (*IPAddressSection) ToDivGrouping 

func (section *IPAddressSection) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToIP.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSection) ToFullString 

func (section *IPAddressSection) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 4 characters for IPv6 segments and 3 characters for IPv4 segments.

func (*IPAddressSection) ToHexString 

func (section *IPAddressSection) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address section as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPAddressSection) ToIPv4 

func (section *IPAddressSection) ToIPv4() *IPv4AddressSection

ToIPv4 converts to an IPv4AddressSection if this section originated as an IPv4 section. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSection) ToIPv6 

func (section *IPAddressSection) ToIPv6() *IPv6AddressSection

ToIPv6 converts to an IPv6AddressSection if this section originated as an IPv6 section. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSection) ToMaxHost 

func (section *IPAddressSection) ToMaxHost() (res *IPAddressSection, err addrerr.IncompatibleAddressError)

ToMaxHost converts the address section to one in which all individual address sections have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-ones section, the max address section.

The returned address section will have the same prefix and prefix length.

This returns an error if the address section is a range of address sections which cannot be converted to a range in which all sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPAddressSection) ToMaxHostLen 

func (section *IPAddressSection) ToMaxHostLen(prefixLength BitCount) (*IPAddressSection, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address section to one in which all individual address sections have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this section has the same prefix length, then the resulting section will too, otherwise the resulting section will have no prefix length.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all address sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPAddressSection) ToNormalizedString 

func (section *IPAddressSection) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address section.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. Zero-segments are not compressed.

With IP addresses, the prefix length is included in the string.

func (*IPAddressSection) ToNormalizedWildcardString 

func (section *IPAddressSection) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPAddressSection) ToOctalString 

func (section *IPAddressSection) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address section as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPAddressSection) ToPrefixBlock 

func (section *IPAddressSection) ToPrefixBlock() *IPAddressSection

ToPrefixBlock returns the section with the same prefix as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

If this section has no prefix, this section is returned.

func (*IPAddressSection) ToPrefixBlockLen 

func (section *IPAddressSection) ToPrefixBlockLen(prefLen BitCount) *IPAddressSection

ToPrefixBlockLen returns the section with the same prefix of the given length as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

func (*IPAddressSection) ToPrefixLenString 

func (section *IPAddressSection) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, a zero host section will be compressed with "::". For IPv4 the string is equivalent to the canonical string.

func (*IPAddressSection) ToReverseDNSString 

func (section *IPAddressSection) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse-DNS lookup string, returning an error if this address section is an IPv6 multiple-valued section for which the range cannot be represented. For "8.255.4.4" it is "4.4.255.8.in-addr.arpa". For "2001:db8::567:89ab" it is "b.a.9.8.7.6.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa".

func (*IPAddressSection) ToSQLWildcardString 

func (section *IPAddressSection) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the wildcard '_'.

func (*IPAddressSection) ToSectionBase 

func (section *IPAddressSection) ToSectionBase() *AddressSection

ToSectionBase converts to an AddressSection, a polymorphic type usable with all address sections. Afterwards, you can convert back with ToIP.

ToSectionBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSection) ToSegmentedBinaryString 

func (section *IPAddressSection) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this IP address section as segments of binary values preceded by the "0b" prefix.

func (*IPAddressSection) ToSubnetString 

func (section *IPAddressSection) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like "1.2.*.*" or "1:2::/16".

In the case of IPv4, this means that wildcards are used instead of a network prefix when a network prefix has been supplied. In the case of IPv6, when a network prefix has been supplied, the prefix will be shown and the host section will be compressed with "::".

func (*IPAddressSection) ToZeroHost 

func (section *IPAddressSection) ToZeroHost() (res *IPAddressSection, err addrerr.IncompatibleAddressError)

ToZeroHost converts the address section to one in which all individual address sections have a host of zero, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned section will have the same prefix and prefix length.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPAddressSection) ToZeroHostLen 

func (section *IPAddressSection) ToZeroHostLen(prefixLength BitCount) (*IPAddressSection, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address section to one in which all individual sections have a host of zero, the host being the bits following the given prefix length. If this address section has the same prefix length, then the returned one will too, otherwise the returned section will have no prefix length.

This returns an error if the section is a range of which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPAddressSection) ToZeroNetwork 

func (section *IPAddressSection) ToZeroNetwork() *IPAddressSection

ToZeroNetwork converts the address section to one in which all individual address sections have a network of zero, the network being the bits within the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned address section will have the same prefix length.

func (*IPAddressSection) UpperBytes 

func (section *IPAddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice.

func (*IPAddressSection) WithoutPrefixLen 

func (section *IPAddressSection) WithoutPrefixLen() *IPAddressSection

WithoutPrefixLen provides the same address section but with no prefix length. The values remain unchanged.

func (*IPAddressSection) Wrap 

func (section *IPAddressSection) Wrap() WrappedIPAddressSection

Wrap wraps this IP address section, returning a WrappedIPAddressSection, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address section.

func (*IPAddressSection) WrapSection added in v1.2.0 

func (section *IPAddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapSection can be called with a nil receiver, wrapping a nil address section.

type IPAddressSegment 

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

IPAddressSegment represents a single segment of an IP address. An IP segment contains a single value or a range of sequential values, a prefix length, and it has an assigned bit length.

For IPv4, segments are 1 byte. For IPv6, they are two bytes.

IPAddressSegment objects are immutable and thus also concurrency-safe.

See AddressSegment for more details regarding segments.

func (*IPAddressSegment) Bytes 

func (seg *IPAddressSegment) Bytes() []byte

Bytes returns the lowest value in the address segment range as a byte slice.

func (*IPAddressSegment) Compare 

func (seg *IPAddressSegment) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address segment is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPAddressSegment) CompareSize added in v1.3.0 

func (seg *IPAddressSegment) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual values within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether this represents more individual values than another.

CompareSize returns a positive integer if this segment has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPAddressSegment) Contains 

func (seg *IPAddressSegment) Contains(other AddressSegmentType) bool

Contains returns whether this is same type and version as the given segment and whether it contains all values in the given segment.

func (*IPAddressSegment) ContainsPrefixBlock 

func (seg *IPAddressSegment) ContainsPrefixBlock(divisionPrefixLen BitCount) bool

ContainsPrefixBlock returns whether the division range includes the block of values for the given prefix length.

func (*IPAddressSegment) ContainsSinglePrefixBlock 

func (seg *IPAddressSegment) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the segment range matches exactly the block of values for the given prefix length and has just a single prefix for that prefix length.

func (*IPAddressSegment) CopyBytes 

func (seg *IPAddressSegment) CopyBytes(bytes []byte) []byte

CopyBytes copies the lowest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddressSegment) CopyUpperBytes 

func (seg *IPAddressSegment) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the highest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddressSegment) Equal 

func (seg *IPAddressSegment) Equal(other AddressSegmentType) bool

Equal returns whether the given segment is equal to this segment. Two segments are equal if they match:

  • type/version IPv4, IPv6
  • value range

Prefix lengths are ignored.

func (*IPAddressSegment) GetBitCount 

func (seg *IPAddressSegment) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (*IPAddressSegment) GetBlockMaskPrefixLen 

func (seg *IPAddressSegment) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address segment is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is a segment with all ones in the network bits and then all zeros in the host bits. A CIDR host mask is a segment with all zeros in the network bits and then all ones in the host bits. The prefix length is the bit-length of the network bits.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this segment. The prefix length returned here indicates the whether the value of this segment can be used as a mask for the network and host bits of any other segment. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPAddressSegment) GetByteCount 

func (seg *IPAddressSegment) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item.

func (*IPAddressSegment) GetCount 

func (seg *IPAddressSegment) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1.

For instance, a segment with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPAddressSegment) GetLower 

func (seg *IPAddressSegment) GetLower() *IPAddressSegment

GetLower returns a segment representing just the lowest value in the range, which will be the same segment if it represents a single value.

func (*IPAddressSegment) GetMaxValue 

func (seg *IPAddressSegment) GetMaxValue() SegInt

GetMaxValue gets the maximum possible value for this type or version of segment, determined by the number of bits.

For the highest range value of this particular segment, use GetUpperSegmentValue.

func (*IPAddressSegment) GetMinPrefixLenForBlock 

func (seg *IPAddressSegment) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this segment includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this segment represents a single value, this returns the bit count.

func (*IPAddressSegment) GetPrefixCountLen 

func (seg *IPAddressSegment) GetPrefixCountLen(segmentPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct prefix values for the given prefix length in the range of values of this segment.

func (*IPAddressSegment) GetPrefixLenForSingleBlock 

func (seg *IPAddressSegment) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this segment, and the range of values in this segment matches the block of all values for that prefix.

If the range of segment values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this segment represents a single value, this returns the bit count of the segment.

func (*IPAddressSegment) GetPrefixValueCount 

func (seg *IPAddressSegment) GetPrefixValueCount() SegIntCount

GetPrefixValueCount returns the count of prefixes in this segment for its prefix length, or the total count if it has no prefix length.

func (*IPAddressSegment) GetPrefixValueCountLen 

func (seg *IPAddressSegment) GetPrefixValueCountLen(segmentPrefixLength BitCount) SegIntCount

GetPrefixValueCountLen returns the same value as GetPrefixCountLen as an integer.

func (*IPAddressSegment) GetSegmentPrefixLen 

func (seg *IPAddressSegment) GetSegmentPrefixLen() PrefixLen

GetSegmentPrefixLen returns the network prefix for the segment.

The network prefix is 16 for an address like "1.2.0.0/16".

When it comes to each address division or segment, the prefix for the division is the prefix obtained when applying the address or section prefix.

For instance, consider the address "1.2.0.0/20". The first segment has no prefix because the address prefix 20 extends beyond the 8 bits in the first segment, it does not even apply to the segment. The second segment has no prefix because the address prefix extends beyond bits 9 to 16 which lie in the second segment, it does not apply to that segment either. The third segment has the prefix 4 because the address prefix 20 corresponds to the first 4 bits in the 3rd segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment has the prefix 0 because not a single bit is in the network section of the address or segment

The division prefixes applied across the address are: nil ... nil (1 to segment bit length) 0 ... 0.

If the segment has no prefix then nil is returned.

func (*IPAddressSegment) GetSegmentValue 

func (seg *IPAddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the segment value range.

func (*IPAddressSegment) GetString 

func (seg *IPAddressSegment) GetString() string

GetString produces a normalized string to represent the segment. If the segment is a CIDR network prefix block for its prefix length, then the string contains only the lower value of the block range. Otherwise, the explicit range will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPAddressSegment) GetUpper 

func (seg *IPAddressSegment) GetUpper() *IPAddressSegment

GetUpper returns a segment representing just the highest value in the range, which will be the same segment if it represents a single value.

func (*IPAddressSegment) GetUpperSegmentValue 

func (seg *IPAddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the segment value range.

func (*IPAddressSegment) GetUpperValue 

func (seg *IPAddressSegment) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address segment range as a big integer.

func (*IPAddressSegment) GetValue 

func (seg *IPAddressSegment) GetValue() *BigDivInt

GetValue returns the lowest value in the address segment range as a big integer.

func (*IPAddressSegment) GetValueCount 

func (seg *IPAddressSegment) GetValueCount() SegIntCount

GetValueCount returns the same value as GetCount as an integer.

func (*IPAddressSegment) GetWildcardString 

func (seg *IPAddressSegment) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters while ignoring any network prefix length. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPAddressSegment) IncludesMax 

func (seg *IPAddressSegment) IncludesMax() bool

IncludesMax returns whether this segment includes the max value, the value whose bits are all ones, within its range.

func (*IPAddressSegment) IncludesZero 

func (seg *IPAddressSegment) IncludesZero() bool

IncludesZero returns whether this segment includes the value of zero within its range.

func (*IPAddressSegment) IsFullRange 

func (seg *IPAddressSegment) IsFullRange() bool

IsFullRange returns whether the segment range includes all possible values for its bit length.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPAddressSegment) IsIPv4 

func (seg *IPAddressSegment) IsIPv4() bool

IsIPv4 returns true if this segment originated as an IPv4 segment. If so, use ToIPv4 to convert back to the IPv4-specific type.

func (*IPAddressSegment) IsIPv6 

func (seg *IPAddressSegment) IsIPv6() bool

IsIPv6 returns true if this segment originated as an IPv6 segment. If so, use ToIPv6 to convert back to the IPv6-specific type.

func (*IPAddressSegment) IsMax 

func (seg *IPAddressSegment) IsMax() bool

IsMax returns whether this segment matches exactly the maximum possible value, the value whose bits are all ones.

func (*IPAddressSegment) IsMultiple 

func (seg *IPAddressSegment) IsMultiple() bool

IsMultiple returns whether this segment represents multiple values.

func (*IPAddressSegment) IsOneBit 

func (seg *IPAddressSegment) IsOneBit(segmentBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*IPAddressSegment) IsPrefixBlock 

func (seg *IPAddressSegment) IsPrefixBlock() bool

IsPrefixBlock returns whether the segment has a prefix length and the segment range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

func (*IPAddressSegment) IsPrefixed 

func (seg *IPAddressSegment) IsPrefixed() bool

IsPrefixed returns whether this section has an associated prefix length.

func (*IPAddressSegment) IsSinglePrefix 

func (seg *IPAddressSegment) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix determines if the segment has a single prefix value for the given prefix length. You can call GetPrefixCountLen to get the count of prefixes.

func (*IPAddressSegment) IsSinglePrefixBlock 

func (seg *IPAddressSegment) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPAddressSegment) IsZero 

func (seg *IPAddressSegment) IsZero() bool

IsZero returns whether this segment matches exactly the value of zero.

func (*IPAddressSegment) Iterator 

func (seg *IPAddressSegment) Iterator() Iterator[*IPAddressSegment]

Iterator provides an iterator to iterate through the individual address segments of this address segment.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address segments.

Call IsMultiple to determine if this instance represents multiple address segments, or GetValueCount for the count.

func (*IPAddressSegment) Matches 

func (seg *IPAddressSegment) Matches(value SegInt) bool

Matches returns true if the segment range matches the given single value.

func (*IPAddressSegment) MatchesValsWithMask 

func (seg *IPAddressSegment) MatchesValsWithMask(lowerValue, upperValue, mask SegInt) bool

MatchesValsWithMask applies the mask to this segment and then compares the result with the given values, returning true if the range of the resulting segment matches the given range.

func (*IPAddressSegment) MatchesWithMask 

func (seg *IPAddressSegment) MatchesWithMask(value, mask SegInt) bool

MatchesWithMask applies the mask to this segment and then compares the result with the given value, returning true if the range of the resulting segment matches that single value.

func (*IPAddressSegment) MatchesWithPrefixMask 

func (seg *IPAddressSegment) MatchesWithPrefixMask(value SegInt, networkBits BitCount) bool

MatchesWithPrefixMask applies the network mask of the given bit-length to this segment and then compares the result with the given value masked by the same mask, returning true if the resulting range matches the given single value.

func (*IPAddressSegment) PrefixBlockIterator 

func (seg *IPAddressSegment) PrefixBlockIterator() Iterator[*IPAddressSegment]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address segment. Each iterated address segment will be a prefix block with the same prefix length as this address segment.

If this address segment has no prefix length, then this is equivalent to Iterator.

func (*IPAddressSegment) PrefixContains 

func (seg *IPAddressSegment) PrefixContains(other AddressSegmentType, prefixLength BitCount) bool

PrefixContains returns whether the prefix values in the prefix of the given segment are also prefix values in this segment. It returns whether the prefix of this segment contains the prefix of the given segment.

func (*IPAddressSegment) PrefixEqual 

func (seg *IPAddressSegment) PrefixEqual(other AddressSegmentType, prefixLength BitCount) bool

PrefixEqual returns whether the prefix bits of this segment match the same bits of the given segment. It returns whether the two segments share the same range of prefix values using the given prefix length.

func (*IPAddressSegment) PrefixIterator 

func (seg *IPAddressSegment) PrefixIterator() Iterator[*IPAddressSegment]

PrefixIterator provides an iterator to iterate through the individual prefixes of this segment, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this segment.

If this address segment has no prefix length, then this is equivalent to Iterator.

func (*IPAddressSegment) PrefixedBlockIterator 

func (seg *IPAddressSegment) PrefixedBlockIterator(segmentPrefixLen BitCount) Iterator[*IPAddressSegment]

PrefixedBlockIterator provides an iterator to iterate through the individual prefix blocks of the given prefix length in this segment, one for each prefix of this address or subnet.

It is similar to PrefixBlockIterator except that this method allows you to specify the prefix length.

func (*IPAddressSegment) ReverseBits 

func (seg *IPAddressSegment) ReverseBits(perByte bool) (res *AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBits returns a segment with the bits reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPAddressSegment) ReverseBytes 

func (seg *IPAddressSegment) ReverseBytes() (res *AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBytes returns a segment with the bytes reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

func (*IPAddressSegment) String 

func (seg *IPAddressSegment) String() string

String produces a string that is useful when a segment string is provided with no context. If the segment was originally constructed as an IPv4 address segment it uses decimal, otherwise hexadecimal. It uses a string prefix for hex ("0x"), and does not use the wildcard '*', because division size is variable, so '*' is ambiguous. GetWildcardString is more appropriate in context with other segments or divisions. It does not use a string prefix and uses '*' for full-range segments. GetString is more appropriate in context with prefix lengths, it uses zeros instead of wildcards with full prefix block ranges alongside prefix lengths.

func (*IPAddressSegment) TestBit 

func (seg *IPAddressSegment) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPAddressSegment) ToDiv 

func (seg *IPAddressSegment) ToDiv() *AddressDivision

ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions. Afterwards, you can convert back with ToIP.

ToDiv can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSegment) ToHexString 

func (seg *IPAddressSegment) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address segment as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

For segments, the error is always nil.

func (*IPAddressSegment) ToHostSegment 

func (seg *IPAddressSegment) ToHostSegment(segmentPrefixLength PrefixLen) *IPAddressSegment

ToHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will have no assigned prefix length.

func (*IPAddressSegment) ToIPv4 

func (seg *IPAddressSegment) ToIPv4() *IPv4AddressSegment

ToIPv4 converts to an IPv4AddressSegment if this segment originated as an IPv4 segment. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSegment) ToIPv6 

func (seg *IPAddressSegment) ToIPv6() *IPv6AddressSegment

ToIPv6 converts to an IPv6AddressSegment if this segment originated as an IPv6 segment. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSegment) ToNetworkSegment 

func (seg *IPAddressSegment) ToNetworkSegment(segmentPrefixLength PrefixLen) *IPAddressSegment

ToNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will have no assigned prefix length.

func (*IPAddressSegment) ToNormalizedString 

func (seg *IPAddressSegment) ToNormalizedString() string

ToNormalizedString produces a string that is consistent for all address segments of the same type and version. IPv4 segments use base 10, while IPv6 segments use base 16.

func (*IPAddressSegment) ToPrefixedHostSegment 

func (seg *IPAddressSegment) ToPrefixedHostSegment(segmentPrefixLength PrefixLen) *IPAddressSegment

ToPrefixedHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPAddressSegment) ToPrefixedNetworkSegment 

func (seg *IPAddressSegment) ToPrefixedNetworkSegment(segmentPrefixLength PrefixLen) *IPAddressSegment

ToPrefixedNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPAddressSegment) ToSegmentBase 

func (seg *IPAddressSegment) ToSegmentBase() *AddressSegment

ToSegmentBase converts to an AddressSegment, a polymorphic type usable with all address segments. Afterwards, you can convert back with ToIP.

ToSegmentBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSegment) UpperBytes 

func (seg *IPAddressSegment) UpperBytes() []byte

UpperBytes returns the highest value in the address segment range as a byte slice.

func (*IPAddressSegment) WithoutPrefixLen 

func (seg *IPAddressSegment) WithoutPrefixLen() *IPAddressSegment

WithoutPrefixLen returns a segment with the same value range but without a prefix length.

type IPAddressSegmentSeries 

type IPAddressSegmentSeries interface {
	AddressSegmentSeries

	// IncludesZeroHost returns whether the series contains an individual series with a host of zero.  If the series has no prefix length it returns false.
	// If the prefix length matches the bit count, then it returns true.
	//
	// Otherwise, it checks whether it contains an individual series for which all bits past the prefix are zero.
	IncludesZeroHost() bool

	// IncludesZeroHostLen returns whether the series contains an individual series with a host of zero, a series for which all bits past the given prefix length are zero.
	IncludesZeroHostLen(prefLen BitCount) bool

	// IncludesMaxHost returns whether the series contains an individual series with a host of all one-bits.  If the series has no prefix length it returns false.
	// If the prefix length matches the bit count, then it returns true.
	//
	// Otherwise, it checks whether it contains an individual series for which all bits past the prefix are one.
	IncludesMaxHost() bool

	// IncludesMaxHostLen returns whether the series contains an individual series with a host of all one-bits, a series for which all bits past the given prefix length are all ones.
	IncludesMaxHostLen(prefLen BitCount) bool

	// IsZeroHost returns whether this series has a prefix length and if so,
	// whether the host section is always zero for all individual series in this subnet or address section.
	//
	// If the host section is zero length (there are zero host bits), IsZeroHost returns true.
	IsZeroHost() bool

	// IsZeroHostLen returns whether the host section is always zero for all individual series in this address or address section,
	// for the given prefix length.
	//
	// If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.
	IsZeroHostLen(BitCount) bool

	// IsMaxHost returns whether this address or address section has a prefix length and if so,
	// whether the host section is always all one-bits, the max value, for all individual series in this address or address section,
	//the host being the bits following the prefix.
	//
	// If the host section is zero length (there are zero host bits), IsMaxHost returns true.
	IsMaxHost() bool

	// IsMaxHostLen returns whether the host is all one-bits, the max value, for all individual series in this address or address section,
	// for the given prefix length, the host being the bits following the prefix.
	//
	// If the host is zero length (there are zero host bits), IsMaxHostLen returns true.
	IsMaxHostLen(BitCount) bool

	// IsSingleNetwork returns whether the network section of the IP address series, the prefix, consists of a single value.
	//
	// If it has no prefix length, it returns true if not multiple, if it contains only a single individual series.
	IsSingleNetwork() bool

	// GetIPVersion returns the IP version of this IP address or IP address section.
	GetIPVersion() IPVersion

	// GetBlockMaskPrefixLen returns the prefix length if this IP address or IP address section is equivalent to the mask for a CIDR prefix block.
	// Otherwise, it returns nil.
	// A CIDR network mask is a series with all ones in the network section and then all zeros in the host section.
	// A CIDR host mask is a series with all zeros in the network section and then all ones in the host section.
	// The prefix length is the bit-length of the network section.
	//
	// Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this instance,
	// indicating the network and host section of this series.
	// The prefix length returned here indicates the whether the value of this series can be used as a mask for the network and host
	// section of any other series.  Therefore, the two values can be different values, or one can be nil while the other is not.
	//
	// This method applies only to the lower value of the range if this series represents multiple values.
	GetBlockMaskPrefixLen(network bool) PrefixLen

	// GetLeadingBitCount returns the number of consecutive leading one or zero-bits.
	// If ones is true, returns the number of consecutive leading one-bits.
	// Otherwise, returns the number of consecutive leading zero bits.
	//
	// This method applies to the lower value of the range if this series represents multiple values.
	GetLeadingBitCount(ones bool) BitCount

	// GetTrailingBitCount returns the number of consecutive trailing one or zero-bits.
	// If ones is true, returns the number of consecutive trailing zero bits.
	// Otherwise, returns the number of consecutive trailing one-bits.
	//
	// This method applies to the lower value of the range if this series represents multiple values.
	GetTrailingBitCount(ones bool) BitCount

	// ToFullString produces a string with no compressed segments and all segments of full length with leading zeros.
	ToFullString() string

	// ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length.
	// For IPv6, a zero host section will be compressed with "::". For IPv4 the string is equivalent to the canonical string.
	ToPrefixLenString() string

	// ToSubnetString produces a string with specific formats for subnets.
	// The subnet string looks like "1.2.*.*" or "1:2::/16".
	//
	// In the case of IPv4, this means that wildcards are used instead of a network prefix when a network prefix has been supplied.
	// In the case of IPv6, when a network prefix has been supplied, the prefix will be shown and the host section will be compressed with "::".
	ToSubnetString() string

	// ToCanonicalWildcardString produces a string similar to the canonical string but avoids the CIDR prefix length.
	// Series with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation.
	// IPv6 series will be compressed according to the canonical representation.
	ToCanonicalWildcardString() string

	// ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, avoiding the CIDR prefix, but with full IPv6 segment compression as well, including single zero-segments.
	// For IPv4 it is the same as ToNormalizedWildcardString.
	ToCompressedWildcardString() string

	// ToSegmentedBinaryString writes this IP address segment series as segments of binary values preceded by the "0b" prefix.
	ToSegmentedBinaryString() string

	// ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that
	// it uses SQL wildcards.  It uses '%' instead of '*' and also uses the wildcard '_'.
	ToSQLWildcardString() string

	// ToReverseDNSString generates the reverse-DNS lookup string,
	// returning an error if this address series is an IPv6 multiple-valued section for which the range cannot be represented.
	// For "8.255.4.4" it is "4.4.255.8.in-addr.arpa".
	// For "2001:db8::567:89ab" it is "b.a.9.8.7.6.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa".
	ToReverseDNSString() (string, addrerr.IncompatibleAddressError)
}

IPAddressSegmentSeries serves as a common interface to all IP address sections and IP addresses.

type IPAddressSeqRange 

type IPAddressSeqRange = SequentialRange[*IPAddress]

type IPAddressSeqRangeKey added in v1.1.0 

type IPAddressSeqRangeKey = SequentialRangeKey[*IPAddress]

type IPAddressSeqRangeType 

type IPAddressSeqRangeType interface {
	AddressItem

	IPAddressRange

	// ContainsRange returns whether all the addresses in the given sequential range are also contained in this sequential range.
	ContainsRange(IPAddressSeqRangeType) bool

	// Contains returns whether this range contains all IP addresses in the given address or subnet.
	Contains(IPAddressType) bool

	// Equal returns whether the given sequential address range is equal to this sequential address range.
	// Two sequential address ranges are equal if their lower and upper range boundaries are equal.
	Equal(IPAddressSeqRangeType) bool

	// ToCanonicalString produces a canonical string for the address range.
	// It has the format "lower -> upper" where lower and upper are the canonical strings for the lowest and highest addresses in the range, given by GetLower and GetUpper.
	ToCanonicalString() string

	// ToNormalizedString produces a normalized string for the address range.
	// It has the format "lower -> upper" where lower and upper are the normalized strings for the lowest and highest addresses in the range, given by GetLower and GetUpper.
	ToNormalizedString() string

	// ToIP converts to an IPAddressSeqRange, a polymorphic type usable with all IP address sequential ranges.
	//
	// ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToIP() *SequentialRange[*IPAddress]
}

IPAddressSeqRangeType represents any IP address sequential range, all of which can be represented by the base type IPAddressSeqRange. This includes IPv4AddressSeqRange and IPv6AddressSeqRange.

type IPAddressString 

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

IPAddressString parses the string representation of an IP address. Such a string can represent just a single address like "1.2.3.4" or "1:2:3:4:6:7:8", or a subnet like "1.2.0.0/16" or "1.*.1-3.1-4" or "1111:222::/64".

This supports a wide range of address string formats. It supports subnet formats, provides specific error messages, and allows more specific configuration.

You can control all the supported formats using an IPAddressStringParamsBuilder to build a parameters instance of IPAddressStringParams. When no IPAddressStringParams is supplied, a default instance of IPAddressStringParams is used that is generally permissive.

Supported Formats

Both IPv4 and IPv6 are supported.

Subnets are supported:

  • wildcards '*' and ranges '-' (for example "1.*.2-3.4"), useful for working with subnets
  • the wildcard '*' can span multiple segments, so you can represent all addresses with '*', all IPv4 with '*.*', or all IPv6 with '*:*'
  • SQL wildcards '%' and '_', although '%' is considered an SQL wildcard only when it is not considered an IPv6 zone indicator
  • CIDR network prefix length addresses, like "1.2.0.0/16", which is equivalent to "1.2.*.*" (all-zero hosts are the full subnet, non-zero hosts are single addresses)
  • address/mask pairs, in which the mask is applied to the address, like "1.2.3.4/255.255.0.0", which is also equivalent to "1.2.*.*"

You can combine these variations, such as "1.*.2-3.4/255.255.255.0".

IPv6 is fully supported:

  • IPv6 addresses like "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
  • IPv6 zones or scope identifiers, like "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%zone"
  • IPv6 mixed addresses are supported, which are addresses for which the last two IPv6 segments are represented as IPv4, like "ffff:ffff:ffff:ffff:ffff:ffff:255.255.255.255"
  • IPv6 compressed addresses like "::1"
  • A single value of 32 hex digits like "00aa00bb00cc00dd00ee00ff00aa00bb" with or without a preceding hex delimiter "0x"
  • A base 85 address comprising 20 base 85 digits like "4)+k&amp;C#VzJ4br&gt;0wv%Yp" as in RFC 1924 https://tools.ietf.org/html/rfc1924
  • Binary, preceded by "0b", either with binary segments that comprise all 16 bits like "::0b0000111100001111" or a single segment address of "0b" followed by 128 binary bits.

All of the above subnet variations work for IPv6, whether network prefix lengths, masks, ranges or wildcards. Similarly, all the above subnet variations work for any supported IPv4 format, such as the standard dotted-decimal IPv4 format as well as the inet_aton formats listed below.

This type support all address formats of the C routine inet_pton and the Java method java.net.InetAddress.getByName. This type supports all IPv4 address formats of the C routine inet_aton as follows:

  • IPv4 hex: "0x1.0x2.0x3.0x4" ("0x" prefix)
  • IPv4 octal: "01.02.03.0234". Note this clashes with the same address interpreted as dotted decimal
  • 3-part IPv4: "1.2.3" (which is interpreted as "1.2.0.3" (ie the third part covers the last two)
  • 2-part IPv4: "1.2" (which is interpreted as "1.0.0.2" (ie the 2nd part covers the last 3)
  • 1-part IPv4: "1" (which is interpreted as "0.0.0.1" (ie the number represents all 4 segments, and can be any number of digits less than the 32 digits which would be interpreted as IPv6)
  • hex or octal variants of 1, 2, and 3 part, such as "0xffffffff" (which is interpreted as "255.255.255.255")

Also supported are binary segments of a "0b" followed by binary digits like "0b1.0b1010.2.3", or a single segment address of "0b" followed by all 32 bits.

inet_aton (and this type) allows mixing octal, hex and decimal (e.g. "0xa.11.013.11" which is equivalent to "11.11.11.11"). String variations using prefixes, masks, ranges, and wildcards also work for inet_aton style. The same can be said of binary segments, they can be mixed with all other formats.

Note that there is ambiguity when supporting both inet_aton octal and dotted-decimal leading zeros, like "010.010.010.010" which can be interpreted as octal or decimal, thus it can be either "8.8.8.8" or "10.10.10.10", with the default behaviour using the former interpretation. This behaviour can be controlled by IPAddressStringParamsBuilder.GetIPv4AddressParamsBuilder and IPv4AddressStringParametersBuilder.allowLeadingZeros(boolean)

Some Additional Formats:

  • empty strings are interpreted as the zero-address or the loopback
  • as noted previously, the single wildcard address "*" represents all addresses both ipv4 and ipv6,

although you need to give it some help when converting to IPAddress by specifying the IP version in GetVersionedAddress(IPVersion) or ToVersionedAddress(IPVersion).

If you have an address in which segments have been delimited with commas, such as "1,2.3.4,5.6", you can parse this with ParseDelimitedSegments(string) which gives an iterator of strings. For "1,2.3.4,5.6" you will iterate through "1.3.4.6", "1.3.5.6", "2.3.4.6" and "2.3.5.6". You can count the number of elements in such an iterator with CountDelimitedAddresses(String). Each string can then be used to construct an IPAddressString.

Usage

Once you have constructed an IPAddressString object, you can convert it to an IPAddress object with various methods.

Most address strings can be converted to an IPAddress object using GetAddress or ToAddress. In most cases the IP version is determined by the string itself.

There are a few exceptions, cases in which the version is unknown or ambiguous, for which GetAddress returns nil:

  • strings which do not represent valid addresses (eg "bla")
  • the "all" address "*" which represents all IPv4 and IPv6 addresses. For this string you can provide the IPv4/IPv6 version to GetVersionedAddress to get an address representing either all IPv4 or all IPv6 addresses.
  • empty string "" is interpreted as the zero-address, or optionally the default loopback address. You can provide the IPv4/IPv6 version to GetVersionedAddress to get the version of your choice.

The other exception is a subnet in which the range of values in a segment of the subnet are not sequential, for which ToAddress returns IncompatibleAddressError because there is no single IPAddress value, there would be many. An IPAddress instance requires that all segments can be represented as a range of values.

There are only two unusual circumstances when this can occur:

  • using masks on subnets specified with wildcard or range characters causing non-sequential segments such as the final IPv4 segment of "0.0.0.*" with mask "0.0.0.128", this example translating to the two addresses "0.0.0.0" and "0.0.0.128", so the last IPv4 segment cannot be represented as a sequential range of values.
  • using wildcards or range characters in the IPv4 section of an IPv6 mixed address causing non-sequential segments such as the last IPv6 segment of "::ffff:0.0.*.0", this example translating to the addresses "::ffff:0:100", "::ffff:0:200", "::ffff:0:300", ..., so the last IPv6 segment cannot be represented as a sequential range of values.

These exceptions do not occur with non-subnets (ie individual addresses), nor can they occur with standard CIDR prefix-based subnets.

This type is concurrency-safe. In fact, IPAddressString objects are immutable. An IPAddressString object represents a single IP address representation that cannot be changed after construction. Some derived state is created upon demand and cached, such as the derived IPAddress instances.

This type has a few methods with analogs in IPAddress, such as Contains, GetSequentialRange, PrefixEqual, IsIPv4, and IsIPv6. Such methods are provided to make creating the IPAddress instance unnecessary when no such IPAddress instance is needed for other reasons.

func NewIPAddressString 

func NewIPAddressString(str string) *IPAddressString

NewIPAddressString constructs an IPAddressString.

func NewIPAddressStringParams 

func NewIPAddressStringParams(str string, params addrstrparam.IPAddressStringParams) *IPAddressString

NewIPAddressStringParams constructs an IPAddressString that will parse the given string according to the given parameters.

func (*IPAddressString) AdjustPrefixLen 

func (addrStr *IPAddressString) AdjustPrefixLen(adjustment BitCount) (*IPAddressString, addrerr.IncompatibleAddressError)

AdjustPrefixLen increases or decreases the prefix length by the given increment.

If the address string has prefix length 0 and represents all addresses of the same version, and the prefix length is being decreased, then the address representing all addresses of any version is returned.

When there is an associated address value and the prefix length is increased, the bits moved within the prefix become zero, and if prefix length is extended beyond the segment series boundary, it is removed. When there is an associated address value and the prefix length is decreased, the bits moved outside the prefix become zero.

If the address string represents a prefix block, then the result will also represent a prefix block.

func (*IPAddressString) Compare 

func (addrStr *IPAddressString) Compare(other *IPAddressString) int

Compare compares this address string with another, returning a negative number, zero, or a positive number if this address string is less than, equal to, or greater than the other.

All address strings are comparable. If two address strings are invalid, their strings are compared. Otherwise, address strings are compared according to which type or version of string, and then within each type or version they are compared using the comparison rules for addresses.

func (*IPAddressString) Contains 

func (addrStr *IPAddressString) Contains(other *IPAddressString) bool

Contains returns whether the address or subnet identified by this address string contains the address or subnet identified by the given string. If this address string or the given address string is invalid then Contains returns false.

func (*IPAddressString) Equal 

func (addrStr *IPAddressString) Equal(other *IPAddressString) bool

Equal compares two IP address strings for equality. Two IPAddressString objects are equal if they represent the same set of addresses. Whether one or the other has an associated network prefix length is not considered.

If an IPAddressString is invalid, it is equal to another address only if the other address was constructed from the same string.

func (IPAddressString) Format added in v1.5.4 

func (addrStr IPAddressString) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface. It accepts the verbs hat are applicable to strings, namely the verbs %s, %q, %x and %X.

func (*IPAddressString) GetAddress 

func (addrStr *IPAddressString) GetAddress() *IPAddress

GetAddress returns the IP address if this IPAddressString is a valid string representing an IP address or subnet. Otherwise, it returns nil.

Use ToAddress for an equivalent method that returns an error when the format is invalid.

If you have a prefixed address and you wish to get only the host without the prefix, use GetHostAddress.

func (*IPAddressString) GetHostAddress 

func (addrStr *IPAddressString) GetHostAddress() *IPAddress

GetHostAddress parses the address while ignoring the prefix length or mask. GetHostAddress returns nil for an invalid string. If you wish to receive an error instead, use ToHostAddress.

func (*IPAddressString) GetIPVersion 

func (addrStr *IPAddressString) GetIPVersion() IPVersion

GetIPVersion returns the IP address version if this represents a valid IP address, otherwise it returns nil.

func (*IPAddressString) GetMask 

func (addrStr *IPAddressString) GetMask() *IPAddress

GetMask returns the mask, if any, that was provided with this address string.

func (*IPAddressString) GetNetworkPrefixLen 

func (addrStr *IPAddressString) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the associated network prefix length.

If this address is a valid address with an associated network prefix length then this returns that prefix length, otherwise returns nil. The prefix length may be expressed explicitly with the notation "/xx" where xx is a decimal value, or it may be expressed implicitly as a network mask such as "/255.255.0.0".

func (*IPAddressString) GetSequentialRange 

func (addrStr *IPAddressString) GetSequentialRange() (res *IPAddressSeqRange)

GetSequentialRange returns the range of sequential addresses from the lowest address specified in this address string to the highest.

Since not all IPAddressString instances describe a sequential series of addresses, this does not necessarily match the exact set of addresses specified by the string. For example, "1-2.3.4.1-2" produces the sequential range "1.3.4.1" to "2.3.4.2" that includes the address "1.255.255.2" not specified by the string.

This method can also produce a range for a string for which no IPAddress instance can be created, those cases where IsValid returns true but ToAddress returns addrerr.IncompatibleAddressError and GetAddress returns nil. The range cannot be produced for the other cases where GetAddress returns nil

This is similar to ToSequentialRange except that ToSequentialRange provides a descriptive error when nil is returned.

func (*IPAddressString) GetValidationOptions 

func (addrStr *IPAddressString) GetValidationOptions() addrstrparam.IPAddressStringParams

GetValidationOptions returns the validation options supplied when constructing this address string, or the default options if no options were supplied. It returns nil if no options were used to construct.

func (*IPAddressString) GetVersionedAddress 

func (addrStr *IPAddressString) GetVersionedAddress(version IPVersion) *IPAddress

GetVersionedAddress is similar to ToVersionedAddress, but returns nil rather than an error when the address is invalid or does not match the supplied version.

func (*IPAddressString) IsAllAddresses 

func (addrStr *IPAddressString) IsAllAddresses() bool

IsAllAddresses returns true if the string represents all IP addresses, such as the string "*". You can denote all IPv4 addresses with *.*, or all IPv6 addresses with *:*.

func (*IPAddressString) IsBase85IPv6 added in v1.3.0 

func (addrStr *IPAddressString) IsBase85IPv6() bool

IsBase85IPv6 returns whether this address string represents an IPv6 address, returns whether the string was base 85.

func (*IPAddressString) IsEmpty 

func (addrStr *IPAddressString) IsEmpty() bool

IsEmpty returns true if the address string is empty (zero-length).

func (*IPAddressString) IsIPv4 

func (addrStr *IPAddressString) IsIPv4() bool

IsIPv4 returns true if the address is IPv4.

func (*IPAddressString) IsIPv4Mapped added in v1.3.0 

func (addrStr *IPAddressString) IsIPv4Mapped() bool

IsIPv4Mapped returns true if the address is an IPv4-mapped IPv6 address.

func (*IPAddressString) IsIPv6 

func (addrStr *IPAddressString) IsIPv6() bool

IsIPv6 returns true if the address is IPv6.

func (*IPAddressString) IsLoopback 

func (addrStr *IPAddressString) IsLoopback() bool

IsLoopback returns whether this address string represents a loopback address, such as "::1" or "127.0.0.1".

func (*IPAddressString) IsMixedIPv6 

func (addrStr *IPAddressString) IsMixedIPv6() bool

IsMixedIPv6 returns whether the lower 4 bytes of the address string are represented as IPv4, if this address string represents an IPv6 address.

func (*IPAddressString) IsPrefixed 

func (addrStr *IPAddressString) IsPrefixed() bool

IsPrefixed returns whether this address string has an associated prefix length. If so, the prefix length is given by GetNetworkPrefixLen.

func (*IPAddressString) IsValid 

func (addrStr *IPAddressString) IsValid() bool

IsValid returns whether this is a valid IP address string format. The accepted IP address formats are: an IPv4 address or subnet, an IPv6 address or subnet, the address representing all addresses of both versions, or an empty string. If this method returns false, and you want more details, call Validate and examine the error.

func (*IPAddressString) IsZero 

func (addrStr *IPAddressString) IsZero() bool

IsZero returns whether this string represents an IP address whose value is exactly zero.

func (*IPAddressString) PrefixContains 

func (addrStr *IPAddressString) PrefixContains(other *IPAddressString) bool

PrefixContains is similar to PrefixEqual, but instead returns whether the prefix of this address contains the same of the given address, using the prefix length of this address. It returns whether the argument address string prefix values of that length are also prefix values in this address string.

In other words, determines if the other address is in one of the same prefix subnets using the prefix length of this address.

If an address has no prefix length, the whole address is used as the prefix.

If this address string or the given address string is invalid, it returns false.

func (*IPAddressString) PrefixEqual 

func (addrStr *IPAddressString) PrefixEqual(other *IPAddressString) bool

PrefixEqual is similar to Equal, but instead returns whether the prefix of this address string matches the same of the given address string, using the prefix length of this address string. It returns whether the argument address string has the same address prefix values as this.

In other words, it determines if the other address has the same prefix subnet using the prefix length of this address.

If an address has no prefix length, the whole address is compared.

If this address string or the given address string is invalid, it returns false.

func (*IPAddressString) String 

func (addrStr *IPAddressString) String() string

String implements the fmt.Stringer interface, returning the original string used to create this IPAddressString (altered by strings.TrimSpace), or "<nil>" if the receiver is a nil pointer.

func (*IPAddressString) ToAddress 

func (addrStr *IPAddressString) ToAddress() (*IPAddress, addrerr.AddressError)

ToAddress produces the IPAddress corresponding to this IPAddressString.

If this object does not represent a specific IPAddress or a subnet, nil is returned.

If the string used to construct this object is not a known format (empty string, address, or range of addresses) then this method returns an error.

An equivalent method that does not return the error is GetAddress.

If you have a prefixed address and you wish to get only the host rather than the address with the prefix, use ToHostAddress.

The error can be addrerr.AddressStringError or addrerr.IncompatibleAddressError

func (*IPAddressString) ToHostAddress 

func (addrStr *IPAddressString) ToHostAddress() (*IPAddress, addrerr.AddressError)

ToHostAddress parses the address while ignoring the prefix length or mask. The error can be addrerr.AddressStringError for invalid strings or addrerr.IncompatibleAddressError. GetHostAddress is similar but does not return errors. Standard address formats do not result in errors.

func (*IPAddressString) ToNormalizedString 

func (addrStr *IPAddressString) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. Zero-segments are not compressed.

If the address has a prefix length, it will be included in the string.

If the original string is not a valid address string, the original string is used.

func (*IPAddressString) ToSequentialRange 

func (addrStr *IPAddressString) ToSequentialRange() (*IPAddressSeqRange, addrerr.AddressStringError)

ToSequentialRange returns the range of sequential addresses from the lowest address specified in this address string to the highest.

This is similar to GetSequentialRange except that this method provides a descriptive error when nil is returned. See GetSequentialRange for more details.

func (*IPAddressString) ToVersionedAddress 

func (addrStr *IPAddressString) ToVersionedAddress(version IPVersion) (*IPAddress, addrerr.AddressError)

ToVersionedAddress Produces the IPAddress of the specified address version corresponding to this IPAddressString.

In most cases the string indicates the address version and calling ToAddress() is sufficient, with a few exceptions.

When this object represents only a network prefix length, specifying the address version allows the conversion to take place to the associated mask for that prefix length.

When this object represents all addresses, specifying the address version allows the conversion to take place to the associated representation of all IPv4 or all IPv6 addresses.

When this object represents the empty string and that string is interpreted as a loopback or zero address, then it returns the corresponding address for the given version.

When this object represents an ipv4 or ipv6 address, it returns that address if and only if that address matches the provided version.

If the string used to construct this object is an invalid format, or a format that does not match the provided version, then an error is returned.

func (*IPAddressString) Validate 

func (addrStr *IPAddressString) Validate() addrerr.AddressStringError

Validate validates that this string is a valid IP address, returning nil, and if not, returns an error with a descriptive message indicating why it is not.

func (*IPAddressString) ValidateIPv4 

func (addrStr *IPAddressString) ValidateIPv4() addrerr.AddressStringError

ValidateIPv4 validates that this string is a valid IPv4 address, returning nil, and if not, returns an error with a descriptive message indicating why it is not.

func (*IPAddressString) ValidateIPv6 

func (addrStr *IPAddressString) ValidateIPv6() addrerr.AddressStringError

ValidateIPv6 validates that this string is a valid IPv6 address, returning nil, and if not, returns an error with a descriptive message indicating why it is not.

func (*IPAddressString) ValidateVersion 

func (addrStr *IPAddressString) ValidateVersion(version IPVersion) addrerr.AddressStringError

ValidateVersion validates that this string is a valid IP address of the given version. If it is, it returns nil, otherwise it returns an error with a descriptive message indicating why it is not.

func (*IPAddressString) Wrap 

func (addrStr *IPAddressString) Wrap() ExtendedIdentifierString

Wrap wraps this address string, returning a WrappedIPAddressString as an implementation of ExtendedIdentifierString, which can be used to write code that works with different host identifier types polymorphically, including IPAddressString, MACAddressString, and HostName.

type IPAddressType 

type IPAddressType interface {
	AddressType

	IPAddressRange

	// Wrap wraps this IP address, returning a WrappedIPAddress, an implementation of ExtendedIPSegmentSeries,
	// which can be used to write code that works with both IP addresses and IP address sections.
	Wrap() WrappedIPAddress

	// ToIP converts to an IPAddress, a polymorphic type usable with all IP addresses and subnets.
	//
	// ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToIP() *IPAddress

	// ToAddressString retrieves or generates an IPAddressString instance for this IP address.
	// This may be the IPAddressString this instance was generated from, if it was generated from an IPAddressString.
	//
	// In general, users are intended to create IP address instances from IPAddressString instances,
	// while the reverse direction, calling this method, is generally not encouraged and not useful, except under specific circumstances.
	//
	// Those specific circumstances may include when maintaining a collection of HostIdentifierString or IPAddressString instances.
	ToAddressString() *IPAddressString
}

IPAddressType represents any IP address, all of which can be represented by the base type IPAddress. This includes IPv4Address and IPv6Address. You must use the pointer types *IPAddress, *IPv4Address, and *IPv6Address when implementing IPAddressType.

type IPAddressValueProvider 

type IPAddressValueProvider interface {
	AddressValueProvider

	GetPrefixLen() PrefixLen // return nil if none

	GetIPVersion() IPVersion // should not return IndeterminateVersion

	GetZone() string // return "" or NoZone if none
}

IPAddressValueProvider supplies all the values that incorporate an IPAddress instance.

type IPPrefixBlockAllocator added in v1.4.0 

type IPPrefixBlockAllocator = PrefixBlockAllocator[*IPAddress]

type IPVersion 

type IPVersion int

IPVersion is the version type used by IP address types. 

const (
	// IndeterminateIPVersion represents an unspecified IP address version
	IndeterminateIPVersion IPVersion = 0

	// IPv4 represents Internet Protocol version 4
	IPv4 IPVersion = 4

	// IPv6 represents Internet Protocol version 6
	IPv6 IPVersion = 6
)

func (IPVersion) Equal 

func (version IPVersion) Equal(other IPVersion) bool

Equal returns whether the given version matches this version. Two indeterminate versions always match, even if their associated strings do not.

func (IPVersion) GetBitCount 

func (version IPVersion) GetBitCount() BitCount

GetBitCount returns the number of bits comprising an address of this IP Version.

func (IPVersion) GetBitsPerSegment 

func (version IPVersion) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment for this address version, either 8 or 16 for IPv4 and IPv6 respectively. Segments in the same address are equal length.

func (IPVersion) GetByteCount 

func (version IPVersion) GetByteCount() int

GetByteCount returns the number of bytes comprising an address of this IP Version.

func (IPVersion) GetBytesPerSegment 

func (version IPVersion) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this address or subnet. Segments in the same address are equal length.

func (IPVersion) GetMaxSegmentValue 

func (version IPVersion) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this IP version, determined by the number of bits per segment.

func (IPVersion) GetNetwork added in v1.4.0 

func (version IPVersion) GetNetwork() (network IPAddressNetwork)

func (IPVersion) GetSegmentCount 

func (version IPVersion) GetSegmentCount() int

GetSegmentCount returns the number of segments comprising an address of this IP Version: 4 for IPv4 and 8 for IPv6.

func (IPVersion) IsIPv4 

func (version IPVersion) IsIPv4() bool

IsIPv4 returns true if this represents version 4

func (IPVersion) IsIPv6 

func (version IPVersion) IsIPv6() bool

IsIPv6 returns true if this represents version 6

func (IPVersion) IsIndeterminate 

func (version IPVersion) IsIndeterminate() bool

IsIndeterminate returns true if this represents an unspecified IP address version

func (IPVersion) String 

func (version IPVersion) String() string

String returns "IPv4", "IPv6", or the zero-value "" representing an indeterminate version

type IPv4Address 

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

IPv4Address is an IPv4 address, or a subnet of multiple IPv4 addresses. An IPv4 address is composed of 4 1-byte segments and can optionally have an associated prefix length. Each segment can represent a single value or a range of values. The zero value is "0.0.0.0".

To construct one from a string, use NewIPAddressString, then use the ToAddress or GetAddress method of IPAddressString, and then use ToIPv4 to get an IPv4Address, assuming the string had an IPv4 format.

For other inputs, use one of the multiple constructor functions like NewIPv4Address. You can also use one of the multiple constructors for IPAddress like NewIPAddress and then convert using ToIPv4.

func NewIPv4Address 

func NewIPv4Address(section *IPv4AddressSection) (*IPv4Address, addrerr.AddressValueError)

NewIPv4Address constructs an IPv4 address or subnet from the given address section. If the section does not have 4 segments, an error is returned.

func NewIPv4AddressFromBytes 

func NewIPv4AddressFromBytes(bytes []byte) (addr *IPv4Address, err addrerr.AddressValueError)

NewIPv4AddressFromBytes constructs an IPv4 address from the given byte slice. An error is returned when the byte slice has too many bytes to match the IPv4 segment count of 4. There should be 4 bytes or less, although extra leading zeros are tolerated.

func NewIPv4AddressFromPrefixedBytes 

func NewIPv4AddressFromPrefixedBytes(bytes []byte, prefixLength PrefixLen) (addr *IPv4Address, err addrerr.AddressValueError)

NewIPv4AddressFromPrefixedBytes constructs an IPv4 address or prefix block from the given byte slice and prefix length. An error is returned when the byte slice has too many bytes to match the IPv4 segment count of 4. There should be 4 bytes or less, although extra leading zeros are tolerated. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv4AddressFromPrefixedRange 

func NewIPv4AddressFromPrefixedRange(vals, upperVals IPv4SegmentValueProvider, prefixLength PrefixLen) *IPv4Address

NewIPv4AddressFromPrefixedRange constructs an IPv4 subnet from the given values and prefix length. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv4AddressFromPrefixedSegs 

func NewIPv4AddressFromPrefixedSegs(segments []*IPv4AddressSegment, prefixLength PrefixLen) (*IPv4Address, addrerr.AddressValueError)

NewIPv4AddressFromPrefixedSegs constructs an IPv4 address or subnet from the given segments and prefix length. If the given slice does not have 4 segments, an error is returned. If the address has a zero host for its prefix length, the returned address will be the prefix block.

func NewIPv4AddressFromPrefixedUint32 

func NewIPv4AddressFromPrefixedUint32(val uint32, prefixLength PrefixLen) *IPv4Address

NewIPv4AddressFromPrefixedUint32 constructs an IPv4 address or prefix block from the given value and prefix length. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv4AddressFromPrefixedVals 

func NewIPv4AddressFromPrefixedVals(vals IPv4SegmentValueProvider, prefixLength PrefixLen) *IPv4Address

NewIPv4AddressFromPrefixedVals constructs an IPv4 address or prefix block from the given values and prefix length. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv4AddressFromRange 

func NewIPv4AddressFromRange(vals, upperVals IPv4SegmentValueProvider) *IPv4Address

NewIPv4AddressFromRange constructs an IPv4 subnet from the given values.

func NewIPv4AddressFromSegs 

func NewIPv4AddressFromSegs(segments []*IPv4AddressSegment) (*IPv4Address, addrerr.AddressValueError)

NewIPv4AddressFromSegs constructs an IPv4 address or subnet from the given segments. If the given slice does not have 4 segments, an error is returned.

func NewIPv4AddressFromUint32 

func NewIPv4AddressFromUint32(val uint32) *IPv4Address

NewIPv4AddressFromUint32 constructs an IPv4 address from the given value.

func NewIPv4AddressFromVals 

func NewIPv4AddressFromVals(vals IPv4SegmentValueProvider) *IPv4Address

NewIPv4AddressFromVals constructs an IPv4 address from the given values.

func (*IPv4Address) AdjustPrefixLen 

func (addr *IPv4Address) AdjustPrefixLen(prefixLen BitCount) *IPv4Address

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*IPv4Address) AdjustPrefixLenZeroed 

func (addr *IPv4Address) AdjustPrefixLenZeroed(prefixLen BitCount) (*IPv4Address, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

For example, "1.2.0.0/16" adjusted by -8 becomes "1.0.0.0/8". "1.2.0.0/16" adjusted by 8 becomes "1.2.0.0/24".

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv4Address) AssignMinPrefixForBlock 

func (addr *IPv4Address) AssignMinPrefixForBlock() *IPv4Address

AssignMinPrefixForBlock returns an equivalent subnet, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this subnet.

In other words, this method assigns a prefix length to this subnet matching the largest prefix block in this subnet.

Examples:

  • 1.2.3.4 returns 1.2.3.4/32
  • 1.2.*.* returns 1.2.0.0/16
  • 1.2.*.0/24 returns 1.2.0.0/16
  • 1.2.*.4 returns 1.2.*.4/32
  • 1.2.0-1.* returns 1.2.0.0/23
  • 1.2.1-2.* returns 1.2.1-2.0/24
  • 1.2.252-255.* returns 1.2.252.0/22
  • 1.2.3.4/16 returns 1.2.3.4/32

func (*IPv4Address) AssignPrefixForSingleBlock 

func (addr *IPv4Address) AssignPrefixForSingleBlock() *IPv4Address

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address - it is required that the range of values match the range of a prefix block. If there is no such address, then nil is returned.

Examples:

  • 1.2.3.4 returns 1.2.3.4/32
  • 1.2.*.* returns 1.2.0.0/16
  • 1.2.*.0/24 returns 1.2.0.0/16
  • 1.2.*.4 returns nil
  • 1.2.0-1.* returns 1.2.0.0/23
  • 1.2.1-2.* returns nil
  • 1.2.252-255.* returns 1.2.252.0/22
  • 1.2.3.4/16 returns 1.2.3.4/32

func (*IPv4Address) BitwiseOr 

func (addr *IPv4Address) BitwiseOr(other *IPv4Address) (masked *IPv4Address, err addrerr.IncompatibleAddressError)

BitwiseOr does the bitwise disjunction with this address or subnet, useful when subnetting. It is similar to Mask which does the bitwise conjunction.

The operation is applied to all individual addresses and the result is returned.

If this is a subnet representing multiple addresses, and applying the operation to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned.

func (*IPv4Address) BlockIterator 

func (addr *IPv4Address) BlockIterator(segmentCount int) Iterator[*IPv4Address]

BlockIterator iterates through the addresses that can be obtained by iterating through all the upper segments up to the given segment count. The segments following remain the same in all iterated addresses.

For instance, given the IPv4 subnet "1-2.3-4.5-6.7" and the count argument 2, BlockIterator will iterate through "1.3.5-6.7", "1.4.5-6.7", "2.3.5-6.7" and "2.4.5-6.7".

func (*IPv4Address) Bytes 

func (addr *IPv4Address) Bytes() []byte

Bytes returns the lowest address in this subnet or address as a byte slice.

func (*IPv4Address) Compare 

func (addr *IPv4Address) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address or subnet is less than, equal, or greater than the given item. Any address item is comparable to any other.

func (*IPv4Address) CompareSize 

func (addr *IPv4Address) CompareSize(other AddressItem) int

CompareSize compares the counts of two subnets or addresses or other items, the number of individual addresses or items within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether this subnet represents more individual addresses than another item.

CompareSize returns a positive integer if this address or subnet has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPv4Address) Contains 

func (addr *IPv4Address) Contains(other AddressType) bool

Contains returns whether this is the same type and version as the given address or subnet and whether it contains all addresses in the given address or subnet.

func (*IPv4Address) ContainsPrefixBlock 

func (addr *IPv4Address) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or subnet contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPv4Address) ContainsSinglePrefixBlock 

func (addr *IPv4Address) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPv4Address) CopyBytes 

func (addr *IPv4Address) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address in the subnet into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4Address) CopyNetIP 

func (addr *IPv4Address) CopyNetIP(ip net.IP) net.IP

CopyNetIP copies the value of the lowest individual address in the subnet into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4Address) CopySegments 

func (addr *IPv4Address) CopySegments(segs []*IPv4AddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPv4Address) CopySubSegments 

func (addr *IPv4Address) CopySubSegments(start, end int, segs []*IPv4AddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPv4Address) CopyUpperBytes 

func (addr *IPv4Address) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address in the subnet into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4Address) CopyUpperNetIP 

func (addr *IPv4Address) CopyUpperNetIP(ip net.IP) net.IP

CopyUpperNetIP copies the value of the highest individual address in the subnet into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4Address) CoverWithPrefixBlock 

func (addr *IPv4Address) CoverWithPrefixBlock() *IPv4Address

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the addresses in this subnet. The resulting block will have a larger subnet size than this, unless this subnet is already a prefix block.

func (*IPv4Address) CoverWithPrefixBlockTo 

func (addr *IPv4Address) CoverWithPrefixBlockTo(other *IPv4Address) *IPv4Address

CoverWithPrefixBlockTo returns the minimal-size prefix block that covers all the addresses spanning from this subnet to the given subnet.

func (*IPv4Address) Equal 

func (addr *IPv4Address) Equal(other AddressType) bool

Equal returns whether the given address or subnet is equal to this address or subnet. Two address instances are equal if they represent the same set of addresses.

func (*IPv4Address) ForEachSegment added in v1.2.0 

func (addr *IPv4Address) ForEachSegment(consumer func(segmentIndex int, segment *IPv4AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (IPv4Address) Format 

func (addr IPv4Address) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*IPv4Address) GetBitCount 

func (addr *IPv4Address) GetBitCount() BitCount

GetBitCount returns the number of bits comprising this address, or each address in the range if a subnet, which is 32.

func (*IPv4Address) GetBitsPerSegment 

func (addr *IPv4Address) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this address. Segments in the same address are equal length.

func (*IPv4Address) GetBlockCount 

func (addr *IPv4Address) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*IPv4Address) GetBlockMaskPrefixLen 

func (addr *IPv4Address) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address with all ones in the network section and then all zeros in the host section. A CIDR host mask is an address with all zeros in the network section and then all ones in the host section. The prefix length is the bit-length of the network section.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this instance, indicating the network and host section of this address. The prefix length returned here indicates the whether the value of this address can be used as a mask for the network and host section of any other address. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this address represents multiple values.

func (*IPv4Address) GetByteCount 

func (addr *IPv4Address) GetByteCount() int

GetByteCount returns the number of bytes required for this address, or each address in the range if a subnet, which is 4.

func (*IPv4Address) GetBytesPerSegment 

func (addr *IPv4Address) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this address or subnet. Segments in the same address are equal length.

func (*IPv4Address) GetCount 

func (addr *IPv4Address) GetCount() *big.Int

GetCount returns the count of addresses that this address or subnet represents.

If just a single address, not a subnet of multiple addresses, returns 1.

For instance, the IP address subnet "1.2.0.0/15" has the count of 2 to the power of 17.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv4Address) GetDivisionCount 

func (addr *IPv4Address) GetDivisionCount() int

GetDivisionCount returns the segment count.

func (*IPv4Address) GetGenericDivision 

func (addr *IPv4Address) GetGenericDivision(index int) DivisionType

GetGenericDivision returns the segment at the given index as a DivisionType.

func (*IPv4Address) GetGenericSegment 

func (addr *IPv4Address) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPv4Address) GetHostMask 

func (addr *IPv4Address) GetHostMask() *IPv4Address

GetHostMask returns the host mask associated with the CIDR network prefix length of this address or subnet. If this address or subnet has no prefix length, then the all-ones mask is returned.

func (*IPv4Address) GetHostSection 

func (addr *IPv4Address) GetHostSection() *IPv4AddressSection

GetHostSection returns a section containing the segments with the host of the address or subnet, the bits beyond the CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

If this series has no prefix length, the returned host section will be the full section.

func (*IPv4Address) GetHostSectionLen 

func (addr *IPv4Address) GetHostSectionLen(prefLen BitCount) *IPv4AddressSection

GetHostSectionLen returns a section containing the segments with the host of the address or subnet, the bits beyond the given CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

func (*IPv4Address) GetIPVersion 

func (addr *IPv4Address) GetIPVersion() IPVersion

GetIPVersion returns IPv4, the IP version of this address.

func (*IPv4Address) GetIPv4BlockCount added in v1.2.0 

func (addr *IPv4Address) GetIPv4BlockCount(segmentCount int) uint64

GetIPv4BlockCount returns the count of distinct values in the given number of initial (more significant) segments.

It is similar to GetBlockCount but returns a uint64 instead of a big integer.

func (*IPv4Address) GetIPv4Count added in v1.2.0 

func (addr *IPv4Address) GetIPv4Count() uint64

GetIPv4Count returns the count of possible distinct values for this section. It is the same as GetCount but returns the value as a uint64 instead of a big integer. If not representing multiple values, the count is 1.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv4Address) GetIPv4MappedAddress 

func (addr *IPv4Address) GetIPv4MappedAddress() (*IPv6Address, addrerr.IncompatibleAddressError)

GetIPv4MappedAddress returns the IPv4-mapped IPv6 address corresponding to this IPv4 address. The IPv4-mapped IPv6 address is all zeros in the first 12 bytes, with the last 4 bytes matching the bytes of this IPv4 address. See rfc 5156 for details. If this is a subnet with segment ranges which cannot be converted to two IPv6 segment ranges, than an error is returned.

func (*IPv4Address) GetIPv4PrefixCount added in v1.2.0 

func (addr *IPv4Address) GetIPv4PrefixCount() uint64

GetIPv4PrefixCount returns the number of distinct prefix values in this section. It is the same as GetPrefixCount but returns the value as a uint64 instead of a big integer.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetIPv4Count.

func (*IPv4Address) GetIPv4PrefixCountLen added in v1.2.0 

func (addr *IPv4Address) GetIPv4PrefixCountLen(prefixLength BitCount) uint64

GetIPv4PrefixCountLen gives count available as a uint64 instead of big.Int.

It is the similar to GetPrefixCountLen but returns a uint64, not a *big.Int

func (*IPv4Address) GetIPv6Address 

func (addr *IPv4Address) GetIPv6Address(section *IPv6AddressSection) (*IPv6Address, addrerr.AddressError)

GetIPv6Address creates an IPv6 mixed address using the given ipv6 segments and using this address for the embedded IPv4 segments

func (*IPv4Address) GetLeadingBitCount 

func (addr *IPv4Address) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower value of the range if this is a subnet representing multiple values.

func (*IPv4Address) GetLower 

func (addr *IPv4Address) GetLower() *IPv4Address

GetLower returns the lowest address in the subnet range, which will be the receiver if it represents a single address. For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned.

func (*IPv4Address) GetLowerIPAddress 

func (addr *IPv4Address) GetLowerIPAddress() *IPAddress

GetLowerIPAddress returns the address in the subnet or address collection with the lowest numeric value, which will be the receiver if it represents a single address. For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned. GetLowerIPAddress implements the IPAddressRange interface

func (*IPv4Address) GetMaxSegmentValue 

func (addr *IPv4Address) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPv4Address) GetMinPrefixLenForBlock 

func (addr *IPv4Address) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

func (*IPv4Address) GetNetIP 

func (addr *IPv4Address) GetNetIP() net.IP

GetNetIP returns the lowest address in this subnet or address as a net.IP.

func (*IPv4Address) GetNetIPAddr added in v1.2.0 

func (addr *IPv4Address) GetNetIPAddr() *net.IPAddr

GetNetIPAddr returns the lowest address in this subnet or address as a net.IPAddr.

func (*IPv4Address) GetNetNetIPAddr added in v1.5.0 

func (addr *IPv4Address) GetNetNetIPAddr() netip.Addr

GetNetNetIPAddr returns the lowest address in this subnet or address range as a netip.Addr.

func (*IPv4Address) GetNetwork 

func (addr *IPv4Address) GetNetwork() IPAddressNetwork

GetNetwork returns the singleton IPv4 network instance.

func (*IPv4Address) GetNetworkMask 

func (addr *IPv4Address) GetNetworkMask() *IPv4Address

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address or subnet. If this address or subnet has no prefix length, then the all-ones mask is returned.

func (*IPv4Address) GetNetworkPrefixLen 

func (addr *IPv4Address) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. GetNetworkPrefixLen is equivalent to the method GetPrefixLen.

func (*IPv4Address) GetNetworkSection 

func (addr *IPv4Address) GetNetworkSection() *IPv4AddressSection

GetNetworkSection returns an address section containing the segments with the network of the address or subnet, the prefix bits. The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.

If this series has no CIDR prefix length, the returned network section will be the entire series as a prefixed section with prefix length matching the address bit length.

func (*IPv4Address) GetNetworkSectionLen 

func (addr *IPv4Address) GetNetworkSectionLen(prefLen BitCount) *IPv4AddressSection

GetNetworkSectionLen returns a section containing the segments with the network of the address or subnet, the prefix bits according to the given prefix length. The returned section will have only as many segments as needed to contain the network.

The new section will be assigned the given prefix length, unless the existing prefix length is smaller, in which case the existing prefix length will be retained.

func (*IPv4Address) GetPrefixCount 

func (addr *IPv4Address) GetPrefixCount() *big.Int

GetPrefixCount returns the count of prefixes in this address or subnet.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the count of the range of values in the prefix.

If this has a nil prefix length, returns the same value as GetCount.

func (*IPv4Address) GetPrefixCountLen 

func (addr *IPv4Address) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the count of prefixes in this address or subnet for the given prefix length.

If not a subnet of multiple addresses, or a subnet with just single prefix of the given length, returns 1.

func (*IPv4Address) GetPrefixLen 

func (addr *IPv4Address) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part of the address that comprise the prefix.

A prefix is a part of the address that is not specific to that address but common amongst a group of addresses, such as a CIDR prefix block subnet.

For IP addresses, the prefix is explicitly defined when the address is created. For example, "1.2.0.0/16" has a prefix length of 16, while "1.2.*.*" has no prefix length, even though they both represent the same set of addresses and are considered equal. Prefixes can be considered variable for a given IP address and can depend on routing.

The methods GetMinPrefixLenForBlock and GetPrefixLenForSingleBlock can help you to obtain or define a prefix length if one does not exist already. The method ToPrefixBlockLen allows you to create the subnet consisting of the block of addresses for any given prefix length.

func (*IPv4Address) GetPrefixLenForSingleBlock 

func (addr *IPv4Address) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address subnet matches exactly the block of addresses for that prefix.

If the range can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix exists, returns nil.

If this segment grouping represents a single value, returns the bit length of this address division series.

Examples:

  • 1.2.3.4 returns 32
  • 1.2.3.4/16 returns 32
  • 1.2.*.* returns 16
  • 1.2.*.0/24 returns 16
  • 1.2.0.0/16 returns 16
  • 1.2.*.4 returns nil
  • 1.2.252-255.* returns 22

func (*IPv4Address) GetSection 

func (addr *IPv4Address) GetSection() *IPv4AddressSection

GetSection returns the backing section for this address or subnet, comprising all segments.

func (*IPv4Address) GetSegment 

func (addr *IPv4Address) GetSegment(index int) *IPv4AddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPv4Address) GetSegmentCount 

func (addr *IPv4Address) GetSegmentCount() int

GetSegmentCount returns the segment count, the number of segments in this address, which is 4.

func (*IPv4Address) GetSegmentStrings 

func (addr *IPv4Address) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*IPv4Address) GetSegments 

func (addr *IPv4Address) GetSegments() []*IPv4AddressSegment

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this address.

func (*IPv4Address) GetSequentialBlockCount 

func (addr *IPv4Address) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential subnets that comprise this subnet.

func (*IPv4Address) GetSequentialBlockIndex 

func (addr *IPv4Address) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full subnet to be sequential, the preceding segments must be single-valued.

func (*IPv4Address) GetSubSection 

func (addr *IPv4Address) GetSubSection(index, endIndex int) *IPv4AddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*IPv4Address) GetTrailingBitCount 

func (addr *IPv4Address) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies to the lower value of the range if this is a subnet representing multiple values.

func (*IPv4Address) GetTrailingSection 

func (addr *IPv4Address) GetTrailingSection(index int) *IPv4AddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*IPv4Address) GetUpper 

func (addr *IPv4Address) GetUpper() *IPv4Address

GetUpper returns the highest address in the subnet range, which will be the receiver if it represents a single address. For example, for "1.2-3.4.5-6", the address "1.3.4.6" is returned.

func (*IPv4Address) GetUpperIPAddress 

func (addr *IPv4Address) GetUpperIPAddress() *IPAddress

GetUpperIPAddress returns the address in the subnet or address collection with the highest numeric value, which will be the receiver if it represents a single address. For example, for the subnet "1.2-3.4.5-6", the address "1.3.4.6" is returned. GetUpperIPAddress implements the IPAddressRange interface

func (*IPv4Address) GetUpperNetIP 

func (addr *IPv4Address) GetUpperNetIP() net.IP

GetUpperNetIP returns the highest address in this subnet or address as a net.IP.

func (*IPv4Address) GetUpperNetIPAddr added in v1.2.0 

func (addr *IPv4Address) GetUpperNetIPAddr() *net.IPAddr

GetUpperNetIPAddr returns the highest address in this subnet or address as a net.IPAddr.

func (*IPv4Address) GetUpperNetNetIPAddr added in v1.5.0 

func (addr *IPv4Address) GetUpperNetNetIPAddr() netip.Addr

GetUpperNetNetIPAddr returns the highest address in this subnet or address range as a netip.Addr.

func (*IPv4Address) GetUpperValue 

func (addr *IPv4Address) GetUpperValue() *big.Int

GetUpperValue returns the highest address in this subnet or address as an integer value.

func (*IPv4Address) GetValue 

func (addr *IPv4Address) GetValue() *big.Int

GetValue returns the lowest address in this subnet or address as an integer value.

func (*IPv4Address) IncludesMax 

func (addr *IPv4Address) IncludesMax() bool

IncludesMax returns whether this address includes the max address, the address whose bits are all ones, within its range.

func (*IPv4Address) IncludesMaxHost 

func (addr *IPv4Address) IncludesMaxHost() bool

IncludesMaxHost returns whether the subnet contains an individual address with a host of all one-bits. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are one.

func (*IPv4Address) IncludesMaxHostLen 

func (addr *IPv4Address) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the subnet contains an individual address with a host of all one-bits, an individual address for which all bits past the given prefix length are all ones.

func (*IPv4Address) IncludesZeroHost 

func (addr *IPv4Address) IncludesZeroHost() bool

IncludesZeroHost returns whether the subnet contains an individual address with a host of zero. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are zero.

func (*IPv4Address) IncludesZeroHostLen 

func (addr *IPv4Address) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the subnet contains an individual address with a host of zero, an individual address for which all bits past the given prefix length are zero.

func (*IPv4Address) Increment 

func (addr *IPv4Address) Increment(increment int64) *IPv4Address

Increment returns the address from the subnet that is the given increment upwards into the subnet range, with the increment of 0 returning the first address in the range.

If the increment i matches or exceeds the subnet size count c, then i - c + 1 is added to the upper address of the range. An increment matching the subnet count gives you the address just above the highest address in the subnet.

If the increment is negative, it is added to the lower address of the range. To get the address just below the lowest address of the subnet, use the increment -1.

If this is just a single address value, the address is simply incremented by the given increment, positive or negative.

If this is a subnet with multiple values, a positive increment i is equivalent i + 1 values from the subnet iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the subnet count is equivalent to the same number of iterator values preceding the upper bound of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On address overflow or underflow, Increment returns nil.

func (*IPv4Address) IncrementBoundary 

func (addr *IPv4Address) IncrementBoundary(increment int64) *IPv4Address

IncrementBoundary returns the address that is the given increment from the range boundaries of this subnet.

If the given increment is positive, adds the value to the upper address (GetUpper) in the subnet range to produce a new address. If the given increment is negative, adds the value to the lower address (GetLower) in the subnet range to produce a new address. If the increment is zero, returns this address.

If this is a single address value, that address is simply incremented by the given increment value, positive or negative.

On address overflow or underflow, IncrementBoundary returns nil.

func (*IPv4Address) Intersect 

func (addr *IPv4Address) Intersect(other *IPv4Address) *IPv4Address

Intersect returns the subnet whose addresses are found in both this and the given subnet argument, or nil if no such addresses exist.

This is also known as the conjunction of the two sets of addresses.

func (*IPv4Address) IsAnyLocal 

func (addr *IPv4Address) IsAnyLocal() bool

IsAnyLocal returns whether this address is the address which binds to any address on the local host. This is the address that has the value of 0, aka the unspecified address.

func (*IPv4Address) IsFullRange added in v1.2.0 

func (addr *IPv4Address) IsFullRange() bool

IsFullRange returns whether this address covers the entire IPv4 address space.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv4Address) IsLinkLocal 

func (addr *IPv4Address) IsLinkLocal() bool

IsLinkLocal returns whether the address is link local, whether unicast or multicast.

func (*IPv4Address) IsLocal 

func (addr *IPv4Address) IsLocal() bool

IsLocal returns true if the address is link local, site local, organization local, administered locally, or unspecified. This includes both unicast and multicast.

func (*IPv4Address) IsLoopback 

func (addr *IPv4Address) IsLoopback() bool

IsLoopback returns whether this address is a loopback address, such as "127.0.0.1".

func (*IPv4Address) IsMax 

func (addr *IPv4Address) IsMax() bool

IsMax returns whether this address matches exactly the maximum possible value, the address whose bits are all ones.

func (*IPv4Address) IsMaxHost 

func (addr *IPv4Address) IsMaxHost() bool

IsMaxHost returns whether this section has a prefix length and if so, whether the host section is always all one-bits, the max value, for all individual addresses in this subnet.

If the host section is zero length (there are zero host bits), IsMaxHost returns true.

func (*IPv4Address) IsMaxHostLen 

func (addr *IPv4Address) IsMaxHostLen(prefLen BitCount) bool

IsMaxHostLen returns whether the host is all one-bits, the max value, for all individual addresses in this subnet, for the given prefix length, the host being the bits following the prefix.

If the host section is zero length (there are zero host bits), IsMaxHostLen returns true.

func (*IPv4Address) IsMulticast 

func (addr *IPv4Address) IsMulticast() bool

IsMulticast returns whether this address or subnet is entirely multicast.

func (*IPv4Address) IsMultiple 

func (addr *IPv4Address) IsMultiple() bool

IsMultiple returns true if this represents more than a single individual address, whether it is a subnet of multiple addresses.

func (*IPv4Address) IsOneBit 

func (addr *IPv4Address) IsOneBit(bitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*IPv4Address) IsPrefixBlock 

func (addr *IPv4Address) IsPrefixBlock() bool

IsPrefixBlock returns whether the address has a prefix length and the address range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

To create a prefix block from any address, use ToPrefixBlock.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*IPv4Address) IsPrefixed 

func (addr *IPv4Address) IsPrefixed() bool

IsPrefixed returns whether this address has an associated prefix length.

func (*IPv4Address) IsPrivate 

func (addr *IPv4Address) IsPrivate() bool

IsPrivate returns whether this is a unicast addresses allocated for private use, as defined by RFC 1918.

func (*IPv4Address) IsSingleNetwork 

func (addr *IPv4Address) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address.

func (*IPv4Address) IsSinglePrefixBlock 

func (addr *IPv4Address) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the address range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

For instance, "1.*.*.* /16" returns false from this method and returns true from IsPrefixBlock.

func (*IPv4Address) IsUnspecified 

func (addr *IPv4Address) IsUnspecified() bool

IsUnspecified returns whether this is the unspecified address. The unspecified address is the address that is all zeros.

func (*IPv4Address) IsZeroHost 

func (addr *IPv4Address) IsZeroHost() bool

IsZeroHost returns whether this subnet has a prefix length and if so, whether the host section is always zero for all individual addresses in this subnet.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (*IPv4Address) IsZeroHostLen 

func (addr *IPv4Address) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual addresses in this subnet, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (*IPv4Address) Iterator 

func (addr *IPv4Address) Iterator() Iterator[*IPv4Address]

Iterator provides an iterator to iterate through the individual addresses of this address or subnet.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual addresses.

Call IsMultiple to determine if this instance represents multiple addresses, or GetCount for the count.

func (*IPv4Address) Mask 

func (addr *IPv4Address) Mask(other *IPv4Address) (masked *IPv4Address, err addrerr.IncompatibleAddressError)

Mask applies the given mask to all addresses represented by this IPv4Address. The mask is applied to all individual addresses.

If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned.

func (*IPv4Address) MatchesWithMask 

func (addr *IPv4Address) MatchesWithMask(other *IPv4Address, mask *IPv4Address) bool

MatchesWithMask applies the mask to this address and then compares the result with the given address, returning true if they match, false otherwise.

func (*IPv4Address) MergeToPrefixBlocks 

func (addr *IPv4Address) MergeToPrefixBlocks(addrs ...*IPv4Address) []*IPv4Address

MergeToPrefixBlocks merges this subnet with the list of subnets to produce the smallest array of CIDR prefix blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv4Address) MergeToSequentialBlocks 

func (addr *IPv4Address) MergeToSequentialBlocks(addrs ...*IPv4Address) []*IPv4Address

MergeToSequentialBlocks merges this with the list of addresses to produce the smallest array of sequential blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv4Address) PrefixBlockIterator 

func (addr *IPv4Address) PrefixBlockIterator() Iterator[*IPv4Address]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address or subnet. Each iterated address or subnet will be a prefix block with the same prefix length as this address or subnet.

If this address has no prefix length, then this is equivalent to Iterator.

func (*IPv4Address) PrefixContains 

func (addr *IPv4Address) PrefixContains(other AddressType) bool

PrefixContains returns whether the prefix values in the given address or subnet are prefix values in this address or subnet, using the prefix length of this address or subnet. If this address has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

func (*IPv4Address) PrefixEqual 

func (addr *IPv4Address) PrefixEqual(other AddressType) bool

PrefixEqual determines if the given address matches this address up to the prefix length of this address. It returns whether the two addresses share the same range of prefix values.

func (*IPv4Address) PrefixIterator 

func (addr *IPv4Address) PrefixIterator() Iterator[*IPv4Address]

PrefixIterator provides an iterator to iterate through the individual prefixes of this subnet, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this subnet.

If the subnet has no prefix length, then this is equivalent to Iterator.

func (*IPv4Address) Replace 

func (addr *IPv4Address) Replace(startIndex int, replacement *IPv4AddressSection) *IPv4Address

Replace replaces segments starting from startIndex with segments from the replacement section. Mappings to or from indices outside the range of this address or the replacement section are skipped.

func (*IPv4Address) ReplaceLen 

func (addr *IPv4Address) ReplaceLen(startIndex, endIndex int, replacement *IPv4Address, replacementIndex int) *IPv4Address

ReplaceLen replaces segments starting from startIndex and ending before endIndex with the same number of segments starting at replacementStartIndex from the replacement section. Mappings to or from indices outside the range of this or the replacement address are skipped.

func (*IPv4Address) ReverseBits 

func (addr *IPv4Address) ReverseBits(perByte bool) (*IPv4Address, addrerr.IncompatibleAddressError)

ReverseBits returns a new address with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv4Address) ReverseBytes 

func (addr *IPv4Address) ReverseBytes() *IPv4Address

ReverseBytes returns a new address with the bytes reversed. Any prefix length is dropped.

func (*IPv4Address) ReverseSegments 

func (addr *IPv4Address) ReverseSegments() *IPv4Address

ReverseSegments returns a new address with the segments reversed.

func (*IPv4Address) SequentialBlockIterator 

func (addr *IPv4Address) SequentialBlockIterator() Iterator[*IPv4Address]

SequentialBlockIterator iterates through the sequential subnets or addresses that make up this address or subnet.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

For instance, given the IPv4 subnet "1-2.3-4.5-6.7-8", it will iterate through "1.3.5.7-8", "1.3.6.7-8", "1.4.5.7-8", "1.4.6.7-8", "2.3.5.7-8", "2.3.6.7-8", "2.4.6.7-8" and "2.4.6.7-8".

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPv4Address) SetPrefixLen 

func (addr *IPv4Address) SetPrefixLen(prefixLen BitCount) *IPv4Address

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPv4Address) SetPrefixLenZeroed 

func (addr *IPv4Address) SetPrefixLenZeroed(prefixLen BitCount) (*IPv4Address, addrerr.IncompatibleAddressError)

func (*IPv4Address) SpanWithPrefixBlocks 

func (addr *IPv4Address) SpanWithPrefixBlocks() []*IPv4Address

SpanWithPrefixBlocks returns an array of prefix blocks that cover the same set of addresses as this subnet.

Unlike SpanWithPrefixBlocksTo, the result only includes addresses that are a part of this subnet.

func (*IPv4Address) SpanWithPrefixBlocksTo 

func (addr *IPv4Address) SpanWithPrefixBlocksTo(other *IPv4Address) []*IPv4Address

SpanWithPrefixBlocksTo returns the smallest slice of prefix block subnets that span from this subnet to the given subnet.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

From the list of returned subnets you can recover the original range (this to other) by converting each to IPAddressRange with ToSequentialRange and them joining them into a single range with the Join method of IPAddressSeqRange.

func (*IPv4Address) SpanWithRange 

func (addr *IPv4Address) SpanWithRange(other *IPv4Address) *SequentialRange[*IPv4Address]

SpanWithRange returns an IPv4AddressSeqRange instance that spans this subnet to the given subnet. If the other address is a different version than this, then the other is ignored, and the result is equivalent to calling ToSequentialRange.

func (*IPv4Address) SpanWithSequentialBlocks 

func (addr *IPv4Address) SpanWithSequentialBlocks() []*IPv4Address

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of addresses as this subnet.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

Unlike SpanWithSequentialBlocksTo, this method only includes addresses that are a part of this subnet.

func (*IPv4Address) SpanWithSequentialBlocksTo 

func (addr *IPv4Address) SpanWithSequentialBlocksTo(other *IPv4Address) []*IPv4Address

SpanWithSequentialBlocksTo produces the smallest slice of sequential block subnets that span all values from this subnet to the given subnet. The span will cover all addresses in both subnets and everything in between.

Individual block subnets come in the form "1-3.1-4.5.6-8", however that particular subnet is not sequential since address "1.1.5.8" is in the subnet, the next sequential address "1.1.5.9" is not in the subnet, and a higher address "1.2.5.6" is in the subnet. Blocks are sequential when the first segment with a range of values is followed by segments that span all values.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv4Address) String 

func (addr *IPv4Address) String() string

String implements the fmt.Stringer interface, returning the canonical string provided by ToCanonicalString, or "<nil>" if the receiver is a nil pointer.

func (*IPv4Address) Subtract 

func (addr *IPv4Address) Subtract(other *IPv4Address) []*IPv4Address

Subtract subtracts the given subnet from this subnet, returning an array of subnets for the result (the subnets will not be contiguous so an array is required). Subtract computes the subnet difference, the set of addresses in this address subnet but not in the provided subnet. This is also known as the relative complement of the given argument in this subnet. This is set subtraction, not subtraction of address values (use Increment for the latter). We have a subnet of addresses and we are removing those addresses found in the argument subnet. If there are no remaining addresses, nil is returned.

func (*IPv4Address) TestBit 

func (addr *IPv4Address) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this address. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv4Address) ToAddressBase 

func (addr *IPv4Address) ToAddressBase() *Address

ToAddressBase converts to an Address, a polymorphic type usable with all addresses and subnets. Afterwards, you can convert back with ToIPv4.

ToAddressBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4Address) ToAddressString 

func (addr *IPv4Address) ToAddressString() *IPAddressString

ToAddressString retrieves or generates an IPAddressString instance for this IPAddress instance. This may be the IPAddressString this instance was generated from, if it was generated from an IPAddressString.

In general, users are intended to create IPAddress instances from IPAddressString instances, while the reverse direction is generally not common and not useful, except under specific circumstances.

However, the reverse direction can be useful under certain circumstances, such as when maintaining a collection of HostIdentifierString instances.

func (*IPv4Address) ToBinaryString 

func (addr *IPv4Address) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4Address) ToBlock 

func (addr *IPv4Address) ToBlock(segmentIndex int, lower, upper SegInt) *IPv4Address

ToBlock creates a new block of addresses by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPv4Address) ToBroadcastAddress 

func (addr *IPv4Address) ToBroadcastAddress() (*IPv4Address, addrerr.IncompatibleAddressError)

ToBroadcastAddress returns the IPv4 broadcast address. The broadcast address has the same prefix but a host that is all 1 bits. If this address or subnet is not prefixed, this returns the address of all 1 bits, the "max" address. This returns an error if a prefixed and ranged-valued segment cannot be converted to a host of all ones and remain a range of consecutive values.

func (*IPv4Address) ToCanonicalString 

func (addr *IPv4Address) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address.

For IPv4, dotted octet format, also known as dotted decimal format, is used. https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1

Each address has a unique canonical string, not counting the prefix length. With IP addresses, the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use ToCanonicalWildcardString for a unique string for each IP address and subnet.

func (*IPv4Address) ToCanonicalWildcardString 

func (addr *IPv4Address) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string and avoids the CIDR prefix length. Addresses and subnets with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPv4Address) ToCompressedString 

func (addr *IPv4Address) ToCompressedString() string

ToCompressedString produces a short representation of this address while remaining within the confines of standard representation(s) of the address.

For IPv4, it is the same as the canonical string.

func (*IPv4Address) ToCompressedWildcardString 

func (addr *IPv4Address) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, and in fact for IPv4 it is the same as ToNormalizedWildcardString.

func (*IPv4Address) ToCustomString 

func (addr *IPv4Address) ToCustomString(stringOptions addrstr.IPStringOptions) string

ToCustomString creates a customized string from this address or subnet according to the given string option parameters.

func (*IPv4Address) ToFullString 

func (addr *IPv4Address) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 3 characters for IPv4 segments.

func (*IPv4Address) ToGenericKey added in v1.5.1 

func (addr *IPv4Address) ToGenericKey() Key[*IPv4Address]

ToGenericKey produces a generic Key[*IPv4Address] that can be used with generic code working with Address, IPAddress, IPv4Address, IPv6Address and MACAddress. ToKey produces a more compact key for code that is IPv4-specific.

func (*IPv4Address) ToHexString 

func (addr *IPv4Address) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4Address) ToIP 

func (addr *IPv4Address) ToIP() *IPAddress

ToIP converts to an IPAddress, a polymorphic type usable with all IP addresses and subnets. Afterwards, you can convert back with ToIPv4.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4Address) ToInetAtonJoinedString 

func (addr *IPv4Address) ToInetAtonJoinedString(radix Inet_aton_radix, joinedCount int) (string, addrerr.IncompatibleAddressError)

ToInetAtonJoinedString returns a string with a format that is styled from the inet_aton routine. The string can have an octal or hexadecimal radix rather than decimal, and can have less than the typical four IPv4 segments by joining the least significant segments together, resulting in a string which just 1, 2 or 3 divisions.

When using octal, the octal segments each have a leading zero prefix of "0", and when using hex, a prefix of "0x".

If this represents a subnet section, this returns an error when unable to join two or more segments into a division of a larger bit-length that represents the same set of values.

func (*IPv4Address) ToInetAtonString 

func (addr *IPv4Address) ToInetAtonString(radix Inet_aton_radix) string

ToInetAtonString returns a string with a format that is styled from the inet_aton routine. The string can have an octal or hexadecimal radix rather than decimal. When using octal, the octal segments each have a leading zero prefix of "0", and when using hex, a prefix of "0x".

func (*IPv4Address) ToKey added in v1.1.0 

func (addr *IPv4Address) ToKey() IPv4AddressKey

ToKey creates the associated address key. While addresses can be compared with the Compare, TrieCompare or Equal methods as well as various provided instances of AddressComparator, they are not comparable with Go operators. However, AddressKey instances are comparable with Go operators, and thus can be used as map keys.

func (*IPv4Address) ToMaxHost 

func (addr *IPv4Address) ToMaxHost() (*IPv4Address, addrerr.IncompatibleAddressError)

ToMaxHost converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-ones address, the max address.

The returned address or subnet will have the same prefix and prefix length.

For instance, the max host of "1.2.3.4/16" gives the broadcast address "1.2.255.255/16".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv4Address) ToMaxHostLen 

func (addr *IPv4Address) ToMaxHostLen(prefixLength BitCount) (*IPv4Address, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the resulting one will too, otherwise the resulting address or subnet will have no prefix length.

For instance, the zero host of "1.2.3.4" for the prefix length of 16 is the address "1.2.255.255".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv4Address) ToNetworkAddress 

func (addr *IPv4Address) ToNetworkAddress() (*IPv4Address, addrerr.IncompatibleAddressError)

ToNetworkAddress returns the IPv4 network address. The network address has the same prefix but a zero host. If this address or subnet is not prefixed, this returns the zero "any" address. This returns an error if a prefixed and ranged-valued segment cannot be converted to a host of all zeros and remain a range of consecutive values.

func (*IPv4Address) ToNormalizedString 

func (addr *IPv4Address) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For IPv4, it is the same as the canonical string.

Each address has a unique normalized string, not counting the prefix length. With IP addresses, the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use the method ToNormalizedWildcardString for a unique string for each IP address and subnet.

func (*IPv4Address) ToNormalizedWildcardString 

func (addr *IPv4Address) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPv4Address) ToOctalString 

func (addr *IPv4Address) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4Address) ToPrefixBlock 

func (addr *IPv4Address) ToPrefixBlock() *IPv4Address

ToPrefixBlock returns the subnet associated with the prefix length of this address. If this address has no prefix length, this address is returned.

The subnet will include all addresses with the same prefix as this one, the prefix "block". The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is "1.2.3.4/16" it returns the subnet "1.2.0.0/16", which can also be written as "1.2.*.*/16".

func (*IPv4Address) ToPrefixBlockLen 

func (addr *IPv4Address) ToPrefixBlockLen(prefLen BitCount) *IPv4Address

ToPrefixBlockLen returns the subnet associated with the given prefix length.

The subnet will include all addresses with the same prefix as this one, the prefix "block" for that prefix length. The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is "1.2.3.4" and the prefix length provided is 16, it returns the subnet "1.2.0.0/16", which can also be written as "1.2.*.*/16".

func (*IPv4Address) ToPrefixLenString 

func (addr *IPv4Address) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, a zero host section will be compressed with "::". For IPv4 the string is equivalent to the canonical string.

func (*IPv4Address) ToReverseDNSString 

func (addr *IPv4Address) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse-DNS lookup string. For IPV4, the error is always nil. For "8.255.4.4" it is "4.4.255.8.in-addr.arpa".

func (*IPv4Address) ToSQLWildcardString 

func (addr *IPv4Address) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the wildcard '_'.

func (*IPv4Address) ToSegmentedBinaryString 

func (addr *IPv4Address) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this address as segments of binary values preceded by the "0b" prefix.

func (*IPv4Address) ToSequentialRange 

func (addr *IPv4Address) ToSequentialRange() *SequentialRange[*IPv4Address]

ToSequentialRange creates a sequential range instance from the lowest and highest addresses in this subnet.

The two will represent the same set of individual addresses if and only if IsSequential is true. To get a series of ranges that represent the same set of individual addresses use the SequentialBlockIterator (or PrefixIterator), and apply this method to each iterated subnet.

If this represents just a single address then the returned instance covers just that single address as well.

func (*IPv4Address) ToSinglePrefixBlockOrAddress added in v1.1.0 

func (addr *IPv4Address) ToSinglePrefixBlockOrAddress() *IPv4Address

ToSinglePrefixBlockOrAddress converts to a single prefix block or address. If the given address is a single prefix block, it is returned. If it can be converted to a single prefix block by assigning a prefix length, the converted block is returned. If it is a single address, any prefix length is removed and the address is returned. Otherwise, nil is returned. This method provides the address formats used by tries. ToSinglePrefixBlockOrAddress is quite similar to AssignPrefixForSingleBlock, which always returns prefixed addresses, while this does not.

func (*IPv4Address) ToSubnetString 

func (addr *IPv4Address) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like "1.2.*.*" or "1:2::/16".

In the case of IPv4, this means that wildcards are used instead of a network prefix when a network prefix has been supplied.

func (*IPv4Address) ToUNCHostName added in v1.3.0 

func (addr *IPv4Address) ToUNCHostName() string

ToUNCHostName Generates the Microsoft UNC path component for this address.

For IPv4 it is the canonical string.

func (*IPv4Address) ToZeroHost 

func (addr *IPv4Address) ToZeroHost() (*IPv4Address, addrerr.IncompatibleAddressError)

ToZeroHost converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix and prefix length.

For instance, the zero host of "1.2.3.4/16" is the individual address "1.2.0.0/16".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv4Address) ToZeroHostLen 

func (addr *IPv4Address) ToZeroHostLen(prefixLength BitCount) (*IPv4Address, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.

For instance, the zero host of "1.2.3.4" for the prefix length of 16 is the address "1.2.0.0".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv4Address) ToZeroNetwork 

func (addr *IPv4Address) ToZeroNetwork() *IPv4Address

ToZeroNetwork converts the address or subnet to one in which all individual addresses have a network of zero, the network being the bits within the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix length.

func (*IPv4Address) TrieCompare added in v1.1.0 

func (addr *IPv4Address) TrieCompare(other *IPv4Address) int

TrieCompare compares two addresses according to address trie ordering. It returns a number less than zero, zero, or a number greater than zero if the first address argument is less than, equal to, or greater than the second.

The comparison is intended for individual addresses and CIDR prefix blocks. If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv4Address) TrieDecrement added in v1.1.0 

func (addr *IPv4Address) TrieDecrement() *IPv4Address

TrieDecrement returns the previous address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv4Address) TrieIncrement added in v1.1.0 

func (addr *IPv4Address) TrieIncrement() *IPv4Address

TrieIncrement returns the next address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv4Address) Uint32Value 

func (addr *IPv4Address) Uint32Value() uint32

Uint32Value returns the lowest address in the subnet range as a uint32.

func (*IPv4Address) UpperBytes 

func (addr *IPv4Address) UpperBytes() []byte

UpperBytes returns the highest address in this subnet or address as a byte slice.

func (*IPv4Address) UpperUint32Value 

func (addr *IPv4Address) UpperUint32Value() uint32

UpperUint32Value returns the highest address in the subnet range as a uint32.

func (*IPv4Address) WithoutPrefixLen 

func (addr *IPv4Address) WithoutPrefixLen() *IPv4Address

WithoutPrefixLen provides the same address but with no prefix length. The values remain unchanged.

func (*IPv4Address) Wrap 

func (addr *IPv4Address) Wrap() WrappedIPAddress

Wrap wraps this IP address, returning a WrappedIPAddress, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address.

func (*IPv4Address) WrapAddress added in v1.2.0 

func (addr *IPv4Address) WrapAddress() WrappedAddress

WrapAddress wraps this IP address, returning a WrappedAddress, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapAddress can be called with a nil receiver, wrapping a nil address.

type IPv4AddressAssociativeTrie added in v1.1.0 

type IPv4AddressAssociativeTrie = AssociativeTrie[*IPv4Address, any]

type IPv4AddressConverter 

type IPv4AddressConverter interface {
	// ToIPv4 converts to IPv4.  If the given address is IPv4, or can be converted to IPv4, returns that IPv4Address.  Otherwise, returns nil.
	ToIPv4(address *IPAddress) *IPv4Address
}

IPv4AddressConverter converts IP addresses to IPv4.

type IPv4AddressKey added in v1.1.0 

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

IPv4AddressKey is a representation of an IPv4 address that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators

It can be used as a map key. It can be obtained from its originating address instances. The zero value corresponds to the zero-value for IPv4Address. Keys do not incorporate prefix length to ensure that all equal addresses have equal keys. To create a key that has prefix length, combine into a struct with the PrefixKey obtained by passing the address into PrefixKeyFrom. IPv4Address can be compared using the Compare or Equal methods, or using an AddressComparator.

func (IPv4AddressKey) String added in v1.1.1 

func (key IPv4AddressKey) String() string

String calls the String method in the corresponding address.

func (IPv4AddressKey) ToAddress added in v1.1.0 

func (key IPv4AddressKey) ToAddress() *IPv4Address

ToAddress converts back to an address instance.

type IPv4AddressNetwork 

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

IPv4AddressNetwork is the implementation of IPAddressNetwork for IPv4

func (IPv4AddressNetwork) GetHostMask 

func (network IPv4AddressNetwork) GetHostMask(prefLen BitCount) *IPv4Address

func (IPv4AddressNetwork) GetLoopback 

func (network IPv4AddressNetwork) GetLoopback() *IPv4Address

func (IPv4AddressNetwork) GetNetworkMask 

func (network IPv4AddressNetwork) GetNetworkMask(prefLen BitCount) *IPv4Address

func (IPv4AddressNetwork) GetPrefixedHostMask 

func (network IPv4AddressNetwork) GetPrefixedHostMask(prefLen BitCount) *IPv4Address

func (IPv4AddressNetwork) GetPrefixedNetworkMask 

func (network IPv4AddressNetwork) GetPrefixedNetworkMask(prefLen BitCount) *IPv4Address

type IPv4AddressSection 

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

IPv4AddressSection represents a section of an IPv4 address comprising 0 to 4 IPv4 address segments. The zero values is a section with zero-segments.

func NewIPv4PrefixedSection 

func NewIPv4PrefixedSection(segments []*IPv4AddressSegment, prefixLen PrefixLen) *IPv4AddressSection

NewIPv4PrefixedSection constructs an IPv4 address or subnet section from the given segments and prefix length.

func NewIPv4Section 

func NewIPv4Section(segments []*IPv4AddressSegment) *IPv4AddressSection

NewIPv4Section constructs an IPv4 address or subnet section from the given segments.

func NewIPv4SectionFromBytes 

func NewIPv4SectionFromBytes(bytes []byte) *IPv4AddressSection

NewIPv4SectionFromBytes constructs an IPv4 address section from the given byte slice. The segment count is determined by the slice length, even if the segment count exceeds 4 segments.

func NewIPv4SectionFromPrefixedBytes 

func NewIPv4SectionFromPrefixedBytes(bytes []byte, segmentCount int, prefixLength PrefixLen) (res *IPv4AddressSection, err addrerr.AddressValueError)

NewIPv4SectionFromPrefixedBytes constructs an IPv4 address or prefix block section from the given byte slice and prefix length. It allows you to specify the segment count for the supplied bytes. If the slice is too large for the given number of segments, an error is returned, although leading zeros are tolerated.

func NewIPv4SectionFromPrefixedRange 

func NewIPv4SectionFromPrefixedRange(vals, upperVals IPv4SegmentValueProvider, segmentCount int, prefixLength PrefixLen) (res *IPv4AddressSection)

NewIPv4SectionFromPrefixedRange constructs an IPv4 subnet section of the given segment count from the given values and prefix length.

func NewIPv4SectionFromPrefixedUint32 

func NewIPv4SectionFromPrefixedUint32(value uint32, segmentCount int, prefixLength PrefixLen) (res *IPv4AddressSection)

NewIPv4SectionFromPrefixedUint32 constructs an IPv4 address or prefix block section of the given segment count from the given value and prefix length.

func NewIPv4SectionFromPrefixedVals 

func NewIPv4SectionFromPrefixedVals(vals IPv4SegmentValueProvider, segmentCount int, prefixLength PrefixLen) (res *IPv4AddressSection)

NewIPv4SectionFromPrefixedVals constructs an IPv4 address or prefix block section of the given segment count from the given values and prefix length.

func NewIPv4SectionFromRange 

func NewIPv4SectionFromRange(vals, upperVals IPv4SegmentValueProvider, segmentCount int) (res *IPv4AddressSection)

NewIPv4SectionFromRange constructs an IPv4 subnet section of the given segment count from the given values.

func NewIPv4SectionFromSegmentedBytes 

func NewIPv4SectionFromSegmentedBytes(bytes []byte, segmentCount int) (res *IPv4AddressSection, err addrerr.AddressValueError)

NewIPv4SectionFromSegmentedBytes constructs an IPv4 address section from the given byte slice. It allows you to specify the segment count for the supplied bytes. If the slice is too large for the given number of segments, an error is returned, although leading zeros are tolerated.

func NewIPv4SectionFromUint32 

func NewIPv4SectionFromUint32(value uint32, segmentCount int) (res *IPv4AddressSection)

NewIPv4SectionFromUint32 constructs an IPv4 address section of the given segment count from the given value.

func NewIPv4SectionFromVals 

func NewIPv4SectionFromVals(vals IPv4SegmentValueProvider, segmentCount int) (res *IPv4AddressSection)

NewIPv4SectionFromVals constructs an IPv4 address section of the given segment count from the given values.

func (*IPv4AddressSection) AdjustPrefixLen 

func (section *IPv4AddressSection) AdjustPrefixLen(prefixLen BitCount) *IPv4AddressSection

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*IPv4AddressSection) AdjustPrefixLenZeroed 

func (section *IPv4AddressSection) AdjustPrefixLenZeroed(prefixLen BitCount) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv4AddressSection) Append 

func (section *IPv4AddressSection) Append(other *IPv4AddressSection) *IPv4AddressSection

Append creates a new section by appending the given section to this section.

func (*IPv4AddressSection) AssignMinPrefixForBlock 

func (section *IPv4AddressSection) AssignMinPrefixForBlock() *IPv4AddressSection

AssignMinPrefixForBlock returns an equivalent address section, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this address section.

In other words, this method assigns a prefix length to this address section matching the largest prefix block in this address section.

func (*IPv4AddressSection) AssignPrefixForSingleBlock 

func (section *IPv4AddressSection) AssignPrefixForSingleBlock() *IPv4AddressSection

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address section. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address section - it is required that the range of values match the range of a prefix block. If there is no such address section, then nil is returned.

func (*IPv4AddressSection) BitwiseOr 

func (section *IPv4AddressSection) BitwiseOr(other *IPv4AddressSection) (res *IPv4AddressSection, err addrerr.IncompatibleAddressError)

BitwiseOr does the bitwise disjunction with this address section, useful when subnetting. It is similar to Mask which does the bitwise conjunction.

The operation is applied to all individual addresses and the result is returned.

If this represents multiple address sections, and applying the operation to all sections creates a set of sections that cannot be represented as a sequential range within each segment, then an error is returned.

func (*IPv4AddressSection) BlockIterator 

func (section *IPv4AddressSection) BlockIterator(segmentCount int) Iterator[*IPv4AddressSection]

BlockIterator Iterates through the address sections that can be obtained by iterating through all the upper segments up to the given segment count. The segments following remain the same in all iterated sections.

func (*IPv4AddressSection) Bytes 

func (section *IPv4AddressSection) Bytes() []byte

Bytes returns the lowest individual address section in this address section as a byte slice.

func (*IPv4AddressSection) Compare 

func (section *IPv4AddressSection) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address section is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPv4AddressSection) CompareSize 

func (section *IPv4AddressSection) CompareSize(other AddressItem) int

CompareSize compares the counts of two address sections or items, the number of individual sections or other items represented.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether this section represents more individual address sections than another.

CompareSize returns a positive integer if this address section has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPv4AddressSection) Contains 

func (section *IPv4AddressSection) Contains(other AddressSectionType) bool

Contains returns whether this is same type and version as the given address section and whether it contains all values in the given section.

Sections must also have the same number of segments to be comparable, otherwise false is returned.

func (*IPv4AddressSection) ContainsPrefixBlock 

func (section *IPv4AddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPv4AddressSection) ContainsSinglePrefixBlock 

func (section *IPv4AddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this section contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPv4AddressSection) CopyBytes 

func (section *IPv4AddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4AddressSection) CopySegments 

func (section *IPv4AddressSection) CopySegments(segs []*IPv4AddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPv4AddressSection) CopySubSegments 

func (section *IPv4AddressSection) CopySubSegments(start, end int, segs []*IPv4AddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPv4AddressSection) CopyUpperBytes 

func (section *IPv4AddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4AddressSection) CoverWithPrefixBlock 

func (section *IPv4AddressSection) CoverWithPrefixBlock() *IPv4AddressSection

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the individual address sections in this section. The resulting block will have a larger count than this, unless this section is already a prefix block.

func (*IPv4AddressSection) CoverWithPrefixBlockTo 

func (section *IPv4AddressSection) CoverWithPrefixBlockTo(other *IPv4AddressSection) (*IPv4AddressSection, addrerr.SizeMismatchError)

CoverWithPrefixBlockTo returns the minimal-size prefix block section that covers all the address sections spanning from this to the given section.

If the other section has a different segment count, an error is returned.

func (*IPv4AddressSection) Equal 

func (section *IPv4AddressSection) Equal(other AddressSectionType) bool

Equal returns whether the given address section is equal to this address section. Two address sections are equal if they represent the same set of sections. They must match:

  • type/version: IPv4
  • segment counts
  • segment value ranges

Prefix lengths are ignored.

func (*IPv4AddressSection) ForEachSegment added in v1.2.0 

func (section *IPv4AddressSection) ForEachSegment(consumer func(segmentIndex int, segment *IPv4AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (*IPv4AddressSection) GetBitCount 

func (section *IPv4AddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (*IPv4AddressSection) GetBitsPerSegment 

func (section *IPv4AddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (*IPv4AddressSection) GetBlockCount 

func (section *IPv4AddressSection) GetBlockCount(segmentCount int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments. It is similar to GetIPv4BlockCount but returns a big integer instead of a uint64.

func (*IPv4AddressSection) GetBlockMaskPrefixLen 

func (section *IPv4AddressSection) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address section is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address section with all ones in the network section and then all zeros in the host section. A CIDR host mask is an address section with all zeros in the network section and then all ones in the host section. The prefix length is the bit-length of the network section.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this instance, indicating the network and host section of this address section. The prefix length returned here indicates the whether the value of this address can be used as a mask for the network and host section of any other address. Therefore the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this section represents multiple values.

func (*IPv4AddressSection) GetByteCount 

func (section *IPv4AddressSection) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item.

func (*IPv4AddressSection) GetBytesPerSegment 

func (section *IPv4AddressSection) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this section. Segments in the same address section are equal length.

func (*IPv4AddressSection) GetCount 

func (section *IPv4AddressSection) GetCount() *big.Int

GetCount returns the count of possible distinct values for this section. It is the same as GetIPv4Count but returns the value as a big integer instead of a uint64. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv4AddressSection) GetGenericSegment 

func (section *IPv4AddressSection) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPv4AddressSection) GetHostMask 

func (section *IPv4AddressSection) GetHostMask() *IPv4AddressSection

GetHostMask returns the host mask associated with the CIDR network prefix length of this address section. If this section has no prefix length, then the all-ones mask is returned.

func (*IPv4AddressSection) GetHostSection 

func (section *IPv4AddressSection) GetHostSection() *IPv4AddressSection

GetHostSection returns a subsection containing the segments with the host of the address section, the bits beyond the CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

If this series has no prefix length, the returned host section will be the full section.

func (*IPv4AddressSection) GetHostSectionLen 

func (section *IPv4AddressSection) GetHostSectionLen(prefLen BitCount) *IPv4AddressSection

GetHostSectionLen returns a subsection containing the segments with the host of the address section, the bits beyond the given CIDR network prefix length. The returned section will have only as many segments as needed to contain the host. The returned section will have an assigned prefix length indicating the beginning of the host.

func (*IPv4AddressSection) GetIPVersion 

func (section *IPv4AddressSection) GetIPVersion() IPVersion

GetIPVersion returns IPv4, the IP version of this address section.

func (*IPv4AddressSection) GetIPv4BlockCount 

func (section *IPv4AddressSection) GetIPv4BlockCount(segmentCount int) uint64

GetIPv4BlockCount returns the count of distinct values in the given number of initial (more significant) segments. It is similar to GetBlockCount but returns a uint64 instead of a big integer.

func (*IPv4AddressSection) GetIPv4Count 

func (section *IPv4AddressSection) GetIPv4Count() uint64

GetIPv4Count returns the count of possible distinct values for this section. It is the same as GetCount but returns the value as a uint64 instead of a big integer. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv4AddressSection) GetIPv4PrefixCount 

func (section *IPv4AddressSection) GetIPv4PrefixCount() uint64

GetIPv4PrefixCount returns the number of distinct prefix values in this section. It is similar to GetPrefixCount but returns a uint64.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetIPv4Count.

func (*IPv4AddressSection) GetIPv4PrefixCountLen 

func (section *IPv4AddressSection) GetIPv4PrefixCountLen(prefixLength BitCount) uint64

GetIPv4PrefixCountLen returns the number of distinct prefix values in this item for the given prefix length.

It is the same as GetPrefixCountLen but returns a uint64, not a *big.Int.

func (*IPv4AddressSection) GetLower 

func (section *IPv4AddressSection) GetLower() *IPv4AddressSection

GetLower returns the section in the range with the lowest numeric value, which will be the same section if it represents a single value. For example, for "1.2-3.4.5-6", the section "1.2.4.5" is returned.

func (*IPv4AddressSection) GetMaxSegmentValue 

func (section *IPv4AddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPv4AddressSection) GetMinPrefixLenForBlock 

func (section *IPv4AddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (*IPv4AddressSection) GetNetworkMask 

func (section *IPv4AddressSection) GetNetworkMask() *IPv4AddressSection

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address section. If this section has no prefix length, then the all-ones mask is returned.

func (*IPv4AddressSection) GetNetworkPrefixLen 

func (section *IPv4AddressSection) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. It is equivalent to GetPrefixLen.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (*IPv4AddressSection) GetNetworkSection 

func (section *IPv4AddressSection) GetNetworkSection() *IPv4AddressSection

GetNetworkSection returns a subsection containing the segments with the network bits of the section. The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.

If this series has no CIDR prefix length, the returned network section will be the entire series as a prefixed section with prefix length matching the address bit length.

func (*IPv4AddressSection) GetNetworkSectionLen 

func (section *IPv4AddressSection) GetNetworkSectionLen(prefLen BitCount) *IPv4AddressSection

GetNetworkSectionLen returns a subsection containing the segments with the network of the section, the prefix bits according to the given prefix length. The returned section will have only as many segments as needed to contain the network.

The new section will be assigned the given prefix length, unless the existing prefix length is smaller, in which case the existing prefix length will be retained.

func (*IPv4AddressSection) GetPrefixCount 

func (section *IPv4AddressSection) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetCount.

func (*IPv4AddressSection) GetPrefixCountLen 

func (section *IPv4AddressSection) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length.

func (*IPv4AddressSection) GetPrefixLenForSingleBlock 

func (section *IPv4AddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (*IPv4AddressSection) GetSegment 

func (section *IPv4AddressSection) GetSegment(index int) *IPv4AddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPv4AddressSection) GetSegmentCount 

func (section *IPv4AddressSection) GetSegmentCount() int

GetSegmentCount returns the segment/division count.

func (*IPv4AddressSection) GetSegmentStrings 

func (section *IPv4AddressSection) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*IPv4AddressSection) GetSegments 

func (section *IPv4AddressSection) GetSegments() (res []*IPv4AddressSegment)

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*IPv4AddressSection) GetSequentialBlockCount 

func (section *IPv4AddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section.

func (*IPv4AddressSection) GetSequentialBlockIndex 

func (section *IPv4AddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (*IPv4AddressSection) GetSubSection 

func (section *IPv4AddressSection) GetSubSection(index, endIndex int) *IPv4AddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*IPv4AddressSection) GetTrailingSection 

func (section *IPv4AddressSection) GetTrailingSection(index int) *IPv4AddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*IPv4AddressSection) GetUpper 

func (section *IPv4AddressSection) GetUpper() *IPv4AddressSection

GetUpper returns the section in the range with the highest numeric value, which will be the same section if it represents a single value. For example, for "1.2-3.4.5-6", the section "1.3.4.6" is returned.

func (*IPv4AddressSection) GetUpperValue 

func (section *IPv4AddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value.

func (*IPv4AddressSection) GetValue 

func (section *IPv4AddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value.

func (*IPv4AddressSection) IncludesMax 

func (section *IPv4AddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range.

func (*IPv4AddressSection) IncludesMaxHost 

func (section *IPv4AddressSection) IncludesMaxHost() bool

IncludesMaxHost returns whether the address section contains an individual address section with a host of all one-bits. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are one.

func (*IPv4AddressSection) IncludesMaxHostLen 

func (section *IPv4AddressSection) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the address section contains an individual address section with a host of all one-bits, an address section for which all bits past the given prefix length are all ones.

func (*IPv4AddressSection) IncludesZero 

func (section *IPv4AddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range.

func (*IPv4AddressSection) IncludesZeroHost 

func (section *IPv4AddressSection) IncludesZeroHost() bool

IncludesZeroHost returns whether the address section contains an individual address section with a host of zero. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are zero.

func (*IPv4AddressSection) IncludesZeroHostLen 

func (section *IPv4AddressSection) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the address section contains an individual section with a host of zero, a section for which all bits past the given prefix length are zero.

func (*IPv4AddressSection) Increment 

func (section *IPv4AddressSection) Increment(inc int64) *IPv4AddressSection

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (*IPv4AddressSection) IncrementBoundary 

func (section *IPv4AddressSection) IncrementBoundary(increment int64) *IPv4AddressSection

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (*IPv4AddressSection) Insert 

func (section *IPv4AddressSection) Insert(index int, other *IPv4AddressSection) *IPv4AddressSection

Insert creates a new section by inserting the given section into this section at the given index.

func (*IPv4AddressSection) Intersect 

func (section *IPv4AddressSection) Intersect(other *IPv4AddressSection) (res *IPv4AddressSection, err addrerr.SizeMismatchError)

Intersect returns the subnet sections whose individual sections are found in both this and the given subnet section argument, or nil if no such sections exist.

This is also known as the conjunction of the two sets of address sections.

If the two sections have different segment counts, an error is returned.

func (*IPv4AddressSection) IsAdaptiveZero 

func (section *IPv4AddressSection) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the division grouping was originally created as an implicitly zero-valued section or grouping (e.g. IPv4AddressSection{}), meaning it was not constructed using a constructor function. Such a grouping, which has no divisions or segments, is convertible to an implicitly zero-valued grouping of any type or version, whether IPv6, IPv4, MAC, or other. In other words, when a section or grouping is the zero-value, then it is equivalent and convertible to the zero value of any other section or grouping type.

func (*IPv4AddressSection) IsFullRange 

func (section *IPv4AddressSection) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv4AddressSection) IsMax 

func (section *IPv4AddressSection) IsMax() bool

IsMax returns whether this section matches exactly the maximum possible value, the value whose bits are all ones.

func (*IPv4AddressSection) IsMaxHost 

func (section *IPv4AddressSection) IsMaxHost() bool

IsMaxHost returns whether this section has a prefix length and if so, whether the host is all all one-bits, the max value, for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsMaxHost returns true.

func (*IPv4AddressSection) IsMaxHostLen 

func (section *IPv4AddressSection) IsMaxHostLen(prefLen BitCount) bool

IsMaxHostLen returns whether the host host is all one-bits, the max value, for all individual sections in this address section, for the given prefix length, the host being the bits following the prefix.

If the host section is zero length (there are zero host bits), IsMaxHostLen returns true.

func (*IPv4AddressSection) IsMultiple 

func (section *IPv4AddressSection) IsMultiple() bool

IsMultiple returns whether this section represents multiple values.

func (*IPv4AddressSection) IsOneBit 

func (section *IPv4AddressSection) IsOneBit(prefixBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*IPv4AddressSection) IsPrefixBlock 

func (section *IPv4AddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*IPv4AddressSection) IsPrefixed 

func (section *IPv4AddressSection) IsPrefixed() bool

IsPrefixed returns whether this section has an associated prefix length.

func (*IPv4AddressSection) IsSequential 

func (section *IPv4AddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (*IPv4AddressSection) IsSingleNetwork 

func (section *IPv4AddressSection) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address section.

func (*IPv4AddressSection) IsSinglePrefixBlock 

func (section *IPv4AddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPv4AddressSection) IsZero 

func (section *IPv4AddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero.

func (*IPv4AddressSection) IsZeroHost 

func (section *IPv4AddressSection) IsZeroHost() bool

IsZeroHost returns whether this section has a prefix length and if so, whether the host section is always zero for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (*IPv4AddressSection) IsZeroHostLen 

func (section *IPv4AddressSection) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual sections in this address section, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (*IPv4AddressSection) Iterator 

func (section *IPv4AddressSection) Iterator() Iterator[*IPv4AddressSection]

Iterator provides an iterator to iterate through the individual address sections of this address section.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address sections.

Call IsMultiple to determine if this instance represents multiple address sections, or GetCount for the count.

func (*IPv4AddressSection) Mask 

func (section *IPv4AddressSection) Mask(other *IPv4AddressSection) (res *IPv4AddressSection, err addrerr.IncompatibleAddressError)

Mask applies the given mask to all address sections represented by this secction, returning the result.

If the sections do not have a comparable number of segments, an error is returned.

If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned.

func (*IPv4AddressSection) MatchesWithMask 

func (section *IPv4AddressSection) MatchesWithMask(other *IPv4AddressSection, mask *IPv4AddressSection) bool

MatchesWithMask applies the mask to this address section and then compares the result with the given address section, returning true if they match, false otherwise. To match, both the given section and mask must have the same number of segments as this section.

func (*IPv4AddressSection) MergeToPrefixBlocks 

func (section *IPv4AddressSection) MergeToPrefixBlocks(sections ...*IPv4AddressSection) ([]*IPv4AddressSection, addrerr.SizeMismatchError)

MergeToPrefixBlocks merges this section with the list of sections to produce the smallest array of prefix blocks.

The resulting slice is sorted from lowest value to highest, regardless of the size of each prefix block.

func (*IPv4AddressSection) MergeToSequentialBlocks 

func (section *IPv4AddressSection) MergeToSequentialBlocks(sections ...*IPv4AddressSection) ([]*IPv4AddressSection, addrerr.SizeMismatchError)

MergeToSequentialBlocks merges this with the list of sections to produce the smallest array of sequential blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv4AddressSection) PrefixBlockIterator 

func (section *IPv4AddressSection) PrefixBlockIterator() Iterator[*IPv4AddressSection]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address section. Each iterated address section will be a prefix block with the same prefix length as this address section.

If this address section has no prefix length, then this is equivalent to Iterator.

func (*IPv4AddressSection) PrefixContains 

func (section *IPv4AddressSection) PrefixContains(other AddressSectionType) bool

PrefixContains returns whether the prefix values in the given address section are prefix values in this address section, using the prefix length of this section. If this address section has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

All prefix bits of this section must be present in the other section to be comparable.

func (*IPv4AddressSection) PrefixEqual 

func (section *IPv4AddressSection) PrefixEqual(other AddressSectionType) bool

PrefixEqual determines if the given section matches this section up to the prefix length of this section. It returns whether the argument section has the same address section prefix values as this.

All prefix bits of this section must be present in the other section to be comparable, otherwise false is returned.

func (*IPv4AddressSection) PrefixIterator 

func (section *IPv4AddressSection) PrefixIterator() Iterator[*IPv4AddressSection]

PrefixIterator provides an iterator to iterate through the individual prefixes of this address section, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this address section.

If the series has no prefix length, then this is equivalent to Iterator.

func (*IPv4AddressSection) Replace 

func (section *IPv4AddressSection) Replace(index int, replacement *IPv4AddressSection) *IPv4AddressSection

Replace replaces the segments of this section starting at the given index with the given replacement segments.

func (*IPv4AddressSection) ReplaceLen 

func (section *IPv4AddressSection) ReplaceLen(startIndex, endIndex int, replacement *IPv4AddressSection, replacementStartIndex, replacementEndIndex int) *IPv4AddressSection

ReplaceLen replaces segments starting from startIndex and ending before endIndex with the segments starting at replacementStartIndex and ending before replacementEndIndex from the replacement section.

func (*IPv4AddressSection) ReverseBits 

func (section *IPv4AddressSection) ReverseBits(perByte bool) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

ReverseBits returns a new section with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv4AddressSection) ReverseBytes 

func (section *IPv4AddressSection) ReverseBytes() *IPv4AddressSection

ReverseBytes returns a new section with the bytes reversed. Any prefix length is dropped.

func (*IPv4AddressSection) ReverseSegments 

func (section *IPv4AddressSection) ReverseSegments() *IPv4AddressSection

ReverseSegments returns a new section with the segments reversed.

func (*IPv4AddressSection) SequentialBlockIterator 

func (section *IPv4AddressSection) SequentialBlockIterator() Iterator[*IPv4AddressSection]

SequentialBlockIterator iterates through the sequential address sections that make up this address section.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPv4AddressSection) SetPrefixLen 

func (section *IPv4AddressSection) SetPrefixLen(prefixLen BitCount) *IPv4AddressSection

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPv4AddressSection) SetPrefixLenZeroed 

func (section *IPv4AddressSection) SetPrefixLenZeroed(prefixLen BitCount) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

If this address section has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address section has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv4AddressSection) SpanWithPrefixBlocks 

func (section *IPv4AddressSection) SpanWithPrefixBlocks() []*IPv4AddressSection

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual address sections as this section.

Unlike SpanWithPrefixBlocksTo, the result only includes blocks that are a part of this section.

func (*IPv4AddressSection) SpanWithPrefixBlocksTo 

func (section *IPv4AddressSection) SpanWithPrefixBlocksTo(other *IPv4AddressSection) ([]*IPv4AddressSection, addrerr.SizeMismatchError)

SpanWithPrefixBlocksTo returns the smallest slice of prefix block subnet sections that span from this section to the given section.

If the given section has a different segment count, an error is returned.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv4AddressSection) SpanWithSequentialBlocks 

func (section *IPv4AddressSection) SpanWithSequentialBlocks() []*IPv4AddressSection

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of sections as this.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

Unlike SpanWithSequentialBlocksTo, this method only includes values that are a part of this section.

func (*IPv4AddressSection) SpanWithSequentialBlocksTo 

func (section *IPv4AddressSection) SpanWithSequentialBlocksTo(other *IPv4AddressSection) ([]*IPv4AddressSection, addrerr.SizeMismatchError)

SpanWithSequentialBlocksTo produces the smallest slice of sequential block address sections that span from this section to the given section.

func (*IPv4AddressSection) String 

func (section *IPv4AddressSection) String() string

String implements the fmt.Stringer interface, returning the normalized string provided by ToNormalizedString, or "<nil>" if the receiver is a nil pointer.

func (*IPv4AddressSection) Subtract 

func (section *IPv4AddressSection) Subtract(other *IPv4AddressSection) (res []*IPv4AddressSection, err addrerr.SizeMismatchError)

Subtract subtracts the given subnet sections from this subnet section, returning an array of sections for the result (the subnet sections will not be contiguous so an array is required).

Subtract computes the subnet difference, the set of address sections in this address section but not in the provided section. This is also known as the relative complement of the given argument in this subnet section.

This is set subtraction, not subtraction of values.

func (*IPv4AddressSection) TestBit 

func (section *IPv4AddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv4AddressSection) ToBinaryString 

func (section *IPv4AddressSection) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address section as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4AddressSection) ToBlock 

func (section *IPv4AddressSection) ToBlock(segmentIndex int, lower, upper SegInt) *IPv4AddressSection

ToBlock creates a new block of address sections by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPv4AddressSection) ToCanonicalString 

func (section *IPv4AddressSection) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address section.

For IPv4, dotted octet format, also known as dotted decimal format, is used. https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

If this section has a prefix length, it will be included in the string.

func (*IPv4AddressSection) ToCanonicalWildcardString 

func (section *IPv4AddressSection) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string but avoids the CIDR prefix length. Address sections with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPv4AddressSection) ToCompressedString 

func (section *IPv4AddressSection) ToCompressedString() string

ToCompressedString produces a short representation of this address section while remaining within the confines of standard representation(s) of the address.

For IPv4, it is the same as the canonical string.

func (*IPv4AddressSection) ToCompressedWildcardString 

func (section *IPv4AddressSection) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, and in fact for IPv4 it is the same as ToNormalizedWildcardString.

func (*IPv4AddressSection) ToDivGrouping 

func (section *IPv4AddressSection) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToIPv4.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSection) ToFullString 

func (section *IPv4AddressSection) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 3 characters for IPv4 segments.

func (*IPv4AddressSection) ToHexString 

func (section *IPv4AddressSection) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address section as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4AddressSection) ToIP 

func (section *IPv4AddressSection) ToIP() *IPAddressSection

ToIP converts to an IPAddressSection, a polymorphic type usable with all IP address sections.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSection) ToInetAtonJoinedString 

func (section *IPv4AddressSection) ToInetAtonJoinedString(radix Inet_aton_radix, joinedCount int) (string, addrerr.IncompatibleAddressError)

ToInetAtonJoinedString returns a string with a format that is styled from the inet_aton routine. The string can have an octal or hexadecimal radix rather than decimal, and can have less than the typical four IPv4 segments by joining the least significant segments together, resulting in a string which just 1, 2 or 3 divisions.

When using octal, the octal segments each have a leading zero prefix of "0", and when using hex, a prefix of "0x".

If this represents a subnet section, this returns an error when unable to join two or more segments into a division of a larger bit-length that represents the same set of values.

func (*IPv4AddressSection) ToInetAtonString 

func (section *IPv4AddressSection) ToInetAtonString(radix Inet_aton_radix) string

ToInetAtonString returns a string with a format that is styled from the inet_aton routine. The string can have an octal or hexadecimal radix rather than decimal. When using octal, the octal segments each have a leading zero prefix of "0", and when using hex, a prefix of "0x".

func (*IPv4AddressSection) ToJoinedSegments 

func (section *IPv4AddressSection) ToJoinedSegments(joinCount int) (AddressDivisionSeries, addrerr.IncompatibleAddressError)

ToJoinedSegments returns an AddressDivisionSeries which organizes the address section by joining the least significant segments together. If joined count is not a positive number, or this section has less than 2 segments, then this returns the original receiver section. Otherwise this returns an AddressDivisionGrouping in which the last division is the division created by joining two or more segments.

If this represents a subnet section, this returns an error when unable to join address segments, one of the first with a range of values, into a division of the larger bit-length that represents the same set of values.

func (*IPv4AddressSection) ToMaxHost 

func (section *IPv4AddressSection) ToMaxHost() (*IPv4AddressSection, addrerr.IncompatibleAddressError)

ToMaxHost converts the address section to one in which all individual address sections have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-ones section, the max address section.

The returned address section will have the same prefix and prefix length.

This returns an error if the address section is a range of address sections which cannot be converted to a range in which all sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv4AddressSection) ToMaxHostLen 

func (section *IPv4AddressSection) ToMaxHostLen(prefixLength BitCount) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address section to one in which all individual address sections have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this section has the same prefix length, then the resulting section will too, otherwise the resulting section will have no prefix length.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all address sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv4AddressSection) ToNormalizedJoinedString 

func (section *IPv4AddressSection) ToNormalizedJoinedString(stringParams addrstr.IPStringOptions, joinedCount int) (string, addrerr.IncompatibleAddressError)

ToNormalizedJoinedString returns a string with a format that is styled from the inet_aton routine. The string can have less than the typical four IPv4 segments by joining the least significant segments together, resulting in a string which just 1, 2 or 3 divisions.

The method accepts an argument of string options as well, allowing callers to customize the string in other ways as well.

If this represents a subnet section, this returns an error when unable to join two or more segments into a division of a larger bit-length that represents the same set of values.

func (*IPv4AddressSection) ToNormalizedString 

func (section *IPv4AddressSection) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address section.

For IPv4, it is the same as the canonical string.

If this section has a prefix length, it will be included in the string.

func (*IPv4AddressSection) ToNormalizedWildcardString 

func (section *IPv4AddressSection) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPv4AddressSection) ToOctalString 

func (section *IPv4AddressSection) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address section as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4AddressSection) ToPrefixBlock 

func (section *IPv4AddressSection) ToPrefixBlock() *IPv4AddressSection

ToPrefixBlock returns the section with the same prefix as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

If this section has no prefix, this section is returned.

func (*IPv4AddressSection) ToPrefixBlockLen 

func (section *IPv4AddressSection) ToPrefixBlockLen(prefLen BitCount) *IPv4AddressSection

ToPrefixBlockLen returns the section with the same prefix of the given length as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

func (*IPv4AddressSection) ToPrefixLenString 

func (section *IPv4AddressSection) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv4 the string is equivalent to the canonical string.

func (*IPv4AddressSection) ToReverseDNSString 

func (section *IPv4AddressSection) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse-DNS lookup string. For IPV4, the error is always nil. For "8.255.4.4" it is "4.4.255.8.in-addr.arpa".

func (*IPv4AddressSection) ToSQLWildcardString 

func (section *IPv4AddressSection) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the wildcard '_'.

func (*IPv4AddressSection) ToSectionBase 

func (section *IPv4AddressSection) ToSectionBase() *AddressSection

ToSectionBase converts to an AddressSection, a polymorphic type usable with all address sections. Afterwards, you can convert back with ToIPv4.

ToSectionBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSection) ToSegmentedBinaryString 

func (section *IPv4AddressSection) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this address section as segments of binary values preceded by the "0b" prefix.

func (*IPv4AddressSection) ToSubnetString 

func (section *IPv4AddressSection) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like "1.2.*.*" or "1:2::/16".

In the case of IPv4, this means that wildcards are used instead of a network prefix when a network prefix has been supplied.

func (*IPv4AddressSection) ToZeroHost 

func (section *IPv4AddressSection) ToZeroHost() (*IPv4AddressSection, addrerr.IncompatibleAddressError)

ToZeroHost converts the address section to one in which all individual address sections have a host of zero, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned section will have the same prefix and prefix length.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv4AddressSection) ToZeroHostLen 

func (section *IPv4AddressSection) ToZeroHostLen(prefixLength BitCount) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address section to one in which all individual sections have a host of zero, the host being the bits following the given prefix length. If this address section has the same prefix length, then the returned one will too, otherwise the returned section will have no prefix length.

This returns an error if the section is a range of which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv4AddressSection) ToZeroNetwork 

func (section *IPv4AddressSection) ToZeroNetwork() *IPv4AddressSection

ToZeroNetwork converts the address section to one in which all individual address sections have a network of zero, the network being the bits within the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned address section will have the same prefix length.

func (*IPv4AddressSection) Uint32Value 

func (section *IPv4AddressSection) Uint32Value() uint32

Uint32Value returns the lowest address in the address section range as a uint32.

func (*IPv4AddressSection) UpperBytes 

func (section *IPv4AddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice.

func (*IPv4AddressSection) UpperUint32Value 

func (section *IPv4AddressSection) UpperUint32Value() uint32

UpperUint32Value returns the highest address in the address section range as a uint32.

func (*IPv4AddressSection) WithoutPrefixLen 

func (section *IPv4AddressSection) WithoutPrefixLen() *IPv4AddressSection

WithoutPrefixLen provides the same address section but with no prefix length. The values remain unchanged.

func (*IPv4AddressSection) Wrap 

func (section *IPv4AddressSection) Wrap() WrappedIPAddressSection

Wrap wraps this IP address section, returning a WrappedIPAddressSection, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address section.

func (*IPv4AddressSection) WrapSection added in v1.2.0 

func (section *IPv4AddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapSection can be called with a nil receiver, wrapping a nil address section.

type IPv4AddressSegment 

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

IPv4AddressSegment represents a segment of an IPv4 address. An IPv4 segment contains a single value or a range of sequential values, a prefix length, and it has bit length of 8 bits.

Like strings, segments are immutable, which also makes them concurrency-safe.

See AddressSegment for more details regarding segments.

func NewIPv4PrefixedSegment 

func NewIPv4PrefixedSegment(val IPv4SegInt, prefixLen PrefixLen) *IPv4AddressSegment

NewIPv4PrefixedSegment constructs a segment of an IPv4 address with the given value and assigned prefix length.

func NewIPv4RangePrefixedSegment 

func NewIPv4RangePrefixedSegment(val, upperVal IPv4SegInt, prefixLen PrefixLen) *IPv4AddressSegment

NewIPv4RangePrefixedSegment constructs a segment of an IPv4 subnet with the given range of sequential values and assigned prefix length.

func NewIPv4RangeSegment 

func NewIPv4RangeSegment(val, upperVal IPv4SegInt) *IPv4AddressSegment

NewIPv4RangeSegment constructs a segment of an IPv4 subnet with the given range of sequential values.

func NewIPv4Segment 

func NewIPv4Segment(val IPv4SegInt) *IPv4AddressSegment

NewIPv4Segment constructs a segment of an IPv4 address with the given value.

func (*IPv4AddressSegment) Bytes 

func (seg *IPv4AddressSegment) Bytes() []byte

Bytes returns the lowest value in the address segment range as a byte slice.

func (*IPv4AddressSegment) Compare 

func (seg *IPv4AddressSegment) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address segment is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPv4AddressSegment) CompareSize added in v1.3.0 

func (seg *IPv4AddressSegment) CompareSize(other AddressItem) int

CompareSize compares the counts of two segments, the number of individual values within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one represents more individual values than another.

CompareSize returns a positive integer if this segment has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPv4AddressSegment) Contains 

func (seg *IPv4AddressSegment) Contains(other AddressSegmentType) bool

Contains returns whether this is same type and version as the given segment and whether it contains all values in the given segment.

func (*IPv4AddressSegment) ContainsPrefixBlock 

func (seg *IPv4AddressSegment) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the division range includes the block of values for the given prefix length.

func (*IPv4AddressSegment) ContainsSinglePrefixBlock 

func (seg *IPv4AddressSegment) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the segment range matches exactly the block of values for the given prefix length and has just a single prefix for that prefix length.

func (*IPv4AddressSegment) CopyBytes 

func (seg *IPv4AddressSegment) CopyBytes(bytes []byte) []byte

CopyBytes copies the lowest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4AddressSegment) CopyUpperBytes 

func (seg *IPv4AddressSegment) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the highest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4AddressSegment) Equal 

func (seg *IPv4AddressSegment) Equal(other AddressSegmentType) bool

Equal returns whether the given segment is equal to this segment. Two segments are equal if they match:

  • type/version: IPv4
  • value range

Prefix lengths are ignored.

func (IPv4AddressSegment) Format added in v1.5.4 

func (seg IPv4AddressSegment) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*IPv4AddressSegment) GetBitCount 

func (seg *IPv4AddressSegment) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item, which is 8.

func (*IPv4AddressSegment) GetBlockMaskPrefixLen 

func (seg *IPv4AddressSegment) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address segment is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is a segment with all ones in the network bits and then all zeros in the host bits. A CIDR host mask is a segment with all zeros in the network bits and then all ones in the host bits. The prefix length is the bit-length of the network bits.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this segment. The prefix length returned here indicates the whether the value of this segment can be used as a mask for the network and host bits of any other segment. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv4AddressSegment) GetByteCount 

func (seg *IPv4AddressSegment) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item, which is 1.

func (*IPv4AddressSegment) GetCount 

func (seg *IPv4AddressSegment) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1.

For instance, a segment with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv4AddressSegment) GetIPv4SegmentValue 

func (seg *IPv4AddressSegment) GetIPv4SegmentValue() IPv4SegInt

GetIPv4SegmentValue returns the lower value. Same as GetSegmentValue but returned as a IPv4SegInt.

func (*IPv4AddressSegment) GetIPv4UpperSegmentValue 

func (seg *IPv4AddressSegment) GetIPv4UpperSegmentValue() IPv4SegInt

GetIPv4UpperSegmentValue returns the lower value. Same as GetUpperSegmentValue but returned as a IPv4SegInt.

func (*IPv4AddressSegment) GetLeadingBitCount 

func (seg *IPv4AddressSegment) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv4AddressSegment) GetLower 

func (seg *IPv4AddressSegment) GetLower() *IPv4AddressSegment

GetLower returns a segment representing just the lowest value in the range, which will be the same segment if it represents a single value.

func (*IPv4AddressSegment) GetMaxValue 

func (seg *IPv4AddressSegment) GetMaxValue() IPv4SegInt

GetMaxValue gets the maximum possible value for this type or version of segment, determined by the number of bits.

For the highest range value of this particular segment, use GetUpperSegmentValue.

func (*IPv4AddressSegment) GetMinPrefixLenForBlock 

func (seg *IPv4AddressSegment) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this segment includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this segment represents a single value, this returns the bit count.

func (*IPv4AddressSegment) GetPrefixCountLen 

func (seg *IPv4AddressSegment) GetPrefixCountLen(segmentPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct prefix values for the given prefix length in the range of values of this segment.

func (*IPv4AddressSegment) GetPrefixLenForSingleBlock 

func (seg *IPv4AddressSegment) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this segment, and the range of values in this segment matches the block of all values for that prefix.

If the range of segment values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this segment represents a single value, this returns the bit count of the segment.

func (*IPv4AddressSegment) GetPrefixValueCount 

func (seg *IPv4AddressSegment) GetPrefixValueCount() SegIntCount

GetPrefixValueCount returns the count of prefixes in this segment for its prefix length, or the total count if it has no prefix length.

func (*IPv4AddressSegment) GetPrefixValueCountLen 

func (seg *IPv4AddressSegment) GetPrefixValueCountLen(segmentPrefixLength BitCount) SegIntCount

GetPrefixValueCountLen returns the same value as GetPrefixCountLen as an integer.

func (*IPv4AddressSegment) GetSegmentPrefixLen 

func (seg *IPv4AddressSegment) GetSegmentPrefixLen() PrefixLen

GetSegmentPrefixLen returns the network prefix for the segment.

The network prefix is 16 for an address like "1.2.0.0/16".

When it comes to each address division or segment, the prefix for the division is the prefix obtained when applying the address or section prefix.

For instance, consider the address "1.2.0.0/20". The first segment has no prefix because the address prefix 20 extends beyond the 8 bits in the first segment, it does not even apply to the segment. The second segment has no prefix because the address prefix extends beyond bits 9 to 16 which lie in the second segment, it does not apply to that segment either. The third segment has the prefix 4 because the address prefix 20 corresponds to the first 4 bits in the 3rd segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment has the prefix 0 because not a single bit is in the network section of the address or segment

The division prefixes applied across the address are: nil ... nil (1 to segment bit length) 0 ... 0.

If the segment has no prefix then nil is returned.

func (*IPv4AddressSegment) GetSegmentValue 

func (seg *IPv4AddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the segment value range.

func (*IPv4AddressSegment) GetString 

func (seg *IPv4AddressSegment) GetString() string

GetString produces a normalized string to represent the segment. If the segment is a CIDR network prefix block for its prefix length, then the string contains only the lower value of the block range. Otherwise, the explicit range will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPv4AddressSegment) GetTrailingBitCount 

func (seg *IPv4AddressSegment) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv4AddressSegment) GetUpper 

func (seg *IPv4AddressSegment) GetUpper() *IPv4AddressSegment

GetUpper returns a segment representing just the highest value in the range, which will be the same segment if it represents a single value.

func (*IPv4AddressSegment) GetUpperSegmentValue 

func (seg *IPv4AddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the segment value range.

func (*IPv4AddressSegment) GetUpperValue 

func (seg *IPv4AddressSegment) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address segment range as a big integer.

func (*IPv4AddressSegment) GetValue 

func (seg *IPv4AddressSegment) GetValue() *BigDivInt

GetValue returns the lowest value in the address segment range as a big integer.

func (*IPv4AddressSegment) GetValueCount 

func (seg *IPv4AddressSegment) GetValueCount() SegIntCount

GetValueCount returns the same value as GetCount as an integer.

func (*IPv4AddressSegment) GetWildcardString 

func (seg *IPv4AddressSegment) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters while ignoring any network prefix length. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPv4AddressSegment) IncludesMax 

func (seg *IPv4AddressSegment) IncludesMax() bool

IncludesMax returns whether this segment includes the max value, the value whose bits are all ones, within its range.

func (*IPv4AddressSegment) IncludesZero 

func (seg *IPv4AddressSegment) IncludesZero() bool

IncludesZero returns whether this segment includes the value of zero within its range.

func (*IPv4AddressSegment) IsFullRange 

func (seg *IPv4AddressSegment) IsFullRange() bool

IsFullRange returns whether the segment range includes all possible values for its bit length.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv4AddressSegment) IsMax 

func (seg *IPv4AddressSegment) IsMax() bool

IsMax returns whether this segment matches exactly the maximum possible value, the value whose bits are all ones.

func (*IPv4AddressSegment) IsMultiple 

func (seg *IPv4AddressSegment) IsMultiple() bool

IsMultiple returns whether this segment represents multiple values.

func (*IPv4AddressSegment) IsOneBit 

func (seg *IPv4AddressSegment) IsOneBit(segmentBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 is the most significant bit.

func (*IPv4AddressSegment) IsPrefixBlock 

func (seg *IPv4AddressSegment) IsPrefixBlock() bool

IsPrefixBlock returns whether the segment has a prefix length and the segment range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

func (*IPv4AddressSegment) IsPrefixed 

func (seg *IPv4AddressSegment) IsPrefixed() bool

IsPrefixed returns whether this segment has an associated prefix length.

func (*IPv4AddressSegment) IsSinglePrefix 

func (seg *IPv4AddressSegment) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix determines if the segment has a single prefix value for the given prefix length. You can call GetPrefixCountLen to get the count of prefixes.

func (*IPv4AddressSegment) IsSinglePrefixBlock 

func (seg *IPv4AddressSegment) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPv4AddressSegment) IsZero 

func (seg *IPv4AddressSegment) IsZero() bool

IsZero returns whether this segment matches exactly the value of zero.

func (*IPv4AddressSegment) Iterator 

func (seg *IPv4AddressSegment) Iterator() Iterator[*IPv4AddressSegment]

Iterator provides an iterator to iterate through the individual address segments of this address segment.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address segments.

Call IsMultiple to determine if this instance represents multiple address segments, or GetValueCount for the count.

func (*IPv4AddressSegment) Join 

func (seg *IPv4AddressSegment) Join(low *IPv4AddressSegment) (*IPv6AddressSegment, addrerr.IncompatibleAddressError)

Join joins this segment with another IPv4 segment to produce an IPv6 segment.

func (*IPv4AddressSegment) Matches 

func (seg *IPv4AddressSegment) Matches(value SegInt) bool

Matches returns true if the segment range matches the given single value.

func (*IPv4AddressSegment) MatchesValsWithMask 

func (seg *IPv4AddressSegment) MatchesValsWithMask(lowerValue, upperValue, mask SegInt) bool

MatchesValsWithMask applies the mask to this segment and then compares the result with the given values, returning true if the range of the resulting segment matches the given range.

func (*IPv4AddressSegment) MatchesWithMask 

func (seg *IPv4AddressSegment) MatchesWithMask(value, mask SegInt) bool

MatchesWithMask applies the mask to this segment and then compares the result with the given value, returning true if the range of the resulting segment matches that single value.

func (*IPv4AddressSegment) MatchesWithPrefixMask 

func (seg *IPv4AddressSegment) MatchesWithPrefixMask(value IPv4SegInt, networkBits BitCount) bool

MatchesWithPrefixMask applies the network mask of the given bit-length to this segment and then compares the result with the given value masked by the same mask, returning true if the resulting range matches the given single value.

func (*IPv4AddressSegment) PrefixBlockIterator 

func (seg *IPv4AddressSegment) PrefixBlockIterator() Iterator[*IPv4AddressSegment]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address segment. Each iterated address segment will be a prefix block with the same prefix length as this address segment.

If this address segment has no prefix length, then this is equivalent to Iterator.

func (*IPv4AddressSegment) PrefixContains 

func (seg *IPv4AddressSegment) PrefixContains(other AddressSegmentType, prefixLength BitCount) bool

PrefixContains returns whether the prefix values in the prefix of the given segment are also prefix values in this segment. It returns whether the prefix of this segment contains the prefix of the given segment.

func (*IPv4AddressSegment) PrefixEqual 

func (seg *IPv4AddressSegment) PrefixEqual(other AddressSegmentType, prefixLength BitCount) bool

PrefixEqual returns whether the prefix bits of this segment match the same bits of the given segment. It returns whether the two segments share the same range of prefix values using the given prefix length.

func (*IPv4AddressSegment) PrefixIterator 

func (seg *IPv4AddressSegment) PrefixIterator() Iterator[*IPv4AddressSegment]

PrefixIterator provides an iterator to iterate through the individual prefixes of this segment, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this segment.

If this address segment has no prefix length, then this is equivalent to Iterator.

func (*IPv4AddressSegment) PrefixedBlockIterator 

func (seg *IPv4AddressSegment) PrefixedBlockIterator(segmentPrefixLen BitCount) Iterator[*IPv4AddressSegment]

PrefixedBlockIterator provides an iterator to iterate through the individual prefix blocks of the given prefix length in this segment, one for each prefix of this address or subnet.

It is similar to PrefixBlockIterator except that this method allows you to specify the prefix length.

func (*IPv4AddressSegment) ReverseBits 

func (seg *IPv4AddressSegment) ReverseBits(_ bool) (res *IPv4AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBits returns a segment with the bits reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv4AddressSegment) ReverseBytes 

func (seg *IPv4AddressSegment) ReverseBytes() (*IPv4AddressSegment, addrerr.IncompatibleAddressError)

ReverseBytes returns a segment with the bytes reversed, which for an IPv4 segment is always the original segment.

func (*IPv4AddressSegment) String 

func (seg *IPv4AddressSegment) String() string

String produces a string that is useful when a segment string is provided with no context. It uses the decimal radix. GetWildcardString is more appropriate in context with other segments or divisions. It does not use a string prefix and uses '*' for full-range segments. GetString is more appropriate in context with prefix lengths, it uses zeros instead of wildcards with full prefix block ranges alongside prefix lengths.

func (*IPv4AddressSegment) TestBit 

func (seg *IPv4AddressSegment) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv4AddressSegment) ToDiv 

func (seg *IPv4AddressSegment) ToDiv() *AddressDivision

ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions. Afterwards, you can convert back with ToIPv4.

ToDiv can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSegment) ToHexString 

func (seg *IPv4AddressSegment) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address segment as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

For segments, the error is always nil.

func (*IPv4AddressSegment) ToHostSegment 

func (seg *IPv4AddressSegment) ToHostSegment(segmentPrefixLength PrefixLen) *IPv4AddressSegment

ToHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will have no assigned prefix length.

func (*IPv4AddressSegment) ToIP 

func (seg *IPv4AddressSegment) ToIP() *IPAddressSegment

ToIP converts to an IPAddressSegment, a polymorphic type usable with all IP address segments. Afterwards, you can convert back with ToIPv4.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSegment) ToNetworkSegment 

func (seg *IPv4AddressSegment) ToNetworkSegment(segmentPrefixLength PrefixLen) *IPv4AddressSegment

ToNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will have no assigned prefix length.

func (*IPv4AddressSegment) ToNormalizedString 

func (seg *IPv4AddressSegment) ToNormalizedString() string

ToNormalizedString produces a string that is consistent for all address segments of the same type and version. IPv4 segments use base 10, while IPv6 segments use base 16.

func (*IPv4AddressSegment) ToPrefixedHostSegment 

func (seg *IPv4AddressSegment) ToPrefixedHostSegment(segmentPrefixLength PrefixLen) *IPv4AddressSegment

ToPrefixedHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPv4AddressSegment) ToPrefixedNetworkSegment 

func (seg *IPv4AddressSegment) ToPrefixedNetworkSegment(segmentPrefixLength PrefixLen) *IPv4AddressSegment

ToPrefixedNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPv4AddressSegment) ToSegmentBase 

func (seg *IPv4AddressSegment) ToSegmentBase() *AddressSegment

ToSegmentBase converts to an AddressSegment, a polymorphic type usable with all address segments. Afterwards, you can convert back with ToIPv4.

ToSegmentBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSegment) UpperBytes 

func (seg *IPv4AddressSegment) UpperBytes() []byte

UpperBytes returns the highest value in the address segment range as a byte slice.

func (*IPv4AddressSegment) WithoutPrefixLen 

func (seg *IPv4AddressSegment) WithoutPrefixLen() *IPv4AddressSegment

WithoutPrefixLen returns a segment with the same value range but without a prefix length.

type IPv4AddressSegmentSeries 

type IPv4AddressSegmentSeries interface {
	IPAddressSegmentSeries

	// GetTrailingSection returns an ending subsection of the full address section.
	GetTrailingSection(index int) *IPv4AddressSection

	// GetSubSection returns a subsection of the full address section.
	GetSubSection(index, endIndex int) *IPv4AddressSection

	// GetNetworkSection returns an address section containing the segments with the network of the series, the prefix bits.
	// The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.
	//
	// If this series has no CIDR prefix length, the returned network section will
	// be the entire series as a prefixed section with prefix length matching the address bit length.
	GetNetworkSection() *IPv4AddressSection

	// GetHostSection returns a section containing the segments with the host of the series, the bits beyond the CIDR network prefix length.
	// The returned section will have only as many segments as needed to contain the host.
	//
	// If this series has no prefix length, the returned host section will be the full section.
	GetHostSection() *IPv4AddressSection

	// GetNetworkSectionLen returns a section containing the segments with the network of the series, the prefix bits according to the given prefix length.
	// The returned section will have only as many segments as needed to contain the network.
	//
	// The new section will be assigned the given prefix length,
	// unless the existing prefix length is smaller, in which case the existing prefix length will be retained.
	GetNetworkSectionLen(BitCount) *IPv4AddressSection

	// GetHostSectionLen returns a section containing the segments with the host of the series, the bits beyond the given CIDR network prefix length.
	// The returned section will have only as many segments as needed to contain the host.
	GetHostSectionLen(BitCount) *IPv4AddressSection

	// GetSegments returns a slice with the address segments.  The returned slice is not backed by the same array as the receiver.
	GetSegments() []*IPv4AddressSegment

	// CopySegments copies the existing segments into the given slice,
	// as much as can be fit into the slice, returning the number of segments copied.
	CopySegments(segs []*IPv4AddressSegment) (count int)

	// CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index,
	// into the given slice, as much as can be fit into the slice, returning the number of segments copied.
	CopySubSegments(start, end int, segs []*IPv4AddressSegment) (count int)

	// GetSegment returns the segment at the given index.
	// The first segment is at index 0.
	// GetSegment will panic given a negative index or an index matching or larger than the segment count.
	GetSegment(index int) *IPv4AddressSegment
}

IPv4AddressSegmentSeries serves as a common interface to all IPv4 address sections and IPv4 addresses.

type IPv4AddressSeqRange 

type IPv4AddressSeqRange = SequentialRange[*IPv4Address]

type IPv4AddressSeqRangeKey added in v1.1.0 

type IPv4AddressSeqRangeKey = SequentialRangeKey[*IPv4Address]

type IPv4AddressTrie added in v1.1.0 

type IPv4AddressTrie = Trie[*IPv4Address]

type IPv4PrefixBlockAllocator added in v1.4.0 

type IPv4PrefixBlockAllocator = PrefixBlockAllocator[*IPv4Address]

type IPv4SegInt 

type IPv4SegInt = uint8

type IPv4SegmentValueProvider 

type IPv4SegmentValueProvider func(segmentIndex int) IPv4SegInt

func WrapSegmentValueProviderForIPv4 added in v1.5.0 

func WrapSegmentValueProviderForIPv4(f SegmentValueProvider) IPv4SegmentValueProvider

WrapSegmentValueProviderForIPv4 converts the given SegmentValueProvider to an IPv4SegmentValueProvider. Values that do not fit IPv4SegInt are truncated.

type IPv6Address 

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

IPv6Address is an IPv6 address, or a subnet of multiple IPv6 addresses. An IPv6 address is composed of 8 2-byte segments and can optionally have an associated prefix length. Each segment can represent a single value or a range of values. The zero value is "::".

To construct one from a string, use NewIPAddressString, then use the ToAddress or GetAddress method of IPAddressString, and then use ToIPv6 to get an IPv6Address, assuming the string had an IPv6 format.

For other inputs, use one of the multiple constructor functions like NewIPv6Address. You can also use one of the multiple constructors for IPAddress like NewIPAddress and then convert using ToIPv6.

func NewIPv6Address 

func NewIPv6Address(section *IPv6AddressSection) (*IPv6Address, addrerr.AddressValueError)

NewIPv6Address constructs an IPv6 address or subnet from the given address section. If the section does not have 8 segments, an error is returned.

func NewIPv6AddressFromBytes 

func NewIPv6AddressFromBytes(bytes []byte) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromBytes constructs an IPv6 address from the given byte slice. An error is returned when the byte slice has too many bytes to match the IPv6 segment count of 8. There should be 16 bytes or less, although extra leading zeros are tolerated.

func NewIPv6AddressFromInt 

func NewIPv6AddressFromInt(val *big.Int) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromInt constructs an IPv6 address from the given value. An error is returned when the values is negative or too large.

func NewIPv6AddressFromMAC 

func NewIPv6AddressFromMAC(prefix *IPv6Address, suffix *MACAddress) (*IPv6Address, addrerr.IncompatibleAddressError)

NewIPv6AddressFromMAC constructs an IPv6 address from a modified EUI-64 (Extended Unique Identifier) MAC address and an IPv6 address 64-bit prefix.

If the supplied MAC address section is an 8-byte EUI-64, then it must match the required EUI-64 format of "xx-xx-ff-fe-xx-xx" with the "ff-fe" section in the middle.

If the supplied MAC address section is a 6-byte MAC-48 or EUI-48, then the "ff-fe" pattern will be inserted when converting to IPv6.

The constructor will toggle the MAC U/L (universal/local) bit as required with EUI-64.

The IPv6 address section must be at least 8 bytes. If it has a zone, then the resulting address will have the same zone.

Any prefix length in the MAC address is ignored, while a prefix length in the IPv6 address is preserved but only up to the first 4 segments.

The error is either an AddressValueError for sections that are of insufficient segment count, or IncompatibleAddressError when attempting to join two MAC segments, at least one with ranged values, into an equivalent IPV6 segment range.

func NewIPv6AddressFromMACSection 

func NewIPv6AddressFromMACSection(prefix *IPv6AddressSection, suffix *MACAddressSection) (*IPv6Address, addrerr.AddressError)

NewIPv6AddressFromMACSection constructs an IPv6 address from a modified EUI-64 (Extended Unique Identifier) MAC address section and an IPv6 address section network prefix.

If the supplied MAC address section is an 8-byte EUI-64, then it must match the required EUI-64 format of "xx-xx-ff-fe-xx-xx" with the "ff-fe" section in the middle.

If the supplied MAC address section is a 6-byte MAC-48 or EUI-48, then the "ff-fe" pattern will be inserted when converting to IPv6.

The constructor will toggle the MAC U/L (universal/local) bit as required with EUI-64.

The IPv6 address section must be at least 8 bytes (4 segments) in length.

Any prefix length in the MAC address is ignored, while a prefix length in the IPv6 address is preserved but only up to the first 4 segments.

The error is either an AddressValueError for sections that are of insufficient segment count, or IncompatibleAddressError when unable to join two MAC segments, at least one with ranged values, into an equivalent IPV6 segment range.

func NewIPv6AddressFromPrefixedBytes 

func NewIPv6AddressFromPrefixedBytes(bytes []byte, prefixLength PrefixLen) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedBytes constructs an IPv6 address from the given byte slice and prefix length. An error is returned when the byte slice has too many bytes to match the IPv6 segment count of 8. There should be 16 bytes or less, although extra leading zeros are tolerated. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromPrefixedInt 

func NewIPv6AddressFromPrefixedInt(val *big.Int, prefixLength PrefixLen) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedInt constructs an IPv6 address from the given value and prefix length. An error is returned when the values is negative or too large. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromPrefixedRange 

func NewIPv6AddressFromPrefixedRange(vals, upperVals IPv6SegmentValueProvider, prefixLength PrefixLen) *IPv6Address

NewIPv6AddressFromPrefixedRange constructs an IPv6 subnet from the given values and prefix length. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromPrefixedSegs 

func NewIPv6AddressFromPrefixedSegs(segments []*IPv6AddressSegment, prefixLength PrefixLen) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedSegs constructs an IPv6 address or subnet from the given segments and prefix length. If the given slice does not have 8 segments, an error is returned. If the address has a zero host for its prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromPrefixedUint64 

func NewIPv6AddressFromPrefixedUint64(highBytes, lowBytes uint64, prefixLength PrefixLen) *IPv6Address

NewIPv6AddressFromPrefixedUint64 constructs an IPv6 address or prefix block from the given values and prefix length. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromPrefixedVals 

func NewIPv6AddressFromPrefixedVals(vals IPv6SegmentValueProvider, prefixLength PrefixLen) *IPv6Address

NewIPv6AddressFromPrefixedVals constructs an IPv6 address or prefix block from the given values and prefix length. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromPrefixedZonedBytes 

func NewIPv6AddressFromPrefixedZonedBytes(bytes []byte, prefixLength PrefixLen, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedZonedBytes constructs an IPv6 address from the given byte slice, prefix length, and zone. An error is returned when the byte slice has too many bytes to match the IPv6 segment count of 8. There should be 16 bytes or less, although extra leading zeros are tolerated. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromPrefixedZonedInt 

func NewIPv6AddressFromPrefixedZonedInt(val *big.Int, prefixLength PrefixLen, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedZonedInt constructs an IPv6 address from the given value, prefix length, and zone. An error is returned when the values is negative or too large. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromPrefixedZonedRange 

func NewIPv6AddressFromPrefixedZonedRange(vals, upperVals IPv6SegmentValueProvider, prefixLength PrefixLen, zone string) *IPv6Address

NewIPv6AddressFromPrefixedZonedRange constructs an IPv6 subnet from the given values, prefix length, and zone. If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromPrefixedZonedSegs 

func NewIPv6AddressFromPrefixedZonedSegs(segments []*IPv6AddressSegment, prefixLength PrefixLen, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedZonedSegs constructs an IPv6 address or subnet from the given segments, prefix length, and zone. If the given slice does not have 8 segments, an error is returned. If the address has a zero host for its prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromPrefixedZonedUint64 

func NewIPv6AddressFromPrefixedZonedUint64(highBytes, lowBytes uint64, prefixLength PrefixLen, zone string) *IPv6Address

NewIPv6AddressFromPrefixedZonedUint64 constructs an IPv6 address or prefix block from the given values, prefix length, and zone If the address has a zero host for the given prefix length, the returned address will be the prefix block.

func NewIPv6AddressFromRange 

func NewIPv6AddressFromRange(vals, upperVals IPv6SegmentValueProvider) *IPv6Address

NewIPv6AddressFromRange constructs an IPv6 subnet from the given values.

func NewIPv6AddressFromSegs 

func NewIPv6AddressFromSegs(segments []*IPv6AddressSegment) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromSegs constructs an IPv6 address or subnet from the given segments. If the given slice does not have 8 segments, an error is returned.

func NewIPv6AddressFromUint64 

func NewIPv6AddressFromUint64(highBytes, lowBytes uint64) *IPv6Address

NewIPv6AddressFromUint64 constructs an IPv6 address from the given values.

func NewIPv6AddressFromVals 

func NewIPv6AddressFromVals(vals IPv6SegmentValueProvider) *IPv6Address

NewIPv6AddressFromVals constructs an IPv6 address from the given values.

func NewIPv6AddressFromZonedBytes 

func NewIPv6AddressFromZonedBytes(bytes []byte, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromZonedBytes constructs an IPv6 address from the given byte slice and zone. An error is returned when the byte slice has too many bytes to match the IPv6 segment count of 8. There should be 16 bytes or less, although extra leading zeros are tolerated.

func NewIPv6AddressFromZonedInt 

func NewIPv6AddressFromZonedInt(val *big.Int, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromZonedInt constructs an IPv6 address from the given value and zone. An error is returned when the values is negative or too large.

func NewIPv6AddressFromZonedMACSection added in v1.2.0 

func NewIPv6AddressFromZonedMACSection(prefix *IPv6AddressSection, suffix *MACAddressSection, zone string) (*IPv6Address, addrerr.AddressError)

NewIPv6AddressFromZonedMACSection constructs an IPv6 address from a modified EUI-64 (Extended Unique Identifier) MAC address section, an IPv6 address section network prefix, and a zone.

It is similar to NewIPv6AddressFromMACSection but also allows you to specify a zone.

It is similar to NewIPv6AddressFromMAC, which can supply a zone with the IPv6Address argument.

func NewIPv6AddressFromZonedRange 

func NewIPv6AddressFromZonedRange(vals, upperVals IPv6SegmentValueProvider, zone string) *IPv6Address

NewIPv6AddressFromZonedRange constructs an IPv6 subnet from the given values and zone.

func NewIPv6AddressFromZonedSegs 

func NewIPv6AddressFromZonedSegs(segments []*IPv6AddressSegment, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromZonedSegs constructs an IPv6 address or subnet from the given segments and zone. If the given slice does not have 8 segments, an error is returned.

func NewIPv6AddressFromZonedUint64 

func NewIPv6AddressFromZonedUint64(highBytes, lowBytes uint64, zone string) *IPv6Address

NewIPv6AddressFromZonedUint64 constructs an IPv6 address from the given values and zone.

func NewIPv6AddressZoned 

func NewIPv6AddressZoned(section *IPv6AddressSection, zone string) (*IPv6Address, addrerr.AddressValueError)

NewIPv6AddressZoned constructs an IPv6 address or subnet from the given address section and zone. If the section does not have 8 segments, an error is returned.

func (*IPv6Address) AdjustPrefixLen 

func (addr *IPv6Address) AdjustPrefixLen(prefixLen BitCount) *IPv6Address

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*IPv6Address) AdjustPrefixLenZeroed 

func (addr *IPv6Address) AdjustPrefixLenZeroed(prefixLen BitCount) (*IPv6Address, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv6Address) AssignMinPrefixForBlock 

func (addr *IPv6Address) AssignMinPrefixForBlock() *IPv6Address

AssignMinPrefixForBlock returns an equivalent subnet, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this subnet.

In other words, this method assigns a prefix length to this subnet matching the largest prefix block in this subnet.

func (*IPv6Address) AssignPrefixForSingleBlock 

func (addr *IPv6Address) AssignPrefixForSingleBlock() *IPv6Address

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address - it is required that the range of values match the range of a prefix block. If there is no such address, then nil is returned.

func (*IPv6Address) BitwiseOr 

func (addr *IPv6Address) BitwiseOr(other *IPv6Address) (masked *IPv6Address, err addrerr.IncompatibleAddressError)

BitwiseOr does the bitwise disjunction with this address or subnet, useful when subnetting. It is similar to Mask which does the bitwise conjunction.

The operation is applied to all individual addresses and the result is returned.

If this is a subnet representing multiple addresses, and applying the operation to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned.

func (*IPv6Address) BlockIterator 

func (addr *IPv6Address) BlockIterator(segmentCount int) Iterator[*IPv6Address]

BlockIterator iterates through the addresses that can be obtained by iterating through all the upper segments up to the given segment count. The segments following remain the same in all iterated addresses.

func (*IPv6Address) Bytes 

func (addr *IPv6Address) Bytes() []byte

Bytes returns the lowest address in this subnet or address as a byte slice.

func (*IPv6Address) Compare 

func (addr *IPv6Address) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address or subnet is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPv6Address) CompareSize 

func (addr *IPv6Address) CompareSize(other AddressItem) int

CompareSize compares the counts of two subnets or addresses or items, the number of individual addresses or items within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether this subnet represents more individual addresses or items than another.

CompareSize returns a positive integer if this address or subnet has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPv6Address) Contains 

func (addr *IPv6Address) Contains(other AddressType) bool

Contains returns whether this is the same type and version as the given address or subnet and whether it contains all addresses in the given address or subnet.

func (*IPv6Address) ContainsPrefixBlock 

func (addr *IPv6Address) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or subnet contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPv6Address) ContainsSinglePrefixBlock 

func (addr *IPv6Address) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPv6Address) CopyBytes 

func (addr *IPv6Address) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address in the subnet into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6Address) CopyNetIP 

func (addr *IPv6Address) CopyNetIP(bytes net.IP) net.IP

CopyNetIP copies the value of the lowest individual address in the subnet into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6Address) CopySegments 

func (addr *IPv6Address) CopySegments(segs []*IPv6AddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPv6Address) CopySubSegments 

func (addr *IPv6Address) CopySubSegments(start, end int, segs []*IPv6AddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPv6Address) CopyUpperBytes 

func (addr *IPv6Address) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address in the subnet into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6Address) CopyUpperNetIP 

func (addr *IPv6Address) CopyUpperNetIP(bytes net.IP) net.IP

CopyUpperNetIP copies the value of the highest individual address in the subnet into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6Address) CoverWithPrefixBlock 

func (addr *IPv6Address) CoverWithPrefixBlock() *IPv6Address

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the addresses in this subnet. The resulting block will have a larger subnet size than this, unless this subnet is already a prefix block.

func (*IPv6Address) CoverWithPrefixBlockTo 

func (addr *IPv6Address) CoverWithPrefixBlockTo(other *IPv6Address) *IPv6Address

CoverWithPrefixBlockTo returns the minimal-size prefix block that covers all the addresses spanning from this subnet to the given subnet.

func (*IPv6Address) Equal 

func (addr *IPv6Address) Equal(other AddressType) bool

Equal returns whether the given address or subnet is equal to this address or subnet. Two address instances are equal if they represent the same set of addresses.

func (*IPv6Address) ForEachSegment added in v1.2.0 

func (addr *IPv6Address) ForEachSegment(consumer func(segmentIndex int, segment *IPv6AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (IPv6Address) Format 

func (addr IPv6Address) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*IPv6Address) Get6To4IPv4Address 

func (addr *IPv6Address) Get6To4IPv4Address() (*IPv4Address, addrerr.IncompatibleAddressError)

Get6To4IPv4Address Returns the second and third segments as an IPv4Address.

func (*IPv6Address) GetBitCount 

func (addr *IPv6Address) GetBitCount() BitCount

GetBitCount returns the number of bits comprising this address, or each address in the range if a subnet, which is 128.

func (*IPv6Address) GetBitsPerSegment 

func (addr *IPv6Address) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this address. Segments in the same address are equal length.

func (*IPv6Address) GetBlockCount 

func (addr *IPv6Address) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*IPv6Address) GetBlockMaskPrefixLen 

func (addr *IPv6Address) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address with all ones in the network section and then all zeros in the host section. A CIDR host mask is an address with all zeros in the network section and then all ones in the host section. The prefix length is the bit-length of the network section.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this instance, indicating the network and host section of this address. The prefix length returned here indicates the whether the value of this address can be used as a mask for the network and host section of any other address. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this address represents multiple values.

func (*IPv6Address) GetByteCount 

func (addr *IPv6Address) GetByteCount() int

GetByteCount returns the number of bytes required for this address, or each address in the range if a subnet, which is 16.

func (*IPv6Address) GetBytesPerSegment 

func (addr *IPv6Address) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this address or subnet. Segments in the same address are equal length.

func (*IPv6Address) GetCount 

func (addr *IPv6Address) GetCount() *big.Int

GetCount returns the count of addresses that this address or subnet represents.

If just a single address, not a subnet of multiple addresses, returns 1.

For instance, the IP address subnet "2001:db8::/64" has the count of 2 to the power of 64.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv6Address) GetDivisionCount 

func (addr *IPv6Address) GetDivisionCount() int

GetDivisionCount returns the segment count.

func (*IPv6Address) GetEmbeddedIPv4Address 

func (addr *IPv6Address) GetEmbeddedIPv4Address() (*IPv4Address, addrerr.IncompatibleAddressError)

GetEmbeddedIPv4Address gets the IPv4 address corresponding to the lowest (least-significant) 2 segments (4 bytes) in this address. Many IPv4 to IPv6 mapping schemes (but not all) use these 4 bytes for a mapped IPv4 address. An error can result when one of the associated IPv6 segments has a range of values that cannot be split into two ranges.

func (*IPv6Address) GetEmbeddedIPv4AddressAt 

func (addr *IPv6Address) GetEmbeddedIPv4AddressAt(byteIndex int) (*IPv4Address, addrerr.IncompatibleAddressError)

GetEmbeddedIPv4AddressAt produces an IPv4 address corresponding to any sequence of 4 bytes in this IPv6 address, starting at the given index.

func (*IPv6Address) GetEmbeddedIPv4AddressSection 

func (addr *IPv6Address) GetEmbeddedIPv4AddressSection() (*IPv4AddressSection, addrerr.IncompatibleAddressError)

GetEmbeddedIPv4AddressSection gets the IPv4 section corresponding to the lowest (least-significant) 2 segments (4 bytes) in this address. Many IPv4 to IPv6 mapping schemes (but not all) use these 4 bytes for a mapped IPv4 address. An error can result when one of the associated IPv6 segments has a range of values that cannot be split into two ranges.

func (*IPv6Address) GetGenericDivision 

func (addr *IPv6Address) GetGenericDivision(index int) DivisionType

GetGenericDivision returns the segment at the given index as a DivisionType.

func (*IPv6Address) GetGenericSegment 

func (addr *IPv6Address) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPv6Address) GetHostMask 

func (addr *IPv6Address) GetHostMask() *IPv6Address

GetHostMask returns the host mask associated with the CIDR network prefix length of this address or subnet. If this address or subnet has no prefix length, then the all-ones mask is returned.

func (*IPv6Address) GetHostSection 

func (addr *IPv6Address) GetHostSection() *IPv6AddressSection

GetHostSection returns a section containing the segments with the host of the address or subnet, the bits beyond the CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

If this series has no prefix length, the returned host section will be the full section.

func (*IPv6Address) GetHostSectionLen 

func (addr *IPv6Address) GetHostSectionLen(prefLen BitCount) *IPv6AddressSection

GetHostSectionLen returns a section containing the segments with the host of the address or subnet, the bits beyond the given CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

func (*IPv6Address) GetIPVersion 

func (addr *IPv6Address) GetIPVersion() IPVersion

GetIPVersion returns IPv6, the IP version of this address.

func (*IPv6Address) GetIPv4AddressSection 

func (addr *IPv6Address) GetIPv4AddressSection(startIndex, endIndex int) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

GetIPv4AddressSection produces an IPv4 address section corresponding to any sequence of bytes in this IPv6 address section

func (*IPv6Address) GetIPv6Address 

func (addr *IPv6Address) GetIPv6Address(embedded IPv4Address) (*IPv6Address, addrerr.IncompatibleAddressError)

GetIPv6Address creates an IPv6 mixed address using the given address for the trailing embedded IPv4 segments

func (*IPv6Address) GetLeadingBitCount 

func (addr *IPv6Address) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower value of the range if this is a subnet representing multiple values.

func (*IPv6Address) GetLower 

func (addr *IPv6Address) GetLower() *IPv6Address

GetLower returns the lowest address in the subnet range, which will be the receiver if it represents a single address. For example, for "1::1:2-3:4:5-6", the series "1::1:2:4:5" is returned.

func (*IPv6Address) GetLowerIPAddress 

func (addr *IPv6Address) GetLowerIPAddress() *IPAddress

GetLowerIPAddress returns the address in the subnet or address collection with the lowest numeric value, which will be the receiver if it represents a single address. GetLowerIPAddress implements the IPAddressRange interface

func (*IPv6Address) GetMaxSegmentValue 

func (addr *IPv6Address) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPv6Address) GetMinPrefixLenForBlock 

func (addr *IPv6Address) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

func (*IPv6Address) GetMixedAddressGrouping 

func (addr *IPv6Address) GetMixedAddressGrouping() (*IPv6v4MixedAddressGrouping, addrerr.IncompatibleAddressError)

GetMixedAddressGrouping creates a grouping by combining an IPv6 address section comprising the first six segments (most significant) in this address with the IPv4 section corresponding to the lowest (least-significant) two segments in this address, as produced by GetEmbeddedIPv4Address.

func (*IPv6Address) GetNetIP 

func (addr *IPv6Address) GetNetIP() net.IP

GetNetIP returns the lowest address in this subnet or address as a net.IP.

func (*IPv6Address) GetNetIPAddr 

func (addr *IPv6Address) GetNetIPAddr() *net.IPAddr

GetNetIPAddr returns the lowest address in this subnet or address as a net.IPAddr.

func (*IPv6Address) GetNetNetIPAddr added in v1.5.0 

func (addr *IPv6Address) GetNetNetIPAddr() netip.Addr

GetNetNetIPAddr returns the lowest address in this subnet or address range as a netip.Addr.

func (*IPv6Address) GetNetwork 

func (addr *IPv6Address) GetNetwork() IPAddressNetwork

GetNetwork returns the singleton IPv6 network instance.

func (*IPv6Address) GetNetworkMask 

func (addr *IPv6Address) GetNetworkMask() *IPv6Address

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address or subnet. If this address or subnet has no prefix length, then the all-ones mask is returned.

func (*IPv6Address) GetNetworkPrefixLen 

func (addr *IPv6Address) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. GetNetworkPrefixLen is equivalent to the method GetPrefixLen.

func (*IPv6Address) GetNetworkSection 

func (addr *IPv6Address) GetNetworkSection() *IPv6AddressSection

GetNetworkSection returns an address section containing the segments with the network of the address or subnet, the prefix bits. The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.

If this series has no CIDR prefix length, the returned network section will be the entire series as a prefixed section with prefix length matching the address bit length.

func (*IPv6Address) GetNetworkSectionLen 

func (addr *IPv6Address) GetNetworkSectionLen(prefLen BitCount) *IPv6AddressSection

GetNetworkSectionLen returns a section containing the segments with the network of the address or subnet, the prefix bits according to the given prefix length. The returned section will have only as many segments as needed to contain the network.

The new section will be assigned the given prefix length, unless the existing prefix length is smaller, in which case the existing prefix length will be retained.

func (*IPv6Address) GetPrefixCount 

func (addr *IPv6Address) GetPrefixCount() *big.Int

GetPrefixCount returns the count of prefixes in this address or subnet.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the count of the range of values in the prefix.

If this has a nil prefix length, returns the same value as GetCount.

func (*IPv6Address) GetPrefixCountLen 

func (addr *IPv6Address) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the count of prefixes in this address or subnet for the given prefix length.

If not a subnet of multiple addresses, or a subnet with just single prefix of the given length, returns 1.

func (*IPv6Address) GetPrefixLen 

func (addr *IPv6Address) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part of the address that comprise the prefix.

A prefix is a part of the address that is not specific to that address but common amongst a group of addresses, such as a CIDR prefix block subnet.

For IP addresses, the prefix is explicitly defined when the address is created. For example, "1.2.0.0/16" has a prefix length of 16, while "1.2.*.*" has no prefix length, even though they both represent the same set of addresses and are considered equal. Prefixes can be considered variable for a given IP address and can depend on routing.

The methods GetMinPrefixLenForBlock and GetPrefixLenForSingleBlock can help you to obtain or define a prefix length if one does not exist already. The method ToPrefixBlockLen allows you to create the subnet consisting of the block of addresses for any given prefix length.

func (*IPv6Address) GetPrefixLenForSingleBlock 

func (addr *IPv6Address) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address subnet matches exactly the block of addresses for that prefix.

If the range can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix exists, returns nil.

If this segment grouping represents a single value, returns the bit length of this address division series.

func (*IPv6Address) GetSection 

func (addr *IPv6Address) GetSection() *IPv6AddressSection

GetSection returns the backing section for this address or subnet, comprising all segments.

func (*IPv6Address) GetSegment 

func (addr *IPv6Address) GetSegment(index int) *IPv6AddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPv6Address) GetSegmentCount 

func (addr *IPv6Address) GetSegmentCount() int

GetSegmentCount returns the segment count, the number of segments in this address, which is 8

func (*IPv6Address) GetSegmentStrings 

func (addr *IPv6Address) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*IPv6Address) GetSegments 

func (addr *IPv6Address) GetSegments() []*IPv6AddressSegment

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this address.

func (*IPv6Address) GetSequentialBlockCount 

func (addr *IPv6Address) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential subnets that comprise this subnet.

func (*IPv6Address) GetSequentialBlockIndex 

func (addr *IPv6Address) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full subnet to be sequential, the preceding segments must be single-valued.

func (*IPv6Address) GetSubSection 

func (addr *IPv6Address) GetSubSection(index, endIndex int) *IPv6AddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*IPv6Address) GetTrailingBitCount 

func (addr *IPv6Address) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies to the lower value of the range if this is a subnet representing multiple values.

func (*IPv6Address) GetTrailingSection 

func (addr *IPv6Address) GetTrailingSection(index int) *IPv6AddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*IPv6Address) GetUpper 

func (addr *IPv6Address) GetUpper() *IPv6Address

GetUpper returns the highest address in the subnet range, which will be the receiver if it represents a single address. For example, for "1::1:2-3:4:5-6", the series "1::1:3:4:6" is returned.

func (*IPv6Address) GetUpperIPAddress 

func (addr *IPv6Address) GetUpperIPAddress() *IPAddress

GetUpperIPAddress returns the address in the subnet or address collection with the highest numeric value, which will be the receiver if it represents a single address. GetUpperIPAddress implements the IPAddressRange interface

func (*IPv6Address) GetUpperNetIP 

func (addr *IPv6Address) GetUpperNetIP() net.IP

GetUpperNetIP returns the highest address in this subnet or address as a net.IP.

func (*IPv6Address) GetUpperNetIPAddr added in v1.2.0 

func (addr *IPv6Address) GetUpperNetIPAddr() *net.IPAddr

GetUpperNetIPAddr returns the highest address in this subnet or address as a net.IPAddr.

func (*IPv6Address) GetUpperNetNetIPAddr added in v1.5.0 

func (addr *IPv6Address) GetUpperNetNetIPAddr() netip.Addr

GetUpperNetNetIPAddr returns the highest address in this subnet or address range as a netip.Addr.

func (*IPv6Address) GetUpperValue 

func (addr *IPv6Address) GetUpperValue() *big.Int

GetUpperValue returns the highest address in this subnet or address as an integer value.

func (*IPv6Address) GetValue 

func (addr *IPv6Address) GetValue() *big.Int

GetValue returns the lowest address in this subnet or address as an integer value.

func (*IPv6Address) GetZone 

func (addr *IPv6Address) GetZone() Zone

GetZone returns the zone it it has one, otherwise it returns NoZone, which is an empty string.

func (*IPv6Address) HasZone 

func (addr *IPv6Address) HasZone() bool

HasZone returns whether this IPv6 address includes a zone or scope.

func (*IPv6Address) IncludesMax 

func (addr *IPv6Address) IncludesMax() bool

IncludesMax returns whether this address includes the max address, the address whose bits are all ones, within its range.

func (*IPv6Address) IncludesMaxHost 

func (addr *IPv6Address) IncludesMaxHost() bool

IncludesMaxHost returns whether the subnet contains an individual address with a host of all one-bits. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are one.

func (*IPv6Address) IncludesMaxHostLen 

func (addr *IPv6Address) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the subnet contains an individual address with a host of all one-bits, an individual address for which all bits past the given prefix length are all ones.

func (*IPv6Address) IncludesZeroHost 

func (addr *IPv6Address) IncludesZeroHost() bool

IncludesZeroHost returns whether the subnet contains an individual address with a host of zero. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are zero.

func (*IPv6Address) IncludesZeroHostLen 

func (addr *IPv6Address) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the subnet contains an individual address with a host of zero, an individual address for which all bits past the given prefix length are zero.

func (*IPv6Address) Increment 

func (addr *IPv6Address) Increment(increment int64) *IPv6Address

Increment returns the address from the subnet that is the given increment upwards into the subnet range, with the increment of 0 returning the first address in the range.

If the increment i matches or exceeds the subnet size count c, then i - c + 1 is added to the upper address of the range. An increment matching the subnet count gives you the address just above the highest address in the subnet.

If the increment is negative, it is added to the lower address of the range. To get the address just below the lowest address of the subnet, use the increment -1.

If this is just a single address value, the address is simply incremented by the given increment, positive or negative.

If this is a subnet with multiple values, a positive increment i is equivalent i + 1 values from the subnet iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the subnet count is equivalent to the same number of iterator values preceding the upper bound of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On address overflow or underflow, Increment returns nil.

func (*IPv6Address) IncrementBoundary 

func (addr *IPv6Address) IncrementBoundary(increment int64) *IPv6Address

IncrementBoundary returns the address that is the given increment from the range boundaries of this subnet.

If the given increment is positive, adds the value to the upper address (GetUpper) in the subnet range to produce a new address. If the given increment is negative, adds the value to the lower address (GetLower) in the subnet range to produce a new address. If the increment is zero, returns this address.

If this is a single address value, that address is simply incremented by the given increment value, positive or negative.

On address overflow or underflow, IncrementBoundary returns nil.

func (*IPv6Address) Intersect 

func (addr *IPv6Address) Intersect(other *IPv6Address) *IPv6Address

Intersect returns the subnet whose addresses are found in both this and the given subnet argument, or nil if no such addresses exist.

This is also known as the conjunction of the two sets of addresses.

func (*IPv6Address) Is6Over4 

func (addr *IPv6Address) Is6Over4() bool

Is6Over4 returns whether the address or all addresses in the subnet are 6over4.

func (*IPv6Address) Is6To4 

func (addr *IPv6Address) Is6To4() bool

Is6To4 returns whether the address or subnet is IPv6 to IPv4 relay.

func (*IPv6Address) IsAnyLocal 

func (addr *IPv6Address) IsAnyLocal() bool

IsAnyLocal returns whether this address is the address which binds to any address on the local host. This is the address that has the value of 0, aka the unspecified address.

func (*IPv6Address) IsEUI64 

func (addr *IPv6Address) IsEUI64() bool

IsEUI64 returns whether this address is consistent with EUI64, which means the 12th and 13th bytes of the address match 0xff and 0xfe.

func (*IPv6Address) IsFullRange added in v1.2.0 

func (addr *IPv6Address) IsFullRange() bool

IsFullRange returns whether this address covers the entire IPv6 address space.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv6Address) IsIPv4Compatible 

func (addr *IPv6Address) IsIPv4Compatible() bool

IsIPv4Compatible returns whether the address or all addresses in the subnet are IPv4-compatible.

func (*IPv6Address) IsIPv4Mapped 

func (addr *IPv6Address) IsIPv4Mapped() bool

IsIPv4Mapped returns whether the address or all addresses in the subnet are IPv4-mapped.

"::ffff:x:x/96" indicates an IPv6 address mapped to IPv4.

func (*IPv6Address) IsIPv4Translatable 

func (addr *IPv6Address) IsIPv4Translatable() bool

IsIPv4Translatable returns whether the address or subnet is IPv4 translatable as in RFC 2765.

func (*IPv6Address) IsIsatap 

func (addr *IPv6Address) IsIsatap() bool

IsIsatap returns whether the address or all addresses in the subnet are ISATAP.

func (*IPv6Address) IsLinkLocal 

func (addr *IPv6Address) IsLinkLocal() bool

IsLinkLocal returns whether the address is link local, whether unicast or multicast.

func (*IPv6Address) IsLocal 

func (addr *IPv6Address) IsLocal() bool

IsLocal returns true if the address is link local, site local, organization local, administered locally, or unspecified. This includes both unicast and multicast.

func (*IPv6Address) IsLoopback 

func (addr *IPv6Address) IsLoopback() bool

IsLoopback returns whether this address is a loopback address, namely "::1".

func (*IPv6Address) IsMax 

func (addr *IPv6Address) IsMax() bool

IsMax returns whether this address matches exactly the maximum possible value, the address whose bits are all ones.

func (*IPv6Address) IsMaxHost 

func (addr *IPv6Address) IsMaxHost() bool

IsMaxHost returns whether this section has a prefix length and if so, whether the host section is always all one-bits, the max value, for all individual addresses in this subnet.

If the host section is zero length (there are zero host bits), IsMaxHost returns true.

func (*IPv6Address) IsMaxHostLen 

func (addr *IPv6Address) IsMaxHostLen(prefLen BitCount) bool

IsMaxHostLen returns whether the host is all one-bits, the max value, for all individual addresses in this subnet, for the given prefix length, the host being the bits following the prefix.

If the host section is zero length (there are zero host bits), IsMaxHostLen returns true.

func (*IPv6Address) IsMulticast 

func (addr *IPv6Address) IsMulticast() bool

IsMulticast returns whether this address or subnet is entirely multicast.

func (*IPv6Address) IsMultiple 

func (addr *IPv6Address) IsMultiple() bool

IsMultiple returns true if this represents more than a single individual address, whether it is a subnet of multiple addresses.

func (*IPv6Address) IsOneBit 

func (addr *IPv6Address) IsOneBit(bitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*IPv6Address) IsPrefixBlock 

func (addr *IPv6Address) IsPrefixBlock() bool

IsPrefixBlock returns whether the address has a prefix length and the address range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

To create a prefix block from any address, use ToPrefixBlock.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*IPv6Address) IsPrefixed 

func (addr *IPv6Address) IsPrefixed() bool

IsPrefixed returns whether this address has an associated prefix length.

func (*IPv6Address) IsSingleNetwork 

func (addr *IPv6Address) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address.

func (*IPv6Address) IsSinglePrefixBlock 

func (addr *IPv6Address) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the address range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

For instance, "1.*.*.* /16" returns false from this method and returns true from IsPrefixBlock.

func (*IPv6Address) IsSiteLocal 

func (addr *IPv6Address) IsSiteLocal() bool

IsSiteLocal returns true if the address is site-local, or all addresses in the subnet are site-local, see rfc 3513, 3879, and 4291.

func (*IPv6Address) IsTeredo 

func (addr *IPv6Address) IsTeredo() bool

IsTeredo returns whether the address or all addresses in the subnet are Teredo.

func (*IPv6Address) IsUniqueLocal 

func (addr *IPv6Address) IsUniqueLocal() bool

IsUniqueLocal returns true if the address is unique-local, or all addresses in the subnet are unique-local, see RFC 4193.

func (*IPv6Address) IsUnspecified 

func (addr *IPv6Address) IsUnspecified() bool

IsUnspecified returns whether this is the unspecified address. The unspecified address is the address that is all zeros.

func (*IPv6Address) IsWellKnownIPv4Translatable 

func (addr *IPv6Address) IsWellKnownIPv4Translatable() bool

IsWellKnownIPv4Translatable returns whether the address has the well-known prefix for IPv4-translatable addresses as in RFC 6052 and RFC 6144.

func (*IPv6Address) IsZeroHost 

func (addr *IPv6Address) IsZeroHost() bool

IsZeroHost returns whether this subnet has a prefix length and if so, whether the host section is always zero for all individual addresses in this subnet.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (*IPv6Address) IsZeroHostLen 

func (addr *IPv6Address) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual addresses in this subnet, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (*IPv6Address) Iterator 

func (addr *IPv6Address) Iterator() Iterator[*IPv6Address]

Iterator provides an iterator to iterate through the individual addresses of this address or subnet.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual addresses.

Call IsMultiple to determine if this instance represents multiple addresses, or GetCount for the count.

func (*IPv6Address) Mask 

func (addr *IPv6Address) Mask(other *IPv6Address) (masked *IPv6Address, err addrerr.IncompatibleAddressError)

Mask applies the given mask to all addresses represented by this IPv6Address. The mask is applied to all individual addresses.

If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned.

func (*IPv6Address) MatchesWithMask 

func (addr *IPv6Address) MatchesWithMask(other *IPv6Address, mask *IPv6Address) bool

MatchesWithMask applies the mask to this address and then compares the result with the given address, returning true if they match, false otherwise.

func (*IPv6Address) MergeToPrefixBlocks 

func (addr *IPv6Address) MergeToPrefixBlocks(addrs ...*IPv6Address) []*IPv6Address

MergeToPrefixBlocks merges this subnet with the list of subnets to produce the smallest array of prefix blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv6Address) MergeToSequentialBlocks 

func (addr *IPv6Address) MergeToSequentialBlocks(addrs ...*IPv6Address) []*IPv6Address

MergeToSequentialBlocks merges this with the list of addresses to produce the smallest array of sequential blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv6Address) PrefixBlockIterator 

func (addr *IPv6Address) PrefixBlockIterator() Iterator[*IPv6Address]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address or subnet. Each iterated address or subnet will be a prefix block with the same prefix length as this address or subnet.

If this address has no prefix length, then this is equivalent to Iterator.

func (*IPv6Address) PrefixContains 

func (addr *IPv6Address) PrefixContains(other AddressType) bool

PrefixContains returns whether the prefix values in the given address or subnet are prefix values in this address or subnet, using the prefix length of this address or subnet. If this address has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

func (*IPv6Address) PrefixEqual 

func (addr *IPv6Address) PrefixEqual(other AddressType) bool

PrefixEqual determines if the given address matches this address up to the prefix length of this address. It returns whether the two addresses share the same range of prefix values.

func (*IPv6Address) PrefixIterator 

func (addr *IPv6Address) PrefixIterator() Iterator[*IPv6Address]

PrefixIterator provides an iterator to iterate through the individual prefixes of this subnet, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this subnet.

If the subnet has no prefix length, then this is equivalent to Iterator.

func (*IPv6Address) Replace 

func (addr *IPv6Address) Replace(startIndex int, replacement *IPv6AddressSection) *IPv6Address

Replace replaces segments starting from startIndex with segments from the replacement section.

func (*IPv6Address) ReplaceLen 

func (addr *IPv6Address) ReplaceLen(startIndex, endIndex int, replacement *IPv6Address, replacementIndex int) *IPv6Address

ReplaceLen replaces segments starting from startIndex and ending before endIndex with the same number of segments starting at replacementStartIndex from the replacement section. Mappings to or from indices outside the range of this or the replacement address are skipped.

func (*IPv6Address) ReverseBits 

func (addr *IPv6Address) ReverseBits(perByte bool) (*IPv6Address, addrerr.IncompatibleAddressError)

ReverseBits returns a new address with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv6Address) ReverseBytes 

func (addr *IPv6Address) ReverseBytes() (*IPv6Address, addrerr.IncompatibleAddressError)

ReverseBytes returns a new address with the bytes reversed. Any prefix length is dropped.

If the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (*IPv6Address) ReverseSegments 

func (addr *IPv6Address) ReverseSegments() *IPv6Address

ReverseSegments returns a new address with the segments reversed.

func (*IPv6Address) SequentialBlockIterator 

func (addr *IPv6Address) SequentialBlockIterator() Iterator[*IPv6Address]

SequentialBlockIterator iterates through the sequential subnets or addresses that make up this address or subnet.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

For instance, given the IPv4 subnet "1-2.3-4.5-6.7-8", it will iterate through "1.3.5.7-8", "1.3.6.7-8", "1.4.5.7-8", "1.4.6.7-8", "2.3.5.7-8", "2.3.6.7-8", "2.4.6.7-8" and "2.4.6.7-8".

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPv6Address) SetPrefixLen 

func (addr *IPv6Address) SetPrefixLen(prefixLen BitCount) *IPv6Address

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPv6Address) SetPrefixLenZeroed 

func (addr *IPv6Address) SetPrefixLenZeroed(prefixLen BitCount) (*IPv6Address, addrerr.IncompatibleAddressError)

func (*IPv6Address) SetZone 

func (addr *IPv6Address) SetZone(zone string) *IPv6Address

SetZone returns the same address associated with the given zone, The existing zone, if any, is replaced.

func (*IPv6Address) SpanWithPrefixBlocks 

func (addr *IPv6Address) SpanWithPrefixBlocks() []*IPv6Address

SpanWithPrefixBlocks returns an array of prefix blocks that cover the same set of addresses as this subnet.

Unlike SpanWithPrefixBlocksTo, the result only includes addresses that are a part of this subnet.

func (*IPv6Address) SpanWithPrefixBlocksTo 

func (addr *IPv6Address) SpanWithPrefixBlocksTo(other *IPv6Address) []*IPv6Address

SpanWithPrefixBlocksTo returns the smallest slice of prefix block subnets that span from this subnet to the given subnet.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

From the list of returned subnets you can recover the original range (from this to other) by converting each to SequentialRange with ToSequentialRange and them joining them into a single range with the Join method of SequentialRange.

func (*IPv6Address) SpanWithRange 

func (addr *IPv6Address) SpanWithRange(other *IPv6Address) *SequentialRange[*IPv6Address]

SpanWithRange returns an IPv6AddressSeqRange instance that spans this subnet to the given subnet. If the other address is a different version than this, then the other is ignored, and the result is equivalent to calling ToSequentialRange.

func (*IPv6Address) SpanWithSequentialBlocks 

func (addr *IPv6Address) SpanWithSequentialBlocks() []*IPv6Address

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of addresses as this subnet.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

Unlike SpanWithSequentialBlocksTo, this method only includes addresses that are a part of this subnet.

func (*IPv6Address) SpanWithSequentialBlocksTo 

func (addr *IPv6Address) SpanWithSequentialBlocksTo(other *IPv6Address) []*IPv6Address

SpanWithSequentialBlocksTo produces the smallest slice of sequential block subnets that span all values from this subnet to the given subnet. The span will cover all addresses in both subnets and everything in between.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv6Address) String 

func (addr *IPv6Address) String() string

String implements the fmt.Stringer interface, returning the canonical string provided by ToCanonicalString, or "<nil>" if the receiver is a nil pointer.

func (*IPv6Address) Subtract 

func (addr *IPv6Address) Subtract(other *IPv6Address) []*IPv6Address

Subtract subtracts the given subnet from this subnet, returning an array of subnets for the result (the subnets will not be contiguous so an array is required). Subtract computes the subnet difference, the set of addresses in this address subnet but not in the provided subnet. This is also known as the relative complement of the given argument in this subnet. This is set subtraction, not subtraction of address values (use Increment for the latter). We have a subnet of addresses and we are removing those addresses found in the argument subnet. If there are no remaining addresses, nil is returned.

func (*IPv6Address) TestBit 

func (addr *IPv6Address) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this address. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv6Address) ToAddressBase 

func (addr *IPv6Address) ToAddressBase() *Address

ToAddressBase converts to an Address, a polymorphic type usable with all addresses and subnets. Afterwards, you can convert back with ToIPv6.

ToAddressBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6Address) ToAddressString 

func (addr *IPv6Address) ToAddressString() *IPAddressString

ToAddressString retrieves or generates an IPAddressString instance for this IPAddress instance. This may be the IPAddressString this instance was generated from, if it was generated from an IPAddressString.

In general, users are intended to create IPAddress instances from IPAddressString instances, while the reverse direction is generally not common and not useful, except under specific circumstances.

However, the reverse direction can be useful under certain circumstances, such as when maintaining a collection of HostIdentifierString instances.

func (*IPv6Address) ToBase85String added in v1.3.0 

func (addr *IPv6Address) ToBase85String() (string, addrerr.IncompatibleAddressError)

ToBase85String creates the base 85 string, which is described by RFC 1924, "A Compact Representation of IPv6 Addresses". See https://www.rfc-editor.org/rfc/rfc1924.html

It may be written as a range of two values if a range that is not a prefixed block.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6Address) ToBinaryString 

func (addr *IPv6Address) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6Address) ToBlock 

func (addr *IPv6Address) ToBlock(segmentIndex int, lower, upper SegInt) *IPv6Address

ToBlock creates a new block of addresses by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPv6Address) ToCanonicalString 

func (addr *IPv6Address) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address.

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

Each address has a unique canonical string, not counting the prefix length. With IP addresses, the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use ToCanonicalWildcardString for a unique string for each IP address and subnet.

func (*IPv6Address) ToCanonicalWildcardString 

func (addr *IPv6Address) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string and avoids the CIDR prefix length. Addresses and subnets with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. IPv6 addresses will be compressed according to the canonical representation.

func (*IPv6Address) ToCompressedString 

func (addr *IPv6Address) ToCompressedString() string

ToCompressedString produces a short representation of this address while remaining within the confines of standard representation(s) of the address.

For IPv6, it differs from the canonical string. It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.

func (*IPv6Address) ToCompressedWildcardString 

func (addr *IPv6Address) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, avoiding the CIDR prefix, but with full IPv6 segment compression as well, including single zero-segments.

func (*IPv6Address) ToCustomString 

func (addr *IPv6Address) ToCustomString(stringOptions addrstr.IPv6StringOptions) (string, addrerr.IncompatibleAddressError)

ToCustomString creates a customized string from this address or subnet according to the given string option parameters.

Errors can result from split digits with ranged values, or mixed IPv4/v6 with ranged values, when a range cannot be split up. Options without split digits or mixed addresses do not produce errors. Single addresses do not produce errors.

func (*IPv6Address) ToEUI 

func (addr *IPv6Address) ToEUI(extended bool) (*MACAddress, addrerr.IncompatibleAddressError)

ToEUI converts to the associated MACAddress. An error is returned if the 0xfffe pattern is missing in segments 5 and 6, or if an IPv6 segment's range of values cannot be split into two ranges of values.

func (*IPv6Address) ToFullString 

func (addr *IPv6Address) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 4 characters for IPv6 segments.

func (*IPv6Address) ToGenericKey added in v1.5.1 

func (addr *IPv6Address) ToGenericKey() Key[*IPv6Address]

ToGenericKey produces a generic Key[*IPv6Address] that can be used with generic code working with Address, IPAddress, IPv4Address, IPv6Address and MACAddress. ToKey produces a more compact key for code that is IPv6-specific.

func (*IPv6Address) ToHexString 

func (addr *IPv6Address) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6Address) ToIP 

func (addr *IPv6Address) ToIP() *IPAddress

ToIP converts to an IPAddress, a polymorphic type usable with all IP addresses and subnets.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6Address) ToKey added in v1.1.0 

func (addr *IPv6Address) ToKey() IPv6AddressKey

ToKey creates the associated address key. While addresses can be compared with the Compare, TrieCompare or Equal methods as well as various provided instances of AddressComparator, they are not comparable with Go operators. However, AddressKey instances are comparable with Go operators, and thus can be used as map keys.

func (*IPv6Address) ToMaxHost 

func (addr *IPv6Address) ToMaxHost() (*IPv6Address, addrerr.IncompatibleAddressError)

ToMaxHost converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-ones address, the max address.

The returned address or subnet will have the same prefix and prefix length.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv6Address) ToMaxHostLen 

func (addr *IPv6Address) ToMaxHostLen(prefixLength BitCount) (*IPv6Address, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the resulting one will too, otherwise the resulting address or subnet will have no prefix length.

For instance, the zero host of "1.2.3.4" for the prefix length of 16 is the address "1.2.255.255".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv6Address) ToMixedString 

func (addr *IPv6Address) ToMixedString() (string, addrerr.IncompatibleAddressError)

ToMixedString produces the mixed IPv6/IPv4 string. It is the shortest such string (ie fully compressed). For some address sections with ranges of values in the IPv4 part of the address, there is not mixed string, and an error is returned.

func (*IPv6Address) ToNormalizedString 

func (addr *IPv6Address) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For IPv6, it differs from the canonical string. Zero-segments are not compressed.

Each address has a unique normalized string, not counting the prefix length. With IP addresses, the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use the method ToNormalizedWildcardString for a unique string for each IP address and subnet.

func (*IPv6Address) ToNormalizedWildcardString 

func (addr *IPv6Address) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPv6Address) ToOctalString 

func (addr *IPv6Address) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6Address) ToPrefixBlock 

func (addr *IPv6Address) ToPrefixBlock() *IPv6Address

ToPrefixBlock returns the subnet associated with the prefix length of this address. If this address has no prefix length, this address is returned.

The subnet will include all addresses with the same prefix as this one, the prefix "block". The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is "1:2:3:4:5:6:7:8/64" it returns the subnet "1:2:3:4::/64" which can also be written as "1:2:3:4:*:*:*:*/64".

func (*IPv6Address) ToPrefixBlockLen 

func (addr *IPv6Address) ToPrefixBlockLen(prefLen BitCount) *IPv6Address

ToPrefixBlockLen returns the subnet associated with the given prefix length.

The subnet will include all addresses with the same prefix as this one, the prefix "block" for that prefix length. The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is "1:2:3:4:5:6:7:8" and the prefix length provided is 64, it returns the subnet "1:2:3:4::/64" which can also be written as "1:2:3:4:*:*:*:*/64".

func (*IPv6Address) ToPrefixLenString 

func (addr *IPv6Address) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, a zero host section will be compressed with "::". For IPv4 the string is equivalent to the canonical string.

func (*IPv6Address) ToReverseDNSString 

func (addr *IPv6Address) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse-DNS lookup string, returning an error if this address is a multiple-valued subnet for which the range cannot be represented. For "2001:db8::567:89ab" it is "b.a.9.8.7.6.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa".

func (*IPv6Address) ToSQLWildcardString 

func (addr *IPv6Address) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the ending single-digit wildcard '_'.

func (*IPv6Address) ToSegmentedBinaryString 

func (addr *IPv6Address) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this address as segments of binary values preceded by the "0b" prefix.

func (*IPv6Address) ToSequentialRange 

func (addr *IPv6Address) ToSequentialRange() *SequentialRange[*IPv6Address]

ToSequentialRange creates a sequential range instance from the lowest and highest addresses in this subnet.

The two will represent the same set of individual addresses if and only if IsSequential is true. To get a series of ranges that represent the same set of individual addresses use the SequentialBlockIterator (or PrefixIterator), and apply this method to each iterated subnet.

If this represents just a single address then the returned instance covers just that single address as well.

func (*IPv6Address) ToSinglePrefixBlockOrAddress added in v1.1.0 

func (addr *IPv6Address) ToSinglePrefixBlockOrAddress() *IPv6Address

ToSinglePrefixBlockOrAddress converts to a single prefix block or address. If the given address is a single prefix block, it is returned. If it can be converted to a single prefix block by assigning a prefix length, the converted block is returned. If it is a single address, any prefix length is removed and the address is returned. Otherwise, nil is returned. This method provides the address formats used by tries. ToSinglePrefixBlockOrAddress is quite similar to AssignPrefixForSingleBlock, which always returns prefixed addresses, while this does not.

func (*IPv6Address) ToSubnetString 

func (addr *IPv6Address) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like "1.2.*.*" or "1:2::/16".

In the case of IPv6, when a network prefix has been supplied, the prefix will be shown and the host section will be compressed with "::".

func (*IPv6Address) ToUNCHostName added in v1.3.0 

func (addr *IPv6Address) ToUNCHostName() string

ToUNCHostName Generates the Microsoft UNC path component for this address. For examples see https://ipv6-literal.com/

For IPv6, it is the canonical string but with colons replaced by dashes, percent signs with the letter “s”, and then appended with the root domain ".ipv6-literal.net".

func (*IPv6Address) ToZeroHost 

func (addr *IPv6Address) ToZeroHost() (*IPv6Address, addrerr.IncompatibleAddressError)

ToZeroHost converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix and prefix length.

For instance, the zero host of "1.2.3.4/16" is the individual address "1.2.0.0/16".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv6Address) ToZeroHostLen 

func (addr *IPv6Address) ToZeroHostLen(prefixLength BitCount) (*IPv6Address, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.

For instance, the zero host of "1.2.3.4" for the prefix length of 16 is the address "1.2.0.0".

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv6Address) ToZeroNetwork 

func (addr *IPv6Address) ToZeroNetwork() *IPv6Address

ToZeroNetwork converts the address or subnet to one in which all individual addresses have a network of zero, the network being the bits within the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix length.

func (*IPv6Address) TrieCompare added in v1.1.0 

func (addr *IPv6Address) TrieCompare(other *IPv6Address) int

TrieCompare compares two addresses according to address trie ordering. It returns a number less than zero, zero, or a number greater than zero if the first address argument is less than, equal to, or greater than the second.

The comparison is intended for individual addresses and CIDR prefix blocks. If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv6Address) TrieDecrement added in v1.1.0 

func (addr *IPv6Address) TrieDecrement() *IPv6Address

TrieDecrement returns the previous address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv6Address) TrieIncrement added in v1.1.0 

func (addr *IPv6Address) TrieIncrement() *IPv6Address

TrieIncrement returns the next address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv6Address) Uint64Values added in v1.5.5 

func (addr *IPv6Address) Uint64Values() (high, low uint64)

Uint64Values returns the lowest address in the address range as a pair of uint64 values.

func (*IPv6Address) UpperBytes 

func (addr *IPv6Address) UpperBytes() []byte

UpperBytes returns the highest address in this subnet or address as a byte slice.

func (*IPv6Address) UpperUint64Values added in v1.5.5 

func (addr *IPv6Address) UpperUint64Values() (high, low uint64)

UpperUint64Values returns the highest address in the address section range as a pair of uint64 values.

func (*IPv6Address) WithoutPrefixLen 

func (addr *IPv6Address) WithoutPrefixLen() *IPv6Address

WithoutPrefixLen provides the same address but with no prefix length. The values remain unchanged.

func (*IPv6Address) WithoutZone 

func (addr *IPv6Address) WithoutZone() *IPv6Address

WithoutZone returns the same address but with no zone.

func (*IPv6Address) Wrap 

func (addr *IPv6Address) Wrap() WrappedIPAddress

Wrap wraps this IP address, returning a WrappedIPAddress, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address.

func (*IPv6Address) WrapAddress added in v1.2.0 

func (addr *IPv6Address) WrapAddress() WrappedAddress

WrapAddress wraps this IP address, returning a WrappedAddress, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapAddress can be called with a nil receiver, wrapping a nil address.

type IPv6AddressAssociativeTrie added in v1.1.0 

type IPv6AddressAssociativeTrie = AssociativeTrie[*IPv6Address, any]

type IPv6AddressConverter 

type IPv6AddressConverter interface {
	// ToIPv6 converts to IPv6.  If the given address is IPv6, or can be converted to IPv6, returns that IPv6Address.  Otherwise, returns nil.
	ToIPv6(address *IPAddress) *IPv6Address
}

IPv6AddressConverter converts IP addresses to IPv6.

type IPv6AddressKey added in v1.1.0 

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

IPv6AddressKey is a representation of an IPv6 address that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators

It can be used as a map key. It can be obtained from its originating address instances. The zero value corresponds to the zero-value for IPv6Address. Keys do not incorporate prefix length to ensure that all equal addresses have equal keys. To create a key that has prefix length, combine into a struct with the PrefixKey obtained by passing the address into PrefixKeyFrom. IPv6Address can be compared using the Compare or Equal methods, or using an AddressComparator.

func (IPv6AddressKey) String added in v1.1.1 

func (key IPv6AddressKey) String() string

String calls the String method in the corresponding address.

func (IPv6AddressKey) ToAddress added in v1.1.0 

func (key IPv6AddressKey) ToAddress() *IPv6Address

ToAddress converts back to an address instance.

type IPv6AddressNetwork 

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

IPv6AddressNetwork is the implementation of IPAddressNetwork for IPv6

func (IPv6AddressNetwork) GetHostMask 

func (network IPv6AddressNetwork) GetHostMask(prefLen BitCount) *IPv6Address

func (IPv6AddressNetwork) GetLoopback 

func (network IPv6AddressNetwork) GetLoopback() *IPv6Address

func (IPv6AddressNetwork) GetNetworkMask 

func (network IPv6AddressNetwork) GetNetworkMask(prefLen BitCount) *IPv6Address

func (IPv6AddressNetwork) GetPrefixedHostMask 

func (network IPv6AddressNetwork) GetPrefixedHostMask(prefLen BitCount) *IPv6Address

func (IPv6AddressNetwork) GetPrefixedNetworkMask 

func (network IPv6AddressNetwork) GetPrefixedNetworkMask(prefLen BitCount) *IPv6Address

type IPv6AddressSection 

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

IPv6AddressSection represents a section of an IPv6 address comprising 0 to 8 IPv6 address segments. The zero values is a section with zero-segments.

func NewIPv6PrefixedSection 

func NewIPv6PrefixedSection(segments []*IPv6AddressSegment, prefixLen PrefixLen) *IPv6AddressSection

NewIPv6PrefixedSection constructs an IPv6 address or subnet section from the given segments and prefix length.

func NewIPv6Section 

func NewIPv6Section(segments []*IPv6AddressSegment) *IPv6AddressSection

NewIPv6Section constructs an IPv6 address or subnet section from the given segments.

func NewIPv6SectionFromBigInt 

func NewIPv6SectionFromBigInt(val *big.Int, segmentCount int) (res *IPv6AddressSection, err addrerr.AddressValueError)

NewIPv6SectionFromBigInt creates an IPv6 address section from the given big integer, returning an error if the value is too large for the given number of segments.

func NewIPv6SectionFromBytes 

func NewIPv6SectionFromBytes(bytes []byte) *IPv6AddressSection

NewIPv6SectionFromBytes constructs an IPv6 address from the given byte slice. The segment count is determined by the slice length, even if the segment count exceeds 8 segments.

func NewIPv6SectionFromMAC 

func NewIPv6SectionFromMAC(eui *MACAddress) (res *IPv6AddressSection, err addrerr.IncompatibleAddressError)

NewIPv6SectionFromMAC constructs an IPv6 address section from a modified EUI-64 (Extended Unique Identifier) MAC address.

If the supplied MAC address section is an 8-byte EUI-64, then it must match the required EUI-64 format of "xx-xx-ff-fe-xx-xx" with the "ff-fe" section in the middle.

If the supplied MAC address section is a 6-byte MAC-48 or EUI-48, then the ff-fe pattern will be inserted when converting to IPv6.

The constructor will toggle the MAC U/L (universal/local) bit as required with EUI-64.

The error is IncompatibleAddressError when unable to join two MAC segments, at least one with ranged values, into an equivalent IPV6 segment range.

func NewIPv6SectionFromPrefixedBigInt 

func NewIPv6SectionFromPrefixedBigInt(val *big.Int, segmentCount int, prefixLen PrefixLen) (res *IPv6AddressSection, err addrerr.AddressValueError)

NewIPv6SectionFromPrefixedBigInt creates an IPv6 address or prefix block section from the given big integer, returning an error if the value is too large for the given number of segments.

func NewIPv6SectionFromPrefixedBytes 

func NewIPv6SectionFromPrefixedBytes(bytes []byte, segmentCount int, prefixLength PrefixLen) (res *IPv6AddressSection, err addrerr.AddressValueError)

NewIPv6SectionFromPrefixedBytes constructs an IPv6 address or prefix block from the given byte slice and prefix length. It allows you to specify the segment count for the supplied bytes. If the slice is too large for the given number of segments, an error is returned, although leading zeros are tolerated.

func NewIPv6SectionFromPrefixedRange added in v1.2.0 

func NewIPv6SectionFromPrefixedRange(vals, upperVals IPv6SegmentValueProvider, segmentCount int, prefixLength PrefixLen) (res *IPv6AddressSection)

NewIPv6SectionFromPrefixedRange constructs an IPv6 subnet section of the given segment count from the given values and prefix length.

func NewIPv6SectionFromPrefixedUint64 

func NewIPv6SectionFromPrefixedUint64(highBytes, lowBytes uint64, segmentCount int, prefixLength PrefixLen) (res *IPv6AddressSection)

NewIPv6SectionFromPrefixedUint64 constructs an IPv6 address or prefix block section of the given segment count from the given values and prefix length.

func NewIPv6SectionFromPrefixedVals 

func NewIPv6SectionFromPrefixedVals(vals IPv6SegmentValueProvider, segmentCount int, prefixLength PrefixLen) (res *IPv6AddressSection)

NewIPv6SectionFromPrefixedVals constructs an IPv6 address or prefix block section of the given segment count from the given values and prefix length.

func NewIPv6SectionFromRange added in v1.2.0 

func NewIPv6SectionFromRange(vals, upperVals IPv6SegmentValueProvider, segmentCount int) (res *IPv6AddressSection)

NewIPv6SectionFromRange constructs an IPv6 subnet section of the given segment count from the given values.

func NewIPv6SectionFromSegmentedBytes 

func NewIPv6SectionFromSegmentedBytes(bytes []byte, segmentCount int) (res *IPv6AddressSection, err addrerr.AddressValueError)

NewIPv6SectionFromSegmentedBytes constructs an IPv6 address from the given byte slice. It allows you to specify the segment count for the supplied bytes. If the slice is too large for the given number of segments, an error is returned, although leading zeros are tolerated.

func NewIPv6SectionFromUint64 

func NewIPv6SectionFromUint64(highBytes, lowBytes uint64, segmentCount int) (res *IPv6AddressSection)

NewIPv6SectionFromUint64 constructs an IPv6 address section of the given segment count from the given values.

func NewIPv6SectionFromVals 

func NewIPv6SectionFromVals(vals IPv6SegmentValueProvider, segmentCount int) (res *IPv6AddressSection)

NewIPv6SectionFromVals constructs an IPv6 address section of the given segment count from the given values.

func (*IPv6AddressSection) AdjustPrefixLen 

func (section *IPv6AddressSection) AdjustPrefixLen(prefixLen BitCount) *IPv6AddressSection

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*IPv6AddressSection) AdjustPrefixLenZeroed 

func (section *IPv6AddressSection) AdjustPrefixLenZeroed(prefixLen BitCount) (*IPv6AddressSection, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv6AddressSection) Append 

func (section *IPv6AddressSection) Append(other *IPv6AddressSection) *IPv6AddressSection

Append creates a new section by appending the given section to this section.

func (*IPv6AddressSection) AssignMinPrefixForBlock 

func (section *IPv6AddressSection) AssignMinPrefixForBlock() *IPv6AddressSection

AssignMinPrefixForBlock returns an equivalent address section, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this address section.

In other words, this method assigns a prefix length to this address section matching the largest prefix block in this address section.

func (*IPv6AddressSection) AssignPrefixForSingleBlock 

func (section *IPv6AddressSection) AssignPrefixForSingleBlock() *IPv6AddressSection

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address section. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address section - it is required that the range of values match the range of a prefix block. If there is no such address section, then nil is returned.

func (*IPv6AddressSection) BitwiseOr 

func (section *IPv6AddressSection) BitwiseOr(other *IPv6AddressSection) (res *IPv6AddressSection, err addrerr.IncompatibleAddressError)

BitwiseOr does the bitwise disjunction with this address section, useful when subnetting. It is similar to Mask which does the bitwise conjunction.

The operation is applied to all individual addresses and the result is returned.

If this represents multiple address sections, and applying the operation to all sections creates a set of sections that cannot be represented as a sequential range within each segment, then an error is returned.

func (*IPv6AddressSection) BlockIterator 

func (section *IPv6AddressSection) BlockIterator(segmentCount int) Iterator[*IPv6AddressSection]

BlockIterator Iterates through the address sections that can be obtained by iterating through all the upper segments up to the given segment count. The segments following remain the same in all iterated sections.

func (*IPv6AddressSection) Bytes 

func (section *IPv6AddressSection) Bytes() []byte

Bytes returns the lowest individual address section in this address section as a byte slice.

func (*IPv6AddressSection) Compare 

func (section *IPv6AddressSection) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address section is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPv6AddressSection) CompareSize 

func (section *IPv6AddressSection) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual sections represented.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one item represents more individual items than another.

CompareSize returns a positive integer if this address section has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPv6AddressSection) Contains 

func (section *IPv6AddressSection) Contains(other AddressSectionType) bool

Contains returns whether this is same type and version as the given address section and whether it contains all values in the given section.

Sections must also have the same number of segments to be comparable, otherwise false is returned.

func (*IPv6AddressSection) ContainsPrefixBlock 

func (section *IPv6AddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPv6AddressSection) ContainsSinglePrefixBlock 

func (section *IPv6AddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this section contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPv6AddressSection) CopyBytes 

func (section *IPv6AddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6AddressSection) CopySegments 

func (section *IPv6AddressSection) CopySegments(segs []*IPv6AddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPv6AddressSection) CopySubSegments 

func (section *IPv6AddressSection) CopySubSegments(start, end int, segs []*IPv6AddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*IPv6AddressSection) CopyUpperBytes 

func (section *IPv6AddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6AddressSection) CoverWithPrefixBlock 

func (section *IPv6AddressSection) CoverWithPrefixBlock() *IPv6AddressSection

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the individual address sections in this section. The resulting block will have a larger count than this, unless this section is already a prefix block.

func (*IPv6AddressSection) CoverWithPrefixBlockTo 

func (section *IPv6AddressSection) CoverWithPrefixBlockTo(other *IPv6AddressSection) (*IPv6AddressSection, addrerr.SizeMismatchError)

CoverWithPrefixBlockTo returns the minimal-size prefix block section that covers all the address sections spanning from this to the given section.

If the other section has a different segment count, an error is returned.

func (*IPv6AddressSection) Equal 

func (section *IPv6AddressSection) Equal(other AddressSectionType) bool

Equal returns whether the given address section is equal to this address section. Two address sections are equal if they represent the same set of sections. They must match:

  • type/version: IPv6
  • segment count
  • segment value ranges

Prefix lengths are ignored.

func (*IPv6AddressSection) ForEachSegment added in v1.2.0 

func (section *IPv6AddressSection) ForEachSegment(consumer func(segmentIndex int, segment *IPv6AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (*IPv6AddressSection) GetBitCount 

func (section *IPv6AddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (*IPv6AddressSection) GetBitsPerSegment 

func (section *IPv6AddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (*IPv6AddressSection) GetBlockCount 

func (section *IPv6AddressSection) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*IPv6AddressSection) GetBlockMaskPrefixLen 

func (section *IPv6AddressSection) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address section is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address section with all ones in the network section and then all zeros in the host section. A CIDR host mask is an address section with all zeros in the network section and then all ones in the host section. The prefix length is the bit-length of the network section.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this instance, indicating the network and host section of this address section. The prefix length returned here indicates the whether the value of this address can be used as a mask for the network and host section of any other address. Therefore the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this section represents multiple values.

func (*IPv6AddressSection) GetByteCount 

func (section *IPv6AddressSection) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item.

func (*IPv6AddressSection) GetBytesPerSegment 

func (section *IPv6AddressSection) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this section. Segments in the same address section are equal length.

func (*IPv6AddressSection) GetCount 

func (section *IPv6AddressSection) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv6AddressSection) GetGenericSegment 

func (section *IPv6AddressSection) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPv6AddressSection) GetHostMask 

func (section *IPv6AddressSection) GetHostMask() *IPv6AddressSection

GetHostMask returns the host mask associated with the CIDR network prefix length of this address section. If this section has no prefix length, then the all-ones mask is returned.

func (*IPv6AddressSection) GetHostSection 

func (section *IPv6AddressSection) GetHostSection() *IPv6AddressSection

GetHostSection returns a subsection containing the segments with the host of the address section, the bits beyond the CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

If this series has no prefix length, the returned host section will be the full section.

func (*IPv6AddressSection) GetHostSectionLen 

func (section *IPv6AddressSection) GetHostSectionLen(prefLen BitCount) *IPv6AddressSection

GetHostSectionLen returns a subsection containing the segments with the host of the address section, the bits beyond the given CIDR network prefix length. The returned section will have only as many segments as needed to contain the host. The returned section will have an assigned prefix length indicating the beginning of the host.

func (*IPv6AddressSection) GetIPVersion 

func (section *IPv6AddressSection) GetIPVersion() IPVersion

GetIPVersion returns IPv6, the IP version of this address section.

func (*IPv6AddressSection) GetIPv4AddressSection 

func (section *IPv6AddressSection) GetIPv4AddressSection(startByteIndex, endByteIndex int) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

GetIPv4AddressSection produces an IPv4 address section from a sequence of bytes in this IPv6 address section.

func (*IPv6AddressSection) GetLower 

func (section *IPv6AddressSection) GetLower() *IPv6AddressSection

GetLower returns the section in the range with the lowest numeric value, which will be the same section if it represents a single value. For example, for "1::1:2-3:4:5-6", the section "1::1:2:4:5" is returned.

func (*IPv6AddressSection) GetMaxSegmentValue 

func (section *IPv6AddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPv6AddressSection) GetMinPrefixLenForBlock 

func (section *IPv6AddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (*IPv6AddressSection) GetNetworkMask 

func (section *IPv6AddressSection) GetNetworkMask() *IPv6AddressSection

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address section. If this section has no prefix length, then the all-ones mask is returned.

func (*IPv6AddressSection) GetNetworkPrefixLen 

func (section *IPv6AddressSection) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. It is equivalent to GetPrefixLen.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (*IPv6AddressSection) GetNetworkSection 

func (section *IPv6AddressSection) GetNetworkSection() *IPv6AddressSection

GetNetworkSection returns a subsection containing the segments with the network bits of the section. The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.

If this series has no CIDR prefix length, the returned network section will be the entire series as a prefixed section with prefix length matching the address bit length.

func (*IPv6AddressSection) GetNetworkSectionLen 

func (section *IPv6AddressSection) GetNetworkSectionLen(prefLen BitCount) *IPv6AddressSection

GetNetworkSectionLen returns a subsection containing the segments with the network of the address section, the prefix bits according to the given prefix length. The returned section will have only as many segments as needed to contain the network.

The new section will be assigned the given prefix length, unless the existing prefix length is smaller, in which case the existing prefix length will be retained.

func (*IPv6AddressSection) GetPrefixCount 

func (section *IPv6AddressSection) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetCount.

func (*IPv6AddressSection) GetPrefixCountLen 

func (section *IPv6AddressSection) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length.

func (*IPv6AddressSection) GetPrefixLenForSingleBlock 

func (section *IPv6AddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (*IPv6AddressSection) GetSegment 

func (section *IPv6AddressSection) GetSegment(index int) *IPv6AddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (*IPv6AddressSection) GetSegmentCount 

func (section *IPv6AddressSection) GetSegmentCount() int

GetSegmentCount returns the segment/division count.

func (*IPv6AddressSection) GetSegmentStrings 

func (section *IPv6AddressSection) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*IPv6AddressSection) GetSegments 

func (section *IPv6AddressSection) GetSegments() (res []*IPv6AddressSegment)

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*IPv6AddressSection) GetSequentialBlockCount 

func (section *IPv6AddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section.

func (*IPv6AddressSection) GetSequentialBlockIndex 

func (section *IPv6AddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (*IPv6AddressSection) GetSubSection 

func (section *IPv6AddressSection) GetSubSection(index, endIndex int) *IPv6AddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*IPv6AddressSection) GetTrailingSection 

func (section *IPv6AddressSection) GetTrailingSection(index int) *IPv6AddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*IPv6AddressSection) GetUpper 

func (section *IPv6AddressSection) GetUpper() *IPv6AddressSection

GetUpper returns the section in the range with the highest numeric value, which will be the same section if it represents a single value. For example, for "1::1:2-3:4:5-6", the section "1::1:3:4:6" is returned.

func (*IPv6AddressSection) GetUpperValue 

func (section *IPv6AddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value.

func (*IPv6AddressSection) GetValue 

func (section *IPv6AddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value.

func (*IPv6AddressSection) GetZeroRangeSegments 

func (section *IPv6AddressSection) GetZeroRangeSegments() SegmentSequenceList

GetZeroRangeSegments returns the list of consecutive zero and zero prefix block segments. Each element in the list will be an segment index and a total segment count for which that count of consecutive segments starting from that index are all zero or a prefix block segment with lowest segment value zero.

func (*IPv6AddressSection) GetZeroSegments 

func (section *IPv6AddressSection) GetZeroSegments() SegmentSequenceList

GetZeroSegments returns the list of consecutive zero-segments. Each element in the list will be an segment index and a total segment count for which that count of consecutive segments starting from that index are all zero.

func (*IPv6AddressSection) IncludesMax 

func (section *IPv6AddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range.

func (*IPv6AddressSection) IncludesMaxHost 

func (section *IPv6AddressSection) IncludesMaxHost() bool

IncludesMaxHost returns whether the address section contains an individual address section with a host of all one-bits. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are one.

func (*IPv6AddressSection) IncludesMaxHostLen 

func (section *IPv6AddressSection) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the address section contains an individual address section with a host of all one-bits, an address section for which all bits past the given prefix length are all ones.

func (*IPv6AddressSection) IncludesZero 

func (section *IPv6AddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range.

func (*IPv6AddressSection) IncludesZeroHost 

func (section *IPv6AddressSection) IncludesZeroHost() bool

IncludesZeroHost returns whether the address section contains an individual address section with a host of zero. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are zero.

func (*IPv6AddressSection) IncludesZeroHostLen 

func (section *IPv6AddressSection) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the address section contains an individual section with a host of zero, a section for which all bits past the given prefix length are zero.

func (*IPv6AddressSection) Increment 

func (section *IPv6AddressSection) Increment(increment int64) *IPv6AddressSection

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (*IPv6AddressSection) IncrementBoundary 

func (section *IPv6AddressSection) IncrementBoundary(increment int64) *IPv6AddressSection

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (*IPv6AddressSection) Insert 

func (section *IPv6AddressSection) Insert(index int, other *IPv6AddressSection) *IPv6AddressSection

Insert creates a new section by inserting the given section into this section at the given index.

func (*IPv6AddressSection) Intersect 

func (section *IPv6AddressSection) Intersect(other *IPv6AddressSection) (res *IPv6AddressSection, err addrerr.SizeMismatchError)

Intersect returns the subnet sections whose individual sections are found in both this and the given subnet section argument, or nil if no such sections exist.

This is also known as the conjunction of the two sets of address sections.

If the two sections have different segment counts, an error is returned.

func (*IPv6AddressSection) IsAdaptiveZero 

func (section *IPv6AddressSection) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the division grouping was originally created as an implicitly zero-valued section or grouping (e.g. IPv4AddressSection{}), meaning it was not constructed using a constructor function. Such a grouping, which has no divisions or segments, is convertible to an implicitly zero-valued grouping of any type or version, whether IPv6, IPv4, MAC, or other. In other words, when a section or grouping is the zero-value, then it is equivalent and convertible to the zero value of any other section or grouping type.

func (*IPv6AddressSection) IsFullRange 

func (section *IPv6AddressSection) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv6AddressSection) IsMax 

func (section *IPv6AddressSection) IsMax() bool

IsMax returns whether this section matches exactly the maximum possible value, the value whose bits are all ones.

func (*IPv6AddressSection) IsMaxHost 

func (section *IPv6AddressSection) IsMaxHost() bool

IsMaxHost returns whether this section has a prefix length and if so, whether the host is all all one-bits, the max value, for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsMaxHost returns true.

func (*IPv6AddressSection) IsMaxHostLen 

func (section *IPv6AddressSection) IsMaxHostLen(prefLen BitCount) bool

IsMaxHostLen returns whether the host host is all one-bits, the max value, for all individual sections in this address section, for the given prefix length, the host being the bits following the prefix.

If the host section is zero length (there are zero host bits), IsMaxHostLen returns true.

func (*IPv6AddressSection) IsMultiple 

func (section *IPv6AddressSection) IsMultiple() bool

IsMultiple returns whether this section represents multiple values.

func (*IPv6AddressSection) IsOneBit 

func (section *IPv6AddressSection) IsOneBit(prefixBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*IPv6AddressSection) IsPrefixBlock 

func (section *IPv6AddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*IPv6AddressSection) IsPrefixed 

func (section *IPv6AddressSection) IsPrefixed() bool

IsPrefixed returns whether this section has an associated prefix length.

func (*IPv6AddressSection) IsSequential 

func (section *IPv6AddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (*IPv6AddressSection) IsSingleNetwork 

func (section *IPv6AddressSection) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address section.

func (*IPv6AddressSection) IsSinglePrefixBlock 

func (section *IPv6AddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPv6AddressSection) IsZero 

func (section *IPv6AddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero.

func (*IPv6AddressSection) IsZeroHost 

func (section *IPv6AddressSection) IsZeroHost() bool

IsZeroHost returns whether this section has a prefix length and if so, whether the host section is always zero for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (*IPv6AddressSection) IsZeroHostLen 

func (section *IPv6AddressSection) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual sections in this address section, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (*IPv6AddressSection) Iterator 

func (section *IPv6AddressSection) Iterator() Iterator[*IPv6AddressSection]

Iterator provides an iterator to iterate through the individual address sections of this address section.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address sections.

Call IsMultiple to determine if this instance represents multiple address sections, or GetCount for the count.

func (*IPv6AddressSection) Mask 

func (section *IPv6AddressSection) Mask(other *IPv6AddressSection) (res *IPv6AddressSection, err addrerr.IncompatibleAddressError)

Mask applies the given mask to all address sections represented by this secction, returning the result.

If the sections do not have a comparable number of segments, an error is returned.

If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned.

func (*IPv6AddressSection) MatchesWithMask 

func (section *IPv6AddressSection) MatchesWithMask(other *IPv6AddressSection, mask *IPv6AddressSection) bool

MatchesWithMask applies the mask to this address section and then compares the result with the given address section, returning true if they match, false otherwise. To match, both the given section and mask must have the same number of segments as this section.

func (*IPv6AddressSection) MergeToPrefixBlocks 

func (section *IPv6AddressSection) MergeToPrefixBlocks(sections ...*IPv6AddressSection) ([]*IPv6AddressSection, addrerr.SizeMismatchError)

MergeToPrefixBlocks merges this section with the list of sections to produce the smallest array of prefix blocks.

The resulting slice is sorted from lowest value to highest, regardless of the size of each prefix block.

func (*IPv6AddressSection) MergeToSequentialBlocks 

func (section *IPv6AddressSection) MergeToSequentialBlocks(sections ...*IPv6AddressSection) ([]*IPv6AddressSection, addrerr.SizeMismatchError)

MergeToSequentialBlocks merges this with the list of sections to produce the smallest array of sequential blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv6AddressSection) PrefixBlockIterator 

func (section *IPv6AddressSection) PrefixBlockIterator() Iterator[*IPv6AddressSection]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address section. Each iterated address section will be a prefix block with the same prefix length as this address section.

If this address section has no prefix length, then this is equivalent to Iterator.

func (*IPv6AddressSection) PrefixContains 

func (section *IPv6AddressSection) PrefixContains(other AddressSectionType) bool

PrefixContains returns whether the prefix values in the given address section are prefix values in this address section, using the prefix length of this section. If this address section has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

All prefix bits of this section must be present in the other section to be comparable.

func (*IPv6AddressSection) PrefixEqual 

func (section *IPv6AddressSection) PrefixEqual(other AddressSectionType) bool

PrefixEqual determines if the given section matches this section up to the prefix length of this section. It returns whether the argument section has the same address section prefix values as this.

All prefix bits of this section must be present in the other section to be comparable, otherwise false is returned.

func (*IPv6AddressSection) PrefixIterator 

func (section *IPv6AddressSection) PrefixIterator() Iterator[*IPv6AddressSection]

PrefixIterator provides an iterator to iterate through the individual prefixes of this address section, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this address section.

If the series has no prefix length, then this is equivalent to Iterator.

func (*IPv6AddressSection) Replace 

func (section *IPv6AddressSection) Replace(index int, replacement *IPv6AddressSection) *IPv6AddressSection

Replace replaces the segments of this section starting at the given index with the given replacement segments.

func (*IPv6AddressSection) ReplaceLen 

func (section *IPv6AddressSection) ReplaceLen(startIndex, endIndex int, replacement *IPv6AddressSection, replacementStartIndex, replacementEndIndex int) *IPv6AddressSection

ReplaceLen replaces the segments starting from startIndex and ending before endIndex with the segments starting at replacementStartIndex and ending before replacementEndIndex from the replacement section.

func (*IPv6AddressSection) ReverseBits 

func (section *IPv6AddressSection) ReverseBits(perByte bool) (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ReverseBits returns a new section with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv6AddressSection) ReverseBytes 

func (section *IPv6AddressSection) ReverseBytes() (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ReverseBytes returns a new section with the bytes reversed. Any prefix length is dropped.

If the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (*IPv6AddressSection) ReverseSegments 

func (section *IPv6AddressSection) ReverseSegments() *IPv6AddressSection

ReverseSegments returns a new section with the segments reversed.

func (*IPv6AddressSection) SequentialBlockIterator 

func (section *IPv6AddressSection) SequentialBlockIterator() Iterator[*IPv6AddressSection]

SequentialBlockIterator iterates through the sequential address sections that make up this address section.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPv6AddressSection) SetPrefixLen 

func (section *IPv6AddressSection) SetPrefixLen(prefixLen BitCount) *IPv6AddressSection

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPv6AddressSection) SetPrefixLenZeroed 

func (section *IPv6AddressSection) SetPrefixLenZeroed(prefixLen BitCount) (*IPv6AddressSection, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

If this address section has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address section has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv6AddressSection) SpanWithPrefixBlocks 

func (section *IPv6AddressSection) SpanWithPrefixBlocks() []*IPv6AddressSection

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual address sections as this section.

Unlike SpanWithPrefixBlocksTo, the result only includes blocks that are a part of this section.

func (*IPv6AddressSection) SpanWithPrefixBlocksTo 

func (section *IPv6AddressSection) SpanWithPrefixBlocksTo(other *IPv6AddressSection) ([]*IPv6AddressSection, addrerr.SizeMismatchError)

SpanWithPrefixBlocksTo returns the smallest slice of prefix block subnet sections that span from this section to the given section.

If the given section has a different segment count, an error is returned.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv6AddressSection) SpanWithSequentialBlocks 

func (section *IPv6AddressSection) SpanWithSequentialBlocks() []*IPv6AddressSection

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of sections as this.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

Unlike SpanWithSequentialBlocksTo, this method only includes values that are a part of this section.

func (*IPv6AddressSection) SpanWithSequentialBlocksTo 

func (section *IPv6AddressSection) SpanWithSequentialBlocksTo(other *IPv6AddressSection) ([]*IPv6AddressSection, addrerr.SizeMismatchError)

SpanWithSequentialBlocksTo produces the smallest slice of sequential block address sections that span from this section to the given section.

func (*IPv6AddressSection) String 

func (section *IPv6AddressSection) String() string

String implements the fmt.Stringer interface, returning the normalized string provided by ToNormalizedString, or "<nil>" if the receiver is a nil pointer.

func (*IPv6AddressSection) Subtract 

func (section *IPv6AddressSection) Subtract(other *IPv6AddressSection) (res []*IPv6AddressSection, err addrerr.SizeMismatchError)

Subtract subtracts the given subnet sections from this subnet section, returning an array of sections for the result (the subnet sections will not be contiguous so an array is required).

Subtract computes the subnet difference, the set of address sections in this address section but not in the provided section. This is also known as the relative complement of the given argument in this subnet section.

This is set subtraction, not subtraction of values.

func (*IPv6AddressSection) TestBit 

func (section *IPv6AddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv6AddressSection) ToBase85String added in v1.3.0 

func (section *IPv6AddressSection) ToBase85String() (string, addrerr.IncompatibleAddressError)

ToBase85String creates the base 85 string, which is described by RFC 1924, "A Compact Representation of IPv6 Addresses". See https://www.rfc-editor.org/rfc/rfc1924.html It may be written as a range of two values if a range that is not a prefixed block.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6AddressSection) ToBinaryString 

func (section *IPv6AddressSection) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address section as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6AddressSection) ToBlock 

func (section *IPv6AddressSection) ToBlock(segmentIndex int, lower, upper SegInt) *IPv6AddressSection

ToBlock creates a new block of address sections by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPv6AddressSection) ToCanonicalString 

func (section *IPv6AddressSection) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address section.

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

If this section has a prefix length, it will be included in the string.

func (*IPv6AddressSection) ToCanonicalWildcardString 

func (section *IPv6AddressSection) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string but avoids the CIDR prefix length. Address sections with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. IPv6 sections will be compressed according to the canonical representation.

func (*IPv6AddressSection) ToCompressedString 

func (section *IPv6AddressSection) ToCompressedString() string

ToCompressedString produces a short representation of this address section while remaining within the confines of standard representation(s) of the address.

For IPv6, it differs from the canonical string. It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.

func (*IPv6AddressSection) ToCompressedWildcardString 

func (section *IPv6AddressSection) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, avoiding the CIDR prefix, but with full IPv6 segment compression as well, including single zero-segments.

func (*IPv6AddressSection) ToCustomString 

func (section *IPv6AddressSection) ToCustomString(stringOptions addrstr.IPv6StringOptions) (string, addrerr.IncompatibleAddressError)

ToCustomString creates a customized string from this address section according to the given string option parameters.

Errors can result from split digits with ranged values, or mixed IPv4/v6 with ranged values, when the segment ranges are incompatible.

func (*IPv6AddressSection) ToDivGrouping 

func (section *IPv6AddressSection) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToIPv6.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSection) ToFullString 

func (section *IPv6AddressSection) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 4 characters for IPv6 segments.

func (*IPv6AddressSection) ToHexString 

func (section *IPv6AddressSection) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address section as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6AddressSection) ToIP 

func (section *IPv6AddressSection) ToIP() *IPAddressSection

ToIP converts to an IPAddressSection, a polymorphic type usable with all IP address sections.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSection) ToMaxHost 

func (section *IPv6AddressSection) ToMaxHost() (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ToMaxHost converts the address section to one in which all individual address sections have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-ones section, the max address section.

The returned address section will have the same prefix and prefix length.

This returns an error if the address section is a range of address sections which cannot be converted to a range in which all sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv6AddressSection) ToMaxHostLen 

func (section *IPv6AddressSection) ToMaxHostLen(prefixLength BitCount) (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address section to one in which all individual address sections have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this section has the same prefix length, then the resulting section will too, otherwise the resulting section will have no prefix length.

For instance, the zero host of "1.2.3.4" for the prefix length of 16 is the address "1.2.255.255".

This returns an error if the section is a range of address sections which cannot be converted to a range in which all address sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv6AddressSection) ToNormalizedString 

func (section *IPv6AddressSection) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address section.

For IPv6, it differs from the canonical string. Zero-segments are not compressed.

If this section has a prefix length, it will be included in the string.

func (*IPv6AddressSection) ToNormalizedWildcardString 

func (section *IPv6AddressSection) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPv6AddressSection) ToOctalString 

func (section *IPv6AddressSection) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address section as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6AddressSection) ToPrefixBlock 

func (section *IPv6AddressSection) ToPrefixBlock() *IPv6AddressSection

ToPrefixBlock returns the section with the same prefix as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

If this section has no prefix, this section is returned.

func (*IPv6AddressSection) ToPrefixBlockLen 

func (section *IPv6AddressSection) ToPrefixBlockLen(prefLen BitCount) *IPv6AddressSection

ToPrefixBlockLen returns the section with the same prefix of the given length as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

func (*IPv6AddressSection) ToPrefixLenString 

func (section *IPv6AddressSection) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, a zero host section will be compressed with "::". For IPv4 the string is equivalent to the canonical string.

func (*IPv6AddressSection) ToReverseDNSString 

func (section *IPv6AddressSection) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse-DNS lookup string, returning an error if this address section is a multiple-valued section for which the range cannot be represented. For "2001:db8::567:89ab" it is "b.a.9.8.7.6.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa".

func (*IPv6AddressSection) ToSQLWildcardString 

func (section *IPv6AddressSection) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the wildcard '_'.

func (*IPv6AddressSection) ToSectionBase 

func (section *IPv6AddressSection) ToSectionBase() *AddressSection

ToSectionBase converts to an AddressSection, a polymorphic type usable with all address sections. Afterwards, you can convert back with ToIPv6.

ToSectionBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSection) ToSegmentedBinaryString 

func (section *IPv6AddressSection) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this address section as segments of binary values preceded by the "0b" prefix.

func (*IPv6AddressSection) ToSubnetString 

func (section *IPv6AddressSection) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like "1.2.*.*" or "1:2::/16".

In the case of IPv6, when a network prefix has been supplied, the prefix will be shown and the host section will be compressed with "::".

func (*IPv6AddressSection) ToZeroHost 

func (section *IPv6AddressSection) ToZeroHost() (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ToZeroHost converts the address section to one in which all individual address sections have a host of zero, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned section will have the same prefix and prefix length.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv6AddressSection) ToZeroHostLen 

func (section *IPv6AddressSection) ToZeroHostLen(prefixLength BitCount) (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address section to one in which all individual sections have a host of zero, the host being the bits following the given prefix length. If this address section has the same prefix length, then the returned one will too, otherwise the returned section will have no prefix length.

This returns an error if the section is a range of which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv6AddressSection) ToZeroNetwork 

func (section *IPv6AddressSection) ToZeroNetwork() *IPv6AddressSection

ToZeroNetwork converts the address section to one in which all individual address sections have a network of zero, the network being the bits within the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned address section will have the same prefix length.

func (*IPv6AddressSection) Uint64Values added in v1.5.5 

func (section *IPv6AddressSection) Uint64Values() (high, low uint64)

Uint64Values returns the lowest address in the address section range as a pair of uint64s.

func (*IPv6AddressSection) UpperBytes 

func (section *IPv6AddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice.

func (*IPv6AddressSection) UpperUint64Values added in v1.5.5 

func (section *IPv6AddressSection) UpperUint64Values() (high, low uint64)

UpperUint64Values returns the highest address in the address section range as pair of uint64 values.

func (*IPv6AddressSection) WithoutPrefixLen 

func (section *IPv6AddressSection) WithoutPrefixLen() *IPv6AddressSection

WithoutPrefixLen provides the same address section but with no prefix length. The values remain unchanged.

func (*IPv6AddressSection) Wrap 

func (section *IPv6AddressSection) Wrap() WrappedIPAddressSection

Wrap wraps this IP address section, returning a WrappedIPAddressSection, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address section.

func (*IPv6AddressSection) WrapSection added in v1.2.0 

func (section *IPv6AddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapSection can be called with a nil receiver, wrapping a nil address section.

type IPv6AddressSegment 

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

IPv6AddressSegment represents a segment of an IPv6 address. An IPv6 segment contains a single value or a range of sequential values, a prefix length, and it has bit length of 16 bits.

Like strings, segments are immutable, which also makes them concurrency-safe.

See AddressSegment for more details regarding segments.

func NewIPv6PrefixedSegment 

func NewIPv6PrefixedSegment(val IPv6SegInt, prefixLen PrefixLen) *IPv6AddressSegment

NewIPv6PrefixedSegment constructs a segment of an IPv6 address with the given value and assigned prefix length.

func NewIPv6RangePrefixedSegment 

func NewIPv6RangePrefixedSegment(val, upperVal IPv6SegInt, prefixLen PrefixLen) *IPv6AddressSegment

NewIPv6RangePrefixedSegment constructs a segment of an IPv6 subnet with the given range of sequential values and assigned prefix length.

func NewIPv6RangeSegment 

func NewIPv6RangeSegment(val, upperVal IPv6SegInt) *IPv6AddressSegment

NewIPv6RangeSegment constructs a segment of an IPv6 subnet with the given range of sequential values.

func NewIPv6Segment 

func NewIPv6Segment(val IPv6SegInt) *IPv6AddressSegment

NewIPv6Segment constructs a segment of an IPv6 address with the given value.

func (*IPv6AddressSegment) Bytes 

func (seg *IPv6AddressSegment) Bytes() []byte

Bytes returns the lowest value in the address segment range as a byte slice.

func (*IPv6AddressSegment) Compare 

func (seg *IPv6AddressSegment) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address segment is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPv6AddressSegment) CompareSize added in v1.3.0 

func (seg *IPv6AddressSegment) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual values within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one represents more individual values than another.

CompareSize returns a positive integer if this segment has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPv6AddressSegment) Contains 

func (seg *IPv6AddressSegment) Contains(other AddressSegmentType) bool

Contains returns whether this is same type and version as the given segment and whether it contains all values in the given segment.

func (*IPv6AddressSegment) ContainsPrefixBlock 

func (seg *IPv6AddressSegment) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the division range includes the block of values for the given prefix length.

func (*IPv6AddressSegment) ContainsSinglePrefixBlock 

func (seg *IPv6AddressSegment) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the segment range matches exactly the block of values for the given prefix length and has just a single prefix for that prefix length.

func (*IPv6AddressSegment) CopyBytes 

func (seg *IPv6AddressSegment) CopyBytes(bytes []byte) []byte

CopyBytes copies the lowest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6AddressSegment) CopyUpperBytes 

func (seg *IPv6AddressSegment) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the highest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6AddressSegment) Equal 

func (seg *IPv6AddressSegment) Equal(other AddressSegmentType) bool

Equal returns whether the given segment is equal to this segment. Two segments are equal if they match:

  • type/version: IPv6
  • value range

Prefix lengths are ignored.

func (*IPv6AddressSegment) GetBitCount 

func (seg *IPv6AddressSegment) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item, which is 16.

func (*IPv6AddressSegment) GetBlockMaskPrefixLen 

func (seg *IPv6AddressSegment) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address segment is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is a segment with all ones in the network bits and then all zeros in the host bits. A CIDR host mask is a segment with all zeros in the network bits and then all ones in the host bits. The prefix length is the bit-length of the network bits.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this segment. The prefix length returned here indicates the whether the value of this segment can be used as a mask for the network and host bits of any other segment. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv6AddressSegment) GetByteCount 

func (seg *IPv6AddressSegment) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item, which is 2.

func (*IPv6AddressSegment) GetCount 

func (seg *IPv6AddressSegment) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1.

For instance, a segment with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv6AddressSegment) GetIPv6SegmentValue 

func (seg *IPv6AddressSegment) GetIPv6SegmentValue() IPv6SegInt

GetIPv6SegmentValue returns the lower value. Same as GetSegmentValue but returned as a IPv6SegInt.

func (*IPv6AddressSegment) GetIPv6UpperSegmentValue 

func (seg *IPv6AddressSegment) GetIPv6UpperSegmentValue() IPv6SegInt

GetIPv6UpperSegmentValue returns the lower value. Same as GetUpperSegmentValue but returned as a IPv6SegInt.

func (*IPv6AddressSegment) GetLeadingBitCount 

func (seg *IPv6AddressSegment) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv6AddressSegment) GetLower 

func (seg *IPv6AddressSegment) GetLower() *IPv6AddressSegment

GetLower returns a segment representing just the lowest value in the range, which will be the same segment if it represents a single value.

func (*IPv6AddressSegment) GetMaxValue 

func (seg *IPv6AddressSegment) GetMaxValue() IPv6SegInt

GetMaxValue gets the maximum possible value for this type or version of segment, determined by the number of bits.

For the highest range value of this particular segment, use GetUpperSegmentValue.

func (*IPv6AddressSegment) GetMinPrefixLenForBlock 

func (seg *IPv6AddressSegment) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this segment includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this segment represents a single value, this returns the bit count.

func (*IPv6AddressSegment) GetPrefixCountLen 

func (seg *IPv6AddressSegment) GetPrefixCountLen(segmentPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct prefix values for the given prefix length in the range of values of this segment.

func (*IPv6AddressSegment) GetPrefixLenForSingleBlock 

func (seg *IPv6AddressSegment) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this segment, and the range of values in this segment matches the block of all values for that prefix.

If the range of segment values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this segment represents a single value, this returns the bit count of the segment.

func (*IPv6AddressSegment) GetPrefixValueCount 

func (seg *IPv6AddressSegment) GetPrefixValueCount() SegIntCount

GetPrefixValueCount returns the count of prefixes in this segment for its prefix length, or the total count if it has no prefix length.

func (*IPv6AddressSegment) GetPrefixValueCountLen 

func (seg *IPv6AddressSegment) GetPrefixValueCountLen(segmentPrefixLength BitCount) SegIntCount

GetPrefixValueCountLen returns the same value as GetPrefixCountLen as an integer.

func (*IPv6AddressSegment) GetSegmentPrefixLen 

func (seg *IPv6AddressSegment) GetSegmentPrefixLen() PrefixLen

GetSegmentPrefixLen returns the network prefix for the segment.

The network prefix is 16 for an address like "1.2.0.0/16".

When it comes to each address division or segment, the prefix for the division is the prefix obtained when applying the address or section prefix.

For instance, consider the address "1.2.0.0/20". The first segment has no prefix because the address prefix 20 extends beyond the 8 bits in the first segment, it does not even apply to the segment. The second segment has no prefix because the address prefix extends beyond bits 9 to 16 which lie in the second segment, it does not apply to that segment either. The third segment has the prefix 4 because the address prefix 20 corresponds to the first 4 bits in the 3rd segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment has the prefix 0 because not a single bit is in the network section of the address or segment

The division prefixes applied across the address are: nil ... nil (1 to segment bit length) 0 ... 0.

If the segment has no prefix then nil is returned.

func (*IPv6AddressSegment) GetSegmentValue 

func (seg *IPv6AddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the segment value range.

func (*IPv6AddressSegment) GetString 

func (seg *IPv6AddressSegment) GetString() string

GetString produces a normalized string to represent the segment. If the segment is a CIDR network prefix block for its prefix length, then the string contains only the lower value of the block range. Otherwise, the explicit range will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPv6AddressSegment) GetTrailingBitCount 

func (seg *IPv6AddressSegment) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv6AddressSegment) GetUpper 

func (seg *IPv6AddressSegment) GetUpper() *IPv6AddressSegment

GetUpper returns a segment representing just the highest value in the range, which will be the same segment if it represents a single value.

func (*IPv6AddressSegment) GetUpperSegmentValue 

func (seg *IPv6AddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the segment value range.

func (*IPv6AddressSegment) GetUpperValue 

func (seg *IPv6AddressSegment) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address segment range as a big integer.

func (*IPv6AddressSegment) GetValue 

func (seg *IPv6AddressSegment) GetValue() *BigDivInt

GetValue returns the lowest value in the address segment range as a big integer.

func (*IPv6AddressSegment) GetValueCount 

func (seg *IPv6AddressSegment) GetValueCount() SegIntCount

GetValueCount returns the same value as GetCount as an integer.

func (*IPv6AddressSegment) GetWildcardString 

func (seg *IPv6AddressSegment) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters while ignoring any network prefix length. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPv6AddressSegment) IncludesMax 

func (seg *IPv6AddressSegment) IncludesMax() bool

IncludesMax returns whether this segment includes the max value, the value whose bits are all ones, within its range.

func (*IPv6AddressSegment) IncludesZero 

func (seg *IPv6AddressSegment) IncludesZero() bool

IncludesZero returns whether this segment includes the value of zero within its range.

func (*IPv6AddressSegment) IsFullRange 

func (seg *IPv6AddressSegment) IsFullRange() bool

IsFullRange returns whether the segment range includes all possible values for its bit length.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv6AddressSegment) IsMax 

func (seg *IPv6AddressSegment) IsMax() bool

IsMax returns whether this segment matches exactly the maximum possible value, the value whose bits are all ones.

func (*IPv6AddressSegment) IsMultiple 

func (seg *IPv6AddressSegment) IsMultiple() bool

IsMultiple returns whether this segment represents multiple values.

func (*IPv6AddressSegment) IsOneBit 

func (seg *IPv6AddressSegment) IsOneBit(segmentBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 is the most significant bit.

func (*IPv6AddressSegment) IsPrefixBlock 

func (seg *IPv6AddressSegment) IsPrefixBlock() bool

IsPrefixBlock returns whether the segment has a prefix length and the segment range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

func (*IPv6AddressSegment) IsPrefixed 

func (seg *IPv6AddressSegment) IsPrefixed() bool

IsPrefixed returns whether this segment has an associated prefix length.

func (*IPv6AddressSegment) IsSinglePrefix 

func (seg *IPv6AddressSegment) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix determines if the segment has a single prefix value for the given prefix length. You can call GetPrefixCountLen to get the count of prefixes.

func (*IPv6AddressSegment) IsSinglePrefixBlock 

func (seg *IPv6AddressSegment) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPv6AddressSegment) IsZero 

func (seg *IPv6AddressSegment) IsZero() bool

IsZero returns whether this segment matches exactly the value of zero.

func (*IPv6AddressSegment) Iterator 

func (seg *IPv6AddressSegment) Iterator() Iterator[*IPv6AddressSegment]

Iterator provides an iterator to iterate through the individual address segments of this address segment.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address segments.

Call IsMultiple to determine if this instance represents multiple address segments, or GetValueCount for the count.

func (*IPv6AddressSegment) Matches 

func (seg *IPv6AddressSegment) Matches(value SegInt) bool

Matches returns true if the segment range matches the given single value.

func (*IPv6AddressSegment) MatchesValsWithMask 

func (seg *IPv6AddressSegment) MatchesValsWithMask(lowerValue, upperValue, mask SegInt) bool

MatchesValsWithMask applies the mask to this segment and then compares the result with the given values, returning true if the range of the resulting segment matches the given range.

func (*IPv6AddressSegment) MatchesWithMask 

func (seg *IPv6AddressSegment) MatchesWithMask(value, mask SegInt) bool

MatchesWithMask applies the mask to this segment and then compares the result with the given value, returning true if the range of the resulting segment matches that single value.

func (*IPv6AddressSegment) MatchesWithPrefixMask 

func (seg *IPv6AddressSegment) MatchesWithPrefixMask(value IPv6SegInt, networkBits BitCount) bool

MatchesWithPrefixMask applies the network mask of the given bit-length to this segment and then compares the result with the given value masked by the same mask, returning true if the resulting range matches the given single value.

func (*IPv6AddressSegment) PrefixBlockIterator 

func (seg *IPv6AddressSegment) PrefixBlockIterator() Iterator[*IPv6AddressSegment]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address segment. Each iterated address segment will be a prefix block with the same prefix length as this address segment.

If this address segment has no prefix length, then this is equivalent to Iterator.

func (*IPv6AddressSegment) PrefixContains 

func (seg *IPv6AddressSegment) PrefixContains(other AddressSegmentType, prefixLength BitCount) bool

PrefixContains returns whether the prefix values in the prefix of the given segment are also prefix values in this segment. It returns whether the prefix of this segment contains the prefix of the given segment.

func (*IPv6AddressSegment) PrefixEqual 

func (seg *IPv6AddressSegment) PrefixEqual(other AddressSegmentType, prefixLength BitCount) bool

PrefixEqual returns whether the prefix bits of this segment match the same bits of the given segment. It returns whether the two segments share the same range of prefix values using the given prefix length.

func (*IPv6AddressSegment) PrefixIterator 

func (seg *IPv6AddressSegment) PrefixIterator() Iterator[*IPv6AddressSegment]

PrefixIterator provides an iterator to iterate through the individual prefixes of this segment, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this segment.

If this address segment has no prefix length, then this is equivalent to Iterator.

func (*IPv6AddressSegment) PrefixedBlockIterator 

func (seg *IPv6AddressSegment) PrefixedBlockIterator(segmentPrefixLen BitCount) Iterator[*IPv6AddressSegment]

PrefixedBlockIterator provides an iterator to iterate through the individual prefix blocks of the given prefix length in this segment, one for each prefix of this address or subnet.

It is similar to PrefixBlockIterator except that this method allows you to specify the prefix length.

func (*IPv6AddressSegment) ReverseBits 

func (seg *IPv6AddressSegment) ReverseBits(perByte bool) (res *IPv6AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBits returns a segment with the bits reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv6AddressSegment) ReverseBytes 

func (seg *IPv6AddressSegment) ReverseBytes() (res *IPv6AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBytes returns a segment with the bytes reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

func (*IPv6AddressSegment) String 

func (seg *IPv6AddressSegment) String() string

String produces a string that is useful when a segment is provided with no context. It uses the hexadecimal radix with the string prefix for hex ("0x"). GetWildcardString is more appropriate in context with other segments or divisions. It does not use a string prefix and uses '*' for full-range segments. GetString is more appropriate in context with prefix lengths, it uses zeros instead of wildcards with full prefix block ranges alongside prefix lengths.

func (*IPv6AddressSegment) TestBit 

func (seg *IPv6AddressSegment) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv6AddressSegment) ToDiv 

func (seg *IPv6AddressSegment) ToDiv() *AddressDivision

ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions. Afterwards, you can convert back with ToIPv6.

ToDiv can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSegment) ToHexString 

func (seg *IPv6AddressSegment) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address segment as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

For segments, the error is always nil.

func (*IPv6AddressSegment) ToHostSegment 

func (seg *IPv6AddressSegment) ToHostSegment(segmentPrefixLength PrefixLen) *IPv6AddressSegment

ToHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will have no assigned prefix length.

func (*IPv6AddressSegment) ToIP 

func (seg *IPv6AddressSegment) ToIP() *IPAddressSegment

ToIP converts to an IPAddressSegment, a polymorphic type usable with all IP address segments. Afterwards, you can convert back with ToIPv6.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSegment) ToNetworkSegment 

func (seg *IPv6AddressSegment) ToNetworkSegment(segmentPrefixLength PrefixLen) *IPv6AddressSegment

ToNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will have no assigned prefix length.

func (*IPv6AddressSegment) ToNormalizedString 

func (seg *IPv6AddressSegment) ToNormalizedString() string

ToNormalizedString produces a string that is consistent for all address segments of the same type and version. IPv4 segments use base 10, while IPv6 segments use base 16.

func (*IPv6AddressSegment) ToPrefixedHostSegment 

func (seg *IPv6AddressSegment) ToPrefixedHostSegment(segmentPrefixLength PrefixLen) *IPv6AddressSegment

ToPrefixedHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPv6AddressSegment) ToPrefixedNetworkSegment 

func (seg *IPv6AddressSegment) ToPrefixedNetworkSegment(segmentPrefixLength PrefixLen) *IPv6AddressSegment

ToPrefixedNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPv6AddressSegment) ToSegmentBase 

func (seg *IPv6AddressSegment) ToSegmentBase() *AddressSegment

ToSegmentBase converts to an AddressSegment, a polymorphic type usable with all address segments. Afterwards, you can convert back with ToIPv6.

ToSegmentBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSegment) UpperBytes 

func (seg *IPv6AddressSegment) UpperBytes() []byte

UpperBytes returns the highest value in the address segment range as a byte slice.

func (*IPv6AddressSegment) WithoutPrefixLen 

func (seg *IPv6AddressSegment) WithoutPrefixLen() *IPv6AddressSegment

WithoutPrefixLen returns a segment with the same value range but without a prefix length.

type IPv6AddressSegmentSeries 

type IPv6AddressSegmentSeries interface {
	IPAddressSegmentSeries

	// GetTrailingSection returns an ending subsection of the full address or address section
	GetTrailingSection(index int) *IPv6AddressSection

	// GetSubSection returns a subsection of the full address or address section
	GetSubSection(index, endIndex int) *IPv6AddressSection

	// GetNetworkSection returns an address section containing the segments with the network of the series, the prefix bits.
	// The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.
	//
	// If this series has no CIDR prefix length, the returned network section will
	// be the entire series as a prefixed section with prefix length matching the address bit length.
	GetNetworkSection() *IPv6AddressSection

	// GetHostSection returns a section containing the segments with the host of the series, the bits beyond the CIDR network prefix length.
	// The returned section will have only as many segments as needed to contain the host.
	//
	// If this series has no prefix length, the returned host section will be the full section.
	GetHostSection() *IPv6AddressSection

	// GetNetworkSectionLen returns a section containing the segments with the network of the series, the prefix bits according to the given prefix length.
	// The returned section will have only as many segments as needed to contain the network.
	//
	// The new section will be assigned the given prefix length,
	// unless the existing prefix length is smaller, in which case the existing prefix length will be retained.
	GetNetworkSectionLen(BitCount) *IPv6AddressSection

	// GetHostSectionLen returns a section containing the segments with the host of the series, the bits beyond the given CIDR network prefix length.
	// The returned section will have only as many segments as needed to contain the host.
	GetHostSectionLen(BitCount) *IPv6AddressSection

	// GetSegments returns a slice with the address segments.  The returned slice is not backed by the same array as the receiver.
	GetSegments() []*IPv6AddressSegment

	// CopySegments copies the existing segments into the given slice,
	// as much as can be fit into the slice, returning the number of segments copied.
	CopySegments(segs []*IPv6AddressSegment) (count int)

	// CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index,
	// into the given slice, as much as can be fit into the slice, returning the number of segments copied.
	CopySubSegments(start, end int, segs []*IPv6AddressSegment) (count int)

	// GetSegment returns the segment at the given index.
	// The first segment is at index 0.
	// GetSegment will panic given a negative index or an index matching or larger than the segment count.
	GetSegment(index int) *IPv6AddressSegment
}

IPv6AddressSegmentSeries serves as a common interface to all IPv6 address sections and IPv6 addresses.

type IPv6AddressSeqRange 

type IPv6AddressSeqRange = SequentialRange[*IPv6Address]

type IPv6AddressSeqRangeKey added in v1.1.0 

type IPv6AddressSeqRangeKey = SequentialRangeKey[*IPv6Address]

type IPv6AddressTrie added in v1.1.0 

type IPv6AddressTrie = Trie[*IPv6Address]

type IPv6PrefixBlockAllocator added in v1.4.0 

type IPv6PrefixBlockAllocator = PrefixBlockAllocator[*IPv6Address]

type IPv6SegInt 

type IPv6SegInt = uint16

type IPv6SegmentValueProvider 

type IPv6SegmentValueProvider func(segmentIndex int) IPv6SegInt

func WrapSegmentValueProviderForIPv6 added in v1.5.0 

func WrapSegmentValueProviderForIPv6(f SegmentValueProvider) IPv6SegmentValueProvider

WrapSegmentValueProviderForIPv6 converts the given SegmentValueProvider to an IPv6SegmentValueProvider. Values that do not fit IPv6SegInt are truncated.

type IPv6v4MixedAddressGrouping 

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

IPv6v4MixedAddressGrouping has divisions which are a mix of IPv6 and IPv4 divisions. It has an initial IPv6 section followed by an IPv4 section.

func (*IPv6v4MixedAddressGrouping) Bytes 

func (grouping *IPv6v4MixedAddressGrouping) Bytes() []byte

Bytes returns the lowest individual division grouping in this grouping as a byte slice.

func (*IPv6v4MixedAddressGrouping) Compare 

func (grouping *IPv6v4MixedAddressGrouping) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address division grouping is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPv6v4MixedAddressGrouping) CompareSize 

func (grouping *IPv6v4MixedAddressGrouping) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual items represented in each.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether this grouping represents more individual address groupings than another item.

CompareSize returns a positive integer if this address division grouping has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*IPv6v4MixedAddressGrouping) ContainsPrefixBlock 

func (grouping *IPv6v4MixedAddressGrouping) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPv6v4MixedAddressGrouping) ContainsSinglePrefixBlock 

func (grouping *IPv6v4MixedAddressGrouping) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this grouping contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPv6v4MixedAddressGrouping) CopyBytes 

func (grouping *IPv6v4MixedAddressGrouping) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest division grouping in the range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

You can use GetByteCount to determine the required array length for the bytes.

func (*IPv6v4MixedAddressGrouping) CopyUpperBytes 

func (grouping *IPv6v4MixedAddressGrouping) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest division grouping in the range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

You can use GetByteCount to determine the required array length for the bytes.

func (IPv6v4MixedAddressGrouping) Format 

func (grouping IPv6v4MixedAddressGrouping) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same
  • 'q' for a quoted string

func (*IPv6v4MixedAddressGrouping) GetBitCount 

func (grouping *IPv6v4MixedAddressGrouping) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (*IPv6v4MixedAddressGrouping) GetBlockCount 

func (grouping *IPv6v4MixedAddressGrouping) GetBlockCount(divisionCount int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) divisions.

func (*IPv6v4MixedAddressGrouping) GetByteCount 

func (grouping *IPv6v4MixedAddressGrouping) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item, rounding up if the bit count is not a multiple of 8.

func (*IPv6v4MixedAddressGrouping) GetCount 

func (grouping *IPv6v4MixedAddressGrouping) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv6v4MixedAddressGrouping) GetDivisionCount 

func (grouping *IPv6v4MixedAddressGrouping) GetDivisionCount() int

GetDivisionCount returns the number of divisions in this grouping.

func (*IPv6v4MixedAddressGrouping) GetGenericDivision 

func (grouping *IPv6v4MixedAddressGrouping) GetGenericDivision(index int) DivisionType

GetGenericDivision returns the division at the given index as a DivisionType implementation.

func (*IPv6v4MixedAddressGrouping) GetIPv4AddressSection 

func (grouping *IPv6v4MixedAddressGrouping) GetIPv4AddressSection() *IPv4AddressSection

GetIPv4AddressSection returns the ending IPv4 section of the grouping.

func (*IPv6v4MixedAddressGrouping) GetIPv6AddressSection 

func (grouping *IPv6v4MixedAddressGrouping) GetIPv6AddressSection() *EmbeddedIPv6AddressSection

GetIPv6AddressSection returns the initial IPv6 section of the grouping.

func (*IPv6v4MixedAddressGrouping) GetMinPrefixLenForBlock 

func (grouping *IPv6v4MixedAddressGrouping) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this grouping includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this grouping represents a single value, this returns the bit count.

func (*IPv6v4MixedAddressGrouping) GetPrefixCount 

func (grouping *IPv6v4MixedAddressGrouping) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetCount.

func (*IPv6v4MixedAddressGrouping) GetPrefixCountLen 

func (grouping *IPv6v4MixedAddressGrouping) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length.

func (*IPv6v4MixedAddressGrouping) GetPrefixLenForSingleBlock 

func (grouping *IPv6v4MixedAddressGrouping) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this division grouping matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this division grouping represents a single value, returns the bit length.

func (*IPv6v4MixedAddressGrouping) GetSequentialBlockCount 

func (grouping *IPv6v4MixedAddressGrouping) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address division groupings that comprise this address division grouping.

func (*IPv6v4MixedAddressGrouping) GetSequentialBlockIndex 

func (grouping *IPv6v4MixedAddressGrouping) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal division index for which all following divisions are full-range blocks.

The division at this index is not a full-range block unless all divisions are full-range. The division at this index and all following divisions form a sequential range. For the full grouping to be sequential, the preceding divisions must be single-valued.

func (*IPv6v4MixedAddressGrouping) GetUpperValue 

func (grouping *IPv6v4MixedAddressGrouping) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address division grouping in this address division grouping as an integer value.

func (*IPv6v4MixedAddressGrouping) GetValue 

func (grouping *IPv6v4MixedAddressGrouping) GetValue() *big.Int

GetValue returns the lowest individual address division grouping in this address division grouping as an integer value.

func (*IPv6v4MixedAddressGrouping) IncludesMax 

func (grouping *IPv6v4MixedAddressGrouping) IncludesMax() bool

IncludesMax returns whether this grouping includes the max value, the value whose bits are all ones, within its range.

func (*IPv6v4MixedAddressGrouping) IncludesZero 

func (grouping *IPv6v4MixedAddressGrouping) IncludesZero() bool

IncludesZero returns whether this grouping includes the value of zero within its range.

func (*IPv6v4MixedAddressGrouping) IsAdaptiveZero 

func (grouping *IPv6v4MixedAddressGrouping) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the division grouping was originally created as an implicitly zero-valued section or grouping (e.g. IPv4AddressSection{}), meaning it was not constructed using a constructor function. Such a grouping, which has no divisions or segments, is convertible to an implicitly zero-valued grouping of any type or version, whether IPv6, IPv4, MAC, or other. In other words, when a section or grouping is the zero-value, then it is equivalent and convertible to the zero value of any other section or grouping type.

func (*IPv6v4MixedAddressGrouping) IsFullRange 

func (grouping *IPv6v4MixedAddressGrouping) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv6v4MixedAddressGrouping) IsMax 

func (grouping *IPv6v4MixedAddressGrouping) IsMax() bool

IsMax returns whether this grouping matches exactly the maximum possible value, the value whose bits are all ones.

func (*IPv6v4MixedAddressGrouping) IsMultiple 

func (grouping *IPv6v4MixedAddressGrouping) IsMultiple() bool

IsMultiple returns whether this grouping represents multiple values.

func (*IPv6v4MixedAddressGrouping) IsPrefixBlock 

func (grouping *IPv6v4MixedAddressGrouping) IsPrefixBlock() bool

IsPrefixBlock returns whether this address division series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*IPv6v4MixedAddressGrouping) IsPrefixed 

func (grouping *IPv6v4MixedAddressGrouping) IsPrefixed() bool

IsPrefixed returns whether this grouping has an associated prefix length.

func (*IPv6v4MixedAddressGrouping) IsSinglePrefixBlock 

func (grouping *IPv6v4MixedAddressGrouping) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range of values matches a single subnet block for the prefix length.

What distinguishes this method with ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPv6v4MixedAddressGrouping) IsZero 

func (grouping *IPv6v4MixedAddressGrouping) IsZero() bool

IsZero returns whether this grouping matches exactly the value of zero.

func (*IPv6v4MixedAddressGrouping) String 

func (grouping *IPv6v4MixedAddressGrouping) String() string

String implements the fmt.Stringer interface, as a slice string with each division converted to a string by String ( ie "[ div0 div1 ...]"), or "<nil>" if the receiver is a nil pointer.

func (*IPv6v4MixedAddressGrouping) ToDivGrouping 

func (grouping *IPv6v4MixedAddressGrouping) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToMixedIPv6v4.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6v4MixedAddressGrouping) UpperBytes 

func (grouping *IPv6v4MixedAddressGrouping) UpperBytes() []byte

UpperBytes returns the highest individual division grouping in this grouping as a byte slice.

type Inet_aton_radix 

type Inet_aton_radix int

Inet_aton_radix represents a radix for printing an address string. 

const (
	Inet_aton_radix_octal   Inet_aton_radix = 8
	Inet_aton_radix_hex     Inet_aton_radix = 16
	Inet_aton_radix_decimal Inet_aton_radix = 10
)

func (Inet_aton_radix) GetRadix 

func (rad Inet_aton_radix) GetRadix() int

GetRadix converts the radix to an int.

func (Inet_aton_radix) GetSegmentStrPrefix 

func (rad Inet_aton_radix) GetSegmentStrPrefix() string

GetSegmentStrPrefix returns the string prefix used to identify the radix.

func (Inet_aton_radix) String 

func (rad Inet_aton_radix) String() string

String returns the name of the radix.

type IteratePartitionConstraint added in v1.5.0 

type IteratePartitionConstraint[T any] interface {
	AddressDivisionSeries

	PrefixedConstraint[T]

	AssignMinPrefixForBlock() T
	PrefixBlockIterator() Iterator[T]
	Iterator() Iterator[T]
}

IteratePartitionConstraint is the generic type constraint for IP subnet and IP section iteration partitions.

type Iterator added in v1.5.0 

type Iterator[T any] interface {
	// HasNext returns true if there is another item to iterate, false otherwise.
	HasNext() bool

	// Next returns the next item, or the zero value for T if there is none left.
	Next() T
}

Iterator iterates collections, such as subnets and sequential address ranges.

func NewFilteredAddrIterator 

func NewFilteredAddrIterator(iter Iterator[*Address], skip func(*Address) bool) Iterator[*Address]

NewFilteredAddrIterator modifies an address iterator to skip certain addresses, skipping those elements for which the "skip" function returns true

func NewFilteredIPAddrIterator 

func NewFilteredIPAddrIterator(iter Iterator[*IPAddress], skip func(*IPAddress) bool) Iterator[*IPAddress]

NewFilteredIPAddrIterator returns an iterator similar to the passed in iterator, but skipping those elements for which the "skip" function returns true

type IteratorWithRemove added in v1.5.0 

type IteratorWithRemove[T any] interface {
	Iterator[T]

	// Remove removes the last iterated item from the underlying data structure or collection, and returns that element.
	// If there is no such element, it returns the zero value for T.
	Remove() T
}

IteratorWithRemove is an iterator that provides a removal operation.

type Key added in v1.5.0 

type Key[T KeyConstraint[T]] struct {
	// contains filtered or unexported fields
}

Key is a representation of an address that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators

It can be used as a map key. It can be obtained from its originating address instances. The zero value corresponds to the zero-value for its generic address type. Keys do not incorporate prefix length to ensure that all equal addresses have equal keys. To create a key that has prefix length, combine into a struct with the PrefixKey obtained by passing the address into PrefixKeyFrom.

func (Key[T]) String added in v1.5.0 

func (key Key[T]) String() string

String calls the String method in the corresponding address.

func (Key[T]) ToAddress added in v1.5.0 

func (key Key[T]) ToAddress() T

ToAddress converts back to an address instance.

type KeyConstraint added in v1.5.0 

type KeyConstraint[T any] interface {
	fmt.Stringer
	// contains filtered or unexported methods
}

KeyConstraint is the generic type constraint for an address type that can be generated from a generic address key.

type KeyGeneratorConstraint added in v1.5.1 

type KeyGeneratorConstraint[T KeyConstraint[T]] interface {
	ToGenericKey() Key[T]
}

KeyGeneratorConstraint is the generic type constraint for an address type that can generate a generic address key.

type MACAddress 

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

MACAddress represents a MAC address, or a collection of multiple individual MAC addresses. Each segment can represent a single byte value or a range of byte values.

You can construct a MAC address from a byte slice, from a uint64, from a SegmentValueProvider, from a MACAddressSection of 6 or 8 segments, or from an array of 6 or 8 MACAddressSegment instances.

To construct one from a string, use NewMACAddressString, then use the ToAddress or GetAddress method of MACAddressString.

func NewMACAddress 

func NewMACAddress(section *MACAddressSection) (*MACAddress, addrerr.AddressValueError)

NewMACAddress constructs a MAC address or address collection from the given segments.

func NewMACAddressFromBytes 

func NewMACAddressFromBytes(bytes net.HardwareAddr) (*MACAddress, addrerr.AddressValueError)

NewMACAddressFromBytes constructs a MAC address from the given byte slice. An error is returned when the byte slice has too many bytes to match the maximum MAC segment count of 8. There should be 8 bytes or less, although extra leading zeros are tolerated.

func NewMACAddressFromRange 

func NewMACAddressFromRange(vals, upperVals MACSegmentValueProvider) (addr *MACAddress)

NewMACAddressFromRange constructs a 6-byte MAC address collection from the given values.

func NewMACAddressFromRangeExt 

func NewMACAddressFromRangeExt(vals, upperVals MACSegmentValueProvider, isExtended bool) (addr *MACAddress)

NewMACAddressFromRangeExt constructs a 6 or 8-byte MAC address collection from the given values. If isExtended is true, it will be 8 bytes.

func NewMACAddressFromSegs added in v1.2.0 

func NewMACAddressFromSegs(segments []*MACAddressSegment) (*MACAddress, addrerr.AddressValueError)

NewMACAddressFromSegs constructs a MAC address or address collection from the given segments. If the given slice does not have either 6 or 8 segments, an error is returned.

func NewMACAddressFromUint64Ext 

func NewMACAddressFromUint64Ext(val uint64, isExtended bool) *MACAddress

NewMACAddressFromUint64Ext constructs a 6 or 8-byte MAC address from the given value. If isExtended is true, it is an 8-byte address, 6 otherwise. If 6 bytes, then the bytes are taken from the lower 48 bits of the uint64.

func NewMACAddressFromVals 

func NewMACAddressFromVals(vals MACSegmentValueProvider) (addr *MACAddress)

NewMACAddressFromVals constructs a 6-byte MAC address from the given values.

func NewMACAddressFromValsExt 

func NewMACAddressFromValsExt(vals MACSegmentValueProvider, isExtended bool) (addr *MACAddress)

NewMACAddressFromValsExt constructs a 6 or 8-byte MAC address from the given values. If isExtended is true, it will be 8 bytes.

func (*MACAddress) AdjustPrefixLen 

func (addr *MACAddress) AdjustPrefixLen(prefixLen BitCount) *MACAddress

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*MACAddress) AdjustPrefixLenZeroed 

func (addr *MACAddress) AdjustPrefixLenZeroed(prefixLen BitCount) (*MACAddress, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*MACAddress) AssignMinPrefixForBlock 

func (addr *MACAddress) AssignMinPrefixForBlock() *MACAddress

AssignMinPrefixForBlock returns an equivalent subnet, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this subnet.

In other words, this method assigns a prefix length to this subnet matching the largest prefix block in this subnet.

func (*MACAddress) AssignPrefixForSingleBlock 

func (addr *MACAddress) AssignPrefixForSingleBlock() *MACAddress

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address - it is required that the range of values match the range of a prefix block. If there is no such address, then nil is returned.

func (*MACAddress) BlockIterator 

func (addr *MACAddress) BlockIterator(segmentCount int) Iterator[*MACAddress]

BlockIterator iterates through the addresses that can be obtained by iterating through all the upper segments up to the given segment count. The segments following remain the same in all iterated addresses.

func (*MACAddress) Bytes 

func (addr *MACAddress) Bytes() []byte

Bytes returns the lowest address in this address or address collection as a byte slice.

func (*MACAddress) Compare 

func (addr *MACAddress) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address or address collection is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*MACAddress) CompareSize 

func (addr *MACAddress) CompareSize(other AddressItem) int

CompareSize compares the counts of two addresses or address collections or address items, the number of individual addresses or items within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one address collection represents more individual addresses than another.

CompareSize returns a positive integer if this address or address collection has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.

func (*MACAddress) Contains 

func (addr *MACAddress) Contains(other AddressType) bool

Contains returns whether this is the same type and version as the given address or subnet and whether it contains all addresses in the given address or subnet.

func (*MACAddress) ContainsPrefixBlock 

func (addr *MACAddress) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or address collection contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*MACAddress) ContainsSinglePrefixBlock 

func (addr *MACAddress) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*MACAddress) CopyBytes 

func (addr *MACAddress) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address in the address collection into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddress) CopyHardwareAddr 

func (addr *MACAddress) CopyHardwareAddr(bytes net.HardwareAddr) net.HardwareAddr

CopyHardwareAddr copies the value of the lowest individual address in the address collection into a net.HardwareAddr.

If the value can fit in the given net.HardwareAddr, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new net.HardwareAddr is created and returned with the value.

func (*MACAddress) CopySegments 

func (addr *MACAddress) CopySegments(segs []*MACAddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*MACAddress) CopySubSegments 

func (addr *MACAddress) CopySubSegments(start, end int, segs []*MACAddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*MACAddress) CopyUpperBytes 

func (addr *MACAddress) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address in the address collection into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddress) CopyUpperHardwareAddr 

func (addr *MACAddress) CopyUpperHardwareAddr(bytes net.HardwareAddr) net.HardwareAddr

CopyUpperHardwareAddr copies the value of the highest individual address in the address collection into a net.HardwareAddr.

If the value can fit in the given net.HardwareAddr, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new net.HardwareAddr is created and returned with the value.

func (*MACAddress) Equal 

func (addr *MACAddress) Equal(other AddressType) bool

Equal returns whether the given address or address collection is equal to this address or address collection. Two address instances are equal if they represent the same set of addresses.

func (*MACAddress) ForEachSegment added in v1.2.0 

func (addr *MACAddress) ForEachSegment(consumer func(segmentIndex int, segment *MACAddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (MACAddress) Format 

func (addr MACAddress) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*MACAddress) GetBitCount 

func (addr *MACAddress) GetBitCount() BitCount

GetBitCount returns the number of bits comprising this address, or each address in the range.

func (*MACAddress) GetBitsPerSegment 

func (addr *MACAddress) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this address. Segments in the same address are equal length.

func (*MACAddress) GetBlockCount 

func (addr *MACAddress) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*MACAddress) GetByteCount 

func (addr *MACAddress) GetByteCount() int

GetByteCount returns the number of bytes required for this address, or each address in the range.

func (*MACAddress) GetBytesPerSegment 

func (addr *MACAddress) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this address. Segments in the same address are equal length.

func (*MACAddress) GetCount 

func (addr *MACAddress) GetCount() *big.Int

GetCount returns the count of addresses that this address or address collection represents.

If just a single address, not a collection of multiple addresses, returns 1.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*MACAddress) GetDivisionCount 

func (addr *MACAddress) GetDivisionCount() int

GetDivisionCount returns the segment count, implementing the interface AddressDivisionSeries.

func (*MACAddress) GetDottedAddress 

func (addr *MACAddress) GetDottedAddress() (*AddressDivisionGrouping, addrerr.IncompatibleAddressError)

GetDottedAddress returns an AddressDivisionGrouping which organizes the address into segments of bit-length 16, rather than the more typical 8 bits per segment.

If this represents a collection of MAC addresses, this returns an error when unable to join two address segments, the first with a range of values, into a division of the larger bit-length that represents the same set of values.

func (*MACAddress) GetGenericDivision 

func (addr *MACAddress) GetGenericDivision(index int) DivisionType

GetGenericDivision returns the segment at the given index as a DivisionType.

func (*MACAddress) GetGenericSegment 

func (addr *MACAddress) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (*MACAddress) GetHardwareAddr 

func (addr *MACAddress) GetHardwareAddr() net.HardwareAddr

GetHardwareAddr returns the lowest address in this address or address collection as a net.HardwareAddr.

func (*MACAddress) GetLower 

func (addr *MACAddress) GetLower() *MACAddress

GetLower returns the address in the collection with the lowest numeric value, which will be the receiver if it represents a single address. For example, for "1:1:1:2-3:4:5-6", the series "1:1:1:2:4:5" is returned.

func (*MACAddress) GetMaxSegmentValue 

func (addr *MACAddress) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*MACAddress) GetMinPrefixLenForBlock 

func (addr *MACAddress) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

func (*MACAddress) GetODISection 

func (addr *MACAddress) GetODISection() *MACAddressSection

GetODISection returns a section with the segments following the first 3 segments, the organizational distinct identifier

func (*MACAddress) GetOUISection 

func (addr *MACAddress) GetOUISection() *MACAddressSection

GetOUISection returns a section with the first 3 segments, the organizational unique identifier

func (*MACAddress) GetPrefixCount 

func (addr *MACAddress) GetPrefixCount() *big.Int

GetPrefixCount returns the count of prefixes in this address or subnet.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the count of the range of values in the prefix.

If this has a nil prefix length, returns the same value as GetCount.

func (*MACAddress) GetPrefixCountLen 

func (addr *MACAddress) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the count of prefixes in this address or subnet for the given prefix length.

If not a subnet of multiple addresses, or a subnet with just single prefix of the given length, returns 1.

func (*MACAddress) GetPrefixLen 

func (addr *MACAddress) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part (most significant bits) of the address that comprise the prefix.

A prefix is a part of the address that is not specific to that address but common amongst a group of addresses, such as a CIDR prefix block subnet.

For IP addresses, the prefix is explicitly defined when the address is created. For example, "1.2.0.0/16" has a prefix length of 16, while "1.2.*.*" has no prefix length, even though they both represent the same set of addresses and are considered equal. Prefixes can be considered variable for a given IP address and can depend on routing.

The methods GetMinPrefixLenForBlock and GetPrefixLenForSingleBlock can help you to obtain or define a prefix length if one does not exist already. The method ToPrefixBlockLen allows you to create the subnet consisting of the block of addresses for any given prefix length.

For MAC addresses, the prefix is initially inferred from the range, so "1:2:3:*:*:*" has a prefix length of 24. MAC addresses derived from an address with a prefix length may retain the prefix length regardless of their own range of values.

func (*MACAddress) GetPrefixLenForSingleBlock 

func (addr *MACAddress) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address collection matches the block of addresses for that prefix.

If the range can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix exists, returns nil.

If this segment grouping represents a single value, this returns the bit length of this address.

func (*MACAddress) GetSection 

func (addr *MACAddress) GetSection() *MACAddressSection

GetSection returns the backing section for this address or address collection, comprising all segments.

func (*MACAddress) GetSegment 

func (addr *MACAddress) GetSegment(index int) *MACAddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (*MACAddress) GetSegmentCount 

func (addr *MACAddress) GetSegmentCount() int

GetSegmentCount returns the segment/division count

func (*MACAddress) GetSegmentStrings 

func (addr *MACAddress) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*MACAddress) GetSegments 

func (addr *MACAddress) GetSegments() []*MACAddressSegment

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this address.

func (*MACAddress) GetSequentialBlockCount 

func (addr *MACAddress) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address ranges that comprise this address collection.

func (*MACAddress) GetSequentialBlockIndex 

func (addr *MACAddress) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address collection to be sequential, the preceding segments must be single-valued.

func (*MACAddress) GetSubSection 

func (addr *MACAddress) GetSubSection(index, endIndex int) *MACAddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*MACAddress) GetTrailingSection 

func (addr *MACAddress) GetTrailingSection(index int) *MACAddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*MACAddress) GetUpper 

func (addr *MACAddress) GetUpper() *MACAddress

GetUpper returns the address in the collection with the highest numeric value, which will be the receiver if it represents a single address. For example, for "1:1:1:2-3:4:5-6", the series "1:1:1:3:4:6" is returned.

func (*MACAddress) GetUpperHardwareAddr 

func (addr *MACAddress) GetUpperHardwareAddr() net.HardwareAddr

GetUpperHardwareAddr returns the highest address in this address or address collection as a net.HardwareAddr.

func (*MACAddress) GetUpperValue 

func (addr *MACAddress) GetUpperValue() *big.Int

GetUpperValue returns the highest address in this subnet or address as an integer value.

func (*MACAddress) GetValue 

func (addr *MACAddress) GetValue() *big.Int

GetValue returns the lowest address in this subnet or address as an integer value.

func (*MACAddress) IncludesMax 

func (addr *MACAddress) IncludesMax() bool

IncludesMax returns whether this address includes the max address, the address whose bits are all ones, within its range.

func (*MACAddress) IncludesZero 

func (addr *MACAddress) IncludesZero() bool

IncludesZero returns whether this address includes the zero address within its range.

func (*MACAddress) Increment 

func (addr *MACAddress) Increment(increment int64) *MACAddress

Increment returns the address from the address collection that is the given increment upwards into the address range, with the increment of 0 returning the first address in the range.

If the increment i matches or exceeds the size count c, then i - c + 1 is added to the upper address of the range. An increment matching the range count gives you the address just above the highest address in the range.

If the increment is negative, it is added to the lower address of the range. To get the address just below the lowest address of the address range, use the increment -1.

If this is just a single address value, the address is simply incremented by the given increment, positive or negative.

If this is an address range with multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the range count is equivalent to the same number of iterator values preceding the upper bound of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On address overflow or underflow, Increment returns nil.

func (*MACAddress) IncrementBoundary 

func (addr *MACAddress) IncrementBoundary(increment int64) *MACAddress

IncrementBoundary returns the address that is the given increment from the range boundaries of this address collection.

If the given increment is positive, adds the value to the upper address (GetUpper) in the range to produce a new address. If the given increment is negative, adds the value to the lower address (GetLower) in the range to produce a new address. If the increment is zero, returns this address.

If this is a single address value, that address is simply incremented by the given increment value, positive or negative.

On address overflow or underflow, IncrementBoundary returns nil.

func (*MACAddress) IsEUI64 

func (addr *MACAddress) IsEUI64(asMAC bool) bool

IsEUI64 returns whether this section is consistent with an IPv6 EUI64Size section, which means it came from an extended 8 byte address, and the corresponding segments in the middle match 0xff and 0xff/fe for MAC/not-MAC

func (*MACAddress) IsFullRange 

func (addr *MACAddress) IsFullRange() bool

IsFullRange returns whether this address covers the entire MAC address space for its MAC bit length.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*MACAddress) IsLocal 

func (addr *MACAddress) IsLocal() bool

IsLocal returns whether this is a local address. Local MAC addresses have the second least significant bit of the first octet set to 1.

func (*MACAddress) IsMax 

func (addr *MACAddress) IsMax() bool

IsMax returns whether this address matches exactly the maximum possible value, the address whose bits are all ones.

func (*MACAddress) IsMulticast 

func (addr *MACAddress) IsMulticast() bool

IsMulticast returns whether this address or collection of addresses is entirely multicast. Multicast MAC addresses have the least significant bit of the first octet set to 1.

func (*MACAddress) IsMultiple 

func (addr *MACAddress) IsMultiple() bool

IsMultiple returns true if this represents more than a single individual address, whether it is a collection of multiple addresses.

func (*MACAddress) IsOneBit 

func (addr *MACAddress) IsOneBit(bitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*MACAddress) IsPrefixBlock 

func (addr *MACAddress) IsPrefixBlock() bool

IsPrefixBlock returns whether the address has a prefix length and the address range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

To create a prefix block from any address, use ToPrefixBlock.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*MACAddress) IsPrefixed 

func (addr *MACAddress) IsPrefixed() bool

IsPrefixed returns whether this address has an associated prefix length.

func (*MACAddress) IsSequential 

func (addr *MACAddress) IsSequential() bool

IsSequential returns whether the address or subnet represents a range of addresses that are sequential.

Generally, for a subnet this means that any segment covering a range of values must be followed by segments that are full range, covering all values.

Individual addresses are sequential and CIDR prefix blocks are sequential. The subnet "1.2.3-4.5" is not sequential, since the two addresses it represents, "1.2.3.5" and "1.2.4.5", are not ("1.2.3.6" is in-between the two but not in the subnet).

With any IP address subnet, you can use SequentialBlockIterator to convert any subnet to a collection of sequential subnets.

func (*MACAddress) IsSinglePrefixBlock 

func (addr *MACAddress) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the address range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

For instance, "1.*.*.* /16" returns false from this method and returns true from IsPrefixBlock.

func (*MACAddress) IsUnicast 

func (addr *MACAddress) IsUnicast() bool

IsUnicast returns whether this address or collection of addresses is entirely unicast. Unicast MAC addresses have the least significant bit of the first octet set to 0.

func (*MACAddress) IsUniversal 

func (addr *MACAddress) IsUniversal() bool

IsUniversal returns whether this is a universal address. Universal MAC addresses have second the least significant bit of the first octet set to 0.

func (*MACAddress) IsZero 

func (addr *MACAddress) IsZero() bool

IsZero returns whether this address matches exactly the value of zero.

func (*MACAddress) Iterator 

func (addr *MACAddress) Iterator() Iterator[*MACAddress]

Iterator provides an iterator to iterate through the individual addresses of this address or subnet.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual addresses.

Call IsMultiple to determine if this instance represents multiple addresses, or GetCount for the count.

func (*MACAddress) PrefixBlockIterator 

func (addr *MACAddress) PrefixBlockIterator() Iterator[*MACAddress]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address or subnet. Each iterated address or subnet will be a prefix block with the same prefix length as this address or subnet.

If this address has no prefix length, then this is equivalent to Iterator.

func (*MACAddress) PrefixContains 

func (addr *MACAddress) PrefixContains(other AddressType) bool

PrefixContains returns whether the prefix values in the given address are prefix values in this address, using the prefix length of this address. If this address has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

func (*MACAddress) PrefixEqual 

func (addr *MACAddress) PrefixEqual(other AddressType) bool

PrefixEqual determines if the given address matches this address up to the prefix length of this address. It returns whether the two addresses share the same range of prefix values.

func (*MACAddress) PrefixIterator 

func (addr *MACAddress) PrefixIterator() Iterator[*MACAddress]

PrefixIterator provides an iterator to iterate through the individual prefixes of this subnet, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this subnet.

If the subnet has no prefix length, then this is equivalent to Iterator.

func (*MACAddress) Replace 

func (addr *MACAddress) Replace(startIndex int, replacement *MACAddressSection) *MACAddress

Replace replaces segments starting from startIndex with segments from the replacement section.

func (*MACAddress) ReplaceLen 

func (addr *MACAddress) ReplaceLen(startIndex, endIndex int, replacement *MACAddress, replacementIndex int) *MACAddress

ReplaceLen replaces segments starting from startIndex and ending before endIndex with the same number of segments starting at replacementStartIndex from the replacement section. Mappings to or from indices outside the range of this or the replacement address are skipped.

func (*MACAddress) ReverseBits 

func (addr *MACAddress) ReverseBits(perByte bool) (*MACAddress, addrerr.IncompatibleAddressError)

ReverseBits returns a new address with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*MACAddress) ReverseBytes 

func (addr *MACAddress) ReverseBytes() *MACAddress

ReverseBytes returns a new address with the bytes reversed. Any prefix length is dropped.

func (*MACAddress) ReverseSegments 

func (addr *MACAddress) ReverseSegments() *MACAddress

ReverseSegments returns a new address with the segments reversed.

func (*MACAddress) SequentialBlockIterator 

func (addr *MACAddress) SequentialBlockIterator() Iterator[*MACAddress]

SequentialBlockIterator iterates through the sequential subnets or addresses that make up this address or subnet.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

For instance, given the IPv4 subnet "1-2.3-4.5-6.7-8", it will iterate through "1.3.5.7-8", "1.3.6.7-8", "1.4.5.7-8", "1.4.6.7-8", "2.3.5.7-8", "2.3.6.7-8", "2.4.6.7-8" and "2.4.6.7-8".

Use GetSequentialBlockCount to get the number of iterated elements.

func (*MACAddress) SetPrefixLen 

func (addr *MACAddress) SetPrefixLen(prefixLen BitCount) *MACAddress

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address. The provided prefix length will be adjusted to these boundaries if necessary.

func (*MACAddress) SetPrefixLenZeroed 

func (addr *MACAddress) SetPrefixLenZeroed(prefixLen BitCount) (*MACAddress, addrerr.IncompatibleAddressError)

func (*MACAddress) String 

func (addr *MACAddress) String() string

String implements the fmt.Stringer interface, returning the canonical string provided by ToCanonicalString, or "<nil>" if the receiver is a nil pointer.

func (*MACAddress) TestBit 

func (addr *MACAddress) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this address. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*MACAddress) ToAddressBase 

func (addr *MACAddress) ToAddressBase() *Address

ToAddressBase converts to an Address, a polymorphic type usable with all addresses and subnets. Afterwards, you can convert back with ToMAC.

ToAddressBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*MACAddress) ToAddressString 

func (addr *MACAddress) ToAddressString() *MACAddressString

ToAddressString retrieves or generates a MACAddressString instance for this MACAddress instance. This may be the MACAddressString this instance was generated from, if it was generated from a MACAddressString.

In general, users are intended to create MACAddress instances from MACAddressString instances, while the reverse direction is generally not common and not useful, except under specific circumstances.

However, the reverse direction can be useful under certain circumstances, such as when maintaining a collection of MACAddressString instances.

func (*MACAddress) ToBinaryString 

func (addr *MACAddress) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If an address collection cannot be written as a range of two values, an error is returned.

func (*MACAddress) ToBlock 

func (addr *MACAddress) ToBlock(segmentIndex int, lower, upper SegInt) *MACAddress

ToBlock creates a new block of addresses by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*MACAddress) ToCanonicalString 

func (addr *MACAddress) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address.

For MAC, it uses the canonical standardized IEEE 802 MAC address representation of xx-xx-xx-xx-xx-xx. An example is "01-23-45-67-89-ab". For range segments, '|' is used: "11-22-33|44-55-66".

Each MAC address has a unique canonical string.

func (*MACAddress) ToColonDelimitedString 

func (addr *MACAddress) ToColonDelimitedString() string

ToColonDelimitedString produces a string delimited by colons: "aa:bb:cc:dd:ee:ff". For range segments, '-' is used: "11:22:33-44:55:66". It returns the same string as ToNormalizedString.

func (*MACAddress) ToCompressedString 

func (addr *MACAddress) ToCompressedString() string

ToCompressedString produces a short representation of this address while remaining within the confines of standard representation(s) of the address.

For MAC, it differs from the canonical string. It produces a shorter string for the address that has no leading zeros.

func (*MACAddress) ToCustomString 

func (addr *MACAddress) ToCustomString(stringOptions addrstr.StringOptions) string

ToCustomString creates a customized string from this address or address collection according to the given string option parameters.

func (*MACAddress) ToDashedString 

func (addr *MACAddress) ToDashedString() string

ToDashedString produces a string delimited by dashes: "aa-bb-cc-dd-ee-ff". For range segments, '|' is used: "11-22-33|44-55-66". It returns the same string as ToCanonicalString.

func (*MACAddress) ToDottedString 

func (addr *MACAddress) ToDottedString() (string, addrerr.IncompatibleAddressError)

ToDottedString produces the dotted hexadecimal format aaaa.bbbb.cccc

func (*MACAddress) ToEUI64 

func (addr *MACAddress) ToEUI64(asMAC bool) (*MACAddress, addrerr.IncompatibleAddressError)

ToEUI64 converts to IPv6 EUI-64 section

http://standards.ieee.org/develop/regauth/tut/eui64.pdf

If asMAC if true, this address is considered MAC and the EUI-64 is extended using ff-ff, otherwise this address is considered EUI-48 and extended using ff-fe Note that IPv6 treats MAC as EUI-48 and extends MAC to IPv6 addresses using ff-fe

func (*MACAddress) ToEUI64IPv6 

func (addr *MACAddress) ToEUI64IPv6() (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ToEUI64IPv6 converts to an Ipv6 address section. Any MAC prefix length is ignored. Other elements of this address section are incorporated into the conversion. This will provide the latter 4 segments of an IPv6 address, to be paired with an IPv6 prefix of 4 segments.

func (*MACAddress) ToGenericKey added in v1.5.1 

func (addr *MACAddress) ToGenericKey() Key[*MACAddress]

ToGenericKey produces a generic Key[*MACAddress] that can be used with generic code working with Address, IPAddress, IPv4Address, IPv6Address and MACAddress. ToKey produces a more compact key for code that is MAC-specific.

func (*MACAddress) ToHexString 

func (addr *MACAddress) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address as a single hexadecimal value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If an address collection cannot be written as a range of two values, an error is returned.

func (*MACAddress) ToKey added in v1.1.0 

func (addr *MACAddress) ToKey() MACAddressKey

ToKey creates the associated address key. While addresses can be compared with the Compare, TrieCompare or Equal methods as well as various provided instances of AddressComparator, they are not comparable with Go operators. However, AddressKey instances are comparable with Go operators, and thus can be used as map keys.

func (*MACAddress) ToLinkLocalIPv6 

func (addr *MACAddress) ToLinkLocalIPv6() (*IPv6Address, addrerr.IncompatibleAddressError)

ToLinkLocalIPv6 converts to a link-local Ipv6 address. Any MAC prefix length is ignored. Other elements of this address section are incorporated into the conversion. This will provide the latter 4 segments of an IPv6 address, to be paired with the link-local IPv6 prefix of 4 segments.

func (*MACAddress) ToNormalizedString 

func (addr *MACAddress) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For MAC, it differs from the canonical string. It uses the most common representation of MAC addresses: "xx:xx:xx:xx:xx:xx". An example is "01:23:45:67:89:ab". For range segments, '-' is used: "11:22:33-44:55:66".

Each address has a unique normalized string.

func (*MACAddress) ToNormalizedWildcardString added in v1.5.0 

func (addr *MACAddress) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces the normalized string.

func (*MACAddress) ToOUIPrefixBlock 

func (addr *MACAddress) ToOUIPrefixBlock() *MACAddress

ToOUIPrefixBlock returns a section in which the range of values match the full block for the OUI (organizationally unique identifier) bytes

func (*MACAddress) ToOctalString 

func (addr *MACAddress) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address as a single octal value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued address collection cannot be written as a single prefix block or a range of two values, an error is returned.

func (*MACAddress) ToPrefixBlock 

func (addr *MACAddress) ToPrefixBlock() *MACAddress

ToPrefixBlock returns the address associated with the prefix of this address or address collection, the address whose prefix matches the prefix of this address, and the remaining bits span all values. If this address has no prefix length, this address is returned.

The returned address collection will include all addresses with the same prefix as this one, the prefix "block".

func (*MACAddress) ToPrefixBlockLen added in v1.2.0 

func (addr *MACAddress) ToPrefixBlockLen(prefLen BitCount) *MACAddress

ToPrefixBlockLen returns the address associated with the prefix length provided, the address collection whose prefix of that length matches the prefix of this address, and the remaining bits span all values.

The returned address will include all addresses with the same prefix as this one, the prefix "block".

func (*MACAddress) ToSinglePrefixBlockOrAddress added in v1.1.0 

func (addr *MACAddress) ToSinglePrefixBlockOrAddress() *MACAddress

ToSinglePrefixBlockOrAddress converts to a single prefix block or address. If the given address is a single prefix block, it is returned. If it can be converted to a single prefix block by assigning a prefix length, the converted block is returned. If it is a single address, any prefix length is removed and the address is returned. Otherwise, nil is returned. This method provides the address formats used by tries. ToSinglePrefixBlockOrAddress is quite similar to AssignPrefixForSingleBlock, which always returns prefixed addresses, while this does not.

func (*MACAddress) ToSpaceDelimitedString 

func (addr *MACAddress) ToSpaceDelimitedString() string

ToSpaceDelimitedString produces a string delimited by spaces: aa bb cc dd ee ff

func (*MACAddress) TrieCompare added in v1.1.0 

func (addr *MACAddress) TrieCompare(other *MACAddress) (int, addrerr.IncompatibleAddressError)

TrieCompare compares two addresses according to address trie ordering. It returns a number less than zero, zero, or a number greater than zero if the first address argument is less than, equal to, or greater than the second.

The comparison is intended for individual addresses and CIDR prefix blocks. If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*MACAddress) TrieDecrement added in v1.1.0 

func (addr *MACAddress) TrieDecrement() *MACAddress

TrieDecrement returns the previous address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*MACAddress) TrieIncrement added in v1.1.0 

func (addr *MACAddress) TrieIncrement() *MACAddress

TrieIncrement returns the next address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*MACAddress) Uint64Value 

func (addr *MACAddress) Uint64Value() uint64

Uint64Value returns the lowest address in the address collection as a uint64.

func (*MACAddress) UpperBytes 

func (addr *MACAddress) UpperBytes() []byte

UpperBytes returns the highest address in this address or address collection as a byte slice.

func (*MACAddress) UpperUint64Value 

func (addr *MACAddress) UpperUint64Value() uint64

UpperUint64Value returns the highest address in the address collection as a uint64.

func (*MACAddress) WithoutPrefixLen 

func (addr *MACAddress) WithoutPrefixLen() *MACAddress

WithoutPrefixLen provides the same address but with no prefix length. The values remain unchanged.

func (*MACAddress) Wrap 

func (addr *MACAddress) Wrap() WrappedAddress

Wrap wraps this address, returning a WrappedAddress, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections.

type MACAddressKey added in v1.1.0 

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

MACAddressKey is a representation of a MAC address that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators

It can be used as a map key. It can be obtained from its originating address instances. The zero value corresponds to the zero-value for MACAddress. Keys do not incorporate prefix length to ensure that all equal addresses have equal keys. To create a key that has prefix length, combine into a struct with the PrefixKey obtained by passing the address into PrefixKeyFrom. MACAddress can be compared using the Compare or Equal methods, or using an AddressComparator.

func (MACAddressKey) String added in v1.1.1 

func (key MACAddressKey) String() string

String calls the String method in the corresponding address.

func (MACAddressKey) ToAddress added in v1.1.0 

func (key MACAddressKey) ToAddress() *MACAddress

ToAddress converts back to an address instance.

type MACAddressSection 

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

MACAddressSection is a section of a MACAddress.

It is a series of 0 to 8 individual MAC address segments.

func NewMACSection 

func NewMACSection(segments []*MACAddressSegment) *MACAddressSection

NewMACSection constructs a MAC address or address collection section from the given segments.

func NewMACSectionFromBytes 

func NewMACSectionFromBytes(bytes []byte, segmentCount int) (res *MACAddressSection, err addrerr.AddressValueError)

NewMACSectionFromBytes constructs a MAC address section from the given byte slice. The segment count is determined by the slice length, even if the segment count exceeds 8 segments.

func NewMACSectionFromRange 

func NewMACSectionFromRange(vals, upperVals MACSegmentValueProvider, segmentCount int) (res *MACAddressSection)

NewMACSectionFromRange constructs a MAC address collection section of the given segment count from the given values.

func NewMACSectionFromUint64 

func NewMACSectionFromUint64(val uint64, segmentCount int) (res *MACAddressSection)

NewMACSectionFromUint64 constructs a MAC address section of the given segment count from the given value. The least significant bits of the given value will be used.

func NewMACSectionFromVals 

func NewMACSectionFromVals(vals MACSegmentValueProvider, segmentCount int) (res *MACAddressSection)

NewMACSectionFromVals constructs a MAC address section of the given segment count from the given values.

func (*MACAddressSection) AdjustPrefixLen 

func (section *MACAddressSection) AdjustPrefixLen(prefixLen BitCount) *AddressSection

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*MACAddressSection) AdjustPrefixLenZeroed 

func (section *MACAddressSection) AdjustPrefixLenZeroed(prefixLen BitCount) (*AddressSection, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*MACAddressSection) Append 

func (section *MACAddressSection) Append(other *MACAddressSection) *MACAddressSection

Append creates a new section by appending the given section to this section.

func (*MACAddressSection) AssignMinPrefixForBlock 

func (section *MACAddressSection) AssignMinPrefixForBlock() *MACAddressSection

AssignMinPrefixForBlock returns an equivalent address section, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this address section.

In other words, this method assigns a prefix length to this address section matching the largest prefix block in this address section.

func (*MACAddressSection) AssignPrefixForSingleBlock 

func (section *MACAddressSection) AssignPrefixForSingleBlock() *MACAddressSection

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address section. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address section - it is required that the range of values match the range of a prefix block. If there is no such address section, then nil is returned.

func (*MACAddressSection) Bytes 

func (section *MACAddressSection) Bytes() []byte

Bytes returns the lowest individual address section in this address section as a byte slice.

func (*MACAddressSection) Compare 

func (section *MACAddressSection) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address section is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*MACAddressSection) CompareSize 

func (section *MACAddressSection) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual items represented.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether this section represents more individual address sections than another.

CompareSize returns a positive integer if this address section has a larger count than the one given, zero if they are the same, or a negative integer if the other has a larger count.

func (*MACAddressSection) Contains 

func (section *MACAddressSection) Contains(other AddressSectionType) bool

Contains returns whether this is same type and version as the given address section and whether it contains all values in the given section.

Sections must also have the same number of segments to be comparable, otherwise false is returned.

func (*MACAddressSection) ContainsPrefixBlock 

func (section *MACAddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*MACAddressSection) ContainsSinglePrefixBlock 

func (section *MACAddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this grouping contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*MACAddressSection) CopyBytes 

func (section *MACAddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddressSection) CopySegments 

func (section *MACAddressSection) CopySegments(segs []*MACAddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*MACAddressSection) CopySubSegments 

func (section *MACAddressSection) CopySubSegments(start, end int, segs []*MACAddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied.

func (*MACAddressSection) CopyUpperBytes 

func (section *MACAddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddressSection) Equal 

func (section *MACAddressSection) Equal(other AddressSectionType) bool

Equal returns whether the given address section is equal to this address section. Two address sections are equal if they represent the same set of sections. They must match:

  • type/version: MAC
  • segment counts
  • segment value ranges

Prefix lengths are ignored.

func (*MACAddressSection) ForEachSegment added in v1.2.0 

func (section *MACAddressSection) ForEachSegment(consumer func(segmentIndex int, segment *MACAddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (MACAddressSection) Format 

func (section MACAddressSection) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*MACAddressSection) GetBitCount 

func (section *MACAddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (*MACAddressSection) GetBitsPerSegment 

func (section *MACAddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (*MACAddressSection) GetBlockCount 

func (section *MACAddressSection) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*MACAddressSection) GetByteCount 

func (section *MACAddressSection) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item.

func (*MACAddressSection) GetBytesPerSegment 

func (section *MACAddressSection) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this section. Segments in the same address section are equal length.

func (*MACAddressSection) GetCount 

func (section *MACAddressSection) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*MACAddressSection) GetDottedGrouping 

func (section *MACAddressSection) GetDottedGrouping() (*AddressDivisionGrouping, addrerr.IncompatibleAddressError)

GetDottedGrouping returns an AddressDivisionGrouping which organizes the address section into segments of bit-length 16, rather than the more typical 8 bits per segment.

If this represents a collection of MAC addresses, this returns an error when unable to join two address segments, the first with a range of values, into a division of the larger bit-length that represents the same set of values.

func (*MACAddressSection) GetGenericSegment 

func (section *MACAddressSection) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment as an AddressSegmentType, allowing all segment types to be represented by a single type. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (*MACAddressSection) GetLeadingBitCount added in v1.1.0 

func (section *MACAddressSection) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower value of the range if this section represents multiple values.

func (*MACAddressSection) GetLower 

func (section *MACAddressSection) GetLower() *MACAddressSection

GetLower returns the section in the range with the lowest numeric value, which will be the same section if it represents a single value. For example, for "1:1:1:2-3:4:5-6", the series "1:1:1:2:4:5" is returned.

func (*MACAddressSection) GetMaxSegmentValue 

func (section *MACAddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*MACAddressSection) GetMinPrefixLenForBlock 

func (section *MACAddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (*MACAddressSection) GetPrefixCount 

func (section *MACAddressSection) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetCount.

func (*MACAddressSection) GetPrefixCountLen 

func (section *MACAddressSection) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length.

func (*MACAddressSection) GetPrefixLen 

func (section *MACAddressSection) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (*MACAddressSection) GetPrefixLenForSingleBlock 

func (section *MACAddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (*MACAddressSection) GetSegment 

func (section *MACAddressSection) GetSegment(index int) *MACAddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (*MACAddressSection) GetSegmentCount 

func (section *MACAddressSection) GetSegmentCount() int

GetSegmentCount returns the segment count.

func (*MACAddressSection) GetSegmentStrings 

func (section *MACAddressSection) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*MACAddressSection) GetSegments 

func (section *MACAddressSection) GetSegments() (res []*MACAddressSegment)

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*MACAddressSection) GetSequentialBlockCount 

func (section *MACAddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section.

func (*MACAddressSection) GetSequentialBlockIndex 

func (section *MACAddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (*MACAddressSection) GetSubSection 

func (section *MACAddressSection) GetSubSection(index, endIndex int) *MACAddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*MACAddressSection) GetTrailingBitCount added in v1.1.0 

func (section *MACAddressSection) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies to the lower value of the range if this section represents multiple values.

func (*MACAddressSection) GetTrailingSection 

func (section *MACAddressSection) GetTrailingSection(index int) *MACAddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*MACAddressSection) GetUpper 

func (section *MACAddressSection) GetUpper() *MACAddressSection

GetUpper returns the section in the range with the highest numeric value, which will be the same section if it represents a single value. For example, for "1:1:1:2-3:4:5-6", the series "1:1:1:3:4:6" is returned.

func (*MACAddressSection) GetUpperValue 

func (section *MACAddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value.

func (*MACAddressSection) GetValue 

func (section *MACAddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value.

func (*MACAddressSection) IncludesMax 

func (section *MACAddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range.

func (*MACAddressSection) IncludesZero 

func (section *MACAddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range.

func (*MACAddressSection) Increment 

func (section *MACAddressSection) Increment(incrementVal int64) *MACAddressSection

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (*MACAddressSection) IncrementBoundary 

func (section *MACAddressSection) IncrementBoundary(increment int64) *MACAddressSection

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (*MACAddressSection) Insert 

func (section *MACAddressSection) Insert(index int, other *MACAddressSection) *MACAddressSection

Insert creates a new section by inserting the given section into this section at the given index.

func (*MACAddressSection) IsAdaptiveZero 

func (section *MACAddressSection) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the division grouping was originally created as an implicitly zero-valued section or grouping (e.g. IPv4AddressSection{}), meaning it was not constructed using a constructor function. Such a grouping, which has no divisions or segments, is convertible to an implicitly zero-valued grouping of any type or version, whether IPv6, IPv4, MAC, or other. In other words, when a section or grouping is the zero-value, then it is equivalent and convertible to the zero value of any other section or grouping type.

func (*MACAddressSection) IsFullRange 

func (section *MACAddressSection) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*MACAddressSection) IsMax 

func (section *MACAddressSection) IsMax() bool

IsMax returns whether this section matches exactly the maximum possible value, the value whose bits are all ones.

func (*MACAddressSection) IsMultiple 

func (section *MACAddressSection) IsMultiple() bool

IsMultiple returns whether this section represents multiple values.

func (*MACAddressSection) IsOneBit 

func (section *MACAddressSection) IsOneBit(prefixBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (*MACAddressSection) IsPrefixBlock 

func (section *MACAddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (*MACAddressSection) IsPrefixed 

func (section *MACAddressSection) IsPrefixed() bool

IsPrefixed returns whether this section has an associated prefix length.

func (*MACAddressSection) IsSequential 

func (section *MACAddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (*MACAddressSection) IsSinglePrefixBlock 

func (section *MACAddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from a prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*MACAddressSection) IsZero 

func (section *MACAddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero.

func (*MACAddressSection) Iterator 

func (section *MACAddressSection) Iterator() Iterator[*MACAddressSection]

Iterator provides an iterator to iterate through the individual address sections of this address section.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address sections.

Call IsMultiple to determine if this instance represents multiple address sections, or GetCount for the count.

func (*MACAddressSection) PrefixBlockIterator 

func (section *MACAddressSection) PrefixBlockIterator() Iterator[*MACAddressSection]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this address section. Each iterated address section will be a prefix block with the same prefix length as this address section.

If this address section has no prefix length, then this is equivalent to Iterator.

func (*MACAddressSection) PrefixContains 

func (section *MACAddressSection) PrefixContains(other AddressSectionType) (res bool)

PrefixContains returns whether the prefix values in the given address section are prefix values in this address section, using the prefix length of this section. If this address section has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

All prefix bits of this section must be present in the other section to be comparable.

func (*MACAddressSection) PrefixEqual 

func (section *MACAddressSection) PrefixEqual(other AddressSectionType) (res bool)

PrefixEqual determines if the given section matches this section up to the prefix length of this section. It returns whether the argument section has the same address section prefix values as this.

All prefix bits of this section must be present in the other section to be comparable, otherwise false is returned.

func (*MACAddressSection) PrefixIterator 

func (section *MACAddressSection) PrefixIterator() Iterator[*MACAddressSection]

PrefixIterator provides an iterator to iterate through the individual prefixes of this address section, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this address section.

If the series has no prefix length, then this is equivalent to Iterator.

func (*MACAddressSection) Replace 

func (section *MACAddressSection) Replace(index int, replacement *MACAddressSection) *MACAddressSection

Replace replaces the segments of this section starting at the given index with the given replacement segments.

func (*MACAddressSection) ReplaceLen 

func (section *MACAddressSection) ReplaceLen(startIndex, endIndex int, replacement *MACAddressSection, replacementStartIndex, replacementEndIndex int) *MACAddressSection

ReplaceLen replaces segments starting from startIndex and ending before endIndex with the segments starting at replacementStartIndex and ending before replacementEndIndex from the replacement section.

func (*MACAddressSection) ReverseBits 

func (section *MACAddressSection) ReverseBits(perByte bool) (*MACAddressSection, addrerr.IncompatibleAddressError)

ReverseBits returns a new section with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*MACAddressSection) ReverseBytes 

func (section *MACAddressSection) ReverseBytes() *MACAddressSection

ReverseBytes returns a new section with the bytes reversed. Any prefix length is dropped.

func (*MACAddressSection) ReverseSegments 

func (section *MACAddressSection) ReverseSegments() *MACAddressSection

ReverseSegments returns a new section with the segments reversed.

func (*MACAddressSection) SetPrefixLen 

func (section *MACAddressSection) SetPrefixLen(prefixLen BitCount) *MACAddressSection

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

func (*MACAddressSection) SetPrefixLenZeroed 

func (section *MACAddressSection) SetPrefixLenZeroed(prefixLen BitCount) (*MACAddressSection, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

If this address section has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address section has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*MACAddressSection) String 

func (section *MACAddressSection) String() string

String implements the fmt.Stringer interface, returning the normalized string provided by ToNormalizedString, or "<nil>" if the receiver is a nil pointer.

func (*MACAddressSection) TestBit 

func (section *MACAddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*MACAddressSection) ToBinaryString 

func (section *MACAddressSection) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address section as a single binary value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a multiple-valued section cannot be written as a range of two values, an error is returned.

func (*MACAddressSection) ToBlock 

func (section *MACAddressSection) ToBlock(segmentIndex int, lower, upper SegInt) *MACAddressSection

ToBlock creates a new block of address sections by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*MACAddressSection) ToCanonicalString 

func (section *MACAddressSection) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address section.

For MAC, it uses the canonical standardized IEEE 802 MAC address representation of xx-xx-xx-xx-xx-xx. An example is "01-23-45-67-89-ab". For range segments, '|' is used: "11-22-33|44-55-66".

func (*MACAddressSection) ToColonDelimitedString 

func (section *MACAddressSection) ToColonDelimitedString() string

ToColonDelimitedString produces a string delimited by colons: "aa:bb:cc:dd:ee:ff". For range segments, '-' is used: "11:22:33-44:55:66". It returns the same string as ToNormalizedString.

func (*MACAddressSection) ToCompressedString 

func (section *MACAddressSection) ToCompressedString() string

ToCompressedString produces a short representation of this address section while remaining within the confines of standard representation(s) of the address.

For MAC, it differs from the canonical string. It produces a shorter string for the address that has no leading zeros.

func (*MACAddressSection) ToDashedString 

func (section *MACAddressSection) ToDashedString() string

ToDashedString produces a string delimited by dashes: "aa-bb-cc-dd-ee-ff". For range segments, '|' is used: "11-22-33|44-55-66". It returns the same string as ToCanonicalString.

func (*MACAddressSection) ToDivGrouping 

func (section *MACAddressSection) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToMAC.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*MACAddressSection) ToDottedString 

func (section *MACAddressSection) ToDottedString() (string, addrerr.IncompatibleAddressError)

ToDottedString produces the dotted hexadecimal format "aaaa.bbbb.cccc".

func (*MACAddressSection) ToHexString 

func (section *MACAddressSection) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address section as a single hexadecimal value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a multiple-valued section cannot be written as a range of two values, an error is returned.

func (*MACAddressSection) ToNormalizedString 

func (section *MACAddressSection) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address section.

For MAC, it differs from the canonical string. It uses the most common representation of MAC addresses: "xx:xx:xx:xx:xx:xx". An example is "01:23:45:67:89:ab". For range segments, '-' is used: "11:22:33-44:55:66".

func (*MACAddressSection) ToNormalizedWildcardString added in v1.5.0 

func (section *MACAddressSection) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces the normalized string.

func (*MACAddressSection) ToOctalString 

func (section *MACAddressSection) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address section as a single octal value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*MACAddressSection) ToPrefixBlock 

func (section *MACAddressSection) ToPrefixBlock() *MACAddressSection

ToPrefixBlock returns the section with the same prefix as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

If this section has no prefix, this section is returned.

func (*MACAddressSection) ToPrefixBlockLen 

func (section *MACAddressSection) ToPrefixBlockLen(prefLen BitCount) *MACAddressSection

ToPrefixBlockLen returns the section with the same prefix of the given length as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

func (*MACAddressSection) ToSectionBase 

func (section *MACAddressSection) ToSectionBase() *AddressSection

ToSectionBase converts to an AddressSection, a polymorphic type usable with all address sections. Afterwards, you can convert back with ToMAC.

ToSectionBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*MACAddressSection) ToSpaceDelimitedString 

func (section *MACAddressSection) ToSpaceDelimitedString() string

ToSpaceDelimitedString produces a string delimited by spaces: "aa bb cc dd ee ff".

func (*MACAddressSection) Uint64Value 

func (section *MACAddressSection) Uint64Value() uint64

Uint64Value returns the lowest individual address section in the address section collection as a uint64.

func (*MACAddressSection) UpperBytes 

func (section *MACAddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice.

func (*MACAddressSection) UpperUint64Value 

func (section *MACAddressSection) UpperUint64Value() uint64

UpperUint64Value returns the highest individual address section in the address section collection as a uint64.

func (*MACAddressSection) WithoutPrefixLen 

func (section *MACAddressSection) WithoutPrefixLen() *MACAddressSection

WithoutPrefixLen provides the same address section but with no prefix length. The values remain unchanged.

func (*MACAddressSection) Wrap 

func (section *MACAddressSection) Wrap() WrappedAddressSection

Wrap wraps this address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections.

type MACAddressSegment 

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

MACAddressSegment represents a segment of a MAC address. For MAC, segments are 1 byte. A MAC segment contains a single value or a range of sequential values, a prefix length, and it has bit length of 8 bits.

Segments are immutable, which also makes them concurrency-safe.

func NewMACRangeSegment 

func NewMACRangeSegment(val, upperVal MACSegInt) *MACAddressSegment

NewMACRangeSegment constructs a segment of a MAC address collection with the given range of sequential values.

func NewMACSegment 

func NewMACSegment(val MACSegInt) *MACAddressSegment

NewMACSegment constructs a segment of a MAC address with the given value.

func (*MACAddressSegment) Bytes 

func (seg *MACAddressSegment) Bytes() []byte

Bytes returns the lowest value in the address segment range as a byte slice.

func (*MACAddressSegment) Compare 

func (seg *MACAddressSegment) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address segment is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*MACAddressSegment) CompareSize added in v1.3.0 

func (seg *MACAddressSegment) CompareSize(other AddressItem) int

CompareSize compares the counts of two items, the number of individual values within.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether one represents more individual values than another.

CompareSize returns a positive integer if this segment has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*MACAddressSegment) Contains 

func (seg *MACAddressSegment) Contains(other AddressSegmentType) bool

Contains returns whether this is same type and version as the given segment and whether it contains all values in the given segment.

func (*MACAddressSegment) ContainsPrefixBlock 

func (seg *MACAddressSegment) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the segment range includes the block of values for the given prefix length.

func (*MACAddressSegment) ContainsSinglePrefixBlock 

func (seg *MACAddressSegment) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the segment range matches exactly the block of values for the given prefix length and has just a single prefix for that prefix length.

func (*MACAddressSegment) CopyBytes 

func (seg *MACAddressSegment) CopyBytes(bytes []byte) []byte

CopyBytes copies the lowest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddressSegment) CopyUpperBytes 

func (seg *MACAddressSegment) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the highest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddressSegment) Equal 

func (seg *MACAddressSegment) Equal(other AddressSegmentType) bool

Equal returns whether the given segment is equal to this segment. Two segments are equal if they match:

  • type/version: MAC
  • value range

Prefix lengths are ignored.

func (*MACAddressSegment) GetBitCount 

func (seg *MACAddressSegment) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item, which is 8.

func (*MACAddressSegment) GetByteCount 

func (seg *MACAddressSegment) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item, which is 1.

func (*MACAddressSegment) GetCount 

func (seg *MACAddressSegment) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1.

For instance, a segment with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*MACAddressSegment) GetLeadingBitCount added in v1.1.0 

func (seg *MACAddressSegment) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*MACAddressSegment) GetLower 

func (seg *MACAddressSegment) GetLower() *MACAddressSegment

GetLower returns a segment representing just the lowest value in the range, which will be the same segment if it represents a single value.

func (*MACAddressSegment) GetMACSegmentValue 

func (seg *MACAddressSegment) GetMACSegmentValue() MACSegInt

GetMACSegmentValue returns the lower value. Same as GetSegmentValue but returned as a MACSegInt.

func (*MACAddressSegment) GetMACUpperSegmentValue 

func (seg *MACAddressSegment) GetMACUpperSegmentValue() MACSegInt

GetMACUpperSegmentValue returns the lower value. Same as GetUpperSegmentValue but returned as a MACSegInt.

func (*MACAddressSegment) GetMaxValue 

func (seg *MACAddressSegment) GetMaxValue() MACSegInt

GetMaxValue gets the maximum possible value for this type or version of segment, determined by the number of bits.

For the highest range value of this particular segment, use GetUpperSegmentValue.

func (*MACAddressSegment) GetMinPrefixLenForBlock 

func (seg *MACAddressSegment) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this segment includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this segment represents a single value, this returns the bit count.

func (*MACAddressSegment) GetPrefixCountLen 

func (seg *MACAddressSegment) GetPrefixCountLen(segmentPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct prefix values for the given prefix length in the range of values of this segment.

func (*MACAddressSegment) GetPrefixLenForSingleBlock 

func (seg *MACAddressSegment) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this segment, and the range of values in this segment matches the block of all values for that prefix.

If the range of segment values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this segment represents a single value, this returns the bit count of the segment.

func (*MACAddressSegment) GetPrefixValueCountLen 

func (seg *MACAddressSegment) GetPrefixValueCountLen(segmentPrefixLength BitCount) SegIntCount

GetPrefixValueCountLen returns the same value as GetPrefixCountLen as an integer.

func (*MACAddressSegment) GetSegmentHostMask added in v1.1.0 

func (seg *MACAddressSegment) GetSegmentHostMask(networkBits BitCount) SegInt

GetSegmentHostMask returns a value comprising the same number of total bits as the bit-length of this segment, the value that is all zero-bits for the given number of bits followed by all one-bits.

func (*MACAddressSegment) GetSegmentNetworkMask added in v1.1.0 

func (seg *MACAddressSegment) GetSegmentNetworkMask(networkBits BitCount) SegInt

GetSegmentNetworkMask returns a value comprising the same number of total bits as the bit-length of this segment, the value that is all one-bits for the given number of bits followed by all zero-bits.

func (*MACAddressSegment) GetSegmentValue 

func (seg *MACAddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the segment value range.

func (*MACAddressSegment) GetString 

func (seg *MACAddressSegment) GetString() string

GetString produces a normalized string to represent the segment.

For MAC segments, the string is the same as that produced by GetWildcardString.

func (*MACAddressSegment) GetTrailingBitCount added in v1.1.0 

func (seg *MACAddressSegment) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*MACAddressSegment) GetUpper 

func (seg *MACAddressSegment) GetUpper() *MACAddressSegment

GetUpper returns a segment representing just the highest value in the range, which will be the same segment if it represents a single value.

func (*MACAddressSegment) GetUpperSegmentValue 

func (seg *MACAddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the segment value range.

func (*MACAddressSegment) GetUpperValue 

func (seg *MACAddressSegment) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address segment range as a big integer.

func (*MACAddressSegment) GetValue 

func (seg *MACAddressSegment) GetValue() *BigDivInt

GetValue returns the lowest value in the address segment range as a big integer.

func (*MACAddressSegment) GetValueCount 

func (seg *MACAddressSegment) GetValueCount() SegIntCount

GetValueCount returns the same value as GetCount as an integer.

func (*MACAddressSegment) GetWildcardString 

func (seg *MACAddressSegment) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*MACAddressSegment) IncludesMax 

func (seg *MACAddressSegment) IncludesMax() bool

IncludesMax returns whether this segment includes the max value, the value whose bits are all ones, within its range.

func (*MACAddressSegment) IncludesZero 

func (seg *MACAddressSegment) IncludesZero() bool

IncludesZero returns whether this segment includes the value of zero within its range.

func (*MACAddressSegment) IsFullRange 

func (seg *MACAddressSegment) IsFullRange() bool

IsFullRange returns whether the segment range includes all possible values for its bit length.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*MACAddressSegment) IsMax 

func (seg *MACAddressSegment) IsMax() bool

IsMax returns whether this segment matches exactly the maximum possible value, the value whose bits are all ones.

func (*MACAddressSegment) IsMultiple 

func (seg *MACAddressSegment) IsMultiple() bool

IsMultiple returns whether this segment represents multiple values.

func (*MACAddressSegment) IsOneBit 

func (seg *MACAddressSegment) IsOneBit(segmentBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 is the most significant bit.

func (*MACAddressSegment) IsSinglePrefix 

func (seg *MACAddressSegment) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix determines if the segment has a single prefix value for the given prefix length. You can call GetPrefixCountLen to get the count of prefixes.

func (*MACAddressSegment) IsZero 

func (seg *MACAddressSegment) IsZero() bool

IsZero returns whether this segment matches exactly the value of zero.

func (*MACAddressSegment) Iterator 

func (seg *MACAddressSegment) Iterator() Iterator[*MACAddressSegment]

Iterator provides an iterator to iterate through the individual address segments of this address segment.

Call IsMultiple to determine if this instance represents multiple address segments, or GetValueCount for the count.

func (*MACAddressSegment) Join 

func (seg *MACAddressSegment) Join(macSegment1 *MACAddressSegment, prefixLength PrefixLen) (*IPv6AddressSegment, addrerr.IncompatibleAddressError)

Join joins with another MAC segment to produce a IPv6 segment.

func (*MACAddressSegment) JoinAndFlip2ndBit 

func (seg *MACAddressSegment) JoinAndFlip2ndBit(macSegment1 *MACAddressSegment, prefixLength PrefixLen) (*IPv6AddressSegment, addrerr.IncompatibleAddressError)

JoinAndFlip2ndBit joins with another MAC segment to produce a IPv6 segment with the second bit flipped from 1 to 0.

func (*MACAddressSegment) Matches 

func (seg *MACAddressSegment) Matches(value SegInt) bool

Matches returns true if the segment range matches the given single value.

func (*MACAddressSegment) MatchesValsWithMask 

func (seg *MACAddressSegment) MatchesValsWithMask(lowerValue, upperValue, mask SegInt) bool

MatchesValsWithMask applies the mask to this segment and then compares the result with the given values, returning true if the range of the resulting segment matches the given range.

func (*MACAddressSegment) MatchesWithMask 

func (seg *MACAddressSegment) MatchesWithMask(value, mask SegInt) bool

MatchesWithMask applies the mask to this segment and then compares the result with the given value, returning true if the range of the resulting segment matches that single value.

func (*MACAddressSegment) PrefixBlockIterator 

func (seg *MACAddressSegment) PrefixBlockIterator(segmentPrefixLen BitCount) Iterator[*MACAddressSegment]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks of the given prefix length, one for each prefix of that length in the segment.

func (*MACAddressSegment) PrefixContains 

func (seg *MACAddressSegment) PrefixContains(other AddressSegmentType, prefixLength BitCount) bool

PrefixContains returns whether the prefix values in the prefix of the given segment are also prefix values in this segment. It returns whether the prefix of this segment contains the prefix of the given segment.

func (*MACAddressSegment) PrefixEqual 

func (seg *MACAddressSegment) PrefixEqual(other AddressSegmentType, prefixLength BitCount) bool

PrefixEqual returns whether the prefix bits of this segment match the same bits of the given segment. It returns whether the two segments share the same range of prefix values using the given prefix length.

func (*MACAddressSegment) PrefixIterator 

func (seg *MACAddressSegment) PrefixIterator(segmentPrefixLen BitCount) Iterator[*MACAddressSegment]

PrefixIterator provides an iterator to iterate through the individual prefixes of the given prefix length in this segment, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this range.

func (*MACAddressSegment) ReverseBits 

func (seg *MACAddressSegment) ReverseBits(_ bool) (res *MACAddressSegment, err addrerr.IncompatibleAddressError)

ReverseBits returns a segment with the bits reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*MACAddressSegment) ReverseBytes 

func (seg *MACAddressSegment) ReverseBytes() (*MACAddressSegment, addrerr.IncompatibleAddressError)

ReverseBytes returns a segment with the bytes reversed, which for a MAC segment is always the original segment.

func (*MACAddressSegment) String 

func (seg *MACAddressSegment) String() string

String produces a string that is useful when a segment is provided with no context. It uses the hexadecimal radix with the string prefix for hex ("0x"). GetWildcardString and GetString are more appropriate in context with other segments or divisions. They do not use a string prefix and use '*' for full-range segments.

func (*MACAddressSegment) TestBit 

func (seg *MACAddressSegment) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*MACAddressSegment) ToDiv 

func (seg *MACAddressSegment) ToDiv() *AddressDivision

ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions. Afterwards, you can convert back with ToMAC.

ToDiv can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*MACAddressSegment) ToHexString 

func (seg *MACAddressSegment) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address segment as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

For segments, the error is always nil.

func (*MACAddressSegment) ToNormalizedString 

func (seg *MACAddressSegment) ToNormalizedString() string

ToNormalizedString produces a string that is consistent for all address segments of the same type and version. IPv4 segments use base 10, while other segment types use base 16.

func (*MACAddressSegment) ToSegmentBase 

func (seg *MACAddressSegment) ToSegmentBase() *AddressSegment

ToSegmentBase converts to an AddressSegment, a polymorphic type usable with all address segments. Afterwards, you can convert back with ToMAC.

ToSegmentBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*MACAddressSegment) UpperBytes 

func (seg *MACAddressSegment) UpperBytes() []byte

UpperBytes returns the highest value in the address segment range as a byte slice.

type MACAddressSegmentSeries 

type MACAddressSegmentSeries interface {
	AddressSegmentSeries

	// GetTrailingSection returns an ending subsection of the full address section.
	GetTrailingSection(index int) *MACAddressSection

	// GetSubSection returns a subsection of the full address section.
	GetSubSection(index, endIndex int) *MACAddressSection

	// GetSegments returns a slice with the address segments.  The returned slice is not backed by the same array as the receiver.
	GetSegments() []*MACAddressSegment

	// CopySegments copies the existing segments into the given slice,
	// as much as can be fit into the slice, returning the number of segments copied.
	CopySegments(segs []*MACAddressSegment) (count int)

	// CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index,
	// into the given slice, as much as can be fit into the slice, returning the number of segments copied.
	CopySubSegments(start, end int, segs []*MACAddressSegment) (count int)

	// GetSegment returns the segment at the given index.
	// The first segment is at index 0.
	// GetSegment will panic given a negative index or an index matching or larger than the segment count.
	GetSegment(index int) *MACAddressSegment
}

MACAddressSegmentSeries serves as a common interface to all MAC address sections and MAC addresses.

type MACAddressString 

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

MACAddressString parses the string representation of a MAC address. Such a string can represent just a single address or a collection of addresses like "1:*:1-3:1-4:5:6".

This supports a wide range of address formats and provides specific error messages, and allows specific configuration.

You can control all the supported formats using MACAddressStringParamsBuilder to build a parameters instance of MACAddressStringParams. When not using the constructor that takes a MACAddressStringParams, a default instance of MACAddressStringParams is used that is generally permissive.

Supported Formats

Ranges are supported:

  • wildcards '*' and ranges '-' (for example "1:*:1-3:1-4:5:6"), useful for working with MAC address collections
  • SQL wildcards '%" and "_", although '%' is considered an SQL wildcard only when it is not considered an IPv6 zone indicator

The different methods of representing MAC addresses are supported:

  • 6 or 8 bytes in hex representation like "aa:bb:cc:dd:ee:ff"
  • The same but with a hyphen separator like "aa-bb-cc-dd-ee-ff" (the range separator in this case becomes '/')
  • The same but with space separator like "aa bb cc dd ee ff"
  • The dotted representation, 4 sets of 12 bits in hex representation like "aaa.bbb.ccc.ddd"
  • The 12 or 16 hex representation with no separators like "aabbccddeeff"

All of the above range variations also work for each of these ways of representing MAC addresses.

Some additional formats:

  • null or empty strings representing an unspecified address
  • the single wildcard address "*" which represents all MAC addresses

Usage Once you have constructed a MACAddressString object, you can convert it to a MACAddress object with GetAddress or ToAddress.

For empty addresses, both ToAddress and GetAddress return nil. For invalid addresses, GetAddress and ToAddress return nil, with ToAddress also returning an error.

This type is concurrency-safe. In fact, MACAddressString objects are immutable. A MACAddressString object represents a single MAC address representation that cannot be changed after construction. Some derived state is created upon demand and cached, such as the derived MACAddress instances.

func NewMACAddressString 

func NewMACAddressString(str string) *MACAddressString

NewMACAddressString constructs a MACAddressString that will parse the given string according to the default parameters.

func NewMACAddressStringParams 

func NewMACAddressStringParams(str string, params addrstrparam.MACAddressStringParams) *MACAddressString

NewMACAddressStringParams constructs a MACAddressString that will parse the given string according to the given parameters.

func (*MACAddressString) Compare 

func (addrStr *MACAddressString) Compare(other *MACAddressString) int

Compare compares this address string with another, returning a negative number, zero, or a positive number if this address string is less than, equal to, or greater than the other.

All address strings are comparable. If two address strings are invalid, their strings are compared. Two valid address trings are compared using the comparison rules for their respective addresses.

func (*MACAddressString) Equal 

func (addrStr *MACAddressString) Equal(other *MACAddressString) bool

Equal returns whether this MACAddressString is equal to the given one. Two MACAddressString objects are equal if they represent the same set of addresses.

If a MACAddressString is invalid, it is equal to another address only if the other address was constructed from the same string.

func (MACAddressString) Format added in v1.5.4 

func (addrStr MACAddressString) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface. It accepts the verbs hat are applicable to strings, namely the verbs %s, %q, %x and %X.

func (*MACAddressString) GetAddress 

func (addrStr *MACAddressString) GetAddress() *MACAddress

GetAddress returns the MAC address if this MACAddressString is a valid string representing a MAC address or address collection. Otherwise, it returns nil.

Use ToAddress for an equivalent method that returns an error when the format is invalid.

func (*MACAddressString) GetPrefixLen 

func (addrStr *MACAddressString) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length if this address is a prefixed address, otherwise it returns nil.

For MAC addresses, the prefix is initially inferred from the range, so "1:2:3:*:*:*" has a prefix length of 24. Addresses derived from the original may retain the original prefix length regardless of their range.

func (*MACAddressString) GetValidationOptions 

func (addrStr *MACAddressString) GetValidationOptions() addrstrparam.MACAddressStringParams

GetValidationOptions returns the validation options supplied when constructing this address string, or the default options if no options were supplied. It returns nil if no parameters were used to construct the address.

func (*MACAddressString) IsEmpty 

func (addrStr *MACAddressString) IsEmpty() bool

IsEmpty returns true if the address is empty (zero-length).

func (*MACAddressString) IsFullRange 

func (addrStr *MACAddressString) IsFullRange() bool

IsFullRange returns whether the address represents the set of all valid MAC addresses for its address length

func (*MACAddressString) IsPrefixed 

func (addrStr *MACAddressString) IsPrefixed() bool

IsPrefixed returns whether this address has an associated prefix length, which for MAC means that the string represents the set of all addresses with the same prefix.

func (*MACAddressString) IsValid 

func (addrStr *MACAddressString) IsValid() bool

IsValid returns whether this is a valid MAC address string format. The accepted MAC address formats are: a MAC address or address collection, the address representing all MAC addresses, or an empty string. If this method returns false, and you want more details, call Validate and examine the error.

func (*MACAddressString) IsZero 

func (addrStr *MACAddressString) IsZero() bool

IsZero returns whether this string represents a MAC address whose value is exactly zero.

func (*MACAddressString) String 

func (addrStr *MACAddressString) String() string

String implements the fmt.Stringer interface, returning the original string used to create this MACAddressString (altered by strings.TrimSpace), or "<nil>" if the receiver is a nil pointer.

func (*MACAddressString) ToAddress 

func (addrStr *MACAddressString) ToAddress() (*MACAddress, addrerr.AddressError)

ToAddress produces the MACAddress corresponding to this MACAddressString.

If this object does not represent a specific MACAddress or address collection, nil is returned.

If the string used to construct this object is not a known format (empty string, address, or range of addresses) then this method returns an error.

An equivalent method that does not return the error is GetAddress.

The error can be addrerr.AddressStringError for an invalid string, or addrerr.IncompatibleAddressError for non-standard strings that cannot be converted to MACAddress.

func (*MACAddressString) ToNormalizedString 

func (addrStr *MACAddressString) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For MAC, it differs from the canonical string. It uses the most common representation of MAC addresses: "xx:xx:xx:xx:xx:xx". An example is "01:23:45:67:89:ab". For range segments, '-' is used: "11:22:33-44:55:66".

If the original string is not a valid address string, the original string is used.

func (*MACAddressString) Validate 

func (addrStr *MACAddressString) Validate() addrerr.AddressStringError

Validate validates that this string is a valid address, and if not, throws an exception with a descriptive message indicating why it is not.

func (*MACAddressString) Wrap 

func (addrStr *MACAddressString) Wrap() ExtendedIdentifierString

Wrap wraps this address string, returning a WrappedMACAddressString as an implementation of ExtendedIdentifierString, which can be used to write code that works with different host identifier types polymorphically, including IPAddressString, MACAddressString, and HostName.

type MACSegInt 

type MACSegInt = uint8

type MACSegmentValueProvider 

type MACSegmentValueProvider func(segmentIndex int) MACSegInt

func WrapSegmentValueProviderForMAC added in v1.5.0 

func WrapSegmentValueProviderForMAC(f SegmentValueProvider) MACSegmentValueProvider

WrapSegmentValueProviderForMAC converts the given SegmentValueProvider to a MACSegmentValueProvider Values that do not fit MACSegInt are truncated.

type MappedPartition added in v1.5.0 

type MappedPartition[T GenericKeyConstraint[T], V any] map[Key[T]]V

MappedPartition is a mapping from the address types in a Partition to values of a generic type V.

func ApplyForEach added in v1.5.0 

func ApplyForEach[T GenericKeyConstraint[T], V any](part *Partition[T], action func(T) V) MappedPartition[T, V]

ApplyForEach supplies to the given function each element of the given partition, inserting return values into the returned map.

func ApplyForEachConditionally added in v1.5.0 

func ApplyForEachConditionally[T GenericKeyConstraint[T], V any](part *Partition[T], action func(T) (V, bool)) MappedPartition[T, V]

ApplyForEachConditionally supplies to the given function each element of the given partition, inserting return values into the returned map as directed. When the action returns true as the second return value, then the other return value is added to the map.

type Masker 

type Masker interface {
	// GetMaskedLower provides the lowest masked value, which is not necessarily the lowest value masked.
	GetMaskedLower(value, maskValue uint64) uint64

	// GetMaskedUpper provides the highest masked value, which is not necessarily the highest value masked.
	GetMaskedUpper(upperValue, maskValue uint64) uint64

	// IsSequential returns whether masking all values in the range results in a sequential set of values.
	IsSequential() bool
}

Masker is used to mask (apply bitwise conjunction) division and segment values.

func MaskRange 

func MaskRange(value, upperValue, maskValue, maxValue uint64) Masker

MaskRange masks divisions with bit counts 64 bits or smaller. Use MaskExtendedRange for larger divisions.

type NodeValue added in v1.1.0 

type NodeValue = any

NodeValue is an alias for the generic node value type for AssociativeAddressTrie, IPv4AddressAssociativeTrie, and IPv6AddressAssociativeTrie

type Partition 

type Partition[T any] struct {
	// contains filtered or unexported fields
}

Partition is a collection of items (such as addresses) partitioned from an original item (such as a subnet). Much like an iterator, the elements of a partition can be iterated just once (using the iterator, using ForEach, or using any other iteration), after which it becomes empty.

func PartitionIPv4WithSingleBlockSize 

func PartitionIPv4WithSingleBlockSize(newAddr *IPv4Address) *Partition[*IPv4Address]

PartitionIPv4WithSingleBlockSize partitions the IPv4 address into prefix blocks and single addresses.

This function is here for backwards compatibility, PartitionWithSingleBlockSize is recommended instead.

func PartitionIPv6WithSingleBlockSize 

func PartitionIPv6WithSingleBlockSize(newAddr *IPv6Address) *Partition[*IPv6Address]

PartitionIPv6WithSingleBlockSize partitions the IPv6 address into prefix blocks and single addresses.

This function is here for backwards compatibility, PartitionWithSingleBlockSize is recommended instead.

func PartitionIpv4WithSpanningBlocks 

func PartitionIpv4WithSpanningBlocks(newAddr *IPv4Address) *Partition[*IPv4Address]

PartitionIpv4WithSpanningBlocks partitions the IPv4 address into prefix blocks and single addresses.

This function is here for backwards compatibility, PartitionWithSpanningBlocks is recommended instead.

func PartitionIpv6WithSpanningBlocks 

func PartitionIpv6WithSpanningBlocks(newAddr *IPv6Address) *Partition[*IPv6Address]

PartitionIpv6WithSpanningBlocks partitions the IPv6 address into prefix blocks and single addresses.

This function is here for backwards compatibility, PartitionWithSpanningBlocks is recommended instead.

func PartitionWithSingleBlockSize added in v1.5.0 

func PartitionWithSingleBlockSize[T IteratePartitionConstraint[T]](newAddr T) *Partition[T]

PartitionWithSingleBlockSize partitions the address series into prefix blocks and single addresses.

This method chooses the maximum block size for a list of prefix blocks contained by the address or subnet, and then iterates to produce blocks of that size.

func PartitionWithSpanningBlocks added in v1.5.0 

func PartitionWithSpanningBlocks[T SpanPartitionConstraint[T]](newAddr T) *Partition[T]

PartitionWithSpanningBlocks partitions the address series into prefix blocks and single addresses.

This method iterates through a list of prefix blocks of different sizes that span the entire subnet.

func (*Partition[T]) ForEach 

func (part *Partition[T]) ForEach(action func(T))

ForEach calls the given action on each partition element.

func (*Partition[T]) Iterator 

func (part *Partition[T]) Iterator() Iterator[T]

Iterator provides an iterator to iterate through each element of the partition.

func (*Partition[T]) PredicateForAny 

func (part *Partition[T]) PredicateForAny(predicate func(T) bool) bool

PredicateForAny applies the supplied predicate operation to each element of the partition, returning true if the given predicate returns true for any of the elements.

func (*Partition[T]) PredicateForAnyEarly 

func (part *Partition[T]) PredicateForAnyEarly(predicate func(T) bool) bool

PredicateForAnyEarly applies the supplied predicate operation to each element of the partition, returning true if the given predicate returns true for any of the elements.

The method returns when one application of the predicate returns true (determining the overall result)

func (*Partition[T]) PredicateForEach 

func (part *Partition[T]) PredicateForEach(predicate func(T) bool) bool

PredicateForEach applies the supplied predicate operation to each element of the partition, returning true if they all return true, false otherwise

func (*Partition[T]) PredicateForEachEarly 

func (part *Partition[T]) PredicateForEachEarly(predicate func(T) bool) bool

PredicateForEachEarly applies the supplied predicate operation to each element of the partition, returning false if the given predicate returns false for any of the elements.

The method returns when one application of the predicate returns false (determining the overall result)

type Port 

type Port = *PortNum

Port represents the port of a UDP or TCP address. A nil value indicates no port.

type PortInt 

type PortInt = int // using signed integers allows for easier arithmetic

type PortNum 

type PortNum uint16

PortNum is the port number for a non-nil Port. For arithmetic, you might wish to use the signed integer type PortInt instead.

func (*PortNum) Compare 

func (portNum *PortNum) Compare(other Port) int

Compare compares PrefixLen values, returning -1, 0, or 1 if the receiver is less than, equal to, or greater than the argument.

func (*PortNum) Equal 

func (portNum *PortNum) Equal(other Port) bool

Equal compares two Port values for equality.

func (*PortNum) Matches 

func (portNum *PortNum) Matches(other PortInt) bool

Matches compares a Port value with a port number.

func (*PortNum) Num 

func (portNum *PortNum) Num() PortInt

Num converts to a PortPortIntNum, returning 0 if the receiver is nil.

func (*PortNum) Port added in v1.5.0 

func (portNum *PortNum) Port() PortNum

Port dereferences this PortNum, while returning 0 if the receiver is nil.

func (*PortNum) String 

func (portNum *PortNum) String() string

String returns the bit count as a base-10 positive integer string, or "<nil>" if the receiver is a nil pointer.

type PrefixBitCount 

type PrefixBitCount uint8

A PrefixBitCount is the count of bits in a non-nil PrefixLen. For arithmetic, you may wish to use the signed integer type BitCount instead, which you can get from a PrefixLen using the Len method.

func (*PrefixBitCount) Compare 

func (prefixBitCount *PrefixBitCount) Compare(other PrefixLen) int

Compare compares PrefixLen values, returning -1, 0, or 1 if this prefix length is less than, equal to, or greater than the given prefix length. This method is intended for the PrefixLen type. BitCount values should be compared with ==, >, <, >= and <= operators.

func (*PrefixBitCount) Equal 

func (prefixBitCount *PrefixBitCount) Equal(other PrefixLen) bool

Equal compares two PrefixLen values for equality. This method is intended for the PrefixLen type. BitCount values should be compared with the == operator.

func (*PrefixBitCount) IsNil 

func (prefixBitCount *PrefixBitCount) IsNil() bool

IsNil returns true if this is nil, meaning it represents having no prefix length, or the absence of a prefix length

func (*PrefixBitCount) Len 

func (prefixBitCount *PrefixBitCount) Len() BitCount

Len returns the length of the prefix. If the receiver is nil, representing the absence of a prefix length, returns 0. It will also return 0 if the receiver is a prefix with length of 0. To distinguish the two, compare the receiver with nil.

func (*PrefixBitCount) Matches 

func (prefixBitCount *PrefixBitCount) Matches(other BitCount) bool

Matches compares a PrefixLen value with a bit count

func (*PrefixBitCount) String 

func (prefixBitCount *PrefixBitCount) String() string

String returns the bit count as a base-10 positive integer string, or "<nil>" if the receiver is a nil pointer.

type PrefixBlockAllocator added in v1.5.0 

type PrefixBlockAllocator[T PrefixBlockConstraint[T]] struct {
	// contains filtered or unexported fields
}

PrefixBlockAllocator allocates blocks of the desired size from a set of seed blocks provided to it previously for allocation.

The generic type T can be *IPAddress, *IPv4Address or *IPv6Address.

Once a prefix block allocator of generic type *IPAddress has been provided with either an IPv4 or IPv6 address or subnet for allocation, it can only be used with the same address version from that point onwards. In other words, it can allocate either IPv4 or IPv6 blocks, but not both.

The zero value of a PrefixBlockAllocator is an allocator ready for use.

func (*PrefixBlockAllocator[T]) AddAvailable added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) AddAvailable(blocks ...T)

AddAvailable provides the given blocks to the allocator for allocating.

func (*PrefixBlockAllocator[T]) AllocateBitLen added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) AllocateBitLen(bitLength BitCount) T

AllocateBitLen allocates a block with the given bit-length, the bit-length being the number of bits extending beyond the prefix length, or nil if no such block is available in the allocator. The reserved count is ignored when allocating by bit-length.

func (*PrefixBlockAllocator[T]) AllocateMultiBitLens added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) AllocateMultiBitLens(bitLengths ...BitCount) []AllocatedBlock[T]

AllocateMultiBitLens returns multiple blocks of the given bit-lengths, or nil if there is insufficient space in the allocator. The reserved count is ignored when allocating by bit-length.

func (*PrefixBlockAllocator[T]) AllocateSize added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) AllocateSize(sizeRequired uint64) T

AllocateSize returns a block of sufficient size, the size indicating the number of distinct addresses required in the block. AllocateSize returns nil if no such block is available in the allocator, or if the size required is zero. The returned block will be able to accommodate sizeRequired hosts as well as the reserved count, if any.

func (*PrefixBlockAllocator[T]) AllocateSizes added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) AllocateSizes(blockSizes ...uint64) []AllocatedBlock[T]

AllocateSizes returns multiple blocks of sufficient size for the given size required, or nil if there is insufficient space in the allocator. The reserved count, if any, will be added to the required sizes.

func (*PrefixBlockAllocator[T]) GetAvailable added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) GetAvailable() (blocks []T)

GetAvailable returns a list of all the blocks available for allocating in the allocator.

func (*PrefixBlockAllocator[T]) GetBlockCount added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) GetBlockCount() int

GetBlockCount returns the count of available blocks in this allocator.

func (*PrefixBlockAllocator[T]) GetReserved added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) GetReserved() (reservedCount int)

GetReserved returns the reserved count. Use SetReserved to change the reserved count.

func (*PrefixBlockAllocator[T]) GetTotalCount added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) GetTotalCount() *big.Int

GetTotalCount returns the total of the count of all individual addresses available in this allocator, which is the total number of individual addresses in all the blocks.

func (*PrefixBlockAllocator[T]) GetVersion added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) GetVersion() IPVersion

GetVersion returns the IP version of the available blocks in the allocator, which is determined by the version of the first block made available to the allocator.

func (*PrefixBlockAllocator[T]) SetReserved added in v1.5.0 

func (alloc *PrefixBlockAllocator[T]) SetReserved(reservedCount int)

SetReserved sets the additional number of addresses to be included in any size allocation. Any request for a block of a given size will adjust that size by the given number. This can be useful when the size requests do not include the count of additional addresses that must be included in every block. For IPv4, it is common to reserve two addresses, the network and broadcast addresses. If the reservedCount is negative, then every request will be shrunk by that number, useful for cases where insufficient space requires that all subnets be reduced in size by an equal number.

func (PrefixBlockAllocator[T]) String added in v1.5.0 

func (alloc PrefixBlockAllocator[T]) String() string

String returns a string showing the counts of available blocks for each prefix size in the allocator.

type PrefixBlockConstraint added in v1.5.0 

type PrefixBlockConstraint[T any] interface {
	SequentialRangeConstraint[T]

	MergeToPrefixBlocks(...T) []T
	PrefixBlockIterator() Iterator[T]
}

PrefixBlockConstraint is the generic type constraint used for a prefix block allocator.

type PrefixKey added in v1.1.0 

type PrefixKey struct {
	// If true, the prefix length is indicated by PrefixLen.
	// If false, this indicates no prefix length for the associated address or subnet.
	IsPrefixed bool

	// If IsPrefixed is true, this holds the prefix length.
	// Otherwise, this should be zero if you wish that each address has a unique key.
	PrefixLen PrefixBitCount
}

PrefixKey is a representation of a prefix length that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators

It can be used as a map key. The zero value is the absence of a prefix length.

func PrefixKeyFrom added in v1.5.0 

func PrefixKeyFrom(addr AddressType) PrefixKey

func (PrefixKey) ToPrefixLen added in v1.1.0 

func (pref PrefixKey) ToPrefixLen() PrefixLen

ToPrefixLen converts this key to its corresponding prefix length.

type PrefixLen 

type PrefixLen = *PrefixBitCount

A PrefixLen indicates the length of the prefix for an address, section, division grouping, segment, or division. The zero value, which is nil, indicates that there is no prefix length.

func ToPrefixLen added in v1.1.0 

func ToPrefixLen(i int) PrefixLen

ToPrefixLen converts the given int to a prefix length

func ValidatePrefixLenStr 

func ValidatePrefixLenStr(str string, version IPVersion) (prefixLen PrefixLen, err addrerr.AddressStringError)

ValidatePrefixLenStr validates that the string represents a valid prefix length, such as "24". The string should not include a beginning '/' character. If invalid, it returns an error with an appropriate message. You can specify the IP version or IndeterminateIPVersion if unknown. An error is returned if the format is invalid.

type Prefixed added in v1.5.3 

type Prefixed interface {
	// IsPrefixed returns whether this item has an associated prefix length.
	IsPrefixed() bool

	// GetPrefixLen returns the prefix length, or nil if there is no prefix length.
	//
	// A prefix length indicates the number of bits in the initial part (most significant bits) of the series that comprise the prefix.
	//
	// A prefix is a part of the series that is not specific to that series but common amongst a group, such as a CIDR prefix block subnet.
	GetPrefixLen() PrefixLen

	// IsPrefixBlock returns whether this item has a prefix length and includes the block associated with that prefix length.
	// If the prefix length matches the bit count, this returns true.
	//
	// This is different from ContainsPrefixBlock in that this method returns
	// false if this item has no prefix length, or it has a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.
	IsPrefixBlock() bool

	// IsSinglePrefixBlock returns whether the range of values matches a single subnet block for the prefix length.
	//
	// This is different from ContainsSinglePrefixBlock in that this method returns
	// false if this series has no prefix length or a prefix length that differs from a prefix length for which ContainsSinglePrefixBlock returns true.
	IsSinglePrefixBlock() bool
}

type PrefixedConstraint added in v1.5.3 

type PrefixedConstraint[T any] interface {
	Prefixed

	// WithoutPrefixLen provides the same item but with no prefix length.  The values remain unchanged.
	WithoutPrefixLen() T

	// ToPrefixBlock returns the item whose prefix matches the prefix of this item, while the remaining bits span all values.
	// If this item has no prefix length, then this item is returned.
	//
	// The returned item will include all items with the same prefix as this item, known as the prefix "block".
	ToPrefixBlock() T

	// ToPrefixBlockLen returns the item associated with the prefix length provided,
	// the item whose prefix of that length matches the prefix of that length in this item, and the remaining bits span all values.
	//
	// The returned address will include all items with the same prefix as this one, known as the prefix "block".
	ToPrefixBlockLen(BitCount) T

	// SetPrefixLen sets the prefix length, returning a new item with the same values but with the new prefix length.
	//
	// A prefix length will not be set to a value lower than zero or beyond the bit length of the item.
	// The provided prefix length will be adjusted to these boundaries if necessary.
	SetPrefixLen(BitCount) T
}

type SegInt 

type SegInt = uint32 // must be at least uint16 to handle IPv6, at least 32 to handle single segment IPv4, and no larger than 64 because we use bits.TrailingZeros64.  IP address segment code uses bits.TrailingZeros32 and bits.LeadingZeros32, so it cannot be larger than 32.

SegInt is an integer type for holding generic address segment values. It is at least as large as all address segment values: IPv6SegInt, IPv4SegInt, MACSegInt.

type SegIntCount 

type SegIntCount = uint64 // must be able to hold: (max value of SegInt) + 1

type SegmentSequence added in v1.2.0 

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

SegmentSequence represents a sequence of consecutive segments with the given length starting from the given segment index.

type SegmentSequenceList added in v1.2.0 

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

SegmentSequenceList represents a list of SegmentSequence instances.

type SegmentValueProvider 

type SegmentValueProvider func(segmentIndex int) SegInt

SegmentValueProvider provides values for segments. Values that fall outside the segment value type range will be truncated using standard golang integer type conversions https://golang.org/ref/spec#Conversions

func WrapIPv4SegmentValueProvider added in v1.5.0 

func WrapIPv4SegmentValueProvider(f IPv4SegmentValueProvider) SegmentValueProvider

WrapIPv4SegmentValueProvider converts the given IPv4SegmentValueProvider to a SegmentValueProvider.

func WrapIPv6SegmentValueProvider added in v1.5.0 

func WrapIPv6SegmentValueProvider(f IPv6SegmentValueProvider) SegmentValueProvider

WrapIPv6SegmentValueProvider converts the given IPv6SegmentValueProvider to a SegmentValueProvider.

func WrapMACSegmentValueProvider added in v1.5.0 

func WrapMACSegmentValueProvider(f MACSegmentValueProvider) SegmentValueProvider

WrapMACSegmentValueProvider converts the given MACSegmentValueProvider to a SegmentValueProvider

type SequentialRange added in v1.5.0 

type SequentialRange[T SequentialRangeConstraint[T]] struct {
	// contains filtered or unexported fields
}

SequentialRange represents an arbitrary range of consecutive IP addresses, from a lower address to an upper address, inclusive.

For the generic type T you can choose *IPAddress, *IPv4Address, or *IPv6Address.

This type allows the representation of any sequential address range, including those that cannot be represented by IPAddress or IPAddressString.

IPAddress and IPAddressString allow you to specify a range of values for each segment, allowing for single addresses, any address CIDR prefix subnet (for example, "1.2.0.0/16" or "1:2:3:4::/64") or any subnet that can be represented with segment ranges (for example, "1.2.0-255.*" or "1:2:3:4:*"). See IPAddressString for details. IPAddressString and IPAddress cover all potential subnets and addresses that can be represented by a single address string of 4 or less segments for IPv4, and 8 or less segments for IPv6. In contrast, this type covers any sequential address range.

String representations of this type include the full address for both the lower and upper bounds of the range.

The zero value is a range from the zero-valued IPAddress to itself.

For a range of type SequentialRange[*IPAddress], the range spans from an IPv4 address to another IPv4 address, or from an IPv6 address to another IPv6 address. A sequential range cannot include both IPv4 and IPv6 addresses.

func NewIPSeqRange added in v1.4.0 

func NewIPSeqRange(lower, upper *IPAddress) *SequentialRange[*IPAddress]

NewIPSeqRange creates an IP sequential range from the given addresses. It is here for backwards compatibility. NewSequentialRange is recommended instead. If the type of T is *IPAddress and the versions of lower and upper do not match (one is IPv4, one IPv6), then nil is returned. Otherwise, the range is returned.

func NewIPv4SeqRange 

func NewIPv4SeqRange(lower, upper *IPv4Address) *SequentialRange[*IPv4Address]

NewIPv4SeqRange creates an IPv4 sequential range from the given addresses. It is here for backwards compatibility. NewSequentialRange is recommended instead.

func NewIPv6SeqRange 

func NewIPv6SeqRange(lower, upper *IPv6Address) *SequentialRange[*IPv6Address]

NewIPv6SeqRange creates an IPv6 sequential range from the given addresses. It is here for backwards compatibility. NewSequentialRange is recommended instead.

func NewSequentialRange added in v1.5.0 

func NewSequentialRange[T SequentialRangeConstraint[T]](lower, upper T) *SequentialRange[T]

NewSequentialRange creates a sequential range from the given addresses. A nil value argument is equivalent to the zero value of the type of T, which then needs to be inferred by the other argument or the function call. If the type of T is *IPAddress and the versions of lower and upper do not match (one is IPv4, one IPv6), then nil is returned. Otherwise, the range is returned.

func (*SequentialRange[T]) Bytes added in v1.5.0 

func (rng *SequentialRange[T]) Bytes() []byte

Bytes returns the lowest address in the range, the one with the lowest numeric value, as a byte slice.

func (*SequentialRange[T]) Compare added in v1.5.0 

func (rng *SequentialRange[T]) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this sequential address range is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*SequentialRange[T]) CompareSize added in v1.5.0 

func (rng *SequentialRange[T]) CompareSize(other AddressItem) int

CompareSize compares the counts of two address ranges or items, the number of individual addresses or items within each.

Rather than calculating counts with GetCount, there can be more efficient ways of determining whether this range spans more individual addresses than another item.

CompareSize returns a positive integer if this range has a larger count than the item given, zero if they are the same, or a negative integer if the other has a larger count.

func (*SequentialRange[T]) Contains added in v1.5.0 

func (rng *SequentialRange[T]) Contains(other IPAddressType) bool

Contains returns whether this range contains all addresses in the given address or subnet.

func (*SequentialRange[T]) ContainsPrefixBlock added in v1.5.0 

func (rng *SequentialRange[T]) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine whether there is a prefix length for which this method returns true.

func (*SequentialRange[T]) ContainsRange added in v1.5.0 

func (rng *SequentialRange[T]) ContainsRange(other IPAddressSeqRangeType) bool

ContainsRange returns whether all the addresses in the given sequential range are also contained in this sequential range.

func (*SequentialRange[T]) ContainsSinglePrefixBlock added in v1.5.0 

func (rng *SequentialRange[T]) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address range contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*SequentialRange[T]) CopyBytes added in v1.5.0 

func (rng *SequentialRange[T]) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest address in the range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*SequentialRange[T]) CopyNetIP added in v1.5.0 

func (rng *SequentialRange[T]) CopyNetIP(bytes net.IP) net.IP

CopyNetIP copies the value of the lower IP address in the range into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*SequentialRange[T]) CopyUpperBytes added in v1.5.0 

func (rng *SequentialRange[T]) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest address in the range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*SequentialRange[T]) CopyUpperNetIP added in v1.5.0 

func (rng *SequentialRange[T]) CopyUpperNetIP(bytes net.IP) net.IP

CopyUpperNetIP copies the upper IP address in the range into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*SequentialRange[T]) CoverWithPrefixBlock added in v1.5.0 

func (rng *SequentialRange[T]) CoverWithPrefixBlock() T

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the addresses in this range. The resulting block will have a larger count than this, unless this range already directly corresponds to a prefix block.

func (*SequentialRange[T]) Equal added in v1.5.0 

func (rng *SequentialRange[T]) Equal(other IPAddressSeqRangeType) bool

Equal returns whether the given sequential address range is equal to this sequential address range. Two sequential address ranges are equal if their lower and upper range boundaries are equal.

func (*SequentialRange[T]) Extend added in v1.5.0 

func (rng *SequentialRange[T]) Extend(other *SequentialRange[T]) *SequentialRange[T]

Extend extends this sequential range to include all address in the given range. If the argument has a different IP version than this, nil is returned. Otherwise, this method returns the range that includes this range, the given range, and all addresses in-between.

func (SequentialRange[T]) Format added in v1.5.0 

func (rng SequentialRange[T]) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface.

It prints the string as "lower -> upper" where lower and upper are the formatted strings for the lowest and highest addresses in the range, given by GetLower and GetUpper. The formats, flags, and other specifications supported are those supported by Format in IPAddress.

func (*SequentialRange[T]) GetBitCount added in v1.5.0 

func (rng *SequentialRange[T]) GetBitCount() BitCount

GetBitCount returns the number of bits in each address in the range.

func (*SequentialRange[T]) GetByteCount added in v1.5.0 

func (rng *SequentialRange[T]) GetByteCount() int

GetByteCount returns the number of bytes in each address in the range.

func (*SequentialRange[T]) GetCount added in v1.5.0 

func (rng *SequentialRange[T]) GetCount() *big.Int

GetCount returns the count of addresses that this sequential range spans.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*SequentialRange[T]) GetIPVersion added in v1.5.0 

func (rng *SequentialRange[T]) GetIPVersion() IPVersion

GetIPVersion returns the IP version of this IP address sequential range

func (*SequentialRange[T]) GetLower added in v1.5.0 

func (rng *SequentialRange[T]) GetLower() T

GetLower returns the lowest address in the range, the one with the lowest numeric value.

func (*SequentialRange[T]) GetLowerIPAddress added in v1.5.0 

func (rng *SequentialRange[T]) GetLowerIPAddress() *IPAddress

GetLowerIPAddress satisfies the IPAddressRange interface, returning the lower address in the range, same as GetLower.

func (*SequentialRange[T]) GetMinPrefixLenForBlock added in v1.5.0 

func (rng *SequentialRange[T]) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

func (*SequentialRange[T]) GetNetIP added in v1.5.0 

func (rng *SequentialRange[T]) GetNetIP() net.IP

GetNetIP returns the lower IP address in the range as a net.IP.

func (*SequentialRange[T]) GetNetNetIPAddr added in v1.5.0 

func (rng *SequentialRange[T]) GetNetNetIPAddr() netip.Addr

GetNetNetIPAddr returns the lowest address in this address range as a netip.Addr.

func (*SequentialRange[T]) GetPrefixCountLen added in v1.5.0 

func (rng *SequentialRange[T]) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct values within the prefix part of the range of addresses.

func (*SequentialRange[T]) GetPrefixLenForSingleBlock added in v1.5.0 

func (rng *SequentialRange[T]) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this range, and the range of values in this range matches the block of all values for that prefix.

If the range can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this item represents a single value, this returns the bit count.

func (*SequentialRange[T]) GetUpper added in v1.5.0 

func (rng *SequentialRange[T]) GetUpper() T

GetUpper returns the highest address in the range, the one with the highest numeric value.

func (*SequentialRange[T]) GetUpperIPAddress added in v1.5.0 

func (rng *SequentialRange[T]) GetUpperIPAddress() *IPAddress

GetUpperIPAddress satisfies the IPAddressRange interface, returning the upper address in the range, same as GetUpper.

func (*SequentialRange[T]) GetUpperNetIP added in v1.5.0 

func (rng *SequentialRange[T]) GetUpperNetIP() net.IP

GetUpperNetIP returns the upper IP address in the range as a net.IP.

func (*SequentialRange[T]) GetUpperNetNetIPAddr added in v1.5.0 

func (rng *SequentialRange[T]) GetUpperNetNetIPAddr() netip.Addr

GetUpperNetNetIPAddr returns the highest address in this address range as a netip.Addr.

func (*SequentialRange[T]) GetUpperValue added in v1.5.0 

func (rng *SequentialRange[T]) GetUpperValue() *big.Int

GetUpperValue returns the highest address in the range, the one with the highest numeric value, as an integer.

func (*SequentialRange[T]) GetValue added in v1.5.0 

func (rng *SequentialRange[T]) GetValue() *big.Int

GetValue returns the lowest address in the range, the one with the lowest numeric value, as an integer.

func (*SequentialRange[T]) IncludesMax added in v1.5.0 

func (rng *SequentialRange[T]) IncludesMax() bool

IncludesMax returns whether this sequential range's upper value is the max value, the value whose bits are all ones.

func (*SequentialRange[T]) IncludesZero added in v1.5.0 

func (rng *SequentialRange[T]) IncludesZero() bool

IncludesZero returns whether this sequential range's lower value is the zero address.

func (*SequentialRange[T]) Intersect added in v1.5.0 

func (rng *SequentialRange[T]) Intersect(other *SequentialRange[T]) *SequentialRange[T]

Intersect returns the intersection of this range with the given range, a range which includes those addresses found in both. It returns nil if there is no common address.

func (*SequentialRange[T]) IsFullRange added in v1.5.0 

func (rng *SequentialRange[T]) IsFullRange() bool

IsFullRange returns whether this address range covers the entire address space of this IP address version.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*SequentialRange[T]) IsIPv4 added in v1.5.0 

func (rng *SequentialRange[T]) IsIPv4() bool

IsIPv4 returns true if this sequential address range is an IPv4 sequential address range. If so, use ToIPv4 to convert to the IPv4-specific type.

func (*SequentialRange[T]) IsIPv6 added in v1.5.0 

func (rng *SequentialRange[T]) IsIPv6() bool

IsIPv6 returns true if this sequential address range is an IPv6 sequential address range. If so, use ToIPv6 to convert to the IPv6-specific type.

func (*SequentialRange[T]) IsMax added in v1.5.0 

func (rng *SequentialRange[T]) IsMax() bool

IsMax returns whether this sequential range spans from the max address, the address whose bits are all ones, to itself.

func (*SequentialRange[T]) IsMultiple added in v1.5.0 

func (rng *SequentialRange[T]) IsMultiple() bool

IsMultiple returns whether this range represents a range of multiple addresses.

func (*SequentialRange[T]) IsSequential added in v1.5.0 

func (rng *SequentialRange[T]) IsSequential() bool

IsSequential returns whether the address or subnet represents a range of values that are sequential.

IP address sequential ranges are sequential by definition, so this returns true.

func (*SequentialRange[T]) IsZero added in v1.5.0 

func (rng *SequentialRange[T]) IsZero() bool

IsZero returns whether this sequential range spans from the zero address to itself.

func (*SequentialRange[T]) Iterator added in v1.5.0 

func (rng *SequentialRange[T]) Iterator() Iterator[T]

Iterator provides an iterator to iterate through the individual addresses of this address range.

Call GetCount for the count.

func (*SequentialRange[T]) Join added in v1.5.0 

func (rng *SequentialRange[T]) Join(ranges ...*SequentialRange[T]) []*SequentialRange[T]

Join joins the receiver with the given ranges into the fewest number of ranges. The returned array will be sorted by ascending lowest range value. Nil ranges are tolerated, and ignored.

func (*SequentialRange[T]) JoinTo added in v1.5.0 

func (rng *SequentialRange[T]) JoinTo(other *SequentialRange[T]) *SequentialRange[T]

JoinTo joins this range to the other if they are contiguous. If this range overlaps with the given range, or if the highest value of the lower range is one below the lowest value of the higher range, then the two are joined into a new larger range that is returned. Otherwise, nil is returned.

func (*SequentialRange[T]) Overlaps added in v1.5.0 

func (rng *SequentialRange[T]) Overlaps(other *SequentialRange[T]) bool

Overlaps returns true if this sequential range overlaps with the given sequential range.

func (*SequentialRange[T]) PrefixBlockIterator added in v1.5.0 

func (rng *SequentialRange[T]) PrefixBlockIterator(prefLength BitCount) Iterator[T]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks of the given prefix length, one for each prefix of that length in the address range.

func (*SequentialRange[T]) PrefixIterator added in v1.5.0 

func (rng *SequentialRange[T]) PrefixIterator(prefLength BitCount) Iterator[*SequentialRange[T]]

PrefixIterator provides an iterator to iterate through the individual prefixes of the given prefix length in this address range, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this range.

Since a range between two arbitrary addresses cannot always be represented with a single IPAddress instance, the returned iterator iterates through SequentialRange instances.

For instance, if iterating from "1.2.3.4" to "1.2.4.5" with prefix 8, the range shares the same prefix of value 1, but the range cannot be represented by the address "1.2.3-4.4-5" which does not include "1.2.3.255" or "1.2.4.0" both of which are in the original range. Nor can the range be represented by "1.2.3-4.0-255" which includes "1.2.4.6" and "1.2.3.3", both of which were not in the original range. A SequentialRange is thus required to represent that prefixed range.

func (*SequentialRange[T]) SpanWithPrefixBlocks added in v1.5.0 

func (rng *SequentialRange[T]) SpanWithPrefixBlocks() []T

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of addresses as this range.

func (*SequentialRange[T]) SpanWithSequentialBlocks added in v1.5.0 

func (rng *SequentialRange[T]) SpanWithSequentialBlocks() []T

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of addresses as this range. This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

func (*SequentialRange[T]) String added in v1.5.0 

func (rng *SequentialRange[T]) String() string

String implements the fmt.Stringer interface, returning the lower address canonical string, followed by the default separator " -> ", followed by the upper address canonical string. It returns "<nil>" if the receiver is a nil pointer.

func (*SequentialRange[T]) Subtract added in v1.5.0 

func (rng *SequentialRange[T]) Subtract(other *SequentialRange[T]) []*SequentialRange[T]

Subtract subtracts the given range from the receiver range, to produce either zero, one, or two address ranges that contain the addresses in the receiver range and not in the given range. If the result has length 2, the two ranges are ordered by ascending lowest range value.

func (*SequentialRange[T]) ToCanonicalString added in v1.5.0 

func (rng *SequentialRange[T]) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address range. It has the format "lower -> upper" where lower and upper are the canonical strings for the lowest and highest addresses in the range, given by GetLower and GetUpper.

func (*SequentialRange[T]) ToIP added in v1.5.0 

func (rng *SequentialRange[T]) ToIP() *SequentialRange[*IPAddress]

ToIP converts to a SequentialRange[*IPAddress], a polymorphic type usable with all IP address sequential ranges.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*SequentialRange[T]) ToIPv4 added in v1.5.0 

func (rng *SequentialRange[T]) ToIPv4() *SequentialRange[*IPv4Address]

ToIPv4 converts to a SequentialRange[*IPv4Address] if this address range is an IPv4 address range. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*SequentialRange[T]) ToIPv6 added in v1.5.0 

func (rng *SequentialRange[T]) ToIPv6() *SequentialRange[*IPv6Address]

ToIPv6 converts to a SequentialRange[*IPv6Address] if this address range is an IPv6 address range. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*SequentialRange[T]) ToKey added in v1.5.0 

func (rng *SequentialRange[T]) ToKey() SequentialRangeKey[T]

ToKey creates the associated address range key. While address ranges can be compared with the Compare or Equal methods as well as various provided instances of AddressComparator, they are not comparable with Go operators. However, SequentialRangeKey instances are comparable with Go operators, and thus can be used as map keys.

func (*SequentialRange[T]) ToNormalizedString added in v1.5.0 

func (rng *SequentialRange[T]) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address range. It has the format "lower -> upper" where lower and upper are the normalized strings for the lowest and highest addresses in the range, given by GetLower and GetUpper.

func (*SequentialRange[T]) ToString added in v1.5.0 

func (rng *SequentialRange[T]) ToString(lowerStringer func(T) string, separator string, upperStringer func(T) string) string

ToString produces a customized string for the address range.

func (*SequentialRange[T]) UpperBytes added in v1.5.0 

func (rng *SequentialRange[T]) UpperBytes() []byte

UpperBytes returns the highest address in the range, the one with the highest numeric value, as a byte slice.

type SequentialRangeConstraint added in v1.5.0 

type SequentialRangeConstraint[T any] interface {
	AddressType // cannot use IPAddressType here because ToAddressString() results in a circular dependency, SequentialRangeConstraint -> IPAddressType -> IPAddressString -> SequentialRange -> SequentialRangeConstraint

	IPAddressRange

	comparable

	ToIP() *IPAddress

	PrefixedConstraint[T]

	Increment(int64) T
	GetLower() T
	GetUpper() T

	CoverWithPrefixBlockTo(T) T
	SpanWithPrefixBlocksTo(T) []T
	SpanWithSequentialBlocksTo(T) []T
	SpanWithPrefixBlocks() []T

	IncludesZeroHostLen(BitCount) bool
	IncludesMaxHostLen(BitCount) bool

	Format(state fmt.State, verb rune)
	// contains filtered or unexported methods
}

SequentialRangeConstraint is the generic type constraint for an IP address sequential range.

type SequentialRangeKey added in v1.5.0 

type SequentialRangeKey[T SequentialRangeConstraint[T]] struct {
	// contains filtered or unexported fields
}

SequentialRangeKey is a representation of SequentialRange that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators

It can be used as a map key. The zero value is a range from a zero-length address to itself.

func (SequentialRangeKey[T]) String added in v1.5.0 

func (key SequentialRangeKey[T]) String() string

String calls the String method in the corresponding sequential range.

func (SequentialRangeKey[T]) ToSeqRange added in v1.5.0 

func (key SequentialRangeKey[T]) ToSeqRange() *SequentialRange[T]

ToSeqRange converts back to a sequential range instance.

type SpanPartitionConstraint added in v1.5.0 

type SpanPartitionConstraint[T any] interface {
	AddressDivisionSeries

	PrefixedConstraint[T]

	SpanWithPrefixBlocks() []T
}

SpanPartitionConstraint is the generic type constraint for IP subnet spanning partitions.

type StandardDivGroupingType 

type StandardDivGroupingType interface {
	AddressDivisionSeries

	// IsAdaptiveZero returns true if the division grouping was originally created as an implicitly zero-valued section or grouping (e.g. IPv4AddressSection{}),
	// meaning it was not constructed using a constructor function.
	// Such a grouping, which has no divisions or segments, is convertible to an implicitly zero-valued grouping of any type or version, whether IPv6, IPv4, MAC, or other.
	// In other words, when a section or grouping is the zero-value, then it is equivalent and convertible to the zero value of any other section or grouping type.
	IsAdaptiveZero() bool

	// ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings.
	//
	// ToDivGrouping implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToDivGrouping() *AddressDivisionGrouping
}

StandardDivGroupingType represents any standard division grouping (division groupings or address sections where all divisions are 64 bits or less) including AddressSection, IPAddressSection, IPv4AddressSection, IPv6AddressSection, MACAddressSection, and AddressDivisionGrouping

type StandardDivisionType 

type StandardDivisionType interface {
	DivisionType

	// ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions.
	//
	// ToDiv implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToDiv() *AddressDivision
}

StandardDivisionType represents any standard address division, which is a division of size 64 bits or less. All can be converted to/from AddressDivision.

type Trie added in v1.5.0 

type Trie[T TrieKeyConstraint[T]] struct {
	// contains filtered or unexported fields
}

Trie is a compact binary trie (aka compact binary prefix tree, or binary radix trie), for addresses and/or CIDR prefix block subnets. The prefixes in used by the prefix trie are the CIDR prefixes, or the full address in the case of individual addresses with no prefix length. The elements of the trie are CIDR prefix blocks or addresses.

For the generic type T, you can choose *Address, *IPAddress, *IPv4Address, *IPv6Address, or *MACAddress.

The zero-value of an AddressTrie is a trie ready for use. Its root will be nil until an element is added to it. Once any subnet or address is added to the trie, it will have an assigned root, and any further addition to the trie must match the type and version of the root, in addition to the generic type of the trie's keys. Once there is a root, the root cannot be removed.

So, for instance, an instance of ipaddr.Trie[*ipaddr.IPAddress] can contain either IPv4 or IPv6 keys, but not both. Once it has been populated with the first key, all remaining additions must have the same IP version, even if the trie is cleared.

Any trie can be copied. If a trie has no root, a copy produces a new zero-valued trie with no root. If a trie has a root, a copy produces a reference to the same trie, much like copying a map or slice.

The trie data structure allows you to check an address for containment in many subnets at once, in constant time. The trie allows you to check a subnet for containment of many smaller subnets or addresses at once, in constant time. The trie allows you to check for equality of a subnet or address with a large number of subnets or addresses at once.

There is only a single possible trie for any given set of address and subnets. For one thing, this means they are automatically balanced. Also, this makes access to subtries and to the nodes themselves more useful, allowing for many of the same operations performed on the original trie.

Each node has either a prefix block or a single address as its key. Each prefix block node can have two sub-nodes, each sub-node a prefix block or address contained by the node.

There are more nodes in the trie than elements added to the trie. A node is considered "added" if it was explicitly added to the trie and is included as an element when viewed as a set. There are non-added prefix block nodes that are generated in the trie as well. When two or more added addresses share the same prefix up until they differ with the bit at index x, then a prefix block node is generated (if not already added to the trie) for the common prefix of length x, with the nodes for those addresses to be found following the lower or upper sub-nodes according to the bit at index x + 1 in each address. If that bit is 1, the node can be found by following the upper sub-node, and when it is 0, the lower sub-node.

Nodes that were generated as part of the trie structure only because of other added elements are not elements of the represented set of addresses and subnets. The set elements are the elements that were explicitly added.

You can work with parts of the trie, starting from any node in the trie, calling methods that start with any given node, such as iterating the subtrie, finding the first or last in the subtrie, doing containment checks with the subtrie, and so on.

The binary trie structure defines a natural ordering of the trie elements. Addresses of equal prefix length are sorted by prefix value. Addresses with no prefix length are sorted by address value. Addresses of differing prefix length are sorted according to the bit that follows the shorter prefix length in the address with the longer prefix length, whether that bit is 0 or 1 determines if that address is ordered before or after the address of shorter prefix length.

The unique and pre-defined structure for a trie means that different means of traversing the trie can be more meaningful. This trie implementation provides 8 different ways of iterating through the trie:

  • 1, 2: the natural sorted trie order, forward and reverse (spliterating is also an option for these two orders). Use the methods NodeIterator, Iterator or DescendingIterator. Functions for incrementing and decrementing keys, or comparing keys, is also provided for this order.
  • 3, 4: pre-order tree traversal, in which parent node is visited before sub-nodes, with sub-nodes visited in forward or reverse order
  • 5, 6: post-order tree traversal, in which sub-nodes are visited before parent nodes, with sub-nodes visited in forward or reverse order
  • 7, 8: prefix-block order, in which larger prefix blocks are visited before smaller, and blocks of equal size are visited in forward or reverse sorted order

All of these orderings are useful in specific contexts.

If you create an iterator, then that iterator can no longer be advanced following any further modification to the trie. Any call to Next or Remove will panic if the trie was changed following creation of the iterator.

You can do lookup and containment checks on all the subnets and addresses in the trie at once, in constant time. A generic trie data structure lookup is O(m) where m is the entry length. For this trie, which operates on address bits, entry length is capped at 128 bits for IPv6 and 32 bits for IPv4. That makes lookup a constant time operation. Subnet containment or equality checks are also constant time since they work the same way as lookup, by comparing prefix bits.

For a generic trie data structure, construction is O(m * n) where m is entry length and n is the number of addresses, but for this trie, since entry length is capped at 128 bits for IPv6 and 32 bits for IPv4, construction is O(n), in linear proportion to the number of added elements.

This trie also allows for constant time size queries (count of added elements, not node count), by storing sub-trie size in each node. It works by updating the size of every node in the path to any added or removed node. This does not change insertion or deletion operations from being constant time (because tree-depth is limited to address bit count). At the same this makes size queries constant time, rather than being O(n) time.

A single trie can use just a single address type or version, since it works with bits alone, and cannot distinguish between different versions and types in the trie structure.

Instead, you could aggregate multiple subtries to create a collection of multiple address types or versions. You can use the method ToString for a String that represents multiple tries as a single tree.

Tries are concurrency-safe when not being modified (elements added or removed), but are not concurrency-safe when any goroutine is modifying the trie.

func NewIPv4AddressTrie added in v1.1.0 

func NewIPv4AddressTrie() *Trie[*IPv4Address]

NewIPv4AddressTrie constructs an IPv4 address trie with the root as the 0.0.0.0/0 prefix block This is here for backwards compatibility. Using NewTrie is recommended instead.

func NewIPv6AddressTrie added in v1.1.0 

func NewIPv6AddressTrie() *Trie[*IPv6Address]

NewIPv6AddressTrie constructs an IPv6 address trie with the root as the ::/0 prefix block This is here for backwards compatibility. Using NewTrie is recommended instead.

func NewMACAddressTrie added in v1.1.0 

func NewMACAddressTrie(extended bool) *Trie[*MACAddress]

NewMACAddressTrie constructs a MAC address trie with the root as the zero-prefix block If extended is true, the trie will consist of 64-bit EUI addresses, otherwise the addresses will be 48-bit. If you wish to construct a trie in which the address size is determined by the first added address, use the zero-value MACAddressTrie{} This is here for backwards compatibility. Using NewTrie is recommended instead.

func NewTrie added in v1.5.0 

func NewTrie[T TrieKeyConstraint[T]]() *Trie[T]

NewTrie constructs an address trie for the given type, without a root. For the generic type T, you can choose *Address, *IPAddress, *IPv4Address, *IPv6Address, or *MACAddress.

func (*Trie[T]) Add added in v1.5.0 

func (trie *Trie[T]) Add(addr T) bool

Add adds the address to this trie. The address must match the same type and version of any existing addresses already in the trie. Returns true if the address did not already exist in the trie.

func (*Trie[T]) AddNode added in v1.5.0 

func (trie *Trie[T]) AddNode(addr T) *TrieNode[T]

AddNode adds the address to this trie. The address must match the same type and version of any existing addresses already in the trie. The new or existing node for the address is returned.

func (*Trie[T]) AddTrie added in v1.5.0 

func (trie *Trie[T]) AddTrie(added *TrieNode[T]) *TrieNode[T]

AddTrie adds nodes for the keys in the trie with the root node as the passed in node. AddTrie returns the sub-node in the trie where the added trie begins, where the first node of the added trie is located.

func (*Trie[T]) AddedNodesTreeString added in v1.5.0 

func (trie *Trie[T]) AddedNodesTreeString() string

AddedNodesTreeString provides a flattened version of the trie showing only the contained added nodes and their containment structure, which is non-binary. The root node is included, which may or may not be added.

func (*Trie[T]) AllNodeIterator added in v1.5.0 

func (trie *Trie[T]) AllNodeIterator(forward bool) IteratorWithRemove[*TrieNode[T]]

AllNodeIterator returns an iterator that iterates through all the nodes in the trie in forward or reverse trie order.

func (*Trie[T]) BlockSizeAllNodeIterator added in v1.5.0 

func (trie *Trie[T]) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IteratorWithRemove[*TrieNode[T]]

BlockSizeAllNodeIterator returns an iterator that iterates all nodes in the trie, ordered by keys from largest prefix blocks to smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*Trie[T]) BlockSizeCachingAllNodeIterator added in v1.5.0 

func (trie *Trie[T]) BlockSizeCachingAllNodeIterator() CachingTrieIterator[*TrieNode[T]]

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from largest prefix blocks to smallest, and then to individual addresses.

func (*Trie[T]) BlockSizeNodeIterator added in v1.5.0 

func (trie *Trie[T]) BlockSizeNodeIterator(lowerSubNodeFirst bool) IteratorWithRemove[*TrieNode[T]]

BlockSizeNodeIterator returns an iterator that iterates the added nodes in the trie, ordered by keys from largest prefix blocks to smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*Trie[T]) CeilingAddedNode added in v1.5.0 

func (trie *Trie[T]) CeilingAddedNode(addr T) *TrieNode[T]

CeilingAddedNode returns the added node whose address is the lowest address greater than or equal to the given address.

func (*Trie[T]) Clear added in v1.5.0 

func (trie *Trie[T]) Clear()

Clear removes all added nodes from the trie, after which IsEmpty will return true.

func (*Trie[T]) Clone added in v1.5.0 

func (trie *Trie[T]) Clone() *Trie[T]

Clone clones this trie.

func (*Trie[T]) ConstructAddedNodesTree added in v1.5.0 

func (trie *Trie[T]) ConstructAddedNodesTree() AddedTree[T]

ConstructAddedNodesTree constructs an associative trie in which the root and each added node have been mapped to a slice of their respective direct added sub-nodes. This trie provides an alternative non-binary tree structure of the added nodes. It is used by ToAddedNodesTreeString to produce a string showing the alternative structure. The returned AddedTree instance wraps the associative trie, presenting it as a non-binary tree with the alternative tree structure, the structure in which each node's child nodes are the list of direct and indirect added child nodes in the original trie. If there are no non-added nodes in this trie, then the alternative tree structure provided by this method is the same as the original trie.

func (*Trie[T]) ContainedFirstAllNodeIterator added in v1.5.0 

func (trie *Trie[T]) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) Iterator[*TrieNode[T]]

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary tree traversal. All sub-nodes will be visited before their parent nodes. For an address trie this means contained addresses and subnets will be visited before their containing subnet blocks.

func (*Trie[T]) ContainedFirstIterator added in v1.5.0 

func (trie *Trie[T]) ContainedFirstIterator(forwardSubNodeOrder bool) IteratorWithRemove[*TrieNode[T]]

ContainedFirstIterator returns an iterator that does a post-order binary tree traversal of the added nodes. All added sub-nodes will be visited before their parent nodes. For an address trie this means contained addresses and subnets will be visited before their containing subnet blocks.

func (*Trie[T]) ContainingFirstAllNodeIterator added in v1.5.0 

func (trie *Trie[T]) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingTrieIterator[*TrieNode[T]]

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary tree traversal. All nodes will be visited before their sub-nodes. For an address trie this means containing subnet blocks will be visited before their contained addresses and subnet blocks.

Once a given node is visited, the iterator allows you to cache an object corresponding to the lower or upper sub-node that can be retrieved when you later visit that sub-node. That allows you to provide iteration context from a parent to its sub-nodes when iterating. The caching and retrieval is done in constant time.

func (*Trie[T]) ContainingFirstIterator added in v1.5.0 

func (trie *Trie[T]) ContainingFirstIterator(forwardSubNodeOrder bool) CachingTrieIterator[*TrieNode[T]]

ContainingFirstIterator returns an iterator that does a pre-order binary tree traversal of the added nodes. All added nodes will be visited before their added sub-nodes. For an address trie this means added containing subnet blocks will be visited before their added contained addresses and subnet blocks.

Once a given node is visited, the iterator allows you to cache an object corresponding to the lower or upper sub-node that can be retrieved when you later visit that sub-node.

Objects are cached only with nodes to be visited. So for this iterator that means an object will be cached with the first added lower or upper sub-node, the next lower or upper sub-node to be visited, which is not necessarily the direct lower or upper sub-node of a given node.

The caching allows you to provide iteration context from a parent to its sub-nodes when iterating. The caching and retrieval is done in constant-time.

func (*Trie[T]) Contains added in v1.5.0 

func (trie *Trie[T]) Contains(addr T) bool

Contains returns whether the given address or prefix block subnet is in the trie as an added element.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the prefix block or address exists already in the trie, false otherwise.

Use GetAddedNode to get the node for the address rather than just checking for its existence.

func (*Trie[T]) DescendingIterator added in v1.5.0 

func (trie *Trie[T]) DescendingIterator() Iterator[T]

DescendingIterator returns an iterator that iterates through the added addresses and prefix blocks in the trie. The iteration is in reverse sorted element order.

func (*Trie[T]) ElementContains added in v1.5.0 

func (trie *Trie[T]) ElementContains(addr T) bool

ElementContains checks if a prefix block subnet or address in the trie contains the given subnet or address.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the subnet or address is contained by a trie element, false otherwise.

To get all the containing addresses, use ElementsContaining.

func (*Trie[T]) ElementsContainedBy added in v1.5.0 

func (trie *Trie[T]) ElementsContainedBy(addr T) *TrieNode[T]

ElementsContainedBy checks if a part of this trie is contained by the given prefix block subnet or individual address.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the root node of the contained sub-trie, or nil if no sub-trie is contained. The node returned need not be an "added" node, see IsAdded for more details on added nodes. The returned sub-trie is backed by this trie, so changes in this trie are reflected in those nodes and vice-versa.

func (*Trie[T]) ElementsContaining added in v1.5.0 

func (trie *Trie[T]) ElementsContaining(addr T) *ContainmentPath[T]

ElementsContaining finds the trie nodes in the trie containing the given key and returns them as a linked list. Only added nodes are added to the linked list.

If the argument is not a single address nor prefix block, this method will panic.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

func (*Trie[T]) Equal added in v1.5.0 

func (trie *Trie[T]) Equal(other *Trie[T]) bool

Equal returns whether the given argument is a trie with a set of nodes with the same keys as in this trie.

func (*Trie[T]) FirstAddedNode added in v1.5.0 

func (trie *Trie[T]) FirstAddedNode() *TrieNode[T]

FirstAddedNode returns the first (lowest valued) added node in this trie, or nil if there are no added entries in this trie or sub-trie.

func (*Trie[T]) FirstNode added in v1.5.0 

func (trie *Trie[T]) FirstNode() *TrieNode[T]

FirstNode returns the first (lowest valued) node in the trie.

func (*Trie[T]) FloorAddedNode added in v1.5.0 

func (trie *Trie[T]) FloorAddedNode(addr T) *TrieNode[T]

FloorAddedNode returns the added node whose address is the highest address less than or equal to the given address.

func (Trie[T]) Format added in v1.5.0 

func (trie Trie[T]) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface.

func (*Trie[T]) GetAddedNode added in v1.5.0 

func (trie *Trie[T]) GetAddedNode(addr T) *TrieNode[T]

GetAddedNode gets trie nodes representing added elements.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Use Contains to check for the existence of a given address in the trie, as well as GetNode to search for all nodes including those not-added but also auto-generated nodes for subnet blocks.

func (*Trie[T]) GetNode added in v1.5.0 

func (trie *Trie[T]) GetNode(addr T) *TrieNode[T]

GetNode gets the node in the trie corresponding to the given address, or returns nil if not such element exists.

It returns any node, whether added or not, including any prefix block node that was not added.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

func (*Trie[T]) GetRoot added in v1.5.0 

func (trie *Trie[T]) GetRoot() *TrieNode[T]

GetRoot returns the root node of this trie, which can be nil for an implicitly zero-valued uninitialized trie, but not for any other trie.

func (*Trie[T]) HigherAddedNode added in v1.5.0 

func (trie *Trie[T]) HigherAddedNode(addr T) *TrieNode[T]

HigherAddedNode returns the added node whose address is the lowest address strictly greater than the given address.

func (*Trie[T]) IsEmpty added in v1.5.0 

func (trie *Trie[T]) IsEmpty() bool

IsEmpty returns true if there are not any added nodes within this trie.

func (*Trie[T]) Iterator added in v1.5.0 

func (trie *Trie[T]) Iterator() Iterator[T]

Iterator returns an iterator that iterates through the added addresses and prefix blocks in the trie. The iteration is in sorted element order.

func (*Trie[T]) LastAddedNode added in v1.5.0 

func (trie *Trie[T]) LastAddedNode() *TrieNode[T]

LastAddedNode returns the last (highest valued) added node in the trie, or nil if there are no added entries in this tree or sub-tree.

func (*Trie[T]) LastNode added in v1.5.0 

func (trie *Trie[T]) LastNode() *TrieNode[T]

LastNode returns the last (highest valued) node in this trie.

func (*Trie[T]) LongestPrefixMatch added in v1.5.0 

func (trie *Trie[T]) LongestPrefixMatch(addr T) T

LongestPrefixMatch returns the address added to the trie with the longest matching prefix compared to the provided address, or nil if no matching address.

func (*Trie[T]) LongestPrefixMatchNode added in v1.5.0 

func (trie *Trie[T]) LongestPrefixMatchNode(addr T) *TrieNode[T]

LongestPrefixMatchNode returns the node of address added to the trie with the longest matching prefix compared to the provided address, or nil if no matching address.

func (*Trie[T]) LowerAddedNode added in v1.5.0 

func (trie *Trie[T]) LowerAddedNode(addr T) *TrieNode[T]

LowerAddedNode returns the added node whose address is the highest address strictly less than the given address.

func (*Trie[T]) NodeIterator added in v1.5.0 

func (trie *Trie[T]) NodeIterator(forward bool) IteratorWithRemove[*TrieNode[T]]

NodeIterator returns an iterator that iterates through all the added nodes in the trie in forward or reverse trie order.

func (*Trie[T]) NodeSize added in v1.5.0 

func (trie *Trie[T]) NodeSize() int

NodeSize returns the number of nodes in the trie, which is always more than the number of elements.

func (*Trie[T]) Remove added in v1.5.0 

func (trie *Trie[T]) Remove(addr T) bool

Remove removes the given single address or prefix block subnet from the trie.

Removing an element will not remove contained elements (nodes for contained blocks and addresses).

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the prefix block or address was removed, false if not already in the trie.

You can also remove by calling GetAddedNode to get the node and then calling Remove on the node.

When an address is removed, the corresponding node may remain in the trie if it remains a subnet block for two sub-nodes. If the corresponding node can be removed from the trie, it will be removed.

func (*Trie[T]) RemoveElementsContainedBy added in v1.5.0 

func (trie *Trie[T]) RemoveElementsContainedBy(addr T) *TrieNode[T]

RemoveElementsContainedBy removes any single address or prefix block subnet from the trie that is contained in the given individual address or prefix block subnet.

This goes further than Remove, not requiring a match to an inserted node, and also removing all the sub-nodes of any removed node or sub-node.

For example, after inserting 1.2.3.0 and 1.2.3.1, passing 1.2.3.0/31 to RemoveElementsContainedBy will remove them both, while the Remove method will remove nothing. After inserting 1.2.3.0/31, then Remove will remove 1.2.3.0/31, but will leave 1.2.3.0 and 1.2.3.1 in the trie.

It cannot partially delete a node, such as deleting a single address from a prefix block represented by a node. It can only delete the whole node if the whole address or block represented by that node is contained in the given address or block.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the root node of the sub-trie that was removed from the trie, or nil if nothing was removed.

func (*Trie[T]) ShortestPrefixMatch added in v1.5.5 

func (trie *Trie[T]) ShortestPrefixMatch(addr T) T

ShortestPrefixMatch returns the address added to the trie with the shortest matching prefix compared to the provided address, or nil if no matching address.

func (*Trie[T]) ShortestPrefixMatchNode added in v1.5.5 

func (trie *Trie[T]) ShortestPrefixMatchNode(addr T) *TrieNode[T]

ShortestPrefixMatchNode returns the node of the address added to the trie with the shortest matching prefix compared to the provided address, or nil if no matching address.

func (*Trie[T]) Size added in v1.5.0 

func (trie *Trie[T]) Size() int

Size returns the number of elements in the trie. It does not return the number of nodes, it returns the number of added nodes. Only nodes for which IsAdded returns true are counted (those nodes corresponding to added addresses and prefix blocks). When zero is returned, IsEmpty returns true.

func (*Trie[T]) String added in v1.5.0 

func (trie *Trie[T]) String() string

String returns a visual representation of the trie with one node per line.

func (*Trie[T]) TreeString added in v1.5.0 

func (trie *Trie[T]) TreeString(withNonAddedKeys bool) string

TreeString returns a visual representation of the trie with one node per line, with or without the non-added keys.

type TrieKeyConstraint added in v1.5.0 

type TrieKeyConstraint[T any] interface {
	comparable

	BitItem

	fmt.Stringer

	PrefixedConstraint[T]

	IsOneBit(index BitCount) bool // AddressComponent
	// contains filtered or unexported methods
}

TrieKeyConstraint is the generic type constraint used for tree keys, which are individual addresses and prefix block subnets.

type TrieNode added in v1.5.0 

type TrieNode[T TrieKeyConstraint[T]] struct {
	// contains filtered or unexported fields
}

TrieNode is a node in a compact binary prefix trie whose elements (keys) are prefix block subnets or addresses.

func (*TrieNode[T]) AllNodeIterator added in v1.5.0 

func (node *TrieNode[T]) AllNodeIterator(forward bool) IteratorWithRemove[*TrieNode[T]]

AllNodeIterator returns an iterator that iterates through all the nodes of the sub-trie with this node as the root, in forward or reverse trie order.

func (*TrieNode[T]) AsNewTrie added in v1.5.0 

func (node *TrieNode[T]) AsNewTrie() *Trie[T]

AsNewTrie creates a new sub-trie, copying the nodes starting with this node as the root. The nodes are copies of the nodes in this sub-trie, but their keys and values are not copies.

func (*TrieNode[T]) BlockSizeAllNodeIterator added in v1.5.0 

func (node *TrieNode[T]) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IteratorWithRemove[*TrieNode[T]]

BlockSizeAllNodeIterator returns an iterator that iterates all the nodes, ordered by keys from largest prefix blocks to smallest and then to individual addresses, in the sub-trie with this node as the root.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order.

func (*TrieNode[T]) BlockSizeCachingAllNodeIterator added in v1.5.0 

func (node *TrieNode[T]) BlockSizeCachingAllNodeIterator() CachingTrieIterator[*TrieNode[T]]

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from largest prefix blocks to smallest and then to individual addresses, in the sub-trie with this node as the root.

func (*TrieNode[T]) BlockSizeNodeIterator added in v1.5.0 

func (node *TrieNode[T]) BlockSizeNodeIterator(lowerSubNodeFirst bool) IteratorWithRemove[*TrieNode[T]]

BlockSizeNodeIterator returns an iterator that iterates the added nodes, ordered by keys from largest prefix blocks to smallest and then to individual addresses, in the sub-trie with this node as the root.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order is taken.

func (*TrieNode[T]) CeilingAddedNode added in v1.5.0 

func (node *TrieNode[T]) CeilingAddedNode(addr T) *TrieNode[T]

CeilingAddedNode returns the added node, in this sub-trie with this node as the root, whose address is the lowest address greater than or equal to the given address.

func (*TrieNode[T]) Clear added in v1.5.0 

func (node *TrieNode[T]) Clear()

Clear removes this node and all sub-nodes from the trie, after which isEmpty will return true.

func (*TrieNode[T]) Clone added in v1.5.0 

func (node *TrieNode[T]) Clone() *TrieNode[T]

Clone clones the node. Keys remain the same, but the parent node and the lower and upper sub-nodes are all set to nil.

func (*TrieNode[T]) CloneTree added in v1.5.0 

func (node *TrieNode[T]) CloneTree() *TrieNode[T]

CloneTree clones the sub-trie starting with this node as the root. The nodes are cloned, but their keys and values are not cloned.

func (*TrieNode[T]) Compare added in v1.5.0 

func (node *TrieNode[T]) Compare(other *TrieNode[T]) int

Compare returns a negative integer, zero, or a positive integer if this node is less than, equal, or greater than the other, according to the key and the trie order.

func (*TrieNode[T]) ContainedFirstAllNodeIterator added in v1.5.0 

func (node *TrieNode[T]) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) Iterator[*TrieNode[T]]

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary trie traversal of all the nodes of the sub-trie with this node as the root. All sub-nodes will be visited before their parent nodes. For an address trie this means contained addresses and subnets will be visited before their containing subnet blocks.

func (*TrieNode[T]) ContainedFirstIterator added in v1.5.0 

func (node *TrieNode[T]) ContainedFirstIterator(forwardSubNodeOrder bool) IteratorWithRemove[*TrieNode[T]]

ContainedFirstIterator returns an iterator that does a post-order binary trie traversal of the added nodes of the sub-trie with this node as the root. All added sub-nodes will be visited before their parent nodes. For an address trie this means contained addresses and subnets will be visited before their containing subnet blocks.

func (*TrieNode[T]) ContainingFirstAllNodeIterator added in v1.5.0 

func (node *TrieNode[T]) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingTrieIterator[*TrieNode[T]]

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary trie traversal of all the nodes of the sub-trie with this node as the root.

All nodes will be visited before their sub-nodes. For an address trie this means containing subnet blocks will be visited before their contained addresses and subnet blocks.

Once a given node is visited, the iterator allows you to cache an object corresponding to the lower or upper sub-node that can be retrieved when you later visit that sub-node. That allows you to provide iteration context from a parent to its sub-nodes when iterating. The caching and retrieval is done in constant-time.

func (*TrieNode[T]) ContainingFirstIterator added in v1.5.0 

func (node *TrieNode[T]) ContainingFirstIterator(forwardSubNodeOrder bool) CachingTrieIterator[*TrieNode[T]]

ContainingFirstIterator returns an iterator that does a pre-order binary trie traversal of the added nodes of the sub-trie with this node as the root.

All added nodes will be visited before their added sub-nodes. For an address trie this means added containing subnet blocks will be visited before their added contained addresses and subnet blocks.

Once a given node is visited, the iterator allows you to cache an object corresponding to the lower or upper sub-node that can be retrieved when you later visit that sub-node.

Objects are cached only with nodes to be visited. So for this iterator that means an object will be cached with the first added lower or upper sub-node, the next lower or upper sub-node to be visited, which is not necessarily the direct lower or upper sub-node of a given node.

The caching allows you to provide iteration context from a parent to its sub-nodes when iterating. The caching and retrieval is done in constant-time.

func (*TrieNode[T]) Contains added in v1.5.0 

func (node *TrieNode[T]) Contains(addr T) bool

Contains returns whether the given address or prefix block subnet is in the sub-trie, as an added element, with this node as the root.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the prefix block or address address exists already in the trie, false otherwise.

Use GetAddedNode to get the node for the address rather than just checking for its existence.

func (*TrieNode[T]) DescendingIterator added in v1.5.0 

func (node *TrieNode[T]) DescendingIterator() Iterator[T]

DescendingIterator returns an iterator that iterates through the elements of the subtrie with this node as the root. The iteration is in reverse sorted element order.

func (*TrieNode[T]) ElementContains added in v1.5.0 

func (node *TrieNode[T]) ElementContains(addr T) bool

ElementContains checks if a prefix block subnet or address in the trie, with this node as the root, contains the given subnet or address.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the subnet or address is contained by a trie element, false otherwise.

To get all the containing addresses, use ElementsContaining.

func (*TrieNode[T]) ElementsContainedBy added in v1.5.0 

func (node *TrieNode[T]) ElementsContainedBy(addr T) *TrieNode[T]

ElementsContainedBy checks if a part of this trie, with this node as the root, is contained by the given prefix block subnet or individual address.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the root node of the contained subtrie, or nil if no subtrie is contained. The node returned need not be an "added" node, see IsAdded for more details on added nodes. The returned subtrie is backed by this trie, so changes in this trie are reflected in those nodes and vice-versa.

func (*TrieNode[T]) ElementsContaining added in v1.5.0 

func (node *TrieNode[T]) ElementsContaining(addr T) *ContainmentPath[T]

ElementsContaining finds the trie nodes in the trie, with this sub-node as the root, containing the given key and returns them as a linked list. Only added nodes are added to the linked list

If the argument is not a single address nor prefix block, this method will panic.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

func (*TrieNode[T]) Equal added in v1.5.0 

func (node *TrieNode[T]) Equal(other *TrieNode[T]) bool

Equal returns whether the address and and mapped value match those of the given node.

func (*TrieNode[T]) FirstAddedNode added in v1.5.0 

func (node *TrieNode[T]) FirstAddedNode() *TrieNode[T]

FirstAddedNode returns the first (the lowest valued) added node in the sub-trie originating from this node, or nil if there are no added entries in this trie or sub-trie.

func (*TrieNode[T]) FirstNode added in v1.5.0 

func (node *TrieNode[T]) FirstNode() *TrieNode[T]

FirstNode returns the first (the lowest valued) node in the sub-trie originating from this node.

func (*TrieNode[T]) FloorAddedNode added in v1.5.0 

func (node *TrieNode[T]) FloorAddedNode(addr T) *TrieNode[T]

FloorAddedNode returns the added node, in this sub-trie with this node as the root, whose address is the highest address less than or equal to the given address.

func (TrieNode[T]) Format added in v1.5.0 

func (node TrieNode[T]) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface.

func (*TrieNode[T]) GetAddedNode added in v1.5.0 

func (node *TrieNode[T]) GetAddedNode(addr T) *TrieNode[T]

GetAddedNode gets trie nodes representing added elements.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Use Contains to check for the existence of a given address in the trie, as well as GetNode to search for all nodes including those not-added but also auto-generated nodes for subnet blocks.

func (*TrieNode[T]) GetKey added in v1.5.0 

func (node *TrieNode[T]) GetKey() T

GetKey gets the key used to place the node in the trie.

func (*TrieNode[T]) GetLowerSubNode added in v1.5.0 

func (node *TrieNode[T]) GetLowerSubNode() *TrieNode[T]

GetLowerSubNode gets the direct child node whose key is smallest in value.

func (*TrieNode[T]) GetNode added in v1.5.0 

func (node *TrieNode[T]) GetNode(addr T) *TrieNode[T]

GetNode gets the node in the trie, with this subnode as the root, corresponding to the given address, or returns nil if not such element exists.

It returns any node, whether added or not, including any prefix block node that was not added.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

func (*TrieNode[T]) GetParent added in v1.5.0 

func (node *TrieNode[T]) GetParent() *TrieNode[T]

GetParent gets the node from which this node is a direct child node, or nil if this is the root.

func (*TrieNode[T]) GetUpperSubNode added in v1.5.0 

func (node *TrieNode[T]) GetUpperSubNode() *TrieNode[T]

GetUpperSubNode gets the direct child node whose key is largest in value.

func (*TrieNode[T]) HigherAddedNode added in v1.5.0 

func (node *TrieNode[T]) HigherAddedNode(addr T) *TrieNode[T]

HigherAddedNode returns the added node, in this sub-trie with this node as the root, whose address is the lowest address strictly greater than the given address.

func (*TrieNode[T]) IsAdded added in v1.5.0 

func (node *TrieNode[T]) IsAdded() bool

IsAdded returns whether the node was "added". Some binary trie nodes are considered "added" and others are not. Those nodes created for key elements added to the trie are "added" nodes. Those that are not added are those nodes created to serve as junctions for the added nodes. Only added elements contribute to the size of a trie. When removing nodes, non-added nodes are removed automatically whenever they are no longer needed, which is when an added node has less than two added sub-nodes.

func (*TrieNode[T]) IsEmpty added in v1.5.0 

func (node *TrieNode[T]) IsEmpty() bool

IsEmpty returns whether the size is zero.

func (*TrieNode[T]) IsLeaf added in v1.5.0 

func (node *TrieNode[T]) IsLeaf() bool

IsLeaf returns whether this node is in the trie (a node for which IsAdded is true) and there are no elements in the sub-trie with this node as the root.

func (*TrieNode[T]) IsRoot added in v1.5.0 

func (node *TrieNode[T]) IsRoot() bool

IsRoot returns whether this node is the root of the trie.

func (*TrieNode[T]) Iterator added in v1.5.0 

func (node *TrieNode[T]) Iterator() Iterator[T]

Iterator returns an iterator that iterates through the elements of the sub-trie with this node as the root. The iteration is in sorted element order.

func (*TrieNode[T]) LastAddedNode added in v1.5.0 

func (node *TrieNode[T]) LastAddedNode() *TrieNode[T]

LastAddedNode returns the last (the highest valued) added node in the sub-trie originating from this node, or nil if there are no added entries in this trie or sub-trie.

func (*TrieNode[T]) LastNode added in v1.5.0 

func (node *TrieNode[T]) LastNode() *TrieNode[T]

LastNode returns the last (the highest valued) node in the sub-trie originating from this node.

func (*TrieNode[T]) LongestPrefixMatch added in v1.5.0 

func (node *TrieNode[T]) LongestPrefixMatch(addr T) T

LongestPrefixMatch returns the address or subnet with the longest prefix of all the added subnets and addresses whose prefix matches the given address. This is equivalent to finding the containing subnet or address with the smallest subnet size.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

The second returned argument is false if no added subnet or address contains the given argument.

Use ElementContains to check for the existence of a containing address. To get all the containing addresses (subnets with matching prefix), use ElementsContaining. To get the node corresponding to the result of this method, use LongestPrefixMatchNode.

func (*TrieNode[T]) LongestPrefixMatchNode added in v1.5.0 

func (node *TrieNode[T]) LongestPrefixMatchNode(addr T) *TrieNode[T]

LongestPrefixMatchNode finds the containing subnet or address in the trie with the smallest subnet size, which is equivalent to finding the subnet or address with the longest matching prefix. Returns the node corresponding to that subnet.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns nil if no added subnet or address contains the given argument.

Use ElementContains to check for the existence of a containing address. To get all the containing addresses, use ElementsContaining. Use LongestPrefixMatch to get only the address corresponding to the result of this method.

func (*TrieNode[T]) LowerAddedNode added in v1.5.0 

func (node *TrieNode[T]) LowerAddedNode(addr T) *TrieNode[T]

LowerAddedNode returns the added node, in this sub-trie with this node as the root, whose address is the highest address strictly less than the given address.

func (*TrieNode[T]) NextAddedNode added in v1.5.0 

func (node *TrieNode[T]) NextAddedNode() *TrieNode[T]

NextAddedNode returns the next node in the trie that is an added node, following the trie order, or nil if there is no such node.

func (*TrieNode[T]) NextNode added in v1.5.0 

func (node *TrieNode[T]) NextNode() *TrieNode[T]

NextNode returns the node that follows this node following the trie order.

func (*TrieNode[T]) NodeIterator added in v1.5.0 

func (node *TrieNode[T]) NodeIterator(forward bool) IteratorWithRemove[*TrieNode[T]]

NodeIterator returns an iterator that iterates through the added nodes of the sub-trie with this node as the root, in forward or reverse trie order.

func (*TrieNode[T]) NodeSize added in v1.5.0 

func (node *TrieNode[T]) NodeSize() int

NodeSize returns the number of nodes in the trie with this node as the root, which is more than the number of added addresses or blocks.

func (*TrieNode[T]) PreviousAddedNode added in v1.5.0 

func (node *TrieNode[T]) PreviousAddedNode() *TrieNode[T]

PreviousAddedNode returns the previous node in the trie that is an added node, following the trie order in reverse, or nil if there is no such node.

func (*TrieNode[T]) PreviousNode added in v1.5.0 

func (node *TrieNode[T]) PreviousNode() *TrieNode[T]

PreviousNode eturns the node that precedes this node following the trie order.

func (*TrieNode[T]) Remove added in v1.5.0 

func (node *TrieNode[T]) Remove()

Remove removes this node from the collection of added nodes, and also from the trie if possible. If it has two sub-nodes, it cannot be removed from the trie, in which case it is marked as not "added", nor is it counted in the trie size. Only added nodes can be removed from the trie. If this node is not added, this method does nothing.

func (*TrieNode[T]) RemoveElementsContainedBy added in v1.5.0 

func (node *TrieNode[T]) RemoveElementsContainedBy(addr T) *TrieNode[T]

RemoveElementsContainedBy removes any single address or prefix block subnet from the trie, with this node as the root, that is contained in the given individual address or prefix block subnet.

Goes further than Remove, not requiring a match to an inserted node, and also removing all the sub-nodes of any removed node or sub-node.

For example, after inserting 1.2.3.0 and 1.2.3.1, passing 1.2.3.0/31 to RemoveElementsContainedBy will remove them both, while the Remove method will remove nothing. After inserting 1.2.3.0/31, then Remove(Address) will remove 1.2.3.0/31, but will leave 1.2.3.0 and 1.2.3.1 in the trie.

It cannot partially delete a node, such as deleting a single address from a prefix block represented by a node. It can only delete the whole node if the whole address or block represented by that node is contained in the given address or block.

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns the root node of the subtrie that was removed from the trie, or nil if nothing was removed.

func (*TrieNode[T]) RemoveNode added in v1.5.0 

func (node *TrieNode[T]) RemoveNode(addr T) bool

RemoveNode removes the given single address or prefix block subnet from the trie with this node as the root.

Removing an element will not remove contained elements (nodes for contained blocks and addresses).

If the argument is not a single address nor prefix block, this method will panic. The Partition type can be used to convert the argument to single addresses and prefix blocks before calling this method.

Returns true if the prefix block or address was removed, false if not already in the trie.

You can also remove by calling GetAddedNode to get the node and then calling Remove on the node.

When an address is removed, the corresponding node may remain in the trie if it remains a subnet block for two sub-nodes. If the corresponding node can be removed from the trie, it will be removed.

func (*TrieNode[T]) SetAdded added in v1.5.0 

func (node *TrieNode[T]) SetAdded()

SetAdded makes this node an added node, which is equivalent to adding the corresponding key to the trie. If the node is already an added node, this method has no effect. You cannot set an added node to non-added, for that you should Remove the node from the trie by calling Remove. A non-added node will only remain in the trie if it needs to be in the trie.

func (*TrieNode[T]) Size added in v1.5.0 

func (node *TrieNode[T]) Size() int

Size returns the number of elements in the sub-trie with this node as the root. Only nodes for which IsAdded returns true are counted. When zero is returned, IsEmpty returns true.

func (*TrieNode[T]) String added in v1.5.0 

func (node *TrieNode[T]) String() string

String returns a visual representation of this node including the key, with an open circle indicating this node is not an added node, a closed circle indicating this node is an added node.

func (*TrieNode[T]) TreeEqual added in v1.5.0 

func (node *TrieNode[T]) TreeEqual(other *TrieNode[T]) bool

TreeEqual returns whether the sub-tree represented by this node as the root node matches the given sub-trie.

func (*TrieNode[T]) TreeString added in v1.5.0 

func (node *TrieNode[T]) TreeString(withNonAddedKeys, withSizes bool) string

TreeString returns a visual representation of the sub-trie with this node as the root, with one node per line.

  • withNonAddedKeys: whether to show nodes that are not added nodes.
  • withSizes: whether to include the counts of added nodes in each sub-trie.

type WrappedAddress 

type WrappedAddress struct {
	*Address
}

WrappedAddress is the implementation of ExtendedSegmentSeries for addresses.

func (WrappedAddress) AdjustPrefixLen 

func (addr WrappedAddress) AdjustPrefixLen(prefixLen BitCount) ExtendedSegmentSeries

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (WrappedAddress) AdjustPrefixLenZeroed 

func (addr WrappedAddress) AdjustPrefixLenZeroed(prefixLen BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

func (WrappedAddress) AssignMinPrefixForBlock 

func (addr WrappedAddress) AssignMinPrefixForBlock() ExtendedSegmentSeries

AssignMinPrefixForBlock returns an equivalent series, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this series.

In other words, this method assigns a prefix length to this series matching the largest prefix block in this series.

func (WrappedAddress) AssignPrefixForSingleBlock 

func (addr WrappedAddress) AssignPrefixForSingleBlock() ExtendedSegmentSeries

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this series. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such series - it is required that the range of values match the range of a prefix block. If there is no such series, then nil is returned.

func (WrappedAddress) Contains 

func (addr WrappedAddress) Contains(other ExtendedSegmentSeries) bool

Contains returns whether this is same type and version as the given address series and whether it contains all values in the given series.

Series must also have the same number of segments to be comparable, otherwise false is returned.

func (WrappedAddress) ContainsPrefixBlock 

func (addr WrappedAddress) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or subnet contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (WrappedAddress) ContainsSinglePrefixBlock 

func (addr WrappedAddress) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (WrappedAddress) Equal 

func (addr WrappedAddress) Equal(other ExtendedSegmentSeries) bool

Equal returns whether the given address series is equal to this address series. Two address series are equal if they represent the same set of series. Both must be equal addresses.

func (WrappedAddress) GetBitCount 

func (addr WrappedAddress) GetBitCount() BitCount

GetBitCount returns the number of bits comprising this address, or each address in the range if a subnet.

func (WrappedAddress) GetBitsPerSegment 

func (addr WrappedAddress) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this address or subnet. Segments in the same address are equal length.

func (WrappedAddress) GetBlockCount 

func (addr WrappedAddress) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (WrappedAddress) GetByteCount 

func (addr WrappedAddress) GetByteCount() int

GetByteCount returns the number of bytes required for this address, or each address in the range if a subnet.

func (WrappedAddress) GetBytesPerSegment 

func (addr WrappedAddress) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this address or subnet. Segments in the same address are equal length.

func (WrappedAddress) GetLower 

func (addr WrappedAddress) GetLower() ExtendedSegmentSeries

GetLower returns the series in the range with the lowest numeric value, which will be the same series if it represents a single value.

func (WrappedAddress) GetMinPrefixLenForBlock 

func (addr WrappedAddress) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

func (WrappedAddress) GetPrefixCount 

func (addr WrappedAddress) GetPrefixCount() *big.Int

GetPrefixCount returns the count of prefixes in this address or subnet.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the count of the range of values in the prefix.

If this has a nil prefix length, returns the same value as GetCount.

func (WrappedAddress) GetPrefixCountLen 

func (addr WrappedAddress) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the count of prefixes in this address or subnet for the given prefix length.

If not a subnet of multiple addresses, or a subnet with just single prefix of the given length, returns 1.

func (WrappedAddress) GetPrefixLen 

func (addr WrappedAddress) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part (most significant bits) of the address that comprise the prefix.

A prefix is a part of the address that is not specific to that address but common amongst a group of addresses, such as a CIDR prefix block subnet.

For IP addresses, the prefix is explicitly defined when the address is created. For example, "1.2.0.0/16" has a prefix length of 16, while "1.2.*.*" has no prefix length, even though they both represent the same set of addresses and are considered equal. Prefixes can be considered variable for a given IP address and can depend on routing.

The methods GetMinPrefixLenForBlock and GetPrefixLenForSingleBlock can help you to obtain or define a prefix length if one does not exist already. The method ToPrefixBlockLen allows you to create the subnet consisting of the block of addresses for any given prefix length.

For MAC addresses, the prefix is initially inferred from the range, so "1:2:3:*:*:*" has a prefix length of 24. MAC addresses derived from an address with a prefix length may retain the prefix length regardless of their own range of values.

func (WrappedAddress) GetPrefixLenForSingleBlock 

func (addr WrappedAddress) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address subnet matches exactly the block of addresses for that prefix.

If the range can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix exists, returns nil.

If this segment grouping represents a single value, returns the bit length of this address.

IP address examples:

  • 1.2.3.4 returns 32
  • 1.2.3.4/16 returns 32
  • 1.2.*.* returns 16
  • 1.2.*.0/24 returns 16
  • 1.2.0.0/16 returns 16
  • 1.2.*.4 returns nil
  • 1.2.252-255.* returns 22

func (WrappedAddress) GetSection 

func (addr WrappedAddress) GetSection() *AddressSection

GetSection returns the backing section for this series, comprising all segments.

func (WrappedAddress) GetUpper 

func (addr WrappedAddress) GetUpper() ExtendedSegmentSeries

GetUpper returns the series in the range with the highest numeric value, which will be the same series if it represents a single value.

func (WrappedAddress) IncludesZero 

func (addr WrappedAddress) IncludesZero() bool

IncludesZero returns whether this address includes the zero address within its range.

func (WrappedAddress) Increment 

func (addr WrappedAddress) Increment(i int64) ExtendedSegmentSeries

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (WrappedAddress) IncrementBoundary 

func (addr WrappedAddress) IncrementBoundary(i int64) ExtendedSegmentSeries

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (WrappedAddress) IsFullRange 

func (addr WrappedAddress) IsFullRange() bool

IsFullRange returns whether this address covers the entire address space of this address version or type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (WrappedAddress) IsPrefixBlock 

func (addr WrappedAddress) IsPrefixBlock() bool

IsPrefixBlock returns whether the address has a prefix length and the address range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

To create a prefix block from any address, use ToPrefixBlock.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (WrappedAddress) IsSequential 

func (addr WrappedAddress) IsSequential() bool

IsSequential returns whether the address or subnet represents a range of addresses that are sequential.

Generally, for a subnet this means that any segment covering a range of values must be followed by segments that are full range, covering all values.

Individual addresses are sequential and CIDR prefix blocks are sequential. The subnet "1.2.3-4.5" is not sequential, since the two addresses it represents, "1.2.3.5" and "1.2.4.5", are not ("1.2.3.6" is in-between the two but not in the subnet).

With any IP address subnet, you can use SequentialBlockIterator to convert any subnet to a collection of sequential subnets.

func (WrappedAddress) IsSinglePrefixBlock 

func (addr WrappedAddress) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the address range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

For instance, "1.*.*.* /16" returns false from this method and returns true from IsPrefixBlock.

func (WrappedAddress) IsZero 

func (addr WrappedAddress) IsZero() bool

IsZero returns whether this address matches exactly the value of zero.

func (WrappedAddress) Iterator 

func (addr WrappedAddress) Iterator() Iterator[ExtendedSegmentSeries]

Iterator provides an iterator to iterate through the individual series of this series.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual series.

Call IsMultiple to determine if this instance represents multiple series, or GetCount for the count.

func (WrappedAddress) PrefixBlockIterator 

func (addr WrappedAddress) PrefixBlockIterator() Iterator[ExtendedSegmentSeries]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this series. Each iterated series will be a prefix block with the same prefix length as this series.

If this series has no prefix length, then this is equivalent to Iterator.

func (WrappedAddress) PrefixIterator 

func (addr WrappedAddress) PrefixIterator() Iterator[ExtendedSegmentSeries]

PrefixIterator provides an iterator to iterate through the individual prefixes of this series, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this series.

If the series has no prefix length, then this is equivalent to Iterator.

func (WrappedAddress) ReverseBits 

func (addr WrappedAddress) ReverseBits(perByte bool) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBits returns a new segment series with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (WrappedAddress) ReverseBytes 

func (addr WrappedAddress) ReverseBytes() (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBytes returns a new segment series with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (WrappedAddress) ReverseSegments 

func (addr WrappedAddress) ReverseSegments() ExtendedSegmentSeries

ReverseSegments returns a new series with the segments reversed.

func (WrappedAddress) SetPrefixLen 

func (addr WrappedAddress) SetPrefixLen(prefixLen BitCount) ExtendedSegmentSeries

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

func (WrappedAddress) SetPrefixLenZeroed 

func (addr WrappedAddress) SetPrefixLenZeroed(prefixLen BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedAddress) ToBlock 

func (addr WrappedAddress) ToBlock(segmentIndex int, lower, upper SegInt) ExtendedSegmentSeries

ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (WrappedAddress) ToIP 

func (addr WrappedAddress) ToIP() IPAddressSegmentSeries

ToIP converts to an IP address if this originated as IPv4 or IPv6, or an implicitly zero-valued IP. If not, ToIP returns nil.

func (WrappedAddress) ToIPv4 

func (addr WrappedAddress) ToIPv4() IPv4AddressSegmentSeries

ToIPv4 converts to an IPv4AddressSegmentSeries if this series originated as an IPv4 series. If not, ToIPv4 returns nil.

ToIPv4 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddress) ToIPv6 

func (addr WrappedAddress) ToIPv6() IPv6AddressSegmentSeries

ToIPv6 converts to an IPv4AddressSegmentSeries if this series originated as an IPv6 series. If not, ToIPv6 returns nil.

ToIPv6 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddress) ToMAC 

func (addr WrappedAddress) ToMAC() MACAddressSegmentSeries

ToMAC converts to a MACAddressSegmentSeries if this series originated as a MAC series. If not, ToMAC returns nil.

ToMAC implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddress) ToPrefixBlock 

func (addr WrappedAddress) ToPrefixBlock() ExtendedSegmentSeries

ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values. The series will be the block of all series with the same prefix.

If this series has no prefix, this series is returned.

func (WrappedAddress) ToPrefixBlockLen added in v1.2.0 

func (addr WrappedAddress) ToPrefixBlockLen(prefLen BitCount) ExtendedSegmentSeries

ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values. The returned series will be the block of all series with the same prefix.

func (WrappedAddress) Unwrap 

func (addr WrappedAddress) Unwrap() AddressSegmentSeries

Unwrap returns the wrapped address as an interface, AddressSegmentSeries.

func (WrappedAddress) WithoutPrefixLen 

func (addr WrappedAddress) WithoutPrefixLen() ExtendedSegmentSeries

WithoutPrefixLen provides the same address series but with no prefix length. The values remain unchanged.

type WrappedAddressSection 

type WrappedAddressSection struct {
	*AddressSection
}

WrappedAddressSection is the implementation of ExtendedSegmentSeries for address sections.

func (WrappedAddressSection) AdjustPrefixLen 

func (section WrappedAddressSection) AdjustPrefixLen(adjustment BitCount) ExtendedSegmentSeries

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (WrappedAddressSection) AdjustPrefixLenZeroed 

func (section WrappedAddressSection) AdjustPrefixLenZeroed(adjustment BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

func (WrappedAddressSection) AssignMinPrefixForBlock 

func (section WrappedAddressSection) AssignMinPrefixForBlock() ExtendedSegmentSeries

AssignMinPrefixForBlock returns an equivalent series, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this series.

In other words, this method assigns a prefix length to this series matching the largest prefix block in this series.

func (WrappedAddressSection) AssignPrefixForSingleBlock 

func (section WrappedAddressSection) AssignPrefixForSingleBlock() ExtendedSegmentSeries

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this series. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such series - it is required that the range of values match the range of a prefix block. If there is no such series, then nil is returned.

func (WrappedAddressSection) Bytes 

func (section WrappedAddressSection) Bytes() []byte

Bytes returns the lowest individual address section in this address section as a byte slice.

func (WrappedAddressSection) Contains 

func (section WrappedAddressSection) Contains(other ExtendedSegmentSeries) bool

Contains returns whether this is same type and version as the given address series and whether it contains all values in the given series.

Series must also have the same number of segments to be comparable, otherwise false is returned.

func (WrappedAddressSection) ContainsPrefixBlock 

func (section WrappedAddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (WrappedAddressSection) ContainsSinglePrefixBlock 

func (section WrappedAddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this grouping contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (WrappedAddressSection) CopyBytes 

func (section WrappedAddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (WrappedAddressSection) CopyUpperBytes 

func (section WrappedAddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (WrappedAddressSection) Equal 

func (section WrappedAddressSection) Equal(other ExtendedSegmentSeries) bool

Equal returns whether the given address series is equal to this address series. Two address series are equal if they represent the same set of series. Both must be equal sections.

func (WrappedAddressSection) ForEachSegment added in v1.2.0 

func (section WrappedAddressSection) ForEachSegment(consumer func(segmentIndex int, segment *AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (WrappedAddressSection) Format 

func (section WrappedAddressSection) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats

  • 'v' for the default address and section format (either the normalized or canonical string),
  • 's' (string) for the same,
  • 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix),
  • 'd' (decimal), 'x' (lowercase hexadecimal), and
  • 'X' (uppercase hexadecimal).

Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which adds a leading zero for octal, and for hexadecimal it adds a leading "0x" or "0X" for "%#x" and "%#X" respectively. Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (WrappedAddressSection) GetBitCount 

func (section WrappedAddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (WrappedAddressSection) GetBitsPerSegment 

func (section WrappedAddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (WrappedAddressSection) GetByteCount 

func (section WrappedAddressSection) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item.

func (WrappedAddressSection) GetBytesPerSegment 

func (section WrappedAddressSection) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this section. Segments in the same address section are equal length.

func (WrappedAddressSection) GetGenericSegment 

func (section WrappedAddressSection) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment as an AddressSegmentType, allowing all segment types to be represented by a single type. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (WrappedAddressSection) GetLeadingBitCount added in v1.1.0 

func (section WrappedAddressSection) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower value of the range if this section represents multiple values.

func (WrappedAddressSection) GetLower 

func (section WrappedAddressSection) GetLower() ExtendedSegmentSeries

GetLower returns the series in the range with the lowest numeric value, which will be the same series if it represents a single value.

func (WrappedAddressSection) GetMaxSegmentValue 

func (section WrappedAddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (WrappedAddressSection) GetMinPrefixLenForBlock 

func (section WrappedAddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (WrappedAddressSection) GetPrefixLen 

func (section WrappedAddressSection) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (WrappedAddressSection) GetPrefixLenForSingleBlock 

func (section WrappedAddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (WrappedAddressSection) GetSection 

func (section WrappedAddressSection) GetSection() *AddressSection

GetSection returns the backing section for this series, comprising all segments.

func (WrappedAddressSection) GetSegment 

func (section WrappedAddressSection) GetSegment(index int) *AddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (WrappedAddressSection) GetSegmentCount 

func (section WrappedAddressSection) GetSegmentCount() int

GetSegmentCount returns the segment count.

func (WrappedAddressSection) GetSequentialBlockCount 

func (section WrappedAddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section.

func (WrappedAddressSection) GetSequentialBlockIndex 

func (section WrappedAddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (WrappedAddressSection) GetTrailingBitCount added in v1.1.0 

func (section WrappedAddressSection) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies to the lower value of the range if this section represents multiple values.

func (WrappedAddressSection) GetUpper 

func (section WrappedAddressSection) GetUpper() ExtendedSegmentSeries

GetUpper returns the series in the range with the highest numeric value, which will be the same series if it represents a single value.

func (WrappedAddressSection) GetUpperValue 

func (section WrappedAddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value.

func (WrappedAddressSection) GetValue 

func (section WrappedAddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value.

func (WrappedAddressSection) IncludesMax 

func (section WrappedAddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range.

func (WrappedAddressSection) IncludesZero 

func (section WrappedAddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range.

func (WrappedAddressSection) Increment 

func (section WrappedAddressSection) Increment(i int64) ExtendedSegmentSeries

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (WrappedAddressSection) IncrementBoundary 

func (section WrappedAddressSection) IncrementBoundary(i int64) ExtendedSegmentSeries

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (WrappedAddressSection) IsFullRange 

func (section WrappedAddressSection) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (WrappedAddressSection) IsMax 

func (section WrappedAddressSection) IsMax() bool

IsMax returns whether this section matches exactly the maximum possible value, the value whose bits are all ones.

func (WrappedAddressSection) IsOneBit 

func (section WrappedAddressSection) IsOneBit(prefixBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (WrappedAddressSection) IsPrefixBlock 

func (section WrappedAddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (WrappedAddressSection) IsSequential 

func (section WrappedAddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (WrappedAddressSection) IsSinglePrefixBlock 

func (section WrappedAddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from a prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (WrappedAddressSection) IsZero 

func (section WrappedAddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero.

func (WrappedAddressSection) Iterator 

func (section WrappedAddressSection) Iterator() Iterator[ExtendedSegmentSeries]

Iterator provides an iterator to iterate through the individual series of this series.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual series.

Call IsMultiple to determine if this instance represents multiple series, or GetCount for the count.

func (WrappedAddressSection) PrefixBlockIterator 

func (section WrappedAddressSection) PrefixBlockIterator() Iterator[ExtendedSegmentSeries]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this series. Each iterated series will be a prefix block with the same prefix length as this series.

If this series has no prefix length, then this is equivalent to Iterator.

func (WrappedAddressSection) PrefixContains 

func (section WrappedAddressSection) PrefixContains(other AddressSectionType) (res bool)

PrefixContains returns whether the prefix values in the given address section are prefix values in this address section, using the prefix length of this section. If this address section has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

All prefix bits of this section must be present in the other section to be comparable.

func (WrappedAddressSection) PrefixEqual 

func (section WrappedAddressSection) PrefixEqual(other AddressSectionType) (res bool)

PrefixEqual determines if the given section matches this section up to the prefix length of this section. It returns whether the argument section has the same address section prefix values as this.

All prefix bits of this section must be present in the other section to be comparable, otherwise false is returned.

func (WrappedAddressSection) PrefixIterator 

func (section WrappedAddressSection) PrefixIterator() Iterator[ExtendedSegmentSeries]

PrefixIterator provides an iterator to iterate through the individual prefixes of this series, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this series.

If the series has no prefix length, then this is equivalent to Iterator.

func (WrappedAddressSection) ReverseBits 

func (section WrappedAddressSection) ReverseBits(perByte bool) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBits returns a new segment series with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (WrappedAddressSection) ReverseBytes 

func (section WrappedAddressSection) ReverseBytes() (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBytes returns a new segment series with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (WrappedAddressSection) ReverseSegments 

func (section WrappedAddressSection) ReverseSegments() ExtendedSegmentSeries

ReverseSegments returns a new series with the segments reversed.

func (WrappedAddressSection) SetPrefixLen 

func (section WrappedAddressSection) SetPrefixLen(prefixLen BitCount) ExtendedSegmentSeries

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

func (WrappedAddressSection) SetPrefixLenZeroed 

func (section WrappedAddressSection) SetPrefixLenZeroed(prefixLen BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedAddressSection) TestBit 

func (section WrappedAddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (WrappedAddressSection) ToBlock 

func (section WrappedAddressSection) ToBlock(segmentIndex int, lower, upper SegInt) ExtendedSegmentSeries

ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (WrappedAddressSection) ToIP 

func (section WrappedAddressSection) ToIP() IPAddressSegmentSeries

ToIP converts to an IP address section if this originated as IPv4 or IPv6, or an implicitly zero-valued IP. If not, ToIP returns nil.

func (WrappedAddressSection) ToIPv4 

func (section WrappedAddressSection) ToIPv4() IPv4AddressSegmentSeries

ToIPv4 converts to an IPv4AddressSegmentSeries if this series originated as an IPv4 series. If not, ToIPv4 returns nil.

ToIPv4 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddressSection) ToIPv6 

func (section WrappedAddressSection) ToIPv6() IPv6AddressSegmentSeries

ToIPv6 converts to an IPv4AddressSegmentSeries if this series originated as an IPv6 series. If not, ToIPv6 returns nil.

ToIPv6 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddressSection) ToMAC 

func (section WrappedAddressSection) ToMAC() MACAddressSegmentSeries

ToMAC converts to a MACAddressSegmentSeries if this series originated as a MAC series. If not, ToMAC returns nil.

ToMAC implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddressSection) ToPrefixBlock 

func (section WrappedAddressSection) ToPrefixBlock() ExtendedSegmentSeries

ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values. The series will be the block of all series with the same prefix.

If this series has no prefix, this series is returned.

func (WrappedAddressSection) ToPrefixBlockLen added in v1.2.0 

func (section WrappedAddressSection) ToPrefixBlockLen(prefLen BitCount) ExtendedSegmentSeries

ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values. The returned series will be the block of all series with the same prefix.

func (WrappedAddressSection) Unwrap 

func (section WrappedAddressSection) Unwrap() AddressSegmentSeries

Unwrap returns the wrapped address section as an interface, AddressSegmentSeries.

func (WrappedAddressSection) UpperBytes 

func (section WrappedAddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice.

func (WrappedAddressSection) WithoutPrefixLen 

func (section WrappedAddressSection) WithoutPrefixLen() ExtendedSegmentSeries

WithoutPrefixLen provides the same address series but with no prefix length. The values remain unchanged.

type WrappedHostName 

type WrappedHostName struct {
	*HostName
}

WrappedHostName wraps a HostName to get an ExtendedIdentifierString.

func (WrappedHostName) GetAddress 

func (host WrappedHostName) GetAddress() AddressType

GetAddress returns the identified address or nil if none.

func (WrappedHostName) ToAddress 

func (host WrappedHostName) ToAddress() (AddressType, error)

ToAddress returns the identified address or an error.

func (WrappedHostName) Unwrap 

func (host WrappedHostName) Unwrap() HostIdentifierString

Unwrap returns the wrapped HostName as an interface, HostIdentifierString.

type WrappedIPAddress 

type WrappedIPAddress struct {
	*IPAddress
}

WrappedIPAddress is the implementation of ExtendedIPSegmentSeries for IP addresses.

func (WrappedIPAddress) AdjustPrefixLen 

func (addr WrappedIPAddress) AdjustPrefixLen(prefixLen BitCount) ExtendedIPSegmentSeries

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (WrappedIPAddress) AdjustPrefixLenZeroed 

func (addr WrappedIPAddress) AdjustPrefixLenZeroed(prefixLen BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedIPAddress) AssignMinPrefixForBlock 

func (addr WrappedIPAddress) AssignMinPrefixForBlock() ExtendedIPSegmentSeries

AssignMinPrefixForBlock returns an equivalent series, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this series.

In other words, this method assigns a prefix length to this series matching the largest prefix block in this series.

func (WrappedIPAddress) AssignPrefixForSingleBlock 

func (addr WrappedIPAddress) AssignPrefixForSingleBlock() ExtendedIPSegmentSeries

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this series. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such series - it is required that the range of values match the range of a prefix block. If there is no such series, then nil is returned.

func (WrappedIPAddress) BlockIterator 

func (addr WrappedIPAddress) BlockIterator(segmentCount int) Iterator[ExtendedIPSegmentSeries]

BlockIterator Iterates through the series that can be obtained by iterating through all the upper segments up to the given segment count. The segments following remain the same in all iterated series.

func (WrappedIPAddress) Contains 

func (addr WrappedIPAddress) Contains(other ExtendedIPSegmentSeries) bool

Contains returns whether this is same type and version as the given address series and whether it contains all values in the given series.

Series must also have the same number of segments to be comparable, otherwise false is returned.

func (WrappedIPAddress) ContainsPrefixBlock 

func (addr WrappedIPAddress) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or subnet contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (WrappedIPAddress) ContainsSinglePrefixBlock 

func (addr WrappedIPAddress) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (WrappedIPAddress) CoverWithPrefixBlock 

func (addr WrappedIPAddress) CoverWithPrefixBlock() ExtendedIPSegmentSeries

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the addresses in this subnet. The resulting block will have a larger subnet size than this, unless this series is already a prefix block.

func (WrappedIPAddress) Equal 

func (addr WrappedIPAddress) Equal(other ExtendedIPSegmentSeries) bool

Equal returns whether the given address series is equal to this address series. Two address series are equal if they represent the same set of series. Both must be equal addresses.

func (WrappedIPAddress) GetBlockCount 

func (addr WrappedIPAddress) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (WrappedIPAddress) GetBlockMaskPrefixLen 

func (addr WrappedIPAddress) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address with all ones in the network section and then all zeros in the host section. A CIDR host mask is an address with all zeros in the network section and then all ones in the host section. The prefix length is the bit-length of the network section.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this instance, indicating the network and host section of this address. The prefix length returned here indicates the whether the value of this address can be used as a mask for the network and host section of any other address. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this address represents multiple values.

func (WrappedIPAddress) GetHostMask 

func (addr WrappedIPAddress) GetHostMask() ExtendedIPSegmentSeries

GetHostMask returns the host mask associated with the CIDR network prefix length of this address or subnet. If this series has no prefix length, then the all-ones mask is returned.

func (WrappedIPAddress) GetLower 

func (addr WrappedIPAddress) GetLower() ExtendedIPSegmentSeries

GetLower returns the series in the range with the lowest numeric value, which will be the same series if it represents a single value. For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned.

func (WrappedIPAddress) GetMinPrefixLenForBlock 

func (addr WrappedIPAddress) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

See AssignMinPrefixForBlock for some examples.

func (WrappedIPAddress) GetNetworkMask 

func (addr WrappedIPAddress) GetNetworkMask() ExtendedIPSegmentSeries

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address or subnet. If this series has no prefix length, then the all-ones mask is returned.

func (WrappedIPAddress) GetNetworkPrefixLen 

func (addr WrappedIPAddress) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. GetNetworkPrefixLen is equivalent to the method GetPrefixLen.

func (WrappedIPAddress) GetPrefixCount 

func (addr WrappedIPAddress) GetPrefixCount() *big.Int

GetPrefixCount returns the count of prefixes in this address or subnet.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the count of the range of values in the prefix.

If this has a nil prefix length, returns the same value as GetCount.

func (WrappedIPAddress) GetPrefixCountLen 

func (addr WrappedIPAddress) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the count of prefixes in this address or subnet for the given prefix length.

If not a subnet of multiple addresses, or a subnet with just single prefix of the given length, returns 1.

func (WrappedIPAddress) GetPrefixLen 

func (addr WrappedIPAddress) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part of the address that comprise the prefix.

A prefix is a part of the address that is not specific to that address but common amongst a group of addresses, such as a CIDR prefix block subnet.

For IP addresses, the prefix is explicitly defined when the address is created. For example, "1.2.0.0/16" has a prefix length of 16, while "1.2.*.*" has no prefix length, even though they both represent the same set of addresses and are considered equal. Prefixes can be considered variable for a given IP address and can depend on routing.

The methods GetMinPrefixLenForBlock and GetPrefixLenForSingleBlock can help you to obtain or define a prefix length if one does not exist already. The method ToPrefixBlockLen allows you to create the subnet consisting of the block of addresses for any given prefix length.

func (WrappedIPAddress) GetPrefixLenForSingleBlock 

func (addr WrappedIPAddress) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address subnet matches exactly the block of addresses for that prefix.

If the range can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix exists, returns nil.

If this segment grouping represents a single value, returns the bit length of this address division series.

IP address examples:

  • 1.2.3.4 returns 32
  • 1.2.3.4/16 returns 32
  • 1.2.*.* returns 16
  • 1.2.*.0/24 returns 16
  • 1.2.0.0/16 returns 16
  • 1.2.*.4 returns nil
  • 1.2.252-255.* returns 22

func (WrappedIPAddress) GetSection 

func (addr WrappedIPAddress) GetSection() *IPAddressSection

GetSection returns the backing section for this series, comprising all segments.

func (WrappedIPAddress) GetUpper 

func (addr WrappedIPAddress) GetUpper() ExtendedIPSegmentSeries

GetUpper returns the series in the range with the highest numeric value, which will be the same series if it represents a single value. For example, for the subnet "1.2-3.4.5-6", the address "1.3.4.6" is returned.

func (WrappedIPAddress) IncludesMaxHost 

func (addr WrappedIPAddress) IncludesMaxHost() bool

IncludesMaxHost returns whether the subnet contains an individual address with a host of all one-bits. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are one.

func (WrappedIPAddress) IncludesZeroHost 

func (addr WrappedIPAddress) IncludesZeroHost() bool

IncludesZeroHost returns whether the subnet contains an individual address with a host of zero. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are zero.

func (WrappedIPAddress) Increment 

func (addr WrappedIPAddress) Increment(i int64) ExtendedIPSegmentSeries

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (WrappedIPAddress) IncrementBoundary 

func (addr WrappedIPAddress) IncrementBoundary(i int64) ExtendedIPSegmentSeries

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (WrappedIPAddress) IsMaxHost 

func (addr WrappedIPAddress) IsMaxHost() bool

IsMaxHost returns whether this section has a prefix length and if so, whether the host section is always all one-bits, the max value, for all individual addresses in this subnet.

If the host section is zero length (there are zero host bits), IsMaxHost returns true.

func (WrappedIPAddress) IsPrefixBlock 

func (addr WrappedIPAddress) IsPrefixBlock() bool

IsPrefixBlock returns whether the address has a prefix length and the address range includes the block of values for that prefix length. If the prefix length matches the bit count, this returns true.

To create a prefix block from any address, use ToPrefixBlock.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (WrappedIPAddress) IsSingleNetwork 

func (addr WrappedIPAddress) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address.

func (WrappedIPAddress) IsSinglePrefixBlock 

func (addr WrappedIPAddress) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the address range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

For instance, "1.*.*.* /16" returns false from this method and returns true from IsPrefixBlock.

func (WrappedIPAddress) IsZeroHost 

func (addr WrappedIPAddress) IsZeroHost() bool

IsZeroHost returns whether this subnet has a prefix length and if so, whether the host section is always zero for all individual addresses in this subnet.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (WrappedIPAddress) Iterator 

func (addr WrappedIPAddress) Iterator() Iterator[ExtendedIPSegmentSeries]

Iterator provides an iterator to iterate through the individual series of this series.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual series.

Call IsMultiple to determine if this instance represents multiple series, or GetCount for the count.

func (WrappedIPAddress) PrefixBlockIterator 

func (addr WrappedIPAddress) PrefixBlockIterator() Iterator[ExtendedIPSegmentSeries]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this series. Each iterated series will be a prefix block with the same prefix length as this series.

If this series has no prefix length, then this is equivalent to Iterator.

func (WrappedIPAddress) PrefixIterator 

func (addr WrappedIPAddress) PrefixIterator() Iterator[ExtendedIPSegmentSeries]

PrefixIterator provides an iterator to iterate through the individual prefixes of this series, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this series.

If the series has no prefix length, then this is equivalent to Iterator.

func (WrappedIPAddress) ReverseBits 

func (addr WrappedIPAddress) ReverseBits(perByte bool) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBits returns a new segment series with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (WrappedIPAddress) ReverseBytes 

func (addr WrappedIPAddress) ReverseBytes() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBytes returns a new segment series with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (WrappedIPAddress) ReverseSegments 

func (addr WrappedIPAddress) ReverseSegments() ExtendedIPSegmentSeries

ReverseSegments returns a new series with the segments reversed.

func (WrappedIPAddress) SequentialBlockIterator 

func (addr WrappedIPAddress) SequentialBlockIterator() Iterator[ExtendedIPSegmentSeries]

SequentialBlockIterator iterates through the sequential series that make up this series.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

Use GetSequentialBlockCount to get the number of iterated elements.

func (WrappedIPAddress) SetPrefixLen 

func (addr WrappedIPAddress) SetPrefixLen(prefixLen BitCount) ExtendedIPSegmentSeries

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

func (WrappedIPAddress) SetPrefixLenZeroed 

func (addr WrappedIPAddress) SetPrefixLenZeroed(prefixLen BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedIPAddress) SpanWithPrefixBlocks 

func (addr WrappedIPAddress) SpanWithPrefixBlocks() []ExtendedIPSegmentSeries

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual series as this subnet.

func (WrappedIPAddress) SpanWithSequentialBlocks 

func (addr WrappedIPAddress) SpanWithSequentialBlocks() []ExtendedIPSegmentSeries

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of individual addresses as this subnet.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

func (WrappedIPAddress) ToBlock 

func (addr WrappedIPAddress) ToBlock(segmentIndex int, lower, upper SegInt) ExtendedIPSegmentSeries

ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (WrappedIPAddress) ToIPv4 

func (addr WrappedIPAddress) ToIPv4() IPv4AddressSegmentSeries

ToIPv4 converts to an IPv4AddressSegmentSeries if this address originated as an IPv4 section. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedIPAddress) ToIPv6 

func (addr WrappedIPAddress) ToIPv6() IPv6AddressSegmentSeries

ToIPv6 converts to an IPv6AddressSegmentSeries if this address originated as an IPv6 section. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedIPAddress) ToMaxHost 

func (addr WrappedIPAddress) ToMaxHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToMaxHost converts the subnet to one in which all individual addresses have a host of all one-bits, the max value, the host being the bits following the prefix length. If the subnet has no prefix length, then it returns an all-ones address, the max address.

The returned series will have the same prefix length.

For instance, the max host of "1.2.3.4/16" gives the broadcast address "1.2.255.255/16".

This returns an error if the series is a range which cannot be converted to a range in which all individual elements have max hosts, because the conversion results in a series segment that is not a sequential range of values.

func (WrappedIPAddress) ToMaxHostLen 

func (addr WrappedIPAddress) ToMaxHostLen(bitCount BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the resulting one will too, otherwise the resulting series will have no prefix length.

For instance, the zero host of "1.2.3.4" for the prefix length of 16 is the address "1.2.255.255".

This returns an error if the address or subnet is a range which cannot be converted to a range in which all individual addresses have max hosts, because the conversion results in a series segment that is not a sequential range of values.

func (WrappedIPAddress) ToPrefixBlock 

func (addr WrappedIPAddress) ToPrefixBlock() ExtendedIPSegmentSeries

ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values. The series will be the block of all series with the same prefix.

If this series has no prefix, this series is returned.

func (WrappedIPAddress) ToPrefixBlockLen 

func (addr WrappedIPAddress) ToPrefixBlockLen(bitCount BitCount) ExtendedIPSegmentSeries

ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values. The returned series will be the block of all series with the same prefix.

func (WrappedIPAddress) ToZeroHost 

func (addr WrappedIPAddress) ToZeroHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToZeroHost converts the subnet to one in which all individual addresses have a host of zero, the host being the bits following the prefix length. If the subnet has no prefix length, then it returns an all-zero series.

The returned series will have the same prefix length.

For instance, the zero host of "1.2.3.4/16" is the individual address "1.2.0.0/16".

This returns an error if the series is a range which cannot be converted to a range in which all individual elements have zero hosts, because the conversion results in a series segment that is not a sequential range of values.

func (WrappedIPAddress) ToZeroHostLen 

func (addr WrappedIPAddress) ToZeroHostLen(bitCount BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the subnet to one in which all individual addresses have a host of zero, the host being the bits following the given prefix length. If this address has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.

This returns an error if the subnet is a range which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (WrappedIPAddress) ToZeroNetwork 

func (addr WrappedIPAddress) ToZeroNetwork() ExtendedIPSegmentSeries

ToZeroNetwork converts the address or subnet to one in which all individual addresses have a network of zero, the network being the bits within the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix length.

func (WrappedIPAddress) Unwrap 

func (addr WrappedIPAddress) Unwrap() IPAddressSegmentSeries

Unwrap returns the wrapped address as an interface, IPAddressSegmentSeries.

func (WrappedIPAddress) WithoutPrefixLen 

func (addr WrappedIPAddress) WithoutPrefixLen() ExtendedIPSegmentSeries

WithoutPrefixLen provides the same address series but with no prefix length. The values remain unchanged.

type WrappedIPAddressSection 

type WrappedIPAddressSection struct {
	*IPAddressSection
}

WrappedIPAddressSection is the implementation of ExtendedIPSegmentSeries for IP address sections.

func (WrappedIPAddressSection) AdjustPrefixLen 

func (section WrappedIPAddressSection) AdjustPrefixLen(prefixLen BitCount) ExtendedIPSegmentSeries

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (WrappedIPAddressSection) AdjustPrefixLenZeroed 

func (section WrappedIPAddressSection) AdjustPrefixLenZeroed(prefixLen BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedIPAddressSection) AssignMinPrefixForBlock 

func (section WrappedIPAddressSection) AssignMinPrefixForBlock() ExtendedIPSegmentSeries

AssignMinPrefixForBlock returns an equivalent series, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this series.

In other words, this method assigns a prefix length to this series matching the largest prefix block in this series.

func (WrappedIPAddressSection) AssignPrefixForSingleBlock 

func (section WrappedIPAddressSection) AssignPrefixForSingleBlock() ExtendedIPSegmentSeries

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this series. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such series - it is required that the range of values match the range of a prefix block. If there is no such series, then nil is returned.

func (WrappedIPAddressSection) BlockIterator 

func (section WrappedIPAddressSection) BlockIterator(segmentCount int) Iterator[ExtendedIPSegmentSeries]

BlockIterator Iterates through the series that can be obtained by iterating through all the upper segments up to the given segment count. The segments following remain the same in all iterated series.

func (WrappedIPAddressSection) Bytes 

func (section WrappedIPAddressSection) Bytes() []byte

Bytes returns the lowest individual address section in this address section as a byte slice.

func (WrappedIPAddressSection) Contains 

func (section WrappedIPAddressSection) Contains(other ExtendedIPSegmentSeries) bool

Contains returns whether this is same type and version as the given address series and whether it contains all values in the given series.

Series must also have the same number of segments to be comparable, otherwise false is returned.

func (WrappedIPAddressSection) ContainsPrefixBlock 

func (section WrappedIPAddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (WrappedIPAddressSection) ContainsSinglePrefixBlock 

func (section WrappedIPAddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this section contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (WrappedIPAddressSection) CopyBytes 

func (section WrappedIPAddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (WrappedIPAddressSection) CopyUpperBytes 

func (section WrappedIPAddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (WrappedIPAddressSection) CoverWithPrefixBlock 

func (section WrappedIPAddressSection) CoverWithPrefixBlock() ExtendedIPSegmentSeries

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the individual address sections in this section. The resulting block will have a larger count than this, unless this section is already a prefix block.

func (WrappedIPAddressSection) Equal 

func (section WrappedIPAddressSection) Equal(other ExtendedIPSegmentSeries) bool

Equal returns whether the given address series is equal to this address series. Two address series are equal if they represent the same set of series. Both must be equal sections.

func (WrappedIPAddressSection) ForEachSegment added in v1.2.0 

func (section WrappedIPAddressSection) ForEachSegment(consumer func(segmentIndex int, segment *IPAddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (WrappedIPAddressSection) GetBitCount 

func (section WrappedIPAddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item.

func (WrappedIPAddressSection) GetBitsPerSegment 

func (section WrappedIPAddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (WrappedIPAddressSection) GetBlockMaskPrefixLen 

func (section WrappedIPAddressSection) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address section is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address section with all ones in the network section and then all zeros in the host section. A CIDR host mask is an address section with all zeros in the network section and then all ones in the host section. The prefix length is the bit-length of the network section.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this instance, indicating the network and host section of this address section. The prefix length returned here indicates the whether the value of this address can be used as a mask for the network and host section of any other address. Therefore the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this section represents multiple values.

func (WrappedIPAddressSection) GetByteCount 

func (section WrappedIPAddressSection) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item.

func (WrappedIPAddressSection) GetBytesPerSegment 

func (section WrappedIPAddressSection) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this section. Segments in the same address section are equal length.

func (WrappedIPAddressSection) GetGenericSegment 

func (section WrappedIPAddressSection) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType. The first segment is at index 0. GetGenericSegment will panic given a negative index or an index matching or larger than the segment count.

func (WrappedIPAddressSection) GetHostMask 

func (section WrappedIPAddressSection) GetHostMask() ExtendedIPSegmentSeries

GetHostMask returns the host mask associated with the CIDR network prefix length of this address section. If this series has no prefix length, then the all-ones mask is returned.

func (WrappedIPAddressSection) GetIPVersion 

func (section WrappedIPAddressSection) GetIPVersion() IPVersion

GetIPVersion returns the IP version of this IP address section.

func (WrappedIPAddressSection) GetLower 

func (section WrappedIPAddressSection) GetLower() ExtendedIPSegmentSeries

GetLower returns the series in the range with the lowest numeric value, which will be the same series if it represents a single value. For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned.

func (WrappedIPAddressSection) GetMaxSegmentValue 

func (section WrappedIPAddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (WrappedIPAddressSection) GetMinPrefixLenForBlock 

func (section WrappedIPAddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (WrappedIPAddressSection) GetNetworkMask 

func (section WrappedIPAddressSection) GetNetworkMask() ExtendedIPSegmentSeries

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address section. If this series has no prefix length, then the all-ones mask is returned.

func (WrappedIPAddressSection) GetNetworkPrefixLen 

func (section WrappedIPAddressSection) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. It is equivalent to GetPrefixLen.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (WrappedIPAddressSection) GetPrefixLenForSingleBlock 

func (section WrappedIPAddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (WrappedIPAddressSection) GetSection 

func (section WrappedIPAddressSection) GetSection() *IPAddressSection

GetSection returns the backing section for this series, comprising all segments.

func (WrappedIPAddressSection) GetSegment 

func (section WrappedIPAddressSection) GetSegment(index int) *IPAddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or an index matching or larger than the segment count.

func (WrappedIPAddressSection) GetSegmentCount 

func (section WrappedIPAddressSection) GetSegmentCount() int

GetSegmentCount returns the segment/division count.

func (WrappedIPAddressSection) GetSequentialBlockCount 

func (section WrappedIPAddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section.

func (WrappedIPAddressSection) GetSequentialBlockIndex 

func (section WrappedIPAddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (WrappedIPAddressSection) GetUpper 

func (section WrappedIPAddressSection) GetUpper() ExtendedIPSegmentSeries

GetUpper returns the series in the range with the highest numeric value, which will be the same series if it represents a single value. For example, for the subnet "1.2-3.4.5-6", the address "1.3.4.6" is returned.

func (WrappedIPAddressSection) GetUpperValue 

func (section WrappedIPAddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value.

func (WrappedIPAddressSection) GetValue 

func (section WrappedIPAddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value.

func (WrappedIPAddressSection) IncludesMax 

func (section WrappedIPAddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range.

func (WrappedIPAddressSection) IncludesMaxHost 

func (section WrappedIPAddressSection) IncludesMaxHost() bool

IncludesMaxHost returns whether the address section contains an individual address section with a host of all one-bits. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are one.

func (WrappedIPAddressSection) IncludesMaxHostLen 

func (section WrappedIPAddressSection) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the address section contains an individual address section with a host of all one-bits, an address section for which all bits past the given prefix length are all ones.

func (WrappedIPAddressSection) IncludesZero 

func (section WrappedIPAddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range.

func (WrappedIPAddressSection) IncludesZeroHost 

func (section WrappedIPAddressSection) IncludesZeroHost() bool

IncludesZeroHost returns whether the address section contains an individual address section with a host of zero. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are zero.

func (WrappedIPAddressSection) IncludesZeroHostLen 

func (section WrappedIPAddressSection) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the address section contains an individual section with a host of zero, a section for which all bits past the given prefix length are zero.

func (WrappedIPAddressSection) Increment 

func (section WrappedIPAddressSection) Increment(i int64) ExtendedIPSegmentSeries

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (WrappedIPAddressSection) IncrementBoundary 

func (section WrappedIPAddressSection) IncrementBoundary(i int64) ExtendedIPSegmentSeries

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (WrappedIPAddressSection) IsFullRange 

func (section WrappedIPAddressSection) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (WrappedIPAddressSection) IsMax 

func (section WrappedIPAddressSection) IsMax() bool

IsMax returns whether this section matches exactly the maximum possible value, the value whose bits are all ones.

func (WrappedIPAddressSection) IsMaxHost 

func (section WrappedIPAddressSection) IsMaxHost() bool

IsMaxHost returns whether this section has a prefix length and if so, whether the host is all all one-bits, the max value, for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsMaxHost returns true.

func (WrappedIPAddressSection) IsMaxHostLen 

func (section WrappedIPAddressSection) IsMaxHostLen(prefLen BitCount) bool

IsMaxHostLen returns whether the host host is all one-bits, the max value, for all individual sections in this address section, for the given prefix length, the host being the bits following the prefix.

If the host section is zero length (there are zero host bits), IsMaxHostLen returns true.

func (WrappedIPAddressSection) IsOneBit 

func (section WrappedIPAddressSection) IsOneBit(prefixBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex is less than zero, or if it is larger than the bit count of this item.

func (WrappedIPAddressSection) IsPrefixBlock 

func (section WrappedIPAddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length, or a prefix length that differs from a prefix length for which ContainsPrefixBlock returns true.

func (WrappedIPAddressSection) IsSequential 

func (section WrappedIPAddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (WrappedIPAddressSection) IsSingleNetwork 

func (section WrappedIPAddressSection) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address section.

func (WrappedIPAddressSection) IsSinglePrefixBlock 

func (section WrappedIPAddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (WrappedIPAddressSection) IsZero 

func (section WrappedIPAddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero.

func (WrappedIPAddressSection) IsZeroHost 

func (section WrappedIPAddressSection) IsZeroHost() bool

IsZeroHost returns whether this section has a prefix length and if so, whether the host section is always zero for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (WrappedIPAddressSection) IsZeroHostLen 

func (section WrappedIPAddressSection) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual sections in this address section, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (WrappedIPAddressSection) Iterator 

func (section WrappedIPAddressSection) Iterator() Iterator[ExtendedIPSegmentSeries]

Iterator provides an iterator to iterate through the individual series of this series.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual series.

Call IsMultiple to determine if this instance represents multiple series, or GetCount for the count.

func (WrappedIPAddressSection) PrefixBlockIterator 

func (section WrappedIPAddressSection) PrefixBlockIterator() Iterator[ExtendedIPSegmentSeries]

PrefixBlockIterator provides an iterator to iterate through the individual prefix blocks, one for each prefix of this series. Each iterated series will be a prefix block with the same prefix length as this series.

If this series has no prefix length, then this is equivalent to Iterator.

func (WrappedIPAddressSection) PrefixContains 

func (section WrappedIPAddressSection) PrefixContains(other AddressSectionType) bool

PrefixContains returns whether the prefix values in the given address section are prefix values in this address section, using the prefix length of this section. If this address section has no prefix length, the entire address is compared.

It returns whether the prefix of this address contains all values of the same prefix length in the given address.

All prefix bits of this section must be present in the other section to be comparable.

func (WrappedIPAddressSection) PrefixEqual 

func (section WrappedIPAddressSection) PrefixEqual(other AddressSectionType) bool

PrefixEqual determines if the given section matches this section up to the prefix length of this section. It returns whether the argument section has the same address section prefix values as this.

All prefix bits of this section must be present in the other section to be comparable, otherwise false is returned.

func (WrappedIPAddressSection) PrefixIterator 

func (section WrappedIPAddressSection) PrefixIterator() Iterator[ExtendedIPSegmentSeries]

PrefixIterator provides an iterator to iterate through the individual prefixes of this series, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this series.

If the series has no prefix length, then this is equivalent to Iterator.

func (WrappedIPAddressSection) ReverseBits 

func (section WrappedIPAddressSection) ReverseBits(perByte bool) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBits returns a new segment series with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (WrappedIPAddressSection) ReverseBytes 

func (section WrappedIPAddressSection) ReverseBytes() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBytes returns a new segment series with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (WrappedIPAddressSection) ReverseSegments 

func (section WrappedIPAddressSection) ReverseSegments() ExtendedIPSegmentSeries

ReverseSegments returns a new series with the segments reversed.

func (WrappedIPAddressSection) SequentialBlockIterator 

func (section WrappedIPAddressSection) SequentialBlockIterator() Iterator[ExtendedIPSegmentSeries]

SequentialBlockIterator iterates through the sequential series that make up this series.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

Use GetSequentialBlockCount to get the number of iterated elements.

func (WrappedIPAddressSection) SetPrefixLen 

func (section WrappedIPAddressSection) SetPrefixLen(prefixLen BitCount) ExtendedIPSegmentSeries

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

func (WrappedIPAddressSection) SetPrefixLenZeroed 

func (section WrappedIPAddressSection) SetPrefixLenZeroed(prefixLen BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedIPAddressSection) SpanWithPrefixBlocks 

func (section WrappedIPAddressSection) SpanWithPrefixBlocks() []ExtendedIPSegmentSeries

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual series as this subnet section.

func (WrappedIPAddressSection) SpanWithSequentialBlocks 

func (section WrappedIPAddressSection) SpanWithSequentialBlocks() []ExtendedIPSegmentSeries

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of individual address sections as this series.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

func (WrappedIPAddressSection) TestBit 

func (section WrappedIPAddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (WrappedIPAddressSection) ToBlock 

func (section WrappedIPAddressSection) ToBlock(segmentIndex int, lower, upper SegInt) ExtendedIPSegmentSeries

ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (WrappedIPAddressSection) ToIPv4 

func (section WrappedIPAddressSection) ToIPv4() IPv4AddressSegmentSeries

ToIPv4 converts to an IPv4AddressSegmentSeries if this section originated as an IPv4 section. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedIPAddressSection) ToIPv6 

func (section WrappedIPAddressSection) ToIPv6() IPv6AddressSegmentSeries

ToIPv6 converts to an IPv6AddressSegmentSeries if this section originated as an IPv6 section. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedIPAddressSection) ToMaxHost 

func (section WrappedIPAddressSection) ToMaxHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToMaxHost converts the address section to one in which all individual address sections have a host of all one-bits, the max value, the host being the bits following the prefix length. If the section has no prefix length, then it returns an all-ones section, the max address section.

The returned series will have the same prefix length.

This returns an error if the series is a range which cannot be converted to a range in which all individual elements have max hosts, because the conversion results in a series segment that is not a sequential range of values.

func (WrappedIPAddressSection) ToMaxHostLen 

func (section WrappedIPAddressSection) ToMaxHostLen(bitCount BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address section to one in which all individual address sections have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this address section has the same prefix length, then the resulting series will too, otherwise the resulting series will have no prefix length.

This returns an error if the address section is a range which cannot be converted to a range in which all individual address sections have max hosts, because the conversion results in a series segment that is not a sequential range of values.

func (WrappedIPAddressSection) ToPrefixBlock 

func (section WrappedIPAddressSection) ToPrefixBlock() ExtendedIPSegmentSeries

ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values. The series will be the block of all series with the same prefix.

If this series has no prefix, this series is returned.

func (WrappedIPAddressSection) ToPrefixBlockLen 

func (section WrappedIPAddressSection) ToPrefixBlockLen(bitCount BitCount) ExtendedIPSegmentSeries

ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values. The returned series will be the block of all series with the same prefix.

func (WrappedIPAddressSection) ToZeroHost 

func (section WrappedIPAddressSection) ToZeroHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToZeroHost converts the section to one in which all individual sections have a host of zero, the host being the bits following the prefix length. If the section has no prefix length, then it returns an all-zero section.

The returned series will have the same prefix length.

This returns an error if the section is a range which cannot be converted to a range in which all individual elements have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (WrappedIPAddressSection) ToZeroHostLen 

func (section WrappedIPAddressSection) ToZeroHostLen(bitCount BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the section to one in which all individual sections have a host of zero, the host being the bits following the given prefix length. If this section has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.

This returns an error if the section is a range which cannot be converted to a range in which all individual sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (WrappedIPAddressSection) ToZeroNetwork 

func (section WrappedIPAddressSection) ToZeroNetwork() ExtendedIPSegmentSeries

ToZeroNetwork converts the address section to one in which all individual address sections have a network of zero, the network being the bits within the prefix length. If the section has no prefix length, then it returns an all-zero series.

The returned address section will have the same prefix length.

func (WrappedIPAddressSection) Unwrap 

func (section WrappedIPAddressSection) Unwrap() IPAddressSegmentSeries

Unwrap returns the wrapped address section as an interface, IPAddressSegmentSeries.

func (WrappedIPAddressSection) UpperBytes 

func (section WrappedIPAddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice.

func (WrappedIPAddressSection) WithoutPrefixLen 

func (section WrappedIPAddressSection) WithoutPrefixLen() ExtendedIPSegmentSeries

WithoutPrefixLen provides the same address series but with no prefix length. The values remain unchanged.

func (WrappedIPAddressSection) Wrap 

func (section WrappedIPAddressSection) Wrap() WrappedIPAddressSection

Wrap wraps this IP address section, returning a WrappedIPAddressSection, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address section.

func (WrappedIPAddressSection) WrapSection added in v1.2.0 

func (section WrappedIPAddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapSection can be called with a nil receiver, wrapping a nil address section.

type WrappedIPAddressString 

type WrappedIPAddressString struct {
	*IPAddressString
}

WrappedIPAddressString wraps an IPAddressString to get an ExtendedIdentifierString, an extended polymorphic type.

func (WrappedIPAddressString) GetAddress 

func (str WrappedIPAddressString) GetAddress() AddressType

GetAddress returns the identified address or nil if none.

func (WrappedIPAddressString) ToAddress 

func (str WrappedIPAddressString) ToAddress() (AddressType, error)

ToAddress returns the identified address or an error.

func (WrappedIPAddressString) Unwrap 

func (str WrappedIPAddressString) Unwrap() HostIdentifierString

Unwrap returns the wrapped IPAddressString as an interface, HostIdentifierString.

type WrappedMACAddressString 

type WrappedMACAddressString struct {
	*MACAddressString
}

WrappedMACAddressString wraps a MACAddressString to get an ExtendedIdentifierString.

func (WrappedMACAddressString) GetAddress 

func (str WrappedMACAddressString) GetAddress() AddressType

GetAddress returns the identified address or nil if none.

func (WrappedMACAddressString) ToAddress 

func (str WrappedMACAddressString) ToAddress() (AddressType, error)

ToAddress returns the identified address or an error.

func (WrappedMACAddressString) Unwrap 

func (str WrappedMACAddressString) Unwrap() HostIdentifierString

Unwrap returns the wrapped MACAddressString as an interface, HostIdentifierString.

type Zone 

type Zone string

Zone represents an IPv6 address zone or scope.

func ValidateZoneStr 

func ValidateZoneStr(zoneStr string) (zone Zone, err addrerr.AddressStringError)

ValidateZoneStr returns an error if the given zone is invalid

func (Zone) IsEmpty 

func (zone Zone) IsEmpty() bool

IsEmpty returns whether the zone is the zero-zone, which is the lack of a zone, or the empty string zone.

func (Zone) String 

func (zone Zone) String() string

String implements the fmt.Stringer interface, returning the zone characters as a string

Source Files

View all Source files

Directories

Path Synopsis
Package addrstr provides interfaces for specifying how to create specific strings from addresses and address sections, as well as builder types to construct instances of those interfaces.
 Package addrstr provides interfaces for specifying how to create specific strings from addresses and address sections, as well as builder types to construct instances of those interfaces.
cmd
test

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.