Module inet.ipaddr
Package inet.ipaddr

Class IPAddressSeqRange

  • All Implemented Interfaces:
    AddressComponentRange, AddressItem, AddressItemRange, IPAddressRange, java.io.Serializable, java.lang.Comparable<AddressItem>
    Direct Known Subclasses:
    IPv4AddressSeqRange, IPv6AddressSeqRange
    public abstract class IPAddressSeqRange
extends java.lang.Object
implements IPAddressRange
    This class can be used to represent an arbitrary range of consecutive IP addresses.

    Note that the IPAddress and IPAddressString classes allow you to specify a range of values for each segment. That allows you to represent single addresses, any address 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.

    Author:
    sfoley
    See Also:
    Serialized Form

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      boolean contains​(IPAddress other)
      Returns whether this range contains all addresses in the given address or subnet
      boolean contains​(IPAddressSeqRange other)
      Returns whether this range contains all addresses in the given sequential range
      boolean containsPrefixBlock​(int prefixLen)
      Returns whether the values of this series contains the prefix block for the given prefix length.
      boolean containsSinglePrefixBlock​(int prefixLen)
      Returns whether the values of this series contains a single prefix block for the given prefix length.
      abstract IPAddress coverWithPrefixBlock()
      Returns the minimal-size prefix block that covers all the addresses in this range.
      java.math.BigInteger enumerate​(IPAddress other)
      Returns the distance of the given address from the initial value of this range.
      boolean equals​(java.lang.Object o)
      Returns whether the given sequential address range is equal to this sequential address range.
      IPAddressSeqRange extend​(IPAddressRange other)
      Extend this sequential range to include all address in the given range, which can be an IPAddress or IPAddressSeqRange.
      int getBitCount()
      Provides the number of bits comprising this address item
      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.
      java.math.BigInteger getCount()
      The count of possible distinct values for this AddressComponent.
      abstract java.lang.Iterable<? extends IPAddress> getIterable()
      Useful for using an instance in a "for-each loop", as in for(addr : address.getIterable()) { ...
      IPAddress getLower()
      Returns the lowest address in the sequential range, the one with the lowest numeric value
      IPAddress getUpper()
      Returns the highest address in the sequential range, the one with the highest numeric value
      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.
      java.math.BigInteger getUpperValue()
      Returns the highest value represented by this address item, the highest value included in the range of values
      java.math.BigInteger getValue()
      Returns the lowest value represented by this address item, the lowest value included in the range of values
      int hashCode()  
      boolean includesMax()
      Returns whether this sequential range's upper value is the highest address, the address whose bits are all ones.
      boolean includesZero()
      Returns whether this sequential range's lower value is the zero address.
      IPAddressSeqRange intersect​(IPAddressSeqRange other)
      Returns the intersection of this range with the given range, a range which includes those addresses in both this and the given range.
      boolean isMax()
      Returns whether this sequential range spans from the highest address, the address whose bits are all ones, to itself.
      boolean isMore​(IPAddressSeqRange other)  
      boolean isMultiple()
      Whether this represents multiple potential values (eg a prefixed address or a segment representing a range of values)
      boolean isSequential()
      Returns whether the address or subnet represents a range of values that are sequential.
      boolean isZero()
      Returns whether this sequential range spans from the zero address to itself.
      abstract java.util.Iterator<? extends IPAddress> iterator()
      Iterates through the individual addresses of this address or subnet.
      IPAddressSeqRange join​(IPAddressSeqRange other)
      Joins two ranges if they are contiguous ranges.
      static IPAddressSeqRange[] join​(IPAddressSeqRange... ranges)
      Joins the given ranges into the fewest number of ranges.
      boolean overlaps​(IPAddress other)
      Returns true if this sequential range overlaps the given address or subnet.
      boolean overlaps​(IPAddressSeqRange other)
      Returns true if this sequential range overlaps the given sequential range.
      abstract java.util.Iterator<? extends IPAddress> prefixBlockIterator​(int prefLength)
      Iterates through the range of prefix blocks in this range instance using the given prefix length.
      abstract AddressComponentRangeSpliterator<? extends IPAddressSeqRange,​? extends IPAddress> prefixBlockSpliterator​(int prefLength)
      Partitions and traverses through the individual prefix blocks for the given prefix length.
      abstract java.util.stream.Stream<? extends IPAddress> prefixBlockStream​(int prefLength)
      Returns a sequential stream of the prefix blocks for the given prefix length.
      java.util.Iterator<? extends IPAddressSeqRange> prefixIterator​(int prefixLength)
      Iterates through the range of prefixes in this range instance using the given prefix length.
      abstract AddressComponentSpliterator<? extends IPAddressSeqRange> prefixSpliterator​(int prefLength)
      Partitions and traverses through the individual prefixes for the given prefix length.
      abstract java.util.stream.Stream<? extends IPAddressSeqRange> prefixStream​(int prefLength)
      Returns a sequential stream of the individual prefixes for the given prefix length.
      abstract IPAddress[] spanWithPrefixBlocks()
      Produces an array of prefix blocks that spans the same set of addresses.
      abstract IPAddress[] spanWithSequentialBlocks()
      Produces an array of blocks that are sequential that cover the same set of addresses.
      abstract AddressComponentRangeSpliterator<? extends IPAddressSeqRange,​? extends IPAddress> spliterator()
      Partitions and traverses through the individual addresses.
      abstract java.util.stream.Stream<? extends IPAddress> stream()
      Returns a sequential stream of the individual address components.
      IPAddressSeqRange[] subtract​(IPAddressSeqRange other)
      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.
      java.lang.String toCanonicalString()
      Produces a canonical string for the address range.
      java.lang.String toCanonicalString​(java.lang.String separator)
      Produces a canonical string for the address range with the given separator string.
      java.lang.String toNormalizedString()
      Produces a normalized string for the address range.
      java.lang.String toNormalizedString​(java.lang.String separator)  
      java.lang.String toString()
      Produces the canonical string for the address, also available from toCanonicalString().
      java.lang.String toString​(java.util.function.Function<? super IPAddress,​java.lang.String> lowerStringer, java.lang.String separator, java.util.function.Function<? super IPAddress,​java.lang.String> upperStringer)  

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • DEFAULT_RANGE_SEPARATOR

        public static final java.lang.String DEFAULT_RANGE_SEPARATOR
        See Also:
        Constant Field Values

    • Method Detail

      • getCount

        public java.math.BigInteger getCount()
        Description copied from interface: AddressItem
        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.
        Specified by:
        getCount in interface AddressItem
        Returns:

      • isMultiple

        public boolean isMultiple()
        Description copied from interface: AddressItem
        Whether this represents multiple potential values (eg a prefixed address or a segment representing a range of values)
        Specified by:
        isMultiple in interface AddressItem

      • isMore

        public boolean isMore​(IPAddressSeqRange other)
        Parameters:
        other - the range to compare, which does not need to range across the same address space
        Returns:
        whether this range spans more addresses than the provided range.

      • prefixBlockIterator

        public abstract java.util.Iterator<? extends IPAddress> prefixBlockIterator​(int prefLength)
        Iterates through the range of prefix blocks in this range instance using the given prefix length.
        Specified by:
        prefixBlockIterator in interface IPAddressRange
        Parameters:
        prefLength -
        Returns:

      • prefixBlockStream

        public abstract java.util.stream.Stream<? extends IPAddress> prefixBlockStream​(int prefLength)
        Description copied from interface: IPAddressRange
        Returns a sequential stream of the prefix blocks for the given prefix length. For a parallel stream, call BaseStream.parallel() on the returned stream.
        Specified by:
        prefixBlockStream in interface IPAddressRange
        Returns:

      • prefixIterator

        public java.util.Iterator<? extends IPAddressSeqRange> prefixIterator​(int prefixLength)
        Iterates through the range of prefixes in this range instance using the given prefix length.

        Since a range between two arbitrary addresses cannot always be represented with a single IPAddress instance, the returned iterator iterates through IPAddressSeqRange instances.

        For instance, if iterating from 1.2.3.4 to 1.2.4.5 with prefix 8, the range shares the same prefix 1, but the range cannot be represented by the address 1.2.3-4.4-5 which does not include 1.2.3.255 or 1.2.4.0 both of which are in the original range. Nor can the range be represented by 1.2.3-4.0-255 which includes 1.2.4.6 and 1.2.3.3, both of which were not in the original range. An IPAddressSeqRange is thus required to represent that prefixed range.

        Specified by:
        prefixIterator in interface IPAddressRange
        Parameters:
        prefixLength -
        Returns:

      • prefixStream

        public abstract java.util.stream.Stream<? extends IPAddressSeqRange> prefixStream​(int prefLength)
        Description copied from interface: IPAddressRange
        Returns a sequential stream of the individual prefixes for the given prefix length. For a parallel stream, call BaseStream.parallel() on the returned stream.
        Specified by:
        prefixStream in interface IPAddressRange
        Returns:

      • stream

        public abstract java.util.stream.Stream<? extends IPAddress> stream()
        Description copied from interface: AddressComponentRange
        Returns a sequential stream of the individual address components. For a parallel stream, call BaseStream.parallel() on the returned stream.
        Specified by:
        stream in interface AddressComponentRange
        Returns:

      • toNormalizedString

        public java.lang.String toNormalizedString​(java.lang.String separator)

      • toNormalizedString

        public java.lang.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().
        Specified by:
        toNormalizedString in interface IPAddressRange
        Returns:

      • toCanonicalString

        public java.lang.String toCanonicalString​(java.lang.String separator)
        Produces a canonical string for the address range with the given separator string.

      • toCanonicalString

        public java.lang.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().
        Specified by:
        toCanonicalString in interface IPAddressRange
        Returns:

      • toString

        public java.lang.String toString​(java.util.function.Function<? super IPAddress,​java.lang.String> lowerStringer,
                                 java.lang.String separator,
                                 java.util.function.Function<? super IPAddress,​java.lang.String> upperStringer)

      • toString

        public java.lang.String toString()
        Produces the canonical string for the address, also available from toCanonicalString().
        Overrides:
        toString in class java.lang.Object

      • coverWithPrefixBlock

        public abstract 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.
        Specified by:
        coverWithPrefixBlock in interface IPAddressRange

      • join

        public static IPAddressSeqRange[] join​(IPAddressSeqRange... ranges)
        Joins the given ranges into the fewest number of ranges. This method can handle null ranges, which are ignored. The returned array will never be null and will be sorted by ascending lowest range value.
        Parameters:
        ranges -
        Returns:

      • overlaps

        public boolean overlaps​(IPAddress other)
        Returns true if this sequential range overlaps the given address or subnet.
        Specified by:
        overlaps in interface IPAddressRange
        Parameters:
        other -
        Returns:

      • overlaps

        public boolean overlaps​(IPAddressSeqRange other)
        Returns true if this sequential range overlaps the given sequential range.
        Specified by:
        overlaps in interface IPAddressRange
        Parameters:
        other -
        Returns:

      • contains

        public boolean contains​(IPAddress other)
        Description copied from interface: IPAddressRange
        Returns whether this range contains all addresses in the given address or subnet
        Specified by:
        contains in interface IPAddressRange
        Returns:

      • enumerate

        public java.math.BigInteger enumerate​(IPAddress other)
        Returns the distance of the given address from the initial value of this range. Indicates where an address sits relative to the range ordering.

        If within or above the range, it is the distance to the lower boundary of the sequential range. If below the, returns the number of addresses following the address to the lower range boundary.

        The method does not return null if this range does not contain the address. You can call contains(IPAddress) or you can compare with getCount() to check for containment. An address is in the range if 0 <= enumerate(IPAddress) < getCount().

        Returns null when the argument is a multi-valued subnet. The argument must be an individual address.

        If the given address does not have the same version or type as the addresses in this range, then null is returned.

        Specified by:
        enumerate in interface IPAddressRange
        Returns:

      • isSequential

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

        Specified by:
        isSequential in interface IPAddressRange
        Returns:
        true

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object o)
        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.
        Overrides:
        equals in class java.lang.Object

      • intersect

        public IPAddressSeqRange intersect​(IPAddressSeqRange other)
        Returns the intersection of this range with the given range, a range which includes those addresses in both this and the given range.
        Parameters:
        other -
        Returns:

      • join

        public IPAddressSeqRange join​(IPAddressSeqRange other)
        Joins two ranges if they are contiguous ranges. If this range overlaps 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, null is returned.

        Parameters:
        other -
        Returns:

      • extend

        public IPAddressSeqRange extend​(IPAddressRange other)
        Extend this sequential range to include all address in the given range, which can be an IPAddress or IPAddressSeqRange. If the argument has a different IP version than this, null is returned. Otherwise, this method returns the range that includes this range, the given range, and all addresses in-between.
        Parameters:
        other -
        Returns:

      • subtract

        public IPAddressSeqRange[] subtract​(IPAddressSeqRange other)
        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.
        Parameters:
        other -
        Returns:

      • containsPrefixBlock

        public boolean containsPrefixBlock​(int prefixLen)
        Description copied from interface: AddressItem
        Returns whether the values of this series contains the prefix block for the given prefix length.

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

        Specified by:
        containsPrefixBlock in interface AddressItem
        Returns:

      • getBitCount

        public int getBitCount()
        Description copied from interface: AddressItem
        Provides the number of bits comprising this address item
        Specified by:
        getBitCount in interface AddressItem
        Returns:
        the number of bits

      • getBytes

        public byte[] getBytes()
        Specified by:
        getBytes in interface AddressItem
        Returns:
        the bytes of the lowest address item represented by this address item

      • getBytes

        public byte[] getBytes​(byte[] bytes)
        Description copied from interface: AddressItem
        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.
        Specified by:
        getBytes in interface AddressItem
        Returns:
        the bytes of the lowest address represented by this address item.

      • getBytes

        public byte[] getBytes​(byte[] bytes,
                       int index)
        Description copied from interface: AddressItem
        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.
        Specified by:
        getBytes in interface AddressItem
        Returns:
        the bytes of the lowest address represented by this address item.

      • getUpperBytes

        public byte[] getUpperBytes()
        Specified by:
        getUpperBytes in interface AddressItem
        Returns:
        the bytes of the largest address item represented by this address item

      • getUpperBytes

        public byte[] getUpperBytes​(byte[] bytes)
        Description copied from interface: AddressItem
        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.
        Specified by:
        getUpperBytes in interface AddressItem
        Returns:
        the bytes of the largest address represented by this address item.

      • getUpperBytes

        public byte[] getUpperBytes​(byte[] bytes,
                            int index)
        Description copied from interface: AddressItem
        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.
        Specified by:
        getUpperBytes in interface AddressItem
        Returns:
        the bytes of the largest address represented by this address item.

      • getValue

        public java.math.BigInteger getValue()
        Description copied from interface: AddressItem
        Returns the lowest value represented by this address item, the lowest value included in the range of values
        Specified by:
        getValue in interface AddressItem
        Returns:
        the lowest value represented by this address item

      • getUpperValue

        public java.math.BigInteger getUpperValue()
        Description copied from interface: AddressItem
        Returns the highest value represented by this address item, the highest value included in the range of values
        Specified by:
        getUpperValue in interface AddressItem
        Returns:
        the highest value represented by this address item

      • isZero

        public boolean isZero()
        Returns whether this sequential range spans from the zero address to itself.
        Specified by:
        isZero in interface AddressItem
        Returns:
        whether this item matches the value of zero

      • includesZero

        public boolean includesZero()
        Returns whether this sequential range's lower value is the zero address.
        Specified by:
        includesZero in interface AddressItem
        Returns:
        whether this item includes the value of zero within its range

      • isMax

        public boolean isMax()
        Returns whether this sequential range spans from the highest address, the address whose bits are all ones, to itself.
        Specified by:
        isMax in interface AddressItem
        Returns:
        whether this item matches the maximum possible value

      • includesMax

        public boolean includesMax()
        Returns whether this sequential range's upper value is the highest address, the address whose bits are all ones.
        Specified by:
        includesMax in interface AddressItem
        Returns:
        whether this item includes the maximum possible value within its range