goip

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Dec 24, 2023 License: Apache-2.0 Imports: 21 Imported by: 0

README

goip Go Reference

Go package for handling IP addresses and subnets. IPv4 and IPv6.

Working with IP addresses and networks, CIDR, address and subnet operations, iterations, content checks, IP to CIDR block lookup, longest prefix match, creating subnets, spanning, merging, ranges and address tries, with polymorphic code

Usage

starting with address or subnet strings

import "github.com/pchchv/goip"

ipv6AddrStr := goip.NewIPAddressString("a:b:c:d::a:b/64")
if ipAddr, err := ipv6AddrStr.ToAddress(); err != nil {
	// error validation
} else {
	// use the address
}

...or checking for nil:

str := goip.NewIPAddressString("a:b:c:d:e-f:f:1.2-3.3.4/64")
addr := str.GetAddress()
if addr != nil {
	// use address
}

starting with host name:

hostStr := "[::1]"
host := goip.NewHostName(hostStr)
if err := host.Validate(); err != nil {
    panic(err)
}

// use host
if host.IsAddress() {
    fmt.Println("address: " + host.AsAddress().String())
} else {
    fmt.Println("host name: " + host.String())
}

Documentation

Overview

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

Benefits of this Library

The primary goals are: - Comprehensive parsing of IPv4 and IPv6 addresses along with commonly used host name formats, and supplementary formats. - Representation of subnets by network prefix length or segment value ranges. - Decoupling address parsing from host parsing. - Configurable parsing options for allowed formats, including IPv4, IPv6, subnet formats, inet_aton formats, among others. - Generation of diverse address strings in various formats for a given IPv4 or IPv6 address and creation of collections of such strings. - Parsing of prevalent MAC Address formats and generation of strings in various MAC address formats. - Integration of MAC addresses with IPv6 via standardized conversions. - Integration of IPv4 Addresses with IPv6 through commonly used address conversions. - Emphasis on polymorphism by maintaining an address framework of interfaces for addressing independence based on type or version (IPv4, IPv6, or MAC). This enables transparent support for both IPv4 and IPv6 in the codebase. - Thread-safety and immutability with core types (e.g., host names, address strings, addresses, address sections, segments, ranges) being immutable, facilitating safe sharing among goroutines. - Address manipulation capabilities such as prefix length alterations, masking, segmentation, network and host section separation, reconstitution from segments, among other operations. - Address operations and subnetting functionalities including obtaining prefix block subnets, iterating through subnets, prefixes, blocks, or segments of subnets, incrementing and decrementing addresses, reversing address bits, set operations like subtracting subnets, intersections, merging, containment checks, and listing subnets covering specific address spans. - Sorting and comparison of host names, addresses, address strings, and subnets with all address component types being comparable. - Integration with Go language primitive types and standard library types like 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. - Simplification of address manipulations by abstracting complexities involving numeric bytes, integers, signed/unsigned values, bit manipulations, iteration, and implementation intricacies related to IPv4/v6.

Design Overview

This library revolves around core types: - `IPAddressString` - `HostName` - `MACAddressString` These are complemented by the base type `Address` and its associated types: - `IPAddress` - `IPv4Address` - `IPv6Address` - `MACAddress` Moreover, it includes the sequential address type `SequentialRange`.

#### Choosing Types Based on Representation:

- For textual IP address representation, begin with `IPAddressString` or `HostName`. - For textual MAC address representation, start with `MACAddressString`. - Instances can represent either a single address or a subnet. Utilize `HostName` for addresses, host names, or items with a port or service name. - For numeric bytes or integers, initiate with `IPv4Address`, `IPv6Address`, `IPAddress`, or `MACAddress`.

### Scalability and Polymorphism

- Facilitates scaling down from specific address types to more generic types and vice versa. - Polymorphism aids in ambiguous IP-version code scenarios, with the most-specific types supporting tailored method sets for the address version or type. - Scaling up to a specific version or address type requires the lower-level instance to originate from an instance of that specific type. - Conversion examples: `IPv6Address` to `IPAddress` via `IPv6Address.ToIP`, or to `Address` via `IPv6Address.ToAddressBase`. Conversion back to `IPv6Address` or `IPAddress` using `Address.ToIP` or `Address.ToIPv6`. - Limitation: Conversion back to IPv4 from `IPv6Address` necessitates the use of `IPv4AddressConverter`.

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 (
	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 (
	NoZone                          = ""
	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 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, then count.
	HighValueComparator = AddressComparator{valueComparator{/* contains filtered or unexported fields */}}
	// LowValueComparator compares by low value first, then high, then count.
	LowValueComparator = AddressComparator{valueComparator{}}
	// With the reverse comparators, ordering with the secondary values (higher or lower) follow a reverse ordering than the primary values (lower or higher)
	// 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}
	IPv6Network = &IPv6AddressNetwork{ipv6Network}
)
View Source 
var (
	IPv6LinkLocalPrefix = createLinkLocalPrefix()
)

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 

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 

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 

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 

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 

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 

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

AddedTreeNode represents a node in an AddedTree.

func (AddedTreeNode[T]) GetKey 

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 

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 

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 

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 

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 set of multiple addresses, such as with an IP subnet or a set of MAC addresses.

Addresses consist of a sequence of segments, each with the same bit-size. The number of such segments and the bit-size are determined by the underlying version or type of 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 - the number of consecutive bits that make up the prefix, the most significant bits of the address.

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

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

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

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

A zero value for an Address is an address with no segments and no associated version or type of address, also known as 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, address_error.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 

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 that make up a given 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 a given 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 

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 number of prefixes in a given address or subnet. The prefix length is given by GetPrefixLen. If the prefix length is not nil, a count of the range of values in the prefix is returned. If the prefix length is nil, the same value is returned as in GetCount.

func (*Address) GetPrefixCountLen 

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

GetPrefixCountLen returns the number of prefixes in the given address or subnet for the given prefix length. If it is not a subnet with multiple addresses or a subnet with a single prefix of the given prefix length, 1 is returned.

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 (high significant bits) of the address that make up 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 specified when the address is created. For example, "1.2.0.0/16" has a prefix length of 16, and "1.2.*.*" has no prefix length, although both represent the same set of addresses and are considered the same. Prefixes may be considered variable for a given IP address and may depend on routing.

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

For MAC addresses, the prefix is initially derived from a range, so "1:2:3:*:*:*" has a prefix length of 24. MAC addresses derived from an address with a prefix length can 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 

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 given address or subnet represents a range of addresses that are sequential.

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

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

Given any subnet of IP addresses, you can use the SequentialBlockIterator to convert any subnet into a set 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, address_error.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, address_error.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, address_error.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, address_error.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 address_string.StringOptions) string

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

func (*Address) ToGenericKey 

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, address_error.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 

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 

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, address_error.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 

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 

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 

func (addr *Address) TrieCompare(other *Address) (int, address_error.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 

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 

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 for comparing addresses, or sections, or series of divisions, or segments, or divisions, or consecutive ranges. The AddressComparator also allows any two instances of any such address items to be compared using the Compare method. A zero value acts as 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 lowest value of the address component by the given index is 1,
	// where index 0 refers to the lowest significant bit. In other words, it calculates (bits & (1 << n) != 0),
	// using the lowest value of this address component. TestBit panics if n < 0,
	// or if it matches or exceeds the number of bits of this address component.
	TestBit(index BitCount) bool
	// IsOneBit returns true if the bit in the lowest value of this address component by the given index is 1, where index 0 refers to the highest bit.
	// IsOneBit causes a panic if bitIndex is less than zero, or if it is greater than the number of bits of this address component.
	IsOneBit(index BitCount) bool
	// ToHexString writes this address component as a single hex value
	// (possibly two values if the range is not a prefix block),
	// the number of digits according to the number of bits,
	// with or without the preceding "0x" prefix.
	// If a multi-digit component cannot be written as a single prefix block or
	// a range of two values, an error is returned.
	ToHexString(with0xPrefix bool) (string, address_error.IncompatibleAddressError)
	// ToNormalizedString creates 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 grouping of address divisions. It can contain a single value or a range of sequential values and has an assigned bit length. Like all address components, it is immutable. Divisions that have been converted from IPv4, IPv6, or MAC segments can be converted back to segments of the same type and version. Divisions that have not been 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 

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 a count of possible distinct values for this division. If no multiple values are represented, the counter is 1. For instance, a division with a value range of 3-7 has a count 5. Use IsMultiple if you just want to know if the counter 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 a 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 occurred as an IPv4 or IPv6 segment, or an implicitly zero-valued IP segment. If so, use ToIP to convert back to 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 IPv4-specific type.

func (*AddressDivision) IsIPv6 

func (div *AddressDivision) IsIPv6() bool

IsIPv6 returns true if this division occurred as an IPv6 segment. If so, use ToIPv6 to convert back to 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 the given division represents a sequential range of values rather than 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 covers only single prefix value for a 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 a mask to a this division and then compares the result to 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, which allows this method to be used in a chain with methods that can 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 containing a consistent 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 limit on the size of the divisions in AddressDivisionGrouping.

AddressDivisionGrouping objects are similar to address sections and addresses, except that groupings can have divisions of different bit-lengths, including divisions that are not the exact number of bytes, whereas all segments in an address or address section must have the same bit size and 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 a block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether this item contains multiple prefix values for a given prefix length is irrelevant.

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 into the given slice, it is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice with the value is created and returned.

To determine the required length of the byte array, it is possible to use the GetByteCount.

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 grouping value with the highest division in the range into the byte slice.

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

To determine the required length of the byte array, it is possible to use the GetByteCount.

func (*AddressDivisionGrouping) ForEachDivision 

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

ForEachDivision visits each segment in order from most significant to least, most significant with index 0, calling the given function for each and 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 the given grouping includes a block of all values for that prefix length.

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

For the returned prefix length, there can be either a single prefix or multiple possible prefix values in this block. To avoid the case of multiple prefix values, use the GetPrefixLenForSingleBlock.

If this grouping represents a single value, a bit count is returned.

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 the given address division series has a prefix length and whether it includes the block associated with its prefix length. If the prefix length matches the bit count, true is returned.

This method differs from the ContainsPrefixBlock method in that it returns false if the series has no prefix length or the prefix length is different from the prefix length for which the ContainsPrefixBlock method returns true. Note that for any given prefix length, you can perform a comparison with GetMinPrefixLenForBlock.

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. Note for any given prefix length you can compare with GetPrefixLenForSingleBlock.

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 the given grouping originated as an address section. Otherwise, the result is nil.

ToSectionBase can be called with a nil receiver, allowing this method to be used in a chain with methods that may 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() int                    // returns the number of divisions
	GetPrefixCount() *big.Int                 // returns the count of prefixes in this series for its prefix length, or the total count if it has no prefix length
	GetBlockCount(divisionCount int) *big.Int // returns the count of distinct values in the given number of initial (more significant) segments
	// GetSequentialBlockCount provides a count of elements from the sequential block iterator,
	// the minimum number of sequential address division series that constitute a given division series.
	GetSequentialBlockCount() *big.Int
	// GetSequentialBlockIndex gets the minimum division index for which all subsequent divisions are full-range blocks.
	// A division by this index is not a full-range block if all divisions are not full-range.
	// A division by this index and all subsequent divisions form a consecutive row.
	// For a full range to be consecutive, the preceding divisions must be single-valued.
	GetSequentialBlockIndex() int
	// IsSequential returns whether the series represents a range of values that are consistent.
	// Generally, this means that any division spanning a range of values must be followed by divisions that are complete, covering all values.
	IsSequential() bool
	Prefixed
	// GetGenericDivision returns the division by the given index as DivisionType.
	// The first division is at index 0.
	// GetGenericDivision panics when the index is negative or an index greater than the number of divisions.
	// Useful for comparisons.
	GetGenericDivision(index int) DivisionType
}

AddressDivisionSeries serves as a common interface for all division groups, address sections and addresses.

type AddressItem 

type AddressItem interface {
	BitItem
	// GetValue returns the smallest individual address element in the range of address elements as an integer value.
	GetValue() *big.Int
	// GetUpperValue returns the topmost individual address element in the range of address elements as an integer value.
	GetUpperValue() *big.Int
	// CopyBytes copies the value of the smallest single address element in that address element range to a byte fragment.
	// If the value can fit in a given fragment,
	// the value is copied to that fragment and a length-adjusted subfragment is returned.
	// Otherwise a new fragment is created and returned with the value.
	CopyBytes(bytes []byte) []byte
	// CopyUpperBytes copies the value of the oldest single address element in that address element range to a byte fragment.
	// If the value can fit in a given fragment,
	// the value is copied to that fragment and a length-adjusted subfragment is returned.
	// Otherwise a new fragment is created and returned with the value.
	CopyUpperBytes(bytes []byte) []byte
	// Bytes returns the smallest single address element in the range of address elements as a byte fragment.
	Bytes() []byte
	// UpperBytes returns the topmost individual address element in the range of address elements as a byte slice.
	UpperBytes() []byte
	// GetCount provides the number of address items represented by the AddressItem, such as subnet size for IP addresses.
	GetCount() *big.Int
	// IsMultiple returns whether the given element represents multiple values (a count greater than 1).
	IsMultiple() bool
	// IsFullRange returns whether the given address element represents
	// all possible values reachable by an address element of that type.
	// This is true if and only if both IncludesZero and IncludesMax return true.
	IsFullRange() bool
	// IncludesZero returns whether the item includes a value of zero in its range.
	IncludesZero() bool
	// IncludesMax returns whether the item includes the maximum value,
	// a value whose bits are all one, in its range.
	IncludesMax() bool
	// IsZero returns whether the given address element is exactly zero.
	IsZero() bool
	// IsMax returns whether the given address element corresponds exactly to the maximum possible value - a value whose bits are all one.
	IsMax() bool
	// ContainsPrefixBlock returns whether the values of a given element contain a prefix block for a given prefix length.
	// Unlike ContainsSinglePrefixBlock, the presence of multiple prefix values for a given prefix length is irrelevant.
	ContainsPrefixBlock(BitCount) bool
	// ContainsSinglePrefixBlock returns whether the values of this series contain a single prefix block for a given prefix length.
	// This means that this element has only one prefix of a given length,
	// and this element contains a prefix block for that prefix, all elements with the same prefix.
	ContainsSinglePrefixBlock(BitCount) bool
	// GetPrefixLenForSingleBlock returns the prefix length for which there is only one prefix of that length in the given element,
	// and the range of that element matches the block of all values for that prefix.
	// If the whole range can be described this way, this method returns the same value as GetMinPrefixLenForBlock.
	// If no such prefix length exists, it returns nil.
	// If this element represents a single value, the number of bits is returned.
	GetPrefixLenForSingleBlock() PrefixLen
	// GetMinPrefixLenForBlock returns the smallest possible prefix length such that this element includes a block of all values for that prefix length.
	// If the entire range can be defined in this way, this method returns the same value as GetPrefixLenForSingleBlock.
	// This item can have a single prefix or multiple possible prefix values for the returned prefix length.
	// Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values. If this element represents a single value, the number of bits is returned.
	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 the given address element is less than,
	// equal to, or greater than the given element.
	// Any address element is comparable to any other address element.
	// All address elements use CountComparator for comparison.
	Compare(AddressItem) int
	// CompareSize compares the number of two address elements, whether they are addresses in a subnet or address range,
	// whether they are individual sections in a collection of sections, whether they are individual segments in a segment range.
	// It compares the number of individual elements within each.
	// Instead of counting the number with GetCount,
	// it can use more efficient ways to determine whether one element represents more individual addresses than another.
	// CompareSize returns a positive integer if the given element has a larger count than the given one,
	// zero if they are the same, or a negative integer if the other element has a larger count.
	CompareSize(AddressItem) int
	fmt.Stringer
	fmt.Formatter
}

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

type AddressKey 

type AddressKey = Key[*Address]

type AddressSection 

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

AddressSection is an address section containing a certain number of consecutive segments. It is a series of individual address segments. Each segment has the same bit length. Each address is backed by an address section that contains all address segments.

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, address_error.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 

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 is intentionally the only method with non-pointer receivers. It is not intended to be called directly, it is intended for use by the fmt package. When called by a function in the fmt package, nil values are detected before this method is called, avoiding a panic when calling this method.

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 

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

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, address_error.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, address_error.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, address_error.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, address_error.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

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 address_string.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 AddressDivisionGrouping, a polymorphic type used with all address sections and divisional groupings. The conversion can then be reversed using ToSectionBase. ToDivGrouping can be called with a nil receiver, allowing this method to be used in a chain with methods that can return a nil pointer.

func (*AddressSection) ToHexString 

func (section *AddressSection) ToHexString(with0xPrefix bool) (string, address_error.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 

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, address_error.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. 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 the given address is the same type and version as the given address section,
	// and whether it contains all the 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 whether the given section matches this section to the prefix length of that section.
	// It returns whether the argument section has the same address section prefix values as this section.
	// The entire prefix of a given section must be present in the other section for comparison.
	PrefixEqual(AddressSectionType) bool
	// PrefixContains returns whether the prefix values in a given address section are prefix values in that address section using the prefix length of that section.
	// If this address section has no prefix length, the entire address is compared.
	// Returns whether the prefix of a given address contains all values of the same prefix length in that address.
	// All prefix bits of a given section must be present in the other section for comparison.
	PrefixContains(AddressSectionType) bool
	// ToSectionBase converts to AddressSection, a polymorphic type used with all address sections.
	// Implementations of ToSectionBase can be called with a nil receiver,
	// allowing this method to be used in a chain with methods that can return a nil pointer.
	ToSectionBase() *AddressSection
}

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

type AddressSegment 

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

AddressSegment represents a single address segment. A segment contains a single value or range of sequential values and has an assigned bit length. Segments are 1 byte for Ipv4, two bytes for Ipv6, and 1 byte for MAC addresses.

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

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

When alternate forms do not follow the general rules for segments, AddressDivision can be used instead. The restriction that address divisions have the same length and an integer number of bytes does not apply to divisions. Divisions can be grouped using AddressDivisionGrouping.

AddressSegment objects are immutable and therefore 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 

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 the given segment is the same type and version as the given segment, and whether it contains all the values in the given segment.

func (*AddressSegment) ContainsPrefixBlock 

func (seg *AddressSegment) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the segment range includes a values block for a 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 to a byte slice. If the value can fit in a given slice, it is copied to that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned along with the value.

func (*AddressSegment) CopyUpperBytes 

func (seg *AddressSegment) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the highest value in the address segment range to a byte slice. If the value can fit in a given slice, it is copied to that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned along 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 that makes up the given address element.

func (*AddressSegment) GetCount 

func (seg *AddressSegment) GetCount() *big.Int

GetCount returns the number of possible different values for this item. If no multiple values are represented, the count is 1. For instance, a segment with a value range of 3-7 has a count of 5. Use IsMultiple if you just want to know if the count is greater than 1.

func (*AddressSegment) GetLeadingBitCount 

func (seg *AddressSegment) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading bits of one or zero. 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 lowest value of the range if that segment represents multiple values.

func (*AddressSegment) GetLower 

func (seg *AddressSegment) GetLower() *AddressSegment

GetLower returns a segment representing only the lowest value in the range, which would be the same segment if it represented a single value.

func (*AddressSegment) GetMaxValue 

func (seg *AddressSegment) GetMaxValue() SegInt

GetMaxValue gets the maximum possible value for a given segment type or version, determined by the number of bits. Use GetUpperSegmentValue to get the highest range value of that particular segment.

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 a count of the number of individual prefix values for a given prefix length in the value range of that 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 

func (seg *AddressSegment) GetSegmentHostMask(networkBits BitCount) SegInt

GetSegmentHostMask returns a value comprising of the same number of total bits as the bit length of a given segment, a value that represents all zero-bits for a given number of bits followed by all one-bits.

func (*AddressSegment) GetSegmentNetworkMask 

func (seg *AddressSegment) GetSegmentNetworkMask(networkBits BitCount) SegInt

GetSegmentNetworkMask returns a value comprising of the same number of total bits as the bit length of a given segment, a value that represents all one-bits for a given number of bits followed by all zero-bits.

func (*AddressSegment) GetSegmentValue 

func (seg *AddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the range of segment values.

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 

func (seg *AddressSegment) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, it returns the number of consecutive trailing zero bits. Otherwise, it returns the number of consecutive trailing one bits. This method applies only to the lowest value of the range if that segment represents multiple values.

func (*AddressSegment) GetUpper 

func (seg *AddressSegment) GetUpper() *AddressSegment

GetUpper returns a segment representing only the highest value in the range, which would be the same segment if it represented a single value.

func (*AddressSegment) GetUpperSegmentValue 

func (seg *AddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the range of segment values.

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 the segment includes the maximum value, a value whose bits are all one, in its range.

func (*AddressSegment) IncludesZero 

func (seg *AddressSegment) IncludesZero() bool

IncludesZero returns whether the segment includes a value of zero in 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 an IP-specific type.

func (*AddressSegment) IsIPv4 

func (seg *AddressSegment) IsIPv4() bool

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

func (*AddressSegment) IsIPv6 

func (seg *AddressSegment) IsIPv6() bool

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

func (*AddressSegment) IsMAC 

func (seg *AddressSegment) IsMAC() bool

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

func (*AddressSegment) IsMax 

func (seg *AddressSegment) IsMax() bool

IsMax returns whether the segment exactly matches the maximum possible value - a value whose bits are all one.

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 lowest value of this segment by the given index is 1, where index 0 refers to the most significant bit. IsOneBit will cause a panic if bitIndex is less than zero, or if it is larger than the number of bits of this item.

func (*AddressSegment) IsSinglePrefix 

func (seg *AddressSegment) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix determines whether a segment has a single prefix value for a given prefix length. You can call GetPrefixCountLen to get the number of prefixes.

func (*AddressSegment) IsZero 

func (seg *AddressSegment) IsZero() bool

IsZero returns whether the segment is exactly 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 range of the segment matches the specified single value.

func (*AddressSegment) MatchesValsWithMask 

func (seg *AddressSegment) MatchesValsWithMask(lowerValue, upperValue, mask SegInt) bool

MatchesValsWithMask applies a mask to a given segment and then compares the result to 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 a mask to a given segment and then compares the result to 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 this segment prefix are also prefix values in this segment. Returns whether the prefix of this segment contains the prefix of given segment.

func (*AddressSegment) PrefixEqual 

func (seg *AddressSegment) PrefixEqual(other AddressSegmentType, prefixLength BitCount) bool

PrefixEqual returns whether the prefix bits of a given segment match the same bits of that segment. Returns whether the two segments have the same range of prefix values for a given prefix length.

func (*AddressSegment) ReverseBits 

func (seg *AddressSegment) ReverseBits(perByte bool) (res *AddressSegment, err address_error.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 address_error.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 lowest value of this segment by the given index is 1, where index 0 refers to the least significant bit. In other words, it calculates (bits & (1 << n) != 0), using the lowest value of that section. TestBit panics if n < 0, or if it matches or exceeds the number of bits of this item.

func (*AddressSegment) ToDiv 

func (seg *AddressSegment) ToDiv() *AddressDivision

ToDiv converts to AddressDivision, a polymorphic type used with all address segments and divisions. This can then be converted back with ToSegmentBase. ToDiv can be called with a nil receiver, allowing this method to be used in a chain with methods that may return a nil pointer.

func (*AddressSegment) ToHexString 

func (seg *AddressSegment) ToHexString(with0xPrefix bool) (string, address_error.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 that can be called with a nil receiver, allowing this method to be used in a chain with methods that can 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.
	// For IPv6, RFC 5952 describes a canonical string representation.
	// For MAC, 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.
	// In the case of 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, such as "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 for 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, address_error.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, address_error.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 for 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)
	// - range of values
	// 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 used with all address segments.
	//
	// Implementations of ToSegmentBase can be called with a nil receiver,
	// allowing this method to be used in a chain with methods that can return a nil pointer.
	ToSegmentBase() *AddressSegment
}

AddressSegmentType serves as a common interface for all segments, including AddressSegment, IPAddressSegment, IPv6AddressSegment, IPv4AddressSegment and MACAddressSegment.

type AddressTrie 

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 

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 

func (alloc AllocatedBlock[T]) GetAddress() T

GetAddress returns the block.

func (AllocatedBlock[T]) GetCount 

func (alloc AllocatedBlock[T]) GetCount() *big.Int

GetCount returns the total number of addresses within the block.

func (AllocatedBlock[T]) GetReservedCount 

func (alloc AllocatedBlock[T]) GetReservedCount() int

GetReservedCount returns the number of reserved addresses with the block.

func (AllocatedBlock[T]) GetSize 

func (alloc AllocatedBlock[T]) GetSize() *big.Int

GetSize returns the number of hosts for which this block was allocated.

func (AllocatedBlock[T]) String 

func (alloc AllocatedBlock[T]) String() string

String returns a string representation of the allocated block.

type AssociativeAddedTree 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

type AssociativeAddressTrie = AssociativeTrie[*Address, any]

type AssociativeTrie 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (trie *AssociativeTrie[T, V]) Clone() *AssociativeTrie[T, V]

Clone clones this trie.

func (*AssociativeTrie[T, V]) ConstructAddedNodesTree 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (trie AssociativeTrie[T, V]) Format(state fmt.State, verb rune)

For some reason Format must be here and not in addressTrieNode for nil node. It panics in fmt code either way, but if in here then it is handled by a recover() call in fmt properly in the debugger.

Format implements the fmt.Formatter interface.

func (*AssociativeTrie[T, V]) Get 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (node *AssociativeTrieNode[T, V]) ClearValue()

ClearValue makes the value associated with this node the zero-value of V.

func (*AssociativeTrieNode[T, V]) Clone 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (node AssociativeTrieNode[T, V]) Format(state fmt.State, verb rune)

For some reason Format must be here and not in addressTrieNode for nil node. It panics in fmt code either way, but if in here then it is handled by a recover() call in fmt properly in the debugger.

Format implements the fmt.Formatter interface.

func (*AssociativeTrieNode[T, V]) Get 

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 

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 

func (node *AssociativeTrieNode[T, V]) GetKey() T

GetKey gets the key used for placing the node in the trie.

func (*AssociativeTrieNode[T, V]) GetLowerSubNode 

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 

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 

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 

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 

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 

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 

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 

func (node *AssociativeTrieNode[T, V]) IsEmpty() bool

IsEmpty returns whether the size is zero.

func (*AssociativeTrieNode[T, V]) IsLeaf 

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 

func (node *AssociativeTrieNode[T, V]) IsRoot() bool

IsRoot returns whether this is the root of the backing trie.

func (*AssociativeTrieNode[T, V]) Iterator 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (node *AssociativeTrieNode[T, V]) SetValue(val V)

SetValue sets the value associated with this node.

func (*AssociativeTrieNode[T, V]) Size 

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 

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 

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 

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 

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

BitCount is a bit count of an address, section, grouping, segment or division. Using signed integers simplifies arithmetic by avoiding errors. However, all methods adjust the number of bits according to the address size, so negative numbers of bits or numbers of bits greater than the address size are meaningless. Using signed integers allows you to simplify arithmetic.

type BitItem 

type BitItem interface {
	// GetByteCount returns the number of bytes needed
	// for each value that makes up the given address element,
	// rounded up if the number of bits 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 

type Cached = tree.C

type CachingTrieIterator 

type CachingTrieIterator[T any] interface {
	IteratorWithRemove[T]
	// Note: We could theoretically try to make the cached type generic.
	// But the problem with that is that the iterator methods that return them cannot be generic on their own, the whole type would need to specify the cache type.
	// The other problem is that even if we could, some callers would not care about the caching behaviour and thus would not want to have to specify a cache type.
	//
	// 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 

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 

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 

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 

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 

func (path *ContainmentPath[T]) String() string

String returns a visual representation of the Path with one node per line.

type ContainmentPathNode 

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

ContainmentPathNode is a node in a ContainmentPath.

func (*ContainmentPathNode[T]) Count 

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 

func (node *ContainmentPathNode[T]) GetKey() T

GetKey gets the containing block or matching address corresponding to this node.

func (*ContainmentPathNode[T]) ListString 

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 

func (node *ContainmentPathNode[T]) Next() *ContainmentPathNode[T]

Next gets the node contained by this node.

func (*ContainmentPathNode[T]) Previous 

func (node *ContainmentPathNode[T]) Previous() *ContainmentPathNode[T]

Previous gets the node containing this node.

func (*ContainmentPathNode[T]) String 

func (node *ContainmentPathNode[T]) String() string

String returns a visual representation of this node including the address key.

type ContainmentValuesPath 

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 

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 

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 

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 

func (path *ContainmentValuesPath[T, V]) String() string

String returns a visual representation of the Path with one node per line.

type ContainmentValuesPathNode 

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 

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 

func (node *ContainmentValuesPathNode[T, V]) GetKey() T

GetKey gets the containing block or matching address corresponding to this node

func (*ContainmentValuesPathNode[T, V]) GetValue 

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 

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 

func (node *ContainmentValuesPathNode[T, V]) Next() *ContainmentValuesPathNode[T, V]

Next gets the node contained by this node.

func (*ContainmentValuesPathNode[T, V]) Previous 

func (node *ContainmentValuesPathNode[T, V]) Previous() *ContainmentValuesPathNode[T, V]

Previous gets the node containing this node

func (*ContainmentValuesPathNode[T, V]) String 

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 

type DelimitedAddressString string

func (DelimitedAddressString) CountDelimitedAddresses 

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 

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 

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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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 address_string.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() AddressType         // returns the identified address or nil if none
	ToAddress() (AddressType, error) // returns the identified address or an error
	Unwrap() HostIdentifierString    // returns the wrapped IPAddressString, MACAddressString or HostName as an interface, 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 

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, address_error.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, address_error.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, address_error.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, address_error.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 address_string.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 

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 

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 

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 

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 

func (hostBitCount *HostBitCount) IsNil() bool

IsNil returns true if this is nil, meaning it represents having no identified host length.

func (*HostBitCount) Len 

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 

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() string     // provides a normalized String representation for the host identified by this HostIdentifierString instance
	IsValid() bool                  // returns whether the wrapped string is a valid identifier for a host
	Wrap() ExtendedIdentifierString // wraps an identifier string into an extended type that is polymorphic to other identifier strings
	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 address_error.AddressValueError)

NewHostNameFromNetIP constructs a HostName from a net.IP.

func NewHostNameFromNetIPAddr 

func NewHostNameFromNetIPAddr(addr *net.IPAddr) (hostName *HostName, err address_error.AddressValueError)

NewHostNameFromNetIPAddr constructs a HostName from a net.IPAddr.

func NewHostNameFromNetNetIPAddr 

func NewHostNameFromNetNetIPAddr(addr netip.Addr) *HostName

NewHostNameFromNetNetIPAddr constructs a host name from a netip.Addr.

func NewHostNameFromNetNetIPAddrPort 

func NewHostNameFromNetNetIPAddrPort(addrPort netip.AddrPort) *HostName

NewHostNameFromNetNetIPAddrPort constructs a host name from a netip.AddrPort.

func NewHostNameFromNetNetIPPrefix 

func NewHostNameFromNetNetIPPrefix(addr netip.Prefix) (hostName *HostName, err address_error.AddressValueError)

NewHostNameFromNetNetIPPrefix constructs a host name from a netip.Prefix.

func NewHostNameFromNetTCPAddr 

func NewHostNameFromNetTCPAddr(addr *net.TCPAddr) (*HostName, address_error.AddressValueError)

NewHostNameFromNetTCPAddr constructs a HostName from a net.TCPAddr.

func NewHostNameFromNetUDPAddr 

func NewHostNameFromNetUDPAddr(addr *net.UDPAddr) (*HostName, address_error.AddressValueError)

NewHostNameFromNetUDPAddr constructs a HostName from a net.UDPAddr.

func NewHostNameFromPrefixedNetIP 

func NewHostNameFromPrefixedNetIP(bytes net.IP, prefixLen PrefixLen) (hostName *HostName, err address_error.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 address_error.AddressValueError)

NewHostNameFromPrefixedNetIPAddr constructs a HostName from a net.IPAddr paired with a prefix length.

func NewHostNameParams 

func NewHostNameParams(str string, params address_string_param.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 

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

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 

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

ToAddresses resolves to one or more addresses. The error can be address_error.AddressStringError, address_error.IncompatibleAddressError, or address_error.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() address_error.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 zero IPAddress, which is neither). An IP address consists of segments that have a range of values and may additionally have an associated prefix length. An IPAddress with a null value has no segments, neither IPv4 nor IPv6, which is not compatible with a null value for IPv4 or IPv6, which are 0.0.0.0 and :: respectively. The null value is also known as adaptive zero. To create it from a string, use NewIPAddressString and then use the ToAddress or GetAddress method from IPAddressString.

func NewIPAddressFromBytes 

func NewIPAddressFromBytes(ip net.IP) (*IPAddress, address_error.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, address_error.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, address_error.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, address_error.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, address_error.AddressError)

NewIPAddressFromNetIPNet constructs a subnet from a net.IPNet. The error can be either address_error.AddressValueError, when the net.IPNet IP or mask has an invalid number of bytes, or address_error.IncompatibleAddressError when the mask and the IP from net.IPNet are different IP versions.

func NewIPAddressFromNetNetIPAddr 

func NewIPAddressFromNetNetIPAddr(addr netip.Addr) *IPAddress

func NewIPAddressFromNetNetIPPrefix 

func NewIPAddressFromNetNetIPPrefix(prefixedAddr netip.Prefix) (*IPAddress, address_error.AddressError)

func NewIPAddressFromPrefixedNetIP 

func NewIPAddressFromPrefixedNetIP(ip net.IP, prefixLength PrefixLen) (*IPAddress, address_error.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, address_error.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 address_error.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 

func NewIPAddressFromSegs(segments []*IPAddressSegment) (res *IPAddress, err address_error.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, address_error.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 address_error.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 

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 

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 

func (addr *IPAddress) GetUpperNetIPAddr() *net.IPAddr

GetUpperNetIPAddr returns the highest address in this subnet or address as a net.IPAddr.

func (*IPAddress) GetUpperNetNetIPAddr 

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 address_error.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, address_error.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, address_error.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, address_error.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, address_error.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 address_string.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 

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, address_error.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 

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, address_error.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, address_error.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, address_error.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, address_error.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 

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 

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, address_error.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, address_error.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 

func (addr *IPAddress) TrieCompare(other *IPAddress) (int, address_error.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 

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 

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 

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, address_error.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 

func (creator IPAddressCreator) NewIPSectionFromSegmentedBytes(bytes []byte, segmentCount int) (*IPAddressSection, address_error.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 

type IPAddressKey = Key[*IPAddress]

type IPAddressLargeDivision 

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

IPAddressLargeDivision represents an arbitrary bit size division in an address or address division grouping. It can contain a single value or a range of consecutive values and has an assigned bit length. Like all address components, it is immutable.

func NewIPAddressLargeDivision 

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 

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 

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 

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 

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

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

func (*IPAddressLargeDivision) CompareSize 

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

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

Instead of calculating the count using GetCount, there can be more efficient ways of determining that one represents more individual values than another.

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

func (*IPAddressLargeDivision) ContainsPrefixBlock 

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 

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 

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 

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 example, 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 

func (div *IPAddressLargeDivision) GetDivisionPrefixLen() PrefixLen

GetDivisionPrefixLen returns the network prefix for the division. For an address like "1.2.0.0/16", the network prefix is 16. When it comes to each address subdivision or segment, the subdivision prefix is the prefix obtained by applying an address or partition prefix. For example, consider the address "1.2.0.0/20." The first segment has no prefix because the address prefix 20 is beyond the 8 bits in the first segment, it is not even applied to the segment. The second segment has no prefix because the address prefix extends beyond bits 9 through 16, which are in the second segment, it also does not apply to this segment. The third segment is prefixed with 4 because address prefix 20 corresponds to the first 4 bits in the third segment, which means that the first 4 bits are part of the network portion of the address or segment. The last segment is prefixed with 0 because no bits are part of the network portion of the address or segment. The following division prefixes apply throughout the address: nil ... nil (1 to the bit length of the segment) 0 ... 0. If the division has no prefix, nil is returned.

func (*IPAddressLargeDivision) GetMinPrefixLenForBlock 

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 in this way, this method returns, the same value as GetPrefixLenForSingleBlock.

This block can have a single prefix or multiple possible prefix values for the returned prefix length. To avoid the case of multiple prefix values, use GetPrefixLenForSingleBlock.

If this division represents a single value, a bit count is returned.

func (*IPAddressLargeDivision) GetPrefixLen 

func (div *IPAddressLargeDivision) GetPrefixLen() PrefixLen

GetPrefixLen returns the network prefix for the unit. For an address like "1.2.0.0/16", the network prefix is 16. When it comes to each address subdivision or segment, the prefix for the subdivision is the prefix obtained when the address or partition prefix is applied. For example, consider the address "1.2.0.0/20". The first segment has no prefix because the address prefix 20 is beyond the 8 bits in the first segment, it is not even applied to the segment. The second segment has no prefix because the address prefix extends beyond bits 9 through 16, which are in the second segment, it also does not apply to this segment. The third segment is prefixed with 4 because address prefix 20 corresponds to the first 4 bits in the third segment, which means that the first 4 bits are part of the network portion of the address or segment. The last segment is prefixed with 0 because no bits are part of the network portion of the address or segment. The following division prefixes apply throughout the address: nil ... nil (1 to the bit length of the segment) 0 ... 0. If the segment has no prefix, nil is returned.

func (*IPAddressLargeDivision) GetPrefixLenForSingleBlock 

func (div *IPAddressLargeDivision) GetPrefixLenForSingleBlock() PrefixLen

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

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

If no such prefix length exists, returns nil.

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

func (*IPAddressLargeDivision) GetString 

func (div *IPAddressLargeDivision) GetString() string

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

The returned string 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, which are more appropriate when there is no context.

func (*IPAddressLargeDivision) GetUpperValue 

func (div *IPAddressLargeDivision) GetUpperValue() *BigDivInt

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

func (*IPAddressLargeDivision) GetValue 

func (div *IPAddressLargeDivision) GetValue() *BigDivInt

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

func (*IPAddressLargeDivision) GetWildcardString 

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 

func (div *IPAddressLargeDivision) IsMultiple() bool

IsMultiple returns true if the given division represents a consecutive range of values or a single value.

func (*IPAddressLargeDivision) IsPrefixBlock 

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 

func (div *IPAddressLargeDivision) IsPrefixed() bool

IsPrefixed returns whether the given division has a prefix length associated with it. If so, the prefix length is given by GetDivisionPrefixLen()

func (*IPAddressLargeDivision) IsSinglePrefix 

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 

func (div *IPAddressLargeDivision) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the division range matches the block of values for its prefix length

func (*IPAddressLargeDivision) String 

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 

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

func NewIPAddressLargeDivGrouping 

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 

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

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

func (*IPAddressLargeDivisionGrouping) Compare 

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 

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 

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 

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 

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 

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 

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 

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, it is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice with the value is created and returned.

You can use the GetByteCount function to determine the required length of the byte array.

func (*IPAddressLargeDivisionGrouping) ForEachDivision 

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 

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 

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 

func (grouping *IPAddressLargeDivisionGrouping) GetDivision(index int) *IPAddressLargeDivision

GetDivision returns the division at the given index.

func (*IPAddressLargeDivisionGrouping) GetMinPrefixLenForBlock 

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 

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 

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 

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 

func (grouping *IPAddressLargeDivisionGrouping) IsMultiple() bool

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

func (*IPAddressLargeDivisionGrouping) IsPrefixBlock 

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 

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 

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 

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 

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 that 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 largest numeric value that 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 a subnet or address range into net.IP.
	// If the value can fit into a given net.IP slice, the value is copied into that slice and a length-adjusted subslice 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 a subnet or address range to net.IP.
	// If the value can fit into a given net.IP slice, the value is copied into that slice and a length-adjusted subslice 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 a given subnet or address range in the form net.IP.
	GetNetIP() net.IP
	// GetUpperNetIP returns the highest address in a given subnet or address range in the form net.IP.
	GetUpperNetIP() net.IP
	// GetNetNetIPAddr returns the lowest address in a given subnet or address range as netip.Addr.
	GetNetNetIPAddr() netip.Addr
	// GetUpperNetNetIPAddr returns the highest address in a given subnet or address range as netip.Addr.
	GetUpperNetNetIPAddr() netip.Addr
	// IsSequential returns whether the address item represents a range of addresses that are sequential.
	// Consecutive IP address 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 a complete 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 instances of IPAddress and all instances of a sequential IPAddress range.

type IPAddressSection 

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

IPAddressSection is the address section of an IP address containing a certain number of consecutive IP address segments. It represents a sequence of individual address segments. Each segment has the same bit length. Behind each address is an address section containing all address segments. 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, address_error.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment, while zeroing out bits that have moved in or out of the prefix.

A prefix length cannot be adjusted lower than zero or more than the bit length of the address section.

If a given address section has no prefix length, the prefix length will be set with the adjustment if positive, or with 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 decreases, bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing the 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, it 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 in the section into a byte slice.

If the value can fit into the given slice, it 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 

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 a block of all values for that prefix length.

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

For the returned prefix length, there can be either a single prefix or multiple possible prefix values in this block. To avoid the case of multiple prefix values, use the GetPrefixLenForSingleBlock.

If this section represents a single value, a bit count is returned.

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. This is equivalent to GetPrefixLen.

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

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

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 a grouping with divisions was originally created as an implicitly zero-valued section or grouping (e.g., IPv4AddressSection{}), that is, it was not constructed using a constructor function. Such a grouping that 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, if a section or grouping is null, it is equivalent and convertible to the null value of any other section or grouping of any 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 the given series of address segments has a prefix length and whether it includes the block associated with its prefix length. If the prefix length matches the bit count, true is returned.

This method differs from the ContainsPrefixBlock method in that it returns false if the series has no prefix length or the prefix length differs from the prefix length for which the 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, address_error.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, address_error.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, address_error.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, address_error.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 address_string.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, address_error.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 address_error.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, address_error.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, address_error.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, address_error.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 address_error.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, address_error.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 that 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 

func (section *IPAddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries that 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 IP address segment. An IP segment contains a single value or a range of sequential values, a prefix length, and has an assigned bit length.

For IPv4, segments consist of 1 byte. For IPv6, they consist of 2 bytes.

IPAddressSegment objects are immutable and therefore concurrency-safe.

For more details about segments, see AddressSegment.

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 

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 is 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 a CIDR prefix block mask. Otherwise, nil is returned.

A CIDR network mask is a segment with all ones in the network bits followed by all zeros in the host bits. A CIDR host mask is a segment with all zeros in the network bits followed by all ones in the host bits. The length of the prefix is equal to the length of the network bits.

Note also that the prefix length returned by this method is not equivalent to the prefix length of this segment. The prefix length returned here indicates 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 may be different, or one may be nil and the other may not.

This method applies only to the lowest 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 a count of possible distinct values for the given item. If multiple values are not represented, the count is 1.

For example, a segment with a range of values 3-7 has a count of 5.

If you want to know if the count is greater than 1, use IsMultiple.

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. For an address like "1.2.0.0.0/16", the network prefix is 16. When it comes to each address division or segment, the prefix for the division is the prefix obtained by applying the address or section prefix.

For example, the address is "1.2.0.0.0/20." The first segment has no prefix because the address prefix 20 extends beyond the 8 bits of the first segment and is not even applied to it. The second segment has no prefix because the address prefix extends beyond bits 9 through 16, which lie in the second segment, it does not apply to that segment either. The third segment has a prefix of 4 because the address prefix 20 corresponds to the first 4 bits in the third segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment is prefixed with 0 because not a single bit of the network section of the address or segment.

Division prefixes applied throughout the address: nil ... nil (1 to the segment bit length) 0 ... 0.

If the segment has no prefix, 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 value block for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock, except that it returns false if the subnet has multiple prefixes.

This method differs from ContainsSinglePrefixBlock in that it returns false if no prefix length is assigned to the series or the prefix length is different from the prefix length for which ContainsSinglePrefixBlock returns true.

Method is similar to IsPrefixBlock, but returns false if 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 address_error.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 address_error.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 AddressDivision, a polymorphic type used with all address segments and divisions. The reverse conversion can then be performed using ToIP.

ToDiv can be called with a nil receiver, allowing this method to be used in a chain with methods that can return a nil pointer.

func (*IPAddressSegment) ToHexString 

func (seg *IPAddressSegment) ToHexString(with0xPrefix bool) (string, address_error.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 AddressSegment, a polymorphic type used with all address segments. The reverse conversion can then be convert with ToIP.

ToSegmentBase can be called with a nil receiver, allowing this method to be used in a chain with methods that can 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, address_error.IncompatibleAddressError)
}

IPAddressSegmentSeries serves as a common interface to all IP address sections and IP addresses.

type IPAddressSeqRange 

type IPAddressSeqRange = SequentialRange[*IPAddress]

type IPAddressSeqRangeKey 

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 address_string_param.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, address_error.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 

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 address_error.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() address_string_param.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 

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 

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, address_error.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 address_error.AddressStringError or address_error.IncompatibleAddressError

func (*IPAddressString) ToHostAddress 

func (addrStr *IPAddressString) ToHostAddress() (*IPAddress, address_error.AddressError)

ToHostAddress parses the address while ignoring the prefix length or mask. The error can be address_error.AddressStringError for invalid strings or address_error.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, address_error.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, address_error.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() address_error.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() address_error.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() address_error.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) address_error.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 

type IPPrefixBlockAllocator = PrefixBlockAllocator[*IPAddress]

type IPVersion 

type IPVersion int

IPVersion is the version type used by IP address types. 

const (
	IPv4                   IPVersion = 4 // represents Internet Protocol version 4
	IPv6                   IPVersion = 6 // represents Internet Protocol version 6
	IndeterminateIPVersion IPVersion = 0 // represents an unspecified IP address version
	PrefixLenSeparator               = '/'
	PrefixLenSeparatorStr            = "/"
)

func (IPVersion) Equal 

func (version IPVersion) Equal(other IPVersion) bool

Equal returns true if 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 

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 nil-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, address_error.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 address_error.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 address_error.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, address_error.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, address_error.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, address_error.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 address_error.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 

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 

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 

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, address_error.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 

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 

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, address_error.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 

func (addr *IPv4Address) GetNetIPAddr() *net.IPAddr

GetNetIPAddr returns the lowest address in this subnet or address as a net.IPAddr.

func (*IPv4Address) GetNetNetIPAddr 

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 

func (addr *IPv4Address) GetUpperNetIPAddr() *net.IPAddr

GetUpperNetIPAddr returns the highest address in this subnet or address as a net.IPAddr.

func (*IPv4Address) GetUpperNetNetIPAddr 

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 

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 address_error.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, address_error.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, address_error.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 (*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, address_error.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, address_error.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 address_string.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 

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, address_error.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 InetAtonRadix, joinedCount int) (string, address_error.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 InetAtonRadix) 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 

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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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 

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 

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, address_error.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, address_error.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 

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 

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 

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 

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 

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 

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.

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 

func (key IPv4AddressKey) String() string

String calls the String method in the corresponding address.

func (IPv4AddressKey) ToAddress 

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 address_error.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 address_error.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, address_error.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 address_error.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, it 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 in the section into a byte slice.

If the value can fit into the given slice, it 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, address_error.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 

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 a block of all values for that prefix length.

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

For the returned prefix length, there can be either a single prefix or multiple possible prefix values in this block. To avoid the case of multiple prefix values, use the GetPrefixLenForSingleBlock.

If this section represents a single value, a bit count is returned.

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. This is equivalent to GetPrefixLen.

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

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

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 address_error.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{}), that is, it was not constructed using a constructor function. Such a grouping that has no divisions or segments is converted to an implicitly zero-valued grouping of any type or version, whether IPv6, IPv4, MAC, or other. In other words, if a section or grouping is zero-value, it is equivalent and convertible to the zero value of any other section or grouping of any 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 the given series of address segments has a prefix length and whether it includes the block associated with its prefix length. If the prefix length matches the bit count, true is returned.

This method differs from the ContainsPrefixBlock method in that it returns false if the series has no prefix length or the prefix length differs from the prefix length for which the 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 address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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 address_error.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, address_error.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, address_error.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 InetAtonRadix, joinedCount int) (string, address_error.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 InetAtonRadix) 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, address_error.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, address_error.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, address_error.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 address_string.IPStringOptions, joinedCount int) (string, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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 that 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 

func (section *IPv4AddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries that 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 

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 

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. For an address like "1.2.0.0.0/16", the network prefix is 16. When it comes to each address division or segment, the prefix for the division is the prefix obtained by applying the address or section prefix.

For example, the address is "1.2.0.0.0/20." The first segment has no prefix because the address prefix 20 extends beyond the 8 bits of the first segment and is not even applied to it. The second segment has no prefix because the address prefix extends beyond bits 9 through 16, which lie in the second segment, it does not apply to that segment either. The third segment has a prefix of 4 because the address prefix 20 corresponds to the first 4 bits in the third segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment is prefixed with 0 because not a single bit of the network section of the address or segment.

Division prefixes applied throughout the address: nil ... nil (1 to the segment bit length) 0 ... 0.

If the segment has no prefix, 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 value block for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock, except that it returns false if the subnet has multiple prefixes.

This method differs from ContainsSinglePrefixBlock in that it returns false if no prefix length is assigned to the series or the prefix length is different from the prefix length for which ContainsSinglePrefixBlock returns true.

Method is similar to IsPrefixBlock, but returns false if 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, address_error.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 address_error.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, address_error.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, address_error.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 

type IPv4AddressSeqRangeKey = SequentialRangeKey[*IPv4Address]

type IPv4AddressTrie 

type IPv4AddressTrie = Trie[*IPv4Address]

type IPv4PrefixBlockAllocator 

type IPv4PrefixBlockAllocator = PrefixBlockAllocator[*IPv4Address]

type IPv4SegInt 

type IPv4SegInt = uint8

type IPv4SegmentValueProvider 

type IPv4SegmentValueProvider func(segmentIndex int) IPv4SegInt

func WrapSegmentValueProviderForIPv4 

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, address_error.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 address_error.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 address_error.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, address_error.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, address_error.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 address_error.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 address_error.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 address_error.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 address_error.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 address_error.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 address_error.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 address_error.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 address_error.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 address_error.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 

func NewIPv6AddressFromZonedMACSection(prefix *IPv6AddressSection, suffix *MACAddressSection, zone string) (*IPv6Address, address_error.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 address_error.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, address_error.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, address_error.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 address_error.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 

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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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 

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 

func (addr *IPv6Address) GetUpperNetIPAddr() *net.IPAddr

GetUpperNetIPAddr returns the highest address in this subnet or address as a net.IPAddr.

func (*IPv6Address) GetUpperNetNetIPAddr 

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 

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 address_error.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, address_error.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, address_error.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, address_error.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 (*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 

func (addr *IPv6Address) ToBase85String() (string, address_error.IncompatibleAddressError)

ToBase85String creates the base 85 string, which is described by [RFC 1924](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, address_error.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 address_string.IPv6StringOptions) (string, address_error.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, address_error.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 

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, address_error.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 

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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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 

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 

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, address_error.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, address_error.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 

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 

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 

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 

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 

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 

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 

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 

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.

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 

func (key IPv6AddressKey) String() string

String calls the String method in the corresponding address.

func (IPv6AddressKey) ToAddress 

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

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 

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 address_error.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, address_error.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 address_error.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, it 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 in the section into a byte slice.

If the value can fit into the given slice, it 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, address_error.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 

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, address_error.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 a block of all values for that prefix length.

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

For the returned prefix length, there can be either a single prefix or multiple possible prefix values in this block. To avoid the case of multiple prefix values, use the GetPrefixLenForSingleBlock.

If this section represents a single value, a bit count is returned.

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. This is equivalent to GetPrefixLen.

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

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

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 address_error.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 the given series of address segments has a prefix length and whether it includes the block associated with its prefix length. If the prefix length matches the bit count, true is returned.

This method differs from the ContainsPrefixBlock method in that it returns false if the series has no prefix length or the prefix length differs from the prefix length for which the 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 address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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 address_error.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 

func (section *IPv6AddressSection) ToBase85String() (string, address_error.IncompatibleAddressError)

ToBase85String creates a base 85 string, which is described in [RFC 1924](https://www.rfc-editor.org/rfc/rfc1924.html). It may be written as a range of two values if a range 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, address_error.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

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 address_string.IPv6StringOptions) (string, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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 

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 

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 that 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 

func (section *IPv6AddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries that 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 an IPv6 address segment. An IPv6 segment contains a single value or a range of sequential values, a prefix length, and is 16 bits long.

Like strings, segments are immutable, which also makes them concurrency-safe.

For more information about segments, see AddressSegment.

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 

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 a CIDR prefix block mask. Otherwise, nil is returned. 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 length of the prefix is equal to the length of the network bits.

Note also that the prefix length returned by this method is not equivalent to the prefix length of this segment The prefix length returned here indicates 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 may be different, or one may be nil and the other may not.

This method applies only to the lowest 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 a count of possible distinct values for the given item. If multiple values are not represented, the count is 1.

For example, a segment with a range of values 3-7 has count 5.

If you want to know if the count is greater than 1, use IsMultiple.

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. For an address like "1.2.0.0.0/16", the network prefix is 16. When it comes to each address division or segment, the prefix for the division is the prefix obtained by applying the address or section prefix.

For example, the address is "1.2.0.0.0/20." The first segment has no prefix because the address prefix 20 extends beyond the 8 bits of the first segment and is not even applied to it. The second segment has no prefix because the address prefix extends beyond bits 9 through 16, which lie in the second segment, it does not apply to that segment either. The third segment has a prefix of 4 because the address prefix 20 corresponds to the first 4 bits in the third segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment is prefixed with 0 because not a single bit of the network section of the address or segment.

Division prefixes applied throughout the address: nil ... nil (1 to the segment bit length) 0 ... 0.

If the segment has no prefix, 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 value block for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock, except that it returns false if the subnet has multiple prefixes.

This method differs from ContainsSinglePrefixBlock in that it returns false if no prefix length is assigned to the series or the prefix length is different from the prefix length for which ContainsSinglePrefixBlock returns true.

Method is similar to IsPrefixBlock, but returns false if 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 address_error.IncompatibleAddressError)

ReverseBits returns a segment with reversed bits.

If this segment represents a range of values that cannot be reversed, an error is returned.

For a range to be reversible, it must include all values except possibly the largest and/or smallest that are reversed into themselves. Otherwise, the result is not contiguous and therefore cannot be represented by a sequential range of values.

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

func (*IPv6AddressSegment) ReverseBytes 

func (seg *IPv6AddressSegment) ReverseBytes() (res *IPv6AddressSegment, err address_error.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, address_error.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 

type IPv6AddressSeqRangeKey = SequentialRangeKey[*IPv6Address]

type IPv6AddressTrie 

type IPv6AddressTrie = Trie[*IPv6Address]

type IPv6PrefixBlockAllocator 

type IPv6PrefixBlockAllocator = PrefixBlockAllocator[*IPv6Address]

type IPv6SegInt 

type IPv6SegInt = uint16

type IPv6SegmentValueProvider 

type IPv6SegmentValueProvider func(segmentIndex int) IPv6SegInt

func WrapSegmentValueProviderForIPv6 

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 that are a mix of IPv6 and IPv4 sections. 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 a block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether this item contains multiple prefix values for a given prefix length is irrelevant.

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 into the given slice, it is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice with the value is created and returned.

To determine the required length of the byte array, it is possible to use the GetByteCount.

func (*IPv6v4MixedAddressGrouping) CopyUpperBytes 

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

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

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

To determine the required length of the byte array, it is possible to use the GetByteCount.

func (IPv6v4MixedAddressGrouping) Format 

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

Format is intentionally the only method with non-pointer receivers. It is not intended to be called directly, it is intended for use by the fmt package. When called by a function in the fmt package, nil values are detected before this method is called, avoiding a panic when calling this method.

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 the given grouping includes a block of all values for that prefix length.

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

For the returned prefix length, there can be either a single prefix or multiple possible prefix values in this block. To avoid the case of multiple prefix values, use the GetPrefixLenForSingleBlock.

If this grouping represents a single value, a bit count is returned.

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 the given address division series has a prefix length and whether it includes the block associated with its prefix length. If the prefix length matches the bit count, true is returned.

This method differs from the ContainsPrefixBlock method in that it returns false if the series has no prefix length or the prefix length is different from the prefix length for which the ContainsPrefixBlock method returns true. Note that for any given prefix length, you can perform a comparison with GetMinPrefixLenForBlock.

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. Note for any given prefix length you can compare with GetPrefixLenForSingleBlock.

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 AddressDivisionGrouping, a polymorphic type used with all address sections and divisional groupings. The reverse conversion can then be performed using ToMixedIPv6v4.

ToDivGrouping can be called with a nil receiver, allowing this method to be used in a chain with methods that can 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 InetAtonRadix 

type InetAtonRadix int

InetAtonRadix represents a radix for printing an address string. 

const (
	InetAtonRadixHex      InetAtonRadix = 16
	InetAtonRadixOctal    InetAtonRadix = 8
	InetAtonRadix_decimal InetAtonRadix = 10
)

func (InetAtonRadix) GetRadix 

func (rad InetAtonRadix) GetRadix() int

GetRadix converts the radix to an int.

func (InetAtonRadix) GetSegmentStrPrefix 

func (rad InetAtonRadix) GetSegmentStrPrefix() string

GetSegmentStrPrefix returns the string prefix used to identify the radix.

func (InetAtonRadix) String 

func (rad InetAtonRadix) String() string

String returns the name of the radix.

type IteratePartitionConstraint 

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 

type Iterator[T any] interface {
	HasNext() bool // returns true if there is another item to iterate, false otherwise
	Next() T       // returns the next item, or the zero value for T if there is none left
}

Iterator iterates collections such as subnets and consecutive 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 

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 

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.

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 

func (key Key[T]) String() string

String calls the String method in the corresponding address.

func (Key[T]) ToAddress 

func (key Key[T]) ToAddress() T

ToAddress converts back to an address instance.

type KeyConstraint 

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 

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 may represent a single byte value or a range of byte values.

A MAC address can be constructed 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 create a string from a string, use NewMACAddressString and then use the ToAddress or GetAddress method from MACAddressString.

func NewMACAddress 

func NewMACAddress(section *MACAddressSection) (*MACAddress, address_error.AddressValueError)

NewMACAddress constructs a MAC address or address collection from the given segments.

func NewMACAddressFromBytes 

func NewMACAddressFromBytes(bytes net.HardwareAddr) (*MACAddress, address_error.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 

func NewMACAddressFromSegs(segments []*MACAddressSegment) (*MACAddress, address_error.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, address_error.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 

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, address_error.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 number of prefixes in a given address or subnet. The prefix length is given by GetPrefixLen. If the prefix length is not nil, a count of the range of values in the prefix is returned. If the prefix length is nil, the same value is returned as in GetCount.

func (*MACAddress) GetPrefixCountLen 

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

GetPrefixCountLen returns the number of prefixes in the given address or subnet for the given prefix length. If it is not a subnet with multiple addresses or a subnet with a single prefix of the given prefix length, 1 is returned.

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 (high significant bits) of the address that make up 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 specified when the address is created. For example, "1.2.0.0/16" has a prefix length of 16, and "1.2.*.*" has no prefix length, although both represent the same set of addresses and are considered the same. Prefixes may be considered variable for a given IP address and may depend on routing.

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

For MAC addresses, the prefix is initially derived from a range, so "1:2:3:*:*:*" has a prefix length of 24. MAC addresses derived from an address with a prefix length can 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 given address or subnet represents a range of addresses that are sequential.

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

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

Given any subnet of IP addresses, you can use the SequentialBlockIterator to convert any subnet into a set 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, address_error.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, address_error.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 (*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, address_error.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 address_string.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, address_error.IncompatibleAddressError)

ToDottedString produces the dotted hexadecimal format aaaa.bbbb.cccc

func (*MACAddress) ToEUI64 

func (addr *MACAddress) ToEUI64(asMAC bool) (*MACAddress, address_error.IncompatibleAddressError)

ToEUI64 converts to IPv6 EUI-64 section.

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, address_error.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 

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, address_error.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 

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, address_error.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 

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, address_error.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 

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 

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 

func (addr *MACAddress) TrieCompare(other *MACAddress) (int, address_error.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 

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 

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 

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.

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 

func (key MACAddressKey) String() string

String calls the String method in the corresponding address.

func (MACAddressKey) ToAddress 

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 address_error.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, address_error.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 

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 is intentionally the only method with non-pointer receivers. It is not intended to be called directly, it is intended for use by the fmt package. When called by a function in the fmt package, nil values are detected before this method is called, avoiding a panic when calling this method.

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, address_error.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 

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 

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, address_error.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, address_error.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, address_error.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, address_error.IncompatibleAddressError)

ToDottedString produces the dotted hexadecimal format "aaaa.bbbb.cccc".

func (*MACAddressSection) ToHexString 

func (section *MACAddressSection) ToHexString(with0xPrefix bool) (string, address_error.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 

func (section *MACAddressSection) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces the normalized string.

func (*MACAddressSection) ToOctalString 

func (section *MACAddressSection) ToOctalString(with0Prefix bool) (string, address_error.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 

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 a values block for a 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 

func (seg *MACAddressSegment) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading bits of one or zero. 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 lowest value of the range if that 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 

func (seg *MACAddressSegment) GetSegmentHostMask(networkBits BitCount) SegInt

GetSegmentHostMask returns a value comprising of the same number of total bits as the bit length of a given segment, a value that represents all zero-bits for a given number of bits followed by all one-bits.

func (*MACAddressSegment) GetSegmentNetworkMask 

func (seg *MACAddressSegment) GetSegmentNetworkMask(networkBits BitCount) SegInt

GetSegmentNetworkMask returns a value comprising of the same number of total bits as the bit length of a given segment, a value that represents all one-bits for a given number of bits followed by all zero-bits.

func (*MACAddressSegment) GetSegmentValue 

func (seg *MACAddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the range of segment values.

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 

func (seg *MACAddressSegment) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, it returns the number of consecutive trailing zero bits. Otherwise, it returns the number of consecutive trailing one bits. This method applies only to the lowest value of the range if that 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 range of segment values.

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 the segment includes the maximum value, a value whose bits are all one, in its range.

func (*MACAddressSegment) IncludesZero 

func (seg *MACAddressSegment) IncludesZero() bool

IncludesZero returns whether the segment includes a value of zero in 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 the segment exactly matches the maximum possible value - a value whose bits are all one.

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 whether a segment has a single prefix value for a given prefix length. You can call GetPrefixCountLen to get the number of prefixes.

func (*MACAddressSegment) IsZero 

func (seg *MACAddressSegment) IsZero() bool

IsZero returns whether the segment is exactly 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, address_error.IncompatibleAddressError)

Join joins with another MAC segment to produce a IPv6 segment.

func (*MACAddressSegment) JoinAndFlip2ndBit 

func (seg *MACAddressSegment) JoinAndFlip2ndBit(macSegment1 *MACAddressSegment, prefixLength PrefixLen) (*IPv6AddressSegment, address_error.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 range of the segment matches the specified single value.

func (*MACAddressSegment) MatchesValsWithMask 

func (seg *MACAddressSegment) MatchesValsWithMask(lowerValue, upperValue, mask SegInt) bool

MatchesValsWithMask applies a mask to a given segment and then compares the result to 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 a mask to a given segment and then compares the result to 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 address_error.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, address_error.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 lowest value of this segment by the given index is 1, where index 0 refers to the least significant bit. In other words, it calculates (bits & (1 << n) != 0), using the lowest value of that section. TestBit panics if n < 0, or if it matches or exceeds the number of bits 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, address_error.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 address_string_param.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 

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() address_string_param.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, address_error.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 address_error.AddressStringError for an invalid string, or address_error.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() address_error.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 

func WrapSegmentValueProviderForMAC(f SegmentValueProvider) MACSegmentValueProvider

WrapSegmentValueProviderForMAC converts the given SegmentValueProvider to a MACSegmentValueProvider Values that do not fit MACSegInt are truncated.

type MappedPartition 

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 

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 

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 smallest masked value, which is not necessarily the smallest masked value.
	GetMaskedLower(value, maskValue uint64) uint64
	// GetMaskedUpper provides the largest masked value, which is not necessarily the largest masked value.
	GetMaskedUpper(upperValue, maskValue uint64) uint64
	// IsSequential returns whether masking all values in a range results in a consistent set of values.
	IsSequential() bool
}

Masker is used to mask (apply a bitwise combination) the division and segment values.

func MaskRange 

func MaskRange(value, upperValue, maskValue, maxValue uint64) Masker

MaskRange masks divisions with 64 bits or less. For larger divisions use MaskExtendedRange.

type NodeValue 

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 

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 

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 

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

PrefixBitCount is the number of bits in a non-zero PrefixLen. For arithmetic you can use the signed integer type BitCount, which you can get from 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 

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 

func (alloc *PrefixBlockAllocator[T]) AddAvailable(blocks ...T)

AddAvailable provides the given blocks to the allocator for allocating.

func (*PrefixBlockAllocator[T]) AllocateBitLen 

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 

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 

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 

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 

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 

func (alloc *PrefixBlockAllocator[T]) GetBlockCount() int

GetBlockCount returns the count of available blocks in this allocator.

func (*PrefixBlockAllocator[T]) GetReserved 

func (alloc *PrefixBlockAllocator[T]) GetReserved() (reservedCount int)

GetReserved returns the reserved count. Use SetReserved to change the reserved count.

func (*PrefixBlockAllocator[T]) GetTotalCount 

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 

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 

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 

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 

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 

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.

It can be used as a map key. The zero value is the absence of a prefix length.

func PrefixKeyFrom 

func PrefixKeyFrom(addr AddressType) PrefixKey

func (PrefixKey) ToPrefixLen 

func (pref PrefixKey) ToPrefixLen() PrefixLen

ToPrefixLen converts this key to its corresponding prefix length.

type PrefixLen 

type PrefixLen = *PrefixBitCount

PrefixLen indicates the prefix length for an address, section, division group, segment or division. A value of zero, i.e. nil, indicates that there is no prefix length.

func ToPrefixLen 

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

type Prefixed interface {
	// IsPrefixed returns whether the given element has a prefix length associated with it.
	IsPrefixed() bool
	// GetPrefixLen returns the prefix length, or nil if there is no prefix length.
	// The prefix length indicates the number of bits in the initial part (the most significant bits) of the series that make up the prefix.
	// A prefix is a portion of a series that is not specific to that series but is common to the group, such as a subnet of a CIDR prefix block.
	GetPrefixLen() PrefixLen
	// IsPrefixBlock returns whether the given element has a prefix length and whether it includes the block associated with that prefix length.
	// If the prefix length is the same as the number of bits, true is returned.
	// This method differs from ContainsPrefixBlock in that it returns false if
	// the given element has no prefix length or has a prefix length different from
	// the prefix length for which ContainsPrefixBlock returns true.
	IsPrefixBlock() bool
	// IsSinglePrefixBlock returns whether the value range matches one subnet block for the prefix length.
	// This method differs from ContainsSinglePrefixBlock in that it returns false if the given series
	// has no prefix length or a different prefix length than the prefix length for which ContainsSinglePrefixBlock returns true.
	IsSinglePrefixBlock() bool
}

type PrefixedConstraint 

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

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.

Must be at least uint16 to handle IPv6, at least 32 to handle single-segment IPv4, and no larger than 64 since bits.TrailingZeros64 is used. IP address segment code uses bits.TrailingZeros32 and bits.LeadingZeros32, so it cannot be larger than 32.

type SegIntCount 

type SegIntCount = uint64 // (max value of SegInt) + 1

type SegmentSequence 

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 

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.

func WrapIPv4SegmentValueProvider 

func WrapIPv4SegmentValueProvider(f IPv4SegmentValueProvider) SegmentValueProvider

WrapIPv4SegmentValueProvider converts the given IPv4SegmentValueProvider to a SegmentValueProvider.

func WrapIPv6SegmentValueProvider 

func WrapIPv6SegmentValueProvider(f IPv6SegmentValueProvider) SegmentValueProvider

WrapIPv6SegmentValueProvider converts the given IPv6SegmentValueProvider to a SegmentValueProvider.

func WrapMACSegmentValueProvider 

func WrapMACSegmentValueProvider(f MACSegmentValueProvider) SegmentValueProvider

WrapMACSegmentValueProvider converts the given MACSegmentValueProvider to a SegmentValueProvider

type SequentialRange 

type SequentialRange[T SequentialRangeConstraint[T]] struct {
	// contains filtered or unexported fields
}

SequentialRange represents an arbitrary range of consecutive IP addresses, starting from the lowest address and ending at the top address, inclusive.

For a generic T type, you can select *IPAddress, *IPv4Address, or *IPv6Address.

This type allows any sequential range of addresses to be represented, including those that cannot be represented in IPAddress or IPAddressString.

IPAddress and IPAddressString allow a range of values to be specified for each segment, allowing single addresses, any address subnet with a CIDR prefix (e.g., "1.2.0.0/16" or "1:2:3:4::/64"), or any subnet that can be represented using segment ranges (e.g., "1.2.0-255.*" or "1:2:3:4:*"). See IPAddressString for more 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.

A zero value represents the range from the zero-valued of IPAddress to itself.

For a range of type SequentialRange[*IPAddress], the range extends 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 

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 

func NewSequentialRange[T SequentialRangeConstraint[T]](lower, upper T) *SequentialRange[T]

NewSequentialRange creates a sequential range from the given addresses. 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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (rng *SequentialRange[T]) GetBitCount() BitCount

GetBitCount returns the number of bits in each address in the range.

func (*SequentialRange[T]) GetByteCount 

func (rng *SequentialRange[T]) GetByteCount() int

GetByteCount returns the number of bytes in each address in the range.

func (*SequentialRange[T]) GetCount 

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 

func (rng *SequentialRange[T]) GetIPVersion() IPVersion

GetIPVersion returns the IP version of this IP address sequential range

func (*SequentialRange[T]) GetLower 

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 

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 

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 

func (rng *SequentialRange[T]) GetNetIP() net.IP

GetNetIP returns the lower IP address in the range as a net.IP.

func (*SequentialRange[T]) GetNetNetIPAddr 

func (rng *SequentialRange[T]) GetNetNetIPAddr() netip.Addr

GetNetNetIPAddr returns the lowest address in this address range as a netip.Addr.

func (*SequentialRange[T]) GetPrefixCountLen 

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 

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 

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 

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 

func (rng *SequentialRange[T]) GetUpperNetIP() net.IP

GetUpperNetIP returns the upper IP address in the range as a net.IP.

func (*SequentialRange[T]) GetUpperNetNetIPAddr 

func (rng *SequentialRange[T]) GetUpperNetNetIPAddr() netip.Addr

GetUpperNetNetIPAddr returns the highest address in this address range as a netip.Addr.

func (*SequentialRange[T]) GetUpperValue 

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 

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 

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 

func (rng *SequentialRange[T]) IncludesZero() bool

IncludesZero returns whether this sequential range's lower value is the zero address.

func (*SequentialRange[T]) Intersect 

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.

func (*SequentialRange[T]) IsFullRange 

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 

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. Returns false when lower is nil.

func (*SequentialRange[T]) IsIPv6 

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. Returns false when lower is nil.

func (*SequentialRange[T]) IsMax 

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 

func (rng *SequentialRange[T]) IsMultiple() bool

IsMultiple returns whether this range represents a range of multiple addresses.

func (*SequentialRange[T]) IsSequential 

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 

func (rng *SequentialRange[T]) IsZero() bool

IsZero returns whether this sequential range spans from the zero address to itself.

func (*SequentialRange[T]) Iterator 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

type SequentialRangeConstraint[T any] interface {
	// cannot use IPAddressType here because ToAddressString() results in a circular dependency,
	// SequentialRangeConstraint -> IPAddressType -> IPAddressString -> SequentialRange -> SequentialRangeConstraint
	AddressType
	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 

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.

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 

func (key SequentialRangeKey[T]) String() string

String calls the String method in the corresponding sequential range.

func (SequentialRangeKey[T]) ToSeqRange 

func (key SequentialRangeKey[T]) ToSeqRange() *SequentialRange[T]

ToSeqRange converts back to a sequential range instance.

type SpanPartitionConstraint 

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 division or grouping
	// (e.g., IPv4AddressSection{}),
	// that is, it was not constructed with the constructor function.
	// Such a grouping with no divisions or segments is converted to an implicit zero-valued grouping of any type or version, be it IPv6, IPv4, MAC, or other.
	// In other words, when a section or grouping is a zero-value, it is equivalent and convertible to the zero value of any other section or grouping.
	IsAdaptiveZero() bool
	// ToDivGrouping converts to AddressDivisionGrouping, a polymorphic type used with all address sections and division groupings.
	// Implementations of ToDivGrouping can be called with a nil receiver, allowing this method to be used in a chain with methods that can 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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (trie *Trie[T]) Clear()

Clear removes all added nodes from the trie, after which IsEmpty will return true.

func (*Trie[T]) Clone 

func (trie *Trie[T]) Clone() *Trie[T]

Clone clones this trie.

func (*Trie[T]) ConstructAddedNodesTree 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (trie *Trie[T]) FirstNode() *TrieNode[T]

FirstNode returns the first (lowest valued) node in the trie.

func (*Trie[T]) FloorAddedNode 

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 

func (trie Trie[T]) Format(state fmt.State, verb rune)

For some reason Format must be here and not in addressTrieNode for nil node. It panics in fmt code either way, but if in here then it is handled by a recover() call in fmt properly. Seems to be a problem only in the debugger.

Format implements the fmt.Formatter interface.

func (*Trie[T]) GetAddedNode 

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 

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 

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 

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 

func (trie *Trie[T]) IsEmpty() bool

IsEmpty returns true if there are not any added nodes within this trie.

func (*Trie[T]) Iterator 

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 

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 

func (trie *Trie[T]) LastNode() *TrieNode[T]

LastNode returns the last (highest valued) node in this trie.

func (*Trie[T]) LongestPrefixMatch 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (trie *Trie[T]) String() string

String returns a visual representation of the trie with one node per line.

func (*Trie[T]) TreeString 

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 

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 

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

TrieNode is a node in a compact binary prefix trie whose keys are prefix block subnets or addresses.

func (*TrieNode[T]) AllNodeIterator 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (node TrieNode[T]) Format(state fmt.State, verb rune)

For some reason Format must be here and not in addressTrieNode for nil node. It panics in fmt code either way, but if in here then it is handled by a recover() call in fmt properly in the debugger.

Format implements the fmt.Formatter interface.

func (*TrieNode[T]) GetAddedNode 

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 

func (node *TrieNode[T]) GetKey() T

GetKey gets the key used to place the node in the trie.

func (*TrieNode[T]) GetLowerSubNode 

func (node *TrieNode[T]) GetLowerSubNode() *TrieNode[T]

GetLowerSubNode gets the direct child node whose key is smallest in value.

func (*TrieNode[T]) GetNode 

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 

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 

func (node *TrieNode[T]) GetUpperSubNode() *TrieNode[T]

GetUpperSubNode gets the direct child node whose key is largest in value.

func (*TrieNode[T]) HigherAddedNode 

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 

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 

func (node *TrieNode[T]) IsEmpty() bool

IsEmpty returns whether the size is zero.

func (*TrieNode[T]) IsLeaf 

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 

func (node *TrieNode[T]) IsRoot() bool

IsRoot returns whether this node is the root of the trie.

func (*TrieNode[T]) Iterator 

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 

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 

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 

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 

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 

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 

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 

func (node *TrieNode[T]) NextNode() *TrieNode[T]

NextNode returns the node that follows this node following the trie order.

func (*TrieNode[T]) NodeIterator 

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 

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 

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 

func (node *TrieNode[T]) PreviousNode() *TrieNode[T]

PreviousNode eturns the node that precedes this node following the trie order.

func (*TrieNode[T]) Remove 

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 

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 

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 

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 

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 

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 

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 

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, address_error.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 that make up a given 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 a given 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 number of prefixes in a given address or subnet. The prefix length is given by GetPrefixLen. If the prefix length is not nil, a count of the range of values in the prefix is returned. If the prefix length is nil, the same value is returned as in GetCount.

func (WrappedAddress) GetPrefixCountLen 

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

GetPrefixCountLen returns the number of prefixes in the given address or subnet for the given prefix length. If it is not a subnet with multiple addresses or a subnet with a single prefix of the given prefix length, 1 is returned.

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 (high significant bits) of the address that make up 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 specified when the address is created. For example, "1.2.0.0/16" has a prefix length of 16, and "1.2.*.*" has no prefix length, although both represent the same set of addresses and are considered the same. Prefixes may be considered variable for a given IP address and may depend on routing.

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

For MAC addresses, the prefix is initially derived from a range, so "1:2:3:*:*:*" has a prefix length of 24. MAC addresses derived from an address with a prefix length can 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 given address or subnet represents a range of addresses that are sequential.

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

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

Given any subnet of IP addresses, you can use the SequentialBlockIterator to convert any subnet into a set 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, address_error.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, address_error.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, address_error.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 

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, address_error.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 

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 is intentionally the only method with non-pointer receivers. It is not intended to be called directly, it is intended for use by the fmt package. When called by a function in the fmt package, nil values are detected before this method is called, avoiding a panic when calling this method.

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 

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 

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, address_error.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, address_error.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, address_error.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 

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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, it 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 in the section into a byte slice.

If the value can fit into the given slice, it 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 

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 a block of all values for that prefix length.

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

For the returned prefix length, there can be either a single prefix or multiple possible prefix values in this block. To avoid the case of multiple prefix values, use the GetPrefixLenForSingleBlock.

If this section represents a single value, a bit count is returned.

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. This is equivalent to GetPrefixLen.

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

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

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 the given series of address segments has a prefix length and whether it includes the block associated with its prefix length. If the prefix length matches the bit count, true is returned.

This method differs from the ContainsPrefixBlock method in that it returns false if the series has no prefix length or the prefix length differs from the prefix length for which the 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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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, address_error.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 that 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 

func (section WrappedIPAddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries that 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 address_error.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
The address_string package provides interfaces to define how to create certain strings from addresses and address sections, as well as the builder types for creating instances of these interfaces.
 The address_string package provides interfaces to define how to create certain strings from addresses and address sections, as well as the builder types for creating instances of these 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.