ipaddr

package
v1.2.1 Latest Latest
Warning

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

 Go to latest Published: Jun 1, 2022 License: Apache-2.0, Apache-2.0 Imports: 19 Imported by: 21

Documentation

Overview

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

Benefits of this Library

• Parsing of all host name and ipv4/ipv6 address formats in common usage plus some additional formats

• Parsing and representation of subnets, either those specified by network prefix length or those specified with ranges of segment values.

• Allow the separation of address parsing from host parsing.

• Allow control over which formats are allowed when parsing, whether IPv4/6, or subnets, or inet_aton formats, and so on.

• Produce all common address strings of different formats for a given IPv4 or IPv6 address and produce collections of such strings

• Support parsing of all common MAC Address formats in usage and produce all common MAC address strings of different formats

• Integration of MAC Address with IPv6 with standard conversions

• Integration of IPv4 Address with IPv6 through common address conversions

• Polymorphism is a key goal. The library maintains an address framework of interfaces that allow most library functionality to be independent of address type or version, whether IPv4, IPv6 or MAC. This allows for code which supports both IPv4 and IPv6 transparently.

• Thread-safety and immutability. The core types (host names, address strings, addresses, address sections, address segments, address ranges) are all immutable. They do not change their underlying value. For sharing amongst goroutines this is valuable.

• Address modifications, such as altering prefix lengths, masking, splitting into sections and segments, splitting into network and host sections, reconstituting from sections and segments

• Address operations and subnetting, such as obtaining the prefix block subnet for a prefixed address, iterating through subnets, iterating through prefixes, prefix blocks, or segment blocks of subnets, incrementing and decrementing addresses by integer values, reversing address bits for endianness or DNS lookup, set-subtracting subnets from other subnets, subnetting, intersections of subnets, merging subnets, checking containment of addresses in subnets, listing subnets covering a span of addresses

• Sorting and comparison of host names, addresses, address strings and subnets. All the address component types are compararable.

• Integrate with the Go language primitive types and the standard library types net.IP, net.IPAddr, net.IPMask, net.IPNet, net.TCPAddr, net.UDPAddr, and big.Int.

• Making address manipulations easy, so you do not have to worry about longs/ints/shorts/bytes/bits, signed/unsigned, sign extension, ipv4/v6, masking, iterating, and other implementation details.

Design Overview

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

This library is similar in design to the Java IPAddress library (https://github.com/seancfoley/IPAddress), with a similar API, despite the differences between the Java and Go languages, such as the differences in error handling and the lack of inheritance in Go.

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

Code Examples

For common use-cases, you may wish to go straight to the wiki code examples which cover a wide breadth of common use-cases: https://github.com/seancfoley/ipaddress-go/wiki/Code-Examples

Further Documentation

https://seancfoley.github.io/IPAddress/

Getting Started Code Examples

Starting with address or subnet strings, or starting with host name strings:

Example (Address) 
package main

import (
	"fmt"

	"github.com/seancfoley/ipaddress-go/ipaddr"
)

func main() {
	ipv6Str := "a:b:c:d::a:b/64"
	ipv6AddrStr := ipaddr.NewIPAddressString(ipv6Str)
	if ipAddr, err := ipv6AddrStr.ToAddress(); err != nil {
		// handle improperly formatted host name or address string
		fmt.Println("parse error: " + err.Error())
	} else {
		// use the address
		fmt.Printf("%v is in CIDR prefix block %v", ipAddr, ipAddr.ToPrefixBlock())
	}
}

Output:

a:b:c:d::a:b/64 is in CIDR prefix block a:b:c:d::/64
Example (Host) 
package main

import (
	"fmt"

	"github.com/seancfoley/ipaddress-go/ipaddr"
)

func main() {
	hostPortStr := "[a:b:c:d:e:f:a:b]:8080"
	hostServiceStr := "a.b.com:service"
	hostAddressStr := "1.2.3.4"
	dnsStr := "a.b.com"

	host := ipaddr.NewHostName(hostPortStr)
	socketAddress := host.ToNetTCPAddr()
	fmt.Printf("using %v from %v\n", socketAddress, host)
	// use socket address

	host = ipaddr.NewHostName(hostServiceStr)
	socketAddress = host.ToNetTCPAddrService(func(service string) ipaddr.Port {
		switch service {
		case "service":
			res := ipaddr.PortNum(100)
			return &res
		}
		return nil
	})
	fmt.Printf("using %v from %v\n", socketAddress, host)
	// use socket address

	host = ipaddr.NewHostName(hostAddressStr)
	address := host.AsAddress() // does not resolve
	fmt.Printf("using %v from %v\n", address, host)
	// use address

	host = ipaddr.NewHostName(dnsStr)
	address, err := host.ToAddress() // resolves if necessary
	if err == nil {
		fmt.Printf("using %v from %v\n", address, host)
		// use address
	}
}

Output:

Index

Examples

Constants

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

	ExtendedDigitsRangeSeparatorStr = "\u00bb"

	SegmentWildcard    = '*'
	SegmentWildcardStr = "*"

	SegmentSqlWildcard          = '%'
	SegmentSqlWildcardStr       = "%"
	SegmentSqlSingleWildcard    = '_'
	SegmentSqlSingleWildcardStr = "_"
)
View Source 
const (
	PortSeparator    = ':'
	LabelSeparator   = '.'
	IPv6StartBracket = '['
	IPv6EndBracket   = ']'
)
View Source 
const (
	PrefixLenSeparator    = '/'
	PrefixLenSeparatorStr = "/"
)
View Source 
const (
	IPv4SegmentSeparator    = '.'
	IPv4SegmentSeparatorStr = "."
	IPv4BitsPerSegment      = 8
	IPv4BytesPerSegment     = 1
	IPv4SegmentCount        = 4
	IPv4ByteCount           = 4
	IPv4BitCount            = 32
	IPv4DefaultTextualRadix = 10
	IPv4MaxValuePerSegment  = 0xff
	IPv4MaxValue            = 0xffffffff
	IPv4ReverseDnsSuffix    = ".in-addr.arpa"
	IPv4SegmentMaxChars     = 3
)
View Source 
const (
	IPv6SegmentSeparator            = ':'
	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  = '-'
	IPv6UncZoneSeparator     = 's'
	IPv6UncRangeSeparator    = AlternativeRangeSeparator
	IPv6UncRangeSeparatorStr = AlternativeRangeSeparatorStr
	IPv6UncSuffix            = ".ipv6-literal.net"

	IPv6SegmentMaxChars = 4

	IPv6AlternativeRangeSeparatorStr = AlternativeRangeSeparatorStr
)
View Source 
const (
	IPv4Scheme               = AddressScheme(IPv4)
	IPv6Scheme               = AddressScheme(IPv6)
	EUIScheme  AddressScheme = "EUI"
)
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 MaxSegmentCount = IPv6SegmentCount
View Source 
const NoZone = ""
View Source 
const SegIntSize = 32 // must match the bit count of SegInt
View Source 
const SegmentValueDelimiter = ','

Variables

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

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

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

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

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

Functions

func AddrsMatchOrdered 

func AddrsMatchOrdered(addrs1, addrs2 []*IPAddress) (result bool)

AddrsMatchOrdered checks if the two slices share the same ordered list of addresses using address equality.

func AddrsMatchUnordered 

func AddrsMatchUnordered(addrs1, addrs2 []*IPAddress) (result bool)

AddrsMatchUnordered checks if the two slices share the same list of addresses in any order, using address equality. The function can handle duplicates and nil addresses, both of which are ignored.

func CompareSegInt added in v1.1.0 

func CompareSegInt(one, two SegInt) int

CompareSegInt returns a negative number, 0 or a positive number if integer one is less than, equal to, or greater than integer two.

func CountDelimitedAddresses 

func CountDelimitedAddresses(str string) int

CountDelimitedAddresses will count the possible combinations, given a string with comma delimiters separating segment elements. It is a counterpart to 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 TreesString added in v1.1.0 

func TreesString(withNonAddedKeys bool, tries ...*AddressTrie) string

Types

type Address 

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

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

Addresses consist of a sequence of segments, each of equal bit-size. The number of such segments and the bit-size are determined by the underlying version or type of the address, whether IPv4, IPv6, MAC, or other. Each segment can represent a single value or a sequential range of values.

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

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

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

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

The zero value for an Address is an address with no segments and no associated address version or type.

func (*Address) AdjustPrefixLen 

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

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

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

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

func (*Address) AdjustPrefixLenZeroed 

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

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

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

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

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

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

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

func (*Address) AssignMinPrefixForBlock 

func (addr *Address) AssignMinPrefixForBlock() *Address

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

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

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

func (*Address) AssignPrefixForSingleBlock 

func (addr *Address) AssignPrefixForSingleBlock() *Address

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

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

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

func (*Address) BlockIterator 

func (addr *Address) BlockIterator(segmentCount int) AddressIterator

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, given the count argument 2, it will iterate through 1.3.5-6.7, 1.4.5-6.7, 2.3.5-6.7, 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 AddressType) int

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

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

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

func (*Address) Contains 

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

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

func (*Address) ContainsPrefixBlock 

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

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

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

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

func (*Address) ContainsSinglePrefixBlock 

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

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

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

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

func (*Address) CopyBytes 

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

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

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

func (*Address) CopySegments 

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

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

func (*Address) CopySubSegments 

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

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

func (*Address) CopyUpperBytes 

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

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

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

func (*Address) Equal 

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

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

func (*Address) ForEachSegment added in v1.2.0 

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

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

func (Address) Format 

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

Format implements fmt.Formatter interface. It accepts the formats 'v' for the default address and section format (either the normalized or canonical string), 's' (string) for the same, 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix), 'd' (decimal), 'x' (lowercase hexadecimal), and 'X' (uppercase hexadecimal). Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which is leading zero for octal and for hexadecimal, a leading "0x" or "0X" for "%#x" and "%#X" respectively, Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*Address) GetBitCount 

func (addr *Address) GetBitCount() BitCount

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

func (*Address) GetBitsPerSegment 

func (addr *Address) GetBitsPerSegment() BitCount

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

func (*Address) GetBlockCount 

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

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

func (*Address) GetByteCount 

func (addr *Address) GetByteCount() int

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

func (*Address) GetBytesPerSegment 

func (addr *Address) GetBytesPerSegment() int

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

func (*Address) GetCount 

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

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

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

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

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

func (*Address) GetDivisionCount 

func (addr *Address) GetDivisionCount() int

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

func (*Address) GetGenericDivision 

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

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

func (*Address) GetGenericSegment 

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

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

func (*Address) GetLeadingBitCount added in v1.1.0 

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

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

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

func (*Address) GetLower 

func (addr *Address) GetLower() *Address

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

func (*Address) GetMaxSegmentValue 

func (addr *Address) GetMaxSegmentValue() SegInt

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

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

func (*Address) GetMinPrefixLenForBlock 

func (addr *Address) GetMinPrefixLenForBlock() BitCount

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

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

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

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

func (*Address) GetPrefixCount 

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

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

The prefix length is given by GetPrefixLen.

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

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

func (*Address) GetPrefixCountLen 

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

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

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

func (*Address) GetPrefixLen 

func (addr *Address) GetPrefixLen() PrefixLen

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

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

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

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

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

For MAC addresses, the prefix is initially inferred from the range, so 1:2:3:*:*:* has a prefix length of 24. Addresses derived from the original may retain the original prefix length regardless of their range.

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 null 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 index larger than the segment count.

func (*Address) GetSegmentCount 

func (addr *Address) GetSegmentCount() int

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

func (*Address) GetSegmentStrings 

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

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

func (*Address) GetSegments 

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

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

func (*Address) GetSequentialBlockCount 

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

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

func (*Address) GetSequentialBlockIndex 

func (addr *Address) GetSequentialBlockIndex() int

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

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

func (*Address) GetSubSection 

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

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

func (*Address) GetTrailingBitCount added in v1.1.0 

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

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

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

func (*Address) GetTrailingSection 

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

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

func (*Address) GetUpper 

func (addr *Address) GetUpper() *Address

GetUpper returns the address in the subnet or address collection with the highest numeric value, which will be the receiver if it represents a single address. For example, for "1.2-3.4.5-6", the series "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 < 0, 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 prefix lengths for which ContainsPrefixBlock returns true.

func (*Address) IsPrefixed 

func (addr *Address) IsPrefixed() bool

IsPrefixed returns whether this address has an associated prefix length

func (*Address) IsSequential 

func (addr *Address) IsSequential() bool

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

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

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

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

func (*Address) IsSinglePrefixBlock 

func (addr *Address) IsSinglePrefixBlock() bool

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

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

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

For instance, 1.*.*.* /16 return false for this method and returns true for 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() AddressIterator

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() AddressIterator

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() AddressIterator

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

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

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

func (*Address) ReverseBits 

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

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

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

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

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

func (*Address) ReverseBytes 

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

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

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

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

func (*Address) ReverseSegments 

func (addr *Address) ReverseSegments() *Address

ReverseSegments returns a new address with the segments reversed.

func (*Address) SequentialBlockIterator 

func (addr *Address) SequentialBlockIterator() AddressIterator

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, 2.4.6.7-8.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*Address) SetPrefixLen 

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

SetPrefixLen sets the prefix length.

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

func (*Address) SetPrefixLenZeroed 

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

SetPrefixLenZeroed sets the prefix length.

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

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

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

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

func (*Address) String 

func (addr *Address) String() string

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

func (*Address) TestBit 

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

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

func (*Address) ToAddressBase 

func (addr *Address) ToAddressBase() *Address

ToAddressBase is an identity method.

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

func (*Address) ToAddressString 

func (addr *Address) ToAddressString() HostIdentifierString

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

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

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

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

func (*Address) ToBinaryString 

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

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

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

func (*Address) ToBlock 

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

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

func (*Address) ToCanonicalString 

func (addr *Address) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address.

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

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

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

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

func (*Address) ToCompressedString 

func (addr *Address) ToCompressedString() string

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

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

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

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

func (*Address) ToCustomString 

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

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

func (*Address) ToHexString 

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

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

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

func (*Address) ToIP 

func (addr *Address) ToIP() *IPAddress

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

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

func (*Address) ToIPv4 

func (addr *Address) ToIPv4() *IPv4Address

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

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

func (*Address) ToIPv6 

func (addr *Address) ToIPv6() *IPv6Address

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

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

func (*Address) ToKey added in v1.1.0 

func (addr *Address) ToKey() *AddressKey

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

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

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

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

func (*Address) ToPrefixBlock 

func (addr *Address) ToPrefixBlock() *Address

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

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

func (*Address) ToPrefixBlockLen added in v1.1.0 

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

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

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

func (*Address) ToSinglePrefixBlockOrAddress added in v1.1.0 

func (addr *Address) ToSinglePrefixBlockOrAddress() *Address

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

func (*Address) TrieCompare added in v1.1.0 

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

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

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

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

func (*Address) TrieDecrement added in v1.1.0 

func (addr *Address) TrieDecrement() *Address

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

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

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

func (*Address) TrieIncrement added in v1.1.0 

func (addr *Address) TrieIncrement() *Address

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

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

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

func (*Address) UpperBytes 

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

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

func (*Address) WithoutPrefixLen 

func (addr *Address) WithoutPrefixLen() *Address

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

func (*Address) Wrap 

func (addr *Address) Wrap() WrappedAddress

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

type AddressComparator 

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

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

func (AddressComparator) Compare 

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

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

func (AddressComparator) CompareAddressSections 

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

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

func (AddressComparator) CompareAddresses 

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

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

func (AddressComparator) CompareDivisions 

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

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

func (AddressComparator) CompareRanges 

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

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

func (AddressComparator) CompareSegments 

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

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

func (AddressComparator) CompareSeries 

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

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

type AddressComponent 

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

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

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

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

AddressComponent represents all addresses, address sections, and address segments

type AddressDivision 

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

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

func NewDivision 

func NewDivision(val DivInt, bitCount BitCount) *AddressDivision

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

func NewPrefixDivision 

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

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

func NewRangeDivision 

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

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

func NewRangePrefixDivision 

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

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

func (*AddressDivision) Bytes 

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

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

func (*AddressDivision) Compare 

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

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

func (*AddressDivision) 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 is leading zero for octal and for hexadecimal, a leading "0x" or "0X" for "%#x" and "%#X" respectively, Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*AddressDivision) GetBitCount 

func (div *AddressDivision) GetBitCount() BitCount

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

func (*AddressDivision) GetByteCount 

func (div *AddressDivision) GetByteCount() int

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

func (*AddressDivision) GetCount 

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

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

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

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

func (*AddressDivision) GetDivisionValue 

func (div *AddressDivision) GetDivisionValue() DivInt

GetDivisionValue returns the lower division value in the range

func (*AddressDivision) GetMaxValue 

func (div *AddressDivision) GetMaxValue() DivInt

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

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

func (*AddressDivision) GetMinPrefixLenForBlock 

func (div *AddressDivision) GetMinPrefixLenForBlock() BitCount

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

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

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

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

func (*AddressDivision) GetPrefixCountLen 

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

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

func (*AddressDivision) GetPrefixLenForSingleBlock 

func (div *AddressDivision) GetPrefixLenForSingleBlock() PrefixLen

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

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

If no such prefix length exists, returns nil.

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

func (*AddressDivision) GetString 

func (div *AddressDivision) GetString() string

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

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

func (*AddressDivision) GetUpperDivisionValue 

func (div *AddressDivision) GetUpperDivisionValue() DivInt

GetUpperDivisionValue returns the upper division value in the range

func (*AddressDivision) GetUpperValue 

func (div *AddressDivision) GetUpperValue() *BigDivInt

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

func (*AddressDivision) GetValue 

func (div *AddressDivision) GetValue() *BigDivInt

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

func (*AddressDivision) GetWildcardString 

func (div *AddressDivision) GetWildcardString() string

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

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

func (*AddressDivision) IncludesMax 

func (div *AddressDivision) IncludesMax() bool

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

func (*AddressDivision) IncludesZero 

func (div *AddressDivision) IncludesZero() bool

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

func (*AddressDivision) IsFullRange 

func (div *AddressDivision) IsFullRange() bool

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

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

func (*AddressDivision) IsIP 

func (div *AddressDivision) IsIP() bool

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

func (*AddressDivision) IsIPv4 

func (div *AddressDivision) IsIPv4() bool

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

func (*AddressDivision) IsIPv6 

func (div *AddressDivision) IsIPv6() bool

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

func (*AddressDivision) IsMAC 

func (div *AddressDivision) IsMAC() bool

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

func (*AddressDivision) IsMax 

func (div *AddressDivision) IsMax() bool

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

func (*AddressDivision) IsMultiple 

func (div *AddressDivision) IsMultiple() bool

IsMultiple returns whether this division represents a sequential range of values

func (*AddressDivision) IsSegmentBase 

func (div *AddressDivision) IsSegmentBase() bool

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

func (*AddressDivision) IsSinglePrefix 

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

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

func (*AddressDivision) IsZero 

func (div *AddressDivision) IsZero() bool

IsZero returns whether this division matches exactly the value of zero

func (*AddressDivision) Matches 

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

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

func (*AddressDivision) MatchesValsWithMask 

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

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

func (*AddressDivision) MatchesWithMask 

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

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

func (*AddressDivision) String 

func (div *AddressDivision) String() string

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

func (*AddressDivision) ToDiv 

func (div *AddressDivision) ToDiv() *AddressDivision

ToDiv is an identity method.

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

func (*AddressDivision) ToIP 

func (div *AddressDivision) ToIP() *IPAddressSegment

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

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

func (*AddressDivision) ToIPv4 

func (div *AddressDivision) ToIPv4() *IPv4AddressSegment

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

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

func (*AddressDivision) ToIPv6 

func (div *AddressDivision) ToIPv6() *IPv6AddressSegment

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

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

func (*AddressDivision) ToMAC 

func (div *AddressDivision) ToMAC() *MACAddressSegment

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

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

func (*AddressDivision) ToSegmentBase 

func (div *AddressDivision) ToSegmentBase() *AddressSegment

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

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

func (*AddressDivision) UpperBytes 

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

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

type AddressDivisionGrouping 

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

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

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

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

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

func NewDivisionGrouping 

func NewDivisionGrouping(divs []*AddressDivision, prefixLength PrefixLen) *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 StandardDivGroupingType) int

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

Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one grouping represents more individual address groupings than another.

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

func (*AddressDivisionGrouping) ContainsPrefixBlock 

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

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

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

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

func (*AddressDivisionGrouping) ContainsSinglePrefixBlock 

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

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

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

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

func (*AddressDivisionGrouping) CopyBytes 

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

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

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

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

func (*AddressDivisionGrouping) CopyDivisions 

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

CopyDivisions copies the existing divisions from the given start index until but not including the division at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments 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 segments copied

func (*AddressDivisionGrouping) CopyUpperBytes 

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

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

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

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

func (*AddressDivisionGrouping) ForEachDivision added in v1.2.0 

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

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

func (AddressDivisionGrouping) Format 

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

Format implements 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 is leading zero for octal and for hexadecimal, 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 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 (*AddressDivisionGrouping) GetDivision 

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

GetDivision returns the division at the given index.

func (*AddressDivisionGrouping) GetDivisionCount 

func (grouping *AddressDivisionGrouping) GetDivisionCount() int

GetDivisionCount returns the number of divisions in this grouping

func (*AddressDivisionGrouping) GetDivisionStrings 

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

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

func (*AddressDivisionGrouping) GetGenericDivision 

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

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

func (*AddressDivisionGrouping) GetMinPrefixLenForBlock 

func (grouping *AddressDivisionGrouping) GetMinPrefixLenForBlock() BitCount

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

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

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

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

func (*AddressDivisionGrouping) GetPrefixCount 

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

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

The prefix length is given by GetPrefixLen.

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

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

func (*AddressDivisionGrouping) GetPrefixCountLen 

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

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

func (*AddressDivisionGrouping) GetPrefixLen 

func (grouping *AddressDivisionGrouping) 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 (*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

func (*AddressDivisionGrouping) IsPrefixBlock 

func (grouping *AddressDivisionGrouping) 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 prefix lengths for which ContainsPrefixBlock returns true.

func (*AddressDivisionGrouping) IsPrefixed 

func (grouping *AddressDivisionGrouping) IsPrefixed() bool

IsPrefixed returns whether this grouping has an associated prefix length

func (*AddressDivisionGrouping) IsSectionBase 

func (grouping *AddressDivisionGrouping) IsSectionBase() bool

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

func (*AddressDivisionGrouping) IsSequential 

func (grouping *AddressDivisionGrouping) IsSequential() bool

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

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

func (*AddressDivisionGrouping) IsSinglePrefixBlock 

func (grouping *AddressDivisionGrouping) IsSinglePrefixBlock() bool

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

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

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

func (*AddressDivisionGrouping) IsZero 

func (grouping *AddressDivisionGrouping) IsZero() bool

IsZero returns whether this grouping matches exactly the value of zero

func (*AddressDivisionGrouping) String 

func (grouping *AddressDivisionGrouping) String() string

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

func (*AddressDivisionGrouping) ToDivGrouping 

func (grouping *AddressDivisionGrouping) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping is an identity method.

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

func (*AddressDivisionGrouping) ToIP 

func (grouping *AddressDivisionGrouping) ToIP() *IPAddressSection

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

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

func (*AddressDivisionGrouping) ToIPv4 

func (grouping *AddressDivisionGrouping) ToIPv4() *IPv4AddressSection

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

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

func (*AddressDivisionGrouping) ToIPv6 

func (grouping *AddressDivisionGrouping) ToIPv6() *IPv6AddressSection

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

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

func (*AddressDivisionGrouping) ToMAC 

func (grouping *AddressDivisionGrouping) ToMAC() *MACAddressSection

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

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

func (*AddressDivisionGrouping) ToMixedIPv6v4 

func (grouping *AddressDivisionGrouping) ToMixedIPv6v4() *IPv6v4MixedAddressGrouping

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

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

func (*AddressDivisionGrouping) ToSectionBase 

func (grouping *AddressDivisionGrouping) ToSectionBase() *AddressSection

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

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

func (*AddressDivisionGrouping) UpperBytes 

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

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

type AddressDivisionSeries 

type AddressDivisionSeries interface {
	AddressItem

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

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

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

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

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

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

	// IsPrefixBlock returns whether this address division series has a prefix length and includes the block associated with its prefix length.
	// If the prefix length matches the bit count, this returns true.
	//
	// This is different from ContainsPrefixBlock in that this method returns
	// false if the series has no prefix length or a prefix length that differs from prefix lengths for which ContainsPrefixBlock returns true.
	IsPrefixBlock() bool

	// IsSinglePrefixBlock returns whether the range of values matches a single subnet block for the prefix length.
	//
	// This is different from ContainsSinglePrefixBlock in that this method returns
	// false if this series has no prefix length or a prefix length that differs from the prefix lengths for which ContainsSinglePrefixBlock returns true.
	IsSinglePrefixBlock() bool

	// IsPrefixed returns whether this address has an associated prefix length
	IsPrefixed() bool

	// GetPrefixLen returns the prefix length, or nil if there is no prefix length.
	//
	// A prefix length indicates the number of bits in the initial part (most significant bits) of the series that comprise the prefix.
	//
	// A prefix is a part of the series that is not specific to that series but common amongst a group, such as a CIDR prefix block subnet.
	GetPrefixLen() PrefixLen

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

AddressDivisionSeries serves as a common interface to all division groupings and addresses

type AddressItem 

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

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

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

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

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

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

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

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

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

	// GetBitCount returns the number of bits in each value comprising this address item
	GetBitCount() BitCount

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

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

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

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

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

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

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

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

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

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

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

	fmt.Stringer
}

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

type AddressIterator 

type AddressIterator interface {
	HasNext

	// Next returns the next address, or nil if there is none left.
	Next() *Address
}

AddressIterator iterates through addresses, subnets and address ranges

func NewFilteredAddrIterator 

func NewFilteredAddrIterator(iter AddressIterator, skip func(*Address) bool) AddressIterator

NewFilteredAddrIterator modifies an address iterator to skip certain addresses, skipping those elements for which the "skip" function returns true

type AddressKey added in v1.1.0 

type AddressKey struct {
	Scheme AddressScheme
	Values [MaxSegmentCount]struct {
		Value      SegInt
		UpperValue SegInt
	}
	SegmentCount uint8
	Prefix       PrefixKey
	Zone         Zone
}

AddressKey is a representation of Address that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators It can be used as a map key. The zero value is a zero-length address.

func (*AddressKey) String added in v1.1.1 

func (key *AddressKey) String() string

String calls the String method in the corresponding address

func (*AddressKey) ToAddress added in v1.1.1 

func (key *AddressKey) ToAddress() *Address

ToAddress converts to an address instance

type AddressScheme added in v1.1.1 

type AddressScheme string

type AddressSection 

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

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

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

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

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

func (*AddressSection) AdjustPrefixLen 

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

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

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

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

func (*AddressSection) AdjustPrefixLenZeroed 

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

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

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

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

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

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

func (*AddressSection) AssignMinPrefixForBlock 

func (section *AddressSection) AssignMinPrefixForBlock() *AddressSection

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

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

func (*AddressSection) AssignPrefixForSingleBlock 

func (section *AddressSection) AssignPrefixForSingleBlock() *AddressSection

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

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

func (*AddressSection) Bytes 

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

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

func (*AddressSection) Compare 

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

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

func (*AddressSection) CompareSize 

func (section *AddressSection) CompareSize(other StandardDivGroupingType) 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 comparing 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, 0 if they are the same, or a negative integer if the other has a larger count.

func (*AddressSection) Contains 

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

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

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

func (*AddressSection) ContainsPrefixBlock 

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

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

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

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

func (*AddressSection) ContainsSinglePrefixBlock 

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

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

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

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

func (*AddressSection) CopyBytes 

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

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

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

func (*AddressSection) CopySegments 

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

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

func (*AddressSection) CopySubSegments 

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

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

func (*AddressSection) CopyUpperBytes 

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

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

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

func (*AddressSection) Equal 

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

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

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

Prefix lengths are ignored.

func (*AddressSection) ForEachSegment added in v1.2.0 

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

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

func (AddressSection) Format 

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

Format implements fmt.Formatter interface. It accepts the formats 'v' for the default address and section format (either the normalized or canonical string), 's' (string) for the same, 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix), 'd' (decimal), 'x' (lowercase hexadecimal), and 'X' (uppercase hexadecimal). Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which is leading zero for octal and for hexadecimal, 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

func (*AddressSection) GetLeadingBitCount added in v1.1.0 

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

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

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

func (*AddressSection) GetLower 

func (section *AddressSection) GetLower() *AddressSection

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

func (*AddressSection) GetMaxSegmentValue 

func (section *AddressSection) GetMaxSegmentValue() SegInt

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

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

func (*AddressSection) GetMinPrefixLenForBlock 

func (section *AddressSection) GetMinPrefixLenForBlock() BitCount

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

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

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

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

func (*AddressSection) GetPrefixCount 

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

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

The prefix length is given by GetPrefixLen.

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

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

func (*AddressSection) GetPrefixCountLen 

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

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

func (*AddressSection) GetPrefixLen 

func (section *AddressSection) GetPrefixLen() PrefixLen

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

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

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

func (*AddressSection) GetPrefixLenForSingleBlock 

func (section *AddressSection) GetPrefixLenForSingleBlock() PrefixLen

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

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

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

func (*AddressSection) GetSegment 

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

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

func (*AddressSection) GetSegmentCount 

func (section *AddressSection) GetSegmentCount() int

func (*AddressSection) GetSegmentStrings 

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

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

func (*AddressSection) GetSegments 

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

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

func (*AddressSection) GetSequentialBlockCount 

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

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

func (*AddressSection) GetSequentialBlockIndex 

func (section *AddressSection) GetSequentialBlockIndex() int

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

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

func (*AddressSection) GetSubSection 

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

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

func (*AddressSection) GetTrailingBitCount added in v1.1.0 

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

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

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

func (*AddressSection) GetTrailingSection 

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

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

func (*AddressSection) GetUpper 

func (section *AddressSection) GetUpper() *AddressSection

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

func (*AddressSection) GetUpperValue 

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

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

func (*AddressSection) GetValue 

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

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

func (*AddressSection) IncludesMax 

func (section *AddressSection) IncludesMax() bool

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

func (*AddressSection) IncludesZero 

func (section *AddressSection) IncludesZero() bool

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

func (*AddressSection) Increment 

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

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

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

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

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

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

On overflow or underflow, Increment returns nil.

func (*AddressSection) IncrementBoundary 

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

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

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

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

On overflow or underflow, IncrementBoundary returns nil.

func (*AddressSection) IsAdaptiveZero 

func (section *AddressSection) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the section was originally created as an implicitly zero-valued section (eg 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, etc 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 (*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 segment 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 < 0, 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() SectionIterator

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() SectionIterator

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() SectionIterator

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

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

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

func (*AddressSection) ReverseBits 

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

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

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

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

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

func (*AddressSection) ReverseBytes 

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

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

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

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

func (*AddressSection) ReverseSegments 

func (section *AddressSection) ReverseSegments() *AddressSection

ReverseSegments returns a new section with the segments reversed.

func (*AddressSection) SetPrefixLen 

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

SetPrefixLen sets the prefix length.

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

func (*AddressSection) SetPrefixLenZeroed 

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

SetPrefixLenZeroed sets the prefix length.

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

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

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

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

func (*AddressSection) String 

func (section *AddressSection) String() string

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

func (*AddressSection) TestBit 

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

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

func (*AddressSection) ToBinaryString 

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

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

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

func (*AddressSection) ToBlock 

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

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

func (*AddressSection) ToCanonicalString 

func (section *AddressSection) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address section.

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

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

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

func (*AddressSection) ToCompressedString 

func (section *AddressSection) ToCompressedString() string

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

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

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

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

func (*AddressSection) ToCustomString 

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

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

func (*AddressSection) ToDivGrouping 

func (section *AddressSection) ToDivGrouping() *AddressDivisionGrouping

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

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

func (*AddressSection) ToHexString 

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

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

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

func (*AddressSection) ToIP 

func (section *AddressSection) ToIP() *IPAddressSection

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

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

func (*AddressSection) ToIPv4 

func (section *AddressSection) ToIPv4() *IPv4AddressSection

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

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

func (*AddressSection) ToIPv6 

func (section *AddressSection) ToIPv6() *IPv6AddressSection

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

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

func (*AddressSection) ToMAC 

func (section *AddressSection) ToMAC() *MACAddressSection

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

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

func (*AddressSection) ToNormalizedString 

func (section *AddressSection) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address section.

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

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

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

func (*AddressSection) ToOctalString 

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

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

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

func (*AddressSection) ToPrefixBlock 

func (section *AddressSection) ToPrefixBlock() *AddressSection

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

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

func (*AddressSection) ToPrefixBlockLen 

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

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

func (*AddressSection) ToSectionBase 

func (section *AddressSection) ToSectionBase() *AddressSection

ToSectionBase is an identity method.

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

func (*AddressSection) UpperBytes 

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

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

func (*AddressSection) WithoutPrefixLen 

func (section *AddressSection) WithoutPrefixLen() *AddressSection

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

func (*AddressSection) Wrap 

func (section *AddressSection) Wrap() WrappedAddressSection

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

type AddressSectionType 

type AddressSectionType interface {
	StandardDivGroupingType

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

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

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

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

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

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

type AddressSegment 

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

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

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

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

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

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

AddressSegment objects are immutable and thus also thread-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) Contains 

func (seg *AddressSegment) Contains(other AddressSegmentType) bool

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

func (*AddressSegment) ContainsPrefixBlock 

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

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

func (*AddressSegment) ContainsSinglePrefixBlock 

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

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

func (*AddressSegment) CopyBytes 

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

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

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

func (*AddressSegment) CopyUpperBytes 

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

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

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

func (*AddressSegment) Equal 

func (seg *AddressSegment) Equal(other AddressSegmentType) bool

Equal returns whether the given segment is equal to this segment. Two segments are equal if they match:

  • type/version (IPv4, IPv6, MAC)
  • value range

Prefix lengths are ignored.

func (*AddressSegment) GetBitCount 

func (seg *AddressSegment) GetBitCount() BitCount

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

func (*AddressSegment) GetByteCount 

func (seg *AddressSegment) GetByteCount() int

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

func (*AddressSegment) GetCount 

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

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

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

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

func (*AddressSegment) GetLeadingBitCount added in v1.1.0 

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

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

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

func (*AddressSegment) GetLower 

func (seg *AddressSegment) GetLower() *AddressSegment

GetLower returns a segment representing just the lowest value in the range, which will be the same segment if it represents a single value.

func (*AddressSegment) GetMaxValue 

func (seg *AddressSegment) GetMaxValue() SegInt

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

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

func (*AddressSegment) GetMinPrefixLenForBlock 

func (seg *AddressSegment) GetMinPrefixLenForBlock() BitCount

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

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

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

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

func (*AddressSegment) GetPrefixCountLen 

func (seg *AddressSegment) GetPrefixCountLen(segmentPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct prefix values for the given prefix length in the range of values of this segment

func (*AddressSegment) GetPrefixLenForSingleBlock 

func (seg *AddressSegment) GetPrefixLenForSingleBlock() PrefixLen

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

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

If no such prefix length exists, returns nil.

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

func (*AddressSegment) GetPrefixValueCountLen 

func (seg *AddressSegment) GetPrefixValueCountLen(segmentPrefixLength BitCount) SegIntCount

GetPrefixValueCountLen returns the same value as GetPrefixCountLen as an integer

func (*AddressSegment) GetSegmentHostMask added in v1.1.0 

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

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

func (*AddressSegment) GetSegmentNetworkMask added in v1.1.0 

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

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

func (*AddressSegment) GetSegmentValue 

func (seg *AddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the segment value range

func (*AddressSegment) GetString 

func (seg *AddressSegment) GetString() string

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

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

func (*AddressSegment) GetTrailingBitCount added in v1.1.0 

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

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

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

func (*AddressSegment) GetUpper 

func (seg *AddressSegment) GetUpper() *AddressSegment

GetUpper returns a segment representing just the highest value in the range, which will be the same segment if it represents a single value.

func (*AddressSegment) GetUpperSegmentValue 

func (seg *AddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the segment value range

func (*AddressSegment) GetUpperValue 

func (seg *AddressSegment) GetUpperValue() *BigDivInt

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

func (*AddressSegment) GetValue 

func (seg *AddressSegment) GetValue() *BigDivInt

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

func (*AddressSegment) GetValueCount 

func (seg *AddressSegment) GetValueCount() SegIntCount

GetValueCount returns the same value as GetCount as an integer

func (*AddressSegment) GetWildcardString 

func (seg *AddressSegment) GetWildcardString() string

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

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

func (*AddressSegment) IncludesMax 

func (seg *AddressSegment) IncludesMax() bool

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

func (*AddressSegment) IncludesZero 

func (seg *AddressSegment) IncludesZero() bool

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

func (*AddressSegment) IsFullRange 

func (seg *AddressSegment) IsFullRange() bool

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

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

func (*AddressSegment) IsIP 

func (seg *AddressSegment) IsIP() bool

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

func (*AddressSegment) IsIPv4 

func (seg *AddressSegment) IsIPv4() bool

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

func (*AddressSegment) IsIPv6 

func (seg *AddressSegment) IsIPv6() bool

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

func (*AddressSegment) IsMAC 

func (seg *AddressSegment) IsMAC() bool

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

func (*AddressSegment) IsMax 

func (seg *AddressSegment) IsMax() bool

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

func (*AddressSegment) IsMultiple 

func (seg *AddressSegment) IsMultiple() bool

IsMultiple returns whether this segment represents multiple values

func (*AddressSegment) IsOneBit 

func (seg *AddressSegment) IsOneBit(segmentBitIndex BitCount) bool

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

func (*AddressSegment) IsSinglePrefix 

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

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

func (*AddressSegment) IsZero 

func (seg *AddressSegment) IsZero() bool

IsZero returns whether this segment matches exactly the value of zero

func (*AddressSegment) Iterator 

func (seg *AddressSegment) Iterator() SegmentIterator

Iterator provides an iterator to iterate through the individual address segments of this address segment.

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

func (*AddressSegment) Matches 

func (seg *AddressSegment) Matches(value SegInt) bool

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

func (*AddressSegment) MatchesValsWithMask 

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

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

func (*AddressSegment) MatchesWithMask 

func (seg *AddressSegment) MatchesWithMask(value, mask SegInt) bool

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

func (*AddressSegment) PrefixContains 

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

PrefixContains returns whether the prefix values in the prefix of the given segment are also prefix values in this segment. It returns whether the prefix of this segment contains the prefix of the given segment.

func (*AddressSegment) PrefixEqual 

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

PrefixEqual returns whether the prefix bits of this segment match the same bits of the given segment. It returns whether the two segments share the same range of prefix values using the given prefix length.

func (*AddressSegment) ReverseBits 

func (seg *AddressSegment) ReverseBits(perByte bool) (res *AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBits returns a segment with the bits reversed.

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

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

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

func (*AddressSegment) ReverseBytes 

func (seg *AddressSegment) ReverseBytes() (res *AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBytes returns a segment with the bytes reversed.

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

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

func (*AddressSegment) String 

func (seg *AddressSegment) String() string

String produces a string that is useful when a segment string is provided with no context. If the segment was originally constructed as an IPv4 address segment it uses decimal, otherwise hexadecimal. It uses a string prefix for hex (0x), and does not use the wildcard '*', because division size is variable, so '*' is ambiguous. GetWildcardString is more appropriate in context with other segments or divisions. It does not use a string prefix and uses '*' for full-range segments. GetString is more appropriate in context with prefix lengths, it uses zeros instead of wildcards with full prefix block ranges alongside prefix lengths.

func (*AddressSegment) TestBit 

func (seg *AddressSegment) TestBit(n BitCount) bool

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

func (*AddressSegment) ToDiv 

func (seg *AddressSegment) ToDiv() *AddressDivision

ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions. Afterwards, you can convert back with ToSegmentBase.

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

func (*AddressSegment) ToHexString 

func (seg *AddressSegment) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

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

For segments, the error is always nil.

func (*AddressSegment) ToIP 

func (seg *AddressSegment) ToIP() *IPAddressSegment

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

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

func (*AddressSegment) ToIPv4 

func (seg *AddressSegment) ToIPv4() *IPv4AddressSegment

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

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

func (*AddressSegment) ToIPv6 

func (seg *AddressSegment) ToIPv6() *IPv6AddressSegment

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

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

func (*AddressSegment) ToMAC 

func (seg *AddressSegment) ToMAC() *MACAddressSegment

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

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

func (*AddressSegment) ToNormalizedString 

func (seg *AddressSegment) ToNormalizedString() string

ToNormalizedString produces a string that is consistent for all address segments of the same type and version. IPv4 segments use base 10, while other segment types use base 16.

func (*AddressSegment) ToSegmentBase 

func (seg *AddressSegment) ToSegmentBase() *AddressSegment

ToSegmentBase is an identity method.

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

func (*AddressSegment) UpperBytes 

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

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

type AddressSegmentSeries 

type AddressSegmentSeries interface {
	AddressComponent

	AddressDivisionSeries

	// GetMaxSegmentValue returns the maximum possible segment value for this type of series.
	//
	// Note this is not the maximum of the range of segment values in this specific series,
	// this is the maximum value of any segment for this series type and version, determined by the number of bits per segment.
	GetMaxSegmentValue() SegInt

	// GetSegmentCount returns the number of segments, which is the same as the division count since the segments are also the divisions
	GetSegmentCount() int

	// GetBitsPerSegment returns the number of bits comprising each segment in this series.  Segments in the same series are equal length.
	GetBitsPerSegment() BitCount

	// GetBytesPerSegment returns the number of bytes comprising each segment in this series.  Segments in the same series are equal length.
	GetBytesPerSegment() int

	// ToCanonicalString produces a canonical string for the address series.
	//
	// For IPv4, dotted octet format, also known as dotted decimal format, is used.
	// https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1
	//
	// For IPv6, RFC 5952 describes the canonical string representation.
	// https://en.wikipedia.org/wiki/IPv6_address#Representation
	// http://tools.ietf.org/html/rfc5952
	//
	// For MAC, it uses the canonical standardized IEEE 802 MAC address representation of xx-xx-xx-xx-xx-xx.  An example is "01-23-45-67-89-ab".
	// For range segments, '|' is used: 11-22-33|44-55-66
	//
	// Each address has a unique canonical string, not counting the prefix length.
	// With IP addresses and sections, the prefix length is included in the string, and the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4".
	// It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*".
	ToCanonicalString() string

	// ToCompressedString produces a short representation of this series while remaining within the confines of standard representation(s) of the series.
	//
	// For IPv4, it is the same as the canonical string.
	//
	// For IPv6, it differs from the canonical string.  It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.
	//
	// For MAC, it differs from the canonical string.  It produces a shorter string for the address that has no leading zeros.
	ToCompressedString() string

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

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

	// GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.
	GetSegmentStrings() []string

	// GetGenericSegment returns the segment at the given index as an AddressSegmentType.
	// The first segment is at index 0.
	// GetGenericSegment will panic given a negative index or index larger than the segment count.
	GetGenericSegment(index int) AddressSegmentType
}

AddressSegmentSeries serves as a common interface to all address sections and addresses

type AddressSegmentType 

type AddressSegmentType interface {
	AddressComponent

	StandardDivisionType

	// Equal returns whether the given segment is equal to this segment.
	// Two segments are equal if they match:
	//  - type/version (IPv4, IPv6, MAC)
	//  - value range
	// Prefix lengths are ignored.
	Equal(AddressSegmentType) bool

	// Contains returns whether this segment is same type and version as the given segment and whether it contains all values in the given segment.
	Contains(AddressSegmentType) bool

	// GetSegmentValue returns the lower value of the segment value range as a SegInt
	GetSegmentValue() SegInt

	// GetUpperSegmentValue returns the upper value of the segment value range as a SegInt
	GetUpperSegmentValue() SegInt

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

AddressSegment serves as a common interface to all segments

type AddressTrie added in v1.1.0 

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

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

The zero-value of an AddressTrie is a trie ready for use. Its root will be nil until an element is added to it. Any trie without a root can be converted to a trie of any address type of version. However, 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, and the trie can no longer be converted a trie for any other address version or type. Once there is a root, the root cannot be removed.

Any trie created by a creation function will start with an assigned root.

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 (*AddressTrie) Add added in v1.1.0 

func (trie *AddressTrie) Add(addr *Address) 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 (*AddressTrie) AddNode added in v1.1.0 

func (trie *AddressTrie) AddNode(addr *Address) *AddressTrieNode

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 (*AddressTrie) AddTrie added in v1.1.0 

func (trie *AddressTrie) AddTrie(added *AddressTrieNode) *AddressTrieNode

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.

func (*AddressTrie) AddedNodesTreeString added in v1.1.0 

func (trie *AddressTrie) 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 (*AddressTrie) AllNodeIterator added in v1.1.0 

func (trie *AddressTrie) AllNodeIterator(forward bool) AddressTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes in the trie in forward or reverse tree order.

func (*AddressTrie) BlockSizeAllNodeIterator added in v1.1.0 

func (trie *AddressTrie) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) AddressTrieNodeIteratorRem

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 (*AddressTrie) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (trie *AddressTrie) BlockSizeCachingAllNodeIterator() CachingAddressTrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from largest prefix blocks to smallest, and then to individual addresses.

func (*AddressTrie) BlockSizeNodeIterator added in v1.1.0 

func (trie *AddressTrie) BlockSizeNodeIterator(lowerSubNodeFirst bool) AddressTrieNodeIteratorRem

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 (*AddressTrie) CeilingAddedNode added in v1.1.0 

func (trie *AddressTrie) CeilingAddedNode(addr *Address) *AddressTrieNode

CeilingAddedNode returns the added node whose address is the lowest address greater than or equal to the given address.

func (*AddressTrie) Clear added in v1.1.0 

func (trie *AddressTrie) Clear()

Clear removes all added nodes from the tree, after which IsEmpty() will return true

func (*AddressTrie) Clone added in v1.1.0 

func (trie *AddressTrie) Clone() *AddressTrie

Clone clones this trie

func (*AddressTrie) ConstructAddedNodesTree added in v1.1.0 

func (trie *AddressTrie) ConstructAddedNodesTree() *AddressTrie

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. 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 (*AddressTrie) ContainedFirstAllNodeIterator added in v1.1.0 

func (trie *AddressTrie) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) AddressTrieNodeIterator

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 (*AddressTrie) ContainedFirstIterator added in v1.1.0 

func (trie *AddressTrie) ContainedFirstIterator(forwardSubNodeOrder bool) AddressTrieNodeIteratorRem

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 (*AddressTrie) ContainingFirstAllNodeIterator added in v1.1.0 

func (trie *AddressTrie) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingAddressTrieNodeIterator

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 and linear space (proportional to tree size).

func (*AddressTrie) ContainingFirstIterator added in v1.1.0 

func (trie *AddressTrie) ContainingFirstIterator(forwardSubNodeOrder bool) CachingAddressTrieNodeIterator

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 and linear space (proportional to tree size).

func (*AddressTrie) Contains added in v1.1.0 

func (trie *AddressTrie) Contains(addr *Address) 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 (*AddressTrie) DescendingIterator added in v1.1.0 

func (trie *AddressTrie) DescendingIterator() AddressIterator

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 (*AddressTrie) ElementContains added in v1.1.0 

func (trie *AddressTrie) ElementContains(addr *Address) 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 (*AddressTrie) ElementsContainedBy added in v1.1.0 

func (trie *AddressTrie) ElementsContainedBy(addr *Address) *AddressTrieNode

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 (*AddressTrie) ElementsContaining added in v1.1.0 

func (trie *AddressTrie) ElementsContaining(addr *Address) *ContainmentPath

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 (*AddressTrie) Equal added in v1.1.0 

func (trie *AddressTrie) Equal(other *AddressTrie) bool

Equal returns whether the given argument is a trie with a set of nodes with the same keys as in this trie

func (*AddressTrie) FirstAddedNode added in v1.1.0 

func (trie *AddressTrie) FirstAddedNode() *AddressTrieNode

FirstAddedNode returns the first (lowest valued) added node in the trie, or nil if there are no added entries in this tree or sub-tree

func (*AddressTrie) FirstNode added in v1.1.0 

func (trie *AddressTrie) FirstNode() *AddressTrieNode

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

func (*AddressTrie) FloorAddedNode added in v1.1.0 

func (trie *AddressTrie) FloorAddedNode(addr *Address) *AddressTrieNode

FloorAddedNode returns the added node whose address is the highest address less than or equal to the given address.

func (AddressTrie) Format added in v1.1.0 

func (trie AddressTrie) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface.

func (*AddressTrie) GetAddedNode added in v1.1.0 

func (trie *AddressTrie) GetAddedNode(addr *Address) *AddressTrieNode

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 (*AddressTrie) GetNode added in v1.1.0 

func (trie *AddressTrie) GetNode(addr *Address) *AddressTrieNode

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 (*AddressTrie) GetRoot added in v1.1.0 

func (trie *AddressTrie) GetRoot() *AddressTrieNode

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 (*AddressTrie) HigherAddedNode added in v1.1.0 

func (trie *AddressTrie) HigherAddedNode(addr *Address) *AddressTrieNode

HigherAddedNode returns the added node whose address is the lowest address strictly greater than the given address.

func (*AddressTrie) IsEmpty added in v1.1.0 

func (trie *AddressTrie) IsEmpty() bool

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

func (*AddressTrie) Iterator added in v1.1.0 

func (trie *AddressTrie) Iterator() AddressIterator

Iterator returns an iterator that iterates through the added addresses and prefix blocks in the trie. The iteration is in sorted element order.

func (*AddressTrie) LastAddedNode added in v1.1.0 

func (trie *AddressTrie) LastAddedNode() *AddressTrieNode

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 (*AddressTrie) LastNode added in v1.1.0 

func (trie *AddressTrie) LastNode() *AddressTrieNode

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

func (*AddressTrie) LongestPrefixMatch added in v1.1.0 

func (trie *AddressTrie) LongestPrefixMatch(addr *Address) *Address

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 (*AddressTrie) LongestPrefixMatchNode added in v1.1.0 

func (trie *AddressTrie) LongestPrefixMatchNode(addr *Address) *AddressTrieNode

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 (*AddressTrie) LowerAddedNode added in v1.1.0 

func (trie *AddressTrie) LowerAddedNode(addr *Address) *AddressTrieNode

LowerAddedNode returns the added node whose address is the highest address strictly less than the given address.

func (*AddressTrie) NodeIterator added in v1.1.0 

func (trie *AddressTrie) NodeIterator(forward bool) AddressTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through all the added nodes in the trie in forward or reverse tree order.

func (*AddressTrie) NodeSize added in v1.1.0 

func (trie *AddressTrie) NodeSize() int

NodeSize returns the number of nodes in the tree, which is always more than the number of elements.

func (*AddressTrie) Remove added in v1.1.0 

func (trie *AddressTrie) Remove(addr *Address) 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.

func (*AddressTrie) RemoveElementsContainedBy added in v1.1.0 

func (trie *AddressTrie) RemoveElementsContainedBy(addr *Address) *AddressTrieNode

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 (*AddressTrie) Size added in v1.1.0 

func (trie *AddressTrie) 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 (*AddressTrie) String added in v1.1.0 

func (trie *AddressTrie) String() string

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

func (*AddressTrie) ToAssociative added in v1.1.0 

func (trie *AddressTrie) ToAssociative() *AssociativeAddressTrie

ToAssociative converts this trie to an associative trie. The underlying trie does not change. Associative tries provide additional API to associate each node with a mapped value.

func (*AddressTrie) ToIPv4 added in v1.1.0 

func (trie *AddressTrie) ToIPv4() *IPv4AddressTrie

ToIPv4 converts this trie to an IPv4 trie. If this trie has no root, or the trie has an IPv4 root, the trie can be converted, otherwise, this method returns nil. The underlying trie does not change. The IPv4 type simply provides type safety, because you cannot mix different address versions or types in the same trie. Mixing versions and or types will cause a panic.

func (*AddressTrie) ToIPv4Associative added in v1.1.0 

func (trie *AddressTrie) ToIPv4Associative() *IPv4AddressAssociativeTrie

ToIPv4Associative converts this trie to an IPv4 associative trie. If this trie has no root, or the trie has an IPv4 root, the trie can be converted, otherwise, this method returns nil. The underlying trie does not change. The IPv4 type simply provides type safety, because you cannot mix different address versions or types in the same trie. Mixing versions and or types will cause a panic.

func (*AddressTrie) ToIPv6 added in v1.1.0 

func (trie *AddressTrie) ToIPv6() *IPv6AddressTrie

ToIPv6 converts this trie to an IPv6 trie. If this trie has no root, or the trie has an IPv6 root, the trie can be converted, otherwise, this method returns nil. The underlying trie does not change. The IPv6 type simply provides type safety, because you cannot mix different address versions or types in the same trie. Mixing versions and or types will cause a panic.

func (*AddressTrie) ToIPv6Associative added in v1.1.0 

func (trie *AddressTrie) ToIPv6Associative() *IPv6AddressAssociativeTrie

ToIPv6Associative converts this trie to an IPv6 associative trie. If this trie has no root, or the trie has an IPv6 root, the trie can be converted, otherwise, this method returns nil. The underlying trie does not change. The IPv6 type simply provides type safety, because you cannot mix different address versions or types in the same trie. Mixing versions and or types will cause a panic.

func (*AddressTrie) ToMAC added in v1.1.0 

func (trie *AddressTrie) ToMAC() *MACAddressTrie

ToMAC converts this trie to a MAC trie. If this trie has no root, or the trie has a MAC root, the trie can be converted, otherwise, this method returns nil. The underlying trie does not change. The MAC type simply provides type safety, because you cannot mix different address versions or types in the same trie. Mixing versions and or types will cause a panic.

func (*AddressTrie) ToMACAssociative added in v1.1.0 

func (trie *AddressTrie) ToMACAssociative() *MACAddressAssociativeTrie

ToMACAssociative converts this trie to a MAC associative trie. If this trie has no root, or the trie has a MAC root, the trie can be converted, otherwise, this method returns nil. The underlying trie does not change. The MAC type simply provides type safety, because you cannot mix different address versions or types in the same trie. Mixing versions and or types will cause a panic.

func (*AddressTrie) TreeString added in v1.1.0 

func (trie *AddressTrie) 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 AddressTrieNode added in v1.1.0 

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

AddressTrieNode is a node for a compact binary prefix trie whose elements (keys) are prefix block subnets or addresses.

func (*AddressTrieNode) AllNodeIterator added in v1.1.0 

func (node *AddressTrieNode) AllNodeIterator(forward bool) AddressTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes of the sub-tree with this node as the root, in forward or reverse tree order.

func (*AddressTrieNode) AsNewTrie added in v1.1.0 

func (node *AddressTrieNode) AsNewTrie() *AddressTrie

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 (*AddressTrieNode) BlockSizeAllNodeIterator added in v1.1.0 

func (node *AddressTrieNode) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) AddressTrieNodeIteratorRem

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 (*AddressTrieNode) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (node *AddressTrieNode) BlockSizeCachingAllNodeIterator() CachingAddressTrieNodeIterator

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 (*AddressTrieNode) BlockSizeNodeIterator added in v1.1.0 

func (node *AddressTrieNode) BlockSizeNodeIterator(lowerSubNodeFirst bool) AddressTrieNodeIteratorRem

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 (*AddressTrieNode) CeilingAddedNode added in v1.1.0 

func (node *AddressTrieNode) CeilingAddedNode(addr *Address) *AddressTrieNode

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 (*AddressTrieNode) Clear added in v1.1.0 

func (node *AddressTrieNode) Clear()

Clear removes this node and all sub-nodes from the tree, after which isEmpty() will return true.

func (*AddressTrieNode) Clone added in v1.1.0 

func (node *AddressTrieNode) Clone() *AddressTrieNode

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 (*AddressTrieNode) CloneTree added in v1.1.0 

func (node *AddressTrieNode) CloneTree() *AddressTrieNode

CloneTree clones the sub-tree starting with this node as the root. The nodes are cloned, but their keys and values are not cloned.

func (*AddressTrieNode) Compare added in v1.1.0 

func (node *AddressTrieNode) Compare(other *AddressTrieNode) int

Compare returns -1, 0 or 1 if this node is less than, equal, or greater than the other, according to the key and the trie order.

func (*AddressTrieNode) ContainedFirstAllNodeIterator added in v1.1.0 

func (node *AddressTrieNode) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) AddressTrieNodeIterator

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary tree 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 (*AddressTrieNode) ContainedFirstIterator added in v1.1.0 

func (node *AddressTrieNode) ContainedFirstIterator(forwardSubNodeOrder bool) AddressTrieNodeIteratorRem

ContainedFirstIterator returns an iterator that does a post-order binary tree 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 (*AddressTrieNode) ContainingFirstAllNodeIterator added in v1.1.0 

func (node *AddressTrieNode) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingAddressTrieNodeIterator

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*AddressTrieNode) ContainingFirstIterator added in v1.1.0 

func (node *AddressTrieNode) ContainingFirstIterator(forwardSubNodeOrder bool) CachingAddressTrieNodeIterator

ContainingFirstIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*AddressTrieNode) Contains added in v1.1.0 

func (node *AddressTrieNode) Contains(addr *Address) 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 (*AddressTrieNode) DescendingIterator added in v1.1.0 

func (node *AddressTrieNode) DescendingIterator() AddressIterator

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 (*AddressTrieNode) ElementContains added in v1.1.0 

func (node *AddressTrieNode) ElementContains(addr *Address) 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 (*AddressTrieNode) ElementsContainedBy added in v1.1.0 

func (node *AddressTrieNode) ElementsContainedBy(addr *Address) *AddressTrieNode

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 (*AddressTrieNode) ElementsContaining added in v1.1.0 

func (node *AddressTrieNode) ElementsContaining(addr *Address) *ContainmentPath

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 (*AddressTrieNode) Equal added in v1.1.0 

func (node *AddressTrieNode) Equal(other *AddressTrieNode) bool

Equal returns whether the address and and mapped value match those of the given node

func (*AddressTrieNode) FirstAddedNode added in v1.1.0 

func (node *AddressTrieNode) FirstAddedNode() *AddressTrieNode

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 tree or sub-trie

func (*AddressTrieNode) FirstNode added in v1.1.0 

func (node *AddressTrieNode) FirstNode() *AddressTrieNode

FirstNode returns the first (the lowest valued) node in the sub-trie originating from this node

func (*AddressTrieNode) FloorAddedNode added in v1.1.0 

func (node *AddressTrieNode) FloorAddedNode(addr *Address) *AddressTrieNode

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 (AddressTrieNode) Format added in v1.1.0 

func (node AddressTrieNode) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*AddressTrieNode) GetAddedNode added in v1.1.0 

func (node *AddressTrieNode) GetAddedNode(addr *Address) *AddressTrieNode

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 (*AddressTrieNode) GetKey added in v1.1.0 

func (node *AddressTrieNode) GetKey() *Address

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

func (*AddressTrieNode) GetLowerSubNode added in v1.1.0 

func (node *AddressTrieNode) GetLowerSubNode() *AddressTrieNode

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

func (*AddressTrieNode) GetNode added in v1.1.0 

func (node *AddressTrieNode) GetNode(addr *Address) *AddressTrieNode

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 (*AddressTrieNode) GetParent added in v1.1.0 

func (node *AddressTrieNode) GetParent() *AddressTrieNode

GetParent gets the node from which this node is a direct child node, or nil if this is the root.

func (*AddressTrieNode) GetUpperSubNode added in v1.1.0 

func (node *AddressTrieNode) GetUpperSubNode() *AddressTrieNode

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

func (*AddressTrieNode) HigherAddedNode added in v1.1.0 

func (node *AddressTrieNode) HigherAddedNode(addr *Address) *AddressTrieNode

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 (*AddressTrieNode) IsAdded added in v1.1.0 

func (node *AddressTrieNode) IsAdded() bool

IsAdded returns whether the node was "added". Some binary tree nodes are considered "added" and others are not. Those nodes created for key elements added to the tree 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 tree. 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 (*AddressTrieNode) IsEmpty added in v1.1.0 

func (node *AddressTrieNode) IsEmpty() bool

IsEmpty returns whether the size is 0

func (*AddressTrieNode) IsLeaf added in v1.1.0 

func (node *AddressTrieNode) 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 (*AddressTrieNode) IsRoot added in v1.1.0 

func (node *AddressTrieNode) IsRoot() bool

IsRoot returns whether this node is the root of the backing tree.

func (*AddressTrieNode) Iterator added in v1.1.0 

func (node *AddressTrieNode) Iterator() AddressIterator

Iterator returns an iterator that iterates through the elements of the sub-tree with this node as the root. The iteration is in sorted element order.

func (*AddressTrieNode) LastAddedNode added in v1.1.0 

func (node *AddressTrieNode) LastAddedNode() *AddressTrieNode

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 tree or sub-trie

func (*AddressTrieNode) LastNode added in v1.1.0 

func (node *AddressTrieNode) LastNode() *AddressTrieNode

LastNode returns the last (the highest valued) node in the sub-trie originating from this node

func (*AddressTrieNode) LongestPrefixMatch added in v1.1.0 

func (node *AddressTrieNode) LongestPrefixMatch(addr *Address) *Address

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 (*AddressTrieNode) LongestPrefixMatchNode added in v1.1.0 

func (node *AddressTrieNode) LongestPrefixMatchNode(addr *Address) *AddressTrieNode

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 (*AddressTrieNode) LowerAddedNode added in v1.1.0 

func (node *AddressTrieNode) LowerAddedNode(addr *Address) *AddressTrieNode

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 (*AddressTrieNode) NextAddedNode added in v1.1.0 

func (node *AddressTrieNode) NextAddedNode() *AddressTrieNode

NextAddedNode returns the next node in the tree that is an added node, following the tree order, or nil if there is no such node.

func (*AddressTrieNode) NextNode added in v1.1.0 

func (node *AddressTrieNode) NextNode() *AddressTrieNode

NextNode returns the node that follows this node following the tree order

func (*AddressTrieNode) NodeIterator added in v1.1.0 

func (node *AddressTrieNode) NodeIterator(forward bool) AddressTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes of the sub-tree with this node as the root, in forward or reverse tree order.

func (*AddressTrieNode) NodeSize added in v1.1.0 

func (node *AddressTrieNode) 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 (*AddressTrieNode) PreviousAddedNode added in v1.1.0 

func (node *AddressTrieNode) PreviousAddedNode() *AddressTrieNode

PreviousAddedNode returns the previous node in the tree that is an added node, following the tree order in reverse, or nil if there is no such node.

func (*AddressTrieNode) PreviousNode added in v1.1.0 

func (node *AddressTrieNode) PreviousNode() *AddressTrieNode

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

func (*AddressTrieNode) Remove added in v1.1.0 

func (node *AddressTrieNode) 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 (*AddressTrieNode) RemoveElementsContainedBy added in v1.1.0 

func (node *AddressTrieNode) RemoveElementsContainedBy(addr *Address) *AddressTrieNode

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 (*AddressTrieNode) RemoveNode added in v1.1.0 

func (node *AddressTrieNode) RemoveNode(addr *Address) 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.

func (*AddressTrieNode) SetAdded added in v1.1.0 

func (node *AddressTrieNode) SetAdded()

SetAdded makes this node an added node, which is equivalent to adding the corresponding key to the tree. 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 tree by calling Remove. A non-added node will only remain in the tree if it needs to in the tree.

func (*AddressTrieNode) Size added in v1.1.0 

func (node *AddressTrieNode) Size() int

Size returns the number of elements in the tree. Only nodes for which IsAdded returns true are counted. When zero is returned, IsEmpty returns true.

func (*AddressTrieNode) String added in v1.1.0 

func (node *AddressTrieNode) 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 (*AddressTrieNode) ToAssociative added in v1.1.0 

func (node *AddressTrieNode) ToAssociative() *AssociativeAddressTrieNode

ToAssociative converts to the associative trie node representation of this trie node. The node is unchanged, the returned node is the same underlying node.

func (*AddressTrieNode) ToIPv4 added in v1.1.0 

func (node *AddressTrieNode) ToIPv4() *IPv4AddressTrieNode

ToIPv4 converts to an IPv4AddressTrieNode if this node originated as an IPv4 address trie node. 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 (*AddressTrieNode) ToIPv4Associative added in v1.1.0 

func (node *AddressTrieNode) ToIPv4Associative() *IPv4AddressAssociativeTrieNode

ToIPv4Associative converts to an IPv4AddressAssociativeTrieNode if this node originated as an IPv4 address trie node. If not, ToIPv4Associative returns nil.

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

func (*AddressTrieNode) ToIPv6 added in v1.1.0 

func (node *AddressTrieNode) ToIPv6() *IPv6AddressTrieNode

ToIPv6 converts to an IPv6AddressTrieNode if this node originated as an IPv6 address trie node. 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 (*AddressTrieNode) ToIPv6Associative added in v1.1.0 

func (node *AddressTrieNode) ToIPv6Associative() *IPv6AddressAssociativeTrieNode

ToIPv6Associative converts to an IPv6AddressAssociativeTrieNode if this node originated as an IPv6 address trie node. If not, ToIPv6Associative returns nil.

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

func (*AddressTrieNode) ToMAC added in v1.1.0 

func (node *AddressTrieNode) ToMAC() *MACAddressTrieNode

ToMAC converts to a MACAddressTrieNode if this node originated as a MAC address trie node. 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 (*AddressTrieNode) ToMACAssociative added in v1.1.0 

func (node *AddressTrieNode) ToMACAssociative() *MACAddressAssociativeTrieNode

ToMACAssociative converts to a MACAddressAssociativeTrieNode if this node originated as a MAC address trie node. If not, ToMACAssociative returns nil.

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

func (*AddressTrieNode) TreeEqual added in v1.1.0 

func (node *AddressTrieNode) TreeEqual(other *AddressTrieNode) bool

TreeEqual returns whether the sub-tree represented by this node as the root node matches the given sub-tree

func (*AddressTrieNode) TreeString added in v1.1.0 

func (node *AddressTrieNode) TreeString(withNonAddedKeys, withSizes bool) string

TreeString returns a visual representation of the sub-tree 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-tree

type AddressTrieNodeIterator added in v1.1.0 

type AddressTrieNodeIterator interface {
	HasNext

	Next() *AddressTrieNode
}

AddressTrieNodeIterator iterates through an address trie, until both Next returns nil and HasNext returns false

type AddressTrieNodeIteratorRem added in v1.1.0 

type AddressTrieNodeIteratorRem interface {
	AddressTrieNodeIterator

	// Remove removes the last iterated element from the underlying trie, and returns that element.
	// If there is no such element, it returns nil.
	Remove() *AddressTrieNode
}

AddressTrieNodeIteratorRem iterates through an address trie, until both Next returns nil and HasNext returns false, and also allows you to remove the node just visited

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

	// CompareSize compares the counts of two subnets, the number of individual addresses within.
	//
	// Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one subnet represents more individual addresses than another.
	//
	// CompareSize returns a positive integer if this address has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.
	CompareSize(AddressType) int

	// 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. 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 AssociativeAddressTrie added in v1.1.0 

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

func (*AssociativeAddressTrie) Add added in v1.1.0 

func (trie *AssociativeAddressTrie) Add(addr *Address) bool

Add adds the address to this trie. Returns true if the address did not already exist in the trie.

func (*AssociativeAddressTrie) AddNode added in v1.1.0 

func (trie *AssociativeAddressTrie) AddNode(addr *Address) *AssociativeAddressTrieNode

AddNode adds the address key to this trie. The new or existing node for the address is returned.

func (*AssociativeAddressTrie) AddTrie added in v1.1.0 

func (trie *AssociativeAddressTrie) AddTrie(added *AssociativeAddressTrieNode) *AssociativeAddressTrieNode

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.

func (*AssociativeAddressTrie) AddedNodesTreeString added in v1.1.0 

func (trie *AssociativeAddressTrie) 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 (*AssociativeAddressTrie) AllNodeIterator added in v1.1.0 

func (trie *AssociativeAddressTrie) AllNodeIterator(forward bool) AssociativeAddressTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes in the trie in forward or reverse tree order.

func (*AssociativeAddressTrie) BlockSizeAllNodeIterator added in v1.1.0 

func (trie *AssociativeAddressTrie) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) AssociativeAddressTrieNodeIteratorRem

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 (*AssociativeAddressTrie) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (trie *AssociativeAddressTrie) BlockSizeCachingAllNodeIterator() CachingAssociativeAddressTrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from largest prefix blocks to smallest, and then to individual addresses.

func (*AssociativeAddressTrie) BlockSizeNodeIterator added in v1.1.0 

func (trie *AssociativeAddressTrie) BlockSizeNodeIterator(lowerSubNodeFirst bool) AssociativeAddressTrieNodeIteratorRem

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 (*AssociativeAddressTrie) CeilingAddedNode added in v1.1.0 

func (trie *AssociativeAddressTrie) CeilingAddedNode(addr *Address) *AssociativeAddressTrieNode

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 tree

func (*AssociativeAddressTrie) Clone added in v1.1.0 

func (trie *AssociativeAddressTrie) Clone() *AssociativeAddressTrie

Clone clones this trie

func (*AssociativeAddressTrie) ConstructAddedNodesTree added in v1.1.0 

func (trie *AssociativeAddressTrie) ConstructAddedNodesTree() *AssociativeAddressTrie

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. 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 (*AssociativeAddressTrie) ContainedFirstAllNodeIterator added in v1.1.0 

func (trie *AssociativeAddressTrie) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) AssociativeAddressTrieNodeIterator

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 (*AssociativeAddressTrie) ContainedFirstIterator added in v1.1.0 

func (trie *AssociativeAddressTrie) ContainedFirstIterator(forwardSubNodeOrder bool) AssociativeAddressTrieNodeIteratorRem

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 (*AssociativeAddressTrie) ContainingFirstAllNodeIterator added in v1.1.0 

func (trie *AssociativeAddressTrie) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingAssociativeAddressTrieNodeIterator

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 and linear space (proportional to tree size).

func (*AssociativeAddressTrie) ContainingFirstIterator added in v1.1.0 

func (trie *AssociativeAddressTrie) ContainingFirstIterator(forwardSubNodeOrder bool) CachingAssociativeAddressTrieNodeIterator

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 and linear space (proportional to tree size).

func (*AssociativeAddressTrie) Contains added in v1.1.0 

func (trie *AssociativeAddressTrie) Contains(addr *Address) 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 (*AssociativeAddressTrie) DeepEqual added in v1.1.0 

func (trie *AssociativeAddressTrie) DeepEqual(other *AssociativeAddressTrie) 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 (*AssociativeAddressTrie) DescendingIterator added in v1.1.0 

func (trie *AssociativeAddressTrie) DescendingIterator() AddressIterator

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 (*AssociativeAddressTrie) ElementContains added in v1.1.0 

func (trie *AssociativeAddressTrie) ElementContains(addr *Address) 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 (*AssociativeAddressTrie) ElementsContainedBy added in v1.1.0 

func (trie *AssociativeAddressTrie) ElementsContainedBy(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrie) ElementsContaining added in v1.1.0 

func (trie *AssociativeAddressTrie) ElementsContaining(addr *Address) *ContainmentPath

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 (*AssociativeAddressTrie) Equal added in v1.1.0 

func (trie *AssociativeAddressTrie) Equal(other *AssociativeAddressTrie) bool

Equal returns whether the given argument is a trie with a set of nodes with the same keys as in this trie

func (*AssociativeAddressTrie) FirstAddedNode added in v1.1.0 

func (trie *AssociativeAddressTrie) FirstAddedNode() *AssociativeAddressTrieNode

FirstAddedNode returns the first (lowest-valued) added node in the trie or nil if there are no added entries in this tree

func (*AssociativeAddressTrie) FirstNode added in v1.1.0 

func (trie *AssociativeAddressTrie) FirstNode() *AssociativeAddressTrieNode

FirstNode returns the first (lowest-valued) node in the trie or nil if the trie is empty

func (*AssociativeAddressTrie) FloorAddedNode added in v1.1.0 

func (trie *AssociativeAddressTrie) FloorAddedNode(addr *Address) *AssociativeAddressTrieNode

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 tree

func (AssociativeAddressTrie) Format added in v1.1.0 

func (trie AssociativeAddressTrie) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*AssociativeAddressTrie) Get added in v1.1.0 

func (trie *AssociativeAddressTrie) Get(addr *Address) NodeValue

Get gets the specified 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 (*AssociativeAddressTrie) GetAddedNode added in v1.1.0 

func (trie *AssociativeAddressTrie) GetAddedNode(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrie) GetNode added in v1.1.0 

func (trie *AssociativeAddressTrie) GetNode(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrie) GetRoot added in v1.1.0 

func (trie *AssociativeAddressTrie) GetRoot() *AssociativeAddressTrieNode

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 (*AssociativeAddressTrie) HigherAddedNode added in v1.1.0 

func (trie *AssociativeAddressTrie) HigherAddedNode(addr *Address) *AssociativeAddressTrieNode

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 tree

func (*AssociativeAddressTrie) IsEmpty added in v1.1.0 

func (trie *AssociativeAddressTrie) IsEmpty() bool

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

func (*AssociativeAddressTrie) Iterator added in v1.1.0 

func (trie *AssociativeAddressTrie) Iterator() AddressIterator

Iterator returns an iterator that iterates through the added addresses and prefix blocks in the trie. The iteration is in sorted element order.

func (*AssociativeAddressTrie) LastAddedNode added in v1.1.0 

func (trie *AssociativeAddressTrie) LastAddedNode() *AssociativeAddressTrieNode

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 tree

func (*AssociativeAddressTrie) LastNode added in v1.1.0 

func (trie *AssociativeAddressTrie) LastNode() *AssociativeAddressTrieNode

LastNode returns the last (highest-valued) node in the trie or nil if the trie is empty

func (*AssociativeAddressTrie) LongestPrefixMatch added in v1.1.0 

func (trie *AssociativeAddressTrie) LongestPrefixMatch(addr *Address) *Address

LongestPrefixMatch returns the address with the longest matching prefix compared to the provided address

func (*AssociativeAddressTrie) LongestPrefixMatchNode added in v1.1.0 

func (trie *AssociativeAddressTrie) LongestPrefixMatchNode(addr *Address) *AssociativeAddressTrieNode

LongestPrefixMatchNode returns the node of the address with the longest matching prefix compared to the provided address

func (*AssociativeAddressTrie) LowerAddedNode added in v1.1.0 

func (trie *AssociativeAddressTrie) LowerAddedNode(addr *Address) *AssociativeAddressTrieNode

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 tree

func (*AssociativeAddressTrie) NodeIterator added in v1.1.0 

func (trie *AssociativeAddressTrie) NodeIterator(forward bool) AssociativeAddressTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through all the added nodes in the trie in forward or reverse tree order.

func (*AssociativeAddressTrie) NodeSize added in v1.1.0 

func (trie *AssociativeAddressTrie) NodeSize() int

NodeSize returns the number of nodes in the tree, which is always more than the number of elements.

func (*AssociativeAddressTrie) Put added in v1.1.0 

func (trie *AssociativeAddressTrie) Put(addr *Address, value NodeValue) (bool, NodeValue)

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 (*AssociativeAddressTrie) PutNode added in v1.1.0 

func (trie *AssociativeAddressTrie) PutNode(addr *Address, value NodeValue) *AssociativeAddressTrieNode

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 tree 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 (*AssociativeAddressTrie) PutTrie added in v1.1.0 

func (trie *AssociativeAddressTrie) PutTrie(added *AssociativeAddressTrieNode) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrie) Remap added in v1.1.0 

func (trie *AssociativeAddressTrie) Remap(addr *Address, remapper func(NodeValue) NodeValue) *AssociativeAddressTrieNode

Remap remaps node values in the trie.

This will lookup the node corresponding to the given key. It will call the remapping function with the key as the first argument, regardless of whether the node is found or not.

If the node is not found, the value argument will be nil. If the node is found, the value argument will be the node's value, which can also be nil.

If the remapping function returns nil, then the matched node will be removed, if any. If it returns a non-nil value, then it will either set the existing node to have that value, or if there was no matched node, it will create a new node with that 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 value specifies changes to be made, then the trie will not be changed and a panic will ensue.

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 (*AssociativeAddressTrie) RemapIfAbsent added in v1.1.0 

func (trie *AssociativeAddressTrie) RemapIfAbsent(addr *Address, supplier func() NodeValue, insertNil bool) *AssociativeAddressTrieNode

RemapIfAbsent remaps node values in the trie, but only for nodes that do not exist or are mapped to nil.

This will look up the node corresponding to the given key. If the node is not found or mapped to nil, this will call the remapping function.

If the remapping function returns a non-nil value, then it will either set the existing node to have that value, or if there was no matched node, it will create a new node with that value. If the remapping function returns nil, then it will do the same if insertNil is true, otherwise it will do nothing.

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 value specifies changes to be made, then the trie will not be changed and ConcurrentModificationException will be thrown instead.

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.

insertNull indicates whether nil values returned from remapper should be inserted into the map, or whether nil values indicate no remapping

func (*AssociativeAddressTrie) Remove added in v1.1.0 

func (trie *AssociativeAddressTrie) Remove(addr *Address) 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.

func (*AssociativeAddressTrie) RemoveElementsContainedBy added in v1.1.0 

func (trie *AssociativeAddressTrie) RemoveElementsContainedBy(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrie) Size added in v1.1.0 

func (trie *AssociativeAddressTrie) 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 (*AssociativeAddressTrie) String added in v1.1.0 

func (trie *AssociativeAddressTrie) String() string

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

func (*AssociativeAddressTrie) ToBase added in v1.1.0 

func (trie *AssociativeAddressTrie) ToBase() *AddressTrie

func (*AssociativeAddressTrie) ToIPv4 added in v1.1.0 

func (trie *AssociativeAddressTrie) ToIPv4() *IPv4AddressAssociativeTrie

ToIPv4 converts this trie to an IPv4 associative trie. If this trie has no root, or the trie has an IPv4 root, the trie can be converted, otherwise, this method returns nil. The underlying trie does not change. The IPv4 type simply provides type safety, because you cannot mix different address versions or types in the same trie. Mixing versions and or types will cause a panic. Also, associative tries provide additional API to associate each node with a mapped value.

func (*AssociativeAddressTrie) TreeString added in v1.1.0 

func (trie *AssociativeAddressTrie) 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 AssociativeAddressTrieNode added in v1.1.0 

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

AssociativeAddressTrieNode represents a node of an associative compact binary prefix trie. The keys is a prefix block subnet or address. The node also has an associated value. Associative nodes can be converted to non-associative nodes and back again without losing their value.

func (*AssociativeAddressTrieNode) AllNodeIterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) AllNodeIterator(forward bool) AssociativeAddressTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes of the sub-tree with this node as the root, in forward or reverse tree order.

func (*AssociativeAddressTrieNode) AsNewTrie added in v1.1.0 

func (node *AssociativeAddressTrieNode) AsNewTrie() *AssociativeAddressTrie

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 (*AssociativeAddressTrieNode) BlockSizeAllNodeIterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) AssociativeAddressTrieNodeIteratorRem

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 (*AssociativeAddressTrieNode) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) BlockSizeCachingAllNodeIterator() CachingAssociativeAddressTrieNodeIterator

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 (*AssociativeAddressTrieNode) BlockSizeNodeIterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) BlockSizeNodeIterator(lowerSubNodeFirst bool) AssociativeAddressTrieNodeIteratorRem

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 (*AssociativeAddressTrieNode) CeilingAddedNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) CeilingAddedNode(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrieNode) Clear added in v1.1.0 

func (node *AssociativeAddressTrieNode) Clear()

Clear removes this node and all sub-nodes from the tree, after which isEmpty() will return true.

func (*AssociativeAddressTrieNode) ClearValue added in v1.1.0 

func (node *AssociativeAddressTrieNode) ClearValue()

ClearValue makes the value associated with this node the nil value

func (*AssociativeAddressTrieNode) Clone added in v1.1.0 

func (node *AssociativeAddressTrieNode) Clone() *AssociativeAddressTrieNode

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 (*AssociativeAddressTrieNode) CloneTree added in v1.1.0 

func (node *AssociativeAddressTrieNode) CloneTree() *AssociativeAddressTrieNode

CloneTree clones the sub-tree starting with this node as the root. The nodes are cloned, but their keys and values are not cloned.

func (*AssociativeAddressTrieNode) Compare added in v1.1.0 

func (node *AssociativeAddressTrieNode) Compare(other *AssociativeAddressTrieNode) int

Compare returns -1, 0 or 1 if this node is less than, equal, or greater than the other, according to the key and the trie order.

func (*AssociativeAddressTrieNode) ContainedFirstAllNodeIterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) AssociativeAddressTrieNodeIterator

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary tree 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 (*AssociativeAddressTrieNode) ContainedFirstIterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) ContainedFirstIterator(forwardSubNodeOrder bool) AssociativeAddressTrieNodeIteratorRem

ContainedFirstIterator returns an iterator that does a post-order binary tree 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 (*AssociativeAddressTrieNode) ContainingFirstAllNodeIterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingAssociativeAddressTrieNodeIterator

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*AssociativeAddressTrieNode) ContainingFirstIterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) ContainingFirstIterator(forwardSubNodeOrder bool) CachingAssociativeAddressTrieNodeIterator

ContainingFirstIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*AssociativeAddressTrieNode) Contains added in v1.1.0 

func (node *AssociativeAddressTrieNode) Contains(addr *Address) 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 (*AssociativeAddressTrieNode) DeepEqual added in v1.1.0 

func (node *AssociativeAddressTrieNode) DeepEqual(other *AssociativeAddressTrieNode) 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 (*AssociativeAddressTrieNode) DescendingIterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) DescendingIterator() AddressIterator

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 (*AssociativeAddressTrieNode) ElementContains added in v1.1.0 

func (node *AssociativeAddressTrieNode) ElementContains(addr *Address) 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 (*AssociativeAddressTrieNode) ElementsContainedBy added in v1.1.0 

func (node *AssociativeAddressTrieNode) ElementsContainedBy(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrieNode) ElementsContaining added in v1.1.0 

func (node *AssociativeAddressTrieNode) ElementsContaining(addr *Address) *ContainmentPath

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 (*AssociativeAddressTrieNode) Equal added in v1.1.0 

func (node *AssociativeAddressTrieNode) Equal(other *AssociativeAddressTrieNode) bool

Equal returns whether the key and and mapped value match those of the given node

func (*AssociativeAddressTrieNode) FirstAddedNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) FirstAddedNode() *AssociativeAddressTrieNode

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 tree or sub-trie

func (*AssociativeAddressTrieNode) FirstNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) FirstNode() *AssociativeAddressTrieNode

FirstNode returns the first (the lowest valued) node in the sub-trie originating from this node

func (*AssociativeAddressTrieNode) FloorAddedNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) FloorAddedNode(addr *Address) *AssociativeAddressTrieNode

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 (AssociativeAddressTrieNode) Format added in v1.1.0 

func (node AssociativeAddressTrieNode) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*AssociativeAddressTrieNode) Get added in v1.1.0 

func (node *AssociativeAddressTrieNode) Get(addr *Address) NodeValue

Get gets the specified 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 (*AssociativeAddressTrieNode) GetAddedNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) GetAddedNode(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrieNode) GetKey added in v1.1.0 

func (node *AssociativeAddressTrieNode) GetKey() *Address

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

func (*AssociativeAddressTrieNode) GetLowerSubNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) GetLowerSubNode() *AssociativeAddressTrieNode

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

func (*AssociativeAddressTrieNode) GetNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) GetNode(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrieNode) GetParent added in v1.1.0 

func (node *AssociativeAddressTrieNode) GetParent() *AssociativeAddressTrieNode

GetParent gets the node from which this node is a direct child node, or nil if this is the root.

func (*AssociativeAddressTrieNode) GetUpperSubNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) GetUpperSubNode() *AssociativeAddressTrieNode

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

func (*AssociativeAddressTrieNode) GetValue added in v1.1.0 

func (node *AssociativeAddressTrieNode) GetValue() NodeValue

GetValue sets the value associated with this node

func (*AssociativeAddressTrieNode) HigherAddedNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) HigherAddedNode(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrieNode) IsAdded added in v1.1.0 

func (node *AssociativeAddressTrieNode) IsAdded() bool

IsAdded returns whether the node was "added". Some binary tree nodes are considered "added" and others are not. Those nodes created for key elements added to the tree 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 tree. 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 (*AssociativeAddressTrieNode) IsEmpty added in v1.1.0 

func (node *AssociativeAddressTrieNode) IsEmpty() bool

IsEmpty returns whether the size is 0

func (*AssociativeAddressTrieNode) IsLeaf added in v1.1.0 

func (node *AssociativeAddressTrieNode) 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 (*AssociativeAddressTrieNode) IsRoot added in v1.1.0 

func (node *AssociativeAddressTrieNode) IsRoot() bool

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

func (*AssociativeAddressTrieNode) Iterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) Iterator() AddressIterator

Iterator returns an iterator that iterates through the elements of the sub-tree with this node as the root. The iteration is in sorted element order.

func (*AssociativeAddressTrieNode) LastAddedNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) LastAddedNode() *AssociativeAddressTrieNode

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 tree or sub-trie

func (*AssociativeAddressTrieNode) LastNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) LastNode() *AssociativeAddressTrieNode

LastNode returns the last (the highest valued) node in the sub-trie originating from this node

func (*AssociativeAddressTrieNode) LongestPrefixMatch added in v1.1.0 

func (node *AssociativeAddressTrieNode) LongestPrefixMatch(addr *Address) *Address

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 (*AssociativeAddressTrieNode) LongestPrefixMatchNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) LongestPrefixMatchNode(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrieNode) LowerAddedNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) LowerAddedNode(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrieNode) NextAddedNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) NextAddedNode() *AssociativeAddressTrieNode

NextAddedNode returns the first added node that follows this node following the tree order

func (*AssociativeAddressTrieNode) NextNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) NextNode() *AssociativeAddressTrieNode

NextNode returns the node that follows this node following the tree order

func (*AssociativeAddressTrieNode) NodeIterator added in v1.1.0 

func (node *AssociativeAddressTrieNode) NodeIterator(forward bool) AssociativeAddressTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes of the sub-tree with this node as the root, in forward or reverse tree order.

func (*AssociativeAddressTrieNode) NodeSize added in v1.1.0 

func (node *AssociativeAddressTrieNode) 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 (*AssociativeAddressTrieNode) PreviousAddedNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) PreviousAddedNode() *AssociativeAddressTrieNode

PreviousAddedNode returns the first added node that precedes this node following the tree order

func (*AssociativeAddressTrieNode) PreviousNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) PreviousNode() *AssociativeAddressTrieNode

PreviousNode returns the node that precedes this node following the tree order.

func (*AssociativeAddressTrieNode) Remove added in v1.1.0 

func (node *AssociativeAddressTrieNode) 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 (*AssociativeAddressTrieNode) RemoveElementsContainedBy added in v1.1.0 

func (node *AssociativeAddressTrieNode) RemoveElementsContainedBy(addr *Address) *AssociativeAddressTrieNode

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 (*AssociativeAddressTrieNode) RemoveNode added in v1.1.0 

func (node *AssociativeAddressTrieNode) RemoveNode(addr *Address) 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.

func (*AssociativeAddressTrieNode) SetAdded added in v1.1.0 

func (node *AssociativeAddressTrieNode) SetAdded()

SetAdded makes this node an added node, which is equivalent to adding the corresponding key to the tree. 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 tree by calling Remove. A non-added node will only remain in the tree if it needs to in the tree.

func (*AssociativeAddressTrieNode) SetValue added in v1.1.0 

func (node *AssociativeAddressTrieNode) SetValue(val NodeValue)

SetValue sets the value associated with this node

func (*AssociativeAddressTrieNode) Size added in v1.1.0 

func (node *AssociativeAddressTrieNode) Size() int

Size returns the number of elements in the tree. Only nodes for which IsAdded returns true are counted. When zero is returned, IsEmpty returns true.

func (*AssociativeAddressTrieNode) String added in v1.1.0 

func (node *AssociativeAddressTrieNode) 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 (*AssociativeAddressTrieNode) ToBase added in v1.1.0 

func (node *AssociativeAddressTrieNode) ToBase() *AddressTrieNode

ToBase converts to the polymorphic base representation of this associative trie node. The node is unchanged, the returned node is the same underlying node.

func (*AssociativeAddressTrieNode) ToIPv4 added in v1.1.0 

func (node *AssociativeAddressTrieNode) ToIPv4() *IPv4AddressAssociativeTrieNode

ToIPv4 converts to an IPv4AddressAssociativeTrieNode if this node originated as an IPv4 address trie node. 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 (*AssociativeAddressTrieNode) ToIPv6 added in v1.1.0 

func (node *AssociativeAddressTrieNode) ToIPv6() *IPv6AddressAssociativeTrieNode

ToIPv6 converts to an IPv6AddressAssociativeTrieNode if this node originated as an IPv6 address trie node. 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 (*AssociativeAddressTrieNode) ToMAC added in v1.1.0 

func (node *AssociativeAddressTrieNode) ToMAC() *MACAddressAssociativeTrieNode

ToMAC converts to a MACAddressAssociativeTrieNode if this node originated as a MAC address trie node. 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 (*AssociativeAddressTrieNode) TreeDeepEqual added in v1.1.0 

func (node *AssociativeAddressTrieNode) TreeDeepEqual(other *AssociativeAddressTrieNode) bool

TreeDeepEqual returns whether the sub-tree represented by this node as the root node matches the given sub-tree, matching with Compare on the keys and reflect.DeepEqual on the values

func (*AssociativeAddressTrieNode) TreeEqual added in v1.1.0 

func (node *AssociativeAddressTrieNode) TreeEqual(other *AssociativeAddressTrieNode) bool

TreeEqual returns whether the sub-tree represented by this node as the root node matches the given sub-tree

func (*AssociativeAddressTrieNode) TreeString added in v1.1.0 

func (node *AssociativeAddressTrieNode) TreeString(withNonAddedKeys, withSizes bool) string

TreeString returns a visual representation of the sub-tree 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-tree

type AssociativeAddressTrieNodeIterator added in v1.1.0 

type AssociativeAddressTrieNodeIterator interface {
	HasNext

	Next() *AssociativeAddressTrieNode
}

AssociativeAddressTrieNodeIterator iterates through an associative address trie, until both Next returns nil and HasNext returns false

type AssociativeAddressTrieNodeIteratorRem added in v1.1.0 

type AssociativeAddressTrieNodeIteratorRem interface {
	AssociativeAddressTrieNodeIterator

	// Remove removes the last iterated element from the underlying trie, and returns that element.
	// If there is no such element, it returns nil.
	Remove() *AssociativeAddressTrieNode
}

AssociativeAddressTrieNodeIteratorRem iterates through an associative address trie, until both Next returns nil and HasNext returns false. It also allows you to remove the last visited node.

type BigDivInt 

type BigDivInt = big.Int

BigDivInt is an unsigned integer type for unlimited size division values.

type BitCount 

type BitCount = int // using signed integers allows for easier arithmetic

A BitCount represents a count of bits in an address, section, grouping, segment, or division. Using signed integers allows for easier arithmetic, avoiding bugs. However, all methods adjust bit counts to match address size, so negative bit counts or bit counts larger than address size are meaningless.

type BitwiseOrer 

type BitwiseOrer interface {
	// GetMaskedLower provides the lowest masked value, which is not necessarily the lowest value masked
	GetOredLower(value, maskValue uint64) uint64

	// GetMaskedUpper provides the highest masked value, which is not necessarily the highest value masked
	GetOredUpper(upperValue, maskValue uint64) uint64

	// IsSequential returns whether masking all values in the range results in a sequential set of values
	IsSequential() bool
}

type CachingAddressTrieNodeIterator added in v1.1.0 

type CachingAddressTrieNodeIterator interface {
	AddressTrieNodeIteratorRem
	tree.CachingIterator
}

type CachingAssociativeAddressTrieNodeIterator added in v1.1.0 

type CachingAssociativeAddressTrieNodeIterator interface {
	AssociativeAddressTrieNodeIteratorRem
	tree.CachingIterator
}

type CachingIPv4AssociativeTrieNodeIterator added in v1.1.0 

type CachingIPv4AssociativeTrieNodeIterator interface {
	IPv4AssociativeTrieNodeIteratorRem
	tree.CachingIterator
}

type CachingIPv4TrieNodeIterator added in v1.1.0 

type CachingIPv4TrieNodeIterator interface {
	IPv4TrieNodeIteratorRem
	tree.CachingIterator
}

type CachingIPv6AssociativeTrieNodeIterator added in v1.1.0 

type CachingIPv6AssociativeTrieNodeIterator interface {
	IPv6AssociativeTrieNodeIteratorRem
	tree.CachingIterator
}

type CachingIPv6TrieNodeIterator added in v1.1.0 

type CachingIPv6TrieNodeIterator interface {
	IPv6TrieNodeIteratorRem
	tree.CachingIterator
}

type CachingMACAssociativeTrieNodeIterator added in v1.1.0 

type CachingMACAssociativeTrieNodeIterator interface {
	MACAssociativeTrieNodeIteratorRem
	tree.CachingIterator
}

type CachingMACTrieNodeIterator added in v1.1.0 

type CachingMACTrieNodeIterator interface {
	MACTrieNodeIteratorRem
	tree.CachingIterator
}

type ContainmentPath added in v1.2.0 

type ContainmentPath 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) Count added in v1.2.0 

func (path *ContainmentPath) 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) LongestPrefixMatch added in v1.2.0 

func (path *ContainmentPath) LongestPrefixMatch() *ContainmentPathNode

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) ShortestPrefixMatch added in v1.2.0 

func (path *ContainmentPath) ShortestPrefixMatch() *ContainmentPathNode

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) String added in v1.2.0 

func (path *ContainmentPath) String() string

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

type ContainmentPathNode added in v1.2.0 

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

ContainmentPathNode is a node in a ContainmentPath

func (*ContainmentPathNode) Count added in v1.2.0 

func (node *ContainmentPathNode) 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) GetKey added in v1.2.0 

func (node *ContainmentPathNode) GetKey() *Address

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

func (*ContainmentPathNode) GetValue added in v1.2.0 

func (node *ContainmentPathNode) GetValue() NodeValue

GetValue returns the value assigned to the block or address, if the node was an associative node from an associative trie, otherwise it returns nil

func (*ContainmentPathNode) ListString added in v1.2.0 

func (node *ContainmentPathNode) ListString() string

ListString returns a visual representation of the containing subnets starting from this node and moving downwards to sub-nodes.

func (*ContainmentPathNode) Next added in v1.2.0 

func (node *ContainmentPathNode) Next() *ContainmentPathNode

Previous gets the node contained by this node

func (*ContainmentPathNode) Previous added in v1.2.0 

func (node *ContainmentPathNode) Previous() *ContainmentPathNode

Previous gets the node containing this node

func (*ContainmentPathNode) String added in v1.2.0 

func (node *ContainmentPathNode) 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 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 (DefaultAddressConverter) IsIPv4Convertible(address *IPAddress) bool

IsIPv4Convertible returns true if ToIPv4 returns non-nil

func (DefaultAddressConverter) IsIPv6Convertible 

func (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 (DefaultAddressConverter) ToIPv6(address *IPAddress) *IPv6Address

ToIPv6 converts to an IPv4-mapped IPv6 address or returns the original address if IPv6 already.

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

	// 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 prefix lengths for which ContainsPrefixBlock returns true.

type ExtendedIPSegmentSeries 

type ExtendedIPSegmentSeries interface {
	IPAddressSegmentSeries

	// Unwrap returns the wrapped IP address or IP address aection 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

	// CompareSize compares the counts of two address series, the number of individual series represented in each.
	//
	// Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one series represents more individual address series than another.
	//
	// CompareSize returns a positive integer if this address series has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.
	CompareSize(ExtendedIPSegmentSeries) int

	// 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 index larger than the segment count.
	GetSegment(index int) *IPAddressSegment

	// GetSegments returns a slice with the address segments.  The returned slice is not backed by the same array as this section.
	GetSegments() []*IPAddressSegment

	// CopySegments copies the existing segments into the given slice,
	// as much as can be fit into the slice, returning the number of segments copied
	CopySegments(segs []*IPAddressSegment) (count int)

	// CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index,
	// into the given slice, as much as can be fit into the slice, returning the number of segments copied
	CopySubSegments(start, end int, segs []*IPAddressSegment) (count int)

	// IsIPv4 returns true if this series originated as an IPv4 series.  If so, use ToIPv4 to convert back to the IPv4-specific type.
	IsIPv4() bool

	// IsIPv6 returns true if this series originated as an IPv6 series.  If so, use ToIPv6 to convert back to the IPv6-specific type.
	IsIPv6() bool

	// ToIPv4 converts to an IPv4AddressSegmentSeries if this series originated as an IPv4 series.
	// If not, ToIPv4 returns nil.
	//
	// ToIPv4 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToIPv4() IPv4AddressSegmentSeries

	// ToIPv6 converts to an IPv4AddressSegmentSeries if this series originated as an IPv6 series.
	// If not, ToIPv6 returns nil.
	//
	// ToIPv6 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToIPv6() IPv6AddressSegmentSeries

	// ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value,
	// and changing the following segments to be full-range.
	ToBlock(segmentIndex int, lower, upper SegInt) ExtendedIPSegmentSeries

	// ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values.
	// The series will be the block of all series with the same prefix.
	//
	// If this series has no prefix, this series is returned.
	ToPrefixBlock() ExtendedIPSegmentSeries

	// ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values.
	// The returned series will be the block of all series with the same prefix.
	ToPrefixBlockLen(BitCount) ExtendedIPSegmentSeries

	// ToZeroHostLen converts the series to one in which all individual series have a host of zero,
	// the host being the bits following the given prefix length.
	// If this series has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.
	//
	// This returns an error if the series is a range which cannot be converted to a range in which all series have zero hosts,
	// because the conversion results in a segment that is not a sequential range of values.
	ToZeroHostLen(BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ToZeroHost converts the series to one in which all individual series have a host of zero,
	// the host being the bits following the prefix length.
	// If the series has no prefix length, then it returns an all-zero series.
	//
	// The returned series will have the same prefix length.
	//
	// For instance, the zero host of 1.2.3.4/16 is the individual address 1.2.0.0/16.
	//
	// This returns an error if the series is a range which cannot be converted to a range in which all individual elements have zero hosts,
	// because the conversion results in a series segment that is not a sequential range of values.
	ToZeroHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ToMaxHostLen converts the series to one in which all individual series have a host of all one-bits, the max host,
	// the host being the bits following the given prefix length.
	// If this series has the same prefix length, then the resulting series will too, otherwise the resulting series will have no prefix length.
	//
	// For instance, the zero host of 1.2.3.4 for the prefix length 16 is the address 1.2.255.255.
	//
	// This returns an error if the series is a range which cannot be converted to a range in which all individual elements have max hosts,
	// because the conversion results in a series segment that is not a sequential range of values.
	ToMaxHostLen(BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ToMaxHost converts the series to one in which all individual series have a host of all one-bits, the max value,
	// the host being the bits following the prefix length.
	// If the series has no prefix length, then it returns an all-ones series, the max series.
	//
	// The returned series will have the same prefix length.
	//
	// For instance, the max host of 1.2.3.4/16 gives the broadcast address 1.2.255.255/16.
	//
	// This returns an error if the series is a range which cannot be converted to a range in which all individual elements have max hosts,
	// because the conversion results in a series segment that is not a sequential range of values.
	ToMaxHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ToZeroNetwork converts the series to one in which all individual addresses or address sections have a network of zero,
	// the network being the bits within the prefix length.
	// If the series has no prefix length, then it returns an all-zero series.
	//
	// The returned series will have the same prefix length.
	ToZeroNetwork() ExtendedIPSegmentSeries

	// Increment returns the item that is the given increment upwards into the range,
	// with the increment of 0 returning the first in the range.
	//
	// If the increment i matches or exceeds the range count c, then i - c + 1
	// is added to the upper item of the range.
	// An increment matching the count gives you the item just above the highest in the range.
	//
	// If the increment is negative, it is added to the lowest of the range.
	// To get the item just below the lowest of the range, use the increment -1.
	//
	// If this represents just a single value, the item is simply incremented by the given increment, positive or negative.
	//
	// If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond.
	// For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on.
	// An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator.
	// For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.
	//
	// On overflow or underflow, Increment returns nil.
	Increment(int64) ExtendedIPSegmentSeries

	// IncrementBoundary returns the item that is the given increment from the range boundaries of this item.
	//
	// If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item.
	// If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item.
	// If the increment is zero, returns this.
	//
	// If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.
	//
	// On overflow or underflow, IncrementBoundary returns nil.
	IncrementBoundary(int64) ExtendedIPSegmentSeries

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

	// GetUpper returns the series in the range with the highest numeric value,
	// which will be the same series if it represents a single value.
	// For example, for "1.2-3.4.5-6", the series "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() ExtendedIPSegmentSeriesIterator

	// 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() ExtendedIPSegmentSeriesIterator

	// 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() ExtendedIPSegmentSeriesIterator

	// 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() ExtendedIPSegmentSeriesIterator

	// 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) ExtendedIPSegmentSeriesIterator

	// SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual series as this address series.
	SpanWithPrefixBlocks() []ExtendedIPSegmentSeries

	// SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of individual series as this series.
	//
	// This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.
	SpanWithSequentialBlocks() []ExtendedIPSegmentSeries

	// CoverWithPrefixBlock returns the minimal-size prefix block that covers all the values in this series.
	// The resulting block will have a larger series count than this, unless this series is already a prefix block.
	CoverWithPrefixBlock() ExtendedIPSegmentSeries

	// AdjustPrefixLen increases or decreases the prefix length by the given increment.
	//
	// A prefix length will not be adjusted lower than zero or beyond the bit length of the series.
	//
	// If this series has no prefix length, then the prefix length will be set to the adjustment if positive,
	// or it will be set to the adjustment added to the bit count if negative.
	AdjustPrefixLen(BitCount) ExtendedIPSegmentSeries

	// AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.
	//
	// A prefix length will not be adjusted lower than zero or beyond the bit length of the series.
	//
	// If this series has no prefix length, then the prefix length will be set to the adjustment if positive,
	// or it will be set to the adjustment added to the bit count if negative.
	//
	// When prefix length is increased, the bits moved within the prefix become zero.
	// When a prefix length is decreased, the bits moved outside the prefix become zero.
	//
	// If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.
	AdjustPrefixLenZeroed(BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// SetPrefixLen sets the prefix length.
	//
	// A prefix length will not be set to a value lower than zero or beyond the bit length of the series.
	// The provided prefix length will be adjusted to these boundaries if necessary.
	SetPrefixLen(BitCount) ExtendedIPSegmentSeries

	// SetPrefixLenZeroed sets the prefix length.
	//
	// A prefix length will not be set to a value lower than zero or beyond the bit length of the series.
	// The provided prefix length will be adjusted to these boundaries if necessary.
	//
	// If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero.
	// If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.
	//
	// In other words, bits that move from one side of the prefix length to the other (ie bits moved into the prefix or outside the prefix) are zeroed.
	//
	// If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.
	SetPrefixLenZeroed(BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// WithoutPrefixLen provides the same address series but with no prefix length.  The values remain unchanged.
	WithoutPrefixLen() ExtendedIPSegmentSeries

	// ReverseBytes returns a new segment series with the bytes reversed.  Any prefix length is dropped.
	//
	// If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range,
	// and reversing the segment values results in a range that is not contiguous, then this returns an error.
	//
	// In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.
	ReverseBytes() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ReverseBits returns a new segment series with the bits reversed.  Any prefix length is dropped.
	//
	// If the bits within a single segment cannot be reversed because the segment represents a range,
	// and reversing the segment values results in a range that is not contiguous, this returns an error.
	//
	// In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.
	//
	// If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.
	ReverseBits(perByte bool) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

	// ReverseSegments returns a new series with the segments reversed.
	ReverseSegments() ExtendedIPSegmentSeries

	// ToCustomString creates a customized string from this series according to the given string option parameters
	ToCustomString(stringOptions addrstr.IPStringOptions) string
}

ExtendedIPSegmentSeries wraps either an IPAddress or IPAddressSection. ExtendedIPSegmentSeries can be used to write code that works with both IP addresses and IP address sections, going further than IPAddressSegmentSeries to offer additional methods, methods with the series types in their signature.

type ExtendedIPSegmentSeriesIterator 

type ExtendedIPSegmentSeriesIterator interface {
	HasNext

	// Next returns the next IP section or IP address, or nil if there is none left
	Next() ExtendedIPSegmentSeries
}

ExtendedIPSegmentSeriesIterator iterates through either IP addresses or IP address sections

type ExtendedIdentifierString 

type ExtendedIdentifierString interface {
	HostIdentifierString

	// GetAddress returns the identified address or nil if none
	GetAddress() AddressType

	// ToAddress returns the identified address or an error
	ToAddress() (AddressType, error)

	// Unwrap returns the wrapped IPAddressString, MACAddressString or HostName as an interface, HostIdentifierString
	Unwrap() HostIdentifierString
}

ExtendedIdentifierString is a common interface for strings that identify hosts, namely IPAddressString, MACAddressString, and HostName

type ExtendedMasker 

type ExtendedMasker interface {
	Masker

	GetExtendedMaskedLower(extendedValue, extendedMaskValue uint64) uint64

	GetExtendedMaskedUpper(extendedUpperValue, extendedMaskValue uint64) uint64
}

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

	// CompareSize compares the counts of two address series, the number of individual series represented in each.
	//
	// Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one series represents more individual address series than another.
	//
	// CompareSize returns a positive integer if this address series has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.
	CompareSize(ExtendedSegmentSeries) int

	// 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 index 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() ExtendedSegmentSeriesIterator

	// 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() ExtendedSegmentSeriesIterator

	// 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() ExtendedSegmentSeriesIterator

	// AdjustPrefixLen increases or decreases the prefix length by the given increment.
	//
	// A prefix length will not be adjusted lower than zero or beyond the bit length of the series.
	//
	// If this series has no prefix length, then the prefix length will be set to the adjustment if positive,
	// or it will be set to the adjustment added to the bit count if negative.
	AdjustPrefixLen(BitCount) ExtendedSegmentSeries

	// AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.
	//
	// A prefix length will not be adjusted lower than zero or beyond the bit length of the series.
	//
	// If this series has no prefix length, then the prefix length will be set to the adjustment if positive,
	// or it will be set to the adjustment added to the bit count if negative.
	//
	// When prefix length is increased, the bits moved within the prefix become zero.
	// When a prefix length is decreased, the bits moved outside the prefix become zero.
	AdjustPrefixLenZeroed(BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

	// SetPrefixLen sets the prefix length.
	//
	// A prefix length will not be set to a value lower than zero or beyond the bit length of the series.
	// The provided prefix length will be adjusted to these boundaries if necessary.
	SetPrefixLen(BitCount) ExtendedSegmentSeries

	// SetPrefixLenZeroed sets the prefix length.
	//
	// A prefix length will not be set to a value lower than zero or beyond the bit length of the series.
	// The provided prefix length will be adjusted to these boundaries if necessary.
	//
	// If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero.
	// If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.
	//
	// In other words, bits that move from one side of the prefix length to the other (ie bits moved into the prefix or outside the prefix) are zeroed.
	//
	// If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.
	SetPrefixLenZeroed(BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

	// WithoutPrefixLen provides the same address series but with no prefix length.  The values remain unchanged.
	WithoutPrefixLen() ExtendedSegmentSeries

	// ReverseBytes returns a new segment series with the bytes reversed.  Any prefix length is dropped.
	//
	// If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range,
	// and reversing the segment values results in a range that is not contiguous, then this returns an error.
	//
	// In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.
	ReverseBytes() (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

	// ReverseBits returns a new segment series with the bits reversed.  Any prefix length is dropped.
	//
	// If the bits within a single segment cannot be reversed because the segment represents a range,
	// and reversing the segment values results in a range that is not contiguous, this returns an error.
	//
	// In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.
	ReverseBits(perByte bool) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

	// ReverseSegments returns a new series with the segments reversed.
	ReverseSegments() ExtendedSegmentSeries

	// ToCustomString creates a customized string from this series according to the given string option parameters
	ToCustomString(stringOptions addrstr.StringOptions) string
}

ExtendedSegmentSeries wraps either an Address or AddressSection. ExtendedSegmentSeries can be used to write code that works with both addresses and address sections, going further than AddressSegmentSeries to offer additional methods with the series types in their signature.

type ExtendedSegmentSeriesIterator 

type ExtendedSegmentSeriesIterator interface {
	HasNext

	// Next returns the next section or address, or nil if there is none left
	Next() ExtendedSegmentSeries
}

ExtendedSegmentSeriesIterator iterates through either addresses or address sections

type HasNext 

type HasNext interface {
	// HasNext returns true if there is another address to iterate, false otherwise
	HasNext() bool
}

HasNext is a component of all interfaces, defining the HasNext interface method

type HostIdentifierString 

type HostIdentifierString interface {

	// ToNormalizedString provides a normalized String representation for the host identified by this HostIdentifierString instance
	ToNormalizedString() string

	// IsValid returns whether the wrapped string is a valid identifier for a host
	IsValid() bool

	Wrap() ExtendedIdentifierString

	fmt.Stringer
}

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, 2181, 952, 1035, 1034, 1123, 5890 or the list of rfcs for IPAddress. For IPv6 addresses in host, see rfc 2732 specifying [] notation and 3986 and 4038 (combining IPv6 [] with prefix or zone) and SMTP rfc 2821 for alternative uses of [] 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 int) *HostName

NewHostNameFromAddrPort constructs a HostName from an IP address and a port.

func NewHostNameFromNetIP 

func NewHostNameFromNetIP(bytes net.IP) (hostName *HostName, err addrerr.AddressValueError)

NewHostNameFromNetIP constructs a HostName from a net.IP.

func NewHostNameFromNetIPAddr 

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

NewHostNameFromNetIPAddr constructs a HostName from a net.IPAddr.

func NewHostNameFromNetTCPAddr 

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

NewHostNameFromNetTCPAddr constructs a HostName from a net.TCPAddr.

func NewHostNameFromNetUDPAddr 

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

NewHostNameFromNetUDPAddr constructs a HostName from a net.UDPAddr.

func NewHostNameFromPrefixedNetIP 

func NewHostNameFromPrefixedNetIP(bytes net.IP, prefixLen PrefixLen) (hostName *HostName, err addrerr.AddressValueError)

NewHostNameFromPrefixedNetIP constructs a HostName from a net.IP paired with a prefix length.

func NewHostNameFromPrefixedNetIPAddr 

func NewHostNameFromPrefixedNetIPAddr(addr *net.IPAddr, prefixLen PrefixLen) (hostName *HostName, err addrerr.AddressValueError)

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

func NewHostNameParams 

func NewHostNameParams(str string, params addrstrparam.HostNameParams) *HostName

NewHostNameParams constructs a HostName that will parse the given string according to the given parameters

func (*HostName) AsAddress 

func (host *HostName) AsAddress() *IPAddress

AsAddress returns the address if this host name represents an ip address. Otherwise, this returns nil. Note that the translation includes prefix lengths and IPv6 zones.

This does not resolve addresses or return resolved addresses. Call ToAddress or GetAddress to get the resolved address.

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

func (host *HostName) GetAddress() *IPAddress

GetAddress attempts to convert this host name to an IP address. If this represents an ip address, returns that address. If this represents a host, returns the resolved ip address of that host. Otherwise, returns nil. GetAddress is similar to ToAddress but does not return any errors.

If you wish to get the represented address while avoiding DNS resolution, use AsAddress or AsAddressString

func (*HostName) GetHost 

func (host *HostName) GetHost() string

GetHost returns the host string normalized but without port, service, prefix or mask.

If an address, returns the address string normalized, but without port, service, prefix, mask, or brackets for IPv6.

To get a normalized string encompassing all details, use toNormalizedString()

If not a valid host, returns the zero string

func (*HostName) GetMask 

func (host *HostName) GetMask() *IPAddress

GetMask returns the resulting mask value if a mask was provided with this host name.

func (*HostName) GetNetworkPrefixLen 

func (host *HostName) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, if a prefix length was supplied, either as part of an address or as part of a domain (in which case the prefix applies to any resolved address). Otherwise, GetNetworkPrefixLen returns nil.

func (*HostName) GetNormalizedLabels 

func (host *HostName) GetNormalizedLabels() []string

GetNormalizedLabels returns an array of normalized strings for this host name instance.

If this represents an IP address, the address segments are separated into the returned array. If this represents a host name string, the domain name segments are separated into the returned array, with the top-level domain name (right-most segment) as the last array element.

The individual segment strings are normalized in the same way as ToNormalizedString.

Ports, service name strings, prefix lengths, and masks are all omitted from the returned array.

func (*HostName) GetPort 

func (host *HostName) GetPort() Port

GetPort returns the port if a port was supplied, otherwise it returns nil

func (*HostName) GetService 

func (host *HostName) GetService() string

GetService returns the service name if a service name was supplied (which is typically mapped to a port), otherwise it returns an empty string

func (*HostName) GetValidationOptions 

func (host *HostName) GetValidationOptions() addrstrparam.HostNameParams

GetValidationOptions returns the validation options supplied when constructing the HostName, or the default validation options if none were supplied.

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] (aka [0:0:0:0:0:0:0:1]) or 127.0.0.1

Also see isSelf()

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

func (host *HostName) IsValid() bool

IsValid returns whether this represents a valid host name or IP address format.

func (*HostName) ResolvesToSelf 

func (host *HostName) ResolvesToSelf() bool

ResolvesToSelf returns whether this represents, or resolves to, a host or address representing the same host.

func (*HostName) String 

func (host *HostName) String() string

String implements the fmt.Stringer interface, returning the original string used to create this HostName (altered by strings.TrimSpace if a host name and not an address), or "<nil>" if the receiver is a nil pointer

func (*HostName) ToAddress 

func (host *HostName) ToAddress() (addr *IPAddress, err addrerr.AddressError)

ToAddress resolves to an address. This method can potentially return a list of resolved addresses and an error as well, if some resolved addresses were invalid.

func (*HostName) ToAddresses 

func (host *HostName) ToAddresses() (addrs []*IPAddress, err addrerr.AddressError)

ToAddresses resolves to one or more addresses. The error can be addrerr.AddressStringError,addrerr.IncompatibleAddressError, or addrerr.HostNameError. This method can potentially return a list of resolved addresses and an error as well if some resolved addresses were invalid.

func (*HostName) ToNetIP 

func (host *HostName) ToNetIP() net.IP

ToNetIP is similar to ToAddress but returns the resulting address as a net.IP

func (*HostName) ToNetIPAddr 

func (host *HostName) ToNetIPAddr() *net.IPAddr

ToNetIPAddr is similar to ToAddress but returns the resulting address as a net.IPAddr

func (*HostName) ToNetTCPAddr 

func (host *HostName) ToNetTCPAddr() *net.TCPAddr

ToNetTCPAddr returns the TCPAddr if this HostName both resolves to an address and has an associated port. Otherwise, it returns nil.

func (*HostName) ToNetTCPAddrService 

func (host *HostName) ToNetTCPAddrService(serviceMapper func(string) Port) *net.TCPAddr

ToNetTCPAddrService returns the TCPAddr if this HostName both resolves to an address and has an associated service or port, otherwise returns nil

func (*HostName) ToNetUDPAddr 

func (host *HostName) ToNetUDPAddr(serviceMapper func(string) Port) *net.UDPAddr

ToNetUDPAddr returns the UDPAddr if this HostName both resolves to an address and has an associated port

func (*HostName) ToNetUDPAddrService 

func (host *HostName) ToNetUDPAddrService(serviceMapper func(string) Port) *net.UDPAddr

ToNetUDPAddrService returns the UDPAddr if this HostName both resolves to an address and has an associated service or port

func (*HostName) ToNormalizedString 

func (host *HostName) ToNormalizedString() string

ToNormalizedString provides a normalized string which is lowercase for host strings, and which is the normalized string for addresses.

func (*HostName) ToNormalizedWildcardString 

func (host *HostName) ToNormalizedWildcardString() string

ToNormalizedWildcardString provides a normalized string which is lowercase for host strings, and which is a normalized string for addresses.

func (*HostName) ToQualifiedString 

func (host *HostName) ToQualifiedString() string

ToQualifiedString provides a normalized string which is lowercase for host strings, and which is a normalized string for addresses.

func (*HostName) Validate 

func (host *HostName) Validate() addrerr.HostNameError

Validate validates that this string is a valid address, and if not, throws an exception with a descriptive message indicating why it is not.

func (*HostName) Wrap 

func (host *HostName) Wrap() ExtendedIdentifierString

Wrap wraps this host name, returning a WrappedHostName, an implementation of ExtendedIdentifierString, which can be used to write code that works with a host identifier string including IPAddressString, MACAddressString, and HostName.

type IPAddress 

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

IPAddress represents an IP address or subnet, either IPv4 or IPv6 (except for the zero-IPAddress which is neither). An IP address is composed of range-valued segments and can optionally have an associated prefix length. The zero value IPAddress has no segments, neither IPv4 nor IPv6, which is not compatible with zero value for IPv4 or IPv6, those being 0.0.0.0 and :: respectively.

func NewIPAddressFromBytes added in v1.2.0 

func NewIPAddressFromBytes(ip net.IP) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromBytes constructs an address from a slice of bytes. An error is returned when the IP has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromNetIP 

func NewIPAddressFromNetIP(ip net.IP) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromNetIP constructs an address from a net.IP. An error is returned when the IP has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromNetIPAddr 

func NewIPAddressFromNetIPAddr(addr *net.IPAddr) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromNetIPAddr constructs an address or subnet from a net.IPAddr. An error is returned when the IP has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromNetIPMask 

func NewIPAddressFromNetIPMask(ip net.IPMask) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromNetIPMask constructs an address from a net.IPMask. An error is returned when the mask has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromNetIPNet 

func NewIPAddressFromNetIPNet(ipnet *net.IPNet) (*IPAddress, addrerr.AddressError)

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

func NewIPAddressFromPrefixedNetIP 

func NewIPAddressFromPrefixedNetIP(ip net.IP, prefixLength PrefixLen) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromPrefixedNetIP constructs an address or subnet from a net.IP with a prefix length. An error is returned when the IP has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromPrefixedNetIPAddr 

func NewIPAddressFromPrefixedNetIPAddr(addr *net.IPAddr, prefixLength PrefixLen) (*IPAddress, addrerr.AddressValueError)

NewIPAddressFromPrefixedNetIPAddr constructs an address or subnet from a net.IPAddr with a prefix length. An error is returned when the IP has an invalid number of bytes. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated.

func NewIPAddressFromPrefixedSegments 

func NewIPAddressFromPrefixedSegments(segs []*IPAddressSegment, prefixLength PrefixLen) (res *IPAddress, err addrerr.AddressValueError)

NewIPAddressFromPrefixedSegments constructs an address from the given segments and prefix length. If the segments are not consistently IPv4 or IPv6, or if there is not the correct number of segments for the IP version (4 for IPv4, 8 for IPv6), then an error is returned.

func NewIPAddressFromPrefixedVals 

func NewIPAddressFromPrefixedVals(version IPVersion, lowerValueProvider, upperValueProvider SegmentValueProvider, prefixLength PrefixLen) *IPAddress

NewIPAddressFromPrefixedVals constructs an IPAddress from the provided segment values and prefix length. If the given version is indeterminate, then nil is returned. The prefix length is adjusted to 0 if negative or to the bit count if larger.

func NewIPAddressFromPrefixedZonedVals 

func NewIPAddressFromPrefixedZonedVals(version IPVersion, lowerValueProvider, upperValueProvider SegmentValueProvider, prefixLength PrefixLen, zone string) *IPAddress

NewIPAddressFromPrefixedZonedVals constructs an IPAddress from the provided segment values, prefix length, and zone. If the given version is indeterminate, then nil is returned. If the version is IPv4, then the zone is ignored. The prefix length is adjusted to 0 if negative or to the bit count if larger.

func NewIPAddressFromSegs added in v1.2.0 

func NewIPAddressFromSegs(segments []*IPAddressSegment) (res *IPAddress, err addrerr.AddressValueError)

NewIPAddressFromSegs constructs an address from the given segments. If the segments are not consistently IPv4 or IPv6, or if there is not the correct number of segments for the IP version (4 for IPv4, 8 for IPv6), then an error is returned.

func NewIPAddressFromVals 

func NewIPAddressFromVals(version IPVersion, lowerValueProvider SegmentValueProvider) *IPAddress

NewIPAddressFromVals constructs an IPAddress from the provided segment values. If the given version is indeterminate, then nil is returned.

func NewIPAddressFromValueProvider 

func NewIPAddressFromValueProvider(valueProvider IPAddressValueProvider) *IPAddress

NewIPAddressFromValueProvider constructs an IPAddress from the provided segment values, prefix length, and zone, all of which are supplied by the implementation of IPAddressValueProvider. If the given version is indeterminate, then nil is returned. If the version is IPv4, then the zone is ignored. The prefix length is adjusted to 0 if negative or to the bit count if larger.

func (*IPAddress) AdjustPrefixLen 

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

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

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

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

func (*IPAddress) AdjustPrefixLenZeroed 

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

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

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

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

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

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

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

func (*IPAddress) AssignMinPrefixForBlock 

func (addr *IPAddress) AssignMinPrefixForBlock() *IPAddress

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

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

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

func (*IPAddress) AssignPrefixForSingleBlock 

func (addr *IPAddress) AssignPrefixForSingleBlock() *IPAddress

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

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

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

func (*IPAddress) BitwiseOr 

func (addr *IPAddress) BitwiseOr(other *IPAddress) (masked *IPAddress, err addrerr.IncompatibleAddressError)

BitwiseOr does the bitwise disjunction with this address or subnet, useful when subnetting. It is similar to Mask which does the bitwise conjunction.

The operation is applied to all individual addresses and the result is returned.

If the given address is a different version than this, then an error is returned.

If this is a subnet representing multiple addresses, and applying the operations to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned

func (*IPAddress) BlockIterator 

func (addr *IPAddress) BlockIterator(segmentCount int) IPAddressIterator

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, given the count argument 2, it will iterate through 1.3.5-6.7, 1.4.5-6.7, 2.3.5-6.7, 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 AddressType) int

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

Rather than calculating counts with GetCount, there can be more efficient ways of comparing 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, 0 if they are the same, or a negative integer if the other has a larger count.

func (*IPAddress) Contains 

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

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

func (*IPAddress) ContainsPrefixBlock 

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

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

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

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

func (*IPAddress) ContainsSinglePrefixBlock 

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

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

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

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

func (*IPAddress) CopyBytes 

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

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

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

func (*IPAddress) CopyNetIP 

func (addr *IPAddress) CopyNetIP(ip net.IP) net.IP

CopyNetIP copies the value of the lowest individual address in the subnet into a net.IP.

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

func (*IPAddress) CopySegments 

func (addr *IPAddress) CopySegments(segs []*IPAddressSegment) (count int)

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

func (*IPAddress) CopySubSegments 

func (addr *IPAddress) CopySubSegments(start, end int, segs []*IPAddressSegment) (count int)

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

func (*IPAddress) CopyUpperBytes 

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

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

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

func (*IPAddress) CopyUpperNetIP 

func (addr *IPAddress) CopyUpperNetIP(ip net.IP) net.IP

CopyUpperNetIP copies the value of the highest individual address in the subnet into a net.IP.

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

func (*IPAddress) CoverWithPrefixBlock 

func (addr *IPAddress) CoverWithPrefixBlock() *IPAddress

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the addresses in this subnet. The resulting block will have a larger subnet size than this, unless this subnet is already a prefix block.

func (*IPAddress) CoverWithPrefixBlockTo 

func (addr *IPAddress) CoverWithPrefixBlockTo(other *IPAddress) *IPAddress

CoverWithPrefixBlockTo returns the minimal-size prefix block that covers all the addresses spanning from this subnet to the given subnet.

If the argument is not the same IP version as the receiver, the argument is ignored, and the result is the same as CoverWithPrefixBlock.

func (*IPAddress) Equal 

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

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

func (*IPAddress) ForEachSegment added in v1.2.0 

func (addr *IPAddress) ForEachSegment(consumer func(segmentIndex int, segment *IPAddressSegment) (stop bool)) int

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

func (IPAddress) Format 

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

Format implements fmt.Formatter interface. It accepts the formats 'v' for the default address and section format (either the normalized or canonical string), 's' (string) for the same, 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix), 'd' (decimal), 'x' (lowercase hexadecimal), and 'X' (uppercase hexadecimal). Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which is leading zero for octal and for hexadecimal, 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 1s in the network section and then all 0s in the host section. A CIDR host mask is an address with all 0s in the network section and then all 1s 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

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 "1.2-3.4.5-6", the series "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) 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 null 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 index 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 "1.2-3.4.5-6", the series "1.3.4.6" is returned. GetUpperIPAddress implements the IPAddressRange interface, and is equivalent to GetUpper()

func (*IPAddress) GetUpperNetIP 

func (addr *IPAddress) GetUpperNetIP() net.IP

GetUpperNetIP returns the highest address in this subnet or address as a net.IP

func (*IPAddress) GetUpperNetIPAddr added in v1.2.0 

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

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

func (*IPAddress) 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] (aka [0:0:0:0:0:0:0: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 < 0, 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 prefix lengths 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 return false for this method and returns true for 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() IPAddressIterator

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

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

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

func (*IPAddress) Mask 

func (addr *IPAddress) Mask(other *IPAddress) (masked *IPAddress, err addrerr.IncompatibleAddressError)

Mask applies the given mask to all addresses represented by this IPAddress. The mask is applied to all individual addresses.

If the mask is a different version than this, then an error is returned.

If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned

func (*IPAddress) MatchesWithMask 

func (addr *IPAddress) MatchesWithMask(other *IPAddress, mask *IPAddress) bool

MatchesWithMask applies the mask to this address and then compares the result with the given address, returning true if they match, false otherwise.

func (*IPAddress) MergeToPrefixBlocks 

func (addr *IPAddress) MergeToPrefixBlocks(addrs ...*IPAddress) []*IPAddress

MergeToPrefixBlocks merges this subnet with the list of subnets to produce the smallest array of prefix blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block. Arguments that are not the same IP version are ignored.

func (*IPAddress) MergeToSequentialBlocks 

func (addr *IPAddress) MergeToSequentialBlocks(addrs ...*IPAddress) []*IPAddress

MergeToSequentialBlocks merges this with the list of addresses to produce the smallest array of sequential blocks

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block. Arguments that are not the same IP version are ignored.

func (*IPAddress) PrefixBlockIterator 

func (addr *IPAddress) PrefixBlockIterator() IPAddressIterator

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() IPAddressIterator

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

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

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

func (*IPAddress) ReverseBits 

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

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

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

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

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

func (*IPAddress) ReverseBytes 

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

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

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

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

func (*IPAddress) ReverseSegments 

func (addr *IPAddress) ReverseSegments() *IPAddress

ReverseSegments returns a new address with the segments reversed.

func (*IPAddress) SequentialBlockIterator 

func (addr *IPAddress) SequentialBlockIterator() IPAddressIterator

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, 2.4.6.7-8.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPAddress) SetPrefixLen 

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

SetPrefixLen sets the prefix length.

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

func (*IPAddress) SetPrefixLenZeroed 

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

SetPrefixLenZeroed sets the prefix length.

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

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

In other words, bits that move from one side of the prefix length to the other (ie 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) *IPAddressSeqRange

SpanWithRange returns an IPAddressSeqRange instance that spans this subnet to the given subnet. If the other address is a different version than this, then the other is ignored, and the result is equivalent to calling ToSequentialRange

func (*IPAddress) SpanWithSequentialBlocks 

func (addr *IPAddress) SpanWithSequentialBlocks() []*IPAddress

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of addresses as this subnet.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

Unlike SpanWithSequentialBlocksTo, this method only includes addresses that are a part of this subnet.

func (*IPAddress) SpanWithSequentialBlocksTo 

func (addr *IPAddress) SpanWithSequentialBlocksTo(other *IPAddress) []*IPAddress

SpanWithSequentialBlocksTo produces the smallest slice of sequential block subnets that span all values from this subnet to the given subnet. The span will cover all addresses in both subnets and everything in between.

Individual block subnets come in the form 1-3.1-4.5.6-8, however that particular subnet is not sequential since address 1.1.5.8 is in the subnet, the next sequential address 1.1.5.9 is not in the subnet, and a higher address 1.2.5.6 is in the subnet. Blocks are sequential when the first segment with a range of values is followed by segments that span all values.

If the other address is a different version than this, then this is equivalent to calling SpanWithSequentialBlocks on this subnet.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPAddress) String 

func (addr *IPAddress) String() string

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

func (*IPAddress) Subtract 

func (addr *IPAddress) Subtract(other *IPAddress) []*IPAddress

Subtract subtracts the given subnet from this subnet, returning an array of subnets for the result (the subnets will not be contiguous so an array is required). Subtract computes the subnet difference, the set of addresses in this address subnet but not in the provided subnet. This is also known as the relative complement of the given argument in this subnet. This is set subtraction, not subtraction of address values (use Increment for the latter). We have a subnet of addresses and we are removing those addresses found in the argument subnet. If there are no remaining addresses, nil is returned.

func (*IPAddress) TestBit 

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

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

func (*IPAddress) ToAddressBase 

func (addr *IPAddress) ToAddressBase() *Address

ToAddressBase converts to an Address, a polymorphic type usable with all addresses and subnets. Afterwards, you can convert back with ToIP.

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

func (*IPAddress) ToAddressString 

func (addr *IPAddress) ToAddressString() *IPAddressString

ToAddressString retrieves or generates an IPAddressString instance for this IPAddress instance. This may be the IPAddressString this instance was generated from, if it was generated from an IPAddressString.

In general, users are intended to create IPAddress instances from IPAddressString instances, while the reverse direction is generally not common and not useful, except under specific circumstances.

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

func (*IPAddress) ToBinaryString 

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

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

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

func (*IPAddress) ToBlock 

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

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

func (*IPAddress) ToCanonicalHostName 

func (addr *IPAddress) ToCanonicalHostName() (*HostName, error)

ToCanonicalHostName does a reverse name lookup to get the canonical host name. Note that the canonical host name may differ on different systems.

This returns an error if this address is a subnet multiple values.

func (*IPAddress) ToCanonicalString 

func (addr *IPAddress) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address.

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

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

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

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

func (*IPAddress) ToCanonicalWildcardString 

func (addr *IPAddress) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string and avoids the CIDR prefix length. Addresses and subnets with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. IPv6 addresses will be compressed according to the canonical representation. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPAddress) ToCompressedString 

func (addr *IPAddress) ToCompressedString() string

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

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

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

func (*IPAddress) ToCompressedWildcardString 

func (addr *IPAddress) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, avoiding the CIDR prefix, but with full IPv6 segment compression as well, including single zero-segments. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPAddress) ToCustomString 

func (addr *IPAddress) ToCustomString(stringOptions addrstr.IPStringOptions) string

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

func (*IPAddress) ToFullString 

func (addr *IPAddress) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 4 characters for IPv6 segments and 3 characters for IPv4 segments.

func (*IPAddress) ToHexString 

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

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

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

func (*IPAddress) ToHostName 

func (addr *IPAddress) ToHostName() *HostName

ToHostName returns the HostName used to resolve, if this address was resolved from a host. Otherwise, if this address represents a subnet of multiple addresses, returns a HostName for that subnet. Otherwise, it does a reverse name lookup to obtain the proper HostName.

func (*IPAddress) ToIP 

func (addr *IPAddress) ToIP() *IPAddress

ToIP is an identity method.

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

func (*IPAddress) ToIPv4 

func (addr *IPAddress) ToIPv4() *IPv4Address

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

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

func (*IPAddress) ToIPv6 

func (addr *IPAddress) ToIPv6() *IPv6Address

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

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

func (*IPAddress) ToKey added in v1.1.0 

func (addr *IPAddress) ToKey() *IPAddressKey

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

func (*IPAddress) ToMaxHost 

func (addr *IPAddress) ToMaxHost() (*IPAddress, addrerr.IncompatibleAddressError)

ToMaxHost converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-ones address, the max address.

The returned address or subnet will have the same prefix and prefix length.

For instance, the max host of 1.2.3.4/16 gives the broadcast address 1.2.255.255/16.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPAddress) ToMaxHostLen 

func (addr *IPAddress) ToMaxHostLen(prefixLength BitCount) (*IPAddress, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the resulting one will too, otherwise the resulting address or subnet will have no prefix length.

For instance, the zero host of 1.2.3.4 for the prefix length 16 is the address 1.2.255.255.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPAddress) ToNormalizedString 

func (addr *IPAddress) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

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

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

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

func (*IPAddress) ToNormalizedWildcardString 

func (addr *IPAddress) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPAddress) ToOctalString 

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

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

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

func (*IPAddress) ToPrefixBlock 

func (addr *IPAddress) ToPrefixBlock() *IPAddress

ToPrefixBlock returns the subnet associated with the prefix length of this address. If this address has no prefix length, this address is returned.

The subnet will include all addresses with the same prefix as this one, the prefix "block". The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is 1.2.3.4/16 it returns the subnet 1.2.0.0/16 which can also be written as 1.2.*.*/16

func (*IPAddress) ToPrefixBlockLen 

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

ToPrefixBlockLen returns the subnet associated with the given prefix length.

The subnet will include all addresses with the same prefix as this one, the prefix "block" for that prefix length. The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is 1.2.3.4 and the prefix length provided is 16, it returns the subnet 1.2.0.0/16 which can also be written as 1.2.*.*/16

func (*IPAddress) ToPrefixLenString 

func (addr *IPAddress) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, a zero host section will be compressed with ::. For IPv4 the string is equivalent to the canonical string.

func (*IPAddress) ToReverseDNSString 

func (addr *IPAddress) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse DNS lookup string, returning an error if this address is an IPv6 multiple-valued subnet for which the range cannot be represented. For 8.255.4.4 it is 4.4.255.8.in-addr.arpa For 2001:db8::567:89ab it is b.a.9.8.7.6.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa

func (*IPAddress) ToSQLWildcardString 

func (addr *IPAddress) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the wildcard '_'..

func (*IPAddress) ToSegmentedBinaryString 

func (addr *IPAddress) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this IP address segment series as segments of binary values preceded by the "0b" prefix.

func (*IPAddress) ToSequentialRange 

func (addr *IPAddress) ToSequentialRange() *IPAddressSeqRange

ToSequentialRange creates a sequential range instance from the lowest and highest addresses in this subnet

The two will represent the same set of individual addresses if and only if IsSequential is true. To get a series of ranges that represent the same set of individual addresses use the SequentialBlockIterator (or PrefixIterator), and apply this method to each iterated subnet.

If this represents just a single address then the returned instance covers just that single address as well.

func (*IPAddress) ToSinglePrefixBlockOrAddress added in v1.1.0 

func (addr *IPAddress) ToSinglePrefixBlockOrAddress() *IPAddress

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

func (*IPAddress) ToSubnetString 

func (addr *IPAddress) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like 1.2.*.* or 1:2::/16

In the case of IPv4, this means that wildcards are used instead of a network prefix when a network prefix has been supplied. In the case of IPv6, when a network prefix has been supplied, the prefix will be shown and the host section will be compressed with ::.

func (*IPAddress) ToZeroHost 

func (addr *IPAddress) ToZeroHost() (*IPAddress, addrerr.IncompatibleAddressError)

ToZeroHost converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix and prefix length.

For instance, the zero host of 1.2.3.4/16 is the individual address 1.2.0.0/16.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPAddress) ToZeroHostLen 

func (addr *IPAddress) ToZeroHostLen(prefixLength BitCount) (*IPAddress, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.

For instance, the zero host of 1.2.3.4 for the prefix length 16 is the address 1.2.0.0.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPAddress) ToZeroNetwork 

func (addr *IPAddress) ToZeroNetwork() *IPAddress

ToZeroNetwork converts the address or subnet to one in which all individual addresses have a network of zero, the network being the bits within the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix length.

func (*IPAddress) TrieCompare added in v1.1.0 

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

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

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

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

func (*IPAddress) TrieDecrement added in v1.1.0 

func (addr *IPAddress) TrieDecrement() *IPAddress

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

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

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

func (*IPAddress) TrieIncrement added in v1.1.0 

func (addr *IPAddress) TrieIncrement() *IPAddress

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

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

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

func (*IPAddress) UpperBytes 

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

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

func (*IPAddress) WithoutPrefixLen 

func (addr *IPAddress) WithoutPrefixLen() *IPAddress

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

func (*IPAddress) Wrap 

func (addr *IPAddress) Wrap() WrappedIPAddress

Wrap wraps this IP address, returning a WrappedIPAddress, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address.

func (*IPAddress) WrapAddress added in v1.2.0 

func (addr *IPAddress) WrapAddress() WrappedAddress

WrapAddress wraps this IP address, returning a WrappedAddress, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapAddress can be called with a nil receiver, wrapping a nil address.

type IPAddressActionAdapter added in v1.1.0 

type IPAddressActionAdapter struct {
	Adapted func(*Address)
}

IPAddressActionAdapter has methods to supply IP, IPv4, and IPv6 addresses to a wrapped consumer function that takes Address arguments

func (IPAddressActionAdapter) IPAction added in v1.2.0 

func (a IPAddressActionAdapter) IPAction(addr *IPAddress)

IPAction calls the wrapped consumer function with the given IP address as the argument

func (IPAddressActionAdapter) IPv4Action added in v1.2.0 

func (a IPAddressActionAdapter) IPv4Action(addr *IPv4Address)

IPv4Action calls the wrapped consumer function with the given IPv4 address as the argument

func (IPAddressActionAdapter) IPv6Action added in v1.2.0 

func (a IPAddressActionAdapter) IPv6Action(addr *IPv6Address)

IPv6Action calls the wrapped consumer function with the given IPv6 address as the argument

type IPAddressConverter 

type IPAddressConverter interface {
	IPv4AddressConverter

	IPv6AddressConverter

	// returns whether the address is IPv4 or can be converted to IPv4.  If true, ToIPv4(IPAddress) returns non-nil.
	IsIPv4Convertible(address *IPAddress) bool

	// returns whether the address is IPv6 or can be converted to IPv6.  If true, ToIPv6(IPAddress) returns non-nil.
	IsIPv6Convertible(address *IPAddress) bool
}

IPAddressConverter converts IP addresses to either IPv4 or IPv6

type IPAddressCreator 

type IPAddressCreator struct {
	IPVersion
}

IPAddressCreator is a polymporphic type providing constructor methods to construct IP addresses corresponding to its contained IP version

func (IPAddressCreator) CreatePrefixSegment 

func (creator IPAddressCreator) CreatePrefixSegment(value SegInt, segmentPrefixLength PrefixLen) *IPAddressSegment

CreatePrefixSegment creates an IPv4 or IPv6 segment with a prefix length depending on the IP version assigned to this IPAddressCreator instance. If the IP version is indeterminate, then nil is returned.

func (IPAddressCreator) CreateRangeSegment 

func (creator IPAddressCreator) CreateRangeSegment(lower, upper SegInt) *IPAddressSegment

CreateRangeSegment creates an IPv4 or IPv6 range-valued segment depending on the IP version assigned to this IPAddressCreator instance. If the IP version is indeterminate, then nil is returned.

func (IPAddressCreator) CreateSegment 

func (creator IPAddressCreator) CreateSegment(lower, upper SegInt, segmentPrefixLength PrefixLen) *IPAddressSegment

CreateSegment creates an IPv4 or IPv6 segment depending on the IP version assigned to this IPAddressCreator instance. If the IP version is indeterminate, then nil is returned.

func (IPAddressCreator) NewIPAddressFromPrefixedVals 

func (creator IPAddressCreator) NewIPAddressFromPrefixedVals(lowerValueProvider, upperValueProvider SegmentValueProvider, prefixLength PrefixLen) *IPAddress

NewIPAddressFromPrefixedVals constructs an IPAddress from the provided segment values and prefix length. If the IP version of this IPAddressCreator is indeterminate, then nil is returned. The prefix length is adjusted to 0 if negative or to the bit count if larger.

func (IPAddressCreator) NewIPAddressFromPrefixedZonedVals 

func (creator IPAddressCreator) NewIPAddressFromPrefixedZonedVals(lowerValueProvider, upperValueProvider SegmentValueProvider, prefixLength PrefixLen, zone string) *IPAddress

NewIPAddressFromPrefixedZonedVals constructs an IPAddress from the provided segment values, prefix length, and zone. If the IP version of this IPAddressCreator is indeterminate, then nil is returned. If the version is IPv4, then the zone is ignored. The prefix length is adjusted to 0 if negative or to the bit count if larger.

func (IPAddressCreator) NewIPAddressFromVals 

func (creator IPAddressCreator) NewIPAddressFromVals(lowerValueProvider SegmentValueProvider) *IPAddress

NewIPAddressFromVals constructs an IPAddress from the provided segment values. If the IP version of this IPAddressCreator is indeterminate, then nil is returned.

func (IPAddressCreator) NewIPSectionFromBytes 

func (creator IPAddressCreator) NewIPSectionFromBytes(bytes []byte) *IPAddressSection

NewIPSectionFromBytes creates an address section from the given bytes, It is IPv4 or IPv6 depending on the IP version assigned to this IPAddressCreator instance. The number of segments is determined by the length of the byte array. If the IP version is indeterminate, then nil is returned.

func (IPAddressCreator) NewIPSectionFromPrefixedBytes 

func (creator IPAddressCreator) NewIPSectionFromPrefixedBytes(bytes []byte, segmentCount int, prefLen PrefixLen) (*IPAddressSection, addrerr.AddressValueError)

NewIPSectionFromPrefixedBytes creates an address section from the given bytes and prefix length. It is IPv4 or IPv6 depending on the IP version assigned to this IPAddressCreator instance. The number of segments is given. An error is returned when the byte slice has too many bytes to match the segment count. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated. If the IP version is indeterminate, then nil is returned.

func (IPAddressCreator) NewIPSectionFromSegmentedBytes added in v1.2.0 

func (creator IPAddressCreator) NewIPSectionFromSegmentedBytes(bytes []byte, segmentCount int) (*IPAddressSection, addrerr.AddressValueError)

NewIPSectionFromSegmentedBytes creates an address section from the given bytes. It is IPv4 or IPv6 depending on the IP version assigned to this IPAddressCreator instance. The number of segments is given. An error is returned when the byte slice has too many bytes to match the segment count. IPv4 should have 4 bytes or less, IPv6 16 bytes or less, although extra leading zeros are tolerated. If the IP version is indeterminate, then nil is returned.

type IPAddressIterator 

type IPAddressIterator interface {
	HasNext

	// Next returns the next IP address, or nil if there is none left.
	Next() *IPAddress
}

IPAddressIterator iterates through IP subnets and ranges

func NewFilteredIPAddrIterator 

func NewFilteredIPAddrIterator(iter IPAddressIterator, skip func(*IPAddress) bool) IPAddressIterator

NewFilteredIPAddrIterator returns an iterator similar to the passed in iterator, but skipping those elements for which the "skip" function returns true

type IPAddressKey added in v1.1.1 

type IPAddressKey struct {
	AddressKey
}

IPAddressKey is a representation of IPAddress that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators It can be used as a map key. The zero value is a zero-length address.

func (*IPAddressKey) ToIP added in v1.1.1 

func (key *IPAddressKey) ToIP() *IPAddress

ToIP converts to an IP address instance

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 IPAddressPredicateAdapter added in v1.1.0 

type IPAddressPredicateAdapter struct {
	Adapted func(*Address) bool
}

IPAddressPredicateAdapter has methods to supply IP, IPv4, and IPv6 addresses to a wrapped predicate function that takes Address arguments

func (IPAddressPredicateAdapter) IPPredicate added in v1.1.0 

func (a IPAddressPredicateAdapter) IPPredicate(addr *IPAddress) bool

IPPredicate calls the wrapped predicate function with the given IP address as the argument

func (IPAddressPredicateAdapter) IPv4Predicate added in v1.1.0 

func (a IPAddressPredicateAdapter) IPv4Predicate(addr *IPv4Address) bool

IPv4Predicate calls the wrapped predicate function with the given IPv4 address as the argument

func (IPAddressPredicateAdapter) IPv6Predicate added in v1.1.0 

func (a IPAddressPredicateAdapter) IPv6Predicate(addr *IPv6Address) bool

IPv6Predicate calls the wrapped predicate function with the given IPv6 address as the argument

type IPAddressRange 

type IPAddressRange interface {
	AddressItem

	// IsSequential returns whether the address item represents a range of addresses that are sequential.
	//
	// IP Address sequential ranges are sequential by definition.
	//
	// Generally, for a subnet this means that any segment covering a range of values must be followed by segments that are full range, covering all values.
	//
	// Individual addresses are sequential and CIDR prefix blocks are sequential.
	// The subnet 1.2.3-4.5 is not sequential, since the two addresses it represents, 1.2.3.5 and 1.2.4.5, are not (1.2.3.6 is in-between the two but not in the subnet).
	IsSequential() bool
	// contains filtered or unexported methods
}

IPAddressRange represents all IPAddress instances and all IPAddress sequential range instances

type IPAddressSection 

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

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

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

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

Most operations that can be performed on IPAddress instances can also be performed on IPAddressSection instances and vice-versa.

func (*IPAddressSection) AdjustPrefixLen 

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

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

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

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

func (*IPAddressSection) AdjustPrefixLenZeroed 

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

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

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

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

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

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

func (*IPAddressSection) AssignMinPrefixForBlock 

func (section *IPAddressSection) AssignMinPrefixForBlock() *IPAddressSection

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

In other words, this method assigns a prefix length to this address section matching the largest prefix block in this address section.

func (*IPAddressSection) AssignPrefixForSingleBlock 

func (section *IPAddressSection) AssignPrefixForSingleBlock() *IPAddressSection

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address section. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address section - it is required that the range of values match the range of a prefix block. If there is no such address section, then nil is returned.

func (*IPAddressSection) BlockIterator 

func (section *IPAddressSection) BlockIterator(segmentCount int) IPSectionIterator

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 StandardDivGroupingType) 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 comparing 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, 0 if they are the same, or a negative integer if the other has a larger count.

func (*IPAddressSection) Contains 

func (section *IPAddressSection) Contains(other AddressSectionType) bool

Contains returns whether this is same type and version as the given address section and whether it contains all values in the given section.

Sections must also have the same number of segments to be comparable, otherwise false is returned.

func (*IPAddressSection) ContainsPrefixBlock 

func (section *IPAddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPAddressSection) ContainsSinglePrefixBlock 

func (section *IPAddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this section contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPAddressSection) CopyBytes 

func (section *IPAddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddressSection) CopySegments 

func (section *IPAddressSection) CopySegments(segs []*IPAddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*IPAddressSection) CopySubSegments 

func (section *IPAddressSection) CopySubSegments(start, end int, segs []*IPAddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*IPAddressSection) CopyUpperBytes 

func (section *IPAddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddressSection) CoverWithPrefixBlock 

func (section *IPAddressSection) CoverWithPrefixBlock() *IPAddressSection

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the individual address sections in this section. The resulting block will have a larger count than this, unless this section is already a prefix block.

func (*IPAddressSection) Equal 

func (section *IPAddressSection) Equal(other AddressSectionType) bool

Equal returns whether the given address section is equal to this address section. Two address sections are equal if they represent the same set of sections. They must match:

  • type/version: IPv4, IPv6
  • segment counts
  • segment value ranges

Prefix lengths are ignored.

func (*IPAddressSection) ForEachSegment added in v1.2.0 

func (section *IPAddressSection) ForEachSegment(consumer func(segmentIndex int, segment *IPAddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true Returns the number of visited segments.

func (*IPAddressSection) GetBitCount 

func (section *IPAddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item

func (*IPAddressSection) GetBitsPerSegment 

func (section *IPAddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (*IPAddressSection) GetBlockCount 

func (section *IPAddressSection) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*IPAddressSection) GetBlockMaskPrefixLen 

func (section *IPAddressSection) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address section is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address section with all 1s in the network section and then all 0s in the host section. A CIDR host mask is an address section with all 0s in the network section and then all 1s 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

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.

func (*IPAddressSection) GetIPVersion 

func (section *IPAddressSection) GetIPVersion() IPVersion

GetIPVersion returns the IP version of this IP address section

func (*IPAddressSection) GetLower 

func (section *IPAddressSection) GetLower() *IPAddressSection

GetLower returns the section in the range with the lowest numeric value, which will be the same section if it represents a single value. For example, for "1.2-3.4.5-6", the section "1.2.4.5" is returned.

func (*IPAddressSection) GetMaxSegmentValue 

func (section *IPAddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPAddressSection) GetMinPrefixLenForBlock 

func (section *IPAddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (*IPAddressSection) GetNetworkMask 

func (section *IPAddressSection) GetNetworkMask() *IPAddressSection

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address section. If this section has no prefix length, then the all-ones mask is returned.

func (*IPAddressSection) GetNetworkPrefixLen 

func (section *IPAddressSection) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. It is equivalent to GetPrefixLen.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (*IPAddressSection) GetNetworkSection 

func (section *IPAddressSection) GetNetworkSection() *IPAddressSection

GetNetworkSection returns a subsection containing the segments with the network bits of the address section. The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.

If this series has no CIDR prefix length, the returned network section will be the entire series as a prefixed section with prefix length matching the address bit length.

func (*IPAddressSection) GetNetworkSectionLen 

func (section *IPAddressSection) GetNetworkSectionLen(prefLen BitCount) *IPAddressSection

GetNetworkSectionLen returns a subsection containing the segments with the network of the address section, the prefix bits according to the given prefix length. The returned section will have only as many segments as needed to contain the network.

The new section will be assigned the given prefix length, unless the existing prefix length is smaller, in which case the existing prefix length will be retained.

func (*IPAddressSection) GetPrefixCount 

func (section *IPAddressSection) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, 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 index larger than the segment count.

func (*IPAddressSection) GetSegmentCount 

func (section *IPAddressSection) GetSegmentCount() int

func (*IPAddressSection) GetSegmentStrings 

func (section *IPAddressSection) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*IPAddressSection) GetSegments 

func (section *IPAddressSection) GetSegments() (res []*IPAddressSegment)

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*IPAddressSection) GetSequentialBlockCount 

func (section *IPAddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section

func (*IPAddressSection) GetSequentialBlockIndex 

func (section *IPAddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (*IPAddressSection) GetSubSection 

func (section *IPAddressSection) GetSubSection(index, endIndex int) *IPAddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex The first segment is at index 0.

func (*IPAddressSection) GetTrailingSection 

func (section *IPAddressSection) GetTrailingSection(index int) *IPAddressSection

GetTrailingSection gets the subsection from the series starting from the given index The first segment is at index 0.

func (*IPAddressSection) GetUpper 

func (section *IPAddressSection) GetUpper() *IPAddressSection

GetUpper returns the section in the range with the highest numeric value, which will be the same section if it represents a single value. For example, for "1.2-3.4.5-6", the section "1.3.4.6" is returned.

func (*IPAddressSection) GetUpperValue 

func (section *IPAddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value

func (*IPAddressSection) GetValue 

func (section *IPAddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value

func (*IPAddressSection) IncludesMax 

func (section *IPAddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range

func (*IPAddressSection) IncludesMaxHost 

func (section *IPAddressSection) IncludesMaxHost() bool

IncludesMaxHost returns whether the address section contains an individual address section with a host of all one-bits. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are one.

func (*IPAddressSection) IncludesMaxHostLen 

func (section *IPAddressSection) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the address section contains an individual address section with a host of all one-bits, an address section for which all bits past the given prefix length are all ones.

func (*IPAddressSection) IncludesZero 

func (section *IPAddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range

func (*IPAddressSection) IncludesZeroHost 

func (section *IPAddressSection) IncludesZeroHost() bool

IncludesZeroHost returns whether the address section contains an individual address section with a host of zero. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are zero.

func (*IPAddressSection) IncludesZeroHostLen 

func (section *IPAddressSection) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the address section contains an individual section with a host of zero, a section for which all bits past the given prefix length are zero.

func (*IPAddressSection) Increment 

func (section *IPAddressSection) Increment(increment int64) *IPAddressSection

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (*IPAddressSection) IncrementBoundary 

func (section *IPAddressSection) IncrementBoundary(increment int64) *IPAddressSection

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (*IPAddressSection) IsAdaptiveZero 

func (section *IPAddressSection) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the section was originally created as an implicitly zero-valued section (eg 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, etc 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 (*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 < 0, or if it is larger than the bit count of this item.

func (*IPAddressSection) IsPrefixBlock 

func (section *IPAddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length or a prefix length that differs from prefix lengths for which ContainsPrefixBlock returns true.

func (*IPAddressSection) IsPrefixed 

func (section *IPAddressSection) IsPrefixed() bool

IsPrefixed returns whether this section has an associated prefix length

func (*IPAddressSection) IsSequential 

func (section *IPAddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (*IPAddressSection) IsSingleNetwork 

func (section *IPAddressSection) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address section.

func (*IPAddressSection) IsSinglePrefixBlock 

func (section *IPAddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock() except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPAddressSection) IsZero 

func (section *IPAddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero

func (*IPAddressSection) IsZeroHost 

func (section *IPAddressSection) IsZeroHost() bool

IsZeroHost returns whether this section has a prefix length and if so, whether the host section is always zero for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (*IPAddressSection) IsZeroHostLen 

func (section *IPAddressSection) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual sections in this address section, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (*IPAddressSection) Iterator 

func (section *IPAddressSection) Iterator() IPSectionIterator

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() IPSectionIterator

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() IPSectionIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this address section, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this address section.

If the series has no prefix length, then this is equivalent to Iterator.

func (*IPAddressSection) ReverseBits 

func (section *IPAddressSection) ReverseBits(perByte bool) (*IPAddressSection, addrerr.IncompatibleAddressError)

ReverseBits returns a new section with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPAddressSection) ReverseBytes 

func (section *IPAddressSection) ReverseBytes() (*IPAddressSection, addrerr.IncompatibleAddressError)

ReverseBytes returns a new section with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (*IPAddressSection) ReverseSegments 

func (section *IPAddressSection) ReverseSegments() *IPAddressSection

ReverseSegments returns a new section with the segments reversed.

func (*IPAddressSection) SequentialBlockIterator 

func (section *IPAddressSection) SequentialBlockIterator() IPSectionIterator

SequentialBlockIterator iterates through the sequential address sections that make up this address section.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPAddressSection) SetPrefixLen 

func (section *IPAddressSection) SetPrefixLen(prefixLen BitCount) *IPAddressSection

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPAddressSection) SetPrefixLenZeroed 

func (section *IPAddressSection) SetPrefixLenZeroed(prefixLen BitCount) (*IPAddressSection, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

If this address section has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address section has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (ie bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPAddressSection) SpanWithPrefixBlocks 

func (section *IPAddressSection) SpanWithPrefixBlocks() []*IPAddressSection

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual address sections as this section.

Unlike SpanWithPrefixBlocksTo, the result only includes blocks that are a part of this section.

func (*IPAddressSection) SpanWithSequentialBlocks 

func (section *IPAddressSection) SpanWithSequentialBlocks() []*IPAddressSection

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of sections as this.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

func (*IPAddressSection) String 

func (section *IPAddressSection) String() string

String implements the fmt.Stringer interface, returning the normalized string provided by ToNormalizedString, or "<nil>" if the receiver is a nil pointer

func (*IPAddressSection) TestBit 

func (section *IPAddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPAddressSection) ToBinaryString 

func (section *IPAddressSection) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address section as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPAddressSection) ToBlock 

func (section *IPAddressSection) ToBlock(segmentIndex int, lower, upper SegInt) *IPAddressSection

ToBlock creates a new block of address sections by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPAddressSection) ToCanonicalString 

func (section *IPAddressSection) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address section.

For IPv4, dotted octet format, also known as dotted decimal format, is used. https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

With IP addresses, the prefix length is included in the string.

func (*IPAddressSection) ToCanonicalWildcardString 

func (section *IPAddressSection) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string but avoids the CIDR prefix length. Address sections with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. IPv6 sections will be compressed according to the canonical representation. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPAddressSection) ToCompressedString 

func (section *IPAddressSection) ToCompressedString() string

ToCompressedString produces a short representation of this address section while remaining within the confines of standard representation(s) of the address.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.

func (*IPAddressSection) ToCompressedWildcardString 

func (section *IPAddressSection) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, avoiding the CIDR prefix, but with full IPv6 segment compression as well, including single zero-segments. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPAddressSection) ToCustomString 

func (section *IPAddressSection) ToCustomString(stringOptions addrstr.IPStringOptions) string

ToCustomString creates a customized string from this address section according to the given string option parameters

func (*IPAddressSection) ToDivGrouping 

func (section *IPAddressSection) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToIP.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSection) ToFullString 

func (section *IPAddressSection) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 4 characters for IPv6 segments and 3 characters for IPv4 segments.

func (*IPAddressSection) ToHexString 

func (section *IPAddressSection) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address section as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPAddressSection) ToIPv4 

func (section *IPAddressSection) ToIPv4() *IPv4AddressSection

ToIPv4 converts to an IPv4AddressSection if this section originated as an IPv4 section. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSection) ToIPv6 

func (section *IPAddressSection) ToIPv6() *IPv6AddressSection

ToIPv6 converts to an IPv6AddressSection if this section originated as an IPv6 section. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSection) ToMaxHost 

func (section *IPAddressSection) ToMaxHost() (res *IPAddressSection, err addrerr.IncompatibleAddressError)

ToMaxHost converts the address section to one in which all individual address sections have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-ones section, the max address section.

The returned address section will have the same prefix and prefix length.

This returns an error if the address section is a range of address sections which cannot be converted to a range in which all sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPAddressSection) ToMaxHostLen 

func (section *IPAddressSection) ToMaxHostLen(prefixLength BitCount) (*IPAddressSection, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address section to one in which all individual address sections have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this section has the same prefix length, then the resulting section will too, otherwise the resulting section will have no prefix length.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all address sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPAddressSection) ToNormalizedString 

func (section *IPAddressSection) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address section.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. Zero segments are not compressed.

With IP addresses, the prefix length is included in the string.

func (*IPAddressSection) ToNormalizedWildcardString 

func (section *IPAddressSection) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPAddressSection) ToOctalString 

func (section *IPAddressSection) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address section as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPAddressSection) ToPrefixBlock 

func (section *IPAddressSection) ToPrefixBlock() *IPAddressSection

ToPrefixBlock returns the section with the same prefix as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

If this section has no prefix, this section is returned.

func (*IPAddressSection) ToPrefixBlockLen 

func (section *IPAddressSection) ToPrefixBlockLen(prefLen BitCount) *IPAddressSection

ToPrefixBlockLen returns the section with the same prefix of the given length as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

func (*IPAddressSection) ToPrefixLenString 

func (section *IPAddressSection) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, a zero host section will be compressed with ::. For IPv4 the string is equivalent to the canonical string.

func (*IPAddressSection) ToReverseDNSString 

func (section *IPAddressSection) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse DNS lookup string, returning an error if this address section is an IPv6 multiple-valued section for which the range cannot be represented. For 8.255.4.4 it is 4.4.255.8.in-addr.arpa For 2001:db8::567:89ab it is b.a.9.8.7.6.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa

func (*IPAddressSection) ToSQLWildcardString 

func (section *IPAddressSection) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the wildcard '_'..

func (*IPAddressSection) ToSectionBase 

func (section *IPAddressSection) ToSectionBase() *AddressSection

ToSectionBase converts to an AddressSection, a polymorphic type usable with all address sections. Afterwards, you can convert back with ToIP.

ToSectionBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSection) ToSegmentedBinaryString 

func (section *IPAddressSection) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this IP address section as segments of binary values preceded by the "0b" prefix.

func (*IPAddressSection) ToSubnetString 

func (section *IPAddressSection) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like 1.2.*.* or 1:2::/16

In the case of IPv4, this means that wildcards are used instead of a network prefix when a network prefix has been supplied. In the case of IPv6, when a network prefix has been supplied, the prefix will be shown and the host section will be compressed with ::.

func (*IPAddressSection) ToZeroHost 

func (section *IPAddressSection) ToZeroHost() (res *IPAddressSection, err addrerr.IncompatibleAddressError)

ToZeroHost converts the address section to one in which all individual address sections have a host of zero, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned section will have the same prefix and prefix length.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPAddressSection) ToZeroHostLen 

func (section *IPAddressSection) ToZeroHostLen(prefixLength BitCount) (*IPAddressSection, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address section to one in which all individual sections have a host of zero, the host being the bits following the given prefix length. If this address section has the same prefix length, then the returned one will too, otherwise the returned section will have no prefix length.

This returns an error if the section is a range of which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPAddressSection) ToZeroNetwork 

func (section *IPAddressSection) ToZeroNetwork() *IPAddressSection

ToZeroNetwork converts the address section to one in which all individual address sections have a network of zero, the network being the bits within the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned address section will have the same prefix length.

func (*IPAddressSection) UpperBytes 

func (section *IPAddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice

func (*IPAddressSection) WithoutPrefixLen 

func (section *IPAddressSection) WithoutPrefixLen() *IPAddressSection

WithoutPrefixLen provides the same address section but with no prefix length. The values remain unchanged.

func (*IPAddressSection) Wrap 

func (section *IPAddressSection) Wrap() WrappedIPAddressSection

Wrap wraps this IP address section, returning a WrappedIPAddressSection, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address section.

func (*IPAddressSection) WrapSection added in v1.2.0 

func (section *IPAddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapSection can be called with a nil receiver, wrapping a nil address section.

type IPAddressSegment 

type IPAddressSegment struct {
	// contains filtered or unexported fields
}

IPAddressSegment represents a single segment of an IP address. An IP segment contains a single value or a range of sequential values, a prefix length, and it has an assigned bit length.

For IPv4, segments are 1 byte. For IPv6, they are two bytes.

IPAddressSegment objects are immutable and thus also concurrency-safe.

See AddressSegment for more details regarding segments.

func (*IPAddressSegment) Bytes 

func (seg *IPAddressSegment) Bytes() []byte

Bytes returns the lowest value in the address segment range as a byte slice

func (*IPAddressSegment) Compare 

func (seg *IPAddressSegment) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address segment is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPAddressSegment) Contains 

func (seg *IPAddressSegment) Contains(other AddressSegmentType) bool

Contains returns whether this is same type and version as the given segment and whether it contains all values in the given segment.

func (*IPAddressSegment) ContainsPrefixBlock 

func (seg *IPAddressSegment) ContainsPrefixBlock(divisionPrefixLen BitCount) bool

ContainsPrefixBlock returns whether the division range includes the block of values for the given prefix length

func (*IPAddressSegment) ContainsSinglePrefixBlock 

func (seg *IPAddressSegment) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the segment range matches exactly the block of values for the given prefix length and has just a single prefix for that prefix length.

func (*IPAddressSegment) CopyBytes 

func (seg *IPAddressSegment) CopyBytes(bytes []byte) []byte

CopyBytes copies the lowest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddressSegment) CopyUpperBytes 

func (seg *IPAddressSegment) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the highest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPAddressSegment) Equal 

func (seg *IPAddressSegment) Equal(other AddressSegmentType) bool

Equal returns whether the given segment is equal to this segment. Two segments are equal if they match:

  • type/version IPv4, IPv6
  • value range

Prefix lengths are ignored.

func (*IPAddressSegment) GetBitCount 

func (seg *IPAddressSegment) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item

func (*IPAddressSegment) GetBlockMaskPrefixLen 

func (seg *IPAddressSegment) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address segment is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is a segment with all 1s in the network bits and then all 0s in the host bits. A CIDR host mask is a segment with all 0s in the network bits and then all 1s in the host bits. The prefix length is the bit-length of the network bits.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this segment. The prefix length returned here indicates the whether the value of this segment can be used as a mask for the network and host bits of any other segment. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPAddressSegment) GetByteCount 

func (seg *IPAddressSegment) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item.

func (*IPAddressSegment) GetCount 

func (seg *IPAddressSegment) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1.

For instance, a segment with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPAddressSegment) GetLower 

func (seg *IPAddressSegment) GetLower() *IPAddressSegment

GetLower returns a segment representing just the lowest value in the range, which will be the same segment if it represents a single value.

func (*IPAddressSegment) GetMaxValue 

func (seg *IPAddressSegment) GetMaxValue() SegInt

GetMaxValue gets the maximum possible value for this type or version of segment, determined by the number of bits.

For the highest range value of this particular segment, use GetUpperSegmentValue.

func (*IPAddressSegment) GetMinPrefixLenForBlock 

func (seg *IPAddressSegment) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this segment includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this segment represents a single value, this returns the bit count.

func (*IPAddressSegment) GetPrefixCountLen 

func (seg *IPAddressSegment) GetPrefixCountLen(segmentPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct prefix values for the given prefix length in the range of values of this segment

func (*IPAddressSegment) GetPrefixLenForSingleBlock 

func (seg *IPAddressSegment) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this segment, and the range of values in this segment matches the block of all values for that prefix.

If the range of segment values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this segment represents a single value, this returns the bit count of the segment.

func (*IPAddressSegment) GetPrefixValueCount 

func (seg *IPAddressSegment) GetPrefixValueCount() SegIntCount

GetPrefixValueCount returns the count of prefixes in this segment for its prefix length, or the total count if it has no prefix length.

func (*IPAddressSegment) GetPrefixValueCountLen 

func (seg *IPAddressSegment) GetPrefixValueCountLen(segmentPrefixLength BitCount) SegIntCount

GetPrefixValueCountLen returns the same value as GetPrefixCountLen as an integer

func (*IPAddressSegment) GetSegmentPrefixLen 

func (seg *IPAddressSegment) GetSegmentPrefixLen() PrefixLen

GetSegmentPrefixLen returns the network prefix for the segment.

The network prefix is 16 for an address like 1.2.0.0/16.

When it comes to each address division or segment, the prefix for the division is the prefix obtained when applying the address or section prefix.

For instance, consider the address 1.2.0.0/20. The first segment has no prefix because the address prefix 20 extends beyond the 8 bits in the first segment, it does not even apply to the segment. The second segment has no prefix because the address prefix extends beyond bits 9 to 16 which lie in the second segment, it does not apply to that segment either. The third segment has the prefix 4 because the address prefix 20 corresponds to the first 4 bits in the 3rd segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment has the prefix 0 because not a single bit is in the network section of the address or segment

The prefix applied across the address is nil ... nil ... (1 to segment bit length) ... 0 ... 0

If the segment has no prefix then nil is returned.

func (*IPAddressSegment) GetSegmentValue 

func (seg *IPAddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the segment value range

func (*IPAddressSegment) GetString 

func (seg *IPAddressSegment) GetString() string

GetString produces a normalized string to represent the segment. If the segment is a CIDR network prefix block for its prefix length, then the string contains only the lower value of the block range. Otherwise, the explicit range will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPAddressSegment) GetUpper 

func (seg *IPAddressSegment) GetUpper() *IPAddressSegment

GetUpper returns a segment representing just the highest value in the range, which will be the same segment if it represents a single value.

func (*IPAddressSegment) GetUpperSegmentValue 

func (seg *IPAddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the segment value range

func (*IPAddressSegment) GetUpperValue 

func (seg *IPAddressSegment) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address segment range as a big integer

func (*IPAddressSegment) GetValue 

func (seg *IPAddressSegment) GetValue() *BigDivInt

GetValue returns the lowest value in the address segment range as a big integer

func (*IPAddressSegment) GetValueCount 

func (seg *IPAddressSegment) GetValueCount() SegIntCount

GetValueCount returns the same value as GetCount as an integer

func (*IPAddressSegment) GetWildcardString 

func (seg *IPAddressSegment) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters while ignoring any network prefix length. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPAddressSegment) IncludesMax 

func (seg *IPAddressSegment) IncludesMax() bool

IncludesMax returns whether this segment includes the max value, the value whose bits are all ones, within its range

func (*IPAddressSegment) IncludesZero 

func (seg *IPAddressSegment) IncludesZero() bool

IncludesZero returns whether this segment includes the value of zero within its range

func (*IPAddressSegment) IsFullRange 

func (seg *IPAddressSegment) IsFullRange() bool

IsFullRange returns whether the segment range includes all possible values for its bit length. 

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPAddressSegment) IsIPv4 

func (seg *IPAddressSegment) IsIPv4() bool

IsIPv4 returns true if this segment originated as an IPv4 segment. If so, use ToIPv4 to convert back to the IPv4-specific type.

func (*IPAddressSegment) IsIPv6 

func (seg *IPAddressSegment) IsIPv6() bool

IsIPv6 returns true if this segment originated as an IPv6 segment. If so, use ToIPv6 to convert back to the IPv6-specific type.

func (*IPAddressSegment) IsMax 

func (seg *IPAddressSegment) IsMax() bool

IsMax returns whether this segment matches exactly the maximum possible value, the value whose bits are all ones

func (*IPAddressSegment) IsMultiple 

func (seg *IPAddressSegment) IsMultiple() bool

IsMultiple returns whether this segment represents multiple values

func (*IPAddressSegment) IsOneBit 

func (seg *IPAddressSegment) IsOneBit(segmentBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex < 0, or if it is larger than the bit count of this item.

func (*IPAddressSegment) IsPrefixBlock 

func (seg *IPAddressSegment) 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 (*IPAddressSegment) IsPrefixed 

func (seg *IPAddressSegment) IsPrefixed() bool

IsPrefixed returns whether this section has an associated prefix length

func (*IPAddressSegment) IsSinglePrefix 

func (seg *IPAddressSegment) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix determines if the segment has a single prefix value for the given prefix length. You can call GetPrefixCountLen to get the count of prefixes.

func (*IPAddressSegment) IsSinglePrefixBlock 

func (seg *IPAddressSegment) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock() except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPAddressSegment) IsZero 

func (seg *IPAddressSegment) IsZero() bool

IsZero returns whether this segment matches exactly the value of zero

func (*IPAddressSegment) Iterator 

func (seg *IPAddressSegment) Iterator() IPSegmentIterator

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() IPSegmentIterator

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() IPSegmentIterator

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) IPSegmentIterator

PrefixedBlockIterator provides an iterator to iterate through the individual prefix blocks of the given prefix length in this segment, one for each prefix of this address or subnet.

It is similar to PrefixBlockIterator except that this method allows you to specify the prefix length.

func (*IPAddressSegment) ReverseBits 

func (seg *IPAddressSegment) ReverseBits(perByte bool) (res *AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBits returns a segment with the bits reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPAddressSegment) ReverseBytes 

func (seg *IPAddressSegment) ReverseBytes() (res *AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBytes returns a segment with the bytes reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

func (*IPAddressSegment) String 

func (seg *IPAddressSegment) String() string

String produces a string that is useful when a segment string is provided with no context. If the segment was originally constructed as an IPv4 address segment it uses decimal, otherwise hexadecimal. It uses a string prefix for hex (0x), and does not use the wildcard '*', because division size is variable, so '*' is ambiguous. GetWildcardString is more appropriate in context with other segments or divisions. It does not use a string prefix and uses '*' for full-range segments. GetString is more appropriate in context with prefix lengths, it uses zeros instead of wildcards with full prefix block ranges alongside prefix lengths.

func (*IPAddressSegment) TestBit 

func (seg *IPAddressSegment) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPAddressSegment) ToDiv 

func (seg *IPAddressSegment) ToDiv() *AddressDivision

ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions. Afterwards, you can convert back with ToIP.

ToDiv can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSegment) ToHexString 

func (seg *IPAddressSegment) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address segment as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

For segments, the error is always nil.

func (*IPAddressSegment) ToHostSegment 

func (seg *IPAddressSegment) ToHostSegment(segmentPrefixLength PrefixLen) *IPAddressSegment

ToHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will have no assigned prefix length.

func (*IPAddressSegment) ToIPv4 

func (seg *IPAddressSegment) ToIPv4() *IPv4AddressSegment

ToIPv4 converts to an IPv4AddressSegment if this segment originated as an IPv4 segment. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSegment) ToIPv6 

func (seg *IPAddressSegment) ToIPv6() *IPv6AddressSegment

ToIPv6 converts to an IPv6AddressSegment if this segment originated as an IPv6 segment. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSegment) ToNetworkSegment 

func (seg *IPAddressSegment) ToNetworkSegment(segmentPrefixLength PrefixLen) *IPAddressSegment

ToNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will have no assigned prefix length.

func (*IPAddressSegment) ToNormalizedString 

func (seg *IPAddressSegment) ToNormalizedString() string

ToNormalizedString produces a string that is consistent for all address segments of the same type and version. IPv4 segments use base 10, while IPv6 segments use base 16.

func (*IPAddressSegment) ToPrefixedHostSegment 

func (seg *IPAddressSegment) ToPrefixedHostSegment(segmentPrefixLength PrefixLen) *IPAddressSegment

ToPrefixedHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPAddressSegment) ToPrefixedNetworkSegment 

func (seg *IPAddressSegment) ToPrefixedNetworkSegment(segmentPrefixLength PrefixLen) *IPAddressSegment

ToPrefixedNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPAddressSegment) ToSegmentBase 

func (seg *IPAddressSegment) ToSegmentBase() *AddressSegment

ToSegmentBase converts to an AddressSegment, a polymorphic type usable with all address segments. Afterwards, you can convert back with ToIP.

ToSegmentBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPAddressSegment) UpperBytes 

func (seg *IPAddressSegment) UpperBytes() []byte

UpperBytes returns the highest value in the address segment range as a byte slice

func (*IPAddressSegment) WithoutPrefixLen 

func (seg *IPAddressSegment) WithoutPrefixLen() *IPAddressSegment

WithoutPrefixLen returns a segment with the same value range but without a prefix length.

type IPAddressSegmentSeries 

type IPAddressSegmentSeries interface {
	AddressSegmentSeries

	// IncludesZeroHost returns whether the series contains an individual series with a host of zero.  If the series has no prefix length it returns false.
	// If the prefix length matches the bit count, then it returns true.
	//
	// Otherwise, it checks whether it contains an individual series for which all bits past the prefix are zero.
	IncludesZeroHost() bool

	// IncludesZeroHostLen returns whether the series contains an individual series with a host of zero, a series for which all bits past the given prefix length are zero.
	IncludesZeroHostLen(prefLen BitCount) bool

	// IncludesMaxHost returns whether the series contains an individual series with a host of all one-bits.  If the series has no prefix length it returns false.
	// If the prefix length matches the bit count, then it returns true.
	//
	// Otherwise, it checks whether it contains an individual series for which all bits past the prefix are one.
	IncludesMaxHost() bool

	// IncludesMaxHostLen returns whether the series contains an individual series with a host of all one-bits, a series for which all bits past the given prefix length are all ones.
	IncludesMaxHostLen(prefLen BitCount) bool

	// IsZeroHost returns whether this series has a prefix length and if so,
	// whether the host section is always zero for all individual series in this subnet or address section.
	//
	// If the host section is zero length (there are zero host bits), IsZeroHost returns true.
	IsZeroHost() bool

	// IsZeroHostLen returns whether the host section is always zero for all individual series in this address or address section,
	// for the given prefix length.
	//
	// If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.
	IsZeroHostLen(BitCount) bool

	// IsMaxHost returns whether this address or address section has a prefix length and if so,
	// whether the host section is always all one-bits, the max value, for all individual series in this address or address section,
	//the host being the bits following the prefix.
	//
	// If the host section is zero length (there are zero host bits), IsMaxHost returns true.
	IsMaxHost() bool

	// IsMaxHostLen returns whether the host is all one-bits, the max value, for all individual series in this address or address section,
	// for the given prefix length, the host being the bits following the prefix.
	//
	// If the host is zero length (there are zero host bits), IsMaxHostLen returns true.
	IsMaxHostLen(BitCount) bool

	// IsSingleNetwork returns whether the network section of the IP address series, the prefix, consists of a single value
	//
	// If it has no prefix length, it returns true if not multiple, if it contains only a single individual series.
	IsSingleNetwork() bool

	// GetIPVersion returns the IP version of this IP address or IP address section
	GetIPVersion() IPVersion

	// GetBlockMaskPrefixLen returns the prefix length if this IP address or IP address section is equivalent to the mask for a CIDR prefix block.
	// Otherwise, it returns nil.
	// A CIDR network mask is a series with all 1s in the network section and then all 0s in the host section.
	// A CIDR host mask is a series with all 0s in the network section and then all 1s 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

	// 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.
	ToNormalizedWildcardString() string

	// ToCanonicalWildcardString produces a string similar to the canonical string but avoids the CIDR prefix length.
	// Series with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation.
	// IPv6 series will be compressed according to the canonical representation.
	ToCanonicalWildcardString() string

	// ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, avoiding the CIDR prefix, but with full IPv6 segment compression as well, including single zero-segments.
	// For IPv4 it is the same as ToNormalizedWildcardString.
	ToCompressedWildcardString() string

	// ToSegmentedBinaryString writes this IP address segment series as segments of binary values preceded by the "0b" prefix.
	ToSegmentedBinaryString() string

	// ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that
	// it uses SQL wildcards.  It uses '%' instead of '*' and also uses the wildcard '_'..
	ToSQLWildcardString() string

	// ToReverseDNSString generates the reverse DNS lookup string,
	// returning an error if this address series is an IPv6 multiple-valued section for which the range cannot be represented.
	// For 8.255.4.4 it is 4.4.255.8.in-addr.arpa
	// For 2001:db8::567:89ab it is b.a.9.8.7.6.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa
	ToReverseDNSString() (string, addrerr.IncompatibleAddressError)
}

IPAddressSegmentSeries serves as a common interface to all IP address sections and IP addresses

type IPAddressSeqRange 

type IPAddressSeqRange struct {
	// contains filtered or unexported fields
}

IPAddressSeqRange represents an arbitrary range of consecutive IP addresses.

Note that IPAddress and IPAddressString allow you to specify a range of values for each segment. That allows you to represent single addresses, any address CIDR prefix subnet (eg 1.2.0.0/16 or 1:2:3:4::/64) or any subnet that can be represented with segment ranges (1.2.0-255.* or 1:2:3:4:*), see IPAddressString for details.

IPAddressString and IPAddress cover all potential subnets and addresses that can be represented by a single address string of 4 or less segments for IPv4, and 8 or less segments for IPv6.

This class allows the representation of any sequential address range, including those that cannot be represented by IPAddress.

String representations include the full address for both the lower and upper bounds of the range.

The zero value is a range from the zero IPAddress to itself.

func (*IPAddressSeqRange) Bytes 

func (rng *IPAddressSeqRange) Bytes() []byte

Bytes returns the lowest address in the range, the one with the lowest numeric value, as a byte slice

func (*IPAddressSeqRange) Compare 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) CompareSize 

func (rng *IPAddressSeqRange) CompareSize(other IPAddressSeqRangeType) int

CompareSize compares the counts of two address ranges, the number of individual addresses within.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one range spans more individual addresses than another.

CompareSize returns a positive integer if this range has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.

func (*IPAddressSeqRange) Contains 

func (rng *IPAddressSeqRange) Contains(other IPAddressType) bool

Contains returns whether this range contains all addresses in the given address or subnet.

func (*IPAddressSeqRange) ContainsPrefixBlock 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) ContainsRange 

func (rng *IPAddressSeqRange) ContainsRange(other IPAddressSeqRangeType) bool

ContainsRange returns whether all the addresses in the given sequential range are also contained in this sequential range.

func (*IPAddressSeqRange) ContainsSinglePrefixBlock 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) CopyBytes 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) CopyNetIP 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) CopyUpperBytes 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) CopyUpperNetIP 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) CoverWithPrefixBlock 

func (rng *IPAddressSeqRange) CoverWithPrefixBlock() *IPAddress

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 (*IPAddressSeqRange) Equal 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) Extend 

func (rng *IPAddressSeqRange) Extend(other *IPAddressSeqRange) *IPAddressSeqRange

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 (IPAddressSeqRange) Format 

func (rng IPAddressSeqRange) 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 (*IPAddressSeqRange) GetBitCount 

func (rng *IPAddressSeqRange) GetBitCount() BitCount

GetBitCount returns the number of bits in each address in the range

func (*IPAddressSeqRange) GetByteCount 

func (rng *IPAddressSeqRange) GetByteCount() int

GetByteCount returns the number of bytes in each address in the range

func (*IPAddressSeqRange) GetCount 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) GetLower 

func (rng *IPAddressSeqRange) GetLower() *IPAddress

GetLower returns the lowest address in the range, the one with the lowest numeric value

func (*IPAddressSeqRange) GetLowerIPAddress 

func (rng *IPAddressSeqRange) GetLowerIPAddress() *IPAddress

GetLowerIPAddress satisfies the IPAddressRange interface, returning the lower address in the range, same as GetLower()

func (*IPAddressSeqRange) GetMinPrefixLenForBlock 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) GetNetIP 

func (rng *IPAddressSeqRange) GetNetIP() net.IP

GetNetIP returns the lower IP address in the range as a net.IP

func (*IPAddressSeqRange) GetPrefixCountLen 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) GetPrefixLenForSingleBlock 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) GetUpper 

func (rng *IPAddressSeqRange) GetUpper() *IPAddress

GetUpper returns the highest address in the range, the one with the highest numeric value

func (*IPAddressSeqRange) GetUpperIPAddress 

func (rng *IPAddressSeqRange) GetUpperIPAddress() *IPAddress

GetUpperIPAddress satisfies the IPAddressRange interface, returning the upper address in the range, same as GetUpper()

func (*IPAddressSeqRange) GetUpperNetIP 

func (rng *IPAddressSeqRange) GetUpperNetIP() net.IP

GetUpperNetIP returns the upper IP address in the range as a net.IP

func (*IPAddressSeqRange) GetUpperValue 

func (rng *IPAddressSeqRange) GetUpperValue() *big.Int

GetUpperValue returns the highest address in the range, the one with the highest numeric value, as an integer

func (*IPAddressSeqRange) GetValue 

func (rng *IPAddressSeqRange) GetValue() *big.Int

GetValue returns the lowest address in the range, the one with the lowest numeric value, as an integer

func (*IPAddressSeqRange) IncludesMax 

func (rng *IPAddressSeqRange) IncludesMax() bool

IncludesMax returns whether this sequential range's upper value is the max value, the value whose bits are all ones.

func (*IPAddressSeqRange) IncludesZero 

func (rng *IPAddressSeqRange) IncludesZero() bool

IncludesZero returns whether this sequential range's lower value is the zero address.

func (*IPAddressSeqRange) Intersect 

func (rng *IPAddressSeqRange) Intersect(other *IPAddressSeqRange) *IPAddressSeqRange

Intersect returns the intersection of this range with the given range, a range which includes those addresses found in both.

func (*IPAddressSeqRange) IsFullRange 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) IsIPv4 

func (rng *IPAddressSeqRange) IsIPv4() bool

IsIPv4 returns true if this sequential address range originated as an IPv4 sequential address range. If so, use ToIPv4 to convert back to the IPv4-specific type.

func (*IPAddressSeqRange) IsIPv6 

func (rng *IPAddressSeqRange) IsIPv6() bool

IsIPv6 returns true if this sequential address range originated as an IPv6 sequential address range. If so, use ToIPv6 to convert back to the IPv6-specific type.

func (*IPAddressSeqRange) IsMax 

func (rng *IPAddressSeqRange) IsMax() bool

IsMax returns whether this sequential range spans from the max address, the address whose bits are all ones, to itself.

func (*IPAddressSeqRange) IsMultiple 

func (rng *IPAddressSeqRange) IsMultiple() bool

IsMultiple returns whether this range represents a range of multiple addresses

func (*IPAddressSeqRange) IsSequential 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) IsZero 

func (rng *IPAddressSeqRange) IsZero() bool

IsZero returns whether this sequential range spans from the zero address to itself.

func (*IPAddressSeqRange) Iterator 

func (rng *IPAddressSeqRange) Iterator() IPAddressIterator

Iterator provides an iterator to iterate through the individual addresses of this address range.

Call GetCount for the count.

func (*IPAddressSeqRange) Join 

func (rng *IPAddressSeqRange) Join(ranges ...*IPAddressSeqRange) []*IPAddressSeqRange

Join joins the given ranges into the fewest number of ranges. The returned array will be sorted by ascending lowest range value.

func (*IPAddressSeqRange) JoinTo 

func (rng *IPAddressSeqRange) JoinTo(other *IPAddressSeqRange) *IPAddressSeqRange

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 (*IPAddressSeqRange) Overlaps 

func (rng *IPAddressSeqRange) Overlaps(other *IPAddressSeqRange) bool

Overlaps returns true if this sequential range overlaps with the given sequential range.

func (*IPAddressSeqRange) PrefixBlockIterator 

func (rng *IPAddressSeqRange) PrefixBlockIterator(prefLength BitCount) IPAddressIterator

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 (*IPAddressSeqRange) PrefixIterator 

func (rng *IPAddressSeqRange) PrefixIterator(prefLength BitCount) IPAddressSeqRangeIterator

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.

func (*IPAddressSeqRange) SpanWithPrefixBlocks 

func (rng *IPAddressSeqRange) SpanWithPrefixBlocks() []*IPAddress

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of addresses as this range.

func (*IPAddressSeqRange) SpanWithSequentialBlocks 

func (rng *IPAddressSeqRange) SpanWithSequentialBlocks() []*IPAddress

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 (*IPAddressSeqRange) String 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) Subtract 

func (rng *IPAddressSeqRange) Subtract(other *IPAddressSeqRange) []*IPAddressSeqRange

Subtract subtracts the given range from this range, to produce either zero, one, or two address ranges that contain the addresses in this range and not in the given range. If the result has length 2, the two ranges are ordered by ascending lowest range value.

func (*IPAddressSeqRange) ToCanonicalString 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) ToIP 

func (rng *IPAddressSeqRange) ToIP() *IPAddressSeqRange

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 (*IPAddressSeqRange) ToIPv4 

func (rng *IPAddressSeqRange) ToIPv4() *IPv4AddressSeqRange

ToIPv4 converts to an IPv4AddressSeqRange if this address range originated as 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 (*IPAddressSeqRange) ToIPv6 

func (rng *IPAddressSeqRange) ToIPv6() *IPv6AddressSeqRange

ToIPv6 converts to an IPv6AddressSeqRange if this address range originated as 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 (*IPAddressSeqRange) ToKey added in v1.1.0 

func (rng *IPAddressSeqRange) ToKey() *IPAddressSeqRangeKey

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, IPAddressSeqRangeKey instances are comparable with go operators, and thus can be used as map keys.

func (*IPAddressSeqRange) ToNormalizedString 

func (rng *IPAddressSeqRange) 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 (*IPAddressSeqRange) ToString 

func (rng *IPAddressSeqRange) ToString(lowerStringer func(*IPAddress) string, separator string, upperStringer func(*IPAddress) string) string

func (*IPAddressSeqRange) UpperBytes 

func (rng *IPAddressSeqRange) UpperBytes() []byte

UpperBytes returns the highest address in the range, the one with the highest numeric value, as a byte slice

type IPAddressSeqRangeIterator 

type IPAddressSeqRangeIterator interface {
	HasNext

	// Next returns the next sequential address range, or nil if there is none left.
	Next() *IPAddressSeqRange
}

IPAddressSeqRangeIterator iterates through IP address sequential ranges

type IPAddressSeqRangeKey added in v1.1.0 

type IPAddressSeqRangeKey struct {
	// contains filtered or unexported fields
}

IPAddressSeqRangeKey is a representation of IPAddressSeqRange that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators It can be used as a map key. The zero value is a range from a zero-length address to itself.

func (*IPAddressSeqRangeKey) String added in v1.1.1 

func (key *IPAddressSeqRangeKey) String() string

String calls the String method in the corresponding sequential range

func (*IPAddressSeqRangeKey) ToSeqRange added in v1.1.1 

func (key *IPAddressSeqRangeKey) ToSeqRange() *IPAddressSeqRange

ToSeqRange converts to the associated sequential range

type IPAddressSeqRangeType 

type IPAddressSeqRangeType interface {
	AddressItem

	// CompareSize compares the counts of two subnets, the number of individual addresses within.
	//
	// Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one subnet represents more individual addresses than another.
	//
	// CompareSize returns a positive integer if this address has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.
	CompareSize(IPAddressSeqRangeType) int

	// 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() *IPAddressSeqRange
	// contains filtered or unexported methods
}

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 of the supported formats using an IPAddressStringParametersBuilder to build a parameters instance of IPAddressStringParameters. When no IPAddressStringParameters is supplied, a default instance of IPAddressStringParameters 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

  • 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 class support all address formats of the C routine inet_pton and the Java method java.net.InetAddress.getByName. This class 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 class) 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 IPAddressStringParametersBuilder.GetIPv4AddressParametersBuilder 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 class is goroutine/thread-safe. In fact, IPAddressString objects are immutable. An IPAddressString object represents a single IP address representation that cannot be changed after construction. Some of the derived state is created upon demand and cached, such as the derived IPAddress instances.

This class has a few methods with analogs in IPAddress, such as Contains(), GetSequentialRange(), PrefixEquals(), IsIPv4(), and IsIPv6(). Such methods are provided to make creating the IPAddress instance unnecessary when no such IPAddress instance is needed for other reasons.

func NewIPAddressString 

func NewIPAddressString(str string) *IPAddressString

NewIPAddressString constructs an IPAddressString.

func NewIPAddressStringParams 

func NewIPAddressStringParams(str string, params addrstrparam.IPAddressStringParams) *IPAddressString

NewIPAddressStringParams constructs an IPAddressString that will parse the given string according to the given parameters.

func (*IPAddressString) AdjustPrefixLen 

func (addrStr *IPAddressString) AdjustPrefixLen(adjustment BitCount) (*IPAddressString, addrerr.IncompatibleAddressError)

AdjustPrefixLen increases or decreases the prefix length by the given increment.

If the address string has prefix length 0 and represents all addresses of the same version, and the prefix length is being decreased, then the address representing all addresses of any version is returned.

When there is an associated address value and the prefix length is increased, the bits moved within the prefix become zero, and if prefix length is extended beyond the segment series boundary, it is removed. When there is an associated address value and the prefix length is decreased, the bits moved outside the prefix become zero.

If the address string represents a prefix block, then the result will also represent a prefix block.

func (*IPAddressString) Compare 

func (addrStr *IPAddressString) Compare(other *IPAddressString) int

Compare compares this address string with another, returning a negative number, zero, or a positive number if this address string is less than, equal to, or greater than the other.

All address strings are comparable. If two address strings are invalid, their strings are compared. Otherwise, address strings are compared according to which type or version of string, and then within each type or version they are compared using the comparison rules for addresses.

func (*IPAddressString) Contains 

func (addrStr *IPAddressString) Contains(other *IPAddressString) bool

Contains returns whether the address or subnet identified by this address string contains the address or subnet identified by the given string. If this address string or the given address string is invalid then Contains returns false.

func (*IPAddressString) Equal 

func (addrStr *IPAddressString) Equal(other *IPAddressString) bool

Equal compares two IP address strings for equality. Two IPAddressString objects are equal if they represent the same set of addresses. Whether one or the other has an associated network prefix length is not considered.

If an IPAddressString is invalid, it is equal to another address only if the other address was constructed from the same string.

func (*IPAddressString) GetAddress 

func (addrStr *IPAddressString) GetAddress() *IPAddress

GetAddress returns the IP address if this IPAddressString is a valid string representing an IP address or subnet. Otherwise, it returns nil.

Use ToAddress for an equivalent method that returns an error when the format is invalid.

If you have a prefixed address and you wish to get only the host without the prefix, use GetHostAddress.

func (*IPAddressString) GetHostAddress 

func (addrStr *IPAddressString) GetHostAddress() *IPAddress

GetHostAddress parses the address while ignoring the prefix length or mask. GetHostAddress returns nil for an invalid string. If you wish to receive an error instead, use ToHostAddress.

func (*IPAddressString) GetIPVersion 

func (addrStr *IPAddressString) GetIPVersion() IPVersion

GetIPVersion returns the IP address version if this represents a valid IP address, otherwise it returns nil

func (*IPAddressString) GetMask 

func (addrStr *IPAddressString) GetMask() *IPAddress

GetMask returns the mask, if any, that was provided with this address string

func (*IPAddressString) GetNetworkPrefixLen 

func (addrStr *IPAddressString) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the associated network prefix length.

If this address is a valid address with an associated network prefix length then this returns that prefix length, otherwise returns nil. The prefix length may be expressed explicitly with the notation "/xx" where xx is a decimal value, or it may be expressed implicitly as a network mask such as "/255.255.0.0"

func (*IPAddressString) GetSequentialRange 

func (addrStr *IPAddressString) GetSequentialRange() (res *IPAddressSeqRange)

GetSequentialRange returns the range of sequential addresses from the lowest address specified in this address string to the highest.

Since not all IPAddressString instances describe a sequential series of addresses, this does not necessarily match the exact set of addresses specified by the string. For example, 1-2.3.4.1-2 produces the sequential range 1.3.4.1 to 2.3.4.2 that includes the address 1.255.255.2 not specified by the string.

This method can also produce a range for a string for which no IPAddress instance can be created, those cases where IsValid returns true but ToAddress returns addrerr.IncompatibleAddressError and GetAddress returns nil. The range cannot be produced for the other cases where GetAddress returns nil

This is similar to ToSequentialRange except that ToSequentialRange provides a descriptive error when nil is returned.

func (*IPAddressString) GetValidationOptions 

func (addrStr *IPAddressString) GetValidationOptions() addrstrparam.IPAddressStringParams

GetValidationOptions returns the validation options supplied when constructing this address string, or the default options if no options were supplied.

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) 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) 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 string represents a loopback IP address.

func (*IPAddressString) IsMixedIPv6 

func (addrStr *IPAddressString) IsMixedIPv6() bool

IsMixedIPv6 returns whether the lower 4 bytes of the address string are represented as IPv4, if this address string represents an IPv6 address.

func (*IPAddressString) IsPrefixed 

func (addrStr *IPAddressString) IsPrefixed() bool

IsPrefixed returns whether this address string has an associated prefix length. If so, the prefix length is given by GetNetworkPrefixLen()

func (*IPAddressString) IsValid 

func (addrStr *IPAddressString) IsValid() bool

IsValid returns whether this is a valid IP address string format. The accepted IP address formats are: an IPv4 address or subnet, an IPv6 address or subnet, the address representing all addresses of both versions, or an empty string. If this method returns false, and you want more details, call Validate and examine the error.

func (*IPAddressString) IsZero 

func (addrStr *IPAddressString) IsZero() bool

IsZero returns whether this string represents an IP address whose value is exactly zero.

func (*IPAddressString) PrefixContains 

func (addrStr *IPAddressString) PrefixContains(other *IPAddressString) bool

PrefixContains is similar to PrefixEqual, but instead returns whether the prefix of this address contains the same of the given address, using the prefix length of this address. It returns whether the argument address string prefix values of that length are also prefix values in this address string.

In other words, determines if the other address is in one of the same prefix subnets using the prefix length of this address.

If an address has no prefix length, the whole address is used as the prefix.

If this address string or the given address string is invalid, it returns false.

func (*IPAddressString) PrefixEqual 

func (addrStr *IPAddressString) PrefixEqual(other *IPAddressString) bool

PrefixEqual is similar to Equal, but instead returns whether the prefix of this address string matches the same of the given address string, using the prefix length of this address string. It returns whether the argument address string has the same address prefix values as this.

In other words, it determines if the other address has the same prefix subnet using the prefix length of this address.

If an address has no prefix length, the whole address is compared.

If this address string or the given address string is invalid, it returns false.

func (*IPAddressString) String 

func (addrStr *IPAddressString) String() string

String implements the fmt.Stringer interface, returning the original string used to create this IPAddressString (altered by strings.TrimSpace), or "<nil>" if the receiver is a nil pointer

func (*IPAddressString) ToAddress 

func (addrStr *IPAddressString) ToAddress() (*IPAddress, addrerr.AddressError)

ToAddress produces the IPAddress corresponding to this IPAddressString.

If this object does not represent a specific IPAddress or a subnet, nil is returned

If the string used to construct this object is not a known format (empty string, address, or range of addresses) then this method returns an error.

An equivalent method that does not return the error is GetAddress.

If you have a prefixed address and you wish to get only the host rather than the address with the prefix, use ToHostAddress.

The error can be addrerr.AddressStringError or addrerr.IncompatibleAddressError

func (*IPAddressString) ToHostAddress 

func (addrStr *IPAddressString) ToHostAddress() (*IPAddress, addrerr.AddressError)

ToHostAddress parses the address while ignoring the prefix length or mask. The error can be addrerr.AddressStringError for invalid strings or addrerr.IncompatibleAddressError. GetHostAddress is similar but does not return errors. Standard address formats do not result in errors.

func (*IPAddressString) ToNormalizedString 

func (addrStr *IPAddressString) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For IPv4, it is the same as the canonical string.

For IPv6, it differs from the canonical string. Zero segments are not compressed.

If the address has a prefix length, it will be included in the string.

If the original string is not a valid address string, the original string is used.

func (*IPAddressString) ToSequentialRange 

func (addrStr *IPAddressString) ToSequentialRange() (res *IPAddressSeqRange, err addrerr.AddressStringError)

ToSequentialRange returns the range of sequential addresses from the lowest address specified in this address string to the highest.

This is similar to GetSequentialRange except that this method provides a descriptive error when nil is returned. See GetSequentialRange for more details.

func (*IPAddressString) ToVersionedAddress 

func (addrStr *IPAddressString) ToVersionedAddress(version IPVersion) (*IPAddress, addrerr.AddressError)

ToVersionedAddress Produces the IPAddress of the specified address version corresponding to this IPAddressString.

In most cases the string indicates the address version and calling ToAddress() is sufficient, with a few exceptions.

When this object represents only a network prefix length, specifying the address version allows the conversion to take place to the associated mask for that prefix length.

When this object represents all addresses, specifying the address version allows the conversion to take place to the associated representation of all IPv4 or all IPv6 addresses.

When this object represents the empty string and that string is interpreted as a loopback or zero address, then it returns the corresponding address for the given version.

When this object represents an ipv4 or ipv6 address, it returns that address if and only if that address matches the provided version.

If the string used to construct this object is an invalid format, or a format that does not match the provided version, then an error is returned

func (*IPAddressString) Validate 

func (addrStr *IPAddressString) Validate() addrerr.AddressStringError

Validate validates that this string is a valid IP address, returning nil, and if not, returns an error with a descriptive message indicating why it is not.

func (*IPAddressString) ValidateIPv4 

func (addrStr *IPAddressString) ValidateIPv4() addrerr.AddressStringError

ValidateIPv4 validates that this string is a valid IPv4 address, returning nil, and if not, returns an error with a descriptive message indicating why it is not.

func (*IPAddressString) ValidateIPv6 

func (addrStr *IPAddressString) ValidateIPv6() addrerr.AddressStringError

ValidateIPv6 validates that this string is a valid IPv6 address, returning nil, and if not, returns an error with a descriptive message indicating why it is not.

func (*IPAddressString) ValidateVersion 

func (addrStr *IPAddressString) ValidateVersion(version IPVersion) addrerr.AddressStringError

ValidateVersion validates that this string is a valid IP address of the given version. If it is, it returns nil, otherwise it returns an error with a descriptive message indicating why it is not.

func (*IPAddressString) Wrap 

func (addrStr *IPAddressString) Wrap() ExtendedIdentifierString

Wrap wraps this address string, returning a WrappedIPAddressString as an implementation of ExtendedIdentifierString, which can be used to write code that works with different host identifier types polymorphically, including IPAddressString, MACAddressString, and HostName.

type IPAddressType 

type IPAddressType interface {
	AddressType

	// 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 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.
	ToAddressString() *IPAddressString
	// contains filtered or unexported methods
}

IPAddressType represents any IP address, all of which can be represented by the base type IPAddress. This includes IPv4Address and IPv6Address.

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 IPSectionIterator 

type IPSectionIterator interface {
	HasNext

	// Next returns the next address section, or nil if there is none left.
	Next() *IPAddressSection
}

IPSectionIterator iterates through IP address sections

type IPSegmentIterator 

type IPSegmentIterator interface {
	HasNext

	// Next returns the next IP address segment, or nil if there is none left.
	Next() *IPAddressSegment
}

IPSegmentIterator iterates through IP address segments

type IPVersion 

type IPVersion string

IPVersion is the version type used by IP address types. 

const (
	// IndeterminateIPVersion represents an unspecified IP address version
	IndeterminateIPVersion IPVersion = ""

	// IPv4 represents Internet Protocol version 4
	IPv4 IPVersion = "IPv4"

	// IPv6 represents Internet Protocol version 6
	IPv6 IPVersion = "IPv6"
)

func (IPVersion) Equal 

func (version IPVersion) Equal(other IPVersion) bool

Equal returns whether the given version matches this version. Two indeterminate versions always match, even if their associated strings do not.

func (IPVersion) GetBitCount 

func (version IPVersion) GetBitCount() BitCount

GetBitCount returns the number of bits comprising an address of this IP Version.

func (IPVersion) GetBitsPerSegment 

func (version IPVersion) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment for this address version, either 8 or 16 for IPv4 and IPv6 respectively. Segments in the same address are equal length.

func (IPVersion) GetByteCount 

func (version IPVersion) GetByteCount() int

GetByteCount returns the number of bytes comprising an address of this IP Version.

func (IPVersion) GetBytesPerSegment 

func (version IPVersion) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this address or subnet. Segments in the same address are equal length.

func (IPVersion) GetMaxSegmentValue 

func (version IPVersion) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this IP version, determined by the number of bits per segment.

func (IPVersion) GetSegmentCount 

func (version IPVersion) GetSegmentCount() int

GetSegmentCount returns the number of segments comprising an address of this IP Version: 4 for IPv4 and 8 for IPv6.

func (IPVersion) IsIPv4 

func (version IPVersion) IsIPv4() bool

IsIPv4 returns true if this represents version 4

func (IPVersion) IsIPv6 

func (version IPVersion) IsIPv6() bool

IsIPv6 returns true if this represents version 6

func (IPVersion) IsIndeterminate 

func (version IPVersion) IsIndeterminate() bool

IsIndeterminate returns true if this represents an unspecified IP address version

func (IPVersion) String 

func (version IPVersion) String() string

String returns "IPv4", "IPv6", or the zero-value "" representing an indeterminate version

type IPv4Address 

type IPv4Address struct {
	// contains filtered or unexported fields
}

IPv4Address is an IPv4 address, or a subnet of multiple IPv4 addresses. An IPv4 address is composed of 4 1-byte segments and can optionally have an associated prefix length. Each segment can represent a single value or a range of values. The zero value is 0.0.0.0

To construct one from a string, use IPAddressString. For other inputs, use one of multiple constructor functions like NewIPv4Address. You can also use one of multiple constructors for IPAddress like NewIPAddress and then convert using ToIPv4.

func NewIPv4Address 

func NewIPv4Address(section *IPv4AddressSection) (*IPv4Address, addrerr.AddressValueError)

NewIPv4Address constructs an IPv4 address or subnet from the given address section. If the section does not have 4 segments, an error is returned.

func NewIPv4AddressFromBytes 

func NewIPv4AddressFromBytes(bytes []byte) (addr *IPv4Address, err addrerr.AddressValueError)

NewIPv4AddressFromBytes constructs an IPv4 address from the given byte slice. An error is returned when the byte slice has too many bytes to match the IPv4 segment count of 4. There should be 4 bytes or less, although extra leading zeros are tolerated.

func NewIPv4AddressFromPrefixedBytes 

func NewIPv4AddressFromPrefixedBytes(bytes []byte, prefixLength PrefixLen) (addr *IPv4Address, err addrerr.AddressValueError)

NewIPv4AddressFromPrefixedBytes constructs an IPv4 address or prefix block from the given byte slice and prefix length. An error is returned when the byte slice has too many bytes to match the IPv4 segment count of 4. There should be 4 bytes or less, although extra leading zeros are tolerated.

func NewIPv4AddressFromPrefixedRange 

func NewIPv4AddressFromPrefixedRange(vals, upperVals IPv4SegmentValueProvider, prefixLength PrefixLen) *IPv4Address

NewIPv4AddressFromPrefixedRange constructs an IPv4 subnet from the given values and prefix length.

func NewIPv4AddressFromPrefixedSegs 

func NewIPv4AddressFromPrefixedSegs(segments []*IPv4AddressSegment, prefixLength PrefixLen) (*IPv4Address, addrerr.AddressValueError)

NewIPv4AddressFromPrefixedSegs constructs an IPv4 address or subnet from the given segments and prefix length. If the given slice does not have 4 segments, an error is returned.

func NewIPv4AddressFromPrefixedUint32 

func NewIPv4AddressFromPrefixedUint32(val uint32, prefixLength PrefixLen) *IPv4Address

NewIPv4AddressFromPrefixedUint32 constructs an IPv4 address or prefix block from the given value and prefix length.

func NewIPv4AddressFromPrefixedVals 

func NewIPv4AddressFromPrefixedVals(vals IPv4SegmentValueProvider, prefixLength PrefixLen) *IPv4Address

NewIPv4AddressFromPrefixedVals constructs an IPv4 address or prefix block from the given values and prefix length.

func NewIPv4AddressFromRange 

func NewIPv4AddressFromRange(vals, upperVals IPv4SegmentValueProvider) *IPv4Address

NewIPv4AddressFromRange constructs an IPv4 subnet from the given values.

func NewIPv4AddressFromSegs 

func NewIPv4AddressFromSegs(segments []*IPv4AddressSegment) (*IPv4Address, addrerr.AddressValueError)

NewIPv4AddressFromSegs constructs an IPv4 address or subnet from the given segments. If the given slice does not have 4 segments, an error is returned.

func NewIPv4AddressFromUint32 

func NewIPv4AddressFromUint32(val uint32) *IPv4Address

NewIPv4AddressFromUint32 constructs an IPv4 address from the given value.

func NewIPv4AddressFromVals 

func NewIPv4AddressFromVals(vals IPv4SegmentValueProvider) *IPv4Address

NewIPv4AddressFromVals constructs an IPv4 address from the given values.

func (*IPv4Address) AdjustPrefixLen 

func (addr *IPv4Address) AdjustPrefixLen(prefixLen BitCount) *IPv4Address

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*IPv4Address) AdjustPrefixLenZeroed 

func (addr *IPv4Address) AdjustPrefixLenZeroed(prefixLen BitCount) (*IPv4Address, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

For example, 1.2.0.0/16 adjusted by -8 becomes 1.0.0.0/8. 1.2.0.0/16 adjusted by 8 becomes 1.2.0.0/24

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv4Address) AssignMinPrefixForBlock 

func (addr *IPv4Address) AssignMinPrefixForBlock() *IPv4Address

AssignMinPrefixForBlock returns an equivalent subnet, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this subnet.

In other words, this method assigns a prefix length to this subnet matching the largest prefix block in this subnet.

Examples: 1.2.3.4 returns 1.2.3.4/32 1.2.*.* returns 1.2.0.0/16 1.2.*.0/24 returns 1.2.0.0/16 1.2.*.4 returns 1.2.*.4/32 1.2.0-1.* returns 1.2.0.0/23 1.2.1-2.* returns 1.2.1-2.0/24 1.2.252-255.* returns 1.2.252.0/22 1.2.3.4/16 returns 1.2.3.4/32

func (*IPv4Address) AssignPrefixForSingleBlock 

func (addr *IPv4Address) AssignPrefixForSingleBlock() *IPv4Address

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address - it is required that the range of values match the range of a prefix block. If there is no such address, then nil is returned.

Examples: 1.2.3.4 returns 1.2.3.4/32 1.2.*.* returns 1.2.0.0/16 1.2.*.0/24 returns 1.2.0.0/16 1.2.*.4 returns nil 1.2.0-1.* returns 1.2.0.0/23 1.2.1-2.* returns nil 1.2.252-255.* returns 1.2.252.0/22 1.2.3.4/16 returns 1.2.3.4/32

func (*IPv4Address) BitwiseOr 

func (addr *IPv4Address) BitwiseOr(other *IPv4Address) (masked *IPv4Address, err addrerr.IncompatibleAddressError)

BitwiseOr does the bitwise disjunction with this address or subnet, useful when subnetting. It is similar to Mask which does the bitwise conjunction.

The operation is applied to all individual addresses and the result is returned.

If this is a subnet representing multiple addresses, and applying the operation to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned

func (*IPv4Address) BlockIterator 

func (addr *IPv4Address) BlockIterator(segmentCount int) IPv4AddressIterator

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, given the count argument 2, it will iterate through 1.3.5-6.7, 1.4.5-6.7, 2.3.5-6.7, 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 AddressType) int

CompareSize compares the counts of two subnets or addresses, the number of individual addresses within.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing 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, 0 if they are the same, or a negative integer if the other has a larger count.

func (*IPv4Address) Contains 

func (addr *IPv4Address) Contains(other AddressType) bool

Contains returns whether this is the same type and version as the given address or subnet and whether it contains all addresses in the given address or subnet.

func (*IPv4Address) ContainsPrefixBlock 

func (addr *IPv4Address) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or subnet contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPv4Address) ContainsSinglePrefixBlock 

func (addr *IPv4Address) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPv4Address) CopyBytes 

func (addr *IPv4Address) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address in the subnet into a byte slice

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4Address) CopyNetIP 

func (addr *IPv4Address) CopyNetIP(ip net.IP) net.IP

CopyNetIP copies the value of the lowest individual address in the subnet into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4Address) CopySegments 

func (addr *IPv4Address) CopySegments(segs []*IPv4AddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*IPv4Address) CopySubSegments 

func (addr *IPv4Address) CopySubSegments(start, end int, segs []*IPv4AddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*IPv4Address) CopyUpperBytes 

func (addr *IPv4Address) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address in the subnet into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4Address) CopyUpperNetIP 

func (addr *IPv4Address) CopyUpperNetIP(ip net.IP) net.IP

CopyUpperNetIP copies the value of the highest individual address in the subnet into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4Address) CoverWithPrefixBlock 

func (addr *IPv4Address) CoverWithPrefixBlock() *IPv4Address

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the addresses in this subnet. The resulting block will have a larger subnet size than this, unless this subnet is already a prefix block.

func (*IPv4Address) CoverWithPrefixBlockTo 

func (addr *IPv4Address) CoverWithPrefixBlockTo(other *IPv4Address) *IPv4Address

CoverWithPrefixBlockTo returns the minimal-size prefix block that covers all the addresses spanning from this subnet to the given subnet.

func (*IPv4Address) Equal 

func (addr *IPv4Address) Equal(other AddressType) bool

Equal returns whether the given address or subnet is equal to this address or subnet. Two address instances are equal if they represent the same set of addresses.

func (*IPv4Address) ForEachSegment added in v1.2.0 

func (addr *IPv4Address) ForEachSegment(consumer func(segmentIndex int, segment *IPv4AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true. Returns the number of visited segments.

func (IPv4Address) Format 

func (addr IPv4Address) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats 'v' for the default address and section format (either the normalized or canonical string), 's' (string) for the same, 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix), 'd' (decimal), 'x' (lowercase hexadecimal), and 'X' (uppercase hexadecimal). Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which is leading zero for octal and for hexadecimal, 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 1s in the network section and then all 0s in the host section. A CIDR host mask is an address with all 0s in the network section and then all 1s 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

func (*IPv4Address) GetHostMask 

func (addr *IPv4Address) GetHostMask() *IPv4Address

GetHostMask returns the host mask associated with the CIDR network prefix length of this address or subnet. If this address or subnet has no prefix length, then the all-ones mask is returned.

func (*IPv4Address) GetHostSection 

func (addr *IPv4Address) GetHostSection() *IPv4AddressSection

GetHostSection returns a section containing the segments with the host of the address or subnet, the bits beyond the CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

If this series has no prefix length, the returned host section will be the full section.

func (*IPv4Address) GetHostSectionLen 

func (addr *IPv4Address) GetHostSectionLen(prefLen BitCount) *IPv4AddressSection

GetHostSectionLen returns a section containing the segments with the host of the address or subnet, the bits beyond the given CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

func (*IPv4Address) GetIPVersion 

func (addr *IPv4Address) GetIPVersion() IPVersion

GetIPVersion returns IPv4, the IP version of this address

func (*IPv4Address) GetIPv4BlockCount added in v1.2.0 

func (addr *IPv4Address) GetIPv4BlockCount(segmentCount int) uint64

GetIPv4BlockCount returns the count of distinct values in the given number of initial (more significant) segments.

It is similar to GetBlockCount but returns a uint64 instead of a big integer.

func (*IPv4Address) GetIPv4Count added in v1.2.0 

func (addr *IPv4Address) GetIPv4Count() uint64

GetIPv4Count returns the count of possible distinct values for this section. It is the same as GetCount but returns the value as a uint64 instead of a big integer. If not representing multiple values, the count is 1.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv4Address) GetIPv4MappedAddress 

func (addr *IPv4Address) GetIPv4MappedAddress() (*IPv6Address, addrerr.IncompatibleAddressError)

GetIPv4MappedAddress returns the IPv4-mapped IPv6 address corresponding to this IPv4 address. The IPv4-mapped IPv6 address is all zeros in the first 12 bytes, with the last 4 bytes matching the bytes of this IPv4 address. See rfc 5156 for details. If this is a subnet with segment ranges which cannot be converted to two IPv6 segment ranges, than an error is returned.

func (*IPv4Address) GetIPv4PrefixCount added in v1.2.0 

func (addr *IPv4Address) GetIPv4PrefixCount() uint64

GetIPv4PrefixCount returns the number of distinct prefix values in this section. It is the same as GetPrefixCount but returns the value as a uint64 instead of a big integer.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetIPv4Count

func (*IPv4Address) GetIPv4PrefixCountLen added in v1.2.0 

func (addr *IPv4Address) GetIPv4PrefixCountLen(prefixLength BitCount) uint64

GetIPv4PrefixCountLen gives count available as a uint64 instead of big.Int

It is the similar to GetPrefixCountLen but returns a uint64, not a *big.Int

func (*IPv4Address) GetIPv6Address 

func (addr *IPv4Address) GetIPv6Address(section *IPv6AddressSection) (*IPv6Address, addrerr.AddressError)

GetIPv6Address creates an IPv6 mixed address using the given ipv6 segments and using this address for the embedded IPv4 segments

func (*IPv4Address) GetLeadingBitCount 

func (addr *IPv4Address) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower value of the range if this is a subnet representing multiple values.

func (*IPv4Address) GetLower 

func (addr *IPv4Address) GetLower() *IPv4Address

GetLower returns the lowest address in the subnet range, which will be the receiver if it represents a single address. For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned.

func (*IPv4Address) GetLowerIPAddress 

func (addr *IPv4Address) GetLowerIPAddress() *IPAddress

GetLowerIPAddress returns the address in the subnet or address collection with the lowest numeric value, which will be the receiver if it represents a single address. For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned. GetLowerIPAddress implements the IPAddressRange interface

func (*IPv4Address) GetMaxSegmentValue 

func (addr *IPv4Address) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPv4Address) GetMinPrefixLenForBlock 

func (addr *IPv4Address) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

func (*IPv4Address) GetNetIP 

func (addr *IPv4Address) GetNetIP() net.IP

GetNetIP returns the lowest address in this subnet or address as a net.IP

func (*IPv4Address) GetNetIPAddr added in v1.2.0 

func (addr *IPv4Address) GetNetIPAddr() *net.IPAddr

GetNetIPAddr returns the lowest address in this subnet or address as a net.IPAddr

func (*IPv4Address) 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.

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 null 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 index 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 series "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 "1.2-3.4.5-6", the series "1.3.4.6" is returned. GetUpperIPAddress implements the IPAddressRange interface

func (*IPv4Address) GetUpperNetIP 

func (addr *IPv4Address) GetUpperNetIP() net.IP

GetUpperNetIP returns the highest address in this subnet or address as a net.IP

func (*IPv4Address) GetUpperNetIPAddr added in v1.2.0 

func (addr *IPv4Address) GetUpperNetIPAddr() *net.IPAddr

GetUpperNetIPAddr returns the highest address in this subnet or address as a net.IPAddr

func (*IPv4Address) GetUpperValue 

func (addr *IPv4Address) GetUpperValue() *big.Int

GetUpperValue returns the highest address in this subnet or address as an integer value

func (*IPv4Address) GetValue 

func (addr *IPv4Address) GetValue() *big.Int

GetValue returns the lowest address in this subnet or address as an integer value

func (*IPv4Address) IncludesMax 

func (addr *IPv4Address) IncludesMax() bool

IncludesMax returns whether this address includes the max address, the address whose bits are all ones, within its range

func (*IPv4Address) IncludesMaxHost 

func (addr *IPv4Address) IncludesMaxHost() bool

IncludesMaxHost returns whether the subnet contains an individual address with a host of all one-bits. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are one.

func (*IPv4Address) IncludesMaxHostLen 

func (addr *IPv4Address) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the subnet contains an individual address with a host of all one-bits, an individual address for which all bits past the given prefix length are all ones.

func (*IPv4Address) IncludesZeroHost 

func (addr *IPv4Address) IncludesZeroHost() bool

IncludesZeroHost returns whether the subnet contains an individual address with a host of zero. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are zero.

func (*IPv4Address) IncludesZeroHostLen 

func (addr *IPv4Address) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the subnet contains an individual address with a host of zero, an individual address for which all bits past the given prefix length are zero.

func (*IPv4Address) Increment 

func (addr *IPv4Address) Increment(increment int64) *IPv4Address

Increment returns the address from the subnet that is the given increment upwards into the subnet range, with the increment of 0 returning the first address in the range.

If the increment i matches or exceeds the subnet size count c, then i - c + 1 is added to the upper address of the range. An increment matching the subnet count gives you the address just above the highest address in the subnet.

If the increment is negative, it is added to the lower address of the range. To get the address just below the lowest address of the subnet, use the increment -1.

If this is just a single address value, the address is simply incremented by the given increment, positive or negative.

If this is a subnet with multiple values, a positive increment i is equivalent i + 1 values from the subnet iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the subnet count is equivalent to the same number of iterator values preceding the upper bound of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On address overflow or underflow, Increment returns nil.

func (*IPv4Address) IncrementBoundary 

func (addr *IPv4Address) IncrementBoundary(increment int64) *IPv4Address

IncrementBoundary returns the address that is the given increment from the range boundaries of this subnet.

If the given increment is positive, adds the value to the upper address (GetUpper) in the subnet range to produce a new address. If the given increment is negative, adds the value to the lower address (GetLower) in the subnet range to produce a new address. If the increment is zero, returns this address.

If this is a single address value, that address is simply incremented by the given increment value, positive or negative.

On address overflow or underflow, IncrementBoundary returns nil.

func (*IPv4Address) Intersect 

func (addr *IPv4Address) Intersect(other *IPv4Address) *IPv4Address

Intersect returns the subnet whose addresses are found in both this and the given subnet argument, or nil if no such addresses exist.

This is also known as the conjunction of the two sets of addresses.

func (*IPv4Address) IsAnyLocal 

func (addr *IPv4Address) IsAnyLocal() bool

IsAnyLocal returns whether this address is the address which binds to any address on the local host. This is the address that has the value of 0, aka the unspecified address.

func (*IPv4Address) IsFullRange added in v1.2.0 

func (addr *IPv4Address) IsFullRange() bool

IsFullRange returns whether this address covers the entire IPv4 address space.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv4Address) IsLinkLocal 

func (addr *IPv4Address) IsLinkLocal() bool

IsLinkLocal returns whether the address is link local, whether unicast or multicast.

func (*IPv4Address) IsLocal 

func (addr *IPv4Address) IsLocal() bool

IsLocal returns true if the address is link local, site local, organization local, administered locally, or unspecified. This includes both unicast and multicast.

func (*IPv4Address) IsLoopback 

func (addr *IPv4Address) IsLoopback() bool

IsLoopback returns whether this address is a loopback address, such as 127.0.0.1

func (*IPv4Address) IsMax 

func (addr *IPv4Address) IsMax() bool

IsMax returns whether this address matches exactly the maximum possible value, the address whose bits are all ones

func (*IPv4Address) IsMaxHost 

func (addr *IPv4Address) IsMaxHost() bool

IsMaxHost returns whether this section has a prefix length and if so, whether the host section is always all one-bits, the max value, for all individual addresses in this subnet.

If the host section is zero length (there are zero host bits), IsMaxHost returns true.

func (*IPv4Address) IsMaxHostLen 

func (addr *IPv4Address) IsMaxHostLen(prefLen BitCount) bool

IsMaxHostLen returns whether the host is all one-bits, the max value, for all individual addresses in this subnet, for the given prefix length, the host being the bits following the prefix.

If the host section is zero length (there are zero host bits), IsMaxHostLen returns true.

func (*IPv4Address) IsMulticast 

func (addr *IPv4Address) IsMulticast() bool

IsMulticast returns whether this address or subnet is entirely multicast

func (*IPv4Address) IsMultiple 

func (addr *IPv4Address) IsMultiple() bool

IsMultiple returns true if this represents more than a single individual address, whether it is a subnet of multiple addresses.

func (*IPv4Address) IsOneBit 

func (addr *IPv4Address) IsOneBit(bitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex < 0, 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 prefix lengths 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 return false for this method and returns true for 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() IPv4AddressIterator

Iterator provides an iterator to iterate through the individual addresses of this address or subnet.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual addresses.

Call IsMultiple to determine if this instance represents multiple addresses, or GetCount for the count.

func (*IPv4Address) Mask 

func (addr *IPv4Address) Mask(other *IPv4Address) (masked *IPv4Address, err addrerr.IncompatibleAddressError)

Mask applies the given mask to all addresses represented by this IPv4Address. The mask is applied to all individual addresses.

If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned

func (*IPv4Address) MatchesWithMask 

func (addr *IPv4Address) MatchesWithMask(other *IPv4Address, mask *IPv4Address) bool

MatchesWithMask applies the mask to this address and then compares the result with the given address, returning true if they match, false otherwise.

func (*IPv4Address) MergeToPrefixBlocks 

func (addr *IPv4Address) MergeToPrefixBlocks(addrs ...*IPv4Address) []*IPv4Address

MergeToPrefixBlocks merges this subnet with the list of subnets to produce the smallest array of CIDR prefix blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv4Address) MergeToSequentialBlocks 

func (addr *IPv4Address) MergeToSequentialBlocks(addrs ...*IPv4Address) []*IPv4Address

MergeToSequentialBlocks merges this with the list of addresses to produce the smallest array of sequential blocks

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv4Address) PrefixBlockIterator 

func (addr *IPv4Address) PrefixBlockIterator() IPv4AddressIterator

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() IPv4AddressIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this subnet, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this subnet.

If the subnet has no prefix length, then this is equivalent to Iterator.

func (*IPv4Address) Replace 

func (addr *IPv4Address) Replace(startIndex int, replacement *IPv4AddressSection) *IPv4Address

Replace replaces segments starting from startIndex with segments from the replacement section. Mappings to or from indices outside the range of this address or the replacement section are skipped.

func (*IPv4Address) ReplaceLen 

func (addr *IPv4Address) ReplaceLen(startIndex, endIndex int, replacement *IPv4Address, replacementIndex int) *IPv4Address

ReplaceLen replaces segments starting from startIndex and ending before endIndex with the same number of segments starting at replacementStartIndex from the replacement section Mappings to or from indices outside the range of this or the replacement address are skipped.

func (*IPv4Address) ReverseBits 

func (addr *IPv4Address) ReverseBits(perByte bool) (*IPv4Address, addrerr.IncompatibleAddressError)

ReverseBits returns a new address with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv4Address) ReverseBytes 

func (addr *IPv4Address) ReverseBytes() *IPv4Address

ReverseBytes returns a new address with the bytes reversed. Any prefix length is dropped.

func (*IPv4Address) ReverseSegments 

func (addr *IPv4Address) ReverseSegments() *IPv4Address

ReverseSegments returns a new address with the segments reversed.

func (*IPv4Address) SequentialBlockIterator 

func (addr *IPv4Address) SequentialBlockIterator() IPv4AddressIterator

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, 2.4.6.7-8.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPv4Address) SetPrefixLen 

func (addr *IPv4Address) SetPrefixLen(prefixLen BitCount) *IPv4Address

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPv4Address) SetPrefixLenZeroed 

func (addr *IPv4Address) SetPrefixLenZeroed(prefixLen BitCount) (*IPv4Address, addrerr.IncompatibleAddressError)

func (*IPv4Address) SpanWithPrefixBlocks 

func (addr *IPv4Address) SpanWithPrefixBlocks() []*IPv4Address

SpanWithPrefixBlocks returns an array of prefix blocks that cover the same set of addresses as this subnet.

Unlike SpanWithPrefixBlocksTo, the result only includes addresses that are a part of this subnet.

func (*IPv4Address) SpanWithPrefixBlocksTo 

func (addr *IPv4Address) SpanWithPrefixBlocksTo(other *IPv4Address) []*IPv4Address

SpanWithPrefixBlocksTo returns the smallest slice of prefix block subnets that span from this subnet to the given subnet.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

From the list of returned subnets you can recover the original range (this to other) by converting each to IPAddressRange with ToSequentialRange and them joining them into a single range with the Join method of IPAddressSeqRange.

func (*IPv4Address) SpanWithRange 

func (addr *IPv4Address) SpanWithRange(other *IPv4Address) *IPv4AddressSeqRange

SpanWithRange returns an IPv4AddressSeqRange instance that spans this subnet to the given subnet. If the other address is a different version than this, then the other is ignored, and the result is equivalent to calling ToSequentialRange.

func (*IPv4Address) SpanWithSequentialBlocks 

func (addr *IPv4Address) SpanWithSequentialBlocks() []*IPv4Address

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of addresses as this subnet.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

Unlike SpanWithSequentialBlocksTo, this method only includes addresses that are a part of this subnet.

func (*IPv4Address) SpanWithSequentialBlocksTo 

func (addr *IPv4Address) SpanWithSequentialBlocksTo(other *IPv4Address) []*IPv4Address

SpanWithSequentialBlocksTo produces the smallest slice of sequential block subnets that span all values from this subnet to the given subnet. The span will cover all addresses in both subnets and everything in between.

Individual block subnets come in the form 1-3.1-4.5.6-8, however that particular subnet is not sequential since address 1.1.5.8 is in the subnet, the next sequential address 1.1.5.9 is not in the subnet, and a higher address 1.2.5.6 is in the subnet. Blocks are sequential when the first segment with a range of values is followed by segments that span all values.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv4Address) String 

func (addr *IPv4Address) String() string

String implements the fmt.Stringer interface, returning the canonical string provided by ToCanonicalString, or "<nil>" if the receiver is a nil pointer

func (*IPv4Address) Subtract 

func (addr *IPv4Address) Subtract(other *IPv4Address) []*IPv4Address

Subtract subtracts the given subnet from this subnet, returning an array of subnets for the result (the subnets will not be contiguous so an array is required). Subtract computes the subnet difference, the set of addresses in this address subnet but not in the provided subnet. This is also known as the relative complement of the given argument in this subnet. This is set subtraction, not subtraction of address values (use Increment for the latter). We have a subnet of addresses and we are removing those addresses found in the argument subnet. If there are no remaining addresses, nil is returned.

func (*IPv4Address) TestBit 

func (addr *IPv4Address) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this address. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv4Address) ToAddressBase 

func (addr *IPv4Address) ToAddressBase() *Address

ToAddressBase converts to an Address, a polymorphic type usable with all addresses and subnets. Afterwards, you can convert back with ToIPv4.

ToAddressBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4Address) ToAddressString 

func (addr *IPv4Address) ToAddressString() *IPAddressString

ToAddressString retrieves or generates an IPAddressString instance for this IPAddress instance. This may be the IPAddressString this instance was generated from, if it was generated from an IPAddressString.

In general, users are intended to create IPAddress instances from IPAddressString instances, while the reverse direction is generally not common and not useful, except under specific circumstances.

However, the reverse direction can be useful under certain circumstances, such as when maintaining a collection of HostIdentifierString instances.

func (*IPv4Address) ToBinaryString 

func (addr *IPv4Address) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4Address) ToBlock 

func (addr *IPv4Address) ToBlock(segmentIndex int, lower, upper SegInt) *IPv4Address

ToBlock creates a new block of addresses by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPv4Address) ToBroadcastAddress 

func (addr *IPv4Address) ToBroadcastAddress() (*IPv4Address, addrerr.IncompatibleAddressError)

ToBroadcastAddress returns the IPv4 broadcast address. The broadcast address has the same prefix but a host that is all 1 bits. If this address or subnet is not prefixed, this returns the address of all 1 bits, the "max" address. This returns an error if a prefixed and ranged-valued segment cannot be converted to a host of all ones and remain a range of consecutive values.

func (*IPv4Address) ToCanonicalString 

func (addr *IPv4Address) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address.

For IPv4, dotted octet format, also known as dotted decimal format, is used. https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1

Each address has a unique canonical string, not counting the prefix length. With IP addresses, the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use ToCanonicalWildcardString for a unique string for each IP address and subnet.

func (*IPv4Address) ToCanonicalWildcardString 

func (addr *IPv4Address) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string and avoids the CIDR prefix length. Addresses and subnets with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPv4Address) ToCompressedString 

func (addr *IPv4Address) ToCompressedString() string

ToCompressedString produces a short representation of this address while remaining within the confines of standard representation(s) of the address.

For IPv4, it is the same as the canonical string.

func (*IPv4Address) ToCompressedWildcardString 

func (addr *IPv4Address) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, and in fact for IPv4 it is the same as ToNormalizedWildcardString.

func (*IPv4Address) ToCustomString 

func (addr *IPv4Address) ToCustomString(stringOptions addrstr.IPStringOptions) string

ToCustomString creates a customized string from this address or subnet according to the given string option parameters

func (*IPv4Address) ToFullString 

func (addr *IPv4Address) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 3 characters for IPv4 segments.

func (*IPv4Address) ToHexString 

func (addr *IPv4Address) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4Address) ToIP 

func (addr *IPv4Address) ToIP() *IPAddress

ToIP converts to an IPAddress, a polymorphic type usable with all IP addresses and subnets. Afterwards, you can convert back with ToIPv4.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4Address) ToInetAtonJoinedString 

func (addr *IPv4Address) ToInetAtonJoinedString(radix Inet_aton_radix, joinedCount int) (string, addrerr.IncompatibleAddressError)

ToInetAtonJoinedString returns a string with a format that is styled from the inet_aton routine. The string can have an octal or hexadecimal radix rather than decimal, and can have less than the typical four IPv4 segments by joining the least significant segments together, resulting in a string which just 1, 2 or 3 divisions.

When using octal, the octal segments each have a leading zero prefix of "0", and when using hex, a prefix of "0x".

If this represents a subnet section, this returns an error when unable to join two or more segments into a division of a larger bit-length that represents the same set of values.

func (*IPv4Address) ToInetAtonString 

func (addr *IPv4Address) ToInetAtonString(radix Inet_aton_radix) string

ToInetAtonString returns a string with a format that is styled from the inet_aton routine. The string can have an octal or hexadecimal radix rather than decimal. When using octal, the octal segments each have a leading zero prefix of "0", and when using hex, a prefix of "0x".

func (*IPv4Address) ToKey added in v1.1.0 

func (addr *IPv4Address) ToKey() *IPv4AddressKey

ToKey creates the associated address key. While addresses can be compared with the Compare, TrieCompare or Equal methods as well as various provided instances of AddressComparator, they are not comparable with go operators. However, IPv4AddressKey instances are comparable with go operators, and thus can be used as map keys.

func (*IPv4Address) ToMaxHost 

func (addr *IPv4Address) ToMaxHost() (*IPv4Address, addrerr.IncompatibleAddressError)

ToMaxHost converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-ones address, the max address.

The returned address or subnet will have the same prefix and prefix length.

For instance, the max host of 1.2.3.4/16 gives the broadcast address 1.2.255.255/16.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv4Address) ToMaxHostLen 

func (addr *IPv4Address) ToMaxHostLen(prefixLength BitCount) (*IPv4Address, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the resulting one will too, otherwise the resulting address or subnet will have no prefix length.

For instance, the zero host of 1.2.3.4 for the prefix length 16 is the address 1.2.255.255.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv4Address) ToNetworkAddress 

func (addr *IPv4Address) ToNetworkAddress() (*IPv4Address, addrerr.IncompatibleAddressError)

ToNetworkAddress returns the IPv4 network address. The network address has the same prefix but a zero host. If this address or subnet is not prefixed, this returns the zero "any" address. This returns an error if a prefixed and ranged-valued segment cannot be converted to a host of all zeros and remain a range of consecutive values.

func (*IPv4Address) ToNormalizedString 

func (addr *IPv4Address) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For IPv4, it is the same as the canonical string.

Each address has a unique normalized string, not counting the prefix length. With IP addresses, the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use the method ToNormalizedWildcardString for a unique string for each IP address and subnet.

func (*IPv4Address) ToNormalizedWildcardString 

func (addr *IPv4Address) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPv4Address) ToOctalString 

func (addr *IPv4Address) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4Address) ToPrefixBlock 

func (addr *IPv4Address) ToPrefixBlock() *IPv4Address

ToPrefixBlock returns the subnet associated with the prefix length of this address. If this address has no prefix length, this address is returned.

The subnet will include all addresses with the same prefix as this one, the prefix "block". The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is 1.2.3.4/16 it returns the subnet 1.2.0.0/16 which can also be written as 1.2.*.*/16

func (*IPv4Address) ToPrefixBlockLen 

func (addr *IPv4Address) ToPrefixBlockLen(prefLen BitCount) *IPv4Address

ToPrefixBlockLen returns the subnet associated with the given prefix length.

The subnet will include all addresses with the same prefix as this one, the prefix "block" for that prefix length. The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is 1.2.3.4 and the prefix length provided is 16, it returns the subnet 1.2.0.0/16 which can also be written as 1.2.*.*/16

func (*IPv4Address) ToPrefixLenString 

func (addr *IPv4Address) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, a zero host section will be compressed with ::. For IPv4 the string is equivalent to the canonical string.

func (*IPv4Address) ToReverseDNSString 

func (addr *IPv4Address) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse DNS lookup string. For IPV4, the error is always nil. For 8.255.4.4 it is 4.4.255.8.in-addr.arpa

func (*IPv4Address) ToSQLWildcardString 

func (addr *IPv4Address) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the wildcard '_'..

func (*IPv4Address) ToSegmentedBinaryString 

func (addr *IPv4Address) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this address as segments of binary values preceded by the "0b" prefix.

func (*IPv4Address) ToSequentialRange 

func (addr *IPv4Address) ToSequentialRange() *IPv4AddressSeqRange

ToSequentialRange creates a sequential range instance from the lowest and highest addresses in this subnet

The two will represent the same set of individual addresses if and only if IsSequential is true. To get a series of ranges that represent the same set of individual addresses use the SequentialBlockIterator (or PrefixIterator), and apply this method to each iterated subnet.

If this represents just a single address then the returned instance covers just that single address as well.

func (*IPv4Address) ToSinglePrefixBlockOrAddress added in v1.1.0 

func (addr *IPv4Address) ToSinglePrefixBlockOrAddress() *IPv4Address

ToSinglePrefixBlockOrAddress converts to a single prefix block or address. If the given address is a single prefix block, it is returned. If it can be converted to a single prefix block by assigning a prefix length, the converted block is returned. If it is a single address, any prefix length is removed and the address is returned. Otherwise, nil is returned. This method provides the address formats used by tries. ToSinglePrefixBlockOrAddress is quite similar to AssignPrefixForSingleBlock, which always returns prefixed addresses, while this does not.

func (*IPv4Address) ToSubnetString 

func (addr *IPv4Address) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like 1.2.*.* or 1:2::/16

In the case of IPv4, this means that wildcards are used instead of a network prefix when a network prefix has been supplied.

func (*IPv4Address) ToZeroHost 

func (addr *IPv4Address) ToZeroHost() (*IPv4Address, addrerr.IncompatibleAddressError)

ToZeroHost converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix and prefix length.

For instance, the zero host of 1.2.3.4/16 is the individual address 1.2.0.0/16.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv4Address) ToZeroHostLen 

func (addr *IPv4Address) ToZeroHostLen(prefixLength BitCount) (*IPv4Address, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.

For instance, the zero host of 1.2.3.4 for the prefix length 16 is the address 1.2.0.0.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv4Address) ToZeroNetwork 

func (addr *IPv4Address) ToZeroNetwork() *IPv4Address

ToZeroNetwork converts the address or subnet to one in which all individual addresses have a network of zero, the network being the bits within the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix length.

func (*IPv4Address) TrieCompare added in v1.1.0 

func (addr *IPv4Address) TrieCompare(other *IPv4Address) int

TrieCompare compares two addresses according to address trie ordering. It returns a number less than zero, zero, or a number greater than zero if the first address argument is less than, equal to, or greater than the second.

The comparison is intended for individual addresses and CIDR prefix blocks. If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv4Address) TrieDecrement added in v1.1.0 

func (addr *IPv4Address) TrieDecrement() *IPv4Address

TrieDecrement returns the previous address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv4Address) TrieIncrement added in v1.1.0 

func (addr *IPv4Address) TrieIncrement() *IPv4Address

TrieIncrement returns the next address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv4Address) Uint32Value 

func (addr *IPv4Address) Uint32Value() uint32

Uint32Value returns the lowest address in the subnet range as a uint32

func (*IPv4Address) UpperBytes 

func (addr *IPv4Address) UpperBytes() []byte

UpperBytes returns the highest address in this subnet or address as a byte slice

func (*IPv4Address) UpperUint32Value 

func (addr *IPv4Address) UpperUint32Value() uint32

UpperUint32Value returns the highest address in the subnet range as a uint32

func (*IPv4Address) WithoutPrefixLen 

func (addr *IPv4Address) WithoutPrefixLen() *IPv4Address

WithoutPrefixLen provides the same address but with no prefix length. The values remain unchanged.

func (*IPv4Address) Wrap 

func (addr *IPv4Address) Wrap() WrappedIPAddress

Wrap wraps this IP address, returning a WrappedIPAddress, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address.

func (*IPv4Address) WrapAddress added in v1.2.0 

func (addr *IPv4Address) WrapAddress() WrappedAddress

WrapAddress wraps this IP address, returning a WrappedAddress, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapAddress can be called with a nil receiver, wrapping a nil address.

type IPv4AddressAssociativeTrie added in v1.1.0 

type IPv4AddressAssociativeTrie struct {
	// contains filtered or unexported fields
}

IPv4AddressAssociativeTrie represents an IPv4 address associative binary trie.

The keys are IPv4 addresses or prefix blocks. Each can be mapped to a value.

The zero value for IPv4AddressAssociativeTrie is a binary trie ready for use.

func NewIPv4AddressAssociativeTrie added in v1.1.0 

func NewIPv4AddressAssociativeTrie() *IPv4AddressAssociativeTrie

NewIPv4AddressAssociativeTrie constructs an IPv4 associative address trie with the root as the 0.0.0.0/0 prefix block

func (*IPv4AddressAssociativeTrie) Add added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) Add(addr *IPv4Address) bool

Add adds the given address key to the trie, returning true if not there already.

func (*IPv4AddressAssociativeTrie) AddNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) AddNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

AddNode adds the address key to this trie. The new or existing node for the address is returned.

func (*IPv4AddressAssociativeTrie) AddTrie added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) AddTrie(added *IPv4AddressAssociativeTrieNode) *IPv4AddressAssociativeTrieNode

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.

func (*IPv4AddressAssociativeTrie) AddedNodesTreeString added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) 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 (*IPv4AddressAssociativeTrie) AllNodeIterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) AllNodeIterator(forward bool) IPv4AssociativeTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates the added all nodes in the trie following the natural trie order

func (*IPv4AddressAssociativeTrie) BlockSizeAllNodeIterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IPv4AssociativeTrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*IPv4AddressAssociativeTrie) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) BlockSizeCachingAllNodeIterator() CachingIPv4AssociativeTrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

func (*IPv4AddressAssociativeTrie) BlockSizeNodeIterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) BlockSizeNodeIterator(lowerSubNodeFirst bool) IPv4AssociativeTrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*IPv4AddressAssociativeTrie) CeilingAddedNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) CeilingAddedNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 tree

func (*IPv4AddressAssociativeTrie) Clone added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) Clone() *IPv4AddressAssociativeTrie

Clone clones this trie

func (*IPv4AddressAssociativeTrie) ConstructAddedNodesTree added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ConstructAddedNodesTree() *IPv4AddressAssociativeTrie

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. 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 (*IPv4AddressAssociativeTrie) ContainedFirstAllNodeIterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) IPv4AssociativeTrieNodeIterator

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 (*IPv4AddressAssociativeTrie) ContainedFirstIterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ContainedFirstIterator(forwardSubNodeOrder bool) IPv4AssociativeTrieNodeIteratorRem

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 (*IPv4AddressAssociativeTrie) ContainingFirstAllNodeIterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingIPv4AssociativeTrieNodeIterator

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 and linear space (proportional to tree size).

func (*IPv4AddressAssociativeTrie) ContainingFirstIterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ContainingFirstIterator(forwardSubNodeOrder bool) CachingIPv4AssociativeTrieNodeIterator

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 and linear space (proportional to tree size).

func (*IPv4AddressAssociativeTrie) Contains added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) Contains(addr *IPv4Address) 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 (*IPv4AddressAssociativeTrie) DeepEqual added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) DeepEqual(other *IPv4AddressAssociativeTrie) 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 (*IPv4AddressAssociativeTrie) DescendingIterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) DescendingIterator() IPv4AddressIterator

DescendingIterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in reverse sorted element order.

func (*IPv4AddressAssociativeTrie) ElementContains added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ElementContains(addr *IPv4Address) 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 (*IPv4AddressAssociativeTrie) ElementsContainedBy added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ElementsContainedBy(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrie) ElementsContaining added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ElementsContaining(addr *IPv4Address) *ContainmentPath

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 (*IPv4AddressAssociativeTrie) Equal added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) Equal(other *IPv4AddressAssociativeTrie) bool

Equal returns whether the given argument is a trie with a set of nodes with the same keys as in this trie

func (*IPv4AddressAssociativeTrie) FirstAddedNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) FirstAddedNode() *IPv4AddressAssociativeTrieNode

FirstAddedNode returns the first (lowest-valued) added node in the trie or nil if there are no added entries in this tree

func (*IPv4AddressAssociativeTrie) FirstNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) FirstNode() *IPv4AddressAssociativeTrieNode

FirstNode returns the first (lowest-valued) node in the trie or nil if the trie is empty

func (*IPv4AddressAssociativeTrie) FloorAddedNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) FloorAddedNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 tree

func (IPv4AddressAssociativeTrie) Format added in v1.1.0 

func (trie IPv4AddressAssociativeTrie) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*IPv4AddressAssociativeTrie) Get added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) Get(addr *IPv4Address) NodeValue

Get gets the specified 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 (*IPv4AddressAssociativeTrie) GetAddedNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) GetAddedNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrie) GetNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) GetNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrie) GetRoot added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) GetRoot() *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrie) HigherAddedNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) HigherAddedNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 tree

func (*IPv4AddressAssociativeTrie) IsEmpty added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) IsEmpty() bool

IsEmpty returns true if there are not any added nodes within this tree

func (*IPv4AddressAssociativeTrie) Iterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) Iterator() IPv4AddressIterator

Iterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in sorted element order.

func (*IPv4AddressAssociativeTrie) LastAddedNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) LastAddedNode() *IPv4AddressAssociativeTrieNode

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 tree

func (*IPv4AddressAssociativeTrie) LastNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) LastNode() *IPv4AddressAssociativeTrieNode

LastNode returns the last (highest-valued) node in the trie or nil if the trie is empty

func (*IPv4AddressAssociativeTrie) LongestPrefixMatch added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) LongestPrefixMatch(addr *IPv4Address) *IPv4Address

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 (*IPv4AddressAssociativeTrie) LongestPrefixMatchNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) LongestPrefixMatchNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrie) LowerAddedNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) LowerAddedNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 tree

func (*IPv4AddressAssociativeTrie) NodeIterator added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) NodeIterator(forward bool) IPv4AssociativeTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through all the added nodes in the trie in forward or reverse tree order.

func (*IPv4AddressAssociativeTrie) NodeSize added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) NodeSize() int

NodeSize returns the number of nodes in the tree, which is always more than the number of elements.

func (*IPv4AddressAssociativeTrie) Put added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) Put(addr *IPv4Address, value NodeValue) (bool, NodeValue)

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 (*IPv4AddressAssociativeTrie) PutNode added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) PutNode(addr *IPv4Address, value NodeValue) *IPv4AddressAssociativeTrieNode

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 tree 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 (*IPv4AddressAssociativeTrie) PutTrie added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) PutTrie(added *IPv4AddressAssociativeTrieNode) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrie) Remap added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) Remap(addr *IPv4Address, remapper func(NodeValue) NodeValue) *IPv4AddressAssociativeTrieNode

Remap remaps node values in the trie.

This will lookup the node corresponding to the given key. It will call the remapping function with the key as the first argument, regardless of whether the node is found or not.

If the node is not found, the value argument will be nil. If the node is found, the value argument will be the node's value, which can also be nil.

If the remapping function returns nil, then the matched node will be removed, if any. If it returns a non-nil value, then it will either set the existing node to have that value, or if there was no matched node, it will create a new node with that 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 value specifies changes to be made, then the trie will not be changed and a panic will ensue.

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 (*IPv4AddressAssociativeTrie) RemapIfAbsent added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) RemapIfAbsent(addr *IPv4Address, supplier func() NodeValue, insertNil bool) *IPv4AddressAssociativeTrieNode

RemapIfAbsent remaps node values in the trie, but only for nodes that do not exist or are mapped to nil.

This will look up the node corresponding to the given key. If the node is not found or mapped to nil, this will call the remapping function.

If the remapping function returns a non-nil value, then it will either set the existing node to have that value, or if there was no matched node, it will create a new node with that value. If the remapping function returns nil, then it will do the same if insertNil is true, otherwise it will do nothing.

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 value specifies changes to be made, then the trie will not be changed and ConcurrentModificationException will be thrown instead.

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.

insertNull indicates whether nil values returned from remapper should be inserted into the map, or whether nil values indicate no remapping

func (*IPv4AddressAssociativeTrie) Remove added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) Remove(addr *IPv4Address) 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.

func (*IPv4AddressAssociativeTrie) RemoveElementsContainedBy added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) RemoveElementsContainedBy(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrie) Size added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) 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 (*IPv4AddressAssociativeTrie) String added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) String() string

String returns a visual representation of the tree with one node per line.

func (*IPv4AddressAssociativeTrie) ToAssociativeBase added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ToAssociativeBase() *AssociativeAddressTrie

ToAssociativeBase converts to the polymorphic associative trie representation of this trie

func (*IPv4AddressAssociativeTrie) ToBase added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ToBase() *AddressTrie

ToBase converts to the polymorphic non-associative representation of this trie

func (*IPv4AddressAssociativeTrie) ToIPv4Base added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) ToIPv4Base() *IPv4AddressTrie

ToIPv4Base converts to the non-associative representation of this trie

func (*IPv4AddressAssociativeTrie) TreeString added in v1.1.0 

func (trie *IPv4AddressAssociativeTrie) 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 IPv4AddressAssociativeTrieNode added in v1.1.0 

type IPv4AddressAssociativeTrieNode struct {
	// contains filtered or unexported fields
}

IPv4AddressAssociativeTrieNode is a node in an IPv4AddressAssociativeTrie.

In an associative trie, each key or node can be associated with a value.

Trie nodes are created by tries during add or put operations.

If a trie node is copied, a panic will result when methods that alter the trie are called on the copied node.

Iterator methods allow for traversal of the sub-trie with this node as the root.

If an iterator is advanced following a trie modification that followed the creation of the iterator, the iterator will panic.

func (*IPv4AddressAssociativeTrieNode) AllNodeIterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) AllNodeIterator(forward bool) IPv4AssociativeTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*IPv4AddressAssociativeTrieNode) AsNewTrie added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) AsNewTrie() *IPv4AddressAssociativeTrie

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 (*IPv4AddressAssociativeTrieNode) BlockSizeAllNodeIterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IPv4AssociativeTrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all the nodes, ordered by keys from the largest prefix blocks to the 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 (*IPv4AddressAssociativeTrieNode) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) BlockSizeCachingAllNodeIterator() CachingIPv4AssociativeTrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest and then to individual addresses, in the sub-trie with this node as the root.

func (*IPv4AddressAssociativeTrieNode) BlockSizeNodeIterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) BlockSizeNodeIterator(lowerSubNodeFirst bool) IPv4AssociativeTrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes, ordered by keys from the largest prefix blocks to the 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 (*IPv4AddressAssociativeTrieNode) CeilingAddedNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) CeilingAddedNode(addr *Address) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrieNode) Clear added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) Clear()

Clear removes this node and all sub-nodes from the tree, after which isEmpty() will return true.

func (*IPv4AddressAssociativeTrieNode) ClearValue added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ClearValue()

ClearValue makes the value associated with this node the nil value

func (*IPv4AddressAssociativeTrieNode) Clone added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) Clone() *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrieNode) CloneTree added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) CloneTree() *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrieNode) Compare added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) Compare(other *IPv4AddressAssociativeTrieNode) int

Compare returns -1, 0 or 1 if this node is less than, equal, or greater than the other, according to the key and the trie order.

func (*IPv4AddressAssociativeTrieNode) ContainedFirstAllNodeIterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) IPv4AssociativeTrieNodeIterator

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary tree 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 (*IPv4AddressAssociativeTrieNode) ContainedFirstIterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ContainedFirstIterator(forwardSubNodeOrder bool) IPv4AssociativeTrieNodeIteratorRem

ContainedFirstIterator returns an iterator that does a post-order binary tree 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 (*IPv4AddressAssociativeTrieNode) ContainingFirstAllNodeIterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingIPv4AssociativeTrieNodeIterator

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*IPv4AddressAssociativeTrieNode) ContainingFirstIterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ContainingFirstIterator(forwardSubNodeOrder bool) CachingIPv4AssociativeTrieNodeIterator

ContainingFirstIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*IPv4AddressAssociativeTrieNode) Contains added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) Contains(addr *IPv4Address) 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 exists already in the trie, false otherwise.

Use GetAddedNode to get the node for the address rather than just checking for its existence.

func (*IPv4AddressAssociativeTrieNode) DeepEqual added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) DeepEqual(other *IPv4AddressAssociativeTrieNode) 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 (*IPv4AddressAssociativeTrieNode) DescendingIterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) DescendingIterator() IPv4AddressIterator

DescendingIterator returns an iterator that iterates through the elements of the sub-trie with this node as the root. The iteration is in reverse sorted element order.

func (*IPv4AddressAssociativeTrieNode) ElementContains added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ElementContains(addr *IPv4Address) 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 (*IPv4AddressAssociativeTrieNode) ElementsContainedBy added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ElementsContainedBy(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 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 (*IPv4AddressAssociativeTrieNode) ElementsContaining added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ElementsContaining(addr *IPv4Address) *ContainmentPath

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 (*IPv4AddressAssociativeTrieNode) Equal added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) Equal(other *IPv4AddressAssociativeTrieNode) bool

Equal returns whether the key and mapped value match those of the given node

func (*IPv4AddressAssociativeTrieNode) FirstAddedNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) FirstAddedNode() *IPv4AddressAssociativeTrieNode

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 tree or sub-trie

func (*IPv4AddressAssociativeTrieNode) FirstNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) FirstNode() *IPv4AddressAssociativeTrieNode

FirstNode returns the first (the lowest valued) node in the sub-trie originating from this node.

func (*IPv4AddressAssociativeTrieNode) FloorAddedNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) FloorAddedNode(addr *Address) *IPv4AddressAssociativeTrieNode

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 (IPv4AddressAssociativeTrieNode) Format added in v1.1.0 

func (node IPv4AddressAssociativeTrieNode) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*IPv4AddressAssociativeTrieNode) Get added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) Get(addr *IPv4Address) NodeValue

Get gets the specified 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 (*IPv4AddressAssociativeTrieNode) GetAddedNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) GetAddedNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrieNode) GetKey added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) GetKey() *IPv4Address

GetKey gets the key used for placing the node in the tree.

func (*IPv4AddressAssociativeTrieNode) GetLowerSubNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) GetLowerSubNode() *IPv4AddressAssociativeTrieNode

GetLowerSubNode gets the direct child node whose key is smallest in value

func (*IPv4AddressAssociativeTrieNode) GetNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) GetNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

GetNode gets the node in the trie, with this sub-node 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 (*IPv4AddressAssociativeTrieNode) GetParent added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) GetParent() *IPv4AddressAssociativeTrieNode

GetParent gets the node from which this node is a direct child node, or nil if this is the root.

func (*IPv4AddressAssociativeTrieNode) GetUpperSubNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) GetUpperSubNode() *IPv4AddressAssociativeTrieNode

GetUpperSubNode gets the direct child node whose key is largest in value

func (*IPv4AddressAssociativeTrieNode) GetValue added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) GetValue() NodeValue

GetValue sets the value associated with this node

func (*IPv4AddressAssociativeTrieNode) HigherAddedNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) HigherAddedNode(addr *Address) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrieNode) IsAdded added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) IsAdded() bool

IsAdded returns whether the node was "added". Some binary tree nodes are considered "added" and others are not. Those nodes created for key elements added to the tree 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 tree. 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 (*IPv4AddressAssociativeTrieNode) IsEmpty added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) IsEmpty() bool

IsEmpty returns whether the size is 0

func (*IPv4AddressAssociativeTrieNode) IsLeaf added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) 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-trie with this node as the root.

func (*IPv4AddressAssociativeTrieNode) IsRoot added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) IsRoot() bool

IsRoot returns whether this is the root of the backing tree.

func (*IPv4AddressAssociativeTrieNode) Iterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) Iterator() IPv4AddressIterator

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 (*IPv4AddressAssociativeTrieNode) LastAddedNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) LastAddedNode() *IPv4AddressAssociativeTrieNode

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 tree or sub-trie

func (*IPv4AddressAssociativeTrieNode) LastNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) LastNode() *IPv4AddressAssociativeTrieNode

LastNode returns the last (the highest valued) node in the sub-trie originating from this node.

func (*IPv4AddressAssociativeTrieNode) LongestPrefixMatch added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) LongestPrefixMatch(addr *IPv4Address) *Address

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 (*IPv4AddressAssociativeTrieNode) LongestPrefixMatchNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) LongestPrefixMatchNode(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrieNode) LowerAddedNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) LowerAddedNode(addr *Address) *IPv4AddressAssociativeTrieNode

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 (*IPv4AddressAssociativeTrieNode) NextAddedNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) NextAddedNode() *IPv4AddressAssociativeTrieNode

NextAddedNode returns the next node in the tree that is an added node, following the tree order, or nil if there is no such node.

func (*IPv4AddressAssociativeTrieNode) NextNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) NextNode() *IPv4AddressAssociativeTrieNode

NextNode returns the node that follows this node following the tree order

func (*IPv4AddressAssociativeTrieNode) NodeIterator added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) NodeIterator(forward bool) IPv4AssociativeTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*IPv4AddressAssociativeTrieNode) NodeSize added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) 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 (*IPv4AddressAssociativeTrieNode) PreviousAddedNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) PreviousAddedNode() *IPv4AddressAssociativeTrieNode

PreviousAddedNode returns the previous node in the tree that is an added node, following the tree order in reverse, or nil if there is no such node.

func (*IPv4AddressAssociativeTrieNode) PreviousNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) PreviousNode() *IPv4AddressAssociativeTrieNode

PreviousNode returns the node that precedes this node following the tree order.

func (*IPv4AddressAssociativeTrieNode) Remove added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) 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 (*IPv4AddressAssociativeTrieNode) RemoveElementsContainedBy added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) RemoveElementsContainedBy(addr *IPv4Address) *IPv4AddressAssociativeTrieNode

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 sub-trie that was removed from the trie, or nil if nothing was removed.

func (*IPv4AddressAssociativeTrieNode) RemoveNode added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) RemoveNode(addr *IPv4Address) 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.

func (*IPv4AddressAssociativeTrieNode) SetAdded added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) SetAdded()

SetAdded makes this node an added node, which is equivalent to adding the corresponding key to the tree. 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 tree by calling Remove. A non-added node will only remain in the tree if it needs to in the tree.

func (*IPv4AddressAssociativeTrieNode) SetValue added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) SetValue(val NodeValue)

SetValue sets the value associated with this node

func (*IPv4AddressAssociativeTrieNode) Size added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) Size() int

Size returns the number of elements in the tree. Only nodes for which IsAdded returns true are counted. When zero is returned, IsEmpty returns true.

func (*IPv4AddressAssociativeTrieNode) String added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) 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 (*IPv4AddressAssociativeTrieNode) ToAssociativeBase added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ToAssociativeBase() *AssociativeAddressTrieNode

ToAssociativeBase converts to the polymorphic associative representation of this trie node The node is unchanged, the returned node is the same underlying node.

func (*IPv4AddressAssociativeTrieNode) ToBase added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ToBase() *AddressTrieNode

ToBase converts to the polymorphic non-associative representation of this trie node The node is unchanged, the returned node is the same underlying node.

func (*IPv4AddressAssociativeTrieNode) ToIPv4Base added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) ToIPv4Base() *IPv4AddressTrieNode

ToIPv4Base converts to the non-associative representation of this IPv4 trie node. The node is unchanged, the returned node is the same underlying node.

func (*IPv4AddressAssociativeTrieNode) TreeDeepEqual added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) TreeDeepEqual(other *IPv4AddressAssociativeTrieNode) 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 (*IPv4AddressAssociativeTrieNode) TreeEqual added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) TreeEqual(other *IPv4AddressAssociativeTrieNode) bool

TreeEqual returns whether the sub-trie represented by this node as the root node matches the given sub-trie

func (*IPv4AddressAssociativeTrieNode) TreeString added in v1.1.0 

func (node *IPv4AddressAssociativeTrieNode) 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 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 IPv4AddressIterator 

type IPv4AddressIterator interface {
	HasNext

	// Next returns the next IPv4 address, or nil if there is none left.
	Next() *IPv4Address
}

IPv4AddressIterator iterates through IPv4 subnets and ranges

type IPv4AddressKey added in v1.1.0 

type IPv4AddressKey struct {
	Values [IPv4SegmentCount]struct {
		Value      IPv4SegInt
		UpperValue IPv4SegInt
	}
	Prefix PrefixKey
}

IPv4AddressKey is a representation of IPv4Address that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators It can be used as a map key. The zero value is the address 0.0.0.0

func (*IPv4AddressKey) Normalize added in v1.1.0 

func (key *IPv4AddressKey) Normalize()

Normalize normalizes the given key. Normalizing a key ensures it is the single unique key for any given address or subnet.

func (*IPv4AddressKey) String added in v1.1.1 

func (key *IPv4AddressKey) String() string

String calls the String method in the corresponding address

func (*IPv4AddressKey) ToAddress added in v1.1.0 

func (key *IPv4AddressKey) ToAddress() *IPv4Address

ToAddress converts to an address instance

func (*IPv4AddressKey) ToBaseKey added in v1.1.0 

func (key *IPv4AddressKey) ToBaseKey() *AddressKey

ToBaseKey converts to key that can be used for any address type or version

func (*IPv4AddressKey) ToIPKey added in v1.1.1 

func (key *IPv4AddressKey) ToIPKey() *IPAddressKey

ToIPKey converts to key that can be used for both IPv4 and IPv6

func (*IPv4AddressKey) UpperVal added in v1.1.0 

func (key *IPv4AddressKey) UpperVal(segmentIndex int) IPv4SegInt

UpperVal provides the upper value for a given segment. For a given key, the val method provides a function of type IPv4SegmentProvider

func (*IPv4AddressKey) Val added in v1.1.0 

func (key *IPv4AddressKey) Val(segmentIndex int) IPv4SegInt

Val provides the lower value for a given segment. For a given key, the val method provides a function of type IPv4SegmentProvider

type IPv4AddressNetwork 

type IPv4AddressNetwork struct {
	// contains filtered or unexported fields
}

func (IPv4AddressNetwork) GetHostMask 

func (network IPv4AddressNetwork) GetHostMask(prefLen BitCount) *IPv4Address

func (IPv4AddressNetwork) GetLoopback 

func (network IPv4AddressNetwork) GetLoopback() *IPv4Address

func (IPv4AddressNetwork) GetNetworkMask 

func (network IPv4AddressNetwork) GetNetworkMask(prefLen BitCount) *IPv4Address

func (IPv4AddressNetwork) GetPrefixedHostMask 

func (network IPv4AddressNetwork) GetPrefixedHostMask(prefLen BitCount) *IPv4Address

func (IPv4AddressNetwork) GetPrefixedNetworkMask 

func (network IPv4AddressNetwork) GetPrefixedNetworkMask(prefLen BitCount) *IPv4Address

type IPv4AddressSection 

type IPv4AddressSection struct {
	// contains filtered or unexported fields
}

IPv4AddressSection represents a section of an IPv4 address comprising 0 to 4 IPv4 address segments. The zero values is a section with zero segments.

func NewIPv4PrefixedSection 

func NewIPv4PrefixedSection(segments []*IPv4AddressSegment, prefixLen PrefixLen) *IPv4AddressSection

NewIPv4PrefixedSection constructs an IPv4 address or subnet section from the given segments and prefix length.

func NewIPv4Section 

func NewIPv4Section(segments []*IPv4AddressSegment) *IPv4AddressSection

NewIPv4Section constructs an IPv4 address or subnet section from the given segments.

func NewIPv4SectionFromBytes 

func NewIPv4SectionFromBytes(bytes []byte) *IPv4AddressSection

NewIPv4SectionFromBytes constructs an IPv4 address section from the given byte slice. The segment count is determined by the slice length, even if the segment count exceeds 4 segments.

func NewIPv4SectionFromPrefixedBytes 

func NewIPv4SectionFromPrefixedBytes(bytes []byte, segmentCount int, prefixLength PrefixLen) (res *IPv4AddressSection, err addrerr.AddressValueError)

NewIPv4SectionFromPrefixedBytes constructs an IPv4 address or prefix block section from the given byte slice and prefix length. It allows you to specify the segment count for the supplied bytes. If the slice is too large for the given number of segments, an error is returned, although leading zeros are tolerated.

func NewIPv4SectionFromPrefixedRange 

func NewIPv4SectionFromPrefixedRange(vals, upperVals IPv4SegmentValueProvider, segmentCount int, prefixLength PrefixLen) (res *IPv4AddressSection)

NewIPv4SectionFromPrefixedRange constructs an IPv4 subnet section of the given segment count from the given values and prefix length.

func NewIPv4SectionFromPrefixedUint32 

func NewIPv4SectionFromPrefixedUint32(value uint32, segmentCount int, prefixLength PrefixLen) (res *IPv4AddressSection)

NewIPv4SectionFromPrefixedUint32 constructs an IPv4 address or prefix block section of the given segment count from the given value and prefix length.

func NewIPv4SectionFromPrefixedVals 

func NewIPv4SectionFromPrefixedVals(vals IPv4SegmentValueProvider, segmentCount int, prefixLength PrefixLen) (res *IPv4AddressSection)

NewIPv4SectionFromPrefixedVals constructs an IPv4 address or prefix block section of the given segment count from the given values and prefix length.

func NewIPv4SectionFromRange 

func NewIPv4SectionFromRange(vals, upperVals IPv4SegmentValueProvider, segmentCount int) (res *IPv4AddressSection)

NewIPv4SectionFromRange constructs an IPv4 subnet section of the given segment count from the given values.

func NewIPv4SectionFromSegmentedBytes 

func NewIPv4SectionFromSegmentedBytes(bytes []byte, segmentCount int) (res *IPv4AddressSection, err addrerr.AddressValueError)

NewIPv4SectionFromSegmentedBytes constructs an IPv4 address section from the given byte slice. It allows you to specify the segment count for the supplied bytes. If the slice is too large for the given number of segments, an error is returned, although leading zeros are tolerated.

func NewIPv4SectionFromUint32 

func NewIPv4SectionFromUint32(value uint32, segmentCount int) (res *IPv4AddressSection)

NewIPv4SectionFromUint32 constructs an IPv4 address section of the given segment count from the given value.

func NewIPv4SectionFromVals 

func NewIPv4SectionFromVals(vals IPv4SegmentValueProvider, segmentCount int) (res *IPv4AddressSection)

NewIPv4SectionFromVals constructs an IPv4 address section of the given segment count from the given values.

func (*IPv4AddressSection) AdjustPrefixLen 

func (section *IPv4AddressSection) AdjustPrefixLen(prefixLen BitCount) *IPv4AddressSection

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*IPv4AddressSection) AdjustPrefixLenZeroed 

func (section *IPv4AddressSection) AdjustPrefixLenZeroed(prefixLen BitCount) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv4AddressSection) Append 

func (section *IPv4AddressSection) Append(other *IPv4AddressSection) *IPv4AddressSection

Append creates a new section by appending the given section to this section.

func (*IPv4AddressSection) AssignMinPrefixForBlock 

func (section *IPv4AddressSection) AssignMinPrefixForBlock() *IPv4AddressSection

AssignMinPrefixForBlock returns an equivalent address section, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this address section.

In other words, this method assigns a prefix length to this address section matching the largest prefix block in this address section.

func (*IPv4AddressSection) AssignPrefixForSingleBlock 

func (section *IPv4AddressSection) AssignPrefixForSingleBlock() *IPv4AddressSection

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address section. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address section - it is required that the range of values match the range of a prefix block. If there is no such address section, then nil is returned.

func (*IPv4AddressSection) BitwiseOr 

func (section *IPv4AddressSection) BitwiseOr(other *IPv4AddressSection) (res *IPv4AddressSection, err addrerr.IncompatibleAddressError)

BitwiseOr does the bitwise disjunction with this address section, useful when subnetting. It is similar to Mask which does the bitwise conjunction.

The operation is applied to all individual addresses and the result is returned.

If this represents multiple address sections, and applying the operation to all sections creates a set of sections that cannot be represented as a sequential range within each segment, then an error is returned

func (*IPv4AddressSection) BlockIterator 

func (section *IPv4AddressSection) BlockIterator(segmentCount int) IPv4SectionIterator

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 StandardDivGroupingType) 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 comparing 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, 0 if they are the same, or a negative integer if the other has a larger count.

func (*IPv4AddressSection) Contains 

func (section *IPv4AddressSection) Contains(other AddressSectionType) bool

Contains returns whether this is same type and version as the given address section and whether it contains all values in the given section.

Sections must also have the same number of segments to be comparable, otherwise false is returned.

func (*IPv4AddressSection) ContainsPrefixBlock 

func (section *IPv4AddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPv4AddressSection) ContainsSinglePrefixBlock 

func (section *IPv4AddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this section contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPv4AddressSection) CopyBytes 

func (section *IPv4AddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4AddressSection) CopySegments 

func (section *IPv4AddressSection) CopySegments(segs []*IPv4AddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*IPv4AddressSection) CopySubSegments 

func (section *IPv4AddressSection) CopySubSegments(start, end int, segs []*IPv4AddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*IPv4AddressSection) CopyUpperBytes 

func (section *IPv4AddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv4AddressSection) CoverWithPrefixBlock 

func (section *IPv4AddressSection) CoverWithPrefixBlock() *IPv4AddressSection

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the individual address sections in this section. The resulting block will have a larger count than this, unless this section is already a prefix block.

func (*IPv4AddressSection) CoverWithPrefixBlockTo 

func (section *IPv4AddressSection) CoverWithPrefixBlockTo(other *IPv4AddressSection) (*IPv4AddressSection, addrerr.SizeMismatchError)

CoverWithPrefixBlockTo returns the minimal-size prefix block section that covers all the address sections spanning from this to the given section.

If the other section has a different segment count, an error is returned.

func (*IPv4AddressSection) Equal 

func (section *IPv4AddressSection) Equal(other AddressSectionType) bool

Equal returns whether the given address section is equal to this address section. Two address sections are equal if they represent the same set of sections. They must match:

  • type/version: IPv4
  • segment counts
  • segment value ranges

Prefix lengths are ignored.

func (*IPv4AddressSection) ForEachSegment added in v1.2.0 

func (section *IPv4AddressSection) ForEachSegment(consumer func(segmentIndex int, segment *IPv4AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true Returns the number of visited segments.

func (*IPv4AddressSection) GetBitCount 

func (section *IPv4AddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item

func (*IPv4AddressSection) GetBitsPerSegment 

func (section *IPv4AddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (*IPv4AddressSection) GetBlockCount 

func (section *IPv4AddressSection) GetBlockCount(segmentCount int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments. It is similar to GetIPv4BlockCount but returns a big integer instead of a uint64.

func (*IPv4AddressSection) GetBlockMaskPrefixLen 

func (section *IPv4AddressSection) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address section is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address section with all 1s in the network section and then all 0s in the host section. A CIDR host mask is an address section with all 0s in the network section and then all 1s 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

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.

func (*IPv4AddressSection) GetIPVersion 

func (section *IPv4AddressSection) GetIPVersion() IPVersion

GetIPVersion returns IPv4, the IP version of this address section

func (*IPv4AddressSection) GetIPv4BlockCount 

func (section *IPv4AddressSection) GetIPv4BlockCount(segmentCount int) uint64

GetIPv4BlockCount returns the count of distinct values in the given number of initial (more significant) segments. It is similar to GetBlockCount but returns a uint64 instead of a big integer.

func (*IPv4AddressSection) GetIPv4Count 

func (section *IPv4AddressSection) GetIPv4Count() uint64

GetIPv4Count returns the count of possible distinct values for this section. It is the same as GetCount but returns the value as a uint64 instead of a big integer. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv4AddressSection) GetIPv4PrefixCount 

func (section *IPv4AddressSection) GetIPv4PrefixCount() uint64

GetIPv4PrefixCount returns the number of distinct prefix values in this section. It is similar to GetPrefixCount but returns a uint64.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetIPv4Count

func (*IPv4AddressSection) GetIPv4PrefixCountLen 

func (section *IPv4AddressSection) GetIPv4PrefixCountLen(prefixLength BitCount) uint64

GetIPv4PrefixCountLen returns the number of distinct prefix values in this item for the given prefix length

It is the same as GetPrefixCountLen but returns a uint64, not a *big.Int

func (*IPv4AddressSection) GetLower 

func (section *IPv4AddressSection) GetLower() *IPv4AddressSection

GetLower returns the section in the range with the lowest numeric value, which will be the same section if it represents a single value. For example, for "1.2-3.4.5-6", the section "1.2.4.5" is returned.

func (*IPv4AddressSection) GetMaxSegmentValue 

func (section *IPv4AddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPv4AddressSection) GetMinPrefixLenForBlock 

func (section *IPv4AddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (*IPv4AddressSection) GetNetworkMask 

func (section *IPv4AddressSection) GetNetworkMask() *IPv4AddressSection

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address section. If this section has no prefix length, then the all-ones mask is returned.

func (*IPv4AddressSection) GetNetworkPrefixLen 

func (section *IPv4AddressSection) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. It is equivalent to GetPrefixLen.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (*IPv4AddressSection) GetNetworkSection 

func (section *IPv4AddressSection) GetNetworkSection() *IPv4AddressSection

GetNetworkSection returns a subsection containing the segments with the network bits of the section. The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.

If this series has no CIDR prefix length, the returned network section will be the entire series as a prefixed section with prefix length matching the address bit length.

func (*IPv4AddressSection) GetNetworkSectionLen 

func (section *IPv4AddressSection) GetNetworkSectionLen(prefLen BitCount) *IPv4AddressSection

GetNetworkSectionLen returns a subsection containing the segments with the network of the section, the prefix bits according to the given prefix length. The returned section will have only as many segments as needed to contain the network.

The new section will be assigned the given prefix length, unless the existing prefix length is smaller, in which case the existing prefix length will be retained.

func (*IPv4AddressSection) GetPrefixCount 

func (section *IPv4AddressSection) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetCount

func (*IPv4AddressSection) GetPrefixCountLen 

func (section *IPv4AddressSection) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length

func (*IPv4AddressSection) GetPrefixLenForSingleBlock 

func (section *IPv4AddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (*IPv4AddressSection) GetSegment 

func (section *IPv4AddressSection) GetSegment(index int) *IPv4AddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or index larger than the segment count.

func (*IPv4AddressSection) GetSegmentCount 

func (section *IPv4AddressSection) GetSegmentCount() int

func (*IPv4AddressSection) GetSegmentStrings 

func (section *IPv4AddressSection) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*IPv4AddressSection) GetSegments 

func (section *IPv4AddressSection) GetSegments() (res []*IPv4AddressSegment)

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*IPv4AddressSection) GetSequentialBlockCount 

func (section *IPv4AddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section

func (*IPv4AddressSection) GetSequentialBlockIndex 

func (section *IPv4AddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (*IPv4AddressSection) GetSubSection 

func (section *IPv4AddressSection) GetSubSection(index, endIndex int) *IPv4AddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*IPv4AddressSection) GetTrailingSection 

func (section *IPv4AddressSection) GetTrailingSection(index int) *IPv4AddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*IPv4AddressSection) GetUpper 

func (section *IPv4AddressSection) GetUpper() *IPv4AddressSection

GetUpper returns the section in the range with the highest numeric value, which will be the same section if it represents a single value. For example, for "1.2-3.4.5-6", the section "1.3.4.6" is returned.

func (*IPv4AddressSection) GetUpperValue 

func (section *IPv4AddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value

func (*IPv4AddressSection) GetValue 

func (section *IPv4AddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value

func (*IPv4AddressSection) IncludesMax 

func (section *IPv4AddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range

func (*IPv4AddressSection) IncludesMaxHost 

func (section *IPv4AddressSection) IncludesMaxHost() bool

IncludesMaxHost returns whether the address section contains an individual address section with a host of all one-bits. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are one.

func (*IPv4AddressSection) IncludesMaxHostLen 

func (section *IPv4AddressSection) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the address section contains an individual address section with a host of all one-bits, an address section for which all bits past the given prefix length are all ones.

func (*IPv4AddressSection) IncludesZero 

func (section *IPv4AddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range

func (*IPv4AddressSection) IncludesZeroHost 

func (section *IPv4AddressSection) IncludesZeroHost() bool

IncludesZeroHost returns whether the address section contains an individual address section with a host of zero. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are zero.

func (*IPv4AddressSection) IncludesZeroHostLen 

func (section *IPv4AddressSection) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the address section contains an individual section with a host of zero, a section for which all bits past the given prefix length are zero.

func (*IPv4AddressSection) Increment 

func (section *IPv4AddressSection) Increment(inc int64) *IPv4AddressSection

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (*IPv4AddressSection) IncrementBoundary 

func (section *IPv4AddressSection) IncrementBoundary(increment int64) *IPv4AddressSection

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (*IPv4AddressSection) Insert 

func (section *IPv4AddressSection) Insert(index int, other *IPv4AddressSection) *IPv4AddressSection

Insert creates a new section by inserting the given section into this section at the given index.

func (*IPv4AddressSection) Intersect 

func (section *IPv4AddressSection) Intersect(other *IPv4AddressSection) (res *IPv4AddressSection, err addrerr.SizeMismatchError)

Intersect returns the subnet sections whose individual sections are found in both this and the given subnet section argument, or nil if no such sections exist.

This is also known as the conjunction of the two sets of address sections.

If the two sections have different segment counts, an error is returned.

func (*IPv4AddressSection) IsAdaptiveZero 

func (section *IPv4AddressSection) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the section was originally created as an implicitly zero-valued section (eg 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, etc 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 (*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 < 0, or if it is larger than the bit count of this item.

func (*IPv4AddressSection) IsPrefixBlock 

func (section *IPv4AddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length or a prefix length that differs from prefix lengths for which ContainsPrefixBlock returns true.

func (*IPv4AddressSection) IsPrefixed 

func (section *IPv4AddressSection) IsPrefixed() bool

IsPrefixed returns whether this section has an associated prefix length

func (*IPv4AddressSection) IsSequential 

func (section *IPv4AddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (*IPv4AddressSection) IsSingleNetwork 

func (section *IPv4AddressSection) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address section.

func (*IPv4AddressSection) IsSinglePrefixBlock 

func (section *IPv4AddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock() except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPv4AddressSection) IsZero 

func (section *IPv4AddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero

func (*IPv4AddressSection) IsZeroHost 

func (section *IPv4AddressSection) IsZeroHost() bool

IsZeroHost returns whether this section has a prefix length and if so, whether the host section is always zero for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (*IPv4AddressSection) IsZeroHostLen 

func (section *IPv4AddressSection) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual sections in this address section, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (*IPv4AddressSection) Iterator 

func (section *IPv4AddressSection) Iterator() IPv4SectionIterator

Iterator provides an iterator to iterate through the individual address sections of this address section.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address sections.

Call IsMultiple to determine if this instance represents multiple address sections, or GetCount for the count.

func (*IPv4AddressSection) Mask 

func (section *IPv4AddressSection) Mask(other *IPv4AddressSection) (res *IPv4AddressSection, err addrerr.IncompatibleAddressError)

Mask applies the given mask to all address sections represented by this secction, returning the result.

If the sections do not have a comparable number of segments, an error is returned.

If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned

func (*IPv4AddressSection) MatchesWithMask 

func (section *IPv4AddressSection) MatchesWithMask(other *IPv4AddressSection, mask *IPv4AddressSection) bool

MatchesWithMask applies the mask to this address section and then compares the result with the given address section, returning true if they match, false otherwise. To match, both the given section and mask must have the same number of segments as this section.

func (*IPv4AddressSection) MergeToPrefixBlocks 

func (section *IPv4AddressSection) MergeToPrefixBlocks(sections ...*IPv4AddressSection) ([]*IPv4AddressSection, addrerr.SizeMismatchError)

MergeToPrefixBlocks merges this section with the list of sections to produce the smallest array of prefix blocks.

The resulting slice is sorted from lowest value to highest, regardless of the size of each prefix block.

func (*IPv4AddressSection) MergeToSequentialBlocks 

func (section *IPv4AddressSection) MergeToSequentialBlocks(sections ...*IPv4AddressSection) ([]*IPv4AddressSection, addrerr.SizeMismatchError)

MergeToSequentialBlocks merges this with the list of sections to produce the smallest array of sequential blocks

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv4AddressSection) PrefixBlockIterator 

func (section *IPv4AddressSection) PrefixBlockIterator() IPv4SectionIterator

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() IPv4SectionIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this address section, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this address section.

If the series has no prefix length, then this is equivalent to Iterator.

func (*IPv4AddressSection) Replace 

func (section *IPv4AddressSection) Replace(index int, replacement *IPv4AddressSection) *IPv4AddressSection

Replace replaces the segments of this section starting at the given index with the given replacement segments

func (*IPv4AddressSection) ReplaceLen 

func (section *IPv4AddressSection) ReplaceLen(startIndex, endIndex int, replacement *IPv4AddressSection, replacementStartIndex, replacementEndIndex int) *IPv4AddressSection

ReplaceLen replaces segments starting from startIndex and ending before endIndex with the segments starting at replacementStartIndex and ending before replacementEndIndex from the replacement section

func (*IPv4AddressSection) ReverseBits 

func (section *IPv4AddressSection) ReverseBits(perByte bool) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

ReverseBits returns a new section with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv4AddressSection) ReverseBytes 

func (section *IPv4AddressSection) ReverseBytes() *IPv4AddressSection

ReverseBytes returns a new section with the bytes reversed. Any prefix length is dropped.

func (*IPv4AddressSection) ReverseSegments 

func (section *IPv4AddressSection) ReverseSegments() *IPv4AddressSection

ReverseSegments returns a new section with the segments reversed.

func (*IPv4AddressSection) SequentialBlockIterator 

func (section *IPv4AddressSection) SequentialBlockIterator() IPv4SectionIterator

SequentialBlockIterator iterates through the sequential address sections that make up this address section.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPv4AddressSection) SetPrefixLen 

func (section *IPv4AddressSection) SetPrefixLen(prefixLen BitCount) *IPv4AddressSection

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPv4AddressSection) SetPrefixLenZeroed 

func (section *IPv4AddressSection) SetPrefixLenZeroed(prefixLen BitCount) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

If this address section has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address section has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (ie bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv4AddressSection) SpanWithPrefixBlocks 

func (section *IPv4AddressSection) SpanWithPrefixBlocks() []*IPv4AddressSection

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual address sections as this section.

Unlike SpanWithPrefixBlocksTo, the result only includes blocks that are a part of this section.

func (*IPv4AddressSection) SpanWithPrefixBlocksTo 

func (section *IPv4AddressSection) SpanWithPrefixBlocksTo(other *IPv4AddressSection) ([]*IPv4AddressSection, addrerr.SizeMismatchError)

SpanWithPrefixBlocksTo returns the smallest slice of prefix block subnet sections that span from this section to the given section.

If the given section has a different segment count, an error is returned.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv4AddressSection) SpanWithSequentialBlocks 

func (section *IPv4AddressSection) SpanWithSequentialBlocks() []*IPv4AddressSection

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of sections as this.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

Unlike SpanWithSequentialBlocksTo, this method only includes values that are a part of this section.

func (*IPv4AddressSection) SpanWithSequentialBlocksTo 

func (section *IPv4AddressSection) SpanWithSequentialBlocksTo(other *IPv4AddressSection) ([]*IPv4AddressSection, addrerr.SizeMismatchError)

SpanWithSequentialBlocksTo produces the smallest slice of sequential block address sections that span from this section to the given section.

func (*IPv4AddressSection) String 

func (section *IPv4AddressSection) String() string

String implements the fmt.Stringer interface, returning the normalized string provided by ToNormalizedString, or "<nil>" if the receiver is a nil pointer

func (*IPv4AddressSection) Subtract 

func (section *IPv4AddressSection) Subtract(other *IPv4AddressSection) (res []*IPv4AddressSection, err addrerr.SizeMismatchError)

Subtract subtracts the given subnet sections from this subnet section, returning an array of sections for the result (the subnet sections will not be contiguous so an array is required).

Subtract computes the subnet difference, the set of address sections in this address section but not in the provided section. This is also known as the relative complement of the given argument in this subnet section.

This is set subtraction, not subtraction of values.

func (*IPv4AddressSection) TestBit 

func (section *IPv4AddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv4AddressSection) ToBinaryString 

func (section *IPv4AddressSection) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address section as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4AddressSection) ToBlock 

func (section *IPv4AddressSection) ToBlock(segmentIndex int, lower, upper SegInt) *IPv4AddressSection

ToBlock creates a new block of address sections by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPv4AddressSection) ToCanonicalString 

func (section *IPv4AddressSection) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address section.

For IPv4, dotted octet format, also known as dotted decimal format, is used. https://datatracker.ietf.org/doc/html/draft-main-ipaddr-text-rep-00#section-2.1

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

If this section has a prefix length, it will be included in the string.

func (*IPv4AddressSection) ToCanonicalWildcardString 

func (section *IPv4AddressSection) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string but avoids the CIDR prefix length. Address sections with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. For IPv4 it is the same as ToNormalizedWildcardString.

func (*IPv4AddressSection) ToCompressedString 

func (section *IPv4AddressSection) ToCompressedString() string

ToCompressedString produces a short representation of this address section while remaining within the confines of standard representation(s) of the address.

For IPv4, it is the same as the canonical string.

func (*IPv4AddressSection) ToCompressedWildcardString 

func (section *IPv4AddressSection) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, and in fact for IPv4 it is the same as ToNormalizedWildcardString.

func (*IPv4AddressSection) ToDivGrouping 

func (section *IPv4AddressSection) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToIPv4.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSection) ToFullString 

func (section *IPv4AddressSection) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 3 characters for IPv4 segments.

func (*IPv4AddressSection) ToHexString 

func (section *IPv4AddressSection) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address section as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4AddressSection) ToIP 

func (section *IPv4AddressSection) ToIP() *IPAddressSection

ToIP converts to an IPAddressSection, a polymorphic type usable with all IP address sections.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSection) ToInetAtonJoinedString 

func (section *IPv4AddressSection) ToInetAtonJoinedString(radix Inet_aton_radix, joinedCount int) (string, addrerr.IncompatibleAddressError)

ToInetAtonJoinedString returns a string with a format that is styled from the inet_aton routine. The string can have an octal or hexadecimal radix rather than decimal, and can have less than the typical four IPv4 segments by joining the least significant segments together, resulting in a string which just 1, 2 or 3 divisions.

When using octal, the octal segments each have a leading zero prefix of "0", and when using hex, a prefix of "0x".

If this represents a subnet section, this returns an error when unable to join two or more segments into a division of a larger bit-length that represents the same set of values.

func (*IPv4AddressSection) ToInetAtonString 

func (section *IPv4AddressSection) ToInetAtonString(radix Inet_aton_radix) string

ToInetAtonString returns a string with a format that is styled from the inet_aton routine. The string can have an octal or hexadecimal radix rather than decimal. When using octal, the octal segments each have a leading zero prefix of "0", and when using hex, a prefix of "0x".

func (*IPv4AddressSection) ToJoinedSegments 

func (section *IPv4AddressSection) ToJoinedSegments(joinCount int) (AddressDivisionSeries, addrerr.IncompatibleAddressError)

ToJoinedSegments returns an AddressDivisionSeries which organizes the address section by joining the least significant segments together. If joined count is not a positive number, or this section has less than 2 segments, then this returns the original receiver section. Otherwise this returns an AddressDivisionGrouping in which the last division is the division created by joining two or more segments.

If this represents a subnet section, this returns an error when unable to join address segments, one of the first with a range of values, into a division of the larger bit-length that represents the same set of values.

func (*IPv4AddressSection) ToMaxHost 

func (section *IPv4AddressSection) ToMaxHost() (*IPv4AddressSection, addrerr.IncompatibleAddressError)

ToMaxHost converts the address section to one in which all individual address sections have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-ones section, the max address section.

The returned address section will have the same prefix and prefix length.

This returns an error if the address section is a range of address sections which cannot be converted to a range in which all sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv4AddressSection) ToMaxHostLen 

func (section *IPv4AddressSection) ToMaxHostLen(prefixLength BitCount) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address section to one in which all individual address sections have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this section has the same prefix length, then the resulting section will too, otherwise the resulting section will have no prefix length.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all address sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv4AddressSection) ToNormalizedJoinedString 

func (section *IPv4AddressSection) ToNormalizedJoinedString(stringParams addrstr.IPStringOptions, joinedCount int) (string, addrerr.IncompatibleAddressError)

ToNormalizedJoinedString returns a string with a format that is styled from the inet_aton routine. The string can have less than the typical four IPv4 segments by joining the least significant segments together, resulting in a string which just 1, 2 or 3 divisions.

The method accepts an argument of string options as well, allowing callers to customize the string in other ways as well.

If this represents a subnet section, this returns an error when unable to join two or more segments into a division of a larger bit-length that represents the same set of values.

func (*IPv4AddressSection) ToNormalizedString 

func (section *IPv4AddressSection) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address section.

For IPv4, it is the same as the canonical string.

If this section has a prefix length, it will be included in the string.

func (*IPv4AddressSection) ToNormalizedWildcardString 

func (section *IPv4AddressSection) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPv4AddressSection) ToOctalString 

func (section *IPv4AddressSection) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address section as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv4AddressSection) ToPrefixBlock 

func (section *IPv4AddressSection) ToPrefixBlock() *IPv4AddressSection

ToPrefixBlock returns the section with the same prefix as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

If this section has no prefix, this section is returned.

func (*IPv4AddressSection) ToPrefixBlockLen 

func (section *IPv4AddressSection) ToPrefixBlockLen(prefLen BitCount) *IPv4AddressSection

ToPrefixBlockLen returns the section with the same prefix of the given length as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

func (*IPv4AddressSection) ToPrefixLenString 

func (section *IPv4AddressSection) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv4 the string is equivalent to the canonical string.

func (*IPv4AddressSection) ToReverseDNSString 

func (section *IPv4AddressSection) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse DNS lookup string. For IPV4, the error is always nil. For 8.255.4.4 it is 4.4.255.8.in-addr.arpa

func (*IPv4AddressSection) ToSQLWildcardString 

func (section *IPv4AddressSection) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the wildcard '_'..

func (*IPv4AddressSection) ToSectionBase 

func (section *IPv4AddressSection) ToSectionBase() *AddressSection

ToSectionBase converts to an AddressSection, a polymorphic type usable with all address sections. Afterwards, you can convert back with ToIPv4.

ToSectionBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSection) ToSegmentedBinaryString 

func (section *IPv4AddressSection) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this address section as segments of binary values preceded by the "0b" prefix.

func (*IPv4AddressSection) ToSubnetString 

func (section *IPv4AddressSection) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like 1.2.*.* or 1:2::/16

In the case of IPv4, this means that wildcards are used instead of a network prefix when a network prefix has been supplied.

func (*IPv4AddressSection) ToZeroHost 

func (section *IPv4AddressSection) ToZeroHost() (*IPv4AddressSection, addrerr.IncompatibleAddressError)

ToZeroHost converts the address section to one in which all individual address sections have a host of zero, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned section will have the same prefix and prefix length.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv4AddressSection) ToZeroHostLen 

func (section *IPv4AddressSection) ToZeroHostLen(prefixLength BitCount) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address section to one in which all individual sections have a host of zero, the host being the bits following the given prefix length. If this address section has the same prefix length, then the returned one will too, otherwise the returned section will have no prefix length.

This returns an error if the section is a range of which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv4AddressSection) ToZeroNetwork 

func (section *IPv4AddressSection) ToZeroNetwork() *IPv4AddressSection

ToZeroNetwork converts the address section to one in which all individual address sections have a network of zero, the network being the bits within the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned address section will have the same prefix length.

func (*IPv4AddressSection) Uint32Value 

func (section *IPv4AddressSection) Uint32Value() uint32

Uint32Value returns the lowest address in the address section range as a uint32

func (*IPv4AddressSection) UpperBytes 

func (section *IPv4AddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice

func (*IPv4AddressSection) UpperUint32Value 

func (section *IPv4AddressSection) UpperUint32Value() uint32

UpperUint32Value returns the highest address in the address section range as a uint32

func (*IPv4AddressSection) WithoutPrefixLen 

func (section *IPv4AddressSection) WithoutPrefixLen() *IPv4AddressSection

WithoutPrefixLen provides the same address section but with no prefix length. The values remain unchanged.

func (*IPv4AddressSection) Wrap 

func (section *IPv4AddressSection) Wrap() WrappedIPAddressSection

Wrap wraps this IP address section, returning a WrappedIPAddressSection, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address section.

func (*IPv4AddressSection) WrapSection added in v1.2.0 

func (section *IPv4AddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapSection can be called with a nil receiver, wrapping a nil address section.

type IPv4AddressSegment 

type IPv4AddressSegment struct {
	// contains filtered or unexported fields
}

IPv4AddressSegment represents a segment of an IPv4 address. An IPv4 segment contains a single value or a range of sequential values, a prefix length, and it has bit length of 8 bits.

Like strings, segments are immutable, which also makes them concurrency-safe.

See AddressSegment for more details regarding segments.

func NewIPv4PrefixedSegment 

func NewIPv4PrefixedSegment(val IPv4SegInt, prefixLen PrefixLen) *IPv4AddressSegment

NewIPv4PrefixedSegment constructs a segment of an IPv4 address with the given value and assigned prefix length.

func NewIPv4RangePrefixedSegment 

func NewIPv4RangePrefixedSegment(val, upperVal IPv4SegInt, prefixLen PrefixLen) *IPv4AddressSegment

NewIPv4RangePrefixedSegment constructs a segment of an IPv4 subnet with the given range of sequential values and assigned prefix length.

func NewIPv4RangeSegment 

func NewIPv4RangeSegment(val, upperVal IPv4SegInt) *IPv4AddressSegment

NewIPv4RangeSegment constructs a segment of an IPv4 subnet with the given range of sequential values.

func NewIPv4Segment 

func NewIPv4Segment(val IPv4SegInt) *IPv4AddressSegment

NewIPv4Segment constructs a segment of an IPv4 address with the given value.

func (*IPv4AddressSegment) Bytes 

func (seg *IPv4AddressSegment) Bytes() []byte

Bytes returns the lowest value in the address segment range as a byte slice

func (*IPv4AddressSegment) Compare 

func (seg *IPv4AddressSegment) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address segment is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPv4AddressSegment) 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) 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 1s in the network bits and then all 0s in the host bits. A CIDR host mask is a segment with all 0s in the network bits and then all 1s in the host bits. The prefix length is the bit-length of the network bits.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this segment. The prefix length returned here indicates the whether the value of this segment can be used as a mask for the network and host bits of any other segment. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv4AddressSegment) GetByteCount 

func (seg *IPv4AddressSegment) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item, which is 1

func (*IPv4AddressSegment) GetCount 

func (seg *IPv4AddressSegment) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1.

For instance, a segment with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv4AddressSegment) GetIPv4SegmentValue 

func (seg *IPv4AddressSegment) GetIPv4SegmentValue() IPv4SegInt

GetIPv4SegmentValue returns the lower value. Same as GetSegmentValue but returned as a IPv4SegInt.

func (*IPv4AddressSegment) GetIPv4UpperSegmentValue 

func (seg *IPv4AddressSegment) GetIPv4UpperSegmentValue() IPv4SegInt

GetIPv4UpperSegmentValue returns the lower value. Same as GetUpperSegmentValue but returned as a IPv4SegInt.

func (*IPv4AddressSegment) GetLeadingBitCount 

func (seg *IPv4AddressSegment) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv4AddressSegment) GetLower 

func (seg *IPv4AddressSegment) GetLower() *IPv4AddressSegment

GetLower returns a segment representing just the lowest value in the range, which will be the same segment if it represents a single value.

func (*IPv4AddressSegment) GetMaxValue 

func (seg *IPv4AddressSegment) GetMaxValue() IPv4SegInt

GetMaxValue gets the maximum possible value for this type or version of segment, determined by the number of bits.

For the highest range value of this particular segment, use GetUpperSegmentValue.

func (*IPv4AddressSegment) GetMinPrefixLenForBlock 

func (seg *IPv4AddressSegment) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this segment includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this segment represents a single value, this returns the bit count.

func (*IPv4AddressSegment) GetPrefixCountLen 

func (seg *IPv4AddressSegment) GetPrefixCountLen(segmentPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct prefix values for the given prefix length in the range of values of this segment

func (*IPv4AddressSegment) GetPrefixLenForSingleBlock 

func (seg *IPv4AddressSegment) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this segment, and the range of values in this segment matches the block of all values for that prefix.

If the range of segment values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this segment represents a single value, this returns the bit count of the segment.

func (*IPv4AddressSegment) GetPrefixValueCount 

func (seg *IPv4AddressSegment) GetPrefixValueCount() SegIntCount

GetPrefixValueCount returns the count of prefixes in this segment for its prefix length, or the total count if it has no prefix length.

func (*IPv4AddressSegment) GetPrefixValueCountLen 

func (seg *IPv4AddressSegment) GetPrefixValueCountLen(segmentPrefixLength BitCount) SegIntCount

GetPrefixValueCountLen returns the same value as GetPrefixCountLen as an integer

func (*IPv4AddressSegment) GetSegmentPrefixLen 

func (seg *IPv4AddressSegment) GetSegmentPrefixLen() PrefixLen

GetSegmentPrefixLen returns the network prefix for the segment.

The network prefix is 16 for an address like 1.2.0.0/16.

When it comes to each address division or segment, the prefix for the division is the prefix obtained when applying the address or section prefix.

For instance, consider the address 1.2.0.0/20. The first segment has no prefix because the address prefix 20 extends beyond the 8 bits in the first segment, it does not even apply to the segment. The second segment has no prefix because the address prefix extends beyond bits 9 to 16 which lie in the second segment, it does not apply to that segment either. The third segment has the prefix 4 because the address prefix 20 corresponds to the first 4 bits in the 3rd segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment has the prefix 0 because not a single bit is in the network section of the address or segment

The prefix applied across the address is nil ... nil ... (1 to segment bit length) ... 0 ... 0

If the segment has no prefix then nil is returned.

func (*IPv4AddressSegment) GetSegmentValue 

func (seg *IPv4AddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the segment value range

func (*IPv4AddressSegment) GetString 

func (seg *IPv4AddressSegment) GetString() string

GetString produces a normalized string to represent the segment. If the segment is a CIDR network prefix block for its prefix length, then the string contains only the lower value of the block range. Otherwise, the explicit range will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPv4AddressSegment) GetTrailingBitCount 

func (seg *IPv4AddressSegment) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv4AddressSegment) GetUpper 

func (seg *IPv4AddressSegment) GetUpper() *IPv4AddressSegment

GetUpper returns a segment representing just the highest value in the range, which will be the same segment if it represents a single value.

func (*IPv4AddressSegment) GetUpperSegmentValue 

func (seg *IPv4AddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the segment value range

func (*IPv4AddressSegment) GetUpperValue 

func (seg *IPv4AddressSegment) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address segment range as a big integer

func (*IPv4AddressSegment) GetValue 

func (seg *IPv4AddressSegment) GetValue() *BigDivInt

GetValue returns the lowest value in the address segment range as a big integer

func (*IPv4AddressSegment) GetValueCount 

func (seg *IPv4AddressSegment) GetValueCount() SegIntCount

GetValueCount returns the same value as GetCount as an integer

func (*IPv4AddressSegment) GetWildcardString 

func (seg *IPv4AddressSegment) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters while ignoring any network prefix length. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPv4AddressSegment) IncludesMax 

func (seg *IPv4AddressSegment) IncludesMax() bool

IncludesMax returns whether this segment includes the max value, the value whose bits are all ones, within its range

func (*IPv4AddressSegment) IncludesZero 

func (seg *IPv4AddressSegment) IncludesZero() bool

IncludesZero returns whether this segment includes the value of zero within its range

func (*IPv4AddressSegment) IsFullRange 

func (seg *IPv4AddressSegment) IsFullRange() bool

IsFullRange returns whether the segment range includes all possible values for its bit length. 

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv4AddressSegment) IsMax 

func (seg *IPv4AddressSegment) IsMax() bool

IsMax returns whether this segment matches exactly the maximum possible value, the value whose bits are all ones

func (*IPv4AddressSegment) IsMultiple 

func (seg *IPv4AddressSegment) IsMultiple() bool

IsMultiple returns whether this segment represents multiple values

func (*IPv4AddressSegment) IsOneBit 

func (seg *IPv4AddressSegment) IsOneBit(segmentBitIndex BitCount) bool

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 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 (*IPv4AddressSegment) IsPrefixed 

func (seg *IPv4AddressSegment) IsPrefixed() bool

IsPrefixed returns whether this segment has an associated prefix length

func (*IPv4AddressSegment) IsSinglePrefix 

func (seg *IPv4AddressSegment) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix determines if the segment has a single prefix value for the given prefix length. You can call GetPrefixCountLen to get the count of prefixes.

func (*IPv4AddressSegment) IsSinglePrefixBlock 

func (seg *IPv4AddressSegment) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock() except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPv4AddressSegment) IsZero 

func (seg *IPv4AddressSegment) IsZero() bool

IsZero returns whether this segment matches exactly the value of zero

func (*IPv4AddressSegment) Iterator 

func (seg *IPv4AddressSegment) Iterator() IPv4SegmentIterator

Iterator provides an iterator to iterate through the individual address segments of this address segment.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address segments.

Call IsMultiple to determine if this instance represents multiple address segments, or GetValueCount for the count.

func (*IPv4AddressSegment) Join 

func (seg *IPv4AddressSegment) Join(low *IPv4AddressSegment) (*IPv6AddressSegment, addrerr.IncompatibleAddressError)

join joins with another IPv4 segment to produce a 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() IPv4SegmentIterator

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() IPv4SegmentIterator

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) IPv4SegmentIterator

PrefixedBlockIterator provides an iterator to iterate through the individual prefix blocks of the given prefix length in this segment, one for each prefix of this address or subnet.

It is similar to PrefixBlockIterator except that this method allows you to specify the prefix length.

func (*IPv4AddressSegment) ReverseBits 

func (seg *IPv4AddressSegment) ReverseBits(_ bool) (res *IPv4AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBits returns a segment with the bits reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv4AddressSegment) ReverseBytes 

func (seg *IPv4AddressSegment) ReverseBytes() (*IPv4AddressSegment, addrerr.IncompatibleAddressError)

ReverseBytes returns a segment with the bytes reversed, which for an IPv4 segment is always the original segment.

func (*IPv4AddressSegment) String 

func (seg *IPv4AddressSegment) String() string

String produces a string that is useful when a segment string is provided with no context. It uses the decimal radix. GetWildcardString is more appropriate in context with other segments or divisions. It does not use a string prefix and uses '*' for full-range segments. GetString is more appropriate in context with prefix lengths, it uses zeros instead of wildcards with full prefix block ranges alongside prefix lengths.

func (*IPv4AddressSegment) TestBit 

func (seg *IPv4AddressSegment) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv4AddressSegment) ToDiv 

func (seg *IPv4AddressSegment) ToDiv() *AddressDivision

ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions. Afterwards, you can convert back with ToIPv4.

ToDiv can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSegment) ToHexString 

func (seg *IPv4AddressSegment) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address segment as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

For segments, the error is always nil.

func (*IPv4AddressSegment) ToHostSegment 

func (seg *IPv4AddressSegment) ToHostSegment(segmentPrefixLength PrefixLen) *IPv4AddressSegment

ToHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will have no assigned prefix length.

func (*IPv4AddressSegment) ToIP 

func (seg *IPv4AddressSegment) ToIP() *IPAddressSegment

ToIP converts to an IPAddressSegment, a polymorphic type usable with all IP address segments. Afterwards, you can convert back with ToIPv4.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSegment) ToNetworkSegment 

func (seg *IPv4AddressSegment) ToNetworkSegment(segmentPrefixLength PrefixLen) *IPv4AddressSegment

ToNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will have no assigned prefix length.

func (*IPv4AddressSegment) ToNormalizedString 

func (seg *IPv4AddressSegment) ToNormalizedString() string

ToNormalizedString produces a string that is consistent for all address segments of the same type and version. IPv4 segments use base 10, while IPv6 segments use base 16.

func (*IPv4AddressSegment) ToPrefixedHostSegment 

func (seg *IPv4AddressSegment) ToPrefixedHostSegment(segmentPrefixLength PrefixLen) *IPv4AddressSegment

ToPrefixedHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPv4AddressSegment) ToPrefixedNetworkSegment 

func (seg *IPv4AddressSegment) ToPrefixedNetworkSegment(segmentPrefixLength PrefixLen) *IPv4AddressSegment

ToPrefixedNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPv4AddressSegment) ToSegmentBase 

func (seg *IPv4AddressSegment) ToSegmentBase() *AddressSegment

ToSegmentBase converts to an AddressSegment, a polymorphic type usable with all address segments. Afterwards, you can convert back with ToIPv4.

ToSegmentBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv4AddressSegment) UpperBytes 

func (seg *IPv4AddressSegment) UpperBytes() []byte

UpperBytes returns the highest value in the address segment range as a byte slice

func (*IPv4AddressSegment) WithoutPrefixLen 

func (seg *IPv4AddressSegment) WithoutPrefixLen() *IPv4AddressSegment

WithoutPrefixLen returns a segment with the same value range but without a prefix length.

type IPv4AddressSegmentSeries 

type IPv4AddressSegmentSeries interface {
	IPAddressSegmentSeries

	// GetTrailingSection returns an ending subsection of the full address section
	GetTrailingSection(index int) *IPv4AddressSection

	// GetSubSection returns a subsection of the full address section
	GetSubSection(index, endIndex int) *IPv4AddressSection

	// GetNetworkSection returns an address section containing the segments with the network of the series, the prefix bits.
	// The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.
	//
	// If this series has no CIDR prefix length, the returned network section will
	// be the entire series as a prefixed section with prefix length matching the address bit length.
	GetNetworkSection() *IPv4AddressSection

	// GetHostSection returns a section containing the segments with the host of the series, the bits beyond the CIDR network prefix length.
	// The returned section will have only as many segments as needed to contain the host.
	//
	// If this series has no prefix length, the returned host section will be the full section.
	GetHostSection() *IPv4AddressSection

	// GetNetworkSectionLen returns a section containing the segments with the network of the series, the prefix bits according to the given prefix length.
	// The returned section will have only as many segments as needed to contain the network.
	//
	// The new section will be assigned the given prefix length,
	// unless the existing prefix length is smaller, in which case the existing prefix length will be retained.
	GetNetworkSectionLen(BitCount) *IPv4AddressSection

	// GetHostSectionLen returns a section containing the segments with the host of the series, the bits beyond the given CIDR network prefix length.
	// The returned section will have only as many segments as needed to contain the host.
	GetHostSectionLen(BitCount) *IPv4AddressSection

	// GetSegments returns a slice with the address segments.  The returned slice is not backed by the same array as the receiver.
	GetSegments() []*IPv4AddressSegment

	// CopySegments copies the existing segments into the given slice,
	// as much as can be fit into the slice, returning the number of segments copied
	CopySegments(segs []*IPv4AddressSegment) (count int)

	// CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index,
	// into the given slice, as much as can be fit into the slice, returning the number of segments copied
	CopySubSegments(start, end int, segs []*IPv4AddressSegment) (count int)

	// GetSegment returns the segment at the given index.
	// The first segment is at index 0.
	// GetSegment will panic given a negative index or index 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 struct {
	// contains filtered or unexported fields
}

IPv4AddressSeqRange represents an arbitrary range of consecutive IPv4 addresses.

The zero value is a range from 0.0.0.0 to 0.0.0.0.

See IPAddressSeqRange for more details.

func NewIPv4SeqRange 

func NewIPv4SeqRange(one, two *IPv4Address) *IPv4AddressSeqRange

func (*IPv4AddressSeqRange) Bytes 

func (rng *IPv4AddressSeqRange) Bytes() []byte

Bytes returns the lowest address in the range, the one with the lowest numeric value, as a byte slice

func (*IPv4AddressSeqRange) Compare 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) CompareSize 

func (rng *IPv4AddressSeqRange) CompareSize(other IPAddressSeqRangeType) int

CompareSize compares the counts of two address ranges, the number of individual addresses within.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one range spans more individual addresses than another.

CompareSize returns a positive integer if this range has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.

func (*IPv4AddressSeqRange) Contains 

func (rng *IPv4AddressSeqRange) Contains(other IPAddressType) bool

Contains returns whether this range contains all addresses in the given address or subnet.

func (*IPv4AddressSeqRange) ContainsPrefixBlock 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) ContainsRange 

func (rng *IPv4AddressSeqRange) ContainsRange(other IPAddressSeqRangeType) bool

ContainsRange returns whether all the addresses in the given sequential range are also contained in this sequential range.

func (*IPv4AddressSeqRange) ContainsSinglePrefixBlock 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) CopyBytes 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) CopyNetIP 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) CopyUpperBytes 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) CopyUpperNetIP 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) CoverWithPrefixBlock 

func (rng *IPv4AddressSeqRange) CoverWithPrefixBlock() *IPv4Address

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 (*IPv4AddressSeqRange) Equal 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) Extend 

func (rng *IPv4AddressSeqRange) Extend(other *IPv4AddressSeqRange) *IPv4AddressSeqRange

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 (IPv4AddressSeqRange) Format 

func (rng IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) GetBitCount 

func (rng *IPv4AddressSeqRange) GetBitCount() BitCount

GetBitCount returns the number of bits in each address in the range, which is 8

func (*IPv4AddressSeqRange) GetByteCount 

func (rng *IPv4AddressSeqRange) GetByteCount() int

GetByteCount returns the number of bytes in each address in the range, which is 1

func (*IPv4AddressSeqRange) GetCount 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) GetIPv4Count 

func (rng *IPv4AddressSeqRange) GetIPv4Count() uint64

GetIPv4Count is equivalent to GetCount() but returns a uint64

func (*IPv4AddressSeqRange) GetIPv4PrefixCount 

func (rng *IPv4AddressSeqRange) GetIPv4PrefixCount(prefixLength BitCount) uint64

GetIPv4PrefixCount is equivalent to GetPrefixCountLen(int) but returns a uint64

func (*IPv4AddressSeqRange) GetLower 

func (rng *IPv4AddressSeqRange) GetLower() *IPv4Address

GetLower returns the lowest address of the sequential range, the one with the lowest numeric value

func (*IPv4AddressSeqRange) GetLowerIPAddress 

func (rng *IPv4AddressSeqRange) GetLowerIPAddress() *IPAddress

GetLowerIPAddress satisfies the IPAddressRange interface, returning the lower address in the range, same as GetLower()

func (*IPv4AddressSeqRange) GetMinPrefixLenForBlock 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) GetNetIP 

func (rng *IPv4AddressSeqRange) GetNetIP() net.IP

GetNetIP returns the lower IP address in the range as a net.IP

func (*IPv4AddressSeqRange) GetPrefixCountLen 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) GetPrefixLenForSingleBlock 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) GetUpper 

func (rng *IPv4AddressSeqRange) GetUpper() *IPv4Address

GetUpper returns the highest address of the sequential range, the one with the highest numeric value

func (*IPv4AddressSeqRange) GetUpperIPAddress 

func (rng *IPv4AddressSeqRange) GetUpperIPAddress() *IPAddress

GetUpperIPAddress satisfies the IPAddressRange interface, returning the upper address in the range, same as GetUpper()

func (*IPv4AddressSeqRange) GetUpperNetIP 

func (rng *IPv4AddressSeqRange) GetUpperNetIP() net.IP

GetUpperNetIP returns the upper IP address in the range as a net.IP

func (*IPv4AddressSeqRange) GetUpperValue 

func (rng *IPv4AddressSeqRange) GetUpperValue() *big.Int

GetUpperValue returns the highest address in the range, the one with the highest numeric value, as an integer

func (*IPv4AddressSeqRange) GetValue 

func (rng *IPv4AddressSeqRange) GetValue() *big.Int

GetValue returns the lowest address in the range, the one with the lowest numeric value, as an integer

func (*IPv4AddressSeqRange) IncludesMax 

func (rng *IPv4AddressSeqRange) IncludesMax() bool

IncludesMax returns whether this sequential range's upper value is the max value, the value whose bits are all ones.

func (*IPv4AddressSeqRange) IncludesZero 

func (rng *IPv4AddressSeqRange) IncludesZero() bool

IncludesZero returns whether this sequential range's lower value is the zero address.

func (*IPv4AddressSeqRange) Intersect 

func (rng *IPv4AddressSeqRange) Intersect(other *IPv4AddressSeqRange) *IPAddressSeqRange

Intersect returns the intersection of this range with the given range, a range which includes those addresses found in both.

func (*IPv4AddressSeqRange) IsFullRange 

func (rng *IPv4AddressSeqRange) IsFullRange() bool

IsFullRange returns whether this address range covers the entire IPv4 address space.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv4AddressSeqRange) IsMax 

func (rng *IPv4AddressSeqRange) IsMax() bool

IsMax returns whether this sequential range spans from the max address, the address whose bits are all ones, to itself.

func (*IPv4AddressSeqRange) IsMultiple 

func (rng *IPv4AddressSeqRange) IsMultiple() bool

IsMultiple returns whether this range represents a range of multiple addresses

func (*IPv4AddressSeqRange) IsSequential 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) IsZero 

func (rng *IPv4AddressSeqRange) IsZero() bool

IsZero returns whether this sequential range spans from the zero address to itself.

func (*IPv4AddressSeqRange) Iterator 

func (rng *IPv4AddressSeqRange) Iterator() IPv4AddressIterator

Iterator provides an iterator to iterate through the individual addresses of this address range.

Call GetCount for the count.

func (*IPv4AddressSeqRange) Join 

func (rng *IPv4AddressSeqRange) Join(ranges ...*IPv4AddressSeqRange) []*IPv4AddressSeqRange

Join joins the given ranges into the fewest number of ranges. The returned array will be sorted by ascending lowest range value.

func (*IPv4AddressSeqRange) JoinTo 

func (rng *IPv4AddressSeqRange) JoinTo(other *IPv4AddressSeqRange) *IPv4AddressSeqRange

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 (*IPv4AddressSeqRange) Overlaps 

func (rng *IPv4AddressSeqRange) Overlaps(other *IPv4AddressSeqRange) bool

Overlaps returns true if this sequential range overlaps with the given sequential range.

func (*IPv4AddressSeqRange) PrefixBlockIterator 

func (rng *IPv4AddressSeqRange) PrefixBlockIterator(prefLength BitCount) IPv4AddressIterator

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 (*IPv4AddressSeqRange) PrefixIterator 

func (rng *IPv4AddressSeqRange) PrefixIterator(prefLength BitCount) IPv4AddressSeqRangeIterator

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.

func (*IPv4AddressSeqRange) SpanWithPrefixBlocks 

func (rng *IPv4AddressSeqRange) SpanWithPrefixBlocks() []*IPv4Address

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of addresses as this range.

func (*IPv4AddressSeqRange) SpanWithSequentialBlocks 

func (rng *IPv4AddressSeqRange) SpanWithSequentialBlocks() []*IPv4Address

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 (*IPv4AddressSeqRange) String 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) Subtract 

func (rng *IPv4AddressSeqRange) Subtract(other *IPv4AddressSeqRange) []*IPv4AddressSeqRange

Subtract Subtracts the given range from this range, to produce either zero, one, or two address ranges that contain the addresses in this range and not in the given range. If the result has length 2, the two ranges are ordered by ascending lowest range value.

func (*IPv4AddressSeqRange) ToCanonicalString 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) ToIP 

func (rng *IPv4AddressSeqRange) ToIP() *IPAddressSeqRange

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.

func (*IPv4AddressSeqRange) ToKey added in v1.1.0 

func (rng *IPv4AddressSeqRange) ToKey() *IPv4AddressSeqRangeKey

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, IPv4AddressSeqRangeKey instances are comparable with go operators, and thus can be used as map keys.

func (*IPv4AddressSeqRange) ToNormalizedString 

func (rng *IPv4AddressSeqRange) 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 (*IPv4AddressSeqRange) ToString 

func (rng *IPv4AddressSeqRange) ToString(lowerStringer func(*IPv4Address) string, separator string, upperStringer func(*IPv4Address) string) string

func (*IPv4AddressSeqRange) UpperBytes 

func (rng *IPv4AddressSeqRange) UpperBytes() []byte

UpperBytes returns the highest address in the range, the one with the highest numeric value, as a byte slice

type IPv4AddressSeqRangeIterator 

type IPv4AddressSeqRangeIterator interface {
	HasNext

	// Next returns the next sequential address range, or nil if there is none left.
	Next() *IPv4AddressSeqRange
}

IPv4AddressSeqRangeIterator iterates through IPv4 address sequential ranges

type IPv4AddressSeqRangeKey added in v1.1.0 

type IPv4AddressSeqRangeKey struct {
	// contains filtered or unexported fields
}

IPv4AddressSeqRangeKey is a representation of IPv4AddressSeqRange that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators It can be used as a map key. The zero value is a range from 0.0.0.0 to itself

func (*IPv4AddressSeqRangeKey) String added in v1.1.1 

func (key *IPv4AddressSeqRangeKey) String() string

String calls the String method in the corresponding sequential range

func (*IPv4AddressSeqRangeKey) ToSeqRange added in v1.1.0 

func (key *IPv4AddressSeqRangeKey) ToSeqRange() *IPv4AddressSeqRange

ToSeqRange converts to the associated sequential range

type IPv4AddressTrie added in v1.1.0 

type IPv4AddressTrie struct {
	// contains filtered or unexported fields
}

IPv4AddressTrie represents an IPv4 address binary trie.

The keys are IPv4 addresses or prefix blocks.

The zero value for IPv4AddressTrie is a binary trie ready for use.

func NewIPv4AddressTrie added in v1.1.0 

func NewIPv4AddressTrie() *IPv4AddressTrie

NewIPv4AddressTrie constructs an IPv4 address trie with the root as the 0.0.0.0/0 prefix block

func (*IPv4AddressTrie) Add added in v1.1.0 

func (trie *IPv4AddressTrie) Add(addr *IPv4Address) bool

Add adds the address to this trie. Returns true if the address did not already exist in the trie.

func (*IPv4AddressTrie) AddNode added in v1.1.0 

func (trie *IPv4AddressTrie) AddNode(addr *IPv4Address) *IPv4AddressTrieNode

AddNode adds the address to this trie. The new or existing node for the address is returned.

func (*IPv4AddressTrie) AddTrie added in v1.1.0 

func (trie *IPv4AddressTrie) AddTrie(added *IPv4AddressTrieNode) *IPv4AddressTrieNode

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.

func (*IPv4AddressTrie) AddedNodesTreeString added in v1.1.0 

func (trie *IPv4AddressTrie) 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 (*IPv4AddressTrie) AllNodeIterator added in v1.1.0 

func (trie *IPv4AddressTrie) AllNodeIterator(forward bool) IPv4TrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes in the trie in forward or reverse tree order.

func (*IPv4AddressTrie) BlockSizeAllNodeIterator added in v1.1.0 

func (trie *IPv4AddressTrie) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IPv4TrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*IPv4AddressTrie) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (trie *IPv4AddressTrie) BlockSizeCachingAllNodeIterator() CachingIPv4TrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

func (*IPv4AddressTrie) BlockSizeNodeIterator added in v1.1.0 

func (trie *IPv4AddressTrie) BlockSizeNodeIterator(lowerSubNodeFirst bool) IPv4TrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*IPv4AddressTrie) CeilingAddedNode added in v1.1.0 

func (trie *IPv4AddressTrie) CeilingAddedNode(addr *IPv4Address) *IPv4AddressTrieNode

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 tree

func (*IPv4AddressTrie) Clear added in v1.1.0 

func (trie *IPv4AddressTrie) Clear()

Clear removes all added nodes from the tree, after which IsEmpty() will return true

func (*IPv4AddressTrie) Clone added in v1.1.0 

func (trie *IPv4AddressTrie) Clone() *IPv4AddressTrie

Clone clones this trie

func (*IPv4AddressTrie) ConstructAddedNodesTree added in v1.1.0 

func (trie *IPv4AddressTrie) ConstructAddedNodesTree() *IPv4AddressTrie

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. 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 (*IPv4AddressTrie) ContainedFirstAllNodeIterator added in v1.1.0 

func (trie *IPv4AddressTrie) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) IPv4TrieNodeIterator

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 (*IPv4AddressTrie) ContainedFirstIterator added in v1.1.0 

func (trie *IPv4AddressTrie) ContainedFirstIterator(forwardSubNodeOrder bool) IPv4TrieNodeIteratorRem

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 (*IPv4AddressTrie) ContainingFirstAllNodeIterator added in v1.1.0 

func (trie *IPv4AddressTrie) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingIPv4TrieNodeIterator

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 and linear space (proportional to tree size).

func (*IPv4AddressTrie) ContainingFirstIterator added in v1.1.0 

func (trie *IPv4AddressTrie) ContainingFirstIterator(forwardSubNodeOrder bool) CachingIPv4TrieNodeIterator

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 and linear space (proportional to tree size).

func (*IPv4AddressTrie) Contains added in v1.1.0 

func (trie *IPv4AddressTrie) Contains(addr *IPv4Address) 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 (*IPv4AddressTrie) DescendingIterator added in v1.1.0 

func (trie *IPv4AddressTrie) DescendingIterator() IPv4AddressIterator

DescendingIterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in reverse sorted element order.

func (*IPv4AddressTrie) ElementContains added in v1.1.0 

func (trie *IPv4AddressTrie) ElementContains(addr *IPv4Address) 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 (*IPv4AddressTrie) ElementsContainedBy added in v1.1.0 

func (trie *IPv4AddressTrie) ElementsContainedBy(addr *IPv4Address) *IPv4AddressTrieNode

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 (*IPv4AddressTrie) ElementsContaining added in v1.1.0 

func (trie *IPv4AddressTrie) ElementsContaining(addr *IPv4Address) *ContainmentPath

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 (*IPv4AddressTrie) Equal added in v1.1.0 

func (trie *IPv4AddressTrie) Equal(other *IPv4AddressTrie) bool

Equal returns whether the given argument is a trie with a set of nodes with the same keys as in this trie

func (*IPv4AddressTrie) FirstAddedNode added in v1.1.0 

func (trie *IPv4AddressTrie) FirstAddedNode() *IPv4AddressTrieNode

FirstAddedNode returns the first (lowest-valued) added node in the trie, or nil if there are no added entries in this tree

func (*IPv4AddressTrie) FirstNode added in v1.1.0 

func (trie *IPv4AddressTrie) FirstNode() *IPv4AddressTrieNode

FirstNode returns the first (lowest-valued) node in the trie or nil if the trie has no nodes

func (*IPv4AddressTrie) FloorAddedNode added in v1.1.0 

func (trie *IPv4AddressTrie) FloorAddedNode(addr *IPv4Address) *IPv4AddressTrieNode

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 tree

func (IPv4AddressTrie) Format added in v1.1.0 

func (trie IPv4AddressTrie) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*IPv4AddressTrie) GetAddedNode added in v1.1.0 

func (trie *IPv4AddressTrie) GetAddedNode(addr *IPv4Address) *IPv4AddressTrieNode

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 (*IPv4AddressTrie) GetNode added in v1.1.0 

func (trie *IPv4AddressTrie) GetNode(addr *IPv4Address) *IPv4AddressTrieNode

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 (*IPv4AddressTrie) GetRoot added in v1.1.0 

func (trie *IPv4AddressTrie) GetRoot() *IPv4AddressTrieNode

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 (*IPv4AddressTrie) HigherAddedNode added in v1.1.0 

func (trie *IPv4AddressTrie) HigherAddedNode(addr *IPv4Address) *IPv4AddressTrieNode

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 tree

func (*IPv4AddressTrie) IsEmpty added in v1.1.0 

func (trie *IPv4AddressTrie) IsEmpty() bool

IsEmpty returns true if there are not any added nodes within this tree

func (*IPv4AddressTrie) Iterator added in v1.1.0 

func (trie *IPv4AddressTrie) Iterator() IPv4AddressIterator

Iterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in sorted element order.

func (*IPv4AddressTrie) LastAddedNode added in v1.1.0 

func (trie *IPv4AddressTrie) LastAddedNode() *IPv4AddressTrieNode

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 tree

func (*IPv4AddressTrie) LastNode added in v1.1.0 

func (trie *IPv4AddressTrie) LastNode() *IPv4AddressTrieNode

LastNode returns the last (highest-valued) node in the trie or nil if the trie has no nodes

func (*IPv4AddressTrie) LongestPrefixMatch added in v1.1.0 

func (trie *IPv4AddressTrie) LongestPrefixMatch(addr *IPv4Address) *IPv4Address

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 (*IPv4AddressTrie) LongestPrefixMatchNode added in v1.1.0 

func (trie *IPv4AddressTrie) LongestPrefixMatchNode(addr *IPv4Address) *IPv4AddressTrieNode

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 (*IPv4AddressTrie) LowerAddedNode added in v1.1.0 

func (trie *IPv4AddressTrie) LowerAddedNode(addr *IPv4Address) *IPv4AddressTrieNode

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 tree

func (*IPv4AddressTrie) NodeIterator added in v1.1.0 

func (trie *IPv4AddressTrie) NodeIterator(forward bool) IPv4TrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes in the trie in forward or reverse tree order.

func (*IPv4AddressTrie) NodeSize added in v1.1.0 

func (trie *IPv4AddressTrie) NodeSize() int

NodeSize returns the number of nodes in the tree, which is always more than the number of elements.

func (*IPv4AddressTrie) Remove added in v1.1.0 

func (trie *IPv4AddressTrie) Remove(addr *IPv4Address) 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.

func (*IPv4AddressTrie) RemoveElementsContainedBy added in v1.1.0 

func (trie *IPv4AddressTrie) RemoveElementsContainedBy(addr *IPv4Address) *IPv4AddressTrieNode

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 (*IPv4AddressTrie) Size added in v1.1.0 

func (trie *IPv4AddressTrie) 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 (*IPv4AddressTrie) String added in v1.1.0 

func (trie *IPv4AddressTrie) String() string

String returns a visual representation of the tree with one node per line.

func (*IPv4AddressTrie) ToAssociative added in v1.1.0 

func (trie *IPv4AddressTrie) ToAssociative() *IPv4AddressAssociativeTrie

ToAssociative converts to the associative representation of this trie

func (*IPv4AddressTrie) ToBase added in v1.1.0 

func (trie *IPv4AddressTrie) ToBase() *AddressTrie

ToBase converts to the polymorphic representation of this trie

func (*IPv4AddressTrie) TreeString added in v1.1.0 

func (trie *IPv4AddressTrie) 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 IPv4AddressTrieNode added in v1.1.0 

type IPv4AddressTrieNode struct {
	// contains filtered or unexported fields
}

IPv4AddressTrieNode represents a node in an IPv4AddressTrie.

Trie nodes are created by tries during add operations.

If a trie node is copied, a panic will result when methods that alter the trie are called on the copied node.

Iterator methods allow for traversal of the sub-trie with this node as the root.

If an iterator is advanced following a trie modification that followed the creation of the iterator, the iterator will panic.

func (*IPv4AddressTrieNode) AllNodeIterator added in v1.1.0 

func (node *IPv4AddressTrieNode) AllNodeIterator(forward bool) IPv4TrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*IPv4AddressTrieNode) AsNewTrie added in v1.1.0 

func (node *IPv4AddressTrieNode) AsNewTrie() *IPv4AddressTrie

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 (*IPv4AddressTrieNode) BlockSizeAllNodeIterator added in v1.1.0 

func (node *IPv4AddressTrieNode) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IPv4TrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all the nodes, ordered by keys from the largest prefix blocks to the 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 (*IPv4AddressTrieNode) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (node *IPv4AddressTrieNode) BlockSizeCachingAllNodeIterator() CachingIPv4TrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest and then to individual addresses, in the sub-trie with this node as the root.

func (*IPv4AddressTrieNode) BlockSizeNodeIterator added in v1.1.0 

func (node *IPv4AddressTrieNode) BlockSizeNodeIterator(lowerSubNodeFirst bool) IPv4TrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes, ordered by keys from the largest prefix blocks to the 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 (*IPv4AddressTrieNode) CeilingAddedNode added in v1.1.0 

func (node *IPv4AddressTrieNode) CeilingAddedNode(addr *Address) *IPv4AddressTrieNode

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 (*IPv4AddressTrieNode) Clear added in v1.1.0 

func (node *IPv4AddressTrieNode) Clear()

Clear removes this node and all sub-nodes from the tree, after which isEmpty() will return true.

func (*IPv4AddressTrieNode) Clone added in v1.1.0 

func (node *IPv4AddressTrieNode) Clone() *IPv4AddressTrieNode

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 (*IPv4AddressTrieNode) CloneTree added in v1.1.0 

func (node *IPv4AddressTrieNode) CloneTree() *IPv4AddressTrieNode

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 (*IPv4AddressTrieNode) Compare added in v1.1.0 

func (node *IPv4AddressTrieNode) Compare(other *IPv4AddressTrieNode) int

Compare returns -1, 0 or 1 if this node is less than, equal, or greater than the other, according to the key and the trie order.

func (*IPv4AddressTrieNode) ContainedFirstAllNodeIterator added in v1.1.0 

func (node *IPv4AddressTrieNode) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) IPv4TrieNodeIterator

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary tree 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 (*IPv4AddressTrieNode) ContainedFirstIterator added in v1.1.0 

func (node *IPv4AddressTrieNode) ContainedFirstIterator(forwardSubNodeOrder bool) IPv4TrieNodeIteratorRem

ContainedFirstIterator returns an iterator that does a post-order binary tree 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 (*IPv4AddressTrieNode) ContainingFirstAllNodeIterator added in v1.1.0 

func (node *IPv4AddressTrieNode) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingIPv4TrieNodeIterator

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*IPv4AddressTrieNode) ContainingFirstIterator added in v1.1.0 

func (node *IPv4AddressTrieNode) ContainingFirstIterator(forwardSubNodeOrder bool) CachingIPv4TrieNodeIterator

ContainingFirstIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*IPv4AddressTrieNode) Contains added in v1.1.0 

func (node *IPv4AddressTrieNode) Contains(addr *IPv4Address) 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 exists already in the trie, false otherwise.

Use GetAddedNode to get the node for the address rather than just checking for its existence.

func (*IPv4AddressTrieNode) DescendingIterator added in v1.1.0 

func (node *IPv4AddressTrieNode) DescendingIterator() IPv4AddressIterator

DescendingIterator returns an iterator that iterates through the elements of the sub-trie with this node as the root. The iteration is in reverse sorted element order.

func (*IPv4AddressTrieNode) ElementContains added in v1.1.0 

func (node *IPv4AddressTrieNode) ElementContains(addr *IPv4Address) 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 (*IPv4AddressTrieNode) ElementsContainedBy added in v1.1.0 

func (node *IPv4AddressTrieNode) ElementsContainedBy(addr *IPv4Address) *IPv4AddressTrieNode

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 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 (*IPv4AddressTrieNode) ElementsContaining added in v1.1.0 

func (node *IPv4AddressTrieNode) ElementsContaining(addr *IPv4Address) *ContainmentPath

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 (*IPv4AddressTrieNode) Equal added in v1.1.0 

func (node *IPv4AddressTrieNode) Equal(other *IPv4AddressTrieNode) bool

Equal returns whether the key and mapped value match those of the given node

func (*IPv4AddressTrieNode) FirstAddedNode added in v1.1.0 

func (node *IPv4AddressTrieNode) FirstAddedNode() *IPv4AddressTrieNode

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 tree or sub-trie

func (*IPv4AddressTrieNode) FirstNode added in v1.1.0 

func (node *IPv4AddressTrieNode) FirstNode() *IPv4AddressTrieNode

FirstNode returns the first (the lowest valued) node in the sub-trie originating from this node

func (*IPv4AddressTrieNode) FloorAddedNode added in v1.1.0 

func (node *IPv4AddressTrieNode) FloorAddedNode(addr *Address) *IPv4AddressTrieNode

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 (IPv4AddressTrieNode) Format added in v1.1.0 

func (node IPv4AddressTrieNode) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*IPv4AddressTrieNode) GetAddedNode added in v1.1.0 

func (node *IPv4AddressTrieNode) GetAddedNode(addr *IPv4Address) *IPv4AddressTrieNode

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 (*IPv4AddressTrieNode) GetKey added in v1.1.0 

func (node *IPv4AddressTrieNode) GetKey() *IPv4Address

GetKey gets the key used for placing the node in the tree.

func (*IPv4AddressTrieNode) GetLowerSubNode added in v1.1.0 

func (node *IPv4AddressTrieNode) GetLowerSubNode() *IPv4AddressTrieNode

GetLowerSubNode gets the direct child node whose key is smallest in value

func (*IPv4AddressTrieNode) GetNode added in v1.1.0 

func (node *IPv4AddressTrieNode) GetNode(addr *IPv4Address) *IPv4AddressTrieNode

GetNode gets the node in the trie, with this sub-node 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 (*IPv4AddressTrieNode) GetParent added in v1.1.0 

func (node *IPv4AddressTrieNode) GetParent() *IPv4AddressTrieNode

GetParent gets the node from which this node is a direct child node, or nil if this is the root.

func (*IPv4AddressTrieNode) GetUpperSubNode added in v1.1.0 

func (node *IPv4AddressTrieNode) GetUpperSubNode() *IPv4AddressTrieNode

GetUpperSubNode gets the direct child node whose key is largest in value

func (*IPv4AddressTrieNode) HigherAddedNode added in v1.1.0 

func (node *IPv4AddressTrieNode) HigherAddedNode(addr *Address) *IPv4AddressTrieNode

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 (*IPv4AddressTrieNode) IsAdded added in v1.1.0 

func (node *IPv4AddressTrieNode) IsAdded() bool

IsAdded returns whether the node was "added". Some binary tree nodes are considered "added" and others are not. Those nodes created for key elements added to the tree 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 tree. 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 (*IPv4AddressTrieNode) IsEmpty added in v1.1.0 

func (node *IPv4AddressTrieNode) IsEmpty() bool

IsEmpty returns whether the size is 0

func (*IPv4AddressTrieNode) IsLeaf added in v1.1.0 

func (node *IPv4AddressTrieNode) 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-trie with this node as the root.

func (*IPv4AddressTrieNode) IsRoot added in v1.1.0 

func (node *IPv4AddressTrieNode) IsRoot() bool

IsRoot returns whether this is the root of the backing tree.

func (*IPv4AddressTrieNode) Iterator added in v1.1.0 

func (node *IPv4AddressTrieNode) Iterator() IPv4AddressIterator

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 (*IPv4AddressTrieNode) LastAddedNode added in v1.1.0 

func (node *IPv4AddressTrieNode) LastAddedNode() *IPv4AddressTrieNode

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 tree or sub-trie

func (*IPv4AddressTrieNode) LastNode added in v1.1.0 

func (node *IPv4AddressTrieNode) LastNode() *IPv4AddressTrieNode

LastNode returns the last (the highest valued) node in the sub-trie originating from this node

func (*IPv4AddressTrieNode) LongestPrefixMatch added in v1.1.0 

func (node *IPv4AddressTrieNode) LongestPrefixMatch(addr *IPv4Address) *Address

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 (*IPv4AddressTrieNode) LongestPrefixMatchNode added in v1.1.0 

func (node *IPv4AddressTrieNode) LongestPrefixMatchNode(addr *IPv4Address) *IPv4AddressTrieNode

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 (*IPv4AddressTrieNode) LowerAddedNode added in v1.1.0 

func (node *IPv4AddressTrieNode) LowerAddedNode(addr *Address) *IPv4AddressTrieNode

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 (*IPv4AddressTrieNode) NextAddedNode added in v1.1.0 

func (node *IPv4AddressTrieNode) NextAddedNode() *IPv4AddressTrieNode

NextAddedNode returns the first added node that follows this node following the tree order

func (*IPv4AddressTrieNode) NextNode added in v1.1.0 

func (node *IPv4AddressTrieNode) NextNode() *IPv4AddressTrieNode

NextNode returns the node that follows this node following the tree order

func (*IPv4AddressTrieNode) NodeIterator added in v1.1.0 

func (node *IPv4AddressTrieNode) NodeIterator(forward bool) IPv4TrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*IPv4AddressTrieNode) NodeSize added in v1.1.0 

func (node *IPv4AddressTrieNode) 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 (*IPv4AddressTrieNode) PreviousAddedNode added in v1.1.0 

func (node *IPv4AddressTrieNode) PreviousAddedNode() *IPv4AddressTrieNode

PreviousAddedNode returns the first added node that precedes this node following the tree order

func (*IPv4AddressTrieNode) PreviousNode added in v1.1.0 

func (node *IPv4AddressTrieNode) PreviousNode() *IPv4AddressTrieNode

PreviousNode returns the node that precedes this node following the tree order

func (*IPv4AddressTrieNode) Remove added in v1.1.0 

func (node *IPv4AddressTrieNode) 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 (*IPv4AddressTrieNode) RemoveElementsContainedBy added in v1.1.0 

func (node *IPv4AddressTrieNode) RemoveElementsContainedBy(addr *IPv4Address) *IPv4AddressTrieNode

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 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 (*IPv4AddressTrieNode) RemoveNode added in v1.1.0 

func (node *IPv4AddressTrieNode) RemoveNode(addr *IPv4Address) 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.

func (*IPv4AddressTrieNode) SetAdded added in v1.1.0 

func (node *IPv4AddressTrieNode) SetAdded()

SetAdded makes this node an added node, which is equivalent to adding the corresponding key to the tree. 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 tree by calling Remove. A non-added node will only remain in the tree if it needs to in the tree.

func (*IPv4AddressTrieNode) Size added in v1.1.0 

func (node *IPv4AddressTrieNode) Size() int

Size returns the number of elements in the tree. Only nodes for which IsAdded returns true are counted. When zero is returned, IsEmpty returns true.

func (*IPv4AddressTrieNode) String added in v1.1.0 

func (node *IPv4AddressTrieNode) 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 (*IPv4AddressTrieNode) ToAssociative added in v1.1.0 

func (node *IPv4AddressTrieNode) ToAssociative() *IPv4AddressAssociativeTrieNode

ToAssociative converts to the associative trie node representation of this IPv4 trie node. The node is unchanged, the returned node is the same underlying node.

func (*IPv4AddressTrieNode) ToBase added in v1.1.0 

func (node *IPv4AddressTrieNode) ToBase() *AddressTrieNode

ToBase converts to the polymorphic base representation of this IPv4 trie node. The node is unchanged, the returned node is the same underlying node.

func (*IPv4AddressTrieNode) TreeEqual added in v1.1.0 

func (node *IPv4AddressTrieNode) TreeEqual(other *IPv4AddressTrieNode) bool

TreeEqual returns whether the sub-trie represented by this node as the root node matches the given sub-trie

func (*IPv4AddressTrieNode) TreeString added in v1.1.0 

func (node *IPv4AddressTrieNode) 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 IPv4AssociativeTrieNodeIterator added in v1.1.0 

type IPv4AssociativeTrieNodeIterator interface {
	HasNext

	Next() *IPv4AddressAssociativeTrieNode
}

IPv4AssociativeTrieNodeIteratorRem iterates through an IPv4 associative address trie, until both Next returns nil and HasNext returns false

type IPv4AssociativeTrieNodeIteratorRem added in v1.1.0 

type IPv4AssociativeTrieNodeIteratorRem interface {
	IPv4AssociativeTrieNodeIterator

	// Remove removes the last iterated element from the underlying trie, and returns that element.
	// If there is no such element, it returns nil.
	Remove() *IPv4AddressAssociativeTrieNode
}

IPv4AssociativeTrieNodeIteratorRem iterates through an IPv4 associative address trie, until both Next returns nil and HasNext returns false. The iterator also allows you to remove the last added node.

type IPv4Partition 

type IPv4Partition struct {
	// contains filtered or unexported fields
}

IPv4Partition is a Partition of an IPv4 address

func PartitionIPv4WithSingleBlockSize 

func PartitionIPv4WithSingleBlockSize(newAddr *IPv4Address) IPv4Partition

PartitionIPv4WithSingleBlockSize 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 PartitionIpv4WithSpanningBlocks 

func PartitionIpv4WithSpanningBlocks(newAddr *IPv4Address) IPv4Partition

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 (IPv4Partition) ForEach 

func (p IPv4Partition) ForEach(action func(*IPv4Address))

ForEach calls the action with each partition element

func (IPv4Partition) Iterator 

func (p IPv4Partition) Iterator() IPv4AddressIterator

Iterator provides an iterator to iterate through each element of the partition.

func (IPv4Partition) PredicateForAny 

func (p IPv4Partition) PredicateForAny(predicate func(*IPv4Address) bool) bool

PredicateForAny applies the operation to each element of the partition, returning true if the given predicate returns true for any of the elements.

func (IPv4Partition) PredicateForAnyEarly 

func (p IPv4Partition) PredicateForAnyEarly(predicate func(*IPv4Address) bool) bool

PredicateForAnyEarly applies the 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 (IPv4Partition) PredicateForEach 

func (p IPv4Partition) PredicateForEach(predicate func(*IPv4Address) bool) bool

PredicateForEach applies the operation to each element of the partition, returning true if they all return true, false otherwise

func (IPv4Partition) PredicateForEachEarly 

func (p IPv4Partition) PredicateForEachEarly(predicate func(*IPv4Address) bool) bool

PredicateForEachEarly applies the 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 IPv4SectionIterator 

type IPv4SectionIterator interface {
	HasNext

	// Next returns the next address section, or nil if there is none left.
	Next() *IPv4AddressSection
}

IPv4SectionIterator iterates through IPv4 address sections

type IPv4SegInt 

type IPv4SegInt = uint8

type IPv4SegmentIterator 

type IPv4SegmentIterator interface {
	HasNext

	// Next returns the next IPv6 address segment, or nil if there is none left.
	Next() *IPv4AddressSegment
}

IPv4SegmentIterator iterates through IPv4 address segments

type IPv4SegmentValueProvider 

type IPv4SegmentValueProvider func(segmentIndex int) IPv4SegInt

func WrappedSegmentValueProviderForIPv4 

func WrappedSegmentValueProviderForIPv4(f SegmentValueProvider) IPv4SegmentValueProvider

WrappedSegmentValueProviderForIPv4 converts the given SegmentValueProvider to an IPv4SegmentValueProvider Values that do not fit IPv4SegInt are truncated.

type IPv4TrieNodeIterator added in v1.1.0 

type IPv4TrieNodeIterator interface {
	HasNext

	Next() *IPv4AddressTrieNode
}

IPv4TrieNodeIteratorRem iterates through an IPv4 address trie, until both Next returns nil and HasNext returns false

type IPv4TrieNodeIteratorRem added in v1.1.0 

type IPv4TrieNodeIteratorRem interface {
	IPv4TrieNodeIterator

	// Remove removes the last iterated element from the underlying trie, and returns that element.
	// If there is no such element, it returns nil.
	Remove() *IPv4AddressTrieNode
}

IPv4TrieNodeIteratorRem iterates through an IPv4 address trie, until both Next returns nil and HasNext returns false The iterator also allows you to remove the last visited node.

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 IPAddressString. For other inputs, use one of multiple constructor functions like NewIPv6Address. You can also use one of multiple constructors for IPAddress like NewIPAddress and then convert using ToIPv6.

func NewIPv6Address 

func NewIPv6Address(section *IPv6AddressSection) (*IPv6Address, addrerr.AddressValueError)

NewIPv6Address constructs an IPv6 address or subnet from the given address section. If the section does not have 8 segments, an error is returned.

func NewIPv6AddressFromBytes 

func NewIPv6AddressFromBytes(bytes []byte) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromBytes constructs an IPv6 address from the given byte slice. An error is returned when the byte slice has too many bytes to match the IPv6 segment count of 8. There should be 16 bytes or less, although extra leading zeros are tolerated.

func NewIPv6AddressFromInt 

func NewIPv6AddressFromInt(val *big.Int) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromInt constructs an IPv6 address from the given value. An error is returned when the values is negative or too large.

func NewIPv6AddressFromMAC 

func NewIPv6AddressFromMAC(prefix *IPv6Address, suffix *MACAddress) (*IPv6Address, addrerr.IncompatibleAddressError)

NewIPv6AddressFromMAC constructs an IPv6 address from a modified EUI-64 (Extended Unique Identifier) MAC address and an IPv6 address 64-bit prefix.

If the supplied MAC address section is an 8 byte EUI-64, then it must match the required EUI-64 format of xx-xx-ff-fe-xx-xx with the ff-fe section in the middle.

If the supplied MAC address section is a 6 byte MAC-48 or EUI-48, then the ff-fe pattern will be inserted when converting to IPv6.

The constructor will toggle the MAC U/L (universal/local) bit as required with EUI-64.

The IPv6 address section must be at least 8 bytes. If it has a zone, then the resulting address will have the same zone.

Any prefix length in the MAC address is ignored, while a prefix length in the IPv6 address is preserved but only up to the first 4 segments.

The error is either an AddressValueError for sections that are of insufficient segment count, or IncompatibleAddressError when attempting to join two MAC segments, at least one with ranged values, into an equivalent IPV6 segment range.

func NewIPv6AddressFromMACSection 

func NewIPv6AddressFromMACSection(prefix *IPv6AddressSection, suffix *MACAddressSection) (*IPv6Address, addrerr.AddressError)

NewIPv6AddressFromMACSection constructs an IPv6 address from a modified EUI-64 (Extended Unique Identifier) MAC address section and an IPv6 address section network prefix.

If the supplied MAC address section is an 8 byte EUI-64, then it must match the required EUI-64 format of xx-xx-ff-fe-xx-xx with the ff-fe section in the middle.

If the supplied MAC address section is a 6 byte MAC-48 or EUI-48, then the ff-fe pattern will be inserted when converting to IPv6.

The constructor will toggle the MAC U/L (universal/local) bit as required with EUI-64.

The IPv6 address section must be at least 8 bytes (4 segments) in length.

Any prefix length in the MAC address is ignored, while a prefix length in the IPv6 address is preserved but only up to the first 4 segments.

The error is either an AddressValueError for sections that are of insufficient segment count, or IncompatibleAddressError when unable to join two MAC segments, at least one with ranged values, into an equivalent IPV6 segment range.

func NewIPv6AddressFromPrefixedBytes 

func NewIPv6AddressFromPrefixedBytes(bytes []byte, prefixLength PrefixLen) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedBytes constructs an IPv6 address from the given byte slice and prefix length. An error is returned when the byte slice has too many bytes to match the IPv6 segment count of 8. There should be 16 bytes or less, although extra leading zeros are tolerated.

func NewIPv6AddressFromPrefixedInt 

func NewIPv6AddressFromPrefixedInt(val *big.Int, prefixLength PrefixLen) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedInt constructs an IPv6 address from the given value and prefix length. An error is returned when the values is negative or too large.

func NewIPv6AddressFromPrefixedRange 

func NewIPv6AddressFromPrefixedRange(vals, upperVals IPv6SegmentValueProvider, prefixLength PrefixLen) *IPv6Address

NewIPv6AddressFromPrefixedRange constructs an IPv6 subnet from the given values and prefix length.

func NewIPv6AddressFromPrefixedSegs 

func NewIPv6AddressFromPrefixedSegs(segments []*IPv6AddressSegment, prefixLength PrefixLen) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedSegs constructs an IPv6 address or subnet from the given segments and prefix length. If the given slice does not have 8 segments, an error is returned.

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.

func NewIPv6AddressFromPrefixedVals 

func NewIPv6AddressFromPrefixedVals(vals IPv6SegmentValueProvider, prefixLength PrefixLen) *IPv6Address

NewIPv6AddressFromPrefixedVals constructs an IPv6 address or prefix block from the given values and prefix length.

func NewIPv6AddressFromPrefixedZonedBytes 

func NewIPv6AddressFromPrefixedZonedBytes(bytes []byte, prefixLength PrefixLen, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedZonedBytes constructs an IPv6 address from the given byte slice, prefix length, and zone. An error is returned when the byte slice has too many bytes to match the IPv6 segment count of 8. There should be 16 bytes or less, although extra leading zeros are tolerated.

func NewIPv6AddressFromPrefixedZonedInt 

func NewIPv6AddressFromPrefixedZonedInt(val *big.Int, prefixLength PrefixLen, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedZonedInt constructs an IPv6 address from the given value, prefix length, and zone. An error is returned when the values is negative or too large.

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.

func NewIPv6AddressFromPrefixedZonedSegs 

func NewIPv6AddressFromPrefixedZonedSegs(segments []*IPv6AddressSegment, prefixLength PrefixLen, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromPrefixedZonedSegs constructs an IPv6 address or subnet from the given segments, prefix length, and zone. If the given slice does not have 8 segments, an error is returned.

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

func NewIPv6AddressFromRange 

func NewIPv6AddressFromRange(vals, upperVals IPv6SegmentValueProvider) *IPv6Address

NewIPv6AddressFromRange constructs an IPv6 subnet from the given values.

func NewIPv6AddressFromSegs 

func NewIPv6AddressFromSegs(segments []*IPv6AddressSegment) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromSegs constructs an IPv6 address or subnet from the given segments. If the given slice does not have 8 segments, an error is returned.

func NewIPv6AddressFromUint64 

func NewIPv6AddressFromUint64(highBytes, lowBytes uint64) *IPv6Address

NewIPv6AddressFromUint64 constructs an IPv6 address from the given values.

func NewIPv6AddressFromVals 

func NewIPv6AddressFromVals(vals IPv6SegmentValueProvider) *IPv6Address

NewIPv6AddressFromVals constructs an IPv6 address from the given values.

func NewIPv6AddressFromZonedBytes 

func NewIPv6AddressFromZonedBytes(bytes []byte, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromZonedBytes constructs an IPv6 address from the given byte slice and zone. An error is returned when the byte slice has too many bytes to match the IPv6 segment count of 8. There should be 16 bytes or less, although extra leading zeros are tolerated.

func NewIPv6AddressFromZonedInt 

func NewIPv6AddressFromZonedInt(val *big.Int, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromZonedInt constructs an IPv6 address from the given value and zone. An error is returned when the values is negative or too large.

func NewIPv6AddressFromZonedMACSection added in v1.2.0 

func NewIPv6AddressFromZonedMACSection(prefix *IPv6AddressSection, suffix *MACAddressSection, zone string) (*IPv6Address, addrerr.AddressError)

NewIPv6AddressFromZonedMACSection constructs an IPv6 address from a modified EUI-64 (Extended Unique Identifier) MAC address section, an IPv6 address section network prefix, and a zone.

It is similar to NewIPv6AddressFromMACSection but also allows you to specify a zone.

It is similar to NewIPv6AddressFromMAC, which can supply a zone with the IPv6Address argument.

func NewIPv6AddressFromZonedRange 

func NewIPv6AddressFromZonedRange(vals, upperVals IPv6SegmentValueProvider, zone string) *IPv6Address

NewIPv6AddressFromZonedRange constructs an IPv6 subnet from the given values and zone.

func NewIPv6AddressFromZonedSegs 

func NewIPv6AddressFromZonedSegs(segments []*IPv6AddressSegment, zone string) (addr *IPv6Address, err addrerr.AddressValueError)

NewIPv6AddressFromZonedSegs constructs an IPv6 address or subnet from the given segments and zone. If the given slice does not have 8 segments, an error is returned.

func NewIPv6AddressFromZonedUint64 

func NewIPv6AddressFromZonedUint64(highBytes, lowBytes uint64, zone string) *IPv6Address

NewIPv6AddressFromZonedUint64 constructs an IPv6 address from the given values and zone.

func NewIPv6AddressZoned 

func NewIPv6AddressZoned(section *IPv6AddressSection, zone string) (*IPv6Address, addrerr.AddressValueError)

NewIPv6AddressZoned constructs an IPv6 address or subnet from the given address section and zone. If the section does not have 8 segments, an error is returned.

func (*IPv6Address) AdjustPrefixLen 

func (addr *IPv6Address) AdjustPrefixLen(prefixLen BitCount) *IPv6Address

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*IPv6Address) AdjustPrefixLenZeroed 

func (addr *IPv6Address) AdjustPrefixLenZeroed(prefixLen BitCount) (*IPv6Address, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv6Address) AssignMinPrefixForBlock 

func (addr *IPv6Address) AssignMinPrefixForBlock() *IPv6Address

AssignMinPrefixForBlock returns an equivalent subnet, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this subnet.

In other words, this method assigns a prefix length to this subnet matching the largest prefix block in this subnet.

func (*IPv6Address) AssignPrefixForSingleBlock 

func (addr *IPv6Address) AssignPrefixForSingleBlock() *IPv6Address

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address - it is required that the range of values match the range of a prefix block. If there is no such address, then nil is returned.

func (*IPv6Address) BitwiseOr 

func (addr *IPv6Address) BitwiseOr(other *IPv6Address) (masked *IPv6Address, err addrerr.IncompatibleAddressError)

BitwiseOr does the bitwise disjunction with this address or subnet, useful when subnetting. It is similar to Mask which does the bitwise conjunction.

The operation is applied to all individual addresses and the result is returned.

If this is a subnet representing multiple addresses, and applying the operation to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned

func (*IPv6Address) BlockIterator 

func (addr *IPv6Address) BlockIterator(segmentCount int) IPv6AddressIterator

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 AddressType) int

CompareSize compares the counts of two subnets or addresses, the number of individual addresses within.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing 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, 0 if they are the same, or a negative integer if the other has a larger count.

func (*IPv6Address) Contains 

func (addr *IPv6Address) Contains(other AddressType) bool

Contains returns whether this is the same type and version as the given address or subnet and whether it contains all addresses in the given address or subnet.

func (*IPv6Address) ContainsPrefixBlock 

func (addr *IPv6Address) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or subnet contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPv6Address) ContainsSinglePrefixBlock 

func (addr *IPv6Address) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPv6Address) CopyBytes 

func (addr *IPv6Address) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address in the subnet into a byte slice

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6Address) CopyNetIP 

func (addr *IPv6Address) CopyNetIP(bytes net.IP) net.IP

CopyNetIP copies the value of the lowest individual address in the subnet into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6Address) CopySegments 

func (addr *IPv6Address) CopySegments(segs []*IPv6AddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*IPv6Address) CopySubSegments 

func (addr *IPv6Address) CopySubSegments(start, end int, segs []*IPv6AddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*IPv6Address) CopyUpperBytes 

func (addr *IPv6Address) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address in the subnet into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6Address) CopyUpperNetIP 

func (addr *IPv6Address) CopyUpperNetIP(bytes net.IP) net.IP

CopyUpperNetIP copies the value of the highest individual address in the subnet into a net.IP.

If the value can fit in the given net.IP slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6Address) CoverWithPrefixBlock 

func (addr *IPv6Address) CoverWithPrefixBlock() *IPv6Address

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the addresses in this subnet. The resulting block will have a larger subnet size than this, unless this subnet is already a prefix block.

func (*IPv6Address) CoverWithPrefixBlockTo 

func (addr *IPv6Address) CoverWithPrefixBlockTo(other *IPv6Address) *IPv6Address

CoverWithPrefixBlockTo returns the minimal-size prefix block that covers all the addresses spanning from this subnet to the given subnet.

func (*IPv6Address) Equal 

func (addr *IPv6Address) Equal(other AddressType) bool

Equal returns whether the given address or subnet is equal to this address or subnet. Two address instances are equal if they represent the same set of addresses.

func (*IPv6Address) ForEachSegment added in v1.2.0 

func (addr *IPv6Address) ForEachSegment(consumer func(segmentIndex int, segment *IPv6AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true Returns the number of visited segments.

func (IPv6Address) Format 

func (addr IPv6Address) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats 'v' for the default address and section format (either the normalized or canonical string), 's' (string) for the same, 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix), 'd' (decimal), 'x' (lowercase hexadecimal), and 'X' (uppercase hexadecimal). Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which is leading zero for octal and for hexadecimal, a leading "0x" or "0X" for "%#x" and "%#X" respectively, Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*IPv6Address) Get6To4IPv4Address 

func (addr *IPv6Address) Get6To4IPv4Address() (*IPv4Address, addrerr.IncompatibleAddressError)

Get6To4IPv4Address Returns the second and third segments as an IPv4Address.

func (*IPv6Address) GetBitCount 

func (addr *IPv6Address) GetBitCount() BitCount

GetBitCount returns the number of bits comprising this address, or each address in the range if a subnet, which is 128.

func (*IPv6Address) GetBitsPerSegment 

func (addr *IPv6Address) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this address. Segments in the same address are equal length.

func (*IPv6Address) GetBlockCount 

func (addr *IPv6Address) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*IPv6Address) GetBlockMaskPrefixLen 

func (addr *IPv6Address) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address with all 1s in the network section and then all 0s in the host section. A CIDR host mask is an address with all 0s in the network section and then all 1s in the host section. The prefix length is the bit-length of the network section.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this instance, indicating the network and host section of this address. The prefix length returned here indicates the whether the value of this address can be used as a mask for the network and host section of any other address. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this address represents multiple values.

func (*IPv6Address) GetByteCount 

func (addr *IPv6Address) GetByteCount() int

GetByteCount returns the number of bytes required for this address, or each address in the range if a subnet, which is 16.

func (*IPv6Address) GetBytesPerSegment 

func (addr *IPv6Address) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this address or subnet. Segments in the same address are equal length.

func (*IPv6Address) GetCount 

func (addr *IPv6Address) GetCount() *big.Int

GetCount returns the count of addresses that this address or subnet represents.

If just a single address, not a subnet of multiple addresses, returns 1.

For instance, the IP address subnet 2001:db8::/64 has the count of 2 to the power of 64.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv6Address) GetDivisionCount 

func (addr *IPv6Address) GetDivisionCount() int

GetDivisionCount returns the segment count

func (*IPv6Address) GetEmbeddedIPv4Address 

func (addr *IPv6Address) GetEmbeddedIPv4Address() (*IPv4Address, addrerr.IncompatibleAddressError)

GetEmbeddedIPv4Address gets the IPv4 address corresponding to the lowest (least-significant) 2 segments (4 bytes) in this address. Many IPv4 to IPv6 mapping schemes (but not all) use these 4 bytes for a mapped IPv4 address. An error can result when one of the associated IPv6 segments has a range of values that cannot be split into two ranges.

func (*IPv6Address) GetEmbeddedIPv4AddressAt 

func (addr *IPv6Address) GetEmbeddedIPv4AddressAt(byteIndex int) (*IPv4Address, addrerr.IncompatibleAddressError)

GetEmbeddedIPv4AddressAt produces an IPv4 address corresponding to any sequence of 4 bytes in this IPv6 address, starting at the given index.

func (*IPv6Address) GetEmbeddedIPv4AddressSection 

func (addr *IPv6Address) GetEmbeddedIPv4AddressSection() (*IPv4AddressSection, addrerr.IncompatibleAddressError)

GetEmbeddedIPv4AddressSection gets the IPv4 section corresponding to the lowest (least-significant) 2 segments (4 bytes) in this address. Many IPv4 to IPv6 mapping schemes (but not all) use these 4 bytes for a mapped IPv4 address. An error can result when one of the associated IPv6 segments has a range of values that cannot be split into two ranges.

func (*IPv6Address) GetGenericDivision 

func (addr *IPv6Address) GetGenericDivision(index int) DivisionType

GetGenericDivision returns the segment at the given index as a DivisionType

func (*IPv6Address) GetGenericSegment 

func (addr *IPv6Address) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType

func (*IPv6Address) GetHostMask 

func (addr *IPv6Address) GetHostMask() *IPv6Address

GetHostMask returns the host mask associated with the CIDR network prefix length of this address or subnet. If this address or subnet has no prefix length, then the all-ones mask is returned.

func (*IPv6Address) GetHostSection 

func (addr *IPv6Address) GetHostSection() *IPv6AddressSection

GetHostSection returns a section containing the segments with the host of the address or subnet, the bits beyond the CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

If this series has no prefix length, the returned host section will be the full section.

func (*IPv6Address) GetHostSectionLen 

func (addr *IPv6Address) GetHostSectionLen(prefLen BitCount) *IPv6AddressSection

GetHostSectionLen returns a section containing the segments with the host of the address or subnet, the bits beyond the given CIDR network prefix length. The returned section will have only as many segments as needed to contain the host.

func (*IPv6Address) GetIPVersion 

func (addr *IPv6Address) GetIPVersion() IPVersion

GetIPVersion returns IPv6, the IP version of this address

func (*IPv6Address) GetIPv4AddressSection 

func (addr *IPv6Address) GetIPv4AddressSection(startIndex, endIndex int) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

GetIPv4AddressSection produces an IPv4 address section corresponding to any sequence of bytes in this IPv6 address section

func (*IPv6Address) GetIPv6Address 

func (addr *IPv6Address) GetIPv6Address(embedded IPv4Address) (*IPv6Address, addrerr.IncompatibleAddressError)

GetIPv6Address creates an IPv6 mixed address using the given address for the trailing embedded IPv4 segments

func (*IPv6Address) GetLeadingBitCount 

func (addr *IPv6Address) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower value of the range if this is a subnet representing multiple values.

func (*IPv6Address) GetLower 

func (addr *IPv6Address) GetLower() *IPv6Address

GetLower returns the lowest address in the subnet range, which will be the receiver if it represents a single address. For example, for "1::1:2-3:4:5-6", the series "1::1:2:4:5" is returned.

func (*IPv6Address) GetLowerIPAddress 

func (addr *IPv6Address) GetLowerIPAddress() *IPAddress

GetLowerIPAddress returns the address in the subnet or address collection with the lowest numeric value, which will be the receiver if it represents a single address. GetLowerIPAddress implements the IPAddressRange interface

func (*IPv6Address) GetMaxSegmentValue 

func (addr *IPv6Address) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPv6Address) GetMinPrefixLenForBlock 

func (addr *IPv6Address) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

func (*IPv6Address) GetMixedAddressGrouping 

func (addr *IPv6Address) GetMixedAddressGrouping() (*IPv6v4MixedAddressGrouping, addrerr.IncompatibleAddressError)

GetMixedAddressGrouping creates a grouping by combining an IPv6 address section comprising the first six segments (most significant) in this address with the IPv4 section corresponding to the lowest (least-significant) two segments in this address, as produced by GetEmbeddedIPv4Address.

func (*IPv6Address) GetNetIP 

func (addr *IPv6Address) GetNetIP() net.IP

GetNetIP returns the lowest address in this subnet or address as a net.IP

func (*IPv6Address) GetNetIPAddr 

func (addr *IPv6Address) GetNetIPAddr() *net.IPAddr

GetNetIPAddr returns the lowest address in this subnet or address as a net.IPAddr

func (*IPv6Address) 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 index larger than the segment count.

func (*IPv6Address) GetSegmentCount 

func (addr *IPv6Address) GetSegmentCount() int

GetSegmentCount returns the segment count, the number of segments in this address, which is 8

func (*IPv6Address) GetSegmentStrings 

func (addr *IPv6Address) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*IPv6Address) GetSegments 

func (addr *IPv6Address) GetSegments() []*IPv6AddressSegment

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this address.

func (*IPv6Address) GetSequentialBlockCount 

func (addr *IPv6Address) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential subnets that comprise this subnet

func (*IPv6Address) GetSequentialBlockIndex 

func (addr *IPv6Address) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full subnet to be sequential, the preceding segments must be single-valued.

func (*IPv6Address) GetSubSection 

func (addr *IPv6Address) GetSubSection(index, endIndex int) *IPv6AddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*IPv6Address) GetTrailingBitCount 

func (addr *IPv6Address) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies to the lower value of the range if this is a subnet representing multiple values.

func (*IPv6Address) GetTrailingSection 

func (addr *IPv6Address) GetTrailingSection(index int) *IPv6AddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*IPv6Address) GetUpper 

func (addr *IPv6Address) GetUpper() *IPv6Address

GetUpper returns the highest address in the subnet range, which will be the receiver if it represents a single address. For example, for "1::1:2-3:4:5-6", the series "1::1:3:4:6" is returned.

func (*IPv6Address) GetUpperIPAddress 

func (addr *IPv6Address) GetUpperIPAddress() *IPAddress

GetUpperIPAddress returns the address in the subnet or address collection with the highest numeric value, which will be the receiver if it represents a single address. GetUpperIPAddress implements the IPAddressRange interface

func (*IPv6Address) GetUpperNetIP 

func (addr *IPv6Address) GetUpperNetIP() net.IP

GetUpperNetIP returns the highest address in this subnet or address as a net.IP

func (*IPv6Address) GetUpperNetIPAddr added in v1.2.0 

func (addr *IPv6Address) GetUpperNetIPAddr() *net.IPAddr

GetUpperNetIPAddr returns the highest address in this subnet or address as a net.IPAddr

func (*IPv6Address) GetUpperValue 

func (addr *IPv6Address) GetUpperValue() *big.Int

GetUpperValue returns the highest address in this subnet or address as an integer value

func (*IPv6Address) GetValue 

func (addr *IPv6Address) GetValue() *big.Int

GetValue returns the lowest address in this subnet or address as an integer value

func (*IPv6Address) GetZone 

func (addr *IPv6Address) GetZone() Zone

GetZone returns the zone it it has one, otherwise it returns NoZone, which is an empty string

func (*IPv6Address) HasZone 

func (addr *IPv6Address) HasZone() bool

HasZone returns whether this IPv6 address includes a zone or scope

func (*IPv6Address) IncludesMax 

func (addr *IPv6Address) IncludesMax() bool

IncludesMax returns whether this address includes the max address, the address whose bits are all ones, within its range

func (*IPv6Address) IncludesMaxHost 

func (addr *IPv6Address) IncludesMaxHost() bool

IncludesMaxHost returns whether the subnet contains an individual address with a host of all one-bits. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are one.

func (*IPv6Address) IncludesMaxHostLen 

func (addr *IPv6Address) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the subnet contains an individual address with a host of all one-bits, an individual address for which all bits past the given prefix length are all ones.

func (*IPv6Address) IncludesZeroHost 

func (addr *IPv6Address) IncludesZeroHost() bool

IncludesZeroHost returns whether the subnet contains an individual address with a host of zero. If the subnet has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address for which all bits past the prefix are zero.

func (*IPv6Address) IncludesZeroHostLen 

func (addr *IPv6Address) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the subnet contains an individual address with a host of zero, an individual address for which all bits past the given prefix length are zero.

func (*IPv6Address) Increment 

func (addr *IPv6Address) Increment(increment int64) *IPv6Address

Increment returns the address from the subnet that is the given increment upwards into the subnet range, with the increment of 0 returning the first address in the range.

If the increment i matches or exceeds the subnet size count c, then i - c + 1 is added to the upper address of the range. An increment matching the subnet count gives you the address just above the highest address in the subnet.

If the increment is negative, it is added to the lower address of the range. To get the address just below the lowest address of the subnet, use the increment -1.

If this is just a single address value, the address is simply incremented by the given increment, positive or negative.

If this is a subnet with multiple values, a positive increment i is equivalent i + 1 values from the subnet iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the subnet count is equivalent to the same number of iterator values preceding the upper bound of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On address overflow or underflow, Increment returns nil.

func (*IPv6Address) IncrementBoundary 

func (addr *IPv6Address) IncrementBoundary(increment int64) *IPv6Address

IncrementBoundary returns the address that is the given increment from the range boundaries of this subnet.

If the given increment is positive, adds the value to the upper address (GetUpper) in the subnet range to produce a new address. If the given increment is negative, adds the value to the lower address (GetLower) in the subnet range to produce a new address. If the increment is zero, returns this address.

If this is a single address value, that address is simply incremented by the given increment value, positive or negative.

On address overflow or underflow, IncrementBoundary returns nil.

func (*IPv6Address) Intersect 

func (addr *IPv6Address) Intersect(other *IPv6Address) *IPv6Address

Intersect returns the subnet whose addresses are found in both this and the given subnet argument, or nil if no such addresses exist.

This is also known as the conjunction of the two sets of addresses.

func (*IPv6Address) Is6Over4 

func (addr *IPv6Address) Is6Over4() bool

Is6Over4 returns whether the address or all addresses in the subnet are 6over4

func (*IPv6Address) Is6To4 

func (addr *IPv6Address) Is6To4() bool

Is6To4 returns whether the address or subnet is IPv6 to IPv4 relay

func (*IPv6Address) IsAnyLocal 

func (addr *IPv6Address) IsAnyLocal() bool

IsAnyLocal returns whether this address is the address which binds to any address on the local host. This is the address that has the value of 0, aka the unspecified address.

func (*IPv6Address) IsEUI64 

func (addr *IPv6Address) IsEUI64() bool

IsEUI64 returns whether this address is consistent with EUI64, which means the 12th and 13th bytes of the address match 0xff and 0xfe.

func (*IPv6Address) IsFullRange added in v1.2.0 

func (addr *IPv6Address) IsFullRange() bool

IsFullRange returns whether this address covers the entire IPv6 address space.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv6Address) IsIPv4Compatible 

func (addr *IPv6Address) IsIPv4Compatible() bool

IsIPv4Compatible returns whether the address or all addresses in the subnet are IPv4-compatible

func (*IPv6Address) IsIPv4Mapped 

func (addr *IPv6Address) IsIPv4Mapped() bool

IsIPv4Mapped returns whether the address or all addresses in the subnet are IPv4-mapped

::ffff:x:x/96 indicates 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] (aka [0:0:0:0:0:0:0: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 < 0, 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 prefix lengths 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 return false for this method and returns true for 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 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() IPv6AddressIterator

Iterator provides an iterator to iterate through the individual addresses of this address or subnet.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual addresses.

Call IsMultiple to determine if this instance represents multiple addresses, or GetCount for the count.

func (*IPv6Address) Mask 

func (addr *IPv6Address) Mask(other *IPv6Address) (masked *IPv6Address, err addrerr.IncompatibleAddressError)

Mask applies the given mask to all addresses represented by this IPv6Address. The mask is applied to all individual addresses.

If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned

func (*IPv6Address) MatchesWithMask 

func (addr *IPv6Address) MatchesWithMask(other *IPv6Address, mask *IPv6Address) bool

MatchesWithMask applies the mask to this address and then compares the result with the given address, returning true if they match, false otherwise.

func (*IPv6Address) MergeToPrefixBlocks 

func (addr *IPv6Address) MergeToPrefixBlocks(addrs ...*IPv6Address) []*IPv6Address

MergeToPrefixBlocks merges this subnet with the list of subnets to produce the smallest array of prefix blocks.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv6Address) MergeToSequentialBlocks 

func (addr *IPv6Address) MergeToSequentialBlocks(addrs ...*IPv6Address) []*IPv6Address

MergeToSequentialBlocks merges this with the list of addresses to produce the smallest array of sequential blocks

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv6Address) PrefixBlockIterator 

func (addr *IPv6Address) PrefixBlockIterator() IPv6AddressIterator

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() IPv6AddressIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this subnet, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this subnet.

If the subnet has no prefix length, then this is equivalent to Iterator.

func (*IPv6Address) Replace 

func (addr *IPv6Address) Replace(startIndex int, replacement *IPv6AddressSection) *IPv6Address

Replace replaces segments starting from startIndex with segments from the replacement section

func (*IPv6Address) ReplaceLen 

func (addr *IPv6Address) ReplaceLen(startIndex, endIndex int, replacement *IPv6Address, replacementIndex int) *IPv6Address

ReplaceLen replaces segments starting from startIndex and ending before endIndex with the same number of segments starting at replacementStartIndex from the replacement section Mappings to or from indices outside the range of this or the replacement address are skipped.

func (*IPv6Address) ReverseBits 

func (addr *IPv6Address) ReverseBits(perByte bool) (*IPv6Address, addrerr.IncompatibleAddressError)

ReverseBits returns a new address with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv6Address) ReverseBytes 

func (addr *IPv6Address) ReverseBytes() (*IPv6Address, addrerr.IncompatibleAddressError)

ReverseBytes returns a new address with the bytes reversed. Any prefix length is dropped.

If the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (*IPv6Address) ReverseSegments 

func (addr *IPv6Address) ReverseSegments() *IPv6Address

ReverseSegments returns a new address with the segments reversed.

func (*IPv6Address) SequentialBlockIterator 

func (addr *IPv6Address) SequentialBlockIterator() IPv6AddressIterator

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, 2.4.6.7-8.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPv6Address) SetPrefixLen 

func (addr *IPv6Address) SetPrefixLen(prefixLen BitCount) *IPv6Address

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPv6Address) SetPrefixLenZeroed 

func (addr *IPv6Address) SetPrefixLenZeroed(prefixLen BitCount) (*IPv6Address, addrerr.IncompatibleAddressError)

func (*IPv6Address) SetZone 

func (addr *IPv6Address) SetZone(zone string) *IPv6Address

SetZone returns the same address associated with the given zone, The existing zone, if any, is replaced.

func (*IPv6Address) SpanWithPrefixBlocks 

func (addr *IPv6Address) SpanWithPrefixBlocks() []*IPv6Address

SpanWithPrefixBlocks returns an array of prefix blocks that cover the same set of addresses as this subnet.

Unlike SpanWithPrefixBlocksTo, the result only includes addresses that are a part of this subnet.

func (*IPv6Address) SpanWithPrefixBlocksTo 

func (addr *IPv6Address) SpanWithPrefixBlocksTo(other *IPv6Address) []*IPv6Address

SpanWithPrefixBlocksTo returns the smallest slice of prefix block subnets that span from this subnet to the given subnet.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

From the list of returned subnets you can recover the original range (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 (*IPv6Address) SpanWithRange 

func (addr *IPv6Address) SpanWithRange(other *IPv6Address) *IPv6AddressSeqRange

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) ToBinaryString 

func (addr *IPv6Address) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6Address) ToBlock 

func (addr *IPv6Address) ToBlock(segmentIndex int, lower, upper SegInt) *IPv6Address

ToBlock creates a new block of addresses by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPv6Address) ToCanonicalString 

func (addr *IPv6Address) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address.

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

Each address has a unique canonical string, not counting the prefix length. With IP addresses, the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use ToCanonicalWildcardString for a unique string for each IP address and subnet.

func (*IPv6Address) ToCanonicalWildcardString 

func (addr *IPv6Address) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string and avoids the CIDR prefix length. Addresses and subnets with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. IPv6 addresses will be compressed according to the canonical representation.

func (*IPv6Address) ToCompressedString 

func (addr *IPv6Address) ToCompressedString() string

ToCompressedString produces a short representation of this address while remaining within the confines of standard representation(s) of the address.

For IPv6, it differs from the canonical string. It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.

func (*IPv6Address) ToCompressedWildcardString 

func (addr *IPv6Address) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, avoiding the CIDR prefix, but with full IPv6 segment compression as well, including single zero-segments.

func (*IPv6Address) ToCustomString 

func (addr *IPv6Address) ToCustomString(stringOptions addrstr.IPv6StringOptions) (string, addrerr.IncompatibleAddressError)

ToCustomString creates a customized string from this address or subnet according to the given string option parameters

Errors can result from split digits with ranged values, or mixed IPv4/v6 with ranged values, when a range cannot be split up. Options without split digits or mixed addresses do not produce errors. Single addresses do not produce errors.

func (*IPv6Address) ToEUI 

func (addr *IPv6Address) ToEUI(extended bool) (*MACAddress, addrerr.IncompatibleAddressError)

ToEUI converts to the associated MACAddress. An error is returned if the 0xfffe pattern is missing in segments 5 and 6, or if an IPv6 segment's range of values cannot be split into two ranges of values.

func (*IPv6Address) ToFullString 

func (addr *IPv6Address) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 4 characters for IPv6 segments.

func (*IPv6Address) ToHexString 

func (addr *IPv6Address) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6Address) ToIP 

func (addr *IPv6Address) ToIP() *IPAddress

ToIP converts to an IPAddress, a polymorphic type usable with all IP addresses and subnets.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6Address) ToKey added in v1.1.0 

func (addr *IPv6Address) ToKey() *IPv6AddressKey

ToKey creates the associated address key. While addresses can be compared with the Compare, TrieCompare or Equal methods as well as various provided instances of AddressComparator, they are not comparable with go operators. However, IPv6AddressKey instances are comparable with go operators, and thus can be used as map keys.

func (*IPv6Address) ToMaxHost 

func (addr *IPv6Address) ToMaxHost() (*IPv6Address, addrerr.IncompatibleAddressError)

ToMaxHost converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-ones address, the max address.

The returned address or subnet will have the same prefix and prefix length.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv6Address) ToMaxHostLen 

func (addr *IPv6Address) ToMaxHostLen(prefixLength BitCount) (*IPv6Address, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the resulting one will too, otherwise the resulting address or subnet will have no prefix length.

For instance, the zero host of 1.2.3.4 for the prefix length 16 is the address 1.2.255.255.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have max hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv6Address) ToMixedString 

func (addr *IPv6Address) ToMixedString() (string, addrerr.IncompatibleAddressError)

ToMixedString produces the mixed IPv6/IPv4 string. It is the shortest such string (ie fully compressed). For some address sections with ranges of values in the IPv4 part of the address, there is not mixed string, and an error is returned.

func (*IPv6Address) ToNormalizedString 

func (addr *IPv6Address) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For IPv6, it differs from the canonical string. Zero segments are not compressed.

Each address has a unique normalized string, not counting the prefix length. With IP addresses, the prefix length can cause two equal addresses to have different strings, for example "1.2.3.4/16" and "1.2.3.4". It can also cause two different addresses to have the same string, such as "1.2.0.0/16" for the individual address "1.2.0.0" and also the prefix block "1.2.*.*". Use the method ToNormalizedWildcardString for a unique string for each IP address and subnet.

func (*IPv6Address) ToNormalizedWildcardString 

func (addr *IPv6Address) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPv6Address) ToOctalString 

func (addr *IPv6Address) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a subnet cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6Address) ToPrefixBlock 

func (addr *IPv6Address) ToPrefixBlock() *IPv6Address

ToPrefixBlock returns the subnet associated with the prefix length of this address. If this address has no prefix length, this address is returned.

The subnet will include all addresses with the same prefix as this one, the prefix "block". The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is 1:2:3:4:5:6:7:8/64 it returns the subnet 1:2:3:4::/64 which can also be written as 1:2:3:4:*:*:*:*/64

func (*IPv6Address) ToPrefixBlockLen 

func (addr *IPv6Address) ToPrefixBlockLen(prefLen BitCount) *IPv6Address

ToPrefixBlockLen returns the subnet associated with the given prefix length.

The subnet will include all addresses with the same prefix as this one, the prefix "block" for that prefix length. The network prefix will match the prefix of this address or subnet, and the host values will span all values.

For example, if the address is 1:2:3:4:5:6:7:8 and the prefix length provided is 64, it returns the subnet 1:2:3:4::/64 which can also be written as 1:2:3:4:*:*:*:*/64

func (*IPv6Address) ToPrefixLenString 

func (addr *IPv6Address) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, a zero host section will be compressed with ::. For IPv4 the string is equivalent to the canonical string.

func (*IPv6Address) ToReverseDNSString 

func (addr *IPv6Address) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse DNS lookup string, returning an error if this address is a multiple-valued subnet for which the range cannot be represented. For 2001:db8::567:89ab it is b.a.9.8.7.6.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa

func (*IPv6Address) ToSQLWildcardString 

func (addr *IPv6Address) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the 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() *IPv6AddressSeqRange

ToSequentialRange creates a sequential range instance from the lowest and highest addresses in this subnet

The two will represent the same set of individual addresses if and only if IsSequential is true. To get a series of ranges that represent the same set of individual addresses use the SequentialBlockIterator (or PrefixIterator), and apply this method to each iterated subnet.

If this represents just a single address then the returned instance covers just that single address as well.

func (*IPv6Address) ToSinglePrefixBlockOrAddress added in v1.1.0 

func (addr *IPv6Address) ToSinglePrefixBlockOrAddress() *IPv6Address

ToSinglePrefixBlockOrAddress converts to a single prefix block or address. If the given address is a single prefix block, it is returned. If it can be converted to a single prefix block by assigning a prefix length, the converted block is returned. If it is a single address, any prefix length is removed and the address is returned. Otherwise, nil is returned. This method provides the address formats used by tries. ToSinglePrefixBlockOrAddress is quite similar to AssignPrefixForSingleBlock, which always returns prefixed addresses, while this does not.

func (*IPv6Address) ToSubnetString 

func (addr *IPv6Address) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like 1.2.*.* or 1:2::/16

In the case of IPv6, when a network prefix has been supplied, the prefix will be shown and the host section will be compressed with ::.

func (*IPv6Address) ToZeroHost 

func (addr *IPv6Address) ToZeroHost() (*IPv6Address, addrerr.IncompatibleAddressError)

ToZeroHost converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix and prefix length.

For instance, the zero host of 1.2.3.4/16 is the individual address 1.2.0.0/16.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv6Address) ToZeroHostLen 

func (addr *IPv6Address) ToZeroHostLen(prefixLength BitCount) (*IPv6Address, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address or subnet to one in which all individual addresses have a host of zero, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.

For instance, the zero host of 1.2.3.4 for the prefix length 16 is the address 1.2.0.0.

This returns an error if the subnet is a range of addresses which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a subnet segment that is not a sequential range of values.

func (*IPv6Address) ToZeroNetwork 

func (addr *IPv6Address) ToZeroNetwork() *IPv6Address

ToZeroNetwork converts the address or subnet to one in which all individual addresses have a network of zero, the network being the bits within the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix length.

func (*IPv6Address) TrieCompare added in v1.1.0 

func (addr *IPv6Address) TrieCompare(other *IPv6Address) int

TrieCompare compares two addresses according to address trie ordering. It returns a number less than zero, zero, or a number greater than zero if the first address argument is less than, equal to, or greater than the second.

The comparison is intended for individual addresses and CIDR prefix blocks. If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv6Address) TrieDecrement added in v1.1.0 

func (addr *IPv6Address) TrieDecrement() *IPv6Address

TrieDecrement returns the previous address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv6Address) TrieIncrement added in v1.1.0 

func (addr *IPv6Address) TrieIncrement() *IPv6Address

TrieIncrement returns the next address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*IPv6Address) UpperBytes 

func (addr *IPv6Address) UpperBytes() []byte

UpperBytes returns the highest address in this subnet or address as a byte slice

func (*IPv6Address) WithoutPrefixLen 

func (addr *IPv6Address) WithoutPrefixLen() *IPv6Address

WithoutPrefixLen provides the same address but with no prefix length. The values remain unchanged.

func (*IPv6Address) WithoutZone 

func (addr *IPv6Address) WithoutZone() *IPv6Address

WithoutZone returns the same address but with no zone.

func (*IPv6Address) Wrap 

func (addr *IPv6Address) Wrap() WrappedIPAddress

Wrap wraps this IP address, returning a WrappedIPAddress, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address.

func (*IPv6Address) WrapAddress added in v1.2.0 

func (addr *IPv6Address) WrapAddress() WrappedAddress

WrapAddress wraps this IP address, returning a WrappedAddress, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapAddress can be called with a nil receiver, wrapping a nil address.

type IPv6AddressAssociativeTrie added in v1.1.0 

type IPv6AddressAssociativeTrie struct {
	// contains filtered or unexported fields
}

IPv6AddressAssociativeTrie represents an IPv6 address associative binary trie.

The keys are IPv6 addresses or prefix blocks. Each can be mapped to a value.

The zero value for IPv6AddressAssociativeTrie is a binary trie ready for use.

func NewIPv6AddressAssociativeTrie added in v1.1.0 

func NewIPv6AddressAssociativeTrie() *IPv6AddressAssociativeTrie

NewIPv6AddressAssociativeTrie constructs an IPv6 associative address trie with the root as the ::/0 prefix block

func (*IPv6AddressAssociativeTrie) Add added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) Add(addr *IPv6Address) bool

Add adds the given address key to the trie, returning true if not there already.

func (*IPv6AddressAssociativeTrie) AddNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) AddNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

AddNode adds the address key to this trie. The new or existing node for the address is returned.

func (*IPv6AddressAssociativeTrie) AddTrie added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) AddTrie(added *IPv6AddressAssociativeTrieNode) *IPv6AddressAssociativeTrieNode

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.

func (*IPv6AddressAssociativeTrie) AddedNodesTreeString added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) 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 (*IPv6AddressAssociativeTrie) AllNodeIterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) AllNodeIterator(forward bool) IPv6AssociativeTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates the added all nodes in the trie following the natural trie order

func (*IPv6AddressAssociativeTrie) BlockSizeAllNodeIterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IPv6AssociativeTrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*IPv6AddressAssociativeTrie) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) BlockSizeCachingAllNodeIterator() CachingIPv6AssociativeTrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

func (*IPv6AddressAssociativeTrie) BlockSizeNodeIterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) BlockSizeNodeIterator(lowerSubNodeFirst bool) IPv6AssociativeTrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*IPv6AddressAssociativeTrie) CeilingAddedNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) CeilingAddedNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 tree

func (*IPv6AddressAssociativeTrie) Clone added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) Clone() *IPv6AddressAssociativeTrie

Clone clones this trie

func (*IPv6AddressAssociativeTrie) ConstructAddedNodesTree added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ConstructAddedNodesTree() *IPv6AddressAssociativeTrie

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. 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 (*IPv6AddressAssociativeTrie) ContainedFirstAllNodeIterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) IPv6AssociativeTrieNodeIterator

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 (*IPv6AddressAssociativeTrie) ContainedFirstIterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ContainedFirstIterator(forwardSubNodeOrder bool) IPv6AssociativeTrieNodeIteratorRem

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 (*IPv6AddressAssociativeTrie) ContainingFirstAllNodeIterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingIPv6AssociativeTrieNodeIterator

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 and linear space (proportional to tree size).

func (*IPv6AddressAssociativeTrie) ContainingFirstIterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ContainingFirstIterator(forwardSubNodeOrder bool) CachingIPv6AssociativeTrieNodeIterator

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 and linear space (proportional to tree size).

func (*IPv6AddressAssociativeTrie) Contains added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) Contains(addr *IPv6Address) 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 (*IPv6AddressAssociativeTrie) DeepEqual added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) DeepEqual(other *IPv6AddressAssociativeTrie) 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 (*IPv6AddressAssociativeTrie) DescendingIterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) DescendingIterator() IPv6AddressIterator

DescendingIterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in reverse sorted element order.

func (*IPv6AddressAssociativeTrie) ElementContains added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ElementContains(addr *IPv6Address) 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 (*IPv6AddressAssociativeTrie) ElementsContainedBy added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ElementsContainedBy(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrie) ElementsContaining added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ElementsContaining(addr *IPv6Address) *ContainmentPath

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 (*IPv6AddressAssociativeTrie) Equal added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) Equal(other *IPv6AddressAssociativeTrie) bool

Equal returns whether the given argument is a trie with a set of nodes with the same keys as in this trie

func (*IPv6AddressAssociativeTrie) FirstAddedNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) FirstAddedNode() *IPv6AddressAssociativeTrieNode

FirstAddedNode returns the first (lowest-valued) added node in the trie or nil if there are no added entries in this tree

func (*IPv6AddressAssociativeTrie) FirstNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) FirstNode() *IPv6AddressAssociativeTrieNode

FirstNode returns the first (lowest-valued) node in the trie or nil if the trie is empty

func (*IPv6AddressAssociativeTrie) FloorAddedNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) FloorAddedNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 tree

func (IPv6AddressAssociativeTrie) Format added in v1.1.0 

func (trie IPv6AddressAssociativeTrie) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*IPv6AddressAssociativeTrie) Get added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) Get(addr *IPv6Address) NodeValue

Get gets the specified 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 (*IPv6AddressAssociativeTrie) GetAddedNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) GetAddedNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrie) GetNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) GetNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrie) GetRoot added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) GetRoot() *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrie) HigherAddedNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) HigherAddedNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 tree

func (*IPv6AddressAssociativeTrie) IsEmpty added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) IsEmpty() bool

IsEmpty returns true if there are not any added nodes within this tree

func (*IPv6AddressAssociativeTrie) Iterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) Iterator() IPv6AddressIterator

Iterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in sorted element order.

func (*IPv6AddressAssociativeTrie) LastAddedNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) LastAddedNode() *IPv6AddressAssociativeTrieNode

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 tree

func (*IPv6AddressAssociativeTrie) LastNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) LastNode() *IPv6AddressAssociativeTrieNode

LastNode returns the last (highest-valued) node in the trie or nil if the trie is empty

func (*IPv6AddressAssociativeTrie) LongestPrefixMatch added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) LongestPrefixMatch(addr *IPv6Address) *IPv6Address

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 (*IPv6AddressAssociativeTrie) LongestPrefixMatchNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) LongestPrefixMatchNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrie) LowerAddedNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) LowerAddedNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 tree

func (*IPv6AddressAssociativeTrie) NodeIterator added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) NodeIterator(forward bool) IPv6AssociativeTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through all the added nodes in the trie in forward or reverse tree order.

func (*IPv6AddressAssociativeTrie) NodeSize added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) NodeSize() int

NodeSize returns the number of nodes in the tree, which is always more than the number of elements.

func (*IPv6AddressAssociativeTrie) Put added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) Put(addr *IPv6Address, value NodeValue) (bool, NodeValue)

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 (*IPv6AddressAssociativeTrie) PutNode added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) PutNode(addr *IPv6Address, value NodeValue) *IPv6AddressAssociativeTrieNode

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 tree 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 (*IPv6AddressAssociativeTrie) PutTrie added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) PutTrie(added *IPv6AddressAssociativeTrieNode) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrie) Remap added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) Remap(addr *IPv6Address, remapper func(NodeValue) NodeValue) *IPv6AddressAssociativeTrieNode

Remap remaps node values in the trie.

This will lookup the node corresponding to the given key. It will call the remapping function with the key as the first argument, regardless of whether the node is found or not.

If the node is not found, the value argument will be nil. If the node is found, the value argument will be the node's value, which can also be nil.

If the remapping function returns nil, then the matched node will be removed, if any. If it returns a non-nil value, then it will either set the existing node to have that value, or if there was no matched node, it will create a new node with that 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 value specifies changes to be made, then the trie will not be changed and a panic will ensue.

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 (*IPv6AddressAssociativeTrie) RemapIfAbsent added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) RemapIfAbsent(addr *IPv6Address, supplier func() NodeValue, insertNil bool) *IPv6AddressAssociativeTrieNode

RemapIfAbsent remaps node values in the trie, but only for nodes that do not exist or are mapped to nil.

This will look up the node corresponding to the given key. If the node is not found or mapped to nil, this will call the remapping function.

If the remapping function returns a non-nil value, then it will either set the existing node to have that value, or if there was no matched node, it will create a new node with that value. If the remapping function returns nil, then it will do the same if insertNil is true, otherwise it will do nothing.

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 value specifies changes to be made, then the trie will not be changed and ConcurrentModificationException will be thrown instead.

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.

insertNull indicates whether nil values returned from remapper should be inserted into the map, or whether nil values indicate no remapping

func (*IPv6AddressAssociativeTrie) Remove added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) Remove(addr *IPv6Address) 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.

func (*IPv6AddressAssociativeTrie) RemoveElementsContainedBy added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) RemoveElementsContainedBy(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrie) Size added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) 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 (*IPv6AddressAssociativeTrie) String added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) String() string

String returns a visual representation of the tree with one node per line.

func (*IPv6AddressAssociativeTrie) ToAssociativeBase added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ToAssociativeBase() *AssociativeAddressTrie

ToAssociativeBase converts to the polymorphic associative trie representation of this trie

func (*IPv6AddressAssociativeTrie) ToBase added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ToBase() *AddressTrie

ToBase converts to the polymorphic non-associative representation of this trie

func (*IPv6AddressAssociativeTrie) ToIPv6Base added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) ToIPv6Base() *IPv6AddressTrie

ToIPv6Base converts to the non-associative representation of this trie

func (*IPv6AddressAssociativeTrie) TreeString added in v1.1.0 

func (trie *IPv6AddressAssociativeTrie) 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 IPv6AddressAssociativeTrieNode added in v1.1.0 

type IPv6AddressAssociativeTrieNode struct {
	// contains filtered or unexported fields
}

IPv6AddressAssociativeTrieNode is a node in an IPv6AddressAssociativeTrie.

In an associative trie, each key or node can be associated with a value.

Trie nodes are created by tries during add or put operations.

If a trie node is copied, a panic will result when methods that alter the trie are called on the copied node.

Iterator methods allow for traversal of the sub-trie with this node as the root.

If an iterator is advanced following a trie modification that followed the creation of the iterator, the iterator will panic.

func (*IPv6AddressAssociativeTrieNode) AllNodeIterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) AllNodeIterator(forward bool) IPv6AssociativeTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*IPv6AddressAssociativeTrieNode) AsNewTrie added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) AsNewTrie() *IPv6AddressAssociativeTrie

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 (*IPv6AddressAssociativeTrieNode) BlockSizeAllNodeIterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IPv6AssociativeTrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all the nodes, ordered by keys from the largest prefix blocks to the 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 (*IPv6AddressAssociativeTrieNode) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) BlockSizeCachingAllNodeIterator() CachingIPv6AssociativeTrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest and then to individual addresses, in the sub-trie with this node as the root.

func (*IPv6AddressAssociativeTrieNode) BlockSizeNodeIterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) BlockSizeNodeIterator(lowerSubNodeFirst bool) IPv6AssociativeTrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes, ordered by keys from the largest prefix blocks to the 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 (*IPv6AddressAssociativeTrieNode) CeilingAddedNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) CeilingAddedNode(addr *Address) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrieNode) Clear added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) Clear()

Clear removes this node and all sub-nodes from the tree, after which isEmpty() will return true.

func (*IPv6AddressAssociativeTrieNode) ClearValue added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ClearValue()

ClearValue makes the value associated with this node the nil value

func (*IPv6AddressAssociativeTrieNode) Clone added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) Clone() *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrieNode) CloneTree added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) CloneTree() *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrieNode) Compare added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) Compare(other *IPv6AddressAssociativeTrieNode) int

Compare returns -1, 0 or 1 if this node is less than, equal, or greater than the other, according to the key and the trie order.

func (*IPv6AddressAssociativeTrieNode) ContainedFirstAllNodeIterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) IPv6AssociativeTrieNodeIterator

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary tree 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 (*IPv6AddressAssociativeTrieNode) ContainedFirstIterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ContainedFirstIterator(forwardSubNodeOrder bool) IPv6AssociativeTrieNodeIteratorRem

ContainedFirstIterator returns an iterator that does a post-order binary tree 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 (*IPv6AddressAssociativeTrieNode) ContainingFirstAllNodeIterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingIPv6AssociativeTrieNodeIterator

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*IPv6AddressAssociativeTrieNode) ContainingFirstIterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ContainingFirstIterator(forwardSubNodeOrder bool) CachingIPv6AssociativeTrieNodeIterator

ContainingFirstIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*IPv6AddressAssociativeTrieNode) Contains added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) Contains(addr *IPv6Address) 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 exists already in the trie, false otherwise.

Use GetAddedNode to get the node for the address rather than just checking for its existence.

func (*IPv6AddressAssociativeTrieNode) DeepEqual added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) DeepEqual(other *IPv6AddressAssociativeTrieNode) 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 (*IPv6AddressAssociativeTrieNode) DescendingIterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) DescendingIterator() IPv6AddressIterator

DescendingIterator returns an iterator that iterates through the elements of the sub-trie with this node as the root. The iteration is in reverse sorted element order.

func (*IPv6AddressAssociativeTrieNode) ElementContains added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ElementContains(addr *IPv6Address) 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 (*IPv6AddressAssociativeTrieNode) ElementsContainedBy added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ElementsContainedBy(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 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 (*IPv6AddressAssociativeTrieNode) ElementsContaining added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ElementsContaining(addr *IPv6Address) *ContainmentPath

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 (*IPv6AddressAssociativeTrieNode) Equal added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) Equal(other *IPv6AddressAssociativeTrieNode) bool

Equal returns whether the key and mapped value match those of the given node

func (*IPv6AddressAssociativeTrieNode) FirstAddedNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) FirstAddedNode() *IPv6AddressAssociativeTrieNode

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 tree or sub-trie

func (*IPv6AddressAssociativeTrieNode) FirstNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) FirstNode() *IPv6AddressAssociativeTrieNode

FirstNode returns the first (the lowest valued) node in the sub-trie originating from this node.

func (*IPv6AddressAssociativeTrieNode) FloorAddedNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) FloorAddedNode(addr *Address) *IPv6AddressAssociativeTrieNode

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 (IPv6AddressAssociativeTrieNode) Format added in v1.1.0 

func (node IPv6AddressAssociativeTrieNode) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*IPv6AddressAssociativeTrieNode) Get added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) Get(addr *IPv6Address) NodeValue

Get gets the specified 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 (*IPv6AddressAssociativeTrieNode) GetAddedNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) GetAddedNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrieNode) GetKey added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) GetKey() *IPv6Address

GetKey gets the key used for placing the node in the tree.

func (*IPv6AddressAssociativeTrieNode) GetLowerSubNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) GetLowerSubNode() *IPv6AddressAssociativeTrieNode

GetLowerSubNode gets the direct child node whose key is smallest in value

func (*IPv6AddressAssociativeTrieNode) GetNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) GetNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

GetNode gets the node in the trie, with this sub-node 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 (*IPv6AddressAssociativeTrieNode) GetParent added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) GetParent() *IPv6AddressAssociativeTrieNode

GetParent gets the node from which this node is a direct child node, or nil if this is the root.

func (*IPv6AddressAssociativeTrieNode) GetUpperSubNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) GetUpperSubNode() *IPv6AddressAssociativeTrieNode

GetUpperSubNode gets the direct child node whose key is largest in value

func (*IPv6AddressAssociativeTrieNode) GetValue added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) GetValue() NodeValue

GetValue sets the value associated with this node

func (*IPv6AddressAssociativeTrieNode) HigherAddedNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) HigherAddedNode(addr *Address) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrieNode) IsAdded added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) IsAdded() bool

IsAdded returns whether the node was "added". Some binary tree nodes are considered "added" and others are not. Those nodes created for key elements added to the tree 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 tree. 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 (*IPv6AddressAssociativeTrieNode) IsEmpty added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) IsEmpty() bool

IsEmpty returns whether the size is 0

func (*IPv6AddressAssociativeTrieNode) IsLeaf added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) 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-trie with this node as the root.

func (*IPv6AddressAssociativeTrieNode) IsRoot added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) IsRoot() bool

IsRoot returns whether this is the root of the backing tree.

func (*IPv6AddressAssociativeTrieNode) Iterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) Iterator() IPv6AddressIterator

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 (*IPv6AddressAssociativeTrieNode) LastAddedNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) LastAddedNode() *IPv6AddressAssociativeTrieNode

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 tree or sub-trie

func (*IPv6AddressAssociativeTrieNode) LastNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) LastNode() *IPv6AddressAssociativeTrieNode

LastNode returns the last (the highest valued) node in the sub-trie originating from this node.

func (*IPv6AddressAssociativeTrieNode) LongestPrefixMatch added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) LongestPrefixMatch(addr *IPv6Address) *Address

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 (*IPv6AddressAssociativeTrieNode) LongestPrefixMatchNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) LongestPrefixMatchNode(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrieNode) LowerAddedNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) LowerAddedNode(addr *Address) *IPv6AddressAssociativeTrieNode

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 (*IPv6AddressAssociativeTrieNode) NextAddedNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) NextAddedNode() *IPv6AddressAssociativeTrieNode

NextAddedNode returns the next node in the tree that is an added node, following the tree order, or nil if there is no such node.

func (*IPv6AddressAssociativeTrieNode) NextNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) NextNode() *IPv6AddressAssociativeTrieNode

NextNode returns the node that follows this node following the tree order

func (*IPv6AddressAssociativeTrieNode) NodeIterator added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) NodeIterator(forward bool) IPv6AssociativeTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*IPv6AddressAssociativeTrieNode) NodeSize added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) 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 (*IPv6AddressAssociativeTrieNode) PreviousAddedNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) PreviousAddedNode() *IPv6AddressAssociativeTrieNode

PreviousAddedNode returns the previous node in the tree that is an added node, following the tree order in reverse, or nil if there is no such node.

func (*IPv6AddressAssociativeTrieNode) PreviousNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) PreviousNode() *IPv6AddressAssociativeTrieNode

PreviousNode returns the node that precedes this node following the tree order.

func (*IPv6AddressAssociativeTrieNode) Remove added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) 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 (*IPv6AddressAssociativeTrieNode) RemoveElementsContainedBy added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) RemoveElementsContainedBy(addr *IPv6Address) *IPv6AddressAssociativeTrieNode

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 sub-trie that was removed from the trie, or nil if nothing was removed.

func (*IPv6AddressAssociativeTrieNode) RemoveNode added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) RemoveNode(addr *IPv6Address) 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.

func (*IPv6AddressAssociativeTrieNode) SetAdded added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) SetAdded()

SetAdded makes this node an added node, which is equivalent to adding the corresponding key to the tree. 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 tree by calling Remove. A non-added node will only remain in the tree if it needs to in the tree.

func (*IPv6AddressAssociativeTrieNode) SetValue added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) SetValue(val NodeValue)

SetValue sets the value associated with this node

func (*IPv6AddressAssociativeTrieNode) Size added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) Size() int

Size returns the number of elements in the tree. Only nodes for which IsAdded returns true are counted. When zero is returned, IsEmpty returns true.

func (*IPv6AddressAssociativeTrieNode) String added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) 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 (*IPv6AddressAssociativeTrieNode) ToAssociativeBase added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ToAssociativeBase() *AssociativeAddressTrieNode

ToAssociativeBase converts to the polymorphic associative representation of this trie node The node is unchanged, the returned node is the same underlying node.

func (*IPv6AddressAssociativeTrieNode) ToBase added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ToBase() *AddressTrieNode

ToBase converts to the polymorphic non-associative representation of this trie node The node is unchanged, the returned node is the same underlying node.

func (*IPv6AddressAssociativeTrieNode) ToIPv6Base added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) ToIPv6Base() *IPv6AddressTrieNode

ToIPv6Base converts to the non-associative representation of this IPv6 trie node. The node is unchanged, the returned node is the same underlying node.

func (*IPv6AddressAssociativeTrieNode) TreeDeepEqual added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) TreeDeepEqual(other *IPv6AddressAssociativeTrieNode) 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 (*IPv6AddressAssociativeTrieNode) TreeEqual added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) TreeEqual(other *IPv6AddressAssociativeTrieNode) bool

TreeEqual returns whether the sub-trie represented by this node as the root node matches the given sub-trie

func (*IPv6AddressAssociativeTrieNode) TreeString added in v1.1.0 

func (node *IPv6AddressAssociativeTrieNode) 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 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 IPv6AddressIterator 

type IPv6AddressIterator interface {
	HasNext

	// Next returns the next IPv6 address, or nil if there is none left.
	Next() *IPv6Address
}

IPv6AddressIterator iterates through IPv6 subnets and ranges

type IPv6AddressKey added in v1.1.0 

type IPv6AddressKey struct {
	Values [IPv6SegmentCount]struct {
		Value      IPv6SegInt
		UpperValue IPv6SegInt
	}
	Prefix PrefixKey
	Zone   Zone
}

IPv6AddressKey is a representation of IPv6Address that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators It can be used as a map key. The zero value is the address ::

func (*IPv6AddressKey) Normalize added in v1.1.0 

func (key *IPv6AddressKey) Normalize()

Normalize normalizes the given key. Normalizing a key ensures it is the single unique key for any given address or subnet.

func (*IPv6AddressKey) String added in v1.1.1 

func (key *IPv6AddressKey) String() string

String calls the String method in the corresponding address

func (*IPv6AddressKey) ToAddress added in v1.1.0 

func (key *IPv6AddressKey) ToAddress() *IPv6Address

ToAddress converts to an address instance

func (*IPv6AddressKey) ToBaseKey added in v1.1.0 

func (key *IPv6AddressKey) ToBaseKey() *AddressKey

ToBaseKey converts to key that can be used for any address type or version

func (*IPv6AddressKey) ToIPKey added in v1.1.1 

func (key *IPv6AddressKey) ToIPKey() *IPAddressKey

ToIPKey converts to key that can be used for both IPv4 and IPv6

func (*IPv6AddressKey) UpperVal added in v1.1.0 

func (key *IPv6AddressKey) UpperVal(segmentIndex int) IPv6SegInt

UpperVal provides the upper value for a given segment. For a given key, the val method provides a function of type IPv4SegmentProvider

func (*IPv6AddressKey) Val added in v1.1.0 

func (key *IPv6AddressKey) Val(segmentIndex int) IPv6SegInt

Val provides the lower value for a given segment. For a given key, the val method provides a function of type IPv4SegmentProvider

type IPv6AddressNetwork 

type IPv6AddressNetwork struct {
	// contains filtered or unexported fields
}

func (IPv6AddressNetwork) GetHostMask 

func (network IPv6AddressNetwork) GetHostMask(prefLen BitCount) *IPv6Address

func (IPv6AddressNetwork) GetLoopback 

func (network IPv6AddressNetwork) GetLoopback() *IPv6Address

func (IPv6AddressNetwork) GetNetworkMask 

func (network IPv6AddressNetwork) GetNetworkMask(prefLen BitCount) *IPv6Address

func (IPv6AddressNetwork) GetPrefixedHostMask 

func (network IPv6AddressNetwork) GetPrefixedHostMask(prefLen BitCount) *IPv6Address

func (IPv6AddressNetwork) GetPrefixedNetworkMask 

func (network IPv6AddressNetwork) GetPrefixedNetworkMask(prefLen BitCount) *IPv6Address

type IPv6AddressSection 

type IPv6AddressSection struct {
	// contains filtered or unexported fields
}

IPv6AddressSection represents a section of an IPv6 address comprising 0 to 8 IPv6 address segments. The zero values is a section with zero segments.

func NewIPv6PrefixedSection 

func NewIPv6PrefixedSection(segments []*IPv6AddressSegment, prefixLen PrefixLen) *IPv6AddressSection

NewIPv6PrefixedSection constructs an IPv6 address or subnet section from the given segments and prefix length.

func NewIPv6Section 

func NewIPv6Section(segments []*IPv6AddressSegment) *IPv6AddressSection

NewIPv6Section constructs an IPv6 address or subnet section from the given segments.

func NewIPv6SectionFromBigInt 

func NewIPv6SectionFromBigInt(val *big.Int, segmentCount int) (res *IPv6AddressSection, err addrerr.AddressValueError)

NewIPv6SectionFromBigInt creates an IPv6 address section from the given big integer, returning an error if the value is too large for the given number of segments.

func NewIPv6SectionFromBytes 

func NewIPv6SectionFromBytes(bytes []byte) *IPv6AddressSection

NewIPv6SectionFromBytes constructs an IPv6 address from the given byte slice. The segment count is determined by the slice length, even if the segment count exceeds 8 segments.

func NewIPv6SectionFromMAC 

func NewIPv6SectionFromMAC(eui *MACAddress) (res *IPv6AddressSection, err addrerr.IncompatibleAddressError)

NewIPv6SectionFromMAC constructs an IPv6 address section from a modified EUI-64 (Extended Unique Identifier) MAC address.

If the supplied MAC address section is an 8 byte EUI-64, then it must match the required EUI-64 format of xx-xx-ff-fe-xx-xx with the ff-fe section in the middle.

If the supplied MAC address section is a 6 byte MAC-48 or EUI-48, then the ff-fe pattern will be inserted when converting to IPv6.

The constructor will toggle the MAC U/L (universal/local) bit as required with EUI-64.

The error is IncompatibleAddressError when unable to join two MAC segments, at least one with ranged values, into an equivalent IPV6 segment range.

func NewIPv6SectionFromPrefixedBigInt 

func NewIPv6SectionFromPrefixedBigInt(val *big.Int, segmentCount int, prefixLen PrefixLen) (res *IPv6AddressSection, err addrerr.AddressValueError)

NewIPv6SectionFromPrefixedBigInt creates an IPv6 address or prefix block section from the given big integer, returning an error if the value is too large for the given number of segments.

func NewIPv6SectionFromPrefixedBytes 

func NewIPv6SectionFromPrefixedBytes(bytes []byte, segmentCount int, prefixLength PrefixLen) (res *IPv6AddressSection, err addrerr.AddressValueError)

NewIPv6SectionFromPrefixedBytes constructs an IPv6 address or prefix block from the given byte slice and prefix length. It allows you to specify the segment count for the supplied bytes. If the slice is too large for the given number of segments, an error is returned, although leading zeros are tolerated.

func NewIPv6SectionFromPrefixedRange added in v1.2.0 

func NewIPv6SectionFromPrefixedRange(vals, upperVals IPv6SegmentValueProvider, segmentCount int, prefixLength PrefixLen) (res *IPv6AddressSection)

NewIPv6SectionFromPrefixedRange constructs an IPv6 subnet section of the given segment count from the given values and prefix length.

func NewIPv6SectionFromPrefixedUint64 

func NewIPv6SectionFromPrefixedUint64(highBytes, lowBytes uint64, segmentCount int, prefixLength PrefixLen) (res *IPv6AddressSection)

NewIPv6SectionFromPrefixedUint64 constructs an IPv6 address or prefix block section of the given segment count from the given values and prefix length.

func NewIPv6SectionFromPrefixedVals 

func NewIPv6SectionFromPrefixedVals(vals IPv6SegmentValueProvider, segmentCount int, prefixLength PrefixLen) (res *IPv6AddressSection)

NewIPv6SectionFromPrefixedVals constructs an IPv6 address or prefix block section of the given segment count from the given values and prefix length.

func NewIPv6SectionFromRange added in v1.2.0 

func NewIPv6SectionFromRange(vals, upperVals IPv6SegmentValueProvider, segmentCount int) (res *IPv6AddressSection)

NewIPv6SectionFromRange constructs an IPv6 subnet section of the given segment count from the given values.

func NewIPv6SectionFromSegmentedBytes 

func NewIPv6SectionFromSegmentedBytes(bytes []byte, segmentCount int) (res *IPv6AddressSection, err addrerr.AddressValueError)

NewIPv6SectionFromSegmentedBytes constructs an IPv6 address from the given byte slice. It allows you to specify the segment count for the supplied bytes. If the slice is too large for the given number of segments, an error is returned, although leading zeros are tolerated.

func NewIPv6SectionFromUint64 

func NewIPv6SectionFromUint64(highBytes, lowBytes uint64, segmentCount int) (res *IPv6AddressSection)

NewIPv6SectionFromUint64 constructs an IPv6 address section of the given segment count from the given values.

func NewIPv6SectionFromVals 

func NewIPv6SectionFromVals(vals IPv6SegmentValueProvider, segmentCount int) (res *IPv6AddressSection)

NewIPv6SectionFromVals constructs an IPv6 address section of the given segment count from the given values.

func (*IPv6AddressSection) AdjustPrefixLen 

func (section *IPv6AddressSection) AdjustPrefixLen(prefixLen BitCount) *IPv6AddressSection

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*IPv6AddressSection) AdjustPrefixLenZeroed 

func (section *IPv6AddressSection) AdjustPrefixLenZeroed(prefixLen BitCount) (*IPv6AddressSection, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv6AddressSection) Append 

func (section *IPv6AddressSection) Append(other *IPv6AddressSection) *IPv6AddressSection

Append creates a new section by appending the given section to this section.

func (*IPv6AddressSection) AssignMinPrefixForBlock 

func (section *IPv6AddressSection) AssignMinPrefixForBlock() *IPv6AddressSection

AssignMinPrefixForBlock returns an equivalent address section, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this address section.

In other words, this method assigns a prefix length to this address section matching the largest prefix block in this address section.

func (*IPv6AddressSection) AssignPrefixForSingleBlock 

func (section *IPv6AddressSection) AssignPrefixForSingleBlock() *IPv6AddressSection

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address section. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address section - it is required that the range of values match the range of a prefix block. If there is no such address section, then nil is returned.

func (*IPv6AddressSection) BitwiseOr 

func (section *IPv6AddressSection) BitwiseOr(other *IPv6AddressSection) (res *IPv6AddressSection, err addrerr.IncompatibleAddressError)

BitwiseOr does the bitwise disjunction with this address section, useful when subnetting. It is similar to Mask which does the bitwise conjunction.

The operation is applied to all individual addresses and the result is returned.

If this represents multiple address sections, and applying the operation to all sections creates a set of sections that cannot be represented as a sequential range within each segment, then an error is returned

func (*IPv6AddressSection) BlockIterator 

func (section *IPv6AddressSection) BlockIterator(segmentCount int) IPv6SectionIterator

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 StandardDivGroupingType) 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 comparing 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, 0 if they are the same, or a negative integer if the other has a larger count.

func (*IPv6AddressSection) Contains 

func (section *IPv6AddressSection) Contains(other AddressSectionType) bool

Contains returns whether this is same type and version as the given address section and whether it contains all values in the given section.

Sections must also have the same number of segments to be comparable, otherwise false is returned.

func (*IPv6AddressSection) ContainsPrefixBlock 

func (section *IPv6AddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*IPv6AddressSection) ContainsSinglePrefixBlock 

func (section *IPv6AddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this section contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPv6AddressSection) CopyBytes 

func (section *IPv6AddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6AddressSection) CopySegments 

func (section *IPv6AddressSection) CopySegments(segs []*IPv6AddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*IPv6AddressSection) CopySubSegments 

func (section *IPv6AddressSection) CopySubSegments(start, end int, segs []*IPv6AddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*IPv6AddressSection) CopyUpperBytes 

func (section *IPv6AddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6AddressSection) CoverWithPrefixBlock 

func (section *IPv6AddressSection) CoverWithPrefixBlock() *IPv6AddressSection

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the individual address sections in this section. The resulting block will have a larger count than this, unless this section is already a prefix block.

func (*IPv6AddressSection) CoverWithPrefixBlockTo 

func (section *IPv6AddressSection) CoverWithPrefixBlockTo(other *IPv6AddressSection) (*IPv6AddressSection, addrerr.SizeMismatchError)

CoverWithPrefixBlockTo returns the minimal-size prefix block section that covers all the address sections spanning from this to the given section.

If the other section has a different segment count, an error is returned.

func (*IPv6AddressSection) Equal 

func (section *IPv6AddressSection) Equal(other AddressSectionType) bool

Equal returns whether the given address section is equal to this address section. Two address sections are equal if they represent the same set of sections. They must match:

  • type/version: IPv6
  • segment count
  • segment value ranges

Prefix lengths are ignored.

func (*IPv6AddressSection) ForEachSegment added in v1.2.0 

func (section *IPv6AddressSection) ForEachSegment(consumer func(segmentIndex int, segment *IPv6AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true Returns the number of visited segments.

func (*IPv6AddressSection) GetBitCount 

func (section *IPv6AddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item

func (*IPv6AddressSection) GetBitsPerSegment 

func (section *IPv6AddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (*IPv6AddressSection) GetBlockCount 

func (section *IPv6AddressSection) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*IPv6AddressSection) GetBlockMaskPrefixLen 

func (section *IPv6AddressSection) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address section is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address section with all 1s in the network section and then all 0s in the host section. A CIDR host mask is an address section with all 0s in the network section and then all 1s 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

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.

func (*IPv6AddressSection) GetIPVersion 

func (section *IPv6AddressSection) GetIPVersion() IPVersion

GetIPVersion returns IPv6, the IP version of this address section

func (*IPv6AddressSection) GetIPv4AddressSection 

func (section *IPv6AddressSection) GetIPv4AddressSection(startByteIndex, endByteIndex int) (*IPv4AddressSection, addrerr.IncompatibleAddressError)

GetIPv4AddressSection produces an IPv4 address section from a sequence of bytes in this IPv6 address section

func (*IPv6AddressSection) GetLower 

func (section *IPv6AddressSection) GetLower() *IPv6AddressSection

GetLower returns the section in the range with the lowest numeric value, which will be the same section if it represents a single value. For example, for "1::1:2-3:4:5-6", the section "1::1:2:4:5" is returned.

func (*IPv6AddressSection) GetMaxSegmentValue 

func (section *IPv6AddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*IPv6AddressSection) GetMinPrefixLenForBlock 

func (section *IPv6AddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (*IPv6AddressSection) GetNetworkMask 

func (section *IPv6AddressSection) GetNetworkMask() *IPv6AddressSection

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address section. If this section has no prefix length, then the all-ones mask is returned.

func (*IPv6AddressSection) GetNetworkPrefixLen 

func (section *IPv6AddressSection) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. It is equivalent to GetPrefixLen.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (*IPv6AddressSection) GetNetworkSection 

func (section *IPv6AddressSection) GetNetworkSection() *IPv6AddressSection

GetNetworkSection returns a subsection containing the segments with the network bits of the section. The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.

If this series has no CIDR prefix length, the returned network section will be the entire series as a prefixed section with prefix length matching the address bit length.

func (*IPv6AddressSection) GetNetworkSectionLen 

func (section *IPv6AddressSection) GetNetworkSectionLen(prefLen BitCount) *IPv6AddressSection

GetNetworkSectionLen returns a subsection containing the segments with the network of the address section, the prefix bits according to the given prefix length. The returned section will have only as many segments as needed to contain the network.

The new section will be assigned the given prefix length, unless the existing prefix length is smaller, in which case the existing prefix length will be retained.

func (*IPv6AddressSection) GetPrefixCount 

func (section *IPv6AddressSection) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetCount

func (*IPv6AddressSection) GetPrefixCountLen 

func (section *IPv6AddressSection) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length

func (*IPv6AddressSection) GetPrefixLenForSingleBlock 

func (section *IPv6AddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (*IPv6AddressSection) GetSegment 

func (section *IPv6AddressSection) GetSegment(index int) *IPv6AddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or index larger than the segment count.

func (*IPv6AddressSection) GetSegmentCount 

func (section *IPv6AddressSection) GetSegmentCount() int

func (*IPv6AddressSection) GetSegmentStrings 

func (section *IPv6AddressSection) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*IPv6AddressSection) GetSegments 

func (section *IPv6AddressSection) GetSegments() (res []*IPv6AddressSegment)

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*IPv6AddressSection) GetSequentialBlockCount 

func (section *IPv6AddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section

func (*IPv6AddressSection) GetSequentialBlockIndex 

func (section *IPv6AddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (*IPv6AddressSection) GetSubSection 

func (section *IPv6AddressSection) GetSubSection(index, endIndex int) *IPv6AddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*IPv6AddressSection) GetTrailingSection 

func (section *IPv6AddressSection) GetTrailingSection(index int) *IPv6AddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*IPv6AddressSection) GetUpper 

func (section *IPv6AddressSection) GetUpper() *IPv6AddressSection

GetUpper returns the section in the range with the highest numeric value, which will be the same section if it represents a single value. For example, for "1::1:2-3:4:5-6", the section "1::1:3:4:6" is returned.

func (*IPv6AddressSection) GetUpperValue 

func (section *IPv6AddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value

func (*IPv6AddressSection) GetValue 

func (section *IPv6AddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value

func (*IPv6AddressSection) GetZeroRangeSegments 

func (section *IPv6AddressSection) GetZeroRangeSegments() SegmentSequenceList

GetZeroRangeSegments returns the list of consecutive zero and zero prefix block segments. Each element in the list will be an segment index and a total segment count for which that count of consecutive segments starting from that index are all zero or a prefix block segment with lowest segment value zero.

func (*IPv6AddressSection) GetZeroSegments 

func (section *IPv6AddressSection) GetZeroSegments() SegmentSequenceList

GetZeroSegments returns the list of consecutive zero segments. Each element in the list will be an segment index and a total segment count for which that count of consecutive segments starting from that index are all zero.

func (*IPv6AddressSection) IncludesMax 

func (section *IPv6AddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range

func (*IPv6AddressSection) IncludesMaxHost 

func (section *IPv6AddressSection) IncludesMaxHost() bool

IncludesMaxHost returns whether the address section contains an individual address section with a host of all one-bits. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are one.

func (*IPv6AddressSection) IncludesMaxHostLen 

func (section *IPv6AddressSection) IncludesMaxHostLen(networkPrefixLength BitCount) bool

IncludesMaxHostLen returns whether the address section contains an individual address section with a host of all one-bits, an address section for which all bits past the given prefix length are all ones.

func (*IPv6AddressSection) IncludesZero 

func (section *IPv6AddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range

func (*IPv6AddressSection) IncludesZeroHost 

func (section *IPv6AddressSection) IncludesZeroHost() bool

IncludesZeroHost returns whether the address section contains an individual address section with a host of zero. If the address section has no prefix length it returns false. If the prefix length matches the bit count, then it returns true.

Otherwise, it checks whether it contains an individual address section for which all bits past the prefix are zero.

func (*IPv6AddressSection) IncludesZeroHostLen 

func (section *IPv6AddressSection) IncludesZeroHostLen(networkPrefixLength BitCount) bool

IncludesZeroHostLen returns whether the address section contains an individual section with a host of zero, a section for which all bits past the given prefix length are zero.

func (*IPv6AddressSection) Increment 

func (section *IPv6AddressSection) Increment(increment int64) *IPv6AddressSection

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (*IPv6AddressSection) IncrementBoundary 

func (section *IPv6AddressSection) IncrementBoundary(increment int64) *IPv6AddressSection

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (*IPv6AddressSection) Insert 

func (section *IPv6AddressSection) Insert(index int, other *IPv6AddressSection) *IPv6AddressSection

Insert creates a new section by inserting the given section into this section at the given index.

func (*IPv6AddressSection) Intersect 

func (section *IPv6AddressSection) Intersect(other *IPv6AddressSection) (res *IPv6AddressSection, err addrerr.SizeMismatchError)

Intersect returns the subnet sections whose individual sections are found in both this and the given subnet section argument, or nil if no such sections exist.

This is also known as the conjunction of the two sets of address sections.

If the two sections have different segment counts, an error is returned.

func (*IPv6AddressSection) IsAdaptiveZero 

func (section *IPv6AddressSection) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the section was originally created as an implicitly zero-valued section or grouping (eg 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, etc 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 (*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 < 0, or if it is larger than the bit count of this item.

func (*IPv6AddressSection) IsPrefixBlock 

func (section *IPv6AddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length or a prefix length that differs from prefix lengths for which ContainsPrefixBlock returns true.

func (*IPv6AddressSection) IsPrefixed 

func (section *IPv6AddressSection) IsPrefixed() bool

IsPrefixed returns whether this section has an associated prefix length

func (*IPv6AddressSection) IsSequential 

func (section *IPv6AddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (*IPv6AddressSection) IsSingleNetwork 

func (section *IPv6AddressSection) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address section.

func (*IPv6AddressSection) IsSinglePrefixBlock 

func (section *IPv6AddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock() except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPv6AddressSection) IsZero 

func (section *IPv6AddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero

func (*IPv6AddressSection) IsZeroHost 

func (section *IPv6AddressSection) IsZeroHost() bool

IsZeroHost returns whether this section has a prefix length and if so, whether the host section is always zero for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (*IPv6AddressSection) IsZeroHostLen 

func (section *IPv6AddressSection) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual sections in this address section, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (*IPv6AddressSection) Iterator 

func (section *IPv6AddressSection) Iterator() IPv6SectionIterator

Iterator provides an iterator to iterate through the individual address sections of this address section.

When iterating, the prefix length is preserved. Remove it using WithoutPrefixLen prior to iterating if you wish to drop it from all individual address sections.

Call IsMultiple to determine if this instance represents multiple address sections, or GetCount for the count.

func (*IPv6AddressSection) Mask 

func (section *IPv6AddressSection) Mask(other *IPv6AddressSection) (res *IPv6AddressSection, err addrerr.IncompatibleAddressError)

Mask applies the given mask to all address sections represented by this secction, returning the result.

If the sections do not have a comparable number of segments, an error is returned.

If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a sequential range within each segment, then an error is returned

func (*IPv6AddressSection) MatchesWithMask 

func (section *IPv6AddressSection) MatchesWithMask(other *IPv6AddressSection, mask *IPv6AddressSection) bool

MatchesWithMask applies the mask to this address section and then compares the result with the given address section, returning true if they match, false otherwise. To match, both the given section and mask must have the same number of segments as this section.

func (*IPv6AddressSection) MergeToPrefixBlocks 

func (section *IPv6AddressSection) MergeToPrefixBlocks(sections ...*IPv6AddressSection) ([]*IPv6AddressSection, addrerr.SizeMismatchError)

MergeToPrefixBlocks merges this section with the list of sections to produce the smallest array of prefix blocks.

The resulting slice is sorted from lowest value to highest, regardless of the size of each prefix block.

func (*IPv6AddressSection) MergeToSequentialBlocks 

func (section *IPv6AddressSection) MergeToSequentialBlocks(sections ...*IPv6AddressSection) ([]*IPv6AddressSection, addrerr.SizeMismatchError)

MergeToSequentialBlocks merges this with the list of sections to produce the smallest array of sequential blocks

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv6AddressSection) PrefixBlockIterator 

func (section *IPv6AddressSection) PrefixBlockIterator() IPv6SectionIterator

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() IPv6SectionIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this address section, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this address section.

If the series has no prefix length, then this is equivalent to Iterator.

func (*IPv6AddressSection) Replace 

func (section *IPv6AddressSection) Replace(index int, replacement *IPv6AddressSection) *IPv6AddressSection

Replace replaces the segments of this section starting at the given index with the given replacement segments

func (*IPv6AddressSection) ReplaceLen 

func (section *IPv6AddressSection) ReplaceLen(startIndex, endIndex int, replacement *IPv6AddressSection, replacementStartIndex, replacementEndIndex int) *IPv6AddressSection

ReplaceLen replaces the segments starting from startIndex and ending before endIndex with the segments starting at replacementStartIndex and ending before replacementEndIndex from the replacement section

func (*IPv6AddressSection) ReverseBits 

func (section *IPv6AddressSection) ReverseBits(perByte bool) (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ReverseBits returns a new section with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv6AddressSection) ReverseBytes 

func (section *IPv6AddressSection) ReverseBytes() (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ReverseBytes returns a new section with the bytes reversed. Any prefix length is dropped.

If the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (*IPv6AddressSection) ReverseSegments 

func (section *IPv6AddressSection) ReverseSegments() *IPv6AddressSection

ReverseSegments returns a new section with the segments reversed.

func (*IPv6AddressSection) SequentialBlockIterator 

func (section *IPv6AddressSection) SequentialBlockIterator() IPv6SectionIterator

SequentialBlockIterator iterates through the sequential address sections that make up this address section.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*IPv6AddressSection) SetPrefixLen 

func (section *IPv6AddressSection) SetPrefixLen(prefixLen BitCount) *IPv6AddressSection

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

func (*IPv6AddressSection) SetPrefixLenZeroed 

func (section *IPv6AddressSection) SetPrefixLenZeroed(prefixLen BitCount) (*IPv6AddressSection, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

If this address section has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address section has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (ie bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*IPv6AddressSection) SpanWithPrefixBlocks 

func (section *IPv6AddressSection) SpanWithPrefixBlocks() []*IPv6AddressSection

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual address sections as this section.

Unlike SpanWithPrefixBlocksTo, the result only includes blocks that are a part of this section.

func (*IPv6AddressSection) SpanWithPrefixBlocksTo 

func (section *IPv6AddressSection) SpanWithPrefixBlocksTo(other *IPv6AddressSection) ([]*IPv6AddressSection, addrerr.SizeMismatchError)

SpanWithPrefixBlocksTo returns the smallest slice of prefix block subnet sections that span from this section to the given section.

If the given section has a different segment count, an error is returned.

The resulting slice is sorted from lowest address value to highest, regardless of the size of each prefix block.

func (*IPv6AddressSection) SpanWithSequentialBlocks 

func (section *IPv6AddressSection) SpanWithSequentialBlocks() []*IPv6AddressSection

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of sections as this.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

Unlike SpanWithSequentialBlocksTo, this method only includes values that are a part of this section.

func (*IPv6AddressSection) SpanWithSequentialBlocksTo 

func (section *IPv6AddressSection) SpanWithSequentialBlocksTo(other *IPv6AddressSection) ([]*IPv6AddressSection, addrerr.SizeMismatchError)

SpanWithSequentialBlocksTo produces the smallest slice of sequential block address sections that span from this section to the given section.

func (*IPv6AddressSection) String 

func (section *IPv6AddressSection) String() string

String implements the fmt.Stringer interface, returning the normalized string provided by ToNormalizedString, or "<nil>" if the receiver is a nil pointer

func (*IPv6AddressSection) Subtract 

func (section *IPv6AddressSection) Subtract(other *IPv6AddressSection) (res []*IPv6AddressSection, err addrerr.SizeMismatchError)

Subtract subtracts the given subnet sections from this subnet section, returning an array of sections for the result (the subnet sections will not be contiguous so an array is required).

Subtract computes the subnet difference, the set of address sections in this address section but not in the provided section. This is also known as the relative complement of the given argument in this subnet section.

This is set subtraction, not subtraction of values.

func (*IPv6AddressSection) TestBit 

func (section *IPv6AddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv6AddressSection) ToBinaryString 

func (section *IPv6AddressSection) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address section as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6AddressSection) ToBlock 

func (section *IPv6AddressSection) ToBlock(segmentIndex int, lower, upper SegInt) *IPv6AddressSection

ToBlock creates a new block of address sections by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*IPv6AddressSection) ToCanonicalString 

func (section *IPv6AddressSection) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address section.

For IPv6, RFC 5952 describes canonical string representation. https://en.wikipedia.org/wiki/IPv6_address#Representation http://tools.ietf.org/html/rfc5952

If this section has a prefix length, it will be included in the string.

func (*IPv6AddressSection) ToCanonicalWildcardString 

func (section *IPv6AddressSection) ToCanonicalWildcardString() string

ToCanonicalWildcardString produces a string similar to the canonical string but avoids the CIDR prefix length. Address sections with a network prefix length will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix length notation. IPv6 sections will be compressed according to the canonical representation.

func (*IPv6AddressSection) ToCompressedString 

func (section *IPv6AddressSection) ToCompressedString() string

ToCompressedString produces a short representation of this address section while remaining within the confines of standard representation(s) of the address.

For IPv6, it differs from the canonical string. It compresses the maximum number of zeros and/or host segments with the IPv6 compression notation '::'.

func (*IPv6AddressSection) ToCompressedWildcardString 

func (section *IPv6AddressSection) ToCompressedWildcardString() string

ToCompressedWildcardString produces a string similar to ToNormalizedWildcardString, avoiding the CIDR prefix, but with full IPv6 segment compression as well, including single zero-segments.

func (*IPv6AddressSection) ToCustomString 

func (section *IPv6AddressSection) ToCustomString(stringOptions addrstr.IPv6StringOptions) (string, addrerr.IncompatibleAddressError)

ToCustomString creates a customized string from this address section according to the given string option parameters

Errors can result from split digits with ranged values, or mixed IPv4/v6 with ranged values, when the segment ranges are incompatible.

func (*IPv6AddressSection) ToDivGrouping 

func (section *IPv6AddressSection) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToIPv6.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSection) ToFullString 

func (section *IPv6AddressSection) ToFullString() string

ToFullString produces a string with no compressed segments and all segments of full length with leading zeros, which is 4 characters for IPv6 segments.

func (*IPv6AddressSection) ToHexString 

func (section *IPv6AddressSection) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address section as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6AddressSection) ToIP 

func (section *IPv6AddressSection) ToIP() *IPAddressSection

ToIP converts to an IPAddressSection, a polymorphic type usable with all IP address sections.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSection) ToMaxHost 

func (section *IPv6AddressSection) ToMaxHost() (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ToMaxHost converts the address section to one in which all individual address sections have a host of all one-bits, the max value, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-ones section, the max address section.

The returned address section will have the same prefix and prefix length.

This returns an error if the address section is a range of address sections which cannot be converted to a range in which all sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv6AddressSection) ToMaxHostLen 

func (section *IPv6AddressSection) ToMaxHostLen(prefixLength BitCount) (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address section to one in which all individual address sections have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this section has the same prefix length, then the resulting section will too, otherwise the resulting section will have no prefix length.

For instance, the zero host of 1.2.3.4 for the prefix length 16 is the address 1.2.255.255.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all address sections have max hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv6AddressSection) ToNormalizedString 

func (section *IPv6AddressSection) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address section.

For IPv6, it differs from the canonical string. Zero segments are not compressed.

If this section has a prefix length, it will be included in the string.

func (*IPv6AddressSection) ToNormalizedWildcardString 

func (section *IPv6AddressSection) ToNormalizedWildcardString() string

ToNormalizedWildcardString produces a string similar to the normalized string but avoids the CIDR prefix length. CIDR addresses will be shown with wildcards and ranges (denoted by '*' and '-') instead of using the CIDR prefix notation.

func (*IPv6AddressSection) ToOctalString 

func (section *IPv6AddressSection) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address section as a single octal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*IPv6AddressSection) ToPrefixBlock 

func (section *IPv6AddressSection) ToPrefixBlock() *IPv6AddressSection

ToPrefixBlock returns the section with the same prefix as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

If this section has no prefix, this section is returned.

func (*IPv6AddressSection) ToPrefixBlockLen 

func (section *IPv6AddressSection) ToPrefixBlockLen(prefLen BitCount) *IPv6AddressSection

ToPrefixBlockLen returns the section with the same prefix of the given length as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

func (*IPv6AddressSection) ToPrefixLenString 

func (section *IPv6AddressSection) ToPrefixLenString() string

ToPrefixLenString returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, a zero host section will be compressed with ::. For IPv4 the string is equivalent to the canonical string.

func (*IPv6AddressSection) ToReverseDNSString 

func (section *IPv6AddressSection) ToReverseDNSString() (string, addrerr.IncompatibleAddressError)

ToReverseDNSString generates the reverse DNS lookup string, returning an error if this address section is a multiple-valued section for which the range cannot be represented. For 2001:db8::567:89ab it is b.a.9.8.7.6.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa

func (*IPv6AddressSection) ToSQLWildcardString 

func (section *IPv6AddressSection) ToSQLWildcardString() string

ToSQLWildcardString create a string similar to that from toNormalizedWildcardString except that it uses SQL wildcards. It uses '%' instead of '*' and also uses the wildcard '_'..

func (*IPv6AddressSection) ToSectionBase 

func (section *IPv6AddressSection) ToSectionBase() *AddressSection

ToSectionBase converts to an AddressSection, a polymorphic type usable with all address sections. Afterwards, you can convert back with ToIPv6.

ToSectionBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSection) ToSegmentedBinaryString 

func (section *IPv6AddressSection) ToSegmentedBinaryString() string

ToSegmentedBinaryString writes this address section as segments of binary values preceded by the "0b" prefix.

func (*IPv6AddressSection) ToSubnetString 

func (section *IPv6AddressSection) ToSubnetString() string

ToSubnetString produces a string with specific formats for subnets. The subnet string looks like 1.2.*.* or 1:2::/16

In the case of IPv6, when a network prefix has been supplied, the prefix will be shown and the host section will be compressed with ::.

func (*IPv6AddressSection) ToZeroHost 

func (section *IPv6AddressSection) ToZeroHost() (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ToZeroHost converts the address section to one in which all individual address sections have a host of zero, the host being the bits following the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned section will have the same prefix and prefix length.

This returns an error if the section is a range of address sections which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv6AddressSection) ToZeroHostLen 

func (section *IPv6AddressSection) ToZeroHostLen(prefixLength BitCount) (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the address section to one in which all individual sections have a host of zero, the host being the bits following the given prefix length. If this address section has the same prefix length, then the returned one will too, otherwise the returned section will have no prefix length.

This returns an error if the section is a range of which cannot be converted to a range in which all sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (*IPv6AddressSection) ToZeroNetwork 

func (section *IPv6AddressSection) ToZeroNetwork() *IPv6AddressSection

ToZeroNetwork converts the address section to one in which all individual address sections have a network of zero, the network being the bits within the prefix length. If the address section has no prefix length, then it returns an all-zero address section.

The returned address section will have the same prefix length.

func (*IPv6AddressSection) UpperBytes 

func (section *IPv6AddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice

func (*IPv6AddressSection) WithoutPrefixLen 

func (section *IPv6AddressSection) WithoutPrefixLen() *IPv6AddressSection

WithoutPrefixLen provides the same address section but with no prefix length. The values remain unchanged.

func (*IPv6AddressSection) Wrap 

func (section *IPv6AddressSection) Wrap() WrappedIPAddressSection

Wrap wraps this IP address section, returning a WrappedIPAddressSection, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address section.

func (*IPv6AddressSection) WrapSection added in v1.2.0 

func (section *IPv6AddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapSection can be called with a nil receiver, wrapping a nil address section.

type IPv6AddressSegment 

type IPv6AddressSegment struct {
	// contains filtered or unexported fields
}

IPv6AddressSegment represents a segment of an IPv6 address. An IPv6 segment contains a single value or a range of sequential values, a prefix length, and it has bit length of 16 bits.

Like strings, segments are immutable, which also makes them concurrency-safe.

See AddressSegment for more details regarding segments.

func NewIPv6PrefixedSegment 

func NewIPv6PrefixedSegment(val IPv6SegInt, prefixLen PrefixLen) *IPv6AddressSegment

NewIPv6PrefixedSegment constructs a segment of an IPv6 address with the given value and assigned prefix length.

func NewIPv6RangePrefixedSegment 

func NewIPv6RangePrefixedSegment(val, upperVal IPv6SegInt, prefixLen PrefixLen) *IPv6AddressSegment

NewIPv6RangePrefixedSegment constructs a segment of an IPv6 subnet with the given range of sequential values and assigned prefix length.

func NewIPv6RangeSegment 

func NewIPv6RangeSegment(val, upperVal IPv6SegInt) *IPv6AddressSegment

NewIPv6RangeSegment constructs a segment of an IPv6 subnet with the given range of sequential values.

func NewIPv6Segment 

func NewIPv6Segment(val IPv6SegInt) *IPv6AddressSegment

NewIPv6Segment constructs a segment of an IPv6 address with the given value.

func (*IPv6AddressSegment) Bytes 

func (seg *IPv6AddressSegment) Bytes() []byte

Bytes returns the lowest value in the address segment range as a byte slice

func (*IPv6AddressSegment) Compare 

func (seg *IPv6AddressSegment) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address segment is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPv6AddressSegment) Contains 

func (seg *IPv6AddressSegment) Contains(other AddressSegmentType) bool

Contains returns whether this is same type and version as the given segment and whether it contains all values in the given segment.

func (*IPv6AddressSegment) ContainsPrefixBlock 

func (seg *IPv6AddressSegment) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the division range includes the block of values for the given prefix length

func (*IPv6AddressSegment) ContainsSinglePrefixBlock 

func (seg *IPv6AddressSegment) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the segment range matches exactly the block of values for the given prefix length and has just a single prefix for that prefix length.

func (*IPv6AddressSegment) CopyBytes 

func (seg *IPv6AddressSegment) CopyBytes(bytes []byte) []byte

CopyBytes copies the lowest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6AddressSegment) CopyUpperBytes 

func (seg *IPv6AddressSegment) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the highest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*IPv6AddressSegment) Equal 

func (seg *IPv6AddressSegment) Equal(other AddressSegmentType) bool

Equal returns whether the given segment is equal to this segment. Two segments are equal if they match:

  • type/version: IPv6
  • value range

Prefix lengths are ignored.

func (*IPv6AddressSegment) GetBitCount 

func (seg *IPv6AddressSegment) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item, which is 16

func (*IPv6AddressSegment) GetBlockMaskPrefixLen 

func (seg *IPv6AddressSegment) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address segment is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is a segment with all 1s in the network bits and then all 0s in the host bits. A CIDR host mask is a segment with all 0s in the network bits and then all 1s in the host bits. The prefix length is the bit-length of the network bits.

Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length of this segment. The prefix length returned here indicates the whether the value of this segment can be used as a mask for the network and host bits of any other segment. Therefore, the two values can be different values, or one can be nil while the other is not.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv6AddressSegment) GetByteCount 

func (seg *IPv6AddressSegment) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item, which is 2

func (*IPv6AddressSegment) GetCount 

func (seg *IPv6AddressSegment) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1.

For instance, a segment with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv6AddressSegment) GetIPv6SegmentValue 

func (seg *IPv6AddressSegment) GetIPv6SegmentValue() IPv6SegInt

GetIPv6SegmentValue returns the lower value. Same as GetSegmentValue but returned as a IPv6SegInt.

func (*IPv6AddressSegment) GetIPv6UpperSegmentValue 

func (seg *IPv6AddressSegment) GetIPv6UpperSegmentValue() IPv6SegInt

GetIPv6UpperSegmentValue returns the lower value. Same as GetUpperSegmentValue but returned as a IPv6SegInt.

func (*IPv6AddressSegment) GetLeadingBitCount 

func (seg *IPv6AddressSegment) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv6AddressSegment) GetLower 

func (seg *IPv6AddressSegment) GetLower() *IPv6AddressSegment

GetLower returns a segment representing just the lowest value in the range, which will be the same segment if it represents a single value.

func (*IPv6AddressSegment) GetMaxValue 

func (seg *IPv6AddressSegment) GetMaxValue() IPv6SegInt

GetMaxValue gets the maximum possible value for this type or version of segment, determined by the number of bits.

For the highest range value of this particular segment, use GetUpperSegmentValue.

func (*IPv6AddressSegment) GetMinPrefixLenForBlock 

func (seg *IPv6AddressSegment) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this segment includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this segment represents a single value, this returns the bit count.

func (*IPv6AddressSegment) GetPrefixCountLen 

func (seg *IPv6AddressSegment) GetPrefixCountLen(segmentPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct prefix values for the given prefix length in the range of values of this segment

func (*IPv6AddressSegment) GetPrefixLenForSingleBlock 

func (seg *IPv6AddressSegment) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this segment, and the range of values in this segment matches the block of all values for that prefix.

If the range of segment values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this segment represents a single value, this returns the bit count of the segment.

func (*IPv6AddressSegment) GetPrefixValueCount 

func (seg *IPv6AddressSegment) GetPrefixValueCount() SegIntCount

GetPrefixValueCount returns the count of prefixes in this segment for its prefix length, or the total count if it has no prefix length.

func (*IPv6AddressSegment) GetPrefixValueCountLen 

func (seg *IPv6AddressSegment) GetPrefixValueCountLen(segmentPrefixLength BitCount) SegIntCount

GetPrefixValueCountLen returns the same value as GetPrefixCountLen as an integer

func (*IPv6AddressSegment) GetSegmentPrefixLen 

func (seg *IPv6AddressSegment) GetSegmentPrefixLen() PrefixLen

GetSegmentPrefixLen returns the network prefix for the segment.

The network prefix is 16 for an address like 1.2.0.0/16.

When it comes to each address division or segment, the prefix for the division is the prefix obtained when applying the address or section prefix.

For instance, consider the address 1.2.0.0/20. The first segment has no prefix because the address prefix 20 extends beyond the 8 bits in the first segment, it does not even apply to the segment. The second segment has no prefix because the address prefix extends beyond bits 9 to 16 which lie in the second segment, it does not apply to that segment either. The third segment has the prefix 4 because the address prefix 20 corresponds to the first 4 bits in the 3rd segment, which means that the first 4 bits are part of the network section of the address or segment. The last segment has the prefix 0 because not a single bit is in the network section of the address or segment

The prefix applied across the address is nil ... nil ... (1 to segment bit length) ... 0 ... 0

If the segment has no prefix then nil is returned.

func (*IPv6AddressSegment) GetSegmentValue 

func (seg *IPv6AddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the segment value range

func (*IPv6AddressSegment) GetString 

func (seg *IPv6AddressSegment) GetString() string

GetString produces a normalized string to represent the segment. If the segment is a CIDR network prefix block for its prefix length, then the string contains only the lower value of the block range. Otherwise, the explicit range will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPv6AddressSegment) GetTrailingBitCount 

func (seg *IPv6AddressSegment) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*IPv6AddressSegment) GetUpper 

func (seg *IPv6AddressSegment) GetUpper() *IPv6AddressSegment

GetUpper returns a segment representing just the highest value in the range, which will be the same segment if it represents a single value.

func (*IPv6AddressSegment) GetUpperSegmentValue 

func (seg *IPv6AddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the segment value range

func (*IPv6AddressSegment) GetUpperValue 

func (seg *IPv6AddressSegment) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address segment range as a big integer

func (*IPv6AddressSegment) GetValue 

func (seg *IPv6AddressSegment) GetValue() *BigDivInt

GetValue returns the lowest value in the address segment range as a big integer

func (*IPv6AddressSegment) GetValueCount 

func (seg *IPv6AddressSegment) GetValueCount() SegIntCount

GetValueCount returns the same value as GetCount as an integer

func (*IPv6AddressSegment) GetWildcardString 

func (seg *IPv6AddressSegment) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters while ignoring any network prefix length. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*IPv6AddressSegment) IncludesMax 

func (seg *IPv6AddressSegment) IncludesMax() bool

IncludesMax returns whether this segment includes the max value, the value whose bits are all ones, within its range

func (*IPv6AddressSegment) IncludesZero 

func (seg *IPv6AddressSegment) IncludesZero() bool

IncludesZero returns whether this segment includes the value of zero within its range

func (*IPv6AddressSegment) IsFullRange 

func (seg *IPv6AddressSegment) IsFullRange() bool

IsFullRange returns whether the segment range includes all possible values for its bit length. 

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv6AddressSegment) IsMax 

func (seg *IPv6AddressSegment) IsMax() bool

IsMax returns whether this segment matches exactly the maximum possible value, the value whose bits are all ones

func (*IPv6AddressSegment) IsMultiple 

func (seg *IPv6AddressSegment) IsMultiple() bool

IsMultiple returns whether this segment represents multiple values

func (*IPv6AddressSegment) IsOneBit 

func (seg *IPv6AddressSegment) IsOneBit(segmentBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 is the most significant bit.

func (*IPv6AddressSegment) IsPrefixBlock 

func (seg *IPv6AddressSegment) IsPrefixBlock() bool

IsPrefixBlock returns whether the 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 (*IPv6AddressSegment) IsPrefixed 

func (seg *IPv6AddressSegment) IsPrefixed() bool

IsPrefixed returns whether this segment has an associated prefix length

func (*IPv6AddressSegment) IsSinglePrefix 

func (seg *IPv6AddressSegment) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix determines if the segment has a single prefix value for the given prefix length. You can call GetPrefixCountLen to get the count of prefixes.

func (*IPv6AddressSegment) IsSinglePrefixBlock 

func (seg *IPv6AddressSegment) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock() except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPv6AddressSegment) IsZero 

func (seg *IPv6AddressSegment) IsZero() bool

IsZero returns whether this segment matches exactly the value of zero

func (*IPv6AddressSegment) Iterator 

func (seg *IPv6AddressSegment) Iterator() IPv6SegmentIterator

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() IPv6SegmentIterator

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() IPv6SegmentIterator

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) IPv6SegmentIterator

PrefixedBlockIterator provides an iterator to iterate through the individual prefix blocks of the given prefix length in this segment, one for each prefix of this address or subnet.

It is similar to PrefixBlockIterator except that this method allows you to specify the prefix length.

func (*IPv6AddressSegment) ReverseBits 

func (seg *IPv6AddressSegment) ReverseBits(perByte bool) (res *IPv6AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBits returns a segment with the bits reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*IPv6AddressSegment) ReverseBytes 

func (seg *IPv6AddressSegment) ReverseBytes() (res *IPv6AddressSegment, err addrerr.IncompatibleAddressError)

ReverseBytes returns a segment with the bytes reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

func (*IPv6AddressSegment) String 

func (seg *IPv6AddressSegment) String() string

String produces a string that is useful when a segment is provided with no context. It uses the hexadecimal radix with the string prefix for hex (0x). GetWildcardString is more appropriate in context with other segments or divisions. It does not use a string prefix and uses '*' for full-range segments. GetString is more appropriate in context with prefix lengths, it uses zeros instead of wildcards with full prefix block ranges alongside prefix lengths.

func (*IPv6AddressSegment) TestBit 

func (seg *IPv6AddressSegment) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*IPv6AddressSegment) ToDiv 

func (seg *IPv6AddressSegment) ToDiv() *AddressDivision

ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions. Afterwards, you can convert back with ToIPv6.

ToDiv can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSegment) ToHexString 

func (seg *IPv6AddressSegment) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address segment as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

For segments, the error is always nil.

func (*IPv6AddressSegment) ToHostSegment 

func (seg *IPv6AddressSegment) ToHostSegment(segmentPrefixLength PrefixLen) *IPv6AddressSegment

ToHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will have no assigned prefix length.

func (*IPv6AddressSegment) ToIP 

func (seg *IPv6AddressSegment) ToIP() *IPAddressSegment

ToIP converts to an IPAddressSegment, a polymorphic type usable with all IP address segments. Afterwards, you can convert back with ToIPv6.

ToIP can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSegment) ToNetworkSegment 

func (seg *IPv6AddressSegment) ToNetworkSegment(segmentPrefixLength PrefixLen) *IPv6AddressSegment

ToNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will have no assigned prefix length.

func (*IPv6AddressSegment) ToNormalizedString 

func (seg *IPv6AddressSegment) ToNormalizedString() string

ToNormalizedString produces a string that is consistent for all address segments of the same type and version. IPv4 segments use base 10, while IPv6 segments use base 16.

func (*IPv6AddressSegment) ToPrefixedHostSegment 

func (seg *IPv6AddressSegment) ToPrefixedHostSegment(segmentPrefixLength PrefixLen) *IPv6AddressSegment

ToPrefixedHostSegment returns a segment with the host bits matching this segment but the network bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPv6AddressSegment) ToPrefixedNetworkSegment 

func (seg *IPv6AddressSegment) ToPrefixedNetworkSegment(segmentPrefixLength PrefixLen) *IPv6AddressSegment

ToPrefixedNetworkSegment returns a segment with the network bits matching this segment but the host bits converted to zero. The new segment will be assigned the given prefix length.

func (*IPv6AddressSegment) ToSegmentBase 

func (seg *IPv6AddressSegment) ToSegmentBase() *AddressSegment

ToSegmentBase converts to an AddressSegment, a polymorphic type usable with all address segments. Afterwards, you can convert back with ToIPv6.

ToSegmentBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6AddressSegment) UpperBytes 

func (seg *IPv6AddressSegment) UpperBytes() []byte

UpperBytes returns the highest value in the address segment range as a byte slice

func (*IPv6AddressSegment) WithoutPrefixLen 

func (seg *IPv6AddressSegment) WithoutPrefixLen() *IPv6AddressSegment

WithoutPrefixLen returns a segment with the same value range but without a prefix length.

type IPv6AddressSegmentSeries 

type IPv6AddressSegmentSeries interface {
	IPAddressSegmentSeries

	// GetTrailingSection returns an ending subsection of the full address or address section
	GetTrailingSection(index int) *IPv6AddressSection

	// GetSubSection returns a subsection of the full address or address section
	GetSubSection(index, endIndex int) *IPv6AddressSection

	// GetNetworkSection returns an address section containing the segments with the network of the series, the prefix bits.
	// The returned section will have only as many segments as needed as determined by the existing CIDR network prefix length.
	//
	// If this series has no CIDR prefix length, the returned network section will
	// be the entire series as a prefixed section with prefix length matching the address bit length.
	GetNetworkSection() *IPv6AddressSection

	// GetHostSection returns a section containing the segments with the host of the series, the bits beyond the CIDR network prefix length.
	// The returned section will have only as many segments as needed to contain the host.
	//
	// If this series has no prefix length, the returned host section will be the full section.
	GetHostSection() *IPv6AddressSection

	// GetNetworkSectionLen returns a section containing the segments with the network of the series, the prefix bits according to the given prefix length.
	// The returned section will have only as many segments as needed to contain the network.
	//
	// The new section will be assigned the given prefix length,
	// unless the existing prefix length is smaller, in which case the existing prefix length will be retained.
	GetNetworkSectionLen(BitCount) *IPv6AddressSection

	// GetHostSectionLen returns a section containing the segments with the host of the series, the bits beyond the given CIDR network prefix length.
	// The returned section will have only as many segments as needed to contain the host.
	GetHostSectionLen(BitCount) *IPv6AddressSection

	// GetSegments returns a slice with the address segments.  The returned slice is not backed by the same array as the receiver.
	GetSegments() []*IPv6AddressSegment

	// CopySegments copies the existing segments into the given slice,
	// as much as can be fit into the slice, returning the number of segments copied
	CopySegments(segs []*IPv6AddressSegment) (count int)

	// CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index,
	// into the given slice, as much as can be fit into the slice, returning the number of segments copied
	CopySubSegments(start, end int, segs []*IPv6AddressSegment) (count int)

	// GetSegment returns the segment at the given index.
	// The first segment is at index 0.
	// GetSegment will panic given a negative index or index 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 struct {
	// contains filtered or unexported fields
}

IPv6AddressSeqRange represents an arbitrary range of consecutive IPv6 addresses.

The zero value is a range from :: to ::.

See IPAddressSeqRange for more details.

func NewIPv6SeqRange 

func NewIPv6SeqRange(one, two *IPv6Address) *IPv6AddressSeqRange

func (*IPv6AddressSeqRange) Bytes 

func (rng *IPv6AddressSeqRange) Bytes() []byte

Bytes returns the lowest address in the range, the one with the lowest numeric value, as a byte slice

func (*IPv6AddressSeqRange) Compare 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) CompareSize 

func (rng *IPv6AddressSeqRange) CompareSize(other IPAddressSeqRangeType) int

CompareSize compares the counts of two address ranges, the number of individual addresses within.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one range spans more individual addresses than another.

CompareSize returns a positive integer if this address range has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.

func (*IPv6AddressSeqRange) Contains 

func (rng *IPv6AddressSeqRange) Contains(other IPAddressType) bool

Contains returns whether this range contains all addresses in the given address or subnet.

func (*IPv6AddressSeqRange) ContainsPrefixBlock 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) ContainsRange 

func (rng *IPv6AddressSeqRange) ContainsRange(other IPAddressSeqRangeType) bool

ContainsRange returns whether all the addresses in the given sequential range are also contained in this sequential range.

func (*IPv6AddressSeqRange) ContainsSinglePrefixBlock 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) CopyBytes 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) CopyNetIP 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) CopyUpperBytes 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) CopyUpperNetIP 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) CoverWithPrefixBlock 

func (rng *IPv6AddressSeqRange) CoverWithPrefixBlock() *IPv6Address

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 (*IPv6AddressSeqRange) Equal 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) Extend 

func (rng *IPv6AddressSeqRange) Extend(other *IPv6AddressSeqRange) *IPv6AddressSeqRange

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 (IPv6AddressSeqRange) Format 

func (rng IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) GetBitCount 

func (rng *IPv6AddressSeqRange) GetBitCount() BitCount

GetBitCount returns the number of bits in each address in the range, which is 16

func (*IPv6AddressSeqRange) GetByteCount 

func (rng *IPv6AddressSeqRange) GetByteCount() int

GetByteCount returns the number of bytes in each address in the range, which is 2

func (*IPv6AddressSeqRange) GetCount 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) GetLower 

func (rng *IPv6AddressSeqRange) GetLower() *IPv6Address

GetLower returns the lowest address of the sequential range, the one with the lowest numeric value

func (*IPv6AddressSeqRange) GetLowerIPAddress 

func (rng *IPv6AddressSeqRange) GetLowerIPAddress() *IPAddress

GetLowerIPAddress satisfies the IPAddressRange interface, returning the lower address in the range, same as GetLower()

func (*IPv6AddressSeqRange) GetMinPrefixLenForBlock 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) GetNetIP 

func (rng *IPv6AddressSeqRange) GetNetIP() net.IP

GetNetIP returns the lower IP address in the range as a net.IP

func (*IPv6AddressSeqRange) GetPrefixCountLen 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) GetPrefixLenForSingleBlock 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) GetUpper 

func (rng *IPv6AddressSeqRange) GetUpper() *IPv6Address

GetUpper returns the highest address of the sequential range, the one with the highest numeric value

func (*IPv6AddressSeqRange) GetUpperIPAddress 

func (rng *IPv6AddressSeqRange) GetUpperIPAddress() *IPAddress

GetUpperIPAddress satisfies the IPAddressRange interface, returning the upper address in the range, same as GetUpper()

func (*IPv6AddressSeqRange) GetUpperNetIP 

func (rng *IPv6AddressSeqRange) GetUpperNetIP() net.IP

GetUpperNetIP returns the upper IP address in the range as a net.IP

func (*IPv6AddressSeqRange) GetUpperValue 

func (rng *IPv6AddressSeqRange) GetUpperValue() *big.Int

GetUpperValue returns the highest address in the range, the one with the highest numeric value, as an integer

func (*IPv6AddressSeqRange) GetValue 

func (rng *IPv6AddressSeqRange) GetValue() *big.Int

GetValue returns the lowest address in the range, the one with the lowest numeric value, as an integer

func (*IPv6AddressSeqRange) IncludesMax 

func (rng *IPv6AddressSeqRange) IncludesMax() bool

IncludesMax returns whether this sequential range's upper value is the max value, the value whose bits are all ones.

func (*IPv6AddressSeqRange) IncludesZero 

func (rng *IPv6AddressSeqRange) IncludesZero() bool

IncludesZero returns whether this sequential range's lower value is the zero address.

func (*IPv6AddressSeqRange) Intersect 

func (rng *IPv6AddressSeqRange) Intersect(other *IPv6AddressSeqRange) *IPAddressSeqRange

Intersect returns the intersection of this range with the given range, a range which includes those addresses found in both.

func (*IPv6AddressSeqRange) IsFullRange 

func (rng *IPv6AddressSeqRange) IsFullRange() bool

IsFullRange returns whether this address range covers the entire IPv6 address space.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv6AddressSeqRange) IsMax 

func (rng *IPv6AddressSeqRange) IsMax() bool

IsMax returns whether this sequential range spans from the max address, the address whose bits are all ones, to itself.

func (*IPv6AddressSeqRange) IsMultiple 

func (rng *IPv6AddressSeqRange) IsMultiple() bool

IsMultiple returns whether this range represents a range of multiple addresses

func (*IPv6AddressSeqRange) IsSequential 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) IsZero 

func (rng *IPv6AddressSeqRange) IsZero() bool

IsZero returns whether this sequential range spans from the zero address to itself.

func (*IPv6AddressSeqRange) Iterator 

func (rng *IPv6AddressSeqRange) Iterator() IPv6AddressIterator

Iterator provides an iterator to iterate through the individual addresses of this address range.

Call GetCount for the count.

func (*IPv6AddressSeqRange) Join 

func (rng *IPv6AddressSeqRange) Join(ranges ...*IPv6AddressSeqRange) []*IPv6AddressSeqRange

Join joins the given ranges into the fewest number of ranges. The returned array will be sorted by ascending lowest range value.

func (*IPv6AddressSeqRange) JoinTo 

func (rng *IPv6AddressSeqRange) JoinTo(other *IPv6AddressSeqRange) *IPv6AddressSeqRange

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 (*IPv6AddressSeqRange) Overlaps 

func (rng *IPv6AddressSeqRange) Overlaps(other *IPv6AddressSeqRange) bool

Overlaps returns true if this sequential range overlaps with the given sequential range.

func (*IPv6AddressSeqRange) PrefixBlockIterator 

func (rng *IPv6AddressSeqRange) PrefixBlockIterator(prefLength BitCount) IPv6AddressIterator

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 (*IPv6AddressSeqRange) PrefixIterator 

func (rng *IPv6AddressSeqRange) PrefixIterator(prefLength BitCount) IPv6AddressSeqRangeIterator

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.

func (*IPv6AddressSeqRange) SpanWithPrefixBlocks 

func (rng *IPv6AddressSeqRange) SpanWithPrefixBlocks() []*IPv6Address

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of addresses as this range.

func (*IPv6AddressSeqRange) SpanWithSequentialBlocks 

func (rng *IPv6AddressSeqRange) SpanWithSequentialBlocks() []*IPv6Address

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 (*IPv6AddressSeqRange) String 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) Subtract 

func (rng *IPv6AddressSeqRange) Subtract(other *IPv6AddressSeqRange) []*IPv6AddressSeqRange

Subtract Subtracts the given range from this range, to produce either zero, one, or two address ranges that contain the addresses in this range and not in the given range. If the result has length 2, the two ranges are ordered by ascending lowest range value.

func (*IPv6AddressSeqRange) ToCanonicalString 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) ToIP 

func (rng *IPv6AddressSeqRange) ToIP() *IPAddressSeqRange

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.

func (*IPv6AddressSeqRange) ToKey added in v1.1.0 

func (rng *IPv6AddressSeqRange) ToKey() *IPv6AddressSeqRangeKey

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, IPv6AddressSeqRangeKey instances are comparable with go operators, and thus can be used as map keys.

func (*IPv6AddressSeqRange) ToNormalizedString 

func (rng *IPv6AddressSeqRange) 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 (*IPv6AddressSeqRange) ToString 

func (rng *IPv6AddressSeqRange) ToString(lowerStringer func(*IPv6Address) string, separator string, upperStringer func(*IPv6Address) string) string

func (*IPv6AddressSeqRange) UpperBytes 

func (rng *IPv6AddressSeqRange) UpperBytes() []byte

UpperBytes returns the highest address in the range, the one with the highest numeric value, as a byte slice

type IPv6AddressSeqRangeIterator 

type IPv6AddressSeqRangeIterator interface {
	HasNext

	// Next returns the next sequential address range, or nil if there is none left.
	Next() *IPv6AddressSeqRange
}

IPv6AddressSeqRangeIterator iterates through IPv6 address sequential ranges

type IPv6AddressSeqRangeKey added in v1.1.0 

type IPv6AddressSeqRangeKey struct {
	// contains filtered or unexported fields
}

IPv6AddressSeqRangeKey is a representation of IPv6AddressSeqRange that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators It can be used as a map key. The zero value is a range from :: to itself

func (*IPv6AddressSeqRangeKey) String added in v1.1.1 

func (key *IPv6AddressSeqRangeKey) String() string

String calls the String method in the corresponding sequential range

func (*IPv6AddressSeqRangeKey) ToSeqRange added in v1.1.0 

func (key *IPv6AddressSeqRangeKey) ToSeqRange() *IPv6AddressSeqRange

ToSeqRange converts to the associated sequential range

type IPv6AddressTrie added in v1.1.0 

type IPv6AddressTrie struct {
	// contains filtered or unexported fields
}

IPv6AddressTrie represents an IPv6 address binary trie.

The keys are IPv6 addresses or prefix blocks.

The zero value for IPv6AddressTrie is a binary trie ready for use.

func NewIPv6AddressTrie added in v1.1.0 

func NewIPv6AddressTrie() *IPv6AddressTrie

NewIPv6AddressTrie constructs an IPv6 address trie with the root as the ::/0 prefix block

func (*IPv6AddressTrie) Add added in v1.1.0 

func (trie *IPv6AddressTrie) Add(addr *IPv6Address) bool

Add adds the address to this trie. Returns true if the address did not already exist in the trie.

func (*IPv6AddressTrie) AddNode added in v1.1.0 

func (trie *IPv6AddressTrie) AddNode(addr *IPv6Address) *IPv6AddressTrieNode

AddNode adds the address to this trie. The new or existing node for the address is returned.

func (*IPv6AddressTrie) AddTrie added in v1.1.0 

func (trie *IPv6AddressTrie) AddTrie(added *IPv6AddressTrieNode) *IPv6AddressTrieNode

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.

func (*IPv6AddressTrie) AddedNodesTreeString added in v1.1.0 

func (trie *IPv6AddressTrie) 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 (*IPv6AddressTrie) AllNodeIterator added in v1.1.0 

func (trie *IPv6AddressTrie) AllNodeIterator(forward bool) IPv6TrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes in the trie in forward or reverse tree order.

func (*IPv6AddressTrie) BlockSizeAllNodeIterator added in v1.1.0 

func (trie *IPv6AddressTrie) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IPv6TrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*IPv6AddressTrie) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (trie *IPv6AddressTrie) BlockSizeCachingAllNodeIterator() CachingIPv6TrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

func (*IPv6AddressTrie) BlockSizeNodeIterator added in v1.1.0 

func (trie *IPv6AddressTrie) BlockSizeNodeIterator(lowerSubNodeFirst bool) IPv6TrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*IPv6AddressTrie) CeilingAddedNode added in v1.1.0 

func (trie *IPv6AddressTrie) CeilingAddedNode(addr *IPv6Address) *IPv6AddressTrieNode

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 tree

func (*IPv6AddressTrie) Clear added in v1.1.0 

func (trie *IPv6AddressTrie) Clear()

Clear removes all added nodes from the tree, after which IsEmpty() will return true

func (*IPv6AddressTrie) Clone added in v1.1.0 

func (trie *IPv6AddressTrie) Clone() *IPv6AddressTrie

Clone clones this trie

func (*IPv6AddressTrie) ConstructAddedNodesTree added in v1.1.0 

func (trie *IPv6AddressTrie) ConstructAddedNodesTree() *IPv6AddressTrie

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. 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 (*IPv6AddressTrie) ContainedFirstAllNodeIterator added in v1.1.0 

func (trie *IPv6AddressTrie) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) IPv6TrieNodeIterator

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 (*IPv6AddressTrie) ContainedFirstIterator added in v1.1.0 

func (trie *IPv6AddressTrie) ContainedFirstIterator(forwardSubNodeOrder bool) IPv6TrieNodeIteratorRem

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 (*IPv6AddressTrie) ContainingFirstAllNodeIterator added in v1.1.0 

func (trie *IPv6AddressTrie) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingIPv6TrieNodeIterator

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 and linear space (proportional to tree size).

func (*IPv6AddressTrie) ContainingFirstIterator added in v1.1.0 

func (trie *IPv6AddressTrie) ContainingFirstIterator(forwardSubNodeOrder bool) CachingIPv6TrieNodeIterator

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 and linear space (proportional to tree size).

func (*IPv6AddressTrie) Contains added in v1.1.0 

func (trie *IPv6AddressTrie) Contains(addr *IPv6Address) 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 (*IPv6AddressTrie) DescendingIterator added in v1.1.0 

func (trie *IPv6AddressTrie) DescendingIterator() IPv6AddressIterator

DescendingIterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in reverse sorted element order.

func (*IPv6AddressTrie) ElementContains added in v1.1.0 

func (trie *IPv6AddressTrie) ElementContains(addr *IPv6Address) 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 (*IPv6AddressTrie) ElementsContainedBy added in v1.1.0 

func (trie *IPv6AddressTrie) ElementsContainedBy(addr *IPv6Address) *IPv6AddressTrieNode

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 (*IPv6AddressTrie) ElementsContaining added in v1.1.0 

func (trie *IPv6AddressTrie) ElementsContaining(addr *IPv6Address) *ContainmentPath

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 (*IPv6AddressTrie) Equal added in v1.1.0 

func (trie *IPv6AddressTrie) Equal(other *IPv6AddressTrie) bool

Equal returns whether the given argument is a trie with a set of nodes with the same keys as in this trie

func (*IPv6AddressTrie) FirstAddedNode added in v1.1.0 

func (trie *IPv6AddressTrie) FirstAddedNode() *IPv6AddressTrieNode

FirstAddedNode returns the first (lowest-valued) added node in the trie, or nil if there are no added entries in this tree

func (*IPv6AddressTrie) FirstNode added in v1.1.0 

func (trie *IPv6AddressTrie) FirstNode() *IPv6AddressTrieNode

FirstNode returns the first (lowest-valued) node in the trie or nil if the trie has no nodes

func (*IPv6AddressTrie) FloorAddedNode added in v1.1.0 

func (trie *IPv6AddressTrie) FloorAddedNode(addr *IPv6Address) *IPv6AddressTrieNode

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 tree

func (IPv6AddressTrie) Format added in v1.1.0 

func (trie IPv6AddressTrie) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*IPv6AddressTrie) GetAddedNode added in v1.1.0 

func (trie *IPv6AddressTrie) GetAddedNode(addr *IPv6Address) *IPv6AddressTrieNode

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 (*IPv6AddressTrie) GetNode added in v1.1.0 

func (trie *IPv6AddressTrie) GetNode(addr *IPv6Address) *IPv6AddressTrieNode

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 (*IPv6AddressTrie) GetRoot added in v1.1.0 

func (trie *IPv6AddressTrie) GetRoot() *IPv6AddressTrieNode

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 (*IPv6AddressTrie) HigherAddedNode added in v1.1.0 

func (trie *IPv6AddressTrie) HigherAddedNode(addr *IPv6Address) *IPv6AddressTrieNode

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 tree

func (*IPv6AddressTrie) IsEmpty added in v1.1.0 

func (trie *IPv6AddressTrie) IsEmpty() bool

IsEmpty returns true if there are not any added nodes within this tree

func (*IPv6AddressTrie) Iterator added in v1.1.0 

func (trie *IPv6AddressTrie) Iterator() IPv6AddressIterator

Iterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in sorted element order.

func (*IPv6AddressTrie) LastAddedNode added in v1.1.0 

func (trie *IPv6AddressTrie) LastAddedNode() *IPv6AddressTrieNode

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 tree

func (*IPv6AddressTrie) LastNode added in v1.1.0 

func (trie *IPv6AddressTrie) LastNode() *IPv6AddressTrieNode

LastNode returns the last (highest-valued) node in the trie or nil if the trie has no nodes

func (*IPv6AddressTrie) LongestPrefixMatch added in v1.1.0 

func (trie *IPv6AddressTrie) LongestPrefixMatch(addr *IPv6Address) *IPv6Address

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 (*IPv6AddressTrie) LongestPrefixMatchNode added in v1.1.0 

func (trie *IPv6AddressTrie) LongestPrefixMatchNode(addr *IPv6Address) *IPv6AddressTrieNode

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 (*IPv6AddressTrie) LowerAddedNode added in v1.1.0 

func (trie *IPv6AddressTrie) LowerAddedNode(addr *IPv6Address) *IPv6AddressTrieNode

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 tree

func (*IPv6AddressTrie) NodeIterator added in v1.1.0 

func (trie *IPv6AddressTrie) NodeIterator(forward bool) IPv6TrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes in the trie in forward or reverse tree order.

func (*IPv6AddressTrie) NodeSize added in v1.1.0 

func (trie *IPv6AddressTrie) NodeSize() int

NodeSize returns the number of nodes in the tree, which is always more than the number of elements.

func (*IPv6AddressTrie) Remove added in v1.1.0 

func (trie *IPv6AddressTrie) Remove(addr *IPv6Address) 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.

func (*IPv6AddressTrie) RemoveElementsContainedBy added in v1.1.0 

func (trie *IPv6AddressTrie) RemoveElementsContainedBy(addr *IPv6Address) *IPv6AddressTrieNode

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 (*IPv6AddressTrie) Size added in v1.1.0 

func (trie *IPv6AddressTrie) 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 (*IPv6AddressTrie) String added in v1.1.0 

func (trie *IPv6AddressTrie) String() string

String returns a visual representation of the tree with one node per line.

func (*IPv6AddressTrie) ToAssociative added in v1.1.0 

func (trie *IPv6AddressTrie) ToAssociative() *IPv6AddressAssociativeTrie

ToAssociative converts to the associative representation of this trie

func (*IPv6AddressTrie) ToBase added in v1.1.0 

func (trie *IPv6AddressTrie) ToBase() *AddressTrie

ToBase converts to the polymorphic representation of this trie

func (*IPv6AddressTrie) TreeString added in v1.1.0 

func (trie *IPv6AddressTrie) 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 IPv6AddressTrieNode added in v1.1.0 

type IPv6AddressTrieNode struct {
	// contains filtered or unexported fields
}

IPv6AddressTrieNode represents a node in an IPv6AddressTrie.

Trie nodes are created by tries during add operations.

If a trie node is copied, a panic will result when methods that alter the trie are called on the copied node.

Iterator methods allow for traversal of the sub-trie with this node as the root.

If an iterator is advanced following a trie modification that followed the creation of the iterator, the iterator will panic.

func (*IPv6AddressTrieNode) AllNodeIterator added in v1.1.0 

func (node *IPv6AddressTrieNode) AllNodeIterator(forward bool) IPv6TrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*IPv6AddressTrieNode) AsNewTrie added in v1.1.0 

func (node *IPv6AddressTrieNode) AsNewTrie() *IPv6AddressTrie

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 (*IPv6AddressTrieNode) BlockSizeAllNodeIterator added in v1.1.0 

func (node *IPv6AddressTrieNode) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) IPv6TrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all the nodes, ordered by keys from the largest prefix blocks to the 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 (*IPv6AddressTrieNode) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (node *IPv6AddressTrieNode) BlockSizeCachingAllNodeIterator() CachingIPv6TrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest and then to individual addresses, in the sub-trie with this node as the root.

func (*IPv6AddressTrieNode) BlockSizeNodeIterator added in v1.1.0 

func (node *IPv6AddressTrieNode) BlockSizeNodeIterator(lowerSubNodeFirst bool) IPv6TrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes, ordered by keys from the largest prefix blocks to the 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 (*IPv6AddressTrieNode) CeilingAddedNode added in v1.1.0 

func (node *IPv6AddressTrieNode) CeilingAddedNode(addr *Address) *IPv6AddressTrieNode

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 (*IPv6AddressTrieNode) Clear added in v1.1.0 

func (node *IPv6AddressTrieNode) Clear()

Clear removes this node and all sub-nodes from the tree, after which isEmpty() will return true.

func (*IPv6AddressTrieNode) Clone added in v1.1.0 

func (node *IPv6AddressTrieNode) Clone() *IPv6AddressTrieNode

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 (*IPv6AddressTrieNode) CloneTree added in v1.1.0 

func (node *IPv6AddressTrieNode) CloneTree() *IPv6AddressTrieNode

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 (*IPv6AddressTrieNode) Compare added in v1.1.0 

func (node *IPv6AddressTrieNode) Compare(other *IPv6AddressTrieNode) int

Compare returns -1, 0 or 1 if this node is less than, equal, or greater than the other, according to the key and the trie order.

func (*IPv6AddressTrieNode) ContainedFirstAllNodeIterator added in v1.1.0 

func (node *IPv6AddressTrieNode) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) IPv6TrieNodeIterator

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary tree 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 (*IPv6AddressTrieNode) ContainedFirstIterator added in v1.1.0 

func (node *IPv6AddressTrieNode) ContainedFirstIterator(forwardSubNodeOrder bool) IPv6TrieNodeIteratorRem

ContainedFirstIterator returns an iterator that does a post-order binary tree 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 (*IPv6AddressTrieNode) ContainingFirstAllNodeIterator added in v1.1.0 

func (node *IPv6AddressTrieNode) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingIPv6TrieNodeIterator

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*IPv6AddressTrieNode) ContainingFirstIterator added in v1.1.0 

func (node *IPv6AddressTrieNode) ContainingFirstIterator(forwardSubNodeOrder bool) CachingIPv6TrieNodeIterator

ContainingFirstIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*IPv6AddressTrieNode) Contains added in v1.1.0 

func (node *IPv6AddressTrieNode) Contains(addr *IPv6Address) 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 exists already in the trie, false otherwise.

Use GetAddedNode to get the node for the address rather than just checking for its existence.

func (*IPv6AddressTrieNode) DescendingIterator added in v1.1.0 

func (node *IPv6AddressTrieNode) DescendingIterator() IPv6AddressIterator

DescendingIterator returns an iterator that iterates through the elements of the sub-trie with this node as the root. The iteration is in reverse sorted element order.

func (*IPv6AddressTrieNode) ElementContains added in v1.1.0 

func (node *IPv6AddressTrieNode) ElementContains(addr *IPv6Address) 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 (*IPv6AddressTrieNode) ElementsContainedBy added in v1.1.0 

func (node *IPv6AddressTrieNode) ElementsContainedBy(addr *IPv6Address) *IPv6AddressTrieNode

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 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 (*IPv6AddressTrieNode) ElementsContaining added in v1.1.0 

func (node *IPv6AddressTrieNode) ElementsContaining(addr *IPv6Address) *ContainmentPath

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 (*IPv6AddressTrieNode) Equal added in v1.1.0 

func (node *IPv6AddressTrieNode) Equal(other *IPv6AddressTrieNode) bool

Equal returns whether the key and mapped value match those of the given node

func (*IPv6AddressTrieNode) FirstAddedNode added in v1.1.0 

func (node *IPv6AddressTrieNode) FirstAddedNode() *IPv6AddressTrieNode

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 tree or sub-trie

func (*IPv6AddressTrieNode) FirstNode added in v1.1.0 

func (node *IPv6AddressTrieNode) FirstNode() *IPv6AddressTrieNode

FirstNode returns the first (the lowest valued) node in the sub-trie originating from this node

func (*IPv6AddressTrieNode) FloorAddedNode added in v1.1.0 

func (node *IPv6AddressTrieNode) FloorAddedNode(addr *Address) *IPv6AddressTrieNode

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 (IPv6AddressTrieNode) Format added in v1.1.0 

func (node IPv6AddressTrieNode) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*IPv6AddressTrieNode) GetAddedNode added in v1.1.0 

func (node *IPv6AddressTrieNode) GetAddedNode(addr *IPv6Address) *IPv6AddressTrieNode

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 (*IPv6AddressTrieNode) GetKey added in v1.1.0 

func (node *IPv6AddressTrieNode) GetKey() *IPv6Address

GetKey gets the key used for placing the node in the tree.

func (*IPv6AddressTrieNode) GetLowerSubNode added in v1.1.0 

func (node *IPv6AddressTrieNode) GetLowerSubNode() *IPv6AddressTrieNode

GetLowerSubNode gets the direct child node whose key is smallest in value

func (*IPv6AddressTrieNode) GetNode added in v1.1.0 

func (node *IPv6AddressTrieNode) GetNode(addr *IPv6Address) *IPv6AddressTrieNode

GetNode gets the node in the trie, with this sub-node 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 (*IPv6AddressTrieNode) GetParent added in v1.1.0 

func (node *IPv6AddressTrieNode) GetParent() *IPv6AddressTrieNode

GetParent gets the node from which this node is a direct child node, or nil if this is the root.

func (*IPv6AddressTrieNode) GetUpperSubNode added in v1.1.0 

func (node *IPv6AddressTrieNode) GetUpperSubNode() *IPv6AddressTrieNode

GetUpperSubNode gets the direct child node whose key is largest in value

func (*IPv6AddressTrieNode) HigherAddedNode added in v1.1.0 

func (node *IPv6AddressTrieNode) HigherAddedNode(addr *Address) *IPv6AddressTrieNode

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 (*IPv6AddressTrieNode) IsAdded added in v1.1.0 

func (node *IPv6AddressTrieNode) IsAdded() bool

IsAdded returns whether the node was "added". Some binary tree nodes are considered "added" and others are not. Those nodes created for key elements added to the tree 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 tree. 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 (*IPv6AddressTrieNode) IsEmpty added in v1.1.0 

func (node *IPv6AddressTrieNode) IsEmpty() bool

IsEmpty returns whether the size is 0

func (*IPv6AddressTrieNode) IsLeaf added in v1.1.0 

func (node *IPv6AddressTrieNode) 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-trie with this node as the root.

func (*IPv6AddressTrieNode) IsRoot added in v1.1.0 

func (node *IPv6AddressTrieNode) IsRoot() bool

IsRoot returns whether this is the root of the backing tree.

func (*IPv6AddressTrieNode) Iterator added in v1.1.0 

func (node *IPv6AddressTrieNode) Iterator() IPv6AddressIterator

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 (*IPv6AddressTrieNode) LastAddedNode added in v1.1.0 

func (node *IPv6AddressTrieNode) LastAddedNode() *IPv6AddressTrieNode

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 tree or sub-trie

func (*IPv6AddressTrieNode) LastNode added in v1.1.0 

func (node *IPv6AddressTrieNode) LastNode() *IPv6AddressTrieNode

LastNode returns the last (the highest valued) node in the sub-trie originating from this node

func (*IPv6AddressTrieNode) LongestPrefixMatch added in v1.1.0 

func (node *IPv6AddressTrieNode) LongestPrefixMatch(addr *IPv6Address) *Address

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 (*IPv6AddressTrieNode) LongestPrefixMatchNode added in v1.1.0 

func (node *IPv6AddressTrieNode) LongestPrefixMatchNode(addr *IPv6Address) *IPv6AddressTrieNode

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 (*IPv6AddressTrieNode) LowerAddedNode added in v1.1.0 

func (node *IPv6AddressTrieNode) LowerAddedNode(addr *Address) *IPv6AddressTrieNode

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 (*IPv6AddressTrieNode) NextAddedNode added in v1.1.0 

func (node *IPv6AddressTrieNode) NextAddedNode() *IPv6AddressTrieNode

NextAddedNode returns the first added node that follows this node following the tree order

func (*IPv6AddressTrieNode) NextNode added in v1.1.0 

func (node *IPv6AddressTrieNode) NextNode() *IPv6AddressTrieNode

NextNode returns the node that follows this node following the tree order

func (*IPv6AddressTrieNode) NodeIterator added in v1.1.0 

func (node *IPv6AddressTrieNode) NodeIterator(forward bool) IPv6TrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*IPv6AddressTrieNode) NodeSize added in v1.1.0 

func (node *IPv6AddressTrieNode) 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 (*IPv6AddressTrieNode) PreviousAddedNode added in v1.1.0 

func (node *IPv6AddressTrieNode) PreviousAddedNode() *IPv6AddressTrieNode

PreviousAddedNode returns the first added node that precedes this node following the tree order

func (*IPv6AddressTrieNode) PreviousNode added in v1.1.0 

func (node *IPv6AddressTrieNode) PreviousNode() *IPv6AddressTrieNode

PreviousNode returns the node that precedes this node following the tree order

func (*IPv6AddressTrieNode) Remove added in v1.1.0 

func (node *IPv6AddressTrieNode) 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 (*IPv6AddressTrieNode) RemoveElementsContainedBy added in v1.1.0 

func (node *IPv6AddressTrieNode) RemoveElementsContainedBy(addr *IPv6Address) *IPv6AddressTrieNode

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 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 (*IPv6AddressTrieNode) RemoveNode added in v1.1.0 

func (node *IPv6AddressTrieNode) RemoveNode(addr *IPv6Address) 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.

func (*IPv6AddressTrieNode) SetAdded added in v1.1.0 

func (node *IPv6AddressTrieNode) SetAdded()

SetAdded makes this node an added node, which is equivalent to adding the corresponding key to the tree. 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 tree by calling Remove. A non-added node will only remain in the tree if it needs to in the tree.

func (*IPv6AddressTrieNode) Size added in v1.1.0 

func (node *IPv6AddressTrieNode) Size() int

Size returns the number of elements in the tree. Only nodes for which IsAdded returns true are counted. When zero is returned, IsEmpty returns true.

func (*IPv6AddressTrieNode) String added in v1.1.0 

func (node *IPv6AddressTrieNode) 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 (*IPv6AddressTrieNode) ToAssociative added in v1.1.0 

func (node *IPv6AddressTrieNode) ToAssociative() *IPv6AddressAssociativeTrieNode

ToAssociative converts to the associative trie node representation of this IPv6 trie node. The node is unchanged, the returned node is the same underlying node.

func (*IPv6AddressTrieNode) ToBase added in v1.1.0 

func (node *IPv6AddressTrieNode) ToBase() *AddressTrieNode

ToBase converts to the polymorphic base representation of this IPv6 trie node. The node is unchanged, the returned node is the same underlying node.

func (*IPv6AddressTrieNode) TreeEqual added in v1.1.0 

func (node *IPv6AddressTrieNode) TreeEqual(other *IPv6AddressTrieNode) bool

TreeEqual returns whether the sub-trie represented by this node as the root node matches the given sub-trie

func (*IPv6AddressTrieNode) TreeString added in v1.1.0 

func (node *IPv6AddressTrieNode) 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 IPv6AssociativeTrieNodeIterator added in v1.1.0 

type IPv6AssociativeTrieNodeIterator interface {
	HasNext

	Next() *IPv6AddressAssociativeTrieNode
}

IPv6AssociativeTrieNodeIterator iterates through an IPv6 associative address trie, until both Next returns nil and HasNext returns false

type IPv6AssociativeTrieNodeIteratorRem added in v1.1.0 

type IPv6AssociativeTrieNodeIteratorRem interface {
	IPv6AssociativeTrieNodeIterator

	// Remove removes the last iterated element from the underlying trie, and returns that element.
	// If there is no such element, it returns nil.
	Remove() *IPv6AddressAssociativeTrieNode
}

IPv6AssociativeTrieNodeIteratorRem iterates through an IPv6 associative address trie, until both Next returns nil and HasNext returns false. The iterator also allows you to remove the last visited node.

type IPv6Partition 

type IPv6Partition struct {
	// contains filtered or unexported fields
}

IPv6Partition is a Partition of an IPv6 address

func PartitionIPv6WithSingleBlockSize 

func PartitionIPv6WithSingleBlockSize(newAddr *IPv6Address) IPv6Partition

PartitionIPv6WithSingleBlockSize 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 PartitionIpv6WithSpanningBlocks 

func PartitionIpv6WithSpanningBlocks(newAddr *IPv6Address) IPv6Partition

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 (IPv6Partition) ForEach 

func (p IPv6Partition) ForEach(action func(*IPv6Address))

ForEach calls the action with each partition element

func (IPv6Partition) Iterator 

func (p IPv6Partition) Iterator() IPv6AddressIterator

Iterator provides an iterator to iterate through each element of the partition.

func (IPv6Partition) PredicateForAny 

func (p IPv6Partition) PredicateForAny(predicate func(*IPv6Address) bool) bool

PredicateForAny applies the operation to each element of the partition, returning true if the given predicate returns true for any of the elements.

func (IPv6Partition) PredicateForAnyEarly 

func (p IPv6Partition) PredicateForAnyEarly(predicate func(*IPv6Address) bool) bool

PredicateForAnyEarly applies the 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 (IPv6Partition) PredicateForEach 

func (p IPv6Partition) PredicateForEach(predicate func(*IPv6Address) bool) bool

PredicateForEach applies the operation to each element of the partition, returning true if they all return true, false otherwise

func (IPv6Partition) PredicateForEachEarly 

func (p IPv6Partition) PredicateForEachEarly(predicate func(*IPv6Address) bool) bool

PredicateForEachEarly applies the 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 IPv6SectionIterator 

type IPv6SectionIterator interface {
	HasNext

	// Next returns the next address section, or nil if there is none left.
	Next() *IPv6AddressSection
}

IPv6SectionIterator iterates through IPv6 address sections

type IPv6SegInt 

type IPv6SegInt = uint16

type IPv6SegmentIterator 

type IPv6SegmentIterator interface {
	HasNext

	// Next returns the next IPv6 address segment, or nil if there is none left.
	Next() *IPv6AddressSegment
}

IPv6SegmentIterator iterates through IPv6 address segments

type IPv6SegmentValueProvider 

type IPv6SegmentValueProvider func(segmentIndex int) IPv6SegInt

func WrappedSegmentValueProviderForIPv6 

func WrappedSegmentValueProviderForIPv6(f SegmentValueProvider) IPv6SegmentValueProvider

WrappedSegmentValueProviderForIPv6 converts the given SegmentValueProvider to an IPv6SegmentValueProvider Values that do not fit IPv6SegInt are truncated.

type IPv6TrieNodeIterator added in v1.1.0 

type IPv6TrieNodeIterator interface {
	HasNext

	Next() *IPv6AddressTrieNode
}

IPv6TrieNodeIterator iterates through an IPv6 address trie, until both Next returns nil and HasNext returns false

type IPv6TrieNodeIteratorRem added in v1.1.0 

type IPv6TrieNodeIteratorRem interface {
	IPv6TrieNodeIterator

	// Remove removes the last iterated element from the underlying trie, and returns that element.
	// If there is no such element, it returns nil.
	Remove() *IPv6AddressTrieNode
}

IPv6TrieNodeIteratorRem iterates through an IPv6 address trie, until both Next returns nil and HasNext returns false. The iterator also allows you to remove the last visited node.

type IPv6v4MixedAddressGrouping 

type IPv6v4MixedAddressGrouping struct {
	// contains filtered or unexported fields
}

IPv6v4MixedAddressGrouping has divisions which are a mix of IPv6 and IPv4 divisions. It has an initial IPv6 section followed by an IPv4 section.

func (*IPv6v4MixedAddressGrouping) Bytes 

func (grouping *IPv6v4MixedAddressGrouping) Bytes() []byte

Bytes returns the lowest individual division grouping in this grouping as a byte slice

func (*IPv6v4MixedAddressGrouping) Compare 

func (grouping *IPv6v4MixedAddressGrouping) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address division grouping is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*IPv6v4MixedAddressGrouping) CompareSize 

func (grouping *IPv6v4MixedAddressGrouping) CompareSize(other StandardDivGroupingType) int

CompareSize compares the counts of two address division groupings, the number of individual groupings represented.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one grouping represents more individual address groupings than another.

CompareSize returns a positive integer if this address division grouping has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.

func (*IPv6v4MixedAddressGrouping) ContainsPrefixBlock 

func (grouping *IPv6v4MixedAddressGrouping) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock() to determine the smallest prefix length for which this method returns true.

func (*IPv6v4MixedAddressGrouping) ContainsSinglePrefixBlock 

func (grouping *IPv6v4MixedAddressGrouping) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this grouping contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*IPv6v4MixedAddressGrouping) CopyBytes 

func (grouping *IPv6v4MixedAddressGrouping) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest division grouping in the range into a byte slice

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

You can use GetByteCount to determine the required array length for the bytes.

func (*IPv6v4MixedAddressGrouping) CopyUpperBytes 

func (grouping *IPv6v4MixedAddressGrouping) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest division grouping in the range into a byte slice

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

You can use GetByteCount to determine the required array length for the bytes.

func (IPv6v4MixedAddressGrouping) Format 

func (grouping IPv6v4MixedAddressGrouping) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats 'v' for the default address and section format (either the normalized or canonical string), 's' (string) for the same 'q' for a quoted string

func (IPv6v4MixedAddressGrouping) GetBitCount 

func (grouping IPv6v4MixedAddressGrouping) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item

func (*IPv6v4MixedAddressGrouping) GetBlockCount 

func (grouping *IPv6v4MixedAddressGrouping) GetBlockCount(divisionCount int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) divisions.

func (IPv6v4MixedAddressGrouping) GetByteCount 

func (grouping IPv6v4MixedAddressGrouping) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item, rounding up if the bit count is not a multiple of 8.

func (*IPv6v4MixedAddressGrouping) GetCount 

func (grouping *IPv6v4MixedAddressGrouping) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*IPv6v4MixedAddressGrouping) GetDivisionCount 

func (grouping *IPv6v4MixedAddressGrouping) GetDivisionCount() int

GetDivisionCount returns the number of divisions in this grouping

func (*IPv6v4MixedAddressGrouping) GetGenericDivision 

func (grouping *IPv6v4MixedAddressGrouping) GetGenericDivision(index int) DivisionType

GetGenericDivision returns the division at the given index as a DivisionType implementation

func (*IPv6v4MixedAddressGrouping) GetIPv4AddressSection 

func (grouping *IPv6v4MixedAddressGrouping) GetIPv4AddressSection() *IPv4AddressSection

GetIPv4AddressSection returns the ending IPv4 section of the grouping.

func (*IPv6v4MixedAddressGrouping) GetIPv6AddressSection 

func (grouping *IPv6v4MixedAddressGrouping) GetIPv6AddressSection() *EmbeddedIPv6AddressSection

GetIPv6AddressSection returns the initial IPv6 section of the grouping.

func (*IPv6v4MixedAddressGrouping) GetMinPrefixLenForBlock 

func (grouping *IPv6v4MixedAddressGrouping) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this grouping includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this grouping represents a single value, this returns the bit count.

func (*IPv6v4MixedAddressGrouping) GetPrefixCount 

func (grouping *IPv6v4MixedAddressGrouping) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetCount

func (*IPv6v4MixedAddressGrouping) GetPrefixCountLen 

func (grouping *IPv6v4MixedAddressGrouping) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length

func (*IPv6v4MixedAddressGrouping) GetPrefixLen 

func (grouping *IPv6v4MixedAddressGrouping) 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 (*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 grouping was originally created as an implicitly zero-valued grouping (eg IPv6v4MixedAddressGrouping{}), 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, etc

func (*IPv6v4MixedAddressGrouping) IsFullRange 

func (grouping *IPv6v4MixedAddressGrouping) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (*IPv6v4MixedAddressGrouping) IsMax 

func (grouping *IPv6v4MixedAddressGrouping) IsMax() bool

IsMax returns whether this grouping matches exactly the maximum possible value, the value whose bits are all ones

func (*IPv6v4MixedAddressGrouping) IsMultiple 

func (grouping *IPv6v4MixedAddressGrouping) IsMultiple() bool

IsMultiple returns whether this grouping represents multiple values

func (*IPv6v4MixedAddressGrouping) IsPrefixBlock 

func (grouping *IPv6v4MixedAddressGrouping) IsPrefixBlock() bool

IsPrefixBlock returns whether this address 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 prefix lengths for which ContainsPrefixBlock returns true.

func (*IPv6v4MixedAddressGrouping) IsPrefixed 

func (grouping *IPv6v4MixedAddressGrouping) IsPrefixed() bool

IsPrefixed returns whether this grouping has an associated prefix length

func (*IPv6v4MixedAddressGrouping) IsSequential 

func (grouping *IPv6v4MixedAddressGrouping) IsSequential() bool

IsSequential returns whether the grouping represents a range of values that are sequential.

Generally, this means that any division covering a range of values must be followed by divisions that are full range, covering all values.

func (*IPv6v4MixedAddressGrouping) IsSinglePrefixBlock 

func (grouping *IPv6v4MixedAddressGrouping) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range of values matches a single subnet block for the prefix length.

What distinguishes this method with ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (*IPv6v4MixedAddressGrouping) IsZero 

func (grouping *IPv6v4MixedAddressGrouping) IsZero() bool

IsZero returns whether this grouping matches exactly the value of zero

func (*IPv6v4MixedAddressGrouping) String 

func (grouping *IPv6v4MixedAddressGrouping) String() string

String implements the fmt.Stringer interface, as a slice string with each division converted to a string by String ( ie "[ div0 div1 ...]"), or "<nil>" if the receiver is a nil pointer

func (*IPv6v4MixedAddressGrouping) ToDivGrouping 

func (grouping *IPv6v4MixedAddressGrouping) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToMixedIPv6v4.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*IPv6v4MixedAddressGrouping) UpperBytes 

func (grouping *IPv6v4MixedAddressGrouping) UpperBytes() []byte

UpperBytes returns the highest individual division grouping in this grouping as a byte slice

type IdentifierStr 

type IdentifierStr struct {
	// contains filtered or unexported fields
}

IdentifierStr is a string representation of an address or host name.

type Inet_aton_radix 

type Inet_aton_radix int

Inet_aton_radix represents a radix for printing an address string 

const (
	Inet_aton_radix_octal   Inet_aton_radix = 8
	Inet_aton_radix_hex     Inet_aton_radix = 16
	Inet_aton_radix_decimal Inet_aton_radix = 10
)

func (Inet_aton_radix) GetRadix 

func (rad Inet_aton_radix) GetRadix() int

GetRadix converts the radix to an int

func (Inet_aton_radix) GetSegmentStrPrefix 

func (rad Inet_aton_radix) GetSegmentStrPrefix() string

GetSegmentStrPrefix returns the string prefix used to identify the radix

func (Inet_aton_radix) String 

func (rad Inet_aton_radix) String() string

String returns the name of the radix

type MACAddress 

type MACAddress struct {
	// contains filtered or unexported fields
}

MACAddress represents a MAC address, or a collection of multiple individual MAC addresses. Each segment can represent a single byte value or a range of byte values.

You can construct a MAC address from a byte slice, from a uint64, from a SegmentValueProvider, from a MACAddressSection of 6 or 8 segments, or from an array of 6 or 8 MACAddressSegment instances.

To construct one from a string use ToAddress or GetAddress of MACAddressString.

func NewMACAddress 

func NewMACAddress(section *MACAddressSection) (*MACAddress, addrerr.AddressValueError)

NewMACAddress constructs a MAC address or address collection from the given segments.

func NewMACAddressFromBytes 

func NewMACAddressFromBytes(bytes net.HardwareAddr) (*MACAddress, addrerr.AddressValueError)

NewMACAddressFromBytes constructs a MAC address from the given byte slice. An error is returned when the byte slice has too many bytes to match the maximum MAC segment count of 8. There should be 8 bytes or less, although extra leading zeros are tolerated.

func NewMACAddressFromRange 

func NewMACAddressFromRange(vals, upperVals MACSegmentValueProvider) (addr *MACAddress)

NewMACAddressFromRange constructs a 6-byte MAC address collection from the given values.

func NewMACAddressFromRangeExt 

func NewMACAddressFromRangeExt(vals, upperVals MACSegmentValueProvider, isExtended bool) (addr *MACAddress)

NewMACAddressFromRangeExt constructs a 6 or 8-byte MAC address collection from the given values. If isExtended is true, it will be 8 bytes.

func NewMACAddressFromSegs added in v1.2.0 

func NewMACAddressFromSegs(segments []*MACAddressSegment) (*MACAddress, addrerr.AddressValueError)

NewMACAddressFromSegs constructs a MAC address or address collection from the given segments. If the given slice does not have either 6 or 8 segments, an error is returned.

func NewMACAddressFromUint64Ext 

func NewMACAddressFromUint64Ext(val uint64, isExtended bool) *MACAddress

NewMACAddressFromUint64Ext constructs a 6 or 8-byte MAC address from the given value. If isExtended is true, it is an 8-byte address, 6 otherwise. If 6 bytes, then the bytes are taken from the lower 48 bits of the uint64.

func NewMACAddressFromVals 

func NewMACAddressFromVals(vals MACSegmentValueProvider) (addr *MACAddress)

NewMACAddressFromVals constructs a 6-byte MAC address from the given values.

func NewMACAddressFromValsExt 

func NewMACAddressFromValsExt(vals MACSegmentValueProvider, isExtended bool) (addr *MACAddress)

NewMACAddressFromValsExt constructs a 6 or 8-byte MAC address from the given values. If isExtended is true, it will be 8 bytes.

func (*MACAddress) AdjustPrefixLen 

func (addr *MACAddress) AdjustPrefixLen(prefixLen BitCount) *MACAddress

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*MACAddress) AdjustPrefixLenZeroed 

func (addr *MACAddress) AdjustPrefixLenZeroed(prefixLen BitCount) (*MACAddress, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address.

If this address has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*MACAddress) AssignMinPrefixForBlock 

func (addr *MACAddress) AssignMinPrefixForBlock() *MACAddress

AssignMinPrefixForBlock returns an equivalent subnet, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this subnet.

In other words, this method assigns a prefix length to this subnet matching the largest prefix block in this subnet.

func (*MACAddress) AssignPrefixForSingleBlock 

func (addr *MACAddress) AssignPrefixForSingleBlock() *MACAddress

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address - it is required that the range of values match the range of a prefix block. If there is no such address, then nil is returned.

func (*MACAddress) BlockIterator 

func (addr *MACAddress) BlockIterator(segmentCount int) MACAddressIterator

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 AddressType) int

CompareSize compares the counts of two addresses or address collections, the number of individual addresses within.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing 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, 0 if they are the same, or a negative integer if the other has a larger count.

func (*MACAddress) Contains 

func (addr *MACAddress) Contains(other AddressType) bool

Contains returns whether this is the same type and version as the given address or subnet and whether it contains all addresses in the given address or subnet.

func (*MACAddress) ContainsPrefixBlock 

func (addr *MACAddress) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or address collection contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*MACAddress) ContainsSinglePrefixBlock 

func (addr *MACAddress) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*MACAddress) CopyBytes 

func (addr *MACAddress) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address in the address collection into a byte slice

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddress) CopyHardwareAddr 

func (addr *MACAddress) CopyHardwareAddr(bytes net.HardwareAddr) net.HardwareAddr

CopyHardwareAddr copies the value of the lowest individual address in the address collection into a net.HardwareAddr

If the value can fit in the given net.HardwareAddr, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new net.HardwareAddr is created and returned with the value.

func (*MACAddress) CopySegments 

func (addr *MACAddress) CopySegments(segs []*MACAddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*MACAddress) CopySubSegments 

func (addr *MACAddress) CopySubSegments(start, end int, segs []*MACAddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*MACAddress) CopyUpperBytes 

func (addr *MACAddress) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address in the address collection into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddress) CopyUpperHardwareAddr 

func (addr *MACAddress) CopyUpperHardwareAddr(bytes net.HardwareAddr) net.HardwareAddr

CopyUpperHardwareAddr copies the value of the highest individual address in the address collection into a net.HardwareAddr

If the value can fit in the given net.HardwareAddr, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new net.HardwareAddr is created and returned with the value.

func (*MACAddress) Equal 

func (addr *MACAddress) Equal(other AddressType) bool

Equal returns whether the given address or address collection is equal to this address or address collection. Two address instances are equal if they represent the same set of addresses.

func (*MACAddress) ForEachSegment added in v1.2.0 

func (addr *MACAddress) ForEachSegment(consumer func(segmentIndex int, segment *MACAddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true Returns the number of visited segments.

func (MACAddress) Format 

func (addr MACAddress) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats 'v' for the default address and section format (either the normalized or canonical string), 's' (string) for the same, 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix), 'd' (decimal), 'x' (lowercase hexadecimal), and 'X' (uppercase hexadecimal). Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which is leading zero for octal and for hexadecimal, a leading "0x" or "0X" for "%#x" and "%#X" respectively, Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*MACAddress) GetBitCount 

func (addr *MACAddress) GetBitCount() BitCount

GetBitCount returns the number of bits comprising this address, or each address in the range.

func (*MACAddress) GetBitsPerSegment 

func (addr *MACAddress) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this address. Segments in the same address are equal length.

func (*MACAddress) GetBlockCount 

func (addr *MACAddress) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*MACAddress) GetByteCount 

func (addr *MACAddress) GetByteCount() int

GetByteCount returns the number of bytes required for this address, or each address in the range.

func (*MACAddress) GetBytesPerSegment 

func (addr *MACAddress) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this address. Segments in the same address are equal length.

func (*MACAddress) GetCount 

func (addr *MACAddress) GetCount() *big.Int

GetCount returns the count of addresses that this address or address collection represents.

If just a single address, not a collection of multiple addresses, returns 1.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*MACAddress) GetDivisionCount 

func (addr *MACAddress) GetDivisionCount() int

GetDivisionCount returns the segment count, implementing the interface AddressDivisionSeries

func (*MACAddress) GetDottedAddress 

func (addr *MACAddress) GetDottedAddress() (*AddressDivisionGrouping, addrerr.IncompatibleAddressError)

GetDottedAddress returns an AddressDivisionGrouping which organizes the address into segments of bit-length 16, rather than the more typical 8 bits per segment.

If this represents a collection of MAC addresses, this returns an error when unable to join two address segments, the first with a range of values, into a division of the larger bit-length that represents the same set of values.

func (*MACAddress) GetGenericDivision 

func (addr *MACAddress) GetGenericDivision(index int) DivisionType

GetGenericDivision returns the segment at the given index as a DivisionType

func (*MACAddress) GetGenericSegment 

func (addr *MACAddress) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment at the given index as an AddressSegmentType

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() *Address

GetLower returns the address in the collection with the lowest numeric value, which will be the receiver if it represents a single address. For example, for "1:1:1:2-3:4:5-6", the series "1:1:1:2:4:5" is returned.

func (*MACAddress) GetMaxSegmentValue 

func (addr *MACAddress) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*MACAddress) GetMinPrefixLenForBlock 

func (addr *MACAddress) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

func (*MACAddress) GetODISection 

func (addr *MACAddress) GetODISection() *MACAddressSection

GetODISection returns a section with the segments following the first 3 segments, the organizational distinct identifier

func (*MACAddress) GetOUISection 

func (addr *MACAddress) GetOUISection() *MACAddressSection

GetOUISection returns a section with the first 3 segments, the organizational unique identifier

func (*MACAddress) GetPrefixCount 

func (addr *MACAddress) GetPrefixCount() *big.Int

GetPrefixCount returns the count of prefixes in this address or subnet.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the count of the range of values in the prefix.

If this has a nil prefix length, returns the same value as GetCount()

func (*MACAddress) GetPrefixCountLen 

func (addr *MACAddress) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the count of prefixes in this address or subnet for the given prefix length.

If not a subnet of multiple addresses, or a subnet with just single prefix of the given length, returns 1.

func (*MACAddress) GetPrefixLen 

func (addr *MACAddress) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part (most significant bits) of the address that comprise the prefix.

A prefix is a part of the address that is not specific to that address but common amongst a group of addresses, such as a CIDR prefix block subnet.

For IP addresses, the prefix is explicitly defined when the address is created. For example, 1.2.0.0/16 has a prefix length of 16, while 1.2.*.* has no prefix length, even though they both represent the same set of addresses and are considered equal. Prefixes can be considered variable for a given IP address and can depend on routing.

The methods GetMinPrefixLenForBlock and GetPrefixLenForSingleBlock can help you to obtain or define a prefix length if one does not exist already. The method ToPrefixBlockLen allows you to create the subnet consisting of the block of addresses for any given prefix length.

For MAC addresses, the prefix is initially inferred from the range, so 1:2:3:*:*:* has a prefix length of 24. Addresses derived from the original may retain the original prefix length regardless of their range.

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 index 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() *Address

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 < 0, 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 prefix lengths for which ContainsPrefixBlock returns true.

func (*MACAddress) IsPrefixed 

func (addr *MACAddress) IsPrefixed() bool

IsPrefixed returns whether this address has an associated prefix length

func (*MACAddress) IsSequential 

func (addr *MACAddress) IsSequential() bool

IsSequential returns whether the address or subnet represents a range of addresses that are sequential.

Generally, for a subnet this means that any segment covering a range of values must be followed by segments that are full range, covering all values.

Individual addresses are sequential and CIDR prefix blocks are sequential. The subnet 1.2.3-4.5 is not sequential, since the two addresses it represents, 1.2.3.5 and 1.2.4.5, are not (1.2.3.6 is in-between the two but not in the subnet).

With any IP address subnet, you can use SequentialBlockIterator to convert any subnet to a collection of sequential subnets.

func (*MACAddress) IsSinglePrefixBlock 

func (addr *MACAddress) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the address range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock() except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

For instance, 1.*.*.* /16 return false for this method and returns true for 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() MACAddressIterator

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() MACAddressIterator

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() MACAddressIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this subnet, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this subnet.

If the subnet has no prefix length, then this is equivalent to Iterator.

func (*MACAddress) Replace 

func (addr *MACAddress) Replace(startIndex int, replacement *MACAddressSection) *MACAddress

Replace replaces segments starting from startIndex with segments from the replacement section

func (*MACAddress) ReplaceLen 

func (addr *MACAddress) ReplaceLen(startIndex, endIndex int, replacement *MACAddress, replacementIndex int) *MACAddress

ReplaceLen replaces segments starting from startIndex and ending before endIndex with the same number of segments starting at replacementStartIndex from the replacement section Mappings to or from indices outside the range of this or the replacement address are skipped.

func (*MACAddress) ReverseBits 

func (addr *MACAddress) ReverseBits(perByte bool) (*MACAddress, addrerr.IncompatibleAddressError)

ReverseBits returns a new address with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a segment range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*MACAddress) ReverseBytes 

func (addr *MACAddress) ReverseBytes() *MACAddress

ReverseBytes returns a new address with the bytes reversed. Any prefix length is dropped.

func (*MACAddress) ReverseSegments 

func (addr *MACAddress) ReverseSegments() *MACAddress

ReverseSegments returns a new address with the segments reversed.

func (*MACAddress) SequentialBlockIterator 

func (addr *MACAddress) SequentialBlockIterator() MACAddressIterator

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, 2.4.6.7-8.

Use GetSequentialBlockCount to get the number of iterated elements.

func (*MACAddress) SetPrefixLen 

func (addr *MACAddress) SetPrefixLen(prefixLen BitCount) *MACAddress

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address. The provided prefix length will be adjusted to these boundaries if necessary.

func (*MACAddress) SetPrefixLenZeroed 

func (addr *MACAddress) SetPrefixLenZeroed(prefixLen BitCount) (*MACAddress, addrerr.IncompatibleAddressError)

func (*MACAddress) String 

func (addr *MACAddress) String() string

String implements the fmt.Stringer interface, returning the canonical string provided by ToCanonicalString, or "<nil>" if the receiver is a nil pointer

func (*MACAddress) TestBit 

func (addr *MACAddress) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this address at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this address. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*MACAddress) ToAddressBase 

func (addr *MACAddress) ToAddressBase() *Address

ToAddressBase converts to an Address, a polymorphic type usable with all addresses and subnets. Afterwards, you can convert back with ToMAC.

ToAddressBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*MACAddress) ToAddressString 

func (addr *MACAddress) ToAddressString() *MACAddressString

ToAddressString retrieves or generates a MACAddressString instance for this MACAddress instance. This may be the MACAddressString this instance was generated from, if it was generated from a MACAddressString.

In general, users are intended to create MACAddress instances from MACAddressString instances, while the reverse direction is generally not common and not useful, except under specific circumstances.

However, the reverse direction can be useful under certain circumstances, such as when maintaining a collection of MACAddressString instances.

func (*MACAddress) ToBinaryString 

func (addr *MACAddress) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address as a single binary value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If an address collection cannot be written as a range of two values, an error is returned.

func (*MACAddress) ToBlock 

func (addr *MACAddress) ToBlock(segmentIndex int, lower, upper SegInt) *MACAddress

ToBlock creates a new block of addresses by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*MACAddress) ToCanonicalString 

func (addr *MACAddress) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address.

For MAC, it uses the canonical standardized IEEE 802 MAC address representation of xx-xx-xx-xx-xx-xx. An example is "01-23-45-67-89-ab". For range segments, '|' is used: 11-22-33|44-55-66

Each MAC address has a unique canonical string.

func (*MACAddress) ToColonDelimitedString 

func (addr *MACAddress) ToColonDelimitedString() string

ToColonDelimitedString produces a string delimited by colons: aa:bb:cc:dd:ee:ff For range segments, '-' is used: 11:22:33-44:55:66 It returns the same string as ToNormalizedString.

func (*MACAddress) ToCompressedString 

func (addr *MACAddress) ToCompressedString() string

ToCompressedString produces a short representation of this address while remaining within the confines of standard representation(s) of the address.

For MAC, it differs from the canonical string. It produces a shorter string for the address that has no leading zeros.

func (*MACAddress) ToCustomString 

func (addr *MACAddress) ToCustomString(stringOptions addrstr.StringOptions) string

ToCustomString creates a customized string from this address or address collection according to the given string option parameters

func (*MACAddress) ToDashedString 

func (addr *MACAddress) ToDashedString() string

ToDashedString produces a string delimited by dashes: aa-bb-cc-dd-ee-ff For range segments, '|' is used: 11-22-33|44-55-66 It returns the same string as ToCanonicalString.

func (*MACAddress) ToDottedString 

func (addr *MACAddress) ToDottedString() (string, addrerr.IncompatibleAddressError)

ToDottedString produces the dotted hexadecimal format aaaa.bbbb.cccc

func (*MACAddress) ToEUI64 

func (addr *MACAddress) ToEUI64(asMAC bool) (*MACAddress, addrerr.IncompatibleAddressError)

ToEUI64 converts to IPv6 EUI-64 section

http://standards.ieee.org/develop/regauth/tut/eui64.pdf

If asMAC if true, this address is considered MAC and the EUI-64 is extended using ff-ff, otherwise this address is considered EUI-48 and extended using ff-fe Note that IPv6 treats MAC as EUI-48 and extends MAC to IPv6 addresses using ff-fe

func (*MACAddress) ToEUI64IPv6 

func (addr *MACAddress) ToEUI64IPv6() (*IPv6AddressSection, addrerr.IncompatibleAddressError)

ToEUI64IPv6 converts to an Ipv6 address section. Any MAC prefix length is ignored. Other elements of this address section are incorporated into the conversion. This will provide the latter 4 segments of an IPv6 address, to be paired with an IPv6 prefix of 4 segments.

func (*MACAddress) ToHexString 

func (addr *MACAddress) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address as a single hexadecimal value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If an address collection cannot be written as a range of two values, an error is returned.

func (*MACAddress) ToKey added in v1.1.0 

func (addr *MACAddress) ToKey() *MACAddressKey

ToKey creates the associated address key. While addresses can be compared with the Compare, TrieCompare or Equal methods as well as various provided instances of AddressComparator, they are not comparable with go operators. However, IPv6AddressKey instances are comparable with go operators, and thus can be used as map keys.

func (*MACAddress) ToLinkLocalIPv6 

func (addr *MACAddress) ToLinkLocalIPv6() (*IPv6Address, addrerr.IncompatibleAddressError)

ToLinkLocalIPv6 converts to a link-local Ipv6 address. Any MAC prefix length is ignored. Other elements of this address section are incorporated into the conversion. This will provide the latter 4 segments of an IPv6 address, to be paired with the link-local IPv6 prefix of 4 segments.

func (*MACAddress) ToNormalizedString 

func (addr *MACAddress) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For MAC, it differs from the canonical string. It uses the most common representation of MAC addresses: xx:xx:xx:xx:xx:xx. An example is "01:23:45:67:89:ab". For range segments, '-' is used: 11:22:33-44:55:66

Each address has a unique normalized string.

func (*MACAddress) ToOUIPrefixBlock 

func (addr *MACAddress) ToOUIPrefixBlock() *MACAddress

ToOUIPrefixBlock returns a section in which the range of values match the full block for the OUI (organizationally unique identifier) bytes

func (*MACAddress) ToOctalString 

func (addr *MACAddress) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address as a single octal value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued address collection cannot be written as a single prefix block or a range of two values, an error is returned.

func (*MACAddress) ToPrefixBlock 

func (addr *MACAddress) ToPrefixBlock() *MACAddress

ToPrefixBlock returns the address associated with the prefix of this address or address collection, the address whose prefix matches the prefix of this address, and the remaining bits span all values. If this address has no prefix length, this address is returned.

The returned address collection will include all addresses with the same prefix as this one, the prefix "block".

func (*MACAddress) ToPrefixBlockLen added in v1.2.0 

func (addr *MACAddress) ToPrefixBlockLen(prefLen BitCount) *MACAddress

ToPrefixBlockLen returns the address associated with the prefix length provided, the address collection whose prefix of that length matches the prefix of this address, and the remaining bits span all values.

The returned address will include all addresses with the same prefix as this one, the prefix "block".

func (*MACAddress) ToSinglePrefixBlockOrAddress added in v1.1.0 

func (addr *MACAddress) ToSinglePrefixBlockOrAddress() *MACAddress

ToSinglePrefixBlockOrAddress converts to a single prefix block or address. If the given address is a single prefix block, it is returned. If it can be converted to a single prefix block by assigning a prefix length, the converted block is returned. If it is a single address, any prefix length is removed and the address is returned. Otherwise, nil is returned. This method provides the address formats used by tries. ToSinglePrefixBlockOrAddress is quite similar to AssignPrefixForSingleBlock, which always returns prefixed addresses, while this does not.

func (*MACAddress) ToSpaceDelimitedString 

func (addr *MACAddress) ToSpaceDelimitedString() string

ToSpaceDelimitedString produces a string delimited by spaces: aa bb cc dd ee ff

func (*MACAddress) TrieCompare added in v1.1.0 

func (addr *MACAddress) TrieCompare(other *MACAddress) (int, addrerr.IncompatibleAddressError)

TrieCompare compares two addresses according to address trie ordering. It returns a number less than zero, zero, or a number greater than zero if the first address argument is less than, equal to, or greater than the second.

The comparison is intended for individual addresses and CIDR prefix blocks. If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*MACAddress) TrieDecrement added in v1.1.0 

func (addr *MACAddress) TrieDecrement() *MACAddress

TrieDecrement returns the previous address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*MACAddress) TrieIncrement added in v1.1.0 

func (addr *MACAddress) TrieIncrement() *MACAddress

TrieIncrement returns the next address or block according to address trie ordering

If an address is neither an individual address nor a prefix block, it is treated like one:

  • ranges that occur inside the prefix length are ignored, only the lower value is used.
  • ranges beyond the prefix length are assumed to be the full range across all hosts for that prefix length.

func (*MACAddress) Uint64Value 

func (addr *MACAddress) Uint64Value() uint64

Uint64Value returns the lowest address in the address collection as a uint64

func (*MACAddress) UpperBytes 

func (addr *MACAddress) UpperBytes() []byte

UpperBytes returns the highest address in this address or address collection as a byte slice

func (*MACAddress) UpperUint64Value 

func (addr *MACAddress) UpperUint64Value() uint64

UpperUint64Value returns the highest address in the address collection as a uint64

func (*MACAddress) WithoutPrefixLen 

func (addr *MACAddress) WithoutPrefixLen() *MACAddress

WithoutPrefixLen provides the same address but with no prefix length. The values remain unchanged.

func (*MACAddress) Wrap 

func (addr *MACAddress) Wrap() WrappedAddress

Wrap wraps this address, returning a WrappedAddress, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections.

type MACAddressAssociativeTrie added in v1.1.0 

type MACAddressAssociativeTrie struct {
	// contains filtered or unexported fields
}

MACAddressAssociativeTrie represents a MAC address associative binary trie.

The keys are MAC addresses or prefix blocks. Each can be mapped to a value.

The zero value for MACAddressAssociativeTrie is a binary trie ready for use.

func NewMACAddressAssociativeTrie added in v1.1.0 

func NewMACAddressAssociativeTrie(extended bool) *MACAddressAssociativeTrie

NewMACAddressAssociativeTrie constructs a MAC associative address trie with the root as the zero-prefix prefix block

func (*MACAddressAssociativeTrie) Add added in v1.1.0 

func (trie *MACAddressAssociativeTrie) Add(addr *MACAddress) bool

Add adds the given address key to the trie, returning true if not there already.

func (*MACAddressAssociativeTrie) AddNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) AddNode(addr *MACAddress) *MACAddressAssociativeTrieNode

AddNode adds the address key to this trie. The new or existing node for the address is returned.

func (*MACAddressAssociativeTrie) AddTrie added in v1.1.0 

func (trie *MACAddressAssociativeTrie) AddTrie(added *MACAddressAssociativeTrieNode) *MACAddressAssociativeTrieNode

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.

func (*MACAddressAssociativeTrie) AddedNodesTreeString added in v1.1.0 

func (trie *MACAddressAssociativeTrie) 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 (*MACAddressAssociativeTrie) AllNodeIterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) AllNodeIterator(forward bool) MACAssociativeTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates the added all nodes in the trie following the natural trie order

func (*MACAddressAssociativeTrie) BlockSizeAllNodeIterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) MACAssociativeTrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*MACAddressAssociativeTrie) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) BlockSizeCachingAllNodeIterator() CachingMACAssociativeTrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

func (*MACAddressAssociativeTrie) BlockSizeNodeIterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) BlockSizeNodeIterator(lowerSubNodeFirst bool) MACAssociativeTrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*MACAddressAssociativeTrie) CeilingAddedNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) CeilingAddedNode(addr *MACAddress) *MACAddressAssociativeTrieNode

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 tree

func (*MACAddressAssociativeTrie) Clone added in v1.1.0 

func (trie *MACAddressAssociativeTrie) Clone() *MACAddressAssociativeTrie

Clone clones this trie

func (*MACAddressAssociativeTrie) ConstructAddedNodesTree added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ConstructAddedNodesTree() *MACAddressAssociativeTrie

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. 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 (*MACAddressAssociativeTrie) ContainedFirstAllNodeIterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) MACAssociativeTrieNodeIterator

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 (*MACAddressAssociativeTrie) ContainedFirstIterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ContainedFirstIterator(forwardSubNodeOrder bool) MACAssociativeTrieNodeIteratorRem

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 (*MACAddressAssociativeTrie) ContainingFirstAllNodeIterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingMACAssociativeTrieNodeIterator

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 and linear space (proportional to tree size).

func (*MACAddressAssociativeTrie) ContainingFirstIterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ContainingFirstIterator(forwardSubNodeOrder bool) CachingMACAssociativeTrieNodeIterator

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 and linear space (proportional to tree size).

func (*MACAddressAssociativeTrie) Contains added in v1.1.0 

func (trie *MACAddressAssociativeTrie) Contains(addr *MACAddress) 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 (*MACAddressAssociativeTrie) DeepEqual added in v1.1.0 

func (trie *MACAddressAssociativeTrie) DeepEqual(other *MACAddressAssociativeTrie) 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 (*MACAddressAssociativeTrie) DescendingIterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) DescendingIterator() MACAddressIterator

DescendingIterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in reverse sorted element order.

func (*MACAddressAssociativeTrie) ElementContains added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ElementContains(addr *MACAddress) 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 (*MACAddressAssociativeTrie) ElementsContainedBy added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ElementsContainedBy(addr *MACAddress) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrie) ElementsContaining added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ElementsContaining(addr *MACAddress) *ContainmentPath

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 (*MACAddressAssociativeTrie) Equal added in v1.1.0 

func (trie *MACAddressAssociativeTrie) Equal(other *MACAddressAssociativeTrie) bool

Equal returns whether the given argument is a trie with a set of nodes with the same keys as in this trie

func (*MACAddressAssociativeTrie) FirstAddedNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) FirstAddedNode() *MACAddressAssociativeTrieNode

FirstAddedNode returns the first (lowest-valued) added node in the trie or nil if there are no added entries in this tree

func (*MACAddressAssociativeTrie) FirstNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) FirstNode() *MACAddressAssociativeTrieNode

FirstNode returns the first (lowest-valued) node in the trie or nil if the trie is empty

func (*MACAddressAssociativeTrie) FloorAddedNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) FloorAddedNode(addr *MACAddress) *MACAddressAssociativeTrieNode

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 tree

func (MACAddressAssociativeTrie) Format added in v1.1.0 

func (trie MACAddressAssociativeTrie) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*MACAddressAssociativeTrie) Get added in v1.1.0 

func (trie *MACAddressAssociativeTrie) Get(addr *MACAddress) NodeValue

Get gets the specified 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 (*MACAddressAssociativeTrie) GetAddedNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) GetAddedNode(addr *MACAddress) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrie) GetNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) GetNode(addr *MACAddress) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrie) GetRoot added in v1.1.0 

func (trie *MACAddressAssociativeTrie) GetRoot() *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrie) HigherAddedNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) HigherAddedNode(addr *MACAddress) *MACAddressAssociativeTrieNode

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 tree

func (*MACAddressAssociativeTrie) IsEmpty added in v1.1.0 

func (trie *MACAddressAssociativeTrie) IsEmpty() bool

IsEmpty returns true if there are not any added nodes within this tree

func (*MACAddressAssociativeTrie) Iterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) Iterator() MACAddressIterator

Iterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in sorted element order.

func (*MACAddressAssociativeTrie) LastAddedNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) LastAddedNode() *MACAddressAssociativeTrieNode

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 tree

func (*MACAddressAssociativeTrie) LastNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) LastNode() *MACAddressAssociativeTrieNode

LastNode returns the last (highest-valued) node in the trie or nil if the trie is empty

func (*MACAddressAssociativeTrie) LongestPrefixMatch added in v1.1.0 

func (trie *MACAddressAssociativeTrie) LongestPrefixMatch(addr *MACAddress) *MACAddress

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 (*MACAddressAssociativeTrie) LongestPrefixMatchNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) LongestPrefixMatchNode(addr *MACAddress) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrie) LowerAddedNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) LowerAddedNode(addr *MACAddress) *MACAddressAssociativeTrieNode

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 tree

func (*MACAddressAssociativeTrie) NodeIterator added in v1.1.0 

func (trie *MACAddressAssociativeTrie) NodeIterator(forward bool) MACAssociativeTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through all the added nodes in the trie in forward or reverse tree order.

func (*MACAddressAssociativeTrie) NodeSize added in v1.1.0 

func (trie *MACAddressAssociativeTrie) NodeSize() int

NodeSize returns the number of nodes in the tree, which is always more than the number of elements.

func (*MACAddressAssociativeTrie) Put added in v1.1.0 

func (trie *MACAddressAssociativeTrie) Put(addr *MACAddress, value NodeValue) (bool, NodeValue)

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 (*MACAddressAssociativeTrie) PutNode added in v1.1.0 

func (trie *MACAddressAssociativeTrie) PutNode(addr *MACAddress, value NodeValue) *MACAddressAssociativeTrieNode

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 tree 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 (*MACAddressAssociativeTrie) PutTrie added in v1.1.0 

func (trie *MACAddressAssociativeTrie) PutTrie(added *MACAddressAssociativeTrieNode) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrie) Remap added in v1.1.0 

func (trie *MACAddressAssociativeTrie) Remap(addr *MACAddress, remapper func(NodeValue) NodeValue) *MACAddressAssociativeTrieNode

Remap remaps node values in the trie.

This will lookup the node corresponding to the given key. It will call the remapping function with the key as the first argument, regardless of whether the node is found or not.

If the node is not found, the value argument will be nil. If the node is found, the value argument will be the node's value, which can also be nil.

If the remapping function returns nil, then the matched node will be removed, if any. If it returns a non-nil value, then it will either set the existing node to have that value, or if there was no matched node, it will create a new node with that 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 value specifies changes to be made, then the trie will not be changed and a panic will ensue.

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 (*MACAddressAssociativeTrie) RemapIfAbsent added in v1.1.0 

func (trie *MACAddressAssociativeTrie) RemapIfAbsent(addr *MACAddress, supplier func() NodeValue, insertNil bool) *MACAddressAssociativeTrieNode

RemapIfAbsent remaps node values in the trie, but only for nodes that do not exist or are mapped to nil.

This will look up the node corresponding to the given key. If the node is not found or mapped to nil, this will call the remapping function.

If the remapping function returns a non-nil value, then it will either set the existing node to have that value, or if there was no matched node, it will create a new node with that value. If the remapping function returns nil, then it will do the same if insertNull is true, otherwise it will do nothing.

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 value specifies changes to be made, then the trie will not be changed and ConcurrentModificationException will be thrown instead.

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.

insertNull indicates whether nil values returned from remapper should be inserted into the map, or whether nil values indicate no remapping

func (*MACAddressAssociativeTrie) Remove added in v1.1.0 

func (trie *MACAddressAssociativeTrie) Remove(addr *MACAddress) 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.

func (*MACAddressAssociativeTrie) RemoveElementsContainedBy added in v1.1.0 

func (trie *MACAddressAssociativeTrie) RemoveElementsContainedBy(addr *MACAddress) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrie) Size added in v1.1.0 

func (trie *MACAddressAssociativeTrie) 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 (*MACAddressAssociativeTrie) String added in v1.1.0 

func (trie *MACAddressAssociativeTrie) String() string

String returns a visual representation of the tree with one node per line.

func (*MACAddressAssociativeTrie) ToAssociativeBase added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ToAssociativeBase() *AssociativeAddressTrie

ToAssociativeBase converts to the polymorphic associative trie representation of this trie

func (*MACAddressAssociativeTrie) ToBase added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ToBase() *AddressTrie

ToBase converts to the polymorphic non-associative representation of this trie

func (*MACAddressAssociativeTrie) ToMACBase added in v1.1.0 

func (trie *MACAddressAssociativeTrie) ToMACBase() *MACAddressTrie

ToMACBase converts to the non-associative representation of this trie

func (*MACAddressAssociativeTrie) TreeString added in v1.1.0 

func (trie *MACAddressAssociativeTrie) 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 MACAddressAssociativeTrieNode added in v1.1.0 

type MACAddressAssociativeTrieNode struct {
	// contains filtered or unexported fields
}

MACAddressAssociativeTrieNode is a node in a MACAddressAssociativeTrie.

In an associative trie, each key or node can be associated with a value.

Trie nodes are created by tries during add or put operations.

If a trie node is copied, a panic will result when methods that alter the trie are called on the copied node.

Iterator methods allow for traversal of the sub-trie with this node as the root.

If an iterator is advanced following a trie modification that followed the creation of the iterator, the iterator will panic.

func (*MACAddressAssociativeTrieNode) AllNodeIterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) AllNodeIterator(forward bool) MACAssociativeTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*MACAddressAssociativeTrieNode) AsNewTrie added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) AsNewTrie() *MACAddressAssociativeTrie

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 (*MACAddressAssociativeTrieNode) BlockSizeAllNodeIterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) MACAssociativeTrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all the nodes, ordered by keys from the largest prefix blocks to the 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 (*MACAddressAssociativeTrieNode) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) BlockSizeCachingAllNodeIterator() CachingMACAssociativeTrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest and then to individual addresses, in the sub-trie with this node as the root.

func (*MACAddressAssociativeTrieNode) BlockSizeNodeIterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) BlockSizeNodeIterator(lowerSubNodeFirst bool) MACAssociativeTrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes, ordered by keys from the largest prefix blocks to the 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 (*MACAddressAssociativeTrieNode) CeilingAddedNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) CeilingAddedNode(addr *Address) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrieNode) Clear added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) Clear()

Clear removes this node and all sub-nodes from the tree, after which isEmpty() will return true.

func (*MACAddressAssociativeTrieNode) ClearValue added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ClearValue()

ClearValue makes the value associated with this node the nil value

func (*MACAddressAssociativeTrieNode) Clone added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) Clone() *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrieNode) CloneTree added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) CloneTree() *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrieNode) Compare added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) Compare(other *MACAddressAssociativeTrieNode) int

Compare returns -1, 0 or 1 if this node is less than, equal, or greater than the other, according to the key and the trie order.

func (*MACAddressAssociativeTrieNode) ContainedFirstAllNodeIterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) MACAssociativeTrieNodeIterator

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary tree 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 (*MACAddressAssociativeTrieNode) ContainedFirstIterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ContainedFirstIterator(forwardSubNodeOrder bool) MACAssociativeTrieNodeIteratorRem

ContainedFirstIterator returns an iterator that does a post-order binary tree 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 (*MACAddressAssociativeTrieNode) ContainingFirstAllNodeIterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingMACAssociativeTrieNodeIterator

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*MACAddressAssociativeTrieNode) ContainingFirstIterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ContainingFirstIterator(forwardSubNodeOrder bool) CachingMACAssociativeTrieNodeIterator

ContainingFirstIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*MACAddressAssociativeTrieNode) Contains added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) Contains(addr *MACAddress) 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 exists already in the trie, false otherwise.

Use GetAddedNode to get the node for the address rather than just checking for its existence.

func (*MACAddressAssociativeTrieNode) DeepEqual added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) DeepEqual(other *MACAddressAssociativeTrieNode) 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 (*MACAddressAssociativeTrieNode) DescendingIterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) DescendingIterator() MACAddressIterator

DescendingIterator returns an iterator that iterates through the elements of the sub-trie with this node as the root. The iteration is in reverse sorted element order.

func (*MACAddressAssociativeTrieNode) ElementContains added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ElementContains(addr *MACAddress) 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 (*MACAddressAssociativeTrieNode) ElementsContainedBy added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ElementsContainedBy(addr *MACAddress) *MACAddressAssociativeTrieNode

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 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 (*MACAddressAssociativeTrieNode) ElementsContaining added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ElementsContaining(addr *MACAddress) *ContainmentPath

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 (*MACAddressAssociativeTrieNode) Equal added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) Equal(other *MACAddressAssociativeTrieNode) bool

Equal returns whether the key and mapped value match those of the given node

func (*MACAddressAssociativeTrieNode) FirstAddedNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) FirstAddedNode() *MACAddressAssociativeTrieNode

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 tree or sub-trie

func (*MACAddressAssociativeTrieNode) FirstNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) FirstNode() *MACAddressAssociativeTrieNode

FirstNode returns the first (the lowest valued) node in the sub-trie originating from this node.

func (*MACAddressAssociativeTrieNode) FloorAddedNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) FloorAddedNode(addr *Address) *MACAddressAssociativeTrieNode

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 (MACAddressAssociativeTrieNode) Format added in v1.1.0 

func (node MACAddressAssociativeTrieNode) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*MACAddressAssociativeTrieNode) Get added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) Get(addr *MACAddress) NodeValue

Get gets the specified 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 (*MACAddressAssociativeTrieNode) GetAddedNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) GetAddedNode(addr *MACAddress) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrieNode) GetKey added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) GetKey() *MACAddress

GetKey gets the key used for placing the node in the tree.

func (*MACAddressAssociativeTrieNode) GetLowerSubNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) GetLowerSubNode() *MACAddressAssociativeTrieNode

GetLowerSubNode gets the direct child node whose key is smallest in value

func (*MACAddressAssociativeTrieNode) GetNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) GetNode(addr *MACAddress) *MACAddressAssociativeTrieNode

GetNode gets the node in the trie, with this sub-node 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 (*MACAddressAssociativeTrieNode) GetParent added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) GetParent() *MACAddressAssociativeTrieNode

GetParent gets the node from which this node is a direct child node, or nil if this is the root.

func (*MACAddressAssociativeTrieNode) GetUpperSubNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) GetUpperSubNode() *MACAddressAssociativeTrieNode

GetUpperSubNode gets the direct child node whose key is largest in value

func (*MACAddressAssociativeTrieNode) GetValue added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) GetValue() NodeValue

GetValue sets the value associated with this node

func (*MACAddressAssociativeTrieNode) HigherAddedNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) HigherAddedNode(addr *Address) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrieNode) IsAdded added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) IsAdded() bool

IsAdded returns whether the node was "added". Some binary tree nodes are considered "added" and others are not. Those nodes created for key elements added to the tree 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 tree. 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 (*MACAddressAssociativeTrieNode) IsEmpty added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) IsEmpty() bool

IsEmpty returns whether the size is 0

func (*MACAddressAssociativeTrieNode) IsLeaf added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) 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-trie with this node as the root.

func (*MACAddressAssociativeTrieNode) IsRoot added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) IsRoot() bool

IsRoot returns whether this is the root of the backing tree.

func (*MACAddressAssociativeTrieNode) Iterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) Iterator() MACAddressIterator

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 (*MACAddressAssociativeTrieNode) LastAddedNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) LastAddedNode() *MACAddressAssociativeTrieNode

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 tree or sub-trie

func (*MACAddressAssociativeTrieNode) LastNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) LastNode() *MACAddressAssociativeTrieNode

LastNode returns the last (the highest valued) node in the sub-trie originating from this node.

func (*MACAddressAssociativeTrieNode) LongestPrefixMatch added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) LongestPrefixMatch(addr *MACAddress) *Address

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 (*MACAddressAssociativeTrieNode) LongestPrefixMatchNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) LongestPrefixMatchNode(addr *MACAddress) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrieNode) LowerAddedNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) LowerAddedNode(addr *Address) *MACAddressAssociativeTrieNode

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 (*MACAddressAssociativeTrieNode) NextAddedNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) NextAddedNode() *MACAddressAssociativeTrieNode

NextAddedNode returns the next node in the tree that is an added node, following the tree order, or nil if there is no such node.

func (*MACAddressAssociativeTrieNode) NextNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) NextNode() *MACAddressAssociativeTrieNode

NextNode returns the node that follows this node following the tree order

func (*MACAddressAssociativeTrieNode) NodeIterator added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) NodeIterator(forward bool) MACAssociativeTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*MACAddressAssociativeTrieNode) NodeSize added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) 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 (*MACAddressAssociativeTrieNode) PreviousAddedNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) PreviousAddedNode() *MACAddressAssociativeTrieNode

PreviousAddedNode returns the previous node in the tree that is an added node, following the tree order in reverse, or nil if there is no such node.

func (*MACAddressAssociativeTrieNode) PreviousNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) PreviousNode() *MACAddressAssociativeTrieNode

PreviousNode returns the node that precedes this node following the tree order.

func (*MACAddressAssociativeTrieNode) Remove added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) 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 (*MACAddressAssociativeTrieNode) RemoveElementsContainedBy added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) RemoveElementsContainedBy(addr *MACAddress) *MACAddressAssociativeTrieNode

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 sub-trie that was removed from the trie, or nil if nothing was removed.

func (*MACAddressAssociativeTrieNode) RemoveNode added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) RemoveNode(addr *MACAddress) 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.

func (*MACAddressAssociativeTrieNode) SetAdded added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) SetAdded()

SetAdded makes this node an added node, which is equivalent to adding the corresponding key to the tree. 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 tree by calling Remove. A non-added node will only remain in the tree if it needs to in the tree.

func (*MACAddressAssociativeTrieNode) SetValue added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) SetValue(val NodeValue)

SetValue sets the value associated with this node

func (*MACAddressAssociativeTrieNode) Size added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) Size() int

Size returns the number of elements in the tree. Only nodes for which IsAdded returns true are counted. When zero is returned, IsEmpty returns true.

func (*MACAddressAssociativeTrieNode) String added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) 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 (*MACAddressAssociativeTrieNode) ToAssociativeBase added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ToAssociativeBase() *AssociativeAddressTrieNode

ToAssociativeBase converts to the polymorphic associative representation of this trie node The node is unchanged, the returned node is the same underlying node.

func (*MACAddressAssociativeTrieNode) ToBase added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ToBase() *AddressTrieNode

ToBase converts to the polymorphic non-associative representation of this trie node The node is unchanged, the returned node is the same underlying node.

func (*MACAddressAssociativeTrieNode) ToMACBase added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) ToMACBase() *MACAddressTrieNode

ToMACBase converts to the non-associative representation of this MAC trie node. The node is unchanged, the returned node is the same underlying node.

func (*MACAddressAssociativeTrieNode) TreeDeepEqual added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) TreeDeepEqual(other *MACAddressAssociativeTrieNode) 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 (*MACAddressAssociativeTrieNode) TreeEqual added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) TreeEqual(other *MACAddressAssociativeTrieNode) bool

TreeEqual returns whether the sub-trie represented by this node as the root node matches the given sub-trie

func (*MACAddressAssociativeTrieNode) TreeString added in v1.1.0 

func (node *MACAddressAssociativeTrieNode) 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 MACAddressIterator 

type MACAddressIterator interface {
	HasNext

	// Next returns the next MAC address, or nil if there is none left.
	Next() *MACAddress
}

MACAddressIterator iterates through MAC address collections

type MACAddressKey added in v1.1.0 

type MACAddressKey struct {
	Values [ExtendedUniqueIdentifier64SegmentCount]struct {
		Value      MACSegInt
		UpperValue MACSegInt
	}
	Prefix       PrefixKey
	SegmentCount uint8
}

MACAddressKey is a representation of MACAddress that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators It can be used as a map key. The zero value is a zero-length MAC address.

func (*MACAddressKey) String added in v1.1.1 

func (key *MACAddressKey) String() string

String calls the String method in the corresponding MAC address

func (*MACAddressKey) ToAddress added in v1.1.0 

func (key *MACAddressKey) ToAddress() *MACAddress

ToAddress converts to an address instance

func (*MACAddressKey) ToBaseKey added in v1.1.0 

func (key *MACAddressKey) ToBaseKey() *AddressKey

ToBaseKey converts to key that can be used for any address type or version

func (*MACAddressKey) UpperVal added in v1.1.0 

func (key *MACAddressKey) UpperVal(segmentIndex int) IPv4SegInt

UpperVal provides the upper value for a given segment. For a given key, the val method provides a function of type MACSegmentProvider

func (*MACAddressKey) Val added in v1.1.0 

func (key *MACAddressKey) Val(segmentIndex int) IPv4SegInt

Val provides the lower value for a given segment. For a given key, the val method provides a function of type MACSegmentProvider

type MACAddressSection 

type MACAddressSection struct {
	// contains filtered or unexported fields
}

MACAddressSection is a section of a MACAddress.

It is a series of 0 to 8 individual MAC address segments.

func NewMACSection 

func NewMACSection(segments []*MACAddressSegment) *MACAddressSection

NewMACSection constructs a MAC address or address collection section from the given segments.

func NewMACSectionFromBytes 

func NewMACSectionFromBytes(bytes []byte, segmentCount int) (res *MACAddressSection, err addrerr.AddressValueError)

NewMACSectionFromBytes constructs a MAC address section from the given byte slice. The segment count is determined by the slice length, even if the segment count exceeds 8 segments.

func NewMACSectionFromRange 

func NewMACSectionFromRange(vals, upperVals MACSegmentValueProvider, segmentCount int) (res *MACAddressSection)

NewMACSectionFromRange constructs a MAC address collection section of the given segment count from the given values.

func NewMACSectionFromUint64 

func NewMACSectionFromUint64(val uint64, segmentCount int) (res *MACAddressSection)

NewMACSectionFromUint64 constructs a MAC address section of the given segment count from the given value. The least significant bits of the given value will be used.

func NewMACSectionFromVals 

func NewMACSectionFromVals(vals MACSegmentValueProvider, segmentCount int) (res *MACAddressSection)

NewMACSectionFromVals constructs a MAC address section of the given segment count from the given values.

func (*MACAddressSection) AdjustPrefixLen 

func (section *MACAddressSection) AdjustPrefixLen(prefixLen BitCount) *AddressSection

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (*MACAddressSection) AdjustPrefixLenZeroed 

func (section *MACAddressSection) AdjustPrefixLenZeroed(prefixLen BitCount) (*AddressSection, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the address section.

If this address section has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*MACAddressSection) Append 

func (section *MACAddressSection) Append(other *MACAddressSection) *MACAddressSection

Append creates a new section by appending the given section to this section.

func (*MACAddressSection) AssignMinPrefixForBlock 

func (section *MACAddressSection) AssignMinPrefixForBlock() *MACAddressSection

AssignMinPrefixForBlock returns an equivalent address section, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this address section.

In other words, this method assigns a prefix length to this address section matching the largest prefix block in this address section.

func (*MACAddressSection) AssignPrefixForSingleBlock 

func (section *MACAddressSection) AssignPrefixForSingleBlock() *MACAddressSection

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this address section. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such address section - it is required that the range of values match the range of a prefix block. If there is no such address section, then nil is returned.

func (*MACAddressSection) Bytes 

func (section *MACAddressSection) Bytes() []byte

Bytes returns the lowest individual address section in this address section as a byte slice

func (*MACAddressSection) Compare 

func (section *MACAddressSection) Compare(item AddressItem) int

Compare returns a negative integer, zero, or a positive integer if this address section is less than, equal, or greater than the given item. Any address item is comparable to any other. All address items use CountComparator to compare.

func (*MACAddressSection) CompareSize 

func (section *MACAddressSection) CompareSize(other StandardDivGroupingType) 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 comparing 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, 0 if they are the same, or a negative integer if the other has a larger count.

func (*MACAddressSection) Contains 

func (section *MACAddressSection) Contains(other AddressSectionType) bool

Contains returns whether this is same type and version as the given address section and whether it contains all values in the given section.

Sections must also have the same number of segments to be comparable, otherwise false is returned.

func (*MACAddressSection) ContainsPrefixBlock 

func (section *MACAddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (*MACAddressSection) ContainsSinglePrefixBlock 

func (section *MACAddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this grouping contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (*MACAddressSection) CopyBytes 

func (section *MACAddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddressSection) CopySegments 

func (section *MACAddressSection) CopySegments(segs []*MACAddressSegment) (count int)

CopySegments copies the existing segments into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*MACAddressSection) CopySubSegments 

func (section *MACAddressSection) CopySubSegments(start, end int, segs []*MACAddressSegment) (count int)

CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index, into the given slice, as much as can be fit into the slice, returning the number of segments copied

func (*MACAddressSection) CopyUpperBytes 

func (section *MACAddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddressSection) Equal 

func (section *MACAddressSection) Equal(other AddressSectionType) bool

Equal returns whether the given address section is equal to this address section. Two address sections are equal if they represent the same set of sections. They must match:

  • type/version: MAC
  • segment counts
  • segment value ranges

Prefix lengths are ignored.

func (*MACAddressSection) ForEachSegment added in v1.2.0 

func (section *MACAddressSection) ForEachSegment(consumer func(segmentIndex int, segment *MACAddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true Returns the number of visited segments.

func (MACAddressSection) Format 

func (section MACAddressSection) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats 'v' for the default address and section format (either the normalized or canonical string), 's' (string) for the same, 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix), 'd' (decimal), 'x' (lowercase hexadecimal), and 'X' (uppercase hexadecimal). Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which is leading zero for octal and for hexadecimal, a leading "0x" or "0X" for "%#x" and "%#X" respectively, Also supported is specification of minimum digits precision, output field width, space or zero padding, and '-' for left or right justification.

func (*MACAddressSection) GetBitCount 

func (section *MACAddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item

func (*MACAddressSection) GetBitsPerSegment 

func (section *MACAddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (*MACAddressSection) GetBlockCount 

func (section *MACAddressSection) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (*MACAddressSection) GetByteCount 

func (section *MACAddressSection) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item

func (*MACAddressSection) GetBytesPerSegment 

func (section *MACAddressSection) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this section. Segments in the same address section are equal length.

func (*MACAddressSection) GetCount 

func (section *MACAddressSection) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1, unless this is a division grouping with no divisions, or an address section with no segments, in which case it is 0.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*MACAddressSection) GetDottedGrouping 

func (section *MACAddressSection) GetDottedGrouping() (*AddressDivisionGrouping, addrerr.IncompatibleAddressError)

GetDottedGrouping returns an AddressDivisionGrouping which organizes the address section into segments of bit-length 16, rather than the more typical 8 bits per segment.

If this represents a collection of MAC addresses, this returns an error when unable to join two address segments, the first with a range of values, into a division of the larger bit-length that represents the same set of values.

func (*MACAddressSection) GetGenericSegment 

func (section *MACAddressSection) GetGenericSegment(index int) AddressSegmentType

GetGenericSegment returns the segment as an AddressSegmentType, allowing all segment types to be represented by a single type

func (*MACAddressSection) GetLeadingBitCount added in v1.1.0 

func (section *MACAddressSection) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower value of the range if this section represents multiple values.

func (*MACAddressSection) GetLower 

func (section *MACAddressSection) GetLower() *MACAddressSection

GetLower returns the section in the range with the lowest numeric value, which will be the same section if it represents a single value. For example, for "1:1:1:2-3:4:5-6", the series "1:1:1:2:4:5" is returned.

func (*MACAddressSection) GetMaxSegmentValue 

func (section *MACAddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (*MACAddressSection) GetMinPrefixLenForBlock 

func (section *MACAddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (*MACAddressSection) GetPrefixCount 

func (section *MACAddressSection) GetPrefixCount() *big.Int

GetPrefixCount returns the number of distinct prefix values in this item.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the number of distinct prefix values.

If this has a nil prefix length, returns the same value as GetCount

func (*MACAddressSection) GetPrefixCountLen 

func (section *MACAddressSection) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the number of distinct prefix values in this item for the given prefix length

func (*MACAddressSection) GetPrefixLen 

func (section *MACAddressSection) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (*MACAddressSection) GetPrefixLenForSingleBlock 

func (section *MACAddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (*MACAddressSection) GetSegment 

func (section *MACAddressSection) GetSegment(index int) *MACAddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or index larger than the segment count.

func (*MACAddressSection) GetSegmentCount 

func (section *MACAddressSection) GetSegmentCount() int

func (*MACAddressSection) GetSegmentStrings 

func (section *MACAddressSection) GetSegmentStrings() []string

GetSegmentStrings returns a slice with the string for each segment being the string that is normalized with wildcards.

func (*MACAddressSection) GetSegments 

func (section *MACAddressSection) GetSegments() (res []*MACAddressSegment)

GetSegments returns a slice with the address segments. The returned slice is not backed by the same array as this section.

func (*MACAddressSection) GetSequentialBlockCount 

func (section *MACAddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section

func (*MACAddressSection) GetSequentialBlockIndex 

func (section *MACAddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (*MACAddressSection) GetSubSection 

func (section *MACAddressSection) GetSubSection(index, endIndex int) *MACAddressSection

GetSubSection gets the subsection from the series starting from the given index and ending just before the give endIndex. The first segment is at index 0.

func (*MACAddressSection) GetTrailingBitCount added in v1.1.0 

func (section *MACAddressSection) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies to the lower value of the range if this section represents multiple values.

func (*MACAddressSection) GetTrailingSection 

func (section *MACAddressSection) GetTrailingSection(index int) *MACAddressSection

GetTrailingSection gets the subsection from the series starting from the given index. The first segment is at index 0.

func (*MACAddressSection) GetUpper 

func (section *MACAddressSection) GetUpper() *MACAddressSection

GetUpper returns the section in the range with the highest numeric value, which will be the same section if it represents a single value. For example, for "1:1:1:2-3:4:5-6", the series "1:1:1:3:4:6" is returned.

func (*MACAddressSection) GetUpperValue 

func (section *MACAddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value

func (*MACAddressSection) GetValue 

func (section *MACAddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value

func (*MACAddressSection) IncludesMax 

func (section *MACAddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range

func (*MACAddressSection) IncludesZero 

func (section *MACAddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range

func (*MACAddressSection) Increment 

func (section *MACAddressSection) Increment(incrementVal int64) *MACAddressSection

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (*MACAddressSection) IncrementBoundary 

func (section *MACAddressSection) IncrementBoundary(increment int64) *MACAddressSection

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (*MACAddressSection) Insert 

func (section *MACAddressSection) Insert(index int, other *MACAddressSection) *MACAddressSection

Insert creates a new section by inserting the given section into this section at the given index.

func (*MACAddressSection) IsAdaptiveZero 

func (section *MACAddressSection) IsAdaptiveZero() bool

IsAdaptiveZero returns true if the section was originally created as an implicitly zero-valued section (eg MACAddressSection{}), 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, etc 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 (*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 < 0, 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() MACSectionIterator

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() MACSectionIterator

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() MACSectionIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this address section, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this address section.

If the series has no prefix length, then this is equivalent to Iterator.

func (*MACAddressSection) Replace 

func (section *MACAddressSection) Replace(index int, replacement *MACAddressSection) *MACAddressSection

Replace replaces the segments of this section starting at the given index with the given replacement segments

func (*MACAddressSection) ReplaceLen 

func (section *MACAddressSection) ReplaceLen(startIndex, endIndex int, replacement *MACAddressSection, replacementStartIndex, replacementEndIndex int) *MACAddressSection

ReplaceLen replaces segments starting from startIndex and ending before endIndex with the segments starting at replacementStartIndex and ending before replacementEndIndex from the replacement section

func (*MACAddressSection) ReverseBits 

func (section *MACAddressSection) ReverseBits(perByte bool) (*MACAddressSection, addrerr.IncompatibleAddressError)

ReverseBits returns a new section with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*MACAddressSection) ReverseBytes 

func (section *MACAddressSection) ReverseBytes() *MACAddressSection

ReverseBytes returns a new section with the bytes reversed. Any prefix length is dropped.

func (*MACAddressSection) ReverseSegments 

func (section *MACAddressSection) ReverseSegments() *MACAddressSection

ReverseSegments returns a new section with the segments reversed.

func (*MACAddressSection) SetPrefixLen 

func (section *MACAddressSection) SetPrefixLen(prefixLen BitCount) *MACAddressSection

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

func (*MACAddressSection) SetPrefixLenZeroed 

func (section *MACAddressSection) SetPrefixLenZeroed(prefixLen BitCount) (*MACAddressSection, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the address section. The provided prefix length will be adjusted to these boundaries if necessary.

If this address section has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this address section has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (ie bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (*MACAddressSection) String 

func (section *MACAddressSection) String() string

String implements the fmt.Stringer interface, returning the normalized string provided by ToNormalizedString, or "<nil>" if the receiver is a nil pointer

func (*MACAddressSection) TestBit 

func (section *MACAddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*MACAddressSection) ToBinaryString 

func (section *MACAddressSection) ToBinaryString(with0bPrefix bool) (string, addrerr.IncompatibleAddressError)

ToBinaryString writes this address section as a single binary value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0b" prefix.

If a multiple-valued section cannot be written as a range of two values, an error is returned.

func (*MACAddressSection) ToBlock 

func (section *MACAddressSection) ToBlock(segmentIndex int, lower, upper SegInt) *MACAddressSection

ToBlock creates a new block of address sections by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (*MACAddressSection) ToCanonicalString 

func (section *MACAddressSection) ToCanonicalString() string

ToCanonicalString produces a canonical string for the address section.

For MAC, it uses the canonical standardized IEEE 802 MAC address representation of xx-xx-xx-xx-xx-xx. An example is "01-23-45-67-89-ab". For range segments, '|' is used: 11-22-33|44-55-66

func (*MACAddressSection) ToColonDelimitedString 

func (section *MACAddressSection) ToColonDelimitedString() string

ToColonDelimitedString produces a string delimited by colons: aa:bb:cc:dd:ee:ff For range segments, '-' is used: 11:22:33-44:55:66 It returns the same string as ToNormalizedString.

func (*MACAddressSection) ToCompressedString 

func (section *MACAddressSection) ToCompressedString() string

ToCompressedString produces a short representation of this address section while remaining within the confines of standard representation(s) of the address.

For MAC, it differs from the canonical string. It produces a shorter string for the address that has no leading zeros.

func (*MACAddressSection) ToDashedString 

func (section *MACAddressSection) ToDashedString() string

ToDashedString produces a string delimited by dashes: aa-bb-cc-dd-ee-ff. For range segments, '|' is used: 11-22-33|44-55-66 It returns the same string as ToCanonicalString.

func (*MACAddressSection) ToDivGrouping 

func (section *MACAddressSection) ToDivGrouping() *AddressDivisionGrouping

ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings. Afterwards, you can convert back with ToMAC.

ToDivGrouping can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*MACAddressSection) ToDottedString 

func (section *MACAddressSection) ToDottedString() (string, addrerr.IncompatibleAddressError)

ToDottedString produces the dotted hexadecimal format aaaa.bbbb.cccc

func (*MACAddressSection) ToHexString 

func (section *MACAddressSection) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address section as a single hexadecimal value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0x" prefix.

If a multiple-valued section cannot be written as a range of two values, an error is returned.

func (*MACAddressSection) ToNormalizedString 

func (section *MACAddressSection) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address section.

For MAC, it differs from the canonical string. It uses the most common representation of MAC addresses: xx:xx:xx:xx:xx:xx. An example is "01:23:45:67:89:ab". For range segments, '-' is used: 11:22:33-44:55:66

func (*MACAddressSection) ToOctalString 

func (section *MACAddressSection) ToOctalString(with0Prefix bool) (string, addrerr.IncompatibleAddressError)

ToOctalString writes this address section as a single octal value (possibly two values if a range), the number of digits according to the bit count, with or without a preceding "0" prefix.

If a multiple-valued section cannot be written as a single prefix block or a range of two values, an error is returned.

func (*MACAddressSection) ToPrefixBlock 

func (section *MACAddressSection) ToPrefixBlock() *MACAddressSection

ToPrefixBlock returns the section with the same prefix as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

If this section has no prefix, this section is returned.

func (*MACAddressSection) ToPrefixBlockLen 

func (section *MACAddressSection) ToPrefixBlockLen(prefLen BitCount) *MACAddressSection

ToPrefixBlockLen returns the section with the same prefix of the given length as this section while the remaining bits span all values. The returned section will be the block of all sections with the same prefix.

func (*MACAddressSection) ToSectionBase 

func (section *MACAddressSection) ToSectionBase() *AddressSection

ToSectionBase converts to an AddressSection, a polymorphic type usable with all address sections. Afterwards, you can convert back with ToMAC.

ToSectionBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*MACAddressSection) ToSpaceDelimitedString 

func (section *MACAddressSection) ToSpaceDelimitedString() string

ToSpaceDelimitedString produces a string delimited by spaces: aa bb cc dd ee ff

func (*MACAddressSection) Uint64Value 

func (section *MACAddressSection) Uint64Value() uint64

Uint64Value returns the lowest indiviudal 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 indiviudal 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) Contains 

func (seg *MACAddressSegment) Contains(other AddressSegmentType) bool

Contains returns whether this is same type and version as the given segment and whether it contains all values in the given segment.

func (*MACAddressSegment) ContainsPrefixBlock 

func (seg *MACAddressSegment) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the segment range includes the block of values for the given prefix length

func (*MACAddressSegment) ContainsSinglePrefixBlock 

func (seg *MACAddressSegment) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the segment range matches exactly the block of values for the given prefix length and has just a single prefix for that prefix length.

func (*MACAddressSegment) CopyBytes 

func (seg *MACAddressSegment) CopyBytes(bytes []byte) []byte

CopyBytes copies the lowest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddressSegment) CopyUpperBytes 

func (seg *MACAddressSegment) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the highest value in the address segment range into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (*MACAddressSegment) Equal 

func (seg *MACAddressSegment) Equal(other AddressSegmentType) bool

Equal returns whether the given segment is equal to this segment. Two segments are equal if they match:

  • type/version: MAC
  • value range

Prefix lengths are ignored.

func (*MACAddressSegment) GetBitCount 

func (seg *MACAddressSegment) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item, which is 8.

func (*MACAddressSegment) GetByteCount 

func (seg *MACAddressSegment) GetByteCount() int

GetByteCount returns the number of bytes required for each value comprising this address item, which is 1.

func (*MACAddressSegment) GetCount 

func (seg *MACAddressSegment) GetCount() *big.Int

GetCount returns the count of possible distinct values for this item. If not representing multiple values, the count is 1.

For instance, a segment with the value range of 3-7 has count 5.

Use IsMultiple if you simply want to know if the count is greater than 1.

func (*MACAddressSegment) GetLeadingBitCount added in v1.1.0 

func (seg *MACAddressSegment) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*MACAddressSegment) GetLower 

func (seg *MACAddressSegment) GetLower() *MACAddressSegment

GetLower returns a segment representing just the lowest value in the range, which will be the same segment if it represents a single value.

func (*MACAddressSegment) GetMACSegmentValue 

func (seg *MACAddressSegment) GetMACSegmentValue() MACSegInt

GetMACSegmentValue returns the lower value. Same as GetSegmentValue but returned as a MACSegInt.

func (*MACAddressSegment) GetMACUpperSegmentValue 

func (seg *MACAddressSegment) GetMACUpperSegmentValue() MACSegInt

GetMACUpperSegmentValue returns the lower value. Same as GetUpperSegmentValue but returned as a MACSegInt.

func (*MACAddressSegment) GetMaxValue 

func (seg *MACAddressSegment) GetMaxValue() MACSegInt

GetMaxValue gets the maximum possible value for this type or version of segment, determined by the number of bits.

For the highest range value of this particular segment, use GetUpperSegmentValue.

func (*MACAddressSegment) GetMinPrefixLenForBlock 

func (seg *MACAddressSegment) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this segment includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this segment represents a single value, this returns the bit count.

func (*MACAddressSegment) GetPrefixCountLen 

func (seg *MACAddressSegment) GetPrefixCountLen(segmentPrefixLength BitCount) *big.Int

GetPrefixCountLen returns the count of the number of distinct prefix values for the given prefix length in the range of values of this segment

func (*MACAddressSegment) GetPrefixLenForSingleBlock 

func (seg *MACAddressSegment) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which there is only one prefix in this segment, and the range of values in this segment matches the block of all values for that prefix.

If the range of segment values can be described this way, then this method returns the same value as GetMinPrefixLenForBlock.

If no such prefix length exists, returns nil.

If this segment represents a single value, this returns the bit count of the segment.

func (*MACAddressSegment) GetPrefixValueCountLen 

func (seg *MACAddressSegment) GetPrefixValueCountLen(segmentPrefixLength BitCount) SegIntCount

GetPrefixValueCountLen returns the same value as GetPrefixCountLen as an integer

func (*MACAddressSegment) GetSegmentHostMask added in v1.1.0 

func (seg *MACAddressSegment) GetSegmentHostMask(networkBits BitCount) SegInt

GetSegmentHostMask returns a value comprising the same number of total bits as the bit-length of this segment, the value that is all zero-bits for the given number of bits followed by all one-bits.

func (*MACAddressSegment) GetSegmentNetworkMask added in v1.1.0 

func (seg *MACAddressSegment) GetSegmentNetworkMask(networkBits BitCount) SegInt

GetSegmentNetworkMask returns a value comprising the same number of total bits as the bit-length of this segment, the value that is all one-bits for the given number of bits followed by all zero-bits.

func (*MACAddressSegment) GetSegmentValue 

func (seg *MACAddressSegment) GetSegmentValue() SegInt

GetSegmentValue returns the lower value of the segment value range

func (*MACAddressSegment) GetString 

func (seg *MACAddressSegment) GetString() string

GetString produces a normalized string to represent the segment.

For MAC segments, the string is the same as that produced by GetWildcardString.

func (*MACAddressSegment) GetTrailingBitCount added in v1.1.0 

func (seg *MACAddressSegment) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies only to the lower value of the range if this segment represents multiple values.

func (*MACAddressSegment) GetUpper 

func (seg *MACAddressSegment) GetUpper() *MACAddressSegment

GetUpper returns a segment representing just the highest value in the range, which will be the same segment if it represents a single value.

func (*MACAddressSegment) GetUpperSegmentValue 

func (seg *MACAddressSegment) GetUpperSegmentValue() SegInt

GetUpperSegmentValue returns the upper value of the segment value range

func (*MACAddressSegment) GetUpperValue 

func (seg *MACAddressSegment) GetUpperValue() *BigDivInt

GetUpperValue returns the highest value in the address segment range as a big integer

func (*MACAddressSegment) GetValue 

func (seg *MACAddressSegment) GetValue() *BigDivInt

GetValue returns the lowest value in the address segment range as a big integer

func (*MACAddressSegment) GetValueCount 

func (seg *MACAddressSegment) GetValueCount() SegIntCount

GetValueCount returns the same value as GetCount as an integer

func (*MACAddressSegment) GetWildcardString 

func (seg *MACAddressSegment) GetWildcardString() string

GetWildcardString produces a normalized string to represent the segment, favouring wildcards and range characters. The explicit range of a range-valued segment will be printed.

The string returned is useful in the context of creating strings for address sections or full addresses, in which case the radix and the bit-length can be deduced from the context. The String method produces strings more appropriate when no context is provided.

func (*MACAddressSegment) IncludesMax 

func (seg *MACAddressSegment) IncludesMax() bool

IncludesMax returns whether this segment includes the max value, the value whose bits are all ones, within its range

func (*MACAddressSegment) IncludesZero 

func (seg *MACAddressSegment) IncludesZero() bool

IncludesZero returns whether this segment includes the value of zero within its range

func (*MACAddressSegment) IsFullRange 

func (seg *MACAddressSegment) IsFullRange() bool

IsFullRange returns whether the segment range includes all possible values for its bit length. 

This is true if and only if both IncludesZero and IncludesMax return true.

func (*MACAddressSegment) IsMax 

func (seg *MACAddressSegment) IsMax() bool

IsMax returns whether this segment matches exactly the maximum possible value, the value whose bits are all ones

func (*MACAddressSegment) IsMultiple 

func (seg *MACAddressSegment) IsMultiple() bool

IsMultiple returns whether this segment represents multiple values

func (*MACAddressSegment) IsOneBit 

func (seg *MACAddressSegment) IsOneBit(segmentBitIndex BitCount) bool

Returns true if the bit in the lower value of this segment at the given index is 1, where index 0 is the most significant bit.

func (*MACAddressSegment) IsSinglePrefix 

func (seg *MACAddressSegment) IsSinglePrefix(divisionPrefixLength BitCount) bool

IsSinglePrefix determines if the segment has a single prefix value for the given prefix length. You can call GetPrefixCountLen to get the count of prefixes.

func (*MACAddressSegment) IsZero 

func (seg *MACAddressSegment) IsZero() bool

IsZero returns whether this segment matches exactly the value of zero

func (*MACAddressSegment) Iterator 

func (seg *MACAddressSegment) Iterator() MACSegmentIterator

Iterator provides an iterator to iterate through the individual address segments of this address segment.

Call IsMultiple to determine if this instance represents multiple address segments, or GetValueCount for the count.

func (*MACAddressSegment) Join 

func (seg *MACAddressSegment) Join(macSegment1 *MACAddressSegment, prefixLength PrefixLen) (*IPv6AddressSegment, addrerr.IncompatibleAddressError)

Join joins with another MAC segment to produce a IPv6 segment.

func (*MACAddressSegment) JoinAndFlip2ndBit 

func (seg *MACAddressSegment) JoinAndFlip2ndBit(macSegment1 *MACAddressSegment, prefixLength PrefixLen) (*IPv6AddressSegment, addrerr.IncompatibleAddressError)

JoinAndFlip2ndBit joins with another MAC segment to produce a IPv6 segment with the second bit flipped from 1 to 0.

func (*MACAddressSegment) Matches 

func (seg *MACAddressSegment) Matches(value SegInt) bool

Matches returns true if the segment range matches the given single value.

func (*MACAddressSegment) MatchesValsWithMask 

func (seg *MACAddressSegment) MatchesValsWithMask(lowerValue, upperValue, mask SegInt) bool

MatchesValsWithMask applies the mask to this segment and then compares the result with the given values, returning true if the range of the resulting segment matches the given range.

func (*MACAddressSegment) MatchesWithMask 

func (seg *MACAddressSegment) MatchesWithMask(value, mask SegInt) bool

MatchesWithMask applies the mask to this segment and then compares the result with the given value, returning true if the range of the resulting segment matches that single value.

func (*MACAddressSegment) PrefixBlockIterator 

func (seg *MACAddressSegment) PrefixBlockIterator(segmentPrefixLen BitCount) MACSegmentIterator

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) MACSegmentIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of the given prefix length in this segment, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this range.

func (*MACAddressSegment) ReverseBits 

func (seg *MACAddressSegment) ReverseBits(_ bool) (res *MACAddressSegment, err addrerr.IncompatibleAddressError)

ReverseBits returns a segment with the bits reversed.

If this segment represents a range of values that cannot be reversed, then this returns an error.

To be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves. Otherwise the result is not contiguous and thus cannot be represented by a sequential range of values.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (*MACAddressSegment) ReverseBytes 

func (seg *MACAddressSegment) ReverseBytes() (*MACAddressSegment, addrerr.IncompatibleAddressError)

ReverseBytes returns a segment with the bytes reversed, which for a MAC segment is always the original segment.

func (*MACAddressSegment) String 

func (seg *MACAddressSegment) String() string

String produces a string that is useful when a segment is provided with no context. It uses the hexadecimal radix with the string prefix for hex (0x). GetWildcardString and GetString are more appropriate in context with other segments or divisions. They do not use a string prefix and use '*' for full-range segments.

func (*MACAddressSegment) TestBit 

func (seg *MACAddressSegment) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this segment at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (*MACAddressSegment) ToDiv 

func (seg *MACAddressSegment) ToDiv() *AddressDivision

ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions. Afterwards, you can convert back with ToMAC.

ToDiv can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*MACAddressSegment) ToHexString 

func (seg *MACAddressSegment) ToHexString(with0xPrefix bool) (string, addrerr.IncompatibleAddressError)

ToHexString writes this address segment as a single hexadecimal value (possibly two values if a range that is not a prefixed block), the number of digits according to the bit count, with or without a preceding "0x" prefix.

For segments, the error is always nil.

func (*MACAddressSegment) ToNormalizedString 

func (seg *MACAddressSegment) ToNormalizedString() string

ToNormalizedString produces a string that is consistent for all address segments of the same type and version. IPv4 segments use base 10, while other segment types use base 16.

func (*MACAddressSegment) ToSegmentBase 

func (seg *MACAddressSegment) ToSegmentBase() *AddressSegment

ToSegmentBase converts to an AddressSegment, a polymorphic type usable with all address segments. Afterwards, you can convert back with ToMAC.

ToSegmentBase can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (*MACAddressSegment) UpperBytes 

func (seg *MACAddressSegment) UpperBytes() []byte

UpperBytes returns the highest value in the address segment range as a byte slice

type MACAddressSegmentSeries 

type MACAddressSegmentSeries interface {
	AddressSegmentSeries

	// GetTrailingSection returns an ending subsection of the full address section
	GetTrailingSection(index int) *MACAddressSection

	// GetSubSection returns a subsection of the full address section
	GetSubSection(index, endIndex int) *MACAddressSection

	// GetSegments returns a slice with the address segments.  The returned slice is not backed by the same array as the receiver.
	GetSegments() []*MACAddressSegment

	// CopySegments copies the existing segments into the given slice,
	// as much as can be fit into the slice, returning the number of segments copied
	CopySegments(segs []*MACAddressSegment) (count int)

	// CopySubSegments copies the existing segments from the given start index until but not including the segment at the given end index,
	// into the given slice, as much as can be fit into the slice, returning the number of segments copied
	CopySubSegments(start, end int, segs []*MACAddressSegment) (count int)

	// GetSegment returns the segment at the given index.
	// The first segment is at index 0.
	// GetSegment will panic given a negative index or index 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 of the supported formats using MACAddressStringParametersBuilder to build a parameters instance of MACAddressStringParameters. When not using the constructor that takes a MACAddressStringParameters, a default instance of MACAddressStringParameters 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 of the derived state is created upon demand and cached, such as the derived MACAddress instances.

func NewMACAddressString 

func NewMACAddressString(str string) *MACAddressString

NewMACAddressString constructs a MACAddressString that will parse the given string according to the default parameters

func NewMACAddressStringParams 

func NewMACAddressStringParams(str string, params addrstrparam.MACAddressStringParams) *MACAddressString

NewMACAddressStringParams constructs a MACAddressString that will parse the given string according to the given parameters

func (*MACAddressString) Compare 

func (addrStr *MACAddressString) Compare(other *MACAddressString) int

Compare compares this address string with another, returning a negative number, zero, or a positive number if this address string is less than, equal to, or greater than the other.

All address strings are comparable. If two address strings are invalid, their strings are compared. Two valid address trings are compared using the comparison rules for their respective addresses.

func (*MACAddressString) Equal 

func (addrStr *MACAddressString) Equal(other *MACAddressString) bool

Equal returns whether this MACAddressString is equal to the given one. Two MACAddressString objects are equal if they represent the same set of addresses.

If a MACAddressString is invalid, it is equal to another address only if the other address was constructed from the same string.

func (*MACAddressString) 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 valid prefixed address, otherwise returns nil

For MAC addresses, the prefix is initially inferred from the range, so 1:2:3:*:*:* has a prefix length of 24. Addresses derived from the original may retain the original prefix length regardless of their range.

func (*MACAddressString) GetValidationOptions 

func (addrStr *MACAddressString) GetValidationOptions() addrstrparam.MACAddressStringParams

GetValidationOptions returns the validation options supplied when constructing this address string, or the default options if no options were supplied.

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 all all valid MAC addresses for its address length

func (*MACAddressString) IsPrefixed 

func (addrStr *MACAddressString) IsPrefixed() bool

IsPrefixed returns whether this address has an associated prefix length, which for MAC means that the string represents the set of all addresses with the same prefix

func (*MACAddressString) IsValid 

func (addrStr *MACAddressString) IsValid() bool

IsValid returns whether this is a valid MAC address string format. The accepted MAC address formats are: a MAC address or address collection, the address representing all MAC addresses, or an empty string. If this method returns false, and you want more details, call Validate and examine the error.

func (*MACAddressString) IsZero 

func (addrStr *MACAddressString) IsZero() bool

IsZero returns whether this string represents a MAC address whose value is exactly zero.

func (*MACAddressString) String 

func (addrStr *MACAddressString) String() string

String implements the fmt.Stringer interface, returning the original string used to create this MACAddressString (altered by strings.TrimSpace), or "<nil>" if the receiver is a nil pointer

func (*MACAddressString) ToAddress 

func (addrStr *MACAddressString) ToAddress() (*MACAddress, addrerr.AddressError)

ToAddress produces the MACAddress corresponding to this MACAddressString.

If this object does not represent a specific MACAddress or address collection, nil is returned.

If the string used to construct this object is not a known format (empty string, address, or range of addresses) then this method returns an error.

An equivalent method that does not return the error is GetAddress.

The error can be addrerr.AddressStringError for an invalid string, or addrerr.IncompatibleAddressError for non-standard strings that cannot be converted to MACAddress.

func (*MACAddressString) ToNormalizedString 

func (addrStr *MACAddressString) ToNormalizedString() string

ToNormalizedString produces a normalized string for the address.

For MAC, it differs from the canonical string. It uses the most common representation of MAC addresses: xx:xx:xx:xx:xx:xx. An example is "01:23:45:67:89:ab". For range segments, '-' is used: 11:22:33-44:55:66

If the original string is not a valid address string, the original string is used.

func (*MACAddressString) Validate 

func (addrStr *MACAddressString) Validate() addrerr.AddressStringError

Validate validates that this string is a valid address, and if not, throws an exception with a descriptive message indicating why it is not.

func (*MACAddressString) Wrap 

func (addrStr *MACAddressString) Wrap() ExtendedIdentifierString

Wrap wraps this address string, returning a WrappedMACAddressString as an implementation of ExtendedIdentifierString, which can be used to write code that works with different host identifier types polymorphically, including IPAddressString, MACAddressString, and HostName.

type MACAddressTrie added in v1.1.0 

type MACAddressTrie struct {
	// contains filtered or unexported fields
}

MACAddressTrie represents a MAC address binary trie.

The keys are MAC addresses or prefix blocks.

The zero value for MACAddressTrie is a binary trie ready for use.

func NewMACAddressTrie added in v1.1.0 

func NewMACAddressTrie(extended bool) *MACAddressTrie

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{}

func (*MACAddressTrie) Add added in v1.1.0 

func (trie *MACAddressTrie) Add(addr *MACAddress) bool

Add adds the address to this trie. Returns true if the address did not already exist in the trie.

func (*MACAddressTrie) AddNode added in v1.1.0 

func (trie *MACAddressTrie) AddNode(addr *MACAddress) *MACAddressTrieNode

AddNode adds the address to this trie. The new or existing node for the address is returned.

func (*MACAddressTrie) AddTrie added in v1.1.0 

func (trie *MACAddressTrie) AddTrie(added *MACAddressTrieNode) *MACAddressTrieNode

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.

func (*MACAddressTrie) AddedNodesTreeString added in v1.1.0 

func (trie *MACAddressTrie) 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 (*MACAddressTrie) AllNodeIterator added in v1.1.0 

func (trie *MACAddressTrie) AllNodeIterator(forward bool) MACTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes in the trie in forward or reverse tree order.

func (*MACAddressTrie) BlockSizeAllNodeIterator added in v1.1.0 

func (trie *MACAddressTrie) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) MACTrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*MACAddressTrie) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (trie *MACAddressTrie) BlockSizeCachingAllNodeIterator() CachingMACTrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

func (*MACAddressTrie) BlockSizeNodeIterator added in v1.1.0 

func (trie *MACAddressTrie) BlockSizeNodeIterator(lowerSubNodeFirst bool) MACTrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes in the trie, ordered by keys from the largest prefix blocks to the smallest, and then to individual addresses.

If lowerSubNodeFirst is true, for blocks of equal size the lower is first, otherwise the reverse order

func (*MACAddressTrie) CeilingAddedNode added in v1.1.0 

func (trie *MACAddressTrie) CeilingAddedNode(addr *MACAddress) *MACAddressTrieNode

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 tree

func (*MACAddressTrie) Clear added in v1.1.0 

func (trie *MACAddressTrie) Clear()

Clear removes all added nodes from the tree, after which IsEmpty() will return true

func (*MACAddressTrie) Clone added in v1.1.0 

func (trie *MACAddressTrie) Clone() *MACAddressTrie

Clone clones this trie

func (*MACAddressTrie) ConstructAddedNodesTree added in v1.1.0 

func (trie *MACAddressTrie) ConstructAddedNodesTree() *MACAddressTrie

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. 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 (*MACAddressTrie) ContainedFirstAllNodeIterator added in v1.1.0 

func (trie *MACAddressTrie) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) MACTrieNodeIterator

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 (*MACAddressTrie) ContainedFirstIterator added in v1.1.0 

func (trie *MACAddressTrie) ContainedFirstIterator(forwardSubNodeOrder bool) MACTrieNodeIteratorRem

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 (*MACAddressTrie) ContainingFirstAllNodeIterator added in v1.1.0 

func (trie *MACAddressTrie) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingMACTrieNodeIterator

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 and linear space (proportional to tree size).

func (*MACAddressTrie) ContainingFirstIterator added in v1.1.0 

func (trie *MACAddressTrie) ContainingFirstIterator(forwardSubNodeOrder bool) CachingMACTrieNodeIterator

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 and linear space (proportional to tree size).

func (*MACAddressTrie) Contains added in v1.1.0 

func (trie *MACAddressTrie) Contains(addr *MACAddress) 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 (*MACAddressTrie) DescendingIterator added in v1.1.0 

func (trie *MACAddressTrie) DescendingIterator() MACAddressIterator

DescendingIterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in reverse sorted element order.

func (*MACAddressTrie) ElementContains added in v1.1.0 

func (trie *MACAddressTrie) ElementContains(addr *MACAddress) 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 (*MACAddressTrie) ElementsContainedBy added in v1.1.0 

func (trie *MACAddressTrie) ElementsContainedBy(addr *MACAddress) *MACAddressTrieNode

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 (*MACAddressTrie) ElementsContaining added in v1.1.0 

func (trie *MACAddressTrie) ElementsContaining(addr *MACAddress) *ContainmentPath

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 (*MACAddressTrie) Equal added in v1.1.0 

func (trie *MACAddressTrie) Equal(other *MACAddressTrie) bool

Equal returns whether the given argument is a trie with a set of nodes with the same keys as in this trie

func (*MACAddressTrie) FirstAddedNode added in v1.1.0 

func (trie *MACAddressTrie) FirstAddedNode() *MACAddressTrieNode

FirstAddedNode returns the first (lowest-valued) added node in the trie, or nil if there are no added entries in this tree

func (*MACAddressTrie) FirstNode added in v1.1.0 

func (trie *MACAddressTrie) FirstNode() *MACAddressTrieNode

FirstNode returns the first (lowest-valued) node in the trie or nil if the trie has no nodes

func (*MACAddressTrie) FloorAddedNode added in v1.1.0 

func (trie *MACAddressTrie) FloorAddedNode(addr *MACAddress) *MACAddressTrieNode

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 tree

func (MACAddressTrie) Format added in v1.1.0 

func (trie MACAddressTrie) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*MACAddressTrie) GetAddedNode added in v1.1.0 

func (trie *MACAddressTrie) GetAddedNode(addr *MACAddress) *MACAddressTrieNode

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 (*MACAddressTrie) GetNode added in v1.1.0 

func (trie *MACAddressTrie) GetNode(addr *MACAddress) *MACAddressTrieNode

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 (*MACAddressTrie) GetRoot added in v1.1.0 

func (trie *MACAddressTrie) GetRoot() *MACAddressTrieNode

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 (*MACAddressTrie) HigherAddedNode added in v1.1.0 

func (trie *MACAddressTrie) HigherAddedNode(addr *MACAddress) *MACAddressTrieNode

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 tree

func (*MACAddressTrie) IsEmpty added in v1.1.0 

func (trie *MACAddressTrie) IsEmpty() bool

IsEmpty returns true if there are not any added nodes within this tree

func (*MACAddressTrie) Iterator added in v1.1.0 

func (trie *MACAddressTrie) Iterator() MACAddressIterator

Iterator returns an iterator that iterates through the added prefix blocks and addresses in the trie. The iteration is in sorted element order.

func (*MACAddressTrie) LastAddedNode added in v1.1.0 

func (trie *MACAddressTrie) LastAddedNode() *MACAddressTrieNode

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 tree

func (*MACAddressTrie) LastNode added in v1.1.0 

func (trie *MACAddressTrie) LastNode() *MACAddressTrieNode

LastNode returns the last (highest-valued) node in the trie or nil if the trie has no nodes

func (*MACAddressTrie) LongestPrefixMatch added in v1.1.0 

func (trie *MACAddressTrie) LongestPrefixMatch(addr *MACAddress) *MACAddress

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 (*MACAddressTrie) LongestPrefixMatchNode added in v1.1.0 

func (trie *MACAddressTrie) LongestPrefixMatchNode(addr *MACAddress) *MACAddressTrieNode

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 (*MACAddressTrie) LowerAddedNode added in v1.1.0 

func (trie *MACAddressTrie) LowerAddedNode(addr *MACAddress) *MACAddressTrieNode

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 tree

func (*MACAddressTrie) NodeIterator added in v1.1.0 

func (trie *MACAddressTrie) NodeIterator(forward bool) MACTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes in the trie in forward or reverse tree order.

func (*MACAddressTrie) NodeSize added in v1.1.0 

func (trie *MACAddressTrie) NodeSize() int

NodeSize returns the number of nodes in the tree, which is always more than the number of elements.

func (*MACAddressTrie) Remove added in v1.1.0 

func (trie *MACAddressTrie) Remove(addr *MACAddress) 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.

func (*MACAddressTrie) RemoveElementsContainedBy added in v1.1.0 

func (trie *MACAddressTrie) RemoveElementsContainedBy(addr *MACAddress) *MACAddressTrieNode

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 (*MACAddressTrie) Size added in v1.1.0 

func (trie *MACAddressTrie) 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 (*MACAddressTrie) String added in v1.1.0 

func (trie *MACAddressTrie) String() string

String returns a visual representation of the tree with one node per line.

func (*MACAddressTrie) ToAssociative added in v1.1.0 

func (trie *MACAddressTrie) ToAssociative() *MACAddressAssociativeTrie

ToAssociative converts to the associative representation of this trie

func (*MACAddressTrie) ToBase added in v1.1.0 

func (trie *MACAddressTrie) ToBase() *AddressTrie

ToBase converts to the polymorphic representation of this trie

func (*MACAddressTrie) TreeString added in v1.1.0 

func (trie *MACAddressTrie) 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 MACAddressTrieNode added in v1.1.0 

type MACAddressTrieNode struct {
	// contains filtered or unexported fields
}

MACAddressTrieNode represents a node in a MACAddressTrie.

Trie nodes are created by tries during add operations.

If a trie node is copied, a panic will result when methods that alter the trie are called on the copied node.

Iterator methods allow for traversal of the sub-trie with this node as the root.

If an iterator is advanced following a trie modification that followed the creation of the iterator, the iterator will panic.

func (*MACAddressTrieNode) AllNodeIterator added in v1.1.0 

func (node *MACAddressTrieNode) AllNodeIterator(forward bool) MACTrieNodeIteratorRem

AllNodeIterator returns an iterator that iterates through all the nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*MACAddressTrieNode) AsNewTrie added in v1.1.0 

func (node *MACAddressTrieNode) AsNewTrie() *MACAddressTrie

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 (*MACAddressTrieNode) BlockSizeAllNodeIterator added in v1.1.0 

func (node *MACAddressTrieNode) BlockSizeAllNodeIterator(lowerSubNodeFirst bool) MACTrieNodeIteratorRem

BlockSizeAllNodeIterator returns an iterator that iterates all the nodes, ordered by keys from the largest prefix blocks to the 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 (*MACAddressTrieNode) BlockSizeCachingAllNodeIterator added in v1.1.0 

func (node *MACAddressTrieNode) BlockSizeCachingAllNodeIterator() CachingMACTrieNodeIterator

BlockSizeCachingAllNodeIterator returns an iterator that iterates all nodes, ordered by keys from the largest prefix blocks to the smallest and then to individual addresses, in the sub-trie with this node as the root.

func (*MACAddressTrieNode) BlockSizeNodeIterator added in v1.1.0 

func (node *MACAddressTrieNode) BlockSizeNodeIterator(lowerSubNodeFirst bool) MACTrieNodeIteratorRem

BlockSizeNodeIterator returns an iterator that iterates the added nodes, ordered by keys from the largest prefix blocks to the 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 (*MACAddressTrieNode) CeilingAddedNode added in v1.1.0 

func (node *MACAddressTrieNode) CeilingAddedNode(addr *Address) *MACAddressTrieNode

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 (*MACAddressTrieNode) Clear added in v1.1.0 

func (node *MACAddressTrieNode) Clear()

Clear removes this node and all sub-nodes from the tree, after which isEmpty() will return true.

func (*MACAddressTrieNode) Clone added in v1.1.0 

func (node *MACAddressTrieNode) Clone() *MACAddressTrieNode

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 (*MACAddressTrieNode) CloneTree added in v1.1.0 

func (node *MACAddressTrieNode) CloneTree() *MACAddressTrieNode

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 (*MACAddressTrieNode) Compare added in v1.1.0 

func (node *MACAddressTrieNode) Compare(other *MACAddressTrieNode) int

Compare returns -1, 0 or 1 if this node is less than, equal, or greater than the other, according to the key and the trie order.

func (*MACAddressTrieNode) ContainedFirstAllNodeIterator added in v1.1.0 

func (node *MACAddressTrieNode) ContainedFirstAllNodeIterator(forwardSubNodeOrder bool) MACTrieNodeIterator

ContainedFirstAllNodeIterator returns an iterator that does a post-order binary tree 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 (*MACAddressTrieNode) ContainedFirstIterator added in v1.1.0 

func (node *MACAddressTrieNode) ContainedFirstIterator(forwardSubNodeOrder bool) MACTrieNodeIteratorRem

ContainedFirstIterator returns an iterator that does a post-order binary tree 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 (*MACAddressTrieNode) ContainingFirstAllNodeIterator added in v1.1.0 

func (node *MACAddressTrieNode) ContainingFirstAllNodeIterator(forwardSubNodeOrder bool) CachingMACTrieNodeIterator

ContainingFirstAllNodeIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*MACAddressTrieNode) ContainingFirstIterator added in v1.1.0 

func (node *MACAddressTrieNode) ContainingFirstIterator(forwardSubNodeOrder bool) CachingMACTrieNodeIterator

ContainingFirstIterator returns an iterator that does a pre-order binary tree 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 and linear space (proportional to tree size).

func (*MACAddressTrieNode) Contains added in v1.1.0 

func (node *MACAddressTrieNode) Contains(addr *MACAddress) 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 exists already in the trie, false otherwise.

Use GetAddedNode to get the node for the address rather than just checking for its existence.

func (*MACAddressTrieNode) DescendingIterator added in v1.1.0 

func (node *MACAddressTrieNode) DescendingIterator() MACAddressIterator

DescendingIterator returns an iterator that iterates through the elements of the sub-trie with this node as the root. The iteration is in reverse sorted element order.

func (*MACAddressTrieNode) ElementContains added in v1.1.0 

func (node *MACAddressTrieNode) ElementContains(addr *MACAddress) 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 (*MACAddressTrieNode) ElementsContainedBy added in v1.1.0 

func (node *MACAddressTrieNode) ElementsContainedBy(addr *MACAddress) *MACAddressTrieNode

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 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 (*MACAddressTrieNode) ElementsContaining added in v1.1.0 

func (node *MACAddressTrieNode) ElementsContaining(addr *MACAddress) *ContainmentPath

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 (*MACAddressTrieNode) Equal added in v1.1.0 

func (node *MACAddressTrieNode) Equal(other *MACAddressTrieNode) bool

Equal returns whether the key and mapped value match those of the given node

func (*MACAddressTrieNode) FirstAddedNode added in v1.1.0 

func (node *MACAddressTrieNode) FirstAddedNode() *MACAddressTrieNode

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 tree or sub-trie

func (*MACAddressTrieNode) FirstNode added in v1.1.0 

func (node *MACAddressTrieNode) FirstNode() *MACAddressTrieNode

FirstNode returns the first (the lowest valued) node in the sub-trie originating from this node

func (*MACAddressTrieNode) FloorAddedNode added in v1.1.0 

func (node *MACAddressTrieNode) FloorAddedNode(addr *Address) *MACAddressTrieNode

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 (MACAddressTrieNode) Format added in v1.1.0 

func (node MACAddressTrieNode) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface

func (*MACAddressTrieNode) GetAddedNode added in v1.1.0 

func (node *MACAddressTrieNode) GetAddedNode(addr *MACAddress) *MACAddressTrieNode

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 (*MACAddressTrieNode) GetKey added in v1.1.0 

func (node *MACAddressTrieNode) GetKey() *MACAddress

GetKey gets the key used for placing the node in the tree.

func (*MACAddressTrieNode) GetLowerSubNode added in v1.1.0 

func (node *MACAddressTrieNode) GetLowerSubNode() *MACAddressTrieNode

GetLowerSubNode gets the direct child node whose key is smallest in value

func (*MACAddressTrieNode) GetNode added in v1.1.0 

func (node *MACAddressTrieNode) GetNode(addr *MACAddress) *MACAddressTrieNode

GetNode gets the node in the trie, with this sub-node 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 (*MACAddressTrieNode) GetParent added in v1.1.0 

func (node *MACAddressTrieNode) GetParent() *MACAddressTrieNode

GetParent gets the node from which this node is a direct child node, or nil if this is the root.

func (*MACAddressTrieNode) GetUpperSubNode added in v1.1.0 

func (node *MACAddressTrieNode) GetUpperSubNode() *MACAddressTrieNode

GetUpperSubNode gets the direct child node whose key is largest in value

func (*MACAddressTrieNode) HigherAddedNode added in v1.1.0 

func (node *MACAddressTrieNode) HigherAddedNode(addr *Address) *MACAddressTrieNode

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 (*MACAddressTrieNode) IsAdded added in v1.1.0 

func (node *MACAddressTrieNode) IsAdded() bool

IsAdded returns whether the node was "added". Some binary tree nodes are considered "added" and others are not. Those nodes created for key elements added to the tree 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 tree. 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 (*MACAddressTrieNode) IsEmpty added in v1.1.0 

func (node *MACAddressTrieNode) IsEmpty() bool

IsEmpty returns whether the size is 0

func (*MACAddressTrieNode) IsLeaf added in v1.1.0 

func (node *MACAddressTrieNode) 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-trie with this node as the root.

func (*MACAddressTrieNode) IsRoot added in v1.1.0 

func (node *MACAddressTrieNode) IsRoot() bool

IsRoot returns whether this is the root of the backing tree.

func (*MACAddressTrieNode) Iterator added in v1.1.0 

func (node *MACAddressTrieNode) Iterator() MACAddressIterator

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 (*MACAddressTrieNode) LastAddedNode added in v1.1.0 

func (node *MACAddressTrieNode) LastAddedNode() *MACAddressTrieNode

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 tree or sub-trie

func (*MACAddressTrieNode) LastNode added in v1.1.0 

func (node *MACAddressTrieNode) LastNode() *MACAddressTrieNode

LastNode returns the last (the highest valued) node in the sub-trie originating from this node

func (*MACAddressTrieNode) LongestPrefixMatch added in v1.1.0 

func (node *MACAddressTrieNode) LongestPrefixMatch(addr *MACAddress) *Address

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 (*MACAddressTrieNode) LongestPrefixMatchNode added in v1.1.0 

func (node *MACAddressTrieNode) LongestPrefixMatchNode(addr *MACAddress) *MACAddressTrieNode

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 (*MACAddressTrieNode) LowerAddedNode added in v1.1.0 

func (node *MACAddressTrieNode) LowerAddedNode(addr *Address) *MACAddressTrieNode

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 (*MACAddressTrieNode) NextAddedNode added in v1.1.0 

func (node *MACAddressTrieNode) NextAddedNode() *MACAddressTrieNode

NextAddedNode returns the first added node that follows this node following the tree order

func (*MACAddressTrieNode) NextNode added in v1.1.0 

func (node *MACAddressTrieNode) NextNode() *MACAddressTrieNode

NextNode returns the node that follows this node following the tree order

func (*MACAddressTrieNode) NodeIterator added in v1.1.0 

func (node *MACAddressTrieNode) NodeIterator(forward bool) MACTrieNodeIteratorRem

NodeIterator returns an iterator that iterates through the added nodes of the sub-trie with this node as the root, in forward or reverse tree order.

func (*MACAddressTrieNode) NodeSize added in v1.1.0 

func (node *MACAddressTrieNode) 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 (*MACAddressTrieNode) PreviousAddedNode added in v1.1.0 

func (node *MACAddressTrieNode) PreviousAddedNode() *MACAddressTrieNode

PreviousAddedNode returns the first added node that precedes this node following the tree order

func (*MACAddressTrieNode) PreviousNode added in v1.1.0 

func (node *MACAddressTrieNode) PreviousNode() *MACAddressTrieNode

PreviousNode returns the node that precedes this node following the tree order

func (*MACAddressTrieNode) Remove added in v1.1.0 

func (node *MACAddressTrieNode) 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 (*MACAddressTrieNode) RemoveElementsContainedBy added in v1.1.0 

func (node *MACAddressTrieNode) RemoveElementsContainedBy(addr *MACAddress) *MACAddressTrieNode

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 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 (*MACAddressTrieNode) RemoveNode added in v1.1.0 

func (node *MACAddressTrieNode) RemoveNode(addr *MACAddress) 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.

func (*MACAddressTrieNode) SetAdded added in v1.1.0 

func (node *MACAddressTrieNode) SetAdded()

SetAdded makes this node an added node, which is equivalent to adding the corresponding key to the tree. 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 tree by calling Remove. A non-added node will only remain in the tree if it needs to in the tree.

func (*MACAddressTrieNode) Size added in v1.1.0 

func (node *MACAddressTrieNode) Size() int

Size returns the number of elements in the tree. Only nodes for which IsAdded returns true are counted. When zero is returned, IsEmpty returns true.

func (*MACAddressTrieNode) String added in v1.1.0 

func (node *MACAddressTrieNode) 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 (*MACAddressTrieNode) ToAssociative added in v1.1.0 

func (node *MACAddressTrieNode) ToAssociative() *MACAddressAssociativeTrieNode

ToAssociative converts to the associative trie node representation of this MAC trie node. The node is unchanged, the returned node is the same underlying node.

func (*MACAddressTrieNode) ToBase added in v1.1.0 

func (node *MACAddressTrieNode) ToBase() *AddressTrieNode

ToBase converts to the polymorphic base representation of this MAC trie node. The node is unchanged, the returned node is the same underlying node.

func (*MACAddressTrieNode) TreeEqual added in v1.1.0 

func (node *MACAddressTrieNode) TreeEqual(other *MACAddressTrieNode) bool

TreeEqual returns whether the sub-trie represented by this node as the root node matches the given sub-trie

func (*MACAddressTrieNode) TreeString added in v1.1.0 

func (node *MACAddressTrieNode) 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 MACAssociativeTrieNodeIterator added in v1.1.0 

type MACAssociativeTrieNodeIterator interface {
	HasNext

	Next() *MACAddressAssociativeTrieNode
}

MACAssociativeTrieNodeIterator iterates through a MAC associative address trie, until both Next returns nil and HasNext returns false

type MACAssociativeTrieNodeIteratorRem added in v1.1.0 

type MACAssociativeTrieNodeIteratorRem interface {
	MACAssociativeTrieNodeIterator

	// Remove removes the last iterated element from the underlying trie, and returns that element.
	// If there is no such element, it returns nil.
	Remove() *MACAddressAssociativeTrieNode
}

MACAssociativeTrieNodeIteratorRem iterates through a MAC associative address trie, until both Next returns nil and HasNext returns false

type MACSectionIterator 

type MACSectionIterator interface {
	HasNext

	// Next returns the next address section, or nil if there is none left.
	Next() *MACAddressSection
}

MACSectionIterator iterates through MAC address sections

type MACSegInt 

type MACSegInt = uint8

type MACSegmentIterator 

type MACSegmentIterator interface {
	HasNext

	// Next returns the next MAC address segment, or nil if there is none left.
	Next() *MACAddressSegment
}

MACSegmentIterator iterates through MAC address segments

type MACSegmentValueProvider 

type MACSegmentValueProvider func(segmentIndex int) MACSegInt

func WrappedSegmentValueProviderForMAC 

func WrappedSegmentValueProviderForMAC(f SegmentValueProvider) MACSegmentValueProvider

WrappedSegmentValueProviderForMAC converts the given SegmentValueProvider to a MACSegmentValueProvider Values that do not fit MACSegInt are truncated.

type MACTrieNodeIterator added in v1.1.0 

type MACTrieNodeIterator interface {
	HasNext

	Next() *MACAddressTrieNode
}

MACTrieNodeIterator iterates through a MAC address trie, until both Next returns nil and HasNext returns false

type MACTrieNodeIteratorRem added in v1.1.0 

type MACTrieNodeIteratorRem interface {
	MACTrieNodeIterator

	// Remove removes the last iterated element from the underlying trie, and returns that element.
	// If there is no such element, it returns nil.
	Remove() *MACAddressTrieNode
}

MACTrieNodeIteratorRem iterates through a MAC address trie, until both Next returns nil and HasNext returns false. The iterator also allows you to remove the last visited node.

type Masker 

type Masker interface {
	// GetMaskedLower provides the lowest masked value, which is not necessarily the lowest value masked
	GetMaskedLower(value, maskValue uint64) uint64

	// GetMaskedUpper provides the highest masked value, which is not necessarily the highest value masked
	GetMaskedUpper(upperValue, maskValue uint64) uint64

	// IsSequential returns whether masking all values in the range results in a sequential set of values
	IsSequential() bool
}

func MaskRange 

func MaskRange(value, upperValue, maskValue, maxValue uint64) Masker

type NodeValue added in v1.1.0 

type NodeValue = tree.V

NodeValue represents the value stored with each node in an associative trie.

type ParsedMACAddress 

type ParsedMACAddress struct {
	// contains filtered or unexported fields
}

type Partition 

type Partition struct {
	// contains filtered or unexported fields
}

A Partition is a collection of addresses partitioned from an original address. Much like an iterator, the elements of the partition can be iterated just once, after which it becomes empty.

func PartitionIPWithSingleBlockSize added in v1.1.0 

func PartitionIPWithSingleBlockSize(newAddr *IPAddress) *Partition

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 PartitionIPWithSpanningBlocks added in v1.1.0 

func PartitionIPWithSpanningBlocks(newAddr *IPAddress) *Partition

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) ForEach 

func (p *Partition) ForEach(action func(*IPAddress))

ForEach calls the action with each partition element.

func (*Partition) Iterator 

func (p *Partition) Iterator() IPAddressIterator

Iterator provides an iterator to iterate through each element of the partition.

func (*Partition) PredicateForAny 

func (p *Partition) PredicateForAny(predicate func(*IPAddress) bool) bool

Applies the operation to each element of the partition, returning true if the given predicate returns true for any of the elements.

func (*Partition) PredicateForAnyEarly 

func (p *Partition) PredicateForAnyEarly(predicate func(*IPAddress) bool) bool

Applies the 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) PredicateForEach 

func (p *Partition) PredicateForEach(predicate func(*IPAddress) bool) bool

PredicateForEach applies the operation to each element of the partition, returning true if they all return true, false otherwise

Use IPAddressPredicateAdapter to pass in a function that takes *Address as argument instead.

func (*Partition) PredicateForEachEarly 

func (p *Partition) PredicateForEachEarly(predicate func(*IPAddress) bool) bool

PredicateForEachEarly applies the 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)

Use IPAddressPredicateAdapter to pass in a function that takes *Address as argument instead.

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

A PortNum is the port number for a non-nil Port

func (*PortNum) Compare 

func (p *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 (p *PortNum) Equal(other Port) bool

Equal compares two Port values for equality.

func (*PortNum) Matches 

func (p *PortNum) Matches(other PortInt) bool

Matches compares a Port value with a port number

func (*PortNum) Num 

func (p *PortNum) Num() PortInt

func (*PortNum) String 

func (p *PortNum) String() string

String returns the bit count as a base-10 positive integer string, or "<nil>" if the receiver is a nil pointer

type PrefixBitCount 

type PrefixBitCount uint8

A PrefixBitCount is the count of bits in a non-nil PrefixLen. For arithmetic, you may wish to use BitCount instead, which you can get from a PrefixLen using the Len method.

func (*PrefixBitCount) Compare 

func (p *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 (p *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 (p *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 (p *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 (p *PrefixBitCount) Matches(other BitCount) bool

Matches compares a PrefixLen value with a bit count

func (*PrefixBitCount) String 

func (p *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 PrefixKey added in v1.1.0 

type PrefixKey struct {
	// If true, the prefix length is indicated by PrefixLen.
	// If false, this indicates no prefix length for the associated address or subnet.
	IsPrefixed bool

	// If IsPrefixed is true, this holds the prefix length.
	// Otherwise, this should be zero if you wish that each address has a unique key.
	PrefixLen PrefixBitCount
}

PrefixKey is a representation of a prefix length that is comparable as defined by the language specification. See https://go.dev/ref/spec#Comparison_operators It can be used as a map key. The zero value is the absence of a prefix length.

func (*PrefixKey) Normalize added in v1.1.0 

func (pref *PrefixKey) Normalize()

Normalize normalizes the prefix length. Normalizing a prefix length ensures it is unique for the represented prefix length.

func (*PrefixKey) ToPrefixLen added in v1.1.0 

func (pref *PrefixKey) ToPrefixLen() PrefixLen

ToPrefixLen converts this key to its corresponding prefix length.

type PrefixLen 

type PrefixLen = *PrefixBitCount

A PrefixLen indicates the length of the prefix for an address, section, division grouping, segment, or division. The zero value, which is nil, indicates that there is no prefix length.

func ToPrefixLen added in v1.1.0 

func ToPrefixLen(i int) PrefixLen

ToPrefixLen converts the given int to a prefix length

func ValidatePrefixLenStr 

func ValidatePrefixLenStr(str string, version IPVersion) (prefixLen PrefixLen, err addrerr.AddressStringError)

ValidatePrefixLenStr validates that the string represents a valid prefix length, such as "24". The string should not include a beginning '/' character. If invalid, it returns an error with an appropriate message. You can specify the IP version or IndeterminateIPVersion if unknown. An error is returned if the format is invalid.

type SectionIterator 

type SectionIterator interface {
	HasNext

	// Next returns the next address section, or nil if there is none left.
	Next() *AddressSection
}

SectionIterator iterates through address sections

type SegInt 

type SegInt = uint32 // must be at least uint16 to handle IPv6, at least 32 to handle single segment IPv4, and no larger than 64 because we use bits.TrailingZeros64.  IP address segment code uses bits.TrailingZeros32 and bits.LeadingZeros32, so it cannot be larger than 32.

SegInt is an integer type for holding generic address segment values. It is at least as large as all address segment values: IPv6SegInt, IPv4SegInt, MACSegInt

type SegIntCount 

type SegIntCount = uint64 // must be able to hold: (max value of SegInt) + 1

type SegmentIterator 

type SegmentIterator interface {
	HasNext

	// Next returns the next address segment, or nil if there is none left.
	Next() *AddressSegment
}

SegmentIterator iterates through address segments

type SegmentSequence added in v1.2.0 

type SegmentSequence struct {
	// contains filtered or unexported fields
}

SegmentSequence represents a sequence of consecutive segments with the given length starting from the given segment index.

type SegmentSequenceList added in v1.2.0 

type SegmentSequenceList struct {
	// contains filtered or unexported fields
}

SegmentSequenceList represents a list of SegmentSequence instances.

type SegmentValueProvider 

type SegmentValueProvider func(segmentIndex int) SegInt

SegmentValueProvider provides values for segments. Values that fall outside the segment value type range will be truncated using standard golang integer type conversions https://golang.org/ref/spec#Conversions

func WrappedIPv4SegmentValueProvider 

func WrappedIPv4SegmentValueProvider(f IPv4SegmentValueProvider) SegmentValueProvider

WrappedIPv4SegmentValueProvider converts the given IPv4SegmentValueProvider to a SegmentValueProvider

func WrappedIPv6SegmentValueProvider 

func WrappedIPv6SegmentValueProvider(f IPv6SegmentValueProvider) SegmentValueProvider

WrappedIPv6SegmentValueProvider converts the given IPv6SegmentValueProvider to a SegmentValueProvider

func WrappedMACSegmentValueProvider 

func WrappedMACSegmentValueProvider(f MACSegmentValueProvider) SegmentValueProvider

WrappedMACSegmentValueProvider converts the given MACSegmentValueProvider to a SegmentValueProvider

type SegmentsIterator 

type SegmentsIterator interface {
	HasNext

	// Next returns the next segment as an address division, or nil if there is none left.
	Next() []*AddressDivision
}

SegmentsIterator iterates through segment arrays of addresses and sections

type StandardDivGroupingType 

type StandardDivGroupingType interface {
	AddressDivisionSeries

	// IsAdaptiveZero returns true if the division grouping was originally created as an implicitly zero-valued section or grouping (eg 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, etc
	IsAdaptiveZero() bool

	// CompareSize compares the counts of two division groupings, the number of individual division groupings within.
	//
	// Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one grouping represents more individual groupings than another.
	//
	// CompareSize returns a positive integer if this address division grouping has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.
	CompareSize(StandardDivGroupingType) int

	// ToDivGrouping converts to an AddressDivisionGrouping, a polymorphic type usable with all address sections and division groupings.
	//
	// ToDivGrouping implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToDivGrouping() *AddressDivisionGrouping
}

StandardDivGroupingType represents any standard division grouping (division groupings or address sections where all divisions are 64 bits or less) including AddressSection, IPAddressSection, IPv4AddressSection, IPv6AddressSection, MACAddressSection, and AddressDivisionGrouping

type StandardDivisionType 

type StandardDivisionType interface {
	DivisionType

	// ToDiv converts to an AddressDivision, a polymorphic type usable with all address segments and divisions.
	//
	// ToDiv implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.
	ToDiv() *AddressDivision
}

Represents any standard address division, which is a division of size 64 bits or less. All can be converted to/from AddressDivision

type StringIterator 

type StringIterator interface {
	HasNext
	Next() string
}

StringIterator iterates through a number of strings

func ParseDelimitedSegments 

func ParseDelimitedSegments(str string) StringIterator

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 WrappedAddress 

type WrappedAddress struct {
	*Address
}

WrappedAddress is the implementation of ExtendedSegmentSeries for addresses

func (WrappedAddress) AdjustPrefixLen 

func (addr WrappedAddress) AdjustPrefixLen(prefixLen BitCount) ExtendedSegmentSeries

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (WrappedAddress) AdjustPrefixLenZeroed 

func (addr WrappedAddress) AdjustPrefixLenZeroed(prefixLen BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

func (WrappedAddress) AssignMinPrefixForBlock 

func (addr WrappedAddress) AssignMinPrefixForBlock() ExtendedSegmentSeries

AssignMinPrefixForBlock returns an equivalent series, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this series.

In other words, this method assigns a prefix length to this series matching the largest prefix block in this series.

func (WrappedAddress) AssignPrefixForSingleBlock 

func (addr WrappedAddress) AssignPrefixForSingleBlock() ExtendedSegmentSeries

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this series. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such series - it is required that the range of values match the range of a prefix block. If there is no such series, then nil is returned.

func (WrappedAddress) CompareSize 

func (addr WrappedAddress) CompareSize(other ExtendedSegmentSeries) int

CompareSize compares the counts of two address series, the number of individual series represented in each.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one series represents more individual address series than another.

CompareSize returns a positive integer if this address series has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.

func (WrappedAddress) Contains 

func (addr WrappedAddress) Contains(other ExtendedSegmentSeries) bool

Contains returns whether this is same type and version as the given address series and whether it contains all values in the given series.

Series must also have the same number of segments to be comparable, otherwise false is returned.

func (WrappedAddress) ContainsPrefixBlock 

func (addr WrappedAddress) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the range of this address or subnet contains the block of addresses for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock() to determine the smallest prefix length for which this method returns true.

func (WrappedAddress) ContainsSinglePrefixBlock 

func (addr WrappedAddress) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether this address contains a single prefix block for the given prefix length.

This means there is only one prefix value for the given prefix length, and it also contains the full prefix block for that prefix, all addresses with that prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (WrappedAddress) Equal 

func (addr WrappedAddress) Equal(other ExtendedSegmentSeries) bool

Equal returns whether the given address series is equal to this address series. Two address series are equal if they represent the same set of series. Both must be equal addresses.

func (WrappedAddress) GetBitCount 

func (addr WrappedAddress) GetBitCount() BitCount

GetBitCount returns the number of bits comprising this address, or each address in the range if a subnet.

func (WrappedAddress) GetBitsPerSegment 

func (addr WrappedAddress) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this address or subnet. Segments in the same address are equal length.

func (WrappedAddress) GetBlockCount 

func (addr WrappedAddress) GetBlockCount(segments int) *big.Int

GetBlockCount returns the count of distinct values in the given number of initial (more significant) segments.

func (WrappedAddress) GetByteCount 

func (addr WrappedAddress) GetByteCount() int

GetByteCount returns the number of bytes required for this address, or each address in the range if a subnet.

func (WrappedAddress) GetBytesPerSegment 

func (addr WrappedAddress) GetBytesPerSegment() int

GetBytesPerSegment returns the number of bytes comprising each segment in this address or subnet. Segments in the same address are equal length.

func (WrappedAddress) GetLower 

func (addr WrappedAddress) GetLower() ExtendedSegmentSeries

GetLower returns the series in the range with the lowest numeric value, which will be the same series if it represents a single value.

func (WrappedAddress) GetMinPrefixLenForBlock 

func (addr WrappedAddress) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this includes the block of addresses for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this represents just a single address, returns the bit length of this address.

func (WrappedAddress) GetPrefixCount 

func (addr WrappedAddress) GetPrefixCount() *big.Int

GetPrefixCount returns the count of prefixes in this address or subnet.

The prefix length is given by GetPrefixLen.

If this has a non-nil prefix length, returns the count of the range of values in the prefix.

If this has a nil prefix length, returns the same value as GetCount()

func (WrappedAddress) GetPrefixCountLen 

func (addr WrappedAddress) GetPrefixCountLen(prefixLen BitCount) *big.Int

GetPrefixCountLen returns the count of prefixes in this address or subnet for the given prefix length.

If not a subnet of multiple addresses, or a subnet with just single prefix of the given length, returns 1.

func (WrappedAddress) GetPrefixLen 

func (addr WrappedAddress) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part (most significant bits) of the address that comprise the prefix.

A prefix is a part of the address that is not specific to that address but common amongst a group of addresses, such as a CIDR prefix block subnet.

For IP addresses, the prefix is explicitly defined when the address is created. For example, 1.2.0.0/16 has a prefix length of 16, while 1.2.*.* has no prefix length, even though they both represent the same set of addresses and are considered equal. Prefixes can be considered variable for a given IP address and can depend on routing.

The methods GetMinPrefixLenForBlock and GetPrefixLenForSingleBlock can help you to obtain or define a prefix length if one does not exist already. The method ToPrefixBlockLen allows you to create the subnet consisting of the block of addresses for any given prefix length.

For MAC addresses, the prefix is initially inferred from the range, so 1:2:3:*:*:* has a prefix length of 24. Addresses derived from the original may retain the original prefix length regardless of their range.

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 null 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 prefix lengths for which ContainsPrefixBlock returns true.

func (WrappedAddress) IsSequential 

func (addr WrappedAddress) IsSequential() bool

IsSequential returns whether the address or subnet represents a range of addresses that are sequential.

Generally, for a subnet this means that any segment covering a range of values must be followed by segments that are full range, covering all values.

Individual addresses are sequential and CIDR prefix blocks are sequential. The subnet 1.2.3-4.5 is not sequential, since the two addresses it represents, 1.2.3.5 and 1.2.4.5, are not (1.2.3.6 is in-between the two but not in the subnet).

With any IP address subnet, you can use SequentialBlockIterator to convert any subnet to a collection of sequential subnets.

func (WrappedAddress) IsSinglePrefixBlock 

func (addr WrappedAddress) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the address range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock() except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

For instance, 1.*.*.* /16 return false for this method and returns true for 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() ExtendedSegmentSeriesIterator

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() ExtendedSegmentSeriesIterator

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() ExtendedSegmentSeriesIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this series, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this series.

If the series has no prefix length, then this is equivalent to Iterator.

func (WrappedAddress) ReverseBits 

func (addr WrappedAddress) ReverseBits(perByte bool) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBits returns a new segment series with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (WrappedAddress) ReverseBytes 

func (addr WrappedAddress) ReverseBytes() (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBytes returns a new segment series with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (WrappedAddress) ReverseSegments 

func (addr WrappedAddress) ReverseSegments() ExtendedSegmentSeries

ReverseSegments returns a new series with the segments reversed.

func (WrappedAddress) SetPrefixLen 

func (addr WrappedAddress) SetPrefixLen(prefixLen BitCount) ExtendedSegmentSeries

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

func (WrappedAddress) SetPrefixLenZeroed 

func (addr WrappedAddress) SetPrefixLenZeroed(prefixLen BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (ie bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedAddress) ToBlock 

func (addr WrappedAddress) ToBlock(segmentIndex int, lower, upper SegInt) ExtendedSegmentSeries

ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (WrappedAddress) ToIP 

func (addr WrappedAddress) ToIP() IPAddressSegmentSeries

ToIP converts to an IP address if this originated as IPv4 or IPv6, or an implicitly zero-valued IP. If not, ToIP returns nil.

func (WrappedAddress) ToIPv4 

func (addr WrappedAddress) ToIPv4() IPv4AddressSegmentSeries

ToIPv4 converts to an IPv4AddressSegmentSeries if this series originated as an IPv4 series. If not, ToIPv4 returns nil.

ToIPv4 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddress) ToIPv6 

func (addr WrappedAddress) ToIPv6() IPv6AddressSegmentSeries

ToIPv6 converts to an IPv4AddressSegmentSeries if this series originated as an IPv6 series. If not, ToIPv6 returns nil.

ToIPv6 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddress) ToMAC 

func (addr WrappedAddress) ToMAC() MACAddressSegmentSeries

ToMAC converts to a MACAddressSegmentSeries if this series originated as a MAC series. If not, ToMAC returns nil.

ToMAC implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddress) ToPrefixBlock 

func (addr WrappedAddress) ToPrefixBlock() ExtendedSegmentSeries

ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values. The series will be the block of all series with the same prefix.

If this series has no prefix, this series is returned.

func (WrappedAddress) ToPrefixBlockLen added in v1.2.0 

func (addr WrappedAddress) ToPrefixBlockLen(prefLen BitCount) ExtendedSegmentSeries

ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values. The returned series will be the block of all series with the same prefix.

func (WrappedAddress) Unwrap 

func (addr WrappedAddress) Unwrap() AddressSegmentSeries

Unwrap returns the wrapped address as an interface, AddressSegmentSeries

func (WrappedAddress) WithoutPrefixLen 

func (addr WrappedAddress) WithoutPrefixLen() ExtendedSegmentSeries

WithoutPrefixLen provides the same address series but with no prefix length. The values remain unchanged.

type WrappedAddressSection 

type WrappedAddressSection struct {
	*AddressSection
}

WrappedAddress is the implementation of ExtendedSegmentSeries for address sections

func (WrappedAddressSection) AdjustPrefixLen 

func (section WrappedAddressSection) AdjustPrefixLen(adjustment BitCount) ExtendedSegmentSeries

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (WrappedAddressSection) AdjustPrefixLenZeroed 

func (section WrappedAddressSection) AdjustPrefixLenZeroed(adjustment BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

func (WrappedAddressSection) AssignMinPrefixForBlock 

func (section WrappedAddressSection) AssignMinPrefixForBlock() ExtendedSegmentSeries

AssignMinPrefixForBlock returns an equivalent series, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this series.

In other words, this method assigns a prefix length to this series matching the largest prefix block in this series.

func (WrappedAddressSection) AssignPrefixForSingleBlock 

func (section WrappedAddressSection) AssignPrefixForSingleBlock() ExtendedSegmentSeries

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this series. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such series - it is required that the range of values match the range of a prefix block. If there is no such series, then nil is returned.

func (WrappedAddressSection) Bytes 

func (section WrappedAddressSection) Bytes() []byte

Bytes returns the lowest individual address section in this address section as a byte slice

func (WrappedAddressSection) CompareSize 

func (section WrappedAddressSection) CompareSize(other ExtendedSegmentSeries) int

CompareSize compares the counts of two address series, the number of individual series represented in each.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one series represents more individual address series than another.

CompareSize returns a positive integer if this address series has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.

func (WrappedAddressSection) Contains 

func (section WrappedAddressSection) Contains(other ExtendedSegmentSeries) bool

Contains returns whether this is same type and version as the given address series and whether it contains all values in the given series.

Series must also have the same number of segments to be comparable, otherwise false is returned.

func (WrappedAddressSection) ContainsPrefixBlock 

func (section WrappedAddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (WrappedAddressSection) ContainsSinglePrefixBlock 

func (section WrappedAddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this grouping contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (WrappedAddressSection) CopyBytes 

func (section WrappedAddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (WrappedAddressSection) CopyUpperBytes 

func (section WrappedAddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (WrappedAddressSection) Equal 

func (section WrappedAddressSection) Equal(other ExtendedSegmentSeries) bool

Equal returns whether the given address series is equal to this address series. Two address series are equal if they represent the same set of series. Both must be equal sections.

func (WrappedAddressSection) ForEachSegment added in v1.2.0 

func (section WrappedAddressSection) ForEachSegment(consumer func(segmentIndex int, segment *AddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true Returns the number of visited segments.

func (WrappedAddressSection) Format 

func (section WrappedAddressSection) Format(state fmt.State, verb rune)

Format implements fmt.Formatter interface. It accepts the formats 'v' for the default address and section format (either the normalized or canonical string), 's' (string) for the same, 'b' (binary), 'o' (octal with 0 prefix), 'O' (octal with 0o prefix), 'd' (decimal), 'x' (lowercase hexadecimal), and 'X' (uppercase hexadecimal). Also supported are some of fmt's format flags for integral types. Sign control is not supported since addresses and sections are never negative. '#' for an alternate format is supported, which is leading zero for octal and for hexadecimal, 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

func (WrappedAddressSection) GetLeadingBitCount added in v1.1.0 

func (section WrappedAddressSection) GetLeadingBitCount(ones bool) BitCount

GetLeadingBitCount returns the number of consecutive leading one or zero bits. If ones is true, returns the number of consecutive leading one bits. Otherwise, returns the number of consecutive leading zero bits.

This method applies to the lower value of the range if this section represents multiple values.

func (WrappedAddressSection) GetLower 

func (section WrappedAddressSection) GetLower() ExtendedSegmentSeries

GetLower returns the series in the range with the lowest numeric value, which will be the same series if it represents a single value.

func (WrappedAddressSection) GetMaxSegmentValue 

func (section WrappedAddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (WrappedAddressSection) GetMinPrefixLenForBlock 

func (section WrappedAddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (WrappedAddressSection) GetPrefixLen 

func (section WrappedAddressSection) GetPrefixLen() PrefixLen

GetPrefixLen returns the prefix length, or nil if there is no prefix length.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (WrappedAddressSection) GetPrefixLenForSingleBlock 

func (section WrappedAddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (WrappedAddressSection) GetSection 

func (section WrappedAddressSection) GetSection() *AddressSection

GetSection returns the backing section for this series, comprising all segments.

func (WrappedAddressSection) GetSegment 

func (section WrappedAddressSection) GetSegment(index int) *AddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or index larger than the segment count.

func (WrappedAddressSection) GetSegmentCount 

func (section WrappedAddressSection) GetSegmentCount() int

func (WrappedAddressSection) GetSequentialBlockCount 

func (section WrappedAddressSection) GetSequentialBlockCount() *big.Int

GetSequentialBlockCount provides the count of elements from the sequential block iterator, the minimal number of sequential address sections that comprise this address section

func (WrappedAddressSection) GetSequentialBlockIndex 

func (section WrappedAddressSection) GetSequentialBlockIndex() int

GetSequentialBlockIndex gets the minimal segment index for which all following segments are full-range blocks.

The segment at this index is not a full-range block itself, unless all segments are full-range. The segment at this index and all following segments form a sequential range. For the full address section to be sequential, the preceding segments must be single-valued.

func (WrappedAddressSection) GetTrailingBitCount added in v1.1.0 

func (section WrappedAddressSection) GetTrailingBitCount(ones bool) BitCount

GetTrailingBitCount returns the number of consecutive trailing one or zero bits. If ones is true, returns the number of consecutive trailing zero bits. Otherwise, returns the number of consecutive trailing one bits.

This method applies to the lower value of the range if this section represents multiple values.

func (WrappedAddressSection) GetUpper 

func (section WrappedAddressSection) GetUpper() ExtendedSegmentSeries

GetUpper returns the series in the range with the highest numeric value, which will be the same series if it represents a single value.

func (WrappedAddressSection) GetUpperValue 

func (section WrappedAddressSection) GetUpperValue() *big.Int

GetUpperValue returns the highest individual address section in this address section as an integer value

func (WrappedAddressSection) GetValue 

func (section WrappedAddressSection) GetValue() *big.Int

GetValue returns the lowest individual address section in this address section as an integer value

func (WrappedAddressSection) IncludesMax 

func (section WrappedAddressSection) IncludesMax() bool

IncludesMax returns whether this section includes the max value, the value whose bits are all ones, within its range

func (WrappedAddressSection) IncludesZero 

func (section WrappedAddressSection) IncludesZero() bool

IncludesZero returns whether this section includes the value of zero within its range

func (WrappedAddressSection) Increment 

func (section WrappedAddressSection) Increment(i int64) ExtendedSegmentSeries

Increment returns the item that is the given increment upwards into the range, with the increment of 0 returning the first in the range.

If the increment i matches or exceeds the range count c, then i - c + 1 is added to the upper item of the range. An increment matching the count gives you the item just above the highest in the range.

If the increment is negative, it is added to the lowest of the range. To get the item just below the lowest of the range, use the increment -1.

If this represents just a single value, the item is simply incremented by the given increment, positive or negative.

If this item represents multiple values, a positive increment i is equivalent i + 1 values from the iterator and beyond. For instance, a increment of 0 is the first value from the iterator, an increment of 1 is the second value from the iterator, and so on. An increment of a negative value added to the count is equivalent to the same number of iterator values preceding the last value of the iterator. For instance, an increment of count - 1 is the last value from the iterator, an increment of count - 2 is the second last value, and so on.

On overflow or underflow, Increment returns nil.

func (WrappedAddressSection) IncrementBoundary 

func (section WrappedAddressSection) IncrementBoundary(i int64) ExtendedSegmentSeries

IncrementBoundary returns the item that is the given increment from the range boundaries of this item.

If the given increment is positive, adds the value to the highest (GetUpper) in the range to produce a new item. If the given increment is negative, adds the value to the lowest (GetLower) in the range to produce a new item. If the increment is zero, returns this.

If this represents just a single value, this item is simply incremented by the given increment value, positive or negative.

On overflow or underflow, IncrementBoundary returns nil.

func (WrappedAddressSection) IsFullRange 

func (section WrappedAddressSection) IsFullRange() bool

IsFullRange returns whether this address item represents all possible values attainable by an address item of this type.

This is true if and only if both IncludesZero and IncludesMax return true.

func (WrappedAddressSection) IsMax 

func (section WrappedAddressSection) IsMax() bool

IsMax returns whether this section matches exactly the maximum possible value, the value whose bits are all ones

func (WrappedAddressSection) IsOneBit 

func (section WrappedAddressSection) IsOneBit(prefixBitIndex BitCount) bool

IsOneBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the most significant bit. IsOneBit will panic if bitIndex < 0, 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() ExtendedSegmentSeriesIterator

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() ExtendedSegmentSeriesIterator

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() ExtendedSegmentSeriesIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this series, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this series.

If the series has no prefix length, then this is equivalent to Iterator.

func (WrappedAddressSection) ReverseBits 

func (section WrappedAddressSection) ReverseBits(perByte bool) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBits returns a new segment series with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (WrappedAddressSection) ReverseBytes 

func (section WrappedAddressSection) ReverseBytes() (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBytes returns a new segment series with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (WrappedAddressSection) ReverseSegments 

func (section WrappedAddressSection) ReverseSegments() ExtendedSegmentSeries

ReverseSegments returns a new series with the segments reversed.

func (WrappedAddressSection) SetPrefixLen 

func (section WrappedAddressSection) SetPrefixLen(prefixLen BitCount) ExtendedSegmentSeries

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

func (WrappedAddressSection) SetPrefixLenZeroed 

func (section WrappedAddressSection) SetPrefixLenZeroed(prefixLen BitCount) (ExtendedSegmentSeries, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (ie bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedAddressSection) TestBit 

func (section WrappedAddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (WrappedAddressSection) ToBlock 

func (section WrappedAddressSection) ToBlock(segmentIndex int, lower, upper SegInt) ExtendedSegmentSeries

ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (WrappedAddressSection) ToIP 

func (section WrappedAddressSection) ToIP() IPAddressSegmentSeries

ToIP converts to an IP address section if this originated as IPv4 or IPv6, or an implicitly zero-valued IP. If not, ToIP returns nil.

func (WrappedAddressSection) ToIPv4 

func (section WrappedAddressSection) ToIPv4() IPv4AddressSegmentSeries

ToIPv4 converts to an IPv4AddressSegmentSeries if this series originated as an IPv4 series. If not, ToIPv4 returns nil.

ToIPv4 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddressSection) ToIPv6 

func (section WrappedAddressSection) ToIPv6() IPv6AddressSegmentSeries

ToIPv6 converts to an IPv4AddressSegmentSeries if this series originated as an IPv6 series. If not, ToIPv6 returns nil.

ToIPv6 implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddressSection) ToMAC 

func (section WrappedAddressSection) ToMAC() MACAddressSegmentSeries

ToMAC converts to a MACAddressSegmentSeries if this series originated as a MAC series. If not, ToMAC returns nil.

ToMAC implementations can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedAddressSection) ToPrefixBlock 

func (section WrappedAddressSection) ToPrefixBlock() ExtendedSegmentSeries

ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values. The series will be the block of all series with the same prefix.

If this series has no prefix, this series is returned.

func (WrappedAddressSection) ToPrefixBlockLen added in v1.2.0 

func (section WrappedAddressSection) ToPrefixBlockLen(prefLen BitCount) ExtendedSegmentSeries

ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values. The returned series will be the block of all series with the same prefix.

func (WrappedAddressSection) Unwrap 

func (section WrappedAddressSection) Unwrap() AddressSegmentSeries

Unwrap returns the wrapped address section as an interface, AddressSegmentSeries

func (WrappedAddressSection) UpperBytes 

func (section WrappedAddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice

func (WrappedAddressSection) WithoutPrefixLen 

func (section WrappedAddressSection) WithoutPrefixLen() ExtendedSegmentSeries

WithoutPrefixLen provides the same address series but with no prefix length. The values remain unchanged.

type WrappedHostName 

type WrappedHostName struct {
	*HostName
}

WrappedIPAddressString wraps a HostName to get an ExtendedIdentifierString

func (WrappedHostName) GetAddress 

func (w WrappedHostName) GetAddress() AddressType

GetAddress returns the identified address or nil if none

func (WrappedHostName) ToAddress 

func (w WrappedHostName) ToAddress() (AddressType, error)

ToAddress returns the identified address or an error

func (WrappedHostName) Unwrap 

func (w WrappedHostName) Unwrap() HostIdentifierString

Unwrap returns the wrapped HostName as an interface, HostIdentifierString

type WrappedIPAddress 

type WrappedIPAddress struct {
	*IPAddress
}

WrappedAddress is the implementation of ExtendedIPSegmentSeries for IP addresses

func (WrappedIPAddress) AdjustPrefixLen 

func (addr WrappedIPAddress) AdjustPrefixLen(prefixLen BitCount) ExtendedIPSegmentSeries

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (WrappedIPAddress) AdjustPrefixLenZeroed 

func (addr WrappedIPAddress) AdjustPrefixLenZeroed(prefixLen BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedIPAddress) AssignMinPrefixForBlock 

func (addr WrappedIPAddress) AssignMinPrefixForBlock() ExtendedIPSegmentSeries

AssignMinPrefixForBlock returns an equivalent series, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this series.

In other words, this method assigns a prefix length to this series matching the largest prefix block in this series.

func (WrappedIPAddress) AssignPrefixForSingleBlock 

func (addr WrappedIPAddress) AssignPrefixForSingleBlock() ExtendedIPSegmentSeries

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this series. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such series - it is required that the range of values match the range of a prefix block. If there is no such series, then nil is returned.

func (WrappedIPAddress) BlockIterator 

func (addr WrappedIPAddress) BlockIterator(segmentCount int) ExtendedIPSegmentSeriesIterator

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) CompareSize 

func (addr WrappedIPAddress) CompareSize(other ExtendedIPSegmentSeries) int

CompareSize compares the counts of two address series, the number of individual series represented in each.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one series represents more individual address series than another.

CompareSize returns a positive integer if this address series has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.

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 1s in the network section and then all 0s in the host section. A CIDR host mask is an address with all 0s in the network section and then all 1s 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 null 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 "1.2-3.4.5-6", the series "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 prefix lengths 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 return false for this method and returns true for 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() ExtendedIPSegmentSeriesIterator

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() ExtendedIPSegmentSeriesIterator

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() ExtendedIPSegmentSeriesIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this series, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this series.

If the series has no prefix length, then this is equivalent to Iterator.

func (WrappedIPAddress) ReverseBits 

func (addr WrappedIPAddress) ReverseBits(perByte bool) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBits returns a new segment series with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (WrappedIPAddress) ReverseBytes 

func (addr WrappedIPAddress) ReverseBytes() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBytes returns a new segment series with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (WrappedIPAddress) ReverseSegments 

func (addr WrappedIPAddress) ReverseSegments() ExtendedIPSegmentSeries

ReverseSegments returns a new series with the segments reversed.

func (WrappedIPAddress) SequentialBlockIterator 

func (addr WrappedIPAddress) SequentialBlockIterator() ExtendedIPSegmentSeriesIterator

SequentialBlockIterator iterates through the sequential series that make up this series.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

Use GetSequentialBlockCount to get the number of iterated elements.

func (WrappedIPAddress) SetPrefixLen 

func (addr WrappedIPAddress) SetPrefixLen(prefixLen BitCount) ExtendedIPSegmentSeries

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

func (WrappedIPAddress) SetPrefixLenZeroed 

func (addr WrappedIPAddress) SetPrefixLenZeroed(prefixLen BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (ie bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedIPAddress) SpanWithPrefixBlocks 

func (addr WrappedIPAddress) SpanWithPrefixBlocks() []ExtendedIPSegmentSeries

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual series as this subnet.

func (WrappedIPAddress) SpanWithSequentialBlocks 

func (addr WrappedIPAddress) SpanWithSequentialBlocks() []ExtendedIPSegmentSeries

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of individual addresses as this subnet.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

func (WrappedIPAddress) ToBlock 

func (addr WrappedIPAddress) ToBlock(segmentIndex int, lower, upper SegInt) ExtendedIPSegmentSeries

ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (WrappedIPAddress) ToIPv4 

func (addr WrappedIPAddress) ToIPv4() IPv4AddressSegmentSeries

ToIPv4 converts to an IPv4AddressSegmentSeries if this address originated as an IPv4 section. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedIPAddress) ToIPv6 

func (addr WrappedIPAddress) ToIPv6() IPv6AddressSegmentSeries

ToIPv6 converts to an IPv6AddressSegmentSeries if this address originated as an IPv6 section. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedIPAddress) ToMaxHost 

func (addr WrappedIPAddress) ToMaxHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToMaxHost converts the subnet to one in which all individual addresses have a host of all one-bits, the max value, the host being the bits following the prefix length. If the subnet has no prefix length, then it returns an all-ones address, the max address.

The returned series will have the same prefix length.

For instance, the max host of 1.2.3.4/16 gives the broadcast address 1.2.255.255/16.

This returns an error if the series is a range which cannot be converted to a range in which all individual elements have max hosts, because the conversion results in a series segment that is not a sequential range of values.

func (WrappedIPAddress) ToMaxHostLen 

func (addr WrappedIPAddress) ToMaxHostLen(bitCount BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address or subnet to one in which all individual addresses have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this address or subnet has the same prefix length, then the resulting one will too, otherwise the resulting series will have no prefix length.

For instance, the zero host of 1.2.3.4 for the prefix length 16 is the address 1.2.255.255.

This returns an error if the address or subnet is a range which cannot be converted to a range in which all individual addresses have max hosts, because the conversion results in a series segment that is not a sequential range of values.

func (WrappedIPAddress) ToPrefixBlock 

func (addr WrappedIPAddress) ToPrefixBlock() ExtendedIPSegmentSeries

ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values. The series will be the block of all series with the same prefix.

If this series has no prefix, this series is returned.

func (WrappedIPAddress) ToPrefixBlockLen 

func (addr WrappedIPAddress) ToPrefixBlockLen(bitCount BitCount) ExtendedIPSegmentSeries

ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values. The returned series will be the block of all series with the same prefix.

func (WrappedIPAddress) ToZeroHost 

func (addr WrappedIPAddress) ToZeroHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToZeroHost converts the subnet to one in which all individual addresses have a host of zero, the host being the bits following the prefix length. If the subnet has no prefix length, then it returns an all-zero series.

The returned series will have the same prefix length.

For instance, the zero host of 1.2.3.4/16 is the individual address 1.2.0.0/16.

This returns an error if the series is a range which cannot be converted to a range in which all individual elements have zero hosts, because the conversion results in a series segment that is not a sequential range of values.

func (WrappedIPAddress) ToZeroHostLen 

func (addr WrappedIPAddress) ToZeroHostLen(bitCount BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the subnet to one in which all individual addresses have a host of zero, the host being the bits following the given prefix length. If this address has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.

This returns an error if the subnet is a range which cannot be converted to a range in which all addresses have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (WrappedIPAddress) ToZeroNetwork 

func (addr WrappedIPAddress) ToZeroNetwork() ExtendedIPSegmentSeries

ToZeroNetwork converts the address or subnet to one in which all individual addresses have a network of zero, the network being the bits within the prefix length. If the address or subnet has no prefix length, then it returns an all-zero address.

The returned address or subnet will have the same prefix length.

func (WrappedIPAddress) Unwrap 

func (addr WrappedIPAddress) Unwrap() IPAddressSegmentSeries

Unwrap returns the wrapped address as an interface, IPAddressSegmentSeries

func (WrappedIPAddress) WithoutPrefixLen 

func (addr WrappedIPAddress) WithoutPrefixLen() ExtendedIPSegmentSeries

WithoutPrefixLen provides the same address series but with no prefix length. The values remain unchanged.

type WrappedIPAddressIterator added in v1.2.0 

type WrappedIPAddressIterator struct {
	IPAddressIterator
}

WrappedIPAddressIterator converts an IP address iterator to an address iterator

func (WrappedIPAddressIterator) Next added in v1.2.0 

func (iter WrappedIPAddressIterator) Next() *Address

type WrappedIPAddressSection 

type WrappedIPAddressSection struct {
	*IPAddressSection
}

WrappedAddress is the implementation of ExtendedIPSegmentSeries for IP address sections

func (WrappedIPAddressSection) AdjustPrefixLen 

func (section WrappedIPAddressSection) AdjustPrefixLen(prefixLen BitCount) ExtendedIPSegmentSeries

AdjustPrefixLen increases or decreases the prefix length by the given increment.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

func (WrappedIPAddressSection) AdjustPrefixLenZeroed 

func (section WrappedIPAddressSection) AdjustPrefixLenZeroed(prefixLen BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

AdjustPrefixLenZeroed increases or decreases the prefix length by the given increment while zeroing out the bits that have moved into or outside the prefix.

A prefix length will not be adjusted lower than zero or beyond the bit length of the series.

If this series has no prefix length, then the prefix length will be set to the adjustment if positive, or it will be set to the adjustment added to the bit count if negative.

When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedIPAddressSection) AssignMinPrefixForBlock 

func (section WrappedIPAddressSection) AssignMinPrefixForBlock() ExtendedIPSegmentSeries

AssignMinPrefixForBlock returns an equivalent series, assigned the smallest prefix length possible, such that the prefix block for that prefix length is in this series.

In other words, this method assigns a prefix length to this series matching the largest prefix block in this series.

func (WrappedIPAddressSection) AssignPrefixForSingleBlock 

func (section WrappedIPAddressSection) AssignPrefixForSingleBlock() ExtendedIPSegmentSeries

AssignPrefixForSingleBlock returns the equivalent prefix block that matches exactly the range of values in this series. The returned block will have an assigned prefix length indicating the prefix length for the block.

There may be no such series - it is required that the range of values match the range of a prefix block. If there is no such series, then nil is returned.

func (WrappedIPAddressSection) BlockIterator 

func (section WrappedIPAddressSection) BlockIterator(segmentCount int) ExtendedIPSegmentSeriesIterator

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) CompareSize 

func (section WrappedIPAddressSection) CompareSize(other ExtendedIPSegmentSeries) int

CompareSize compares the counts of two address series, the number of individual series represented in each.

Rather than calculating counts with GetCount, there can be more efficient ways of comparing whether one series represents more individual address series than another.

CompareSize returns a positive integer if this address series has a larger count than the one given, 0 if they are the same, or a negative integer if the other has a larger count.

func (WrappedIPAddressSection) Contains 

func (section WrappedIPAddressSection) Contains(other ExtendedIPSegmentSeries) bool

Contains returns whether this is same type and version as the given address series and whether it contains all values in the given series.

Series must also have the same number of segments to be comparable, otherwise false is returned.

func (WrappedIPAddressSection) ContainsPrefixBlock 

func (section WrappedIPAddressSection) ContainsPrefixBlock(prefixLen BitCount) bool

ContainsPrefixBlock returns whether the values of this item contains the block of values for the given prefix length.

Unlike ContainsSinglePrefixBlock, whether there are multiple prefix values in this item for the given prefix length makes no difference.

Use GetMinPrefixLenForBlock to determine the smallest prefix length for which this method returns true.

func (WrappedIPAddressSection) ContainsSinglePrefixBlock 

func (section WrappedIPAddressSection) ContainsSinglePrefixBlock(prefixLen BitCount) bool

ContainsSinglePrefixBlock returns whether the values of this section contains a single prefix block for the given prefix length.

This means there is only one prefix of the given length in this item, and this item contains the prefix block for that given prefix.

Use GetPrefixLenForSingleBlock to determine whether there is a prefix length for which this method returns true.

func (WrappedIPAddressSection) CopyBytes 

func (section WrappedIPAddressSection) CopyBytes(bytes []byte) []byte

CopyBytes copies the value of the lowest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (WrappedIPAddressSection) CopyUpperBytes 

func (section WrappedIPAddressSection) CopyUpperBytes(bytes []byte) []byte

CopyUpperBytes copies the value of the highest individual address section in the section into a byte slice.

If the value can fit in the given slice, the value is copied into that slice and a length-adjusted sub-slice is returned. Otherwise, a new slice is created and returned with the value.

func (WrappedIPAddressSection) CoverWithPrefixBlock 

func (section WrappedIPAddressSection) CoverWithPrefixBlock() ExtendedIPSegmentSeries

CoverWithPrefixBlock returns the minimal-size prefix block that covers all the individual address sections in this section. The resulting block will have a larger count than this, unless this section is already a prefix block.

func (WrappedIPAddressSection) Equal 

func (section WrappedIPAddressSection) Equal(other ExtendedIPSegmentSeries) bool

Equal returns whether the given address series is equal to this address series. Two address series are equal if they represent the same set of series. Both must be equal sections.

func (WrappedIPAddressSection) ForEachSegment added in v1.2.0 

func (section WrappedIPAddressSection) ForEachSegment(consumer func(segmentIndex int, segment *IPAddressSegment) (stop bool)) int

ForEachSegment visits each segment in order from most-significant to least, the most significant with index 0, calling the given function for each, terminating early if the function returns true Returns the number of visited segments.

func (WrappedIPAddressSection) GetBitCount 

func (section WrappedIPAddressSection) GetBitCount() BitCount

GetBitCount returns the number of bits in each value comprising this address item

func (WrappedIPAddressSection) GetBitsPerSegment 

func (section WrappedIPAddressSection) GetBitsPerSegment() BitCount

GetBitsPerSegment returns the number of bits comprising each segment in this section. Segments in the same address section are equal length.

func (WrappedIPAddressSection) GetBlockMaskPrefixLen 

func (section WrappedIPAddressSection) GetBlockMaskPrefixLen(network bool) PrefixLen

GetBlockMaskPrefixLen returns the prefix length if this address section is equivalent to the mask for a CIDR prefix block. Otherwise, it returns nil. A CIDR network mask is an address section with all 1s in the network section and then all 0s in the host section. A CIDR host mask is an address section with all 0s in the network section and then all 1s 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

func (WrappedIPAddressSection) GetHostMask 

func (section WrappedIPAddressSection) GetHostMask() ExtendedIPSegmentSeries

GetHostMask returns the host mask associated with the CIDR network prefix length of this address section. If this series has no prefix length, then the all-ones mask is returned.

func (WrappedIPAddressSection) GetIPVersion 

func (section WrappedIPAddressSection) GetIPVersion() IPVersion

GetIPVersion returns the IP version of this IP address section

func (WrappedIPAddressSection) GetLower 

func (section WrappedIPAddressSection) GetLower() ExtendedIPSegmentSeries

GetLower returns the series in the range with the lowest numeric value, which will be the same series if it represents a single value. For example, for "1.2-3.4.5-6", the series "1.2.4.5" is returned.

func (WrappedIPAddressSection) GetMaxSegmentValue 

func (section WrappedIPAddressSection) GetMaxSegmentValue() SegInt

GetMaxSegmentValue returns the maximum possible segment value for this type of address.

Note this is not the maximum of the range of segment values in this specific address, this is the maximum value of any segment for this address type and version, determined by the number of bits per segment.

func (WrappedIPAddressSection) GetMinPrefixLenForBlock 

func (section WrappedIPAddressSection) GetMinPrefixLenForBlock() BitCount

GetMinPrefixLenForBlock returns the smallest prefix length such that this section includes the block of all values for that prefix length.

If the entire range can be described this way, then this method returns the same value as GetPrefixLenForSingleBlock.

There may be a single prefix, or multiple possible prefix values in this item for the returned prefix length. Use GetPrefixLenForSingleBlock to avoid the case of multiple prefix values.

If this section represents a single value, this returns the bit count.

func (WrappedIPAddressSection) GetNetworkMask 

func (section WrappedIPAddressSection) GetNetworkMask() ExtendedIPSegmentSeries

GetNetworkMask returns the network mask associated with the CIDR network prefix length of this address section. If this series has no prefix length, then the all-ones mask is returned.

func (WrappedIPAddressSection) GetNetworkPrefixLen 

func (section WrappedIPAddressSection) GetNetworkPrefixLen() PrefixLen

GetNetworkPrefixLen returns the prefix length, or nil if there is no prefix length. It is equivalent to GetPrefixLen.

A prefix length indicates the number of bits in the initial part of the address item that comprises the prefix.

A prefix is a part of the address item that is not specific to that address but common amongst a group of such items, such as a CIDR prefix block subnet.

func (WrappedIPAddressSection) GetPrefixLenForSingleBlock 

func (section WrappedIPAddressSection) GetPrefixLenForSingleBlock() PrefixLen

GetPrefixLenForSingleBlock returns a prefix length for which the range of this address section matches the block of addresses for that prefix.

If no such prefix exists, GetPrefixLenForSingleBlock returns nil.

If this address section represents a single value, returns the bit length.

func (WrappedIPAddressSection) GetSection 

func (section WrappedIPAddressSection) GetSection() *IPAddressSection

GetSection returns the backing section for this series, comprising all segments.

func (WrappedIPAddressSection) GetSegment 

func (section WrappedIPAddressSection) GetSegment(index int) *IPAddressSegment

GetSegment returns the segment at the given index. The first segment is at index 0. GetSegment will panic given a negative index or index larger than the segment count.

func (WrappedIPAddressSection) GetSegmentCount 

func (section WrappedIPAddressSection) GetSegmentCount() int

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 "1.2-3.4.5-6", the series "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 < 0, or if it is larger than the bit count of this item.

func (WrappedIPAddressSection) IsPrefixBlock 

func (section WrappedIPAddressSection) IsPrefixBlock() bool

IsPrefixBlock returns whether this address segment series has a prefix length and includes the block associated with its prefix length. If the prefix length matches the bit count, this returns true.

This is different from ContainsPrefixBlock in that this method returns false if the series has no prefix length or a prefix length that differs from prefix lengths for which ContainsPrefixBlock returns true.

func (WrappedIPAddressSection) IsSequential 

func (section WrappedIPAddressSection) IsSequential() bool

IsSequential returns whether the section represents a range of values that are sequential.

Generally, this means that any segment covering a range of values must be followed by segment that are full range, covering all values.

func (WrappedIPAddressSection) IsSingleNetwork 

func (section WrappedIPAddressSection) IsSingleNetwork() bool

IsSingleNetwork returns whether the network section of the address, the prefix, consists of a single value.

If it has no prefix length, it returns true if not multiple, if it contains only a single individual address section.

func (WrappedIPAddressSection) IsSinglePrefixBlock 

func (section WrappedIPAddressSection) IsSinglePrefixBlock() bool

IsSinglePrefixBlock returns whether the range matches the block of values for a single prefix identified by the prefix length of this address. This is similar to IsPrefixBlock() except that it returns false when the subnet has multiple prefixes.

What distinguishes this method from ContainsSinglePrefixBlock is that this method returns false if the series does not have a prefix length assigned to it, or a prefix length that differs from the prefix length for which ContainsSinglePrefixBlock returns true.

It is similar to IsPrefixBlock but returns false when there are multiple prefixes.

func (WrappedIPAddressSection) IsZero 

func (section WrappedIPAddressSection) IsZero() bool

IsZero returns whether this section matches exactly the value of zero

func (WrappedIPAddressSection) IsZeroHost 

func (section WrappedIPAddressSection) IsZeroHost() bool

IsZeroHost returns whether this section has a prefix length and if so, whether the host section is always zero for all individual sections in this address section.

If the host section is zero length (there are zero host bits), IsZeroHost returns true.

func (WrappedIPAddressSection) IsZeroHostLen 

func (section WrappedIPAddressSection) IsZeroHostLen(prefLen BitCount) bool

IsZeroHostLen returns whether the host section is always zero for all individual sections in this address section, for the given prefix length.

If the host section is zero length (there are zero host bits), IsZeroHostLen returns true.

func (WrappedIPAddressSection) Iterator 

func (section WrappedIPAddressSection) Iterator() ExtendedIPSegmentSeriesIterator

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() ExtendedIPSegmentSeriesIterator

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() ExtendedIPSegmentSeriesIterator

PrefixIterator provides an iterator to iterate through the individual prefixes of this series, each iterated element spanning the range of values for its prefix.

It is similar to the prefix block iterator, except for possibly the first and last iterated elements, which might not be prefix blocks, instead constraining themselves to values from this series.

If the series has no prefix length, then this is equivalent to Iterator.

func (WrappedIPAddressSection) ReverseBits 

func (section WrappedIPAddressSection) ReverseBits(perByte bool) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBits returns a new segment series with the bits reversed. Any prefix length is dropped.

If the bits within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

If perByte is true, the bits are reversed within each byte, otherwise all the bits are reversed.

func (WrappedIPAddressSection) ReverseBytes 

func (section WrappedIPAddressSection) ReverseBytes() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ReverseBytes returns a new segment series with the bytes reversed. Any prefix length is dropped.

If each segment is more than 1 byte long, and the bytes within a single segment cannot be reversed because the segment represents a range, and reversing the segment values results in a range that is not contiguous, then this returns an error.

In practice this means that to be reversible, a range must include all values except possibly the largest and/or smallest, which reverse to themselves.

func (WrappedIPAddressSection) ReverseSegments 

func (section WrappedIPAddressSection) ReverseSegments() ExtendedIPSegmentSeries

ReverseSegments returns a new series with the segments reversed.

func (WrappedIPAddressSection) SequentialBlockIterator 

func (section WrappedIPAddressSection) SequentialBlockIterator() ExtendedIPSegmentSeriesIterator

SequentialBlockIterator iterates through the sequential series that make up this series.

Practically, this means finding the count of segments for which the segments that follow are not full range, and then using BlockIterator with that segment count.

Use GetSequentialBlockCount to get the number of iterated elements.

func (WrappedIPAddressSection) SetPrefixLen 

func (section WrappedIPAddressSection) SetPrefixLen(prefixLen BitCount) ExtendedIPSegmentSeries

SetPrefixLen sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

func (WrappedIPAddressSection) SetPrefixLenZeroed 

func (section WrappedIPAddressSection) SetPrefixLenZeroed(prefixLen BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

SetPrefixLenZeroed sets the prefix length.

A prefix length will not be set to a value lower than zero or beyond the bit length of the series. The provided prefix length will be adjusted to these boundaries if necessary.

If this series has a prefix length, and the prefix length is increased when setting the new prefix length, the bits moved within the prefix become zero. If this series has a prefix length, and the prefix length is decreased when setting the new prefix length, the bits moved outside the prefix become zero.

In other words, bits that move from one side of the prefix length to the other (ie bits moved into the prefix or outside the prefix) are zeroed.

If the result cannot be zeroed because zeroing out bits results in a non-contiguous segment, an error is returned.

func (WrappedIPAddressSection) SpanWithPrefixBlocks 

func (section WrappedIPAddressSection) SpanWithPrefixBlocks() []ExtendedIPSegmentSeries

SpanWithPrefixBlocks returns an array of prefix blocks that spans the same set of individual series as this subnet section.

func (WrappedIPAddressSection) SpanWithSequentialBlocks 

func (section WrappedIPAddressSection) SpanWithSequentialBlocks() []ExtendedIPSegmentSeries

SpanWithSequentialBlocks produces the smallest slice of sequential blocks that cover the same set of individual address sections as this series.

This slice can be shorter than that produced by SpanWithPrefixBlocks and is never longer.

func (WrappedIPAddressSection) TestBit 

func (section WrappedIPAddressSection) TestBit(n BitCount) bool

TestBit returns true if the bit in the lower value of this section at the given index is 1, where index 0 refers to the least significant bit. In other words, it computes (bits & (1 << n)) != 0), using the lower value of this section. TestBit will panic if n < 0, or if it matches or exceeds the bit count of this item.

func (WrappedIPAddressSection) ToBlock 

func (section WrappedIPAddressSection) ToBlock(segmentIndex int, lower, upper SegInt) ExtendedIPSegmentSeries

ToBlock creates a new series block by changing the segment at the given index to have the given lower and upper value, and changing the following segments to be full-range.

func (WrappedIPAddressSection) ToIPv4 

func (section WrappedIPAddressSection) ToIPv4() IPv4AddressSegmentSeries

ToIPv4 converts to an IPv4AddressSegmentSeries if this section originated as an IPv4 section. If not, ToIPv4 returns nil.

ToIPv4 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedIPAddressSection) ToIPv6 

func (section WrappedIPAddressSection) ToIPv6() IPv6AddressSegmentSeries

ToIPv6 converts to an IPv6AddressSegmentSeries if this section originated as an IPv6 section. If not, ToIPv6 returns nil.

ToIPv6 can be called with a nil receiver, enabling you to chain this method with methods that might return a nil pointer.

func (WrappedIPAddressSection) ToMaxHost 

func (section WrappedIPAddressSection) ToMaxHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToMaxHost converts the address section to one in which all individual address sections have a host of all one-bits, the max value, the host being the bits following the prefix length. If the section has no prefix length, then it returns an all-ones section, the max address section.

The returned series will have the same prefix length.

This returns an error if the series is a range which cannot be converted to a range in which all individual elements have max hosts, because the conversion results in a series segment that is not a sequential range of values.

func (WrappedIPAddressSection) ToMaxHostLen 

func (section WrappedIPAddressSection) ToMaxHostLen(bitCount BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToMaxHostLen converts the address section to one in which all individual address sections have a host of all one-bits, the max host, the host being the bits following the given prefix length. If this address section has the same prefix length, then the resulting series will too, otherwise the resulting series will have no prefix length.

This returns an error if the address section is a range which cannot be converted to a range in which all individual address sections have max hosts, because the conversion results in a series segment that is not a sequential range of values.

func (WrappedIPAddressSection) ToPrefixBlock 

func (section WrappedIPAddressSection) ToPrefixBlock() ExtendedIPSegmentSeries

ToPrefixBlock returns the series with the same prefix as this series while the remaining bits span all values. The series will be the block of all series with the same prefix.

If this series has no prefix, this series is returned.

func (WrappedIPAddressSection) ToPrefixBlockLen 

func (section WrappedIPAddressSection) ToPrefixBlockLen(bitCount BitCount) ExtendedIPSegmentSeries

ToPrefixBlockLen returns the series with the same prefix of the given length as this series while the remaining bits span all values. The returned series will be the block of all series with the same prefix.

func (WrappedIPAddressSection) ToZeroHost 

func (section WrappedIPAddressSection) ToZeroHost() (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToZeroHost converts the section to one in which all individual sections have a host of zero, the host being the bits following the prefix length. If the section has no prefix length, then it returns an all-zero section.

The returned series will have the same prefix length.

This returns an error if the section is a range which cannot be converted to a range in which all individual elements have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (WrappedIPAddressSection) ToZeroHostLen 

func (section WrappedIPAddressSection) ToZeroHostLen(bitCount BitCount) (ExtendedIPSegmentSeries, addrerr.IncompatibleAddressError)

ToZeroHostLen converts the section to one in which all individual sections have a host of zero, the host being the bits following the given prefix length. If this section has the same prefix length, then the returned one will too, otherwise the returned series will have no prefix length.

This returns an error if the section is a range which cannot be converted to a range in which all individual sections have zero hosts, because the conversion results in a segment that is not a sequential range of values.

func (WrappedIPAddressSection) ToZeroNetwork 

func (section WrappedIPAddressSection) ToZeroNetwork() ExtendedIPSegmentSeries

ToZeroNetwork converts the address section to one in which all individual address sections have a network of zero, the network being the bits within the prefix length. If the section has no prefix length, then it returns an all-zero series.

The returned address section will have the same prefix length.

func (WrappedIPAddressSection) Unwrap 

func (section WrappedIPAddressSection) Unwrap() IPAddressSegmentSeries

Unwrap returns the wrapped address section as an interface, IPAddressSegmentSeries

func (WrappedIPAddressSection) UpperBytes 

func (section WrappedIPAddressSection) UpperBytes() []byte

UpperBytes returns the highest individual address section in this address section as a byte slice

func (WrappedIPAddressSection) WithoutPrefixLen 

func (section WrappedIPAddressSection) WithoutPrefixLen() ExtendedIPSegmentSeries

WithoutPrefixLen provides the same address series but with no prefix length. The values remain unchanged.

func (WrappedIPAddressSection) Wrap 

func (section WrappedIPAddressSection) Wrap() WrappedIPAddressSection

Wrap wraps this IP address section, returning a WrappedIPAddressSection, an implementation of ExtendedIPSegmentSeries, which can be used to write code that works with both IP addresses and IP address sections. Wrap can be called with a nil receiver, wrapping a nil address section.

func (WrappedIPAddressSection) WrapSection added in v1.2.0 

func (section WrappedIPAddressSection) WrapSection() WrappedAddressSection

WrapSection wraps this IP address section, returning a WrappedAddressSection, an implementation of ExtendedSegmentSeries, which can be used to write code that works with both addresses and address sections. WrapSection can be called with a nil receiver, wrapping a nil address section.

type WrappedIPAddressString 

type WrappedIPAddressString struct {
	*IPAddressString
}

WrappedIPAddressString wraps an IPAddressString to get an ExtendedIdentifierString

func (WrappedIPAddressString) GetAddress 

func (w WrappedIPAddressString) GetAddress() AddressType

GetAddress returns the identified address or nil if none

func (WrappedIPAddressString) ToAddress 

func (w WrappedIPAddressString) ToAddress() (AddressType, error)

ToAddress returns the identified address or an error

func (WrappedIPAddressString) Unwrap 

func (w WrappedIPAddressString) Unwrap() HostIdentifierString

Unwrap returns the wrapped IPAddressString as an interface, HostIdentifierString

type WrappedIPSegmentIterator 

type WrappedIPSegmentIterator struct {
	IPSegmentIterator
}

WrappedIPSegmentIterator converts an IP address segment iterator to an address segment iterator

func (WrappedIPSegmentIterator) Next 

func (iter WrappedIPSegmentIterator) Next() *AddressSegment

type WrappedMACAddressString 

type WrappedMACAddressString struct {
	*MACAddressString
}

WrappedMACAddressString wraps a MACAddressString to get an ExtendedIdentifierString

func (WrappedMACAddressString) GetAddress 

func (w WrappedMACAddressString) GetAddress() AddressType

GetAddress returns the identified address or nil if none

func (WrappedMACAddressString) ToAddress 

func (w WrappedMACAddressString) ToAddress() (AddressType, error)

ToAddress returns the identified address or an error

func (WrappedMACAddressString) Unwrap 

func (w WrappedMACAddressString) Unwrap() HostIdentifierString

Unwrap returns the wrapped MACAddressString as an interface, HostIdentifierString

type Zone 

type Zone string

func ValidateZoneStr 

func ValidateZoneStr(zoneStr string) (zone Zone, err addrerr.AddressStringError)

ValidateZone returns an error if the zone is invalid

func (Zone) IsEmpty 

func (zone Zone) IsEmpty() bool

IsEmpty returns whether the zone is the zero-zone, which is the lack of a zone, or the empty string zone.

func (Zone) String 

func (zone Zone) String() string

String implements the fmt.Stringer interface, returning the zone characters as a string

Source Files

View all Source files

Directories

Path Synopsis
Package addrstr provides interfaces for specifying how to create specific strings from addresses and address sections, as well as builder types to construct instances of those interfaces.
 Package addrstr provides interfaces for specifying how to create specific strings from addresses and address sections, as well as builder types to construct instances of those interfaces.

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.