AddressItem (IPAddress javadoc by seancfoley)

All Superinterfaces:

Comparable<AddressItem>, Serializable

All Known Subinterfaces:

AddressComponent, AddressComponentRange, AddressDivisionSeries, AddressGenericDivision, AddressItemRange, AddressSection, AddressSegment, AddressSegmentSeries, IPAddressDivisionSeries, IPAddressGenericDivision, IPAddressRange, IPAddressSegmentSeries

All Known Implementing Classes:

Address, AddressBitsDivision, AddressDivision, AddressDivisionBase, AddressDivisionGrouping, AddressDivisionGroupingBase, IPAddress, IPAddressBitsDivision, IPAddressDivision, IPAddressDivisionGrouping, IPAddressJoinedSegments, IPAddressLargeDivision, IPAddressLargeDivisionGrouping, IPAddressSection, IPAddressSegment, IPAddressSeqRange, IPv4Address, IPv4AddressSection, IPv4AddressSegment, IPv4AddressSeqRange, IPv4JoinedSegments, IPv6Address, IPv6AddressSection, IPv6AddressSection.IPv6v4MixedAddressSection, IPv6AddressSegment, IPv6AddressSeqRange, MACAddress, MACAddressSection, MACAddressSegment
```
public interface AddressItem
extends Comparable<AddressItem>, Serializable
```
Represents any part of an address, whether divided into the standard arrangement of AddressComponent objects, or whether an alternative arrangement using AddressDivision objects.
The basic difference between the AddressComponent hierarchy and the AddressDivision hierarchy is that
AddressComponent hierarchy uses
- standardized/typical arrangement (ie for ipv4, 4 equal segments of 1 byte each, for ipv6, 8 equal segments of 2 bytes each, for mac, 6 or 8 equal segments of 1 byte each)
- equal size segments
- segments divided along byte boundaries
AddressDivision allows alternative arrangements, such as inet_aton style of presenting ipv4 in fewer divisions, or base 85 for ipv6 which does not even use a base that is a power of 2 (and hence so subdivisions possibly using bit boundaries), or the aaa-bbb-ccc-ddd mac format with which segments are not divided along byte boundaries
Parsing creates objects in the AddressComponent hierarchy, which can then be used to create alternative arrangements using AddressDivisionGrouping or AddressStringDivisionSeries

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default int`	`compareTo(AddressItem other)` Uses `Address.DEFAULT_ADDRESS_COMPARATOR`, an instance of `AddressComparator.CountComparator`, to compare any two address items.
`default boolean`	`containsPrefixBlock(int divisionPrefixLen)` Returns whether the values of this series contains the prefix block for the given prefix length.
`default boolean`	`containsSinglePrefixBlock(int divisionPrefixLen)` Returns whether the values of this series contains a single prefix block for the given prefix length.
`int`	`getBitCount()` Provides the number of bits comprising this address item
`static Integer`	`getBitsForCount(long count)` BitsForCount returns the number of bits required outside the prefix length for a single prefix block to span at least as many addresses as the given count.
`static BigInteger`	`getBlockSize(int bitCount)` Returns the total number of values when ranging across the given number of host bits.
`default int`	`getByteCount()` Provides the number of bytes required for this address item, rounding up if the bit count is not a multiple of 8
`byte[]`	`getBytes()`
`byte[]`	`getBytes(byte[] bytes)` Copies the bytes of the lowest address item represented by this address item into the supplied array, and returns that array.
`byte[]`	`getBytes(byte[] bytes, int index)` Copies the bytes of the lowest address item represented by this address item into the supplied array starting at the given index, and returns that array.
`default BigInteger`	`getCount()` The count of possible distinct values for this AddressComponent.
`default int`	`getMinPrefixLengthForBlock()` Returns the smallest prefix length possible such that this item includes the block of all values for that prefix length.
`default BigInteger`	`getPrefixCount(int prefixLength)` The count of the number of distinct values within the prefix part of the address item, the bits that appear within the prefix length.
`default Integer`	`getPrefixLengthForSingleBlock()` Returns a prefix length for which the range of this item matches the block of all values for that prefix length.
`byte[]`	`getUpperBytes()`
`byte[]`	`getUpperBytes(byte[] bytes)` Copies the bytes of the largest address item represented by this address item into the supplied array, and returns that array.
`byte[]`	`getUpperBytes(byte[] bytes, int index)` Copies the bytes of the largest address item represented by this address item into the supplied array at the given index, and returns that array.
`BigInteger`	`getUpperValue()` Returns the highest value represented by this address item, the highest value included in the range of values
`BigInteger`	`getValue()` Returns the lowest value represented by this address item, the lowest value included in the range of values
`boolean`	`includesMax()` Returns whether this item includes the maximum possible value for the address type or version within its range
`boolean`	`includesZero()` Returns whether this item includes the value of zero within its range
`default boolean`	`isFullRange()` whether this address item represents all possible values attainable by an address item of this type
`boolean`	`isMax()` Returns whether this item matches the maximum possible value for the address type or version
`default boolean`	`isMultiple()` Whether this represents multiple potential values (eg a prefixed address or a segment representing a range of values)
`boolean`	`isZero()` Returns whether this item matches the value of zero

- Method Detail
  - compareTo
```
default int compareTo(AddressItem other)
```
    Uses Address.DEFAULT_ADDRESS_COMPARATOR, an instance of AddressComparator.CountComparator, to compare any two address items.
    
    Specified by:
    
    compareTo in interface Comparable<AddressItem>
  - getCount
```
default BigInteger getCount()
```
    The count of possible distinct values for this AddressComponent. If not multiple, this is 1. Note that an AddressDivisionSeries with no divisions or AddressSection with no segments has a single value of 0. For instance, if this is the ip address series subnet 0::/64, then the count is 2 to the power of 64. If this is a the segment 3-7, then the count is 5.
    
    Returns:
  - getPrefixCount
```
default BigInteger getPrefixCount(int prefixLength)
```
    The count of the number of distinct values within the prefix part of the address item, the bits that appear within the prefix length.
    
    Parameters:
    
    prefixLength -
    
    Returns:
  - getBitCount
```
int getBitCount()
```
    Provides the number of bits comprising this address item
    
    Returns:
    
    the number of bits
  - getByteCount
```
default int getByteCount()
```
    Provides the number of bytes required for this address item, rounding up if the bit count is not a multiple of 8
    
    Returns:
    
    the number of bytes
  - isMultiple
```
default boolean isMultiple()
```
    Whether this represents multiple potential values (eg a prefixed address or a segment representing a range of values)
  - getBytes
```
byte[] getBytes()
```
    Returns:
    
    the bytes of the lowest address item represented by this address item
  - getBytes
```
byte[] getBytes(byte[] bytes)
```
    Copies the bytes of the lowest address item represented by this address item into the supplied array, and returns that array. If the supplied array is null or of insufficient size, a new array is created and returned.
    
    Returns:
    
    the bytes of the lowest address represented by this address item.
  - getBytes
```
byte[] getBytes(byte[] bytes,
                int index)
```
    Copies the bytes of the lowest address item represented by this address item into the supplied array starting at the given index, and returns that array. If the supplied array is null or of insufficient size, a new array is created and returned, with the rest of the array contents the same as the original.
    
    Returns:
    
    the bytes of the lowest address represented by this address item.
  - getUpperBytes
```
byte[] getUpperBytes()
```
    Returns:
    
    the bytes of the largest address item represented by this address item
  - getUpperBytes
```
byte[] getUpperBytes(byte[] bytes)
```
    Copies the bytes of the largest address item represented by this address item into the supplied array, and returns that array. If the supplied array is null or of insufficient size, a new array is created and returned, with the rest of the array contents the same as the original.
    
    Returns:
    
    the bytes of the largest address represented by this address item.
  - getUpperBytes
```
byte[] getUpperBytes(byte[] bytes,
                     int index)
```
    Copies the bytes of the largest address item represented by this address item into the supplied array at the given index, and returns that array. If the supplied array is null or of insufficient size, a new array is created and returned.
    
    Returns:
    
    the bytes of the largest address represented by this address item.
  - getValue
```
BigInteger getValue()
```
    Returns the lowest value represented by this address item, the lowest value included in the range of values
    
    Returns:
    
    the lowest value represented by this address item
  - getUpperValue
```
BigInteger getUpperValue()
```
    Returns the highest value represented by this address item, the highest value included in the range of values
    
    Returns:
    
    the highest value represented by this address item
  - isZero
```
boolean isZero()
```
    Returns whether this item matches the value of zero
    
    Returns:
    
    whether this item matches the value of zero
  - includesZero
```
boolean includesZero()
```
    Returns whether this item includes the value of zero within its range
    
    Returns:
    
    whether this item includes the value of zero within its range
  - isMax
```
boolean isMax()
```
    Returns whether this item matches the maximum possible value for the address type or version
    
    Returns:
    
    whether this item matches the maximum possible value
  - includesMax
```
boolean includesMax()
```
    Returns whether this item includes the maximum possible value for the address type or version within its range
    
    Returns:
    
    whether this item includes the maximum possible value within its range
  - isFullRange
```
default boolean isFullRange()
```
    whether this address item represents all possible values attainable by an address item of this type
    
    Returns:
    
    whether this address item represents all possible values attainable by an address item of this type, or in other words, both includesZero() and includesMax() return true
  - containsPrefixBlock
```
default boolean containsPrefixBlock(int divisionPrefixLen)
```
    Returns whether the values of this series contains the prefix block for the given prefix length.
    Use getMinPrefixLengthForBlock() to determine the smallest prefix length for which this method returns true.
    
    Parameters:
    
    divisionPrefixLen -
    
    Returns:
    
    Throws:
    
    PrefixLenException - if prefixLength exceeds the bit count or is negative
  - containsSinglePrefixBlock
```
default boolean containsSinglePrefixBlock(int divisionPrefixLen)
```
    Returns whether the values of this series contains a single prefix block for the given prefix length.
    Use getPrefixLengthForSingleBlock() to determine whether there is a prefix length for which this method returns true.
    
    Parameters:
    
    divisionPrefixLen -
    
    Returns:
    
    Throws:
    
    PrefixLenException - if prefixLength exceeds the bit count or is negative
  - getMinPrefixLengthForBlock
```
default int getMinPrefixLengthForBlock()
```
    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 getPrefixLengthForSingleBlock(). Otherwise, this method will return the minimal possible prefix that can be paired with this address, while getPrefixLengthForSingleBlock() will return null.
    In cases where the final bit is constant so there is no such block, this returns the bit count.
    
    Returns:
    
    the prefix length
  - getPrefixLengthForSingleBlock
```
default Integer getPrefixLengthForSingleBlock()
```
    Returns a prefix length for which the range of this item matches the block of all values for that prefix length.
    If the range can be dictated this way, then this method returns the same value as getMinPrefixLengthForBlock().
    If no such prefix length exists, returns null.
    If this item represents a single value, this returns the bit count.
    
    Returns:
    
    the prefix length or null
  - getBlockSize
```
static BigInteger getBlockSize(int bitCount)
```
    Returns the total number of values when ranging across the given number of host bits. This is the reverse of getBitsForCount(long). A bitCount of zero or less returns zero.
    
    Parameters:
    
    bitCount -
  - getBitsForCount
```
static Integer getBitsForCount(long count)
```
    BitsForCount returns the number of bits required outside the prefix length for a single prefix block to span at least as many addresses as the given count. Mathematically, it is the ceiling of the base 2 logarithm of the given count. A count of zero or less than zero returns null. See getBlockSize(int) for the reverse direction.
    
    Parameters:
    
    count -

Interface AddressItem

Method Summary

Method Detail

compareTo

getCount

getPrefixCount

getBitCount

getByteCount

isMultiple

getBytes

getBytes

getBytes

getUpperBytes

getUpperBytes

getUpperBytes

getValue

getUpperValue

isZero

includesZero

isMax

includesMax

isFullRange

containsPrefixBlock

containsSinglePrefixBlock

getMinPrefixLengthForBlock

getPrefixLengthForSingleBlock

getBlockSize

getBitsForCount