Module inet.ipaddr
Package inet.ipaddr

Class IPAddress

    • Method Detail

      • toAddressString

        public IPAddressString toAddressString()
        Generates an IPAddressString object for this IPAddress object.

        This same IPAddress object can be retrieved from the resulting IPAddressString object using IPAddressString.getAddress()

        In general, users are intended to create IPAddress objects from IPAddressString objects, while the reverse direction is generally not all that useful.

        However, the reverse direction can be useful under certain circumstances.

        Not all IPAddressString objects can be converted to IPAddress objects, as is the case with IPAddressString objects corresponding to the types IPType.INVALID and IPType.EMPTY.

        Not all IPAddressString objects can be converted to IPAddress objects without specifying the IP version, as is the case with IPAddressString objects corresponding to the types IPType.PREFIX and IPType.ALL.

        So in the event you wish to store a collection of IPAddress objects with a collection of IPAddressString objects, and not all the IPAddressString objects can be converted to IPAddress objects, then you may wish to use a collection of only IPAddressString objects, in which case this method is useful.

        Overrides:
        toAddressString in class Address
        Returns:
        an IPAddressString object for this IPAddress.
      • toHostName

        public HostName toHostName()
        If this address was resolved from a host, returns that host. Otherwise, does a reverse name lookup.
      • toCanonicalHostName

        public HostName toCanonicalHostName()
        Does a reverse name lookup to get the canonical host name. Note that the canonical host name may differ on different systems, as it aligns with InetAddress.getCanonicalHostName() In particular, on some systems the loopback address has canonical host localhost and on others the canonical host is the same loopback address.
      • getMaxSegmentValue

        public int getMaxSegmentValue()
        Description copied from interface: AddressSegmentSeries
        Returns the maximum possible segment value for this type of address. Note this is not the maximum value of the range of segment values in this specific address, this is the maximum value of any segment for this address type, and is usually determined by the number of bits per segment.
        Specified by:
        getMaxSegmentValue in interface AddressSegmentSeries
        Returns:
        the maximum possible segment value for a series of the same type
      • getNonZeroHostCount

        public java.math.BigInteger getNonZeroHostCount()
        Description copied from interface: IPAddressSegmentSeries
        Gets the count of single value series that this series may represent, but excluding series whose host is zero. The host is determined by the CIDR prefix length, if there is one.

        If this address series has no range of values, then there is only one such address, or none if it has a zero host.

        If this has no CIDR network prefix length, then it is equivalent to AddressDivisionSeries.getCount().

        Specified by:
        getNonZeroHostCount in interface IPAddressSegmentSeries
        Returns:
      • getBytesPerSegment

        public int getBytesPerSegment()
        Description copied from interface: AddressSegmentSeries
        Returns the number of bytes comprising each segment in this series. Segments in the same series are equal length.
        Specified by:
        getBytesPerSegment in interface AddressSegmentSeries
        Returns:
      • getBitsPerSegment

        public int getBitsPerSegment()
        Description copied from interface: AddressSegmentSeries
        Returns the number of bits comprising each segment in this series. Segments in the same series are equal length.
        Specified by:
        getBitsPerSegment in interface AddressSegmentSeries
        Returns:
      • getByteCount

        public int getByteCount()
        Description copied from interface: AddressItem
        Provides the number of bytes required for this address item, rounding up if the bit count is not a multiple of 8
        Specified by:
        getByteCount in interface AddressItem
        Overrides:
        getByteCount in class Address
        Returns:
        the number of bytes
      • applyToBounds

        public <V> V applyToBounds​(java.util.function.BiFunction<? super IPAddress,​? super IPAddress,​V> func,
                                   IPAddress... series)
        Finds the lowest and highest single-valued address from the given addresses and subnets and this one, calling the given BiFunction with the lowest as first argument and the highest as second. It returns the result returned from the call to the BiFunction.

        For instance, given the IPv4 addresses 1.2.0.0/16 and 1.3.4.5, the lowest is 1.2.0.0 and the highest is 1.3.4.5. Given the addresses 1.2.0.0/16 and 1.1.4.5, the lowest is 1.1.4.5 and the highest is 1.2.255.255.

        If one of the given addresses or subnets is a different version than this, then the default conversion is applied to the other address first using toIPv4() or toIPv6()

        This can be useful for methods that require a range as input, like spanWithPrefixBlocks(IPAddress), spanWithSequentialBlocks(IPAddress), coverWithPrefixBlock(IPAddress), or toSequentialRange(IPAddress).

        For instance, to cover multiple addresses with a prefix block:
        IPAddress coveringAddress = address0.applyToBounds(IPAddress::coverWithPrefixBlock, address1, address2, address3, ...);

      • blockIterator

        public abstract java.util.Iterator<? extends IPAddress> blockIterator​(int segmentCount)
        Description copied from interface: IPAddressSegmentSeries
        Iterates through series that can be obtained by iterating through all the upper segments up to the given segment count. Segments following remain the same in all iterated series.

        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

        Specified by:
        blockIterator in interface IPAddressSegmentSeries
        Returns:
      • blockStream

        public abstract java.util.stream.Stream<? extends IPAddress> blockStream​(int segmentCount)
        Description copied from interface: IPAddressSegmentSeries
        Returns a sequential stream of the individual blocks created from each of the individual values up to the given segment count. For a parallel stream, call BaseStream.parallel() on the returned stream.
        Specified by:
        blockStream in interface IPAddressSegmentSeries
        Returns:
      • increment

        public abstract IPAddress increment​(long increment)
                                     throws AddressValueException
        Description copied from interface: AddressSegmentSeries
        Returns the series 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 subnet has multiple values and the increment exceeds the subnet size, then the amount by which it exceeds the size - 1 is added to the upper series of the range (the final iterator value).

        If the increment is negative, it is added to the lower series of the range (the first iterator value).

        If the subnet is just a single address values, the series is simply incremented by the given value, positive or negative.

        If a subnet has multiple values, a positive increment value is equivalent to the same number of values from the AddressSegmentSeries.iterator() 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. A negative increment added to the subnet count is equivalent to the same number of 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.

        An increment of size count gives you the series just above the highest series of the subnet. To get the series just below the lowest series of the subnet, use the increment -1.

        Specified by:
        increment in interface AddressSegmentSeries
        Specified by:
        increment in interface IPAddressSegmentSeries
        Specified by:
        increment in class Address
        Returns:
        Throws:
        AddressValueException - in case of underflow or overflow
      • isIPAddress

        public boolean isIPAddress()
        Description copied from class: Address
        Returns whether this address is an IP address
        Overrides:
        isIPAddress in class Address
        Returns:
        whether this address is an IP address
      • toIPAddress

        public IPAddress toIPAddress()
        Description copied from class: Address
        If this address is an IP address, returns that IPAddress. Otherwise, returns null.
        Overrides:
        toIPAddress in class Address
        Returns:
        the IP address
      • isIPv4

        public boolean isIPv4()
      • isIPv6

        public boolean isIPv6()
      • isIPv4Convertible

        public abstract boolean isIPv4Convertible()
        Determines whether this address can be converted to IPv4, if not IPv4 already. Override this method to convert in your own way. If IPv6, the default behaviour is to convert by IPv4 mapping, see IPv6Address.isIPv4Mapped() You should also override toIPv4() to match the conversion. This method returns true for all IPv4 addresses.
        Returns:
      • isIPv6Convertible

        public abstract boolean isIPv6Convertible()
        Determines whether an address can be converted to IPv6, if not IPv6 already. Override this method to convert in your own way. The default behaviour is to convert by IPv4 mapping, see IPv4Address.getIPv4MappedAddress() You should also override toIPv6() to match the conversion. This method returns true for all IPv6 addresses.
        Returns:
      • isLinkLocal

        public abstract boolean isLinkLocal()
        Returns whether the address is link local, whether unicast or multicast.
        See Also:
        InetAddress.isLinkLocalAddress()
      • isLocal

        public abstract boolean isLocal()
        Returns true if the address is link local, site local, organization local, administered locally, or unspecified. This includes both unicast and multicast.
        Specified by:
        isLocal in class Address
        Returns:
      • isUnspecified

        public boolean isUnspecified()
        The unspecified address is the address that is all zeros.
        Returns:
      • isAnyLocal

        public boolean 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.
        See Also:
        InetAddress.isAnyLocalAddress()
      • isLoopback

        public abstract boolean isLoopback()
        See Also:
        InetAddress.isLoopbackAddress()
      • toUpperInetAddress

        public java.net.InetAddress toUpperInetAddress()
        Converts the highest value of this address to an InetAddress. If this consists of just a single address and not a subnet, this is equivalent to toInetAddress()
      • toInetAddress

        public java.net.InetAddress toInetAddress()
        Converts the lowest value of this address to an InetAddress
      • toSequentialRange

        public abstract 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 Address.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.

        Specified by:
        toSequentialRange in interface IPAddressRange
        Returns:
      • overlaps

        public boolean overlaps​(IPAddress other)
        Returns true if this address 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 address overlaps the given sequential range
        Specified by:
        overlaps in interface IPAddressRange
        Parameters:
        other -
        Returns:
      • contains

        public boolean contains​(IPAddress other)
        Returns whether this contains all values of the given address or subnet

        Implements the same method in IPAddressRange.

        Specified by:
        contains in interface IPAddressRange
        Parameters:
        other -
        Returns:
      • containsNonZeroHosts

        public boolean containsNonZeroHosts​(IPAddress other)
        Returns whether this address contains the non-zero host addresses in the other address or subnet
        Parameters:
        other -
        Returns:
      • prefixContains

        public boolean prefixContains​(IPAddress other)
        Returns whether the prefix of this address contains all values of the same bits in the given address or subnet
        Parameters:
        other -
        Returns:
      • isZeroHost

        public boolean isZeroHost()
        Returns whether this address has a prefix length and if so, whether the host section is zero for this address or all addresses in this subnet. If the host section is zero length (there are no host bits at all), returns false.
        Returns:
      • isZeroHost

        public boolean isZeroHost​(int networkPrefixLength)
        Returns whether the host is zero for the given prefix length for this address or all addresses in this subnet. If this address already has a prefix length, then that prefix length is ignored. If the host section is zero length (there are no host bits at all), returns false.
        Returns:
      • matchesWithMask

        public boolean matchesWithMask​(IPAddress other,
                                       IPAddress mask)
        Applies the mask to this address and then compares values with the given address
        Parameters:
        mask -
        other -
        Returns:
      • toNormalizedString

        public static void toNormalizedString​(IPAddress.IPAddressValueProvider provider,
                                              java.lang.StringBuilder builder)
        Allows for the creation of a normalized string without creating a full IP address object first. Instead you can implement the IPAddress.IPAddressValueProvider interface in whatever way is most efficient. The string is appended to the provided StringBuilder instance.
        Parameters:
        provider -
        builder -
      • toNormalizedString

        public static java.lang.String toNormalizedString​(IPAddress.IPAddressValueProvider provider)
        Allows for the creation of a normalized string without creating a full IP address object first. Instead you can implement the IPAddress.IPAddressValueProvider interface in whatever way is most efficient.
        Parameters:
        provider -
      • toFullString

        public java.lang.String toFullString()
        This produces a string with no compressed segments and all segments of full length, which is 4 characters for IPv6 segments and 3 characters for IPv4 segments. Each address has a unique full string, not counting CIDR the prefix, which can give two equal addresses different strings.
        Specified by:
        toFullString in interface IPAddressSegmentSeries
      • toSubnetString

        public java.lang.String toSubnetString()
        Produces a consistent subnet string that 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 ::.
        Specified by:
        toSubnetString in interface IPAddressSegmentSeries
      • toNormalizedWildcardString

        public java.lang.String toNormalizedWildcardString()
        This produces a string similar to the normalized string but avoids the CIDR prefix. CIDR addresses will be shown with wildcards and ranges instead of using the CIDR prefix notation.
        Specified by:
        toNormalizedWildcardString in interface IPAddressSegmentSeries
      • toCanonicalWildcardString

        public java.lang.String toCanonicalWildcardString()
        This produces a string similar to the canonical string but avoids the CIDR prefix. Addresses with a network prefix length will be shown with wildcards and ranges instead of using the CIDR prefix length notation. IPv6 addresses will be compressed according to the canonical representation.
        Specified by:
        toCanonicalWildcardString in interface IPAddressSegmentSeries
      • toCompressedWildcardString

        public java.lang.String toCompressedWildcardString()
        This is similar to toNormalizedWildcardString, avoiding the CIDR prefix, but with compression as well.
        Specified by:
        toCompressedWildcardString in interface IPAddressSegmentSeries
      • toPrefixLengthString

        public java.lang.String toPrefixLengthString()
        Returns a string with a CIDR network prefix length if this address has a network prefix length. For IPv6, the host section will be compressed with ::, for IPv4 the host section will be zeros.
        Specified by:
        toPrefixLengthString in interface IPAddressSegmentSeries
        Returns:
      • toConvertedString

        public java.lang.String toConvertedString()
        Returns a mixed string if it represents a convertible IPv4 address, returns the normalized string otherwise.
        Returns:
      • toUNCHostName

        public abstract java.lang.String toUNCHostName()
        Generates the Microsoft UNC path component for this address
        Returns:
      • toReverseDNSLookupString

        public java.lang.String toReverseDNSLookupString()
        Generates the reverse DNS lookup string

        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

        Specified by:
        toReverseDNSLookupString in interface IPAddressSegmentSeries
        Returns:
        Throws:
        IncompatibleAddressException - if this address is a subnet
      • toOctalString

        public java.lang.String toOctalString​(boolean with0Prefix)
                                       throws IncompatibleAddressException
        Writes this address as a single octal value with always the exact same number of characters, with or without a preceding 0 prefix.

        If this section represents a range of values not corresponding to a prefix, then this is printed as a range of two hex values.

        Specified by:
        toOctalString in interface IPAddressSegmentSeries
        Throws:
        IncompatibleAddressException
      • toNormalizedString

        public java.lang.String toNormalizedString​(IPAddressSection.IPStringOptions params)
        Constructs a string representing this address according to the given parameters
        Specified by:
        toNormalizedString in interface IPAddressSegmentSeries
        Parameters:
        params - the parameters for the address string
        Returns:
        Throws:
        IncompatibleAddressException - for cases in which the requested string cannot be produced, which can generally only occur with specific strings from specific subnets.
      • toStandardStrings

        public java.lang.String[] toStandardStrings()
        Returns at most a few dozen string representations: -mixed (1:2:3:4:5:6:1.2.3.4) -full compressions (a:0:b:c:d:0:e:f or a::b:c:d:0:e:f or a:0:b:c:d::e:f) -full leading zeros (000a:0000:000b:000c:000d:0000:000e:000f) -all uppercase and all lowercase (a::a can be A::A) -combinations thereof
        Returns:
      • toAllStrings

        public java.lang.String[] toAllStrings()
        Produces almost all possible string variations

        Use this method with care... a single IPv6 address can have thousands of string representations.

        Examples:

        • "::" has 1297 such variations, but only 9 are considered standard
        • "a:b:c:0:d:e:f:1" has 1920 variations, but only 12 are standard

        Variations included in this method:

        • all standard variations from toStandardStrings()
        • adding a variable number of leading zeros (::a can be ::0a, ::00a, ::000a)
        • choosing any number of zero-segments to compress (:: can be 0:0:0::0:0)
        • mixed representation of all variations (1:2:3:4:5:6:1.2.3.4)
        • all uppercase and all lowercase (a::a can be A::A)
        • all combinations of such variations
        Variations omitted from this method: mixed case of a-f, which you can easily handle yourself with String.equalsIgnoreCase

        Returns:
        the strings
      • toStrings

        public java.lang.String[] toStrings​(IPAddressSection.IPStringBuilderOptions options)
        Rather than using toAllStrings or StandardStrings, you can use this method to customize the list of strings produced for this address
      • toDelimitedSQLStrs

        public static java.lang.String toDelimitedSQLStrs​(java.lang.String[] strs)
      • getNetworkPrefixLength

        public java.lang.Integer getNetworkPrefixLength()
        Description copied from interface: IPAddressDivisionSeries
        Returns the CIDR network prefix length of the series, or null if the series has no associated prefix length.

        Equivalent to AddressDivisionSeries.getPrefixLength(), which is the more general concept of set of address series that share the same set of leading bits. For IP addresses and sections the prefix length and the CIDR network prefix length are the same thing.

        For IP addresses and sections each individual segment has an associated prefix length which is determine by the network prefix length. The segment prefix lengths follow the pattern: null, null, ...., null, x, 0, 0, ..., 0

        For instance, an IPv4 address 1.2.3.4/16 has the network prefix length 16. The segment prefix lengths are [null, 8, 0, 0] The segment prefix lengths of 1.2.3.4/22 are [null, null, 6, 0]

        Specified by:
        getNetworkPrefixLength in interface IPAddressDivisionSeries
        Returns:
      • getHostMask

        public IPAddress getHostMask()
        Description copied from interface: IPAddressSegmentSeries
        Returns the host mask associated with the CIDR network prefix length of this series. If this series has no prefix length, then the whole series is considered a host and the all ones host mask is returned.
        Specified by:
        getHostMask in interface IPAddressSegmentSeries
        Returns:
      • getNetworkMask

        public IPAddress getNetworkMask()
        Description copied from interface: IPAddressSegmentSeries
        Returns the network mask associated with the CIDR network prefix length of this series. If this series has no prefix length, then the whole series is considered network and the all ones network mask is returned.
        Specified by:
        getNetworkMask in interface IPAddressSegmentSeries
        Returns:
      • includesZeroHost

        public boolean includesZeroHost()
        Description copied from interface: IPAddressSegmentSeries
        Returns whether the series has a host of zero. If the series has no prefix length, or the prefix length matches the bit count, then returns false. Otherwise, it checks whether all bits past the prefix are zero.
        Specified by:
        includesZeroHost in interface IPAddressSegmentSeries
        Returns:
      • toZeroHost

        public abstract IPAddress toZeroHost​(int prefixLength)
        Description copied from interface: IPAddressSegmentSeries
        Produces the series with host values of 0 for 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.

        This is nearly equivalent to doing the mask (bitwise conjunction) of this address series with the network mask for the given prefix length, but without the possibility of IncompatibleAddressException that can occur when applying a mask to a range of values. Instead, in this case, if the resulting series has a range of values, then the resulting series range boundaries will have host values of 0, but not necessarily the intervening values.

        For instance, you can get the network address for a subnet of prefix length 16 as follows: String addrStr = "1.2.3.4"; IPAddress address = new IPAddressString(addrStr).getAddress(); IPAddress networkAddress = address.toZeroHost(16); //1.2.0.0

        Specified by:
        toZeroHost in interface IPAddressSegmentSeries
        Returns:
      • toMaxHost

        public abstract IPAddress toMaxHost​(int prefixLength)
        Description copied from interface: IPAddressSegmentSeries
        Produces the series with host values of all one bits for 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.

        This is nearly equivalent to doing the bitwise or (bitwise disjunction) of this address series with the network mask for the given prefix length, but without the possibility of IncompatibleAddressException that can occur when applying a mask to a range of values. Instead, in this case, if the resulting series has a range of values, then the resulting series range boundaries will have host values of all ones, but not necessarily the intervening values.

        For instance, you can get the broadcast address for a subnet of prefix length 16 as follows: String addrStr = "1.2.3.4"; IPAddress address = new IPAddressString(addrStr).getAddress(); IPAddress broadcastAddress = address.toMaxHost(16); //1.2.255.255

        Specified by:
        toMaxHost in interface IPAddressSegmentSeries
        Returns:
      • includesMaxHost

        public boolean includesMaxHost()
        Description copied from interface: IPAddressSegmentSeries
        Returns whether the series has a host of all ones. If the series has no prefix length, or the prefix length matches the bit count, then returns false. Otherwise, it checks whether all bits past the prefix are ones.
        Specified by:
        includesMaxHost in interface IPAddressSegmentSeries
        Returns:
      • isSingleNetwork

        public boolean isSingleNetwork()
        Returns true if the network section of the address spans just a single value

        For example, return true for 1.2.3.4/16 and false for 1.2-3.3.4/16

      • toPrefixBlock

        public abstract IPAddress toPrefixBlock()
        Returns the subnet associated with the prefix length of this address. If this address has no prefix length, this address is returned.

        For example, if the address is 1.2.3.4/16 it returns the subnet 1.2.*.* /16

        Specified by:
        toPrefixBlock in interface AddressSegmentSeries
        Specified by:
        toPrefixBlock in interface IPAddressSegmentSeries
        Specified by:
        toPrefixBlock in class Address
        Returns:
        the block of address series for the prefix length
      • getBlockMaskPrefixLength

        public java.lang.Integer getBlockMaskPrefixLength​(boolean network)
        If this address is equivalent to the mask for a CIDR prefix block, it returns that prefix length. Otherwise, it returns null. A CIDR network mask is all 1 bits in the network section and then all 0 bits in the host section. A CIDR host mask is all 0 bits in the network section and then all 1 bits in the host section. The prefix is the length of the network section.

        Also, keep in mind that the prefix length returned by this method is not equivalent to the prefix length used to construct this object. The prefix length used to construct indicates 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 null while the other is not.

        Just like the mask methods which use the lower value for masking, this method applies only to the lower value of the range if this address represents multiple values.

        Parameters:
        network - whether to check if we are a network mask or a host mask
        Returns:
        the prefix length corresponding to this mask, or null if there is no such prefix length
      • getTrailingBitCount

        public int getTrailingBitCount​(boolean network)
        Returns the number of consecutive trailing one or zero bits. If network 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 address represents multiple values.

        Parameters:
        network -
        Returns:
      • getLeadingBitCount

        public int getLeadingBitCount​(boolean network)
        Returns the number of consecutive leading one or zero bits. If network 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 address represents multiple values.

        Parameters:
        network -
        Returns:
      • spanWithSequentialBlocks

        public abstract IPAddress[] spanWithSequentialBlocks​(IPAddress other)
                                                      throws AddressConversionException
        Produces a list of sequential block subnets that span all values from this subnet to the given subnet. The span will cover the sequence of all addresses from the lowest address in both subnets to the highest address in both subnets.

        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 the default conversion is applied to the other address first using toIPv4() or toIPv6()

        The resulting array 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 and other) by converting each to IPAddressRange with toSequentialRange() and them joining them into a single range with IPAddressSeqRange.join(IPAddressSeqRange...)

        When you have multiple subnets, span with:
        IPAddress blocks[] = subnet0.applyToBounds(IPAddress::spanWithSequentialBlocks, subnet1, subnet2, ...);

        See applyToBounds(java.util.function.BiFunction, IPAddress...)

        Parameters:
        other -
        Returns:
        Throws:
        AddressConversionException
      • mergeToPrefixBlocks

        public abstract IPAddress[] mergeToPrefixBlocks​(IPAddress... addresses)
                                                 throws AddressConversionException
        Merges this with the list of addresses to produce the smallest list of prefix blocks.

        For the smallest list of subnets use mergeToSequentialBlocks(IPAddress...).

        If any other address in the list is a different version than this, then the default conversion is applied to the other address first using toIPv4() or toIPv6(), which can result in AddressConversionException

        The resulting array is sorted from lowest address value to highest, regardless of the size of each prefix block.

        In version 5.3.1 and earlier, the result was sorted from single address to smallest blocks to largest blocks. For that ordering, sort with IPAddressSegmentSeries.getPrefixLenComparator():
        Arrays.sort(result, IPAddressSegmentSeries.getPrefixLenComparator());

        The merging process works with sequential blocks. CIDR prefix subnets have just a single sequential block, as does individual addresses. So this method works efficiently for most conventionally-used subnets.

        For example, the subnet ::*:*:*:1-ffff has 281474976710656 sequential blocks. Just like you should avoid iterating through such a large number of blocks, you should avoid using this method to merge such a subnet, rather than a subnet like ::1-ffff:*:*:*:* which has 1 sequential block, or the subnet ::1-ffff:1-ffff:*:*:*:* which has 65535 sequential blocks. You can use getSequentialBlockCount() to get the sequential block count.

        There are alternatives ways to merge into prefix blocks available in this library. Typically this method is most efficient when merging CIDR prefix blocks and/or individual addresses, which is likely to be the case for most users most of the time. It converts to CIDR prefix blocks prior to merging, if not CIDR prefix blocks or individual addresses already.

        When merging a large number of blocks that are not prefix blocks nor individual addresses, it may be more efficient to merge first and then convert to CIDR prefix blocks afterwards. You can use mergeToSequentialBlocks(IPAddress...) to merge, and then span each merged element in the result with IPAddressSegmentSeries.spanWithPrefixBlocks(), giving the same result as this method.

        Sequential ranges provide another option. You can convert to sequential blocks first with sequentialBlockIterator(), then convert each sequential block to IPAddressSeqRange with toSequentialRange(), then join those sequential ranges with IPAddressSeqRange.join(IPAddressSeqRange...), then convert them to CIDR prefix blocks with IPAddressSeqRange.spanWithPrefixBlocks(), giving the same result as this method.

        Parameters:
        addresses - the addresses to merge with this
        Returns:
        Throws:
        AddressConversionException
      • mergeToDualSequentialBlocks

        public static IPAddress.DualIPv4Pv6Arrays mergeToDualSequentialBlocks​(IPAddress... addresses)
        merges the given set of IP addresses and subnets into a minimal number of prefix blocks. This function complements the MergeToPrefixBlock methods of each IP address type. Those instance methods attempt to convert arguments that do not match the IP version of the method receiver, while this function does not. This static method merges every non-null argument into one of the two returned slices.
        Parameters:
        addresses -
        Returns:
      • mergeToDualPrefixBlocks

        public static IPAddress.DualIPv4Pv6Arrays mergeToDualPrefixBlocks​(IPAddress... addresses)
        merges the given set of IP addresses and subnets into a minimal number of prefix blocks. This function complements the MergeToPrefixBlock methods of each IP address type. Those instance methods attempt to convert arguments that do not match the IP version of the method receiver, while this function does not. This static method merges every non-null argument into one of the two returned slices.
        Parameters:
        addresses -
        Returns:
      • mergeToSequentialBlocks

        public abstract IPAddress[] mergeToSequentialBlocks​(IPAddress... addresses)
                                                     throws AddressConversionException
        Merges this with the list of subnets to produce the smallest list of block subnets that are sequential.

        Block subnets come in the form 1-3.1-4.5.6-8, however that 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.

        This list will eliminate overlaps to produce the smallest list of sequential block subnets, which is the same size or smaller than the list of prefix blocks produced by mergeToPrefixBlocks(IPAddress...)

        If the incoming blocks are not sequential, the result could be a longer list, since the list is divided into sequential blocks before merging.

        If any other address in the list is a different version than this, then the default conversion is applied to the other address first using toIPv4() or toIPv6(), which can result in AddressConversionException

        The resulting array is sorted by lower address, regardless of the size of each prefix block.

        In version 5.3.1 and earlier, the result was sorted from single address to smallest blocks to largest blocks. For that ordering, sort with IPAddressSegmentSeries.getPrefixLenComparator():
        Arrays.sort(result, IPAddressSegmentSeries.getPrefixLenComparator());

        See the javadoc for mergeToPrefixBlocks(IPAddress...) for some alternatives for merging subnets.

        Parameters:
        addresses - the addresses to merge with this
        Returns:
        Throws:
        AddressConversionException
      • intersect

        public abstract IPAddress intersect​(IPAddress other)
                                     throws AddressConversionException
        Produces the subnet whose addresses are found in both this and the given subnet argument, or null if no such addresses.

        This is also known as the conjunction of the two sets of addresses.

        If the address is not the same version, the default conversion will be applied using toIPv4() or toIPv6(), and it that fails, AddressConversionException will be thrown.

        Parameters:
        other -
        Returns:
        the subnet containing the addresses found in both this and the given subnet
        Throws:
        AddressConversionException - if the address argument could not be converted to the same address version as this
      • subtract

        public abstract IPAddress[] subtract​(IPAddress other)
                                      throws AddressConversionException
        Subtract 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).

        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.

        If the address is not the same version, the default conversion will be applied using toIPv4() or toIPv6(), and it that fails, AddressConversionException will be thrown.

        Parameters:
        other -
        Returns:
        the difference
        Throws:
        AddressConversionException - if the address argument could not be converted to the same address version as this
      • mask

        public abstract IPAddress mask​(IPAddress mask,
                                       boolean retainPrefix)
                                throws AddressConversionException,
                                       IncompatibleAddressException
        Applies the given mask to all addresses represented by this IPAddress. The mask is applied to all individual addresses. Any existing prefix length is removed beforehand. If the retainPrefix argument is true, then the existing prefix length will be applied to the result.

        If the mask is a different version than this, then the default conversion is applied to the other address first using toIPv4() or toIPv6()

        If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a contiguous range within each segment, then IncompatibleAddressException is thrown.

        Parameters:
        mask -
        Returns:
        Throws:
        IncompatibleAddressException - if this is a range of addresses and applying the mask results in an address that cannot be represented as a contiguous range within each segment
        AddressConversionException - if the address argument could not be converted to the same address version as this
      • maskNetwork

        public abstract IPAddress maskNetwork​(IPAddress mask,
                                              int networkPrefixLength)
                                       throws AddressConversionException,
                                              IncompatibleAddressException
        Applies the given mask to all addresses represented by this IPAddress while also applying the given prefix length at the same time.

        Any existing prefix length is removed as the mask and new prefix length is applied to all individual addresses.

        If the mask is a different version than this, then the default conversion is applied to the other address first using toIPv4() or toIPv6()

        If this represents multiple addresses, and applying the mask to all addresses creates a set of addresses that cannot be represented as a contiguous range within each segment, then IncompatibleAddressException is thrown.

        Throws:
        IncompatibleAddressException - if this is a range of addresses and applying the mask results in an address that cannot be represented as a contiguous range within each segment
        AddressConversionException - if the address argument could not be converted to the same address version as this
      • bitwiseOr

        public abstract IPAddress bitwiseOr​(IPAddress mask,
                                            boolean retainPrefix)
                                     throws AddressConversionException,
                                            IncompatibleAddressException
        Does the bitwise disjunction with this address. Useful when subnetting.

        The mask is applied to all individual addresses, similar to how the method mask(IPAddress, boolean) applies the bitwise conjunction. Any existing prefix length is removed beforehand. If the retainPrefix argument is true, then the existing prefix length will be applied to the result.

        If the mask is a different version than this, then the default conversion is applied to the other address first using toIPv4() or toIPv6()

        If you wish to mask a section of the network, use bitwiseOrNetwork(IPAddress, int)

        For instance, you can get the broadcast address for a subnet as follows: String addrStr = "1.2.3.4/16"; IPAddress address = new IPAddressString(addrStr).getAddress(); IPAddress hostMask = address.getNetwork().getHostMask(address.getNetworkPrefixLength());//0.0.255.255 IPAddress broadcastAddress = address.bitwiseOr(hostMask); //1.2.255.255

        Parameters:
        mask -
        retainPrefix -
        Returns:
        Throws:
        AddressConversionException - if the address argument could not be converted to the same address version as this
        IncompatibleAddressException - if this is a range of addresses and applying the mask results in an address that cannot be represented as a contiguous range within each segment
      • bitwiseOrNetwork

        public abstract IPAddress bitwiseOrNetwork​(IPAddress mask,
                                                   int networkPrefixLength)
                                            throws AddressConversionException,
                                                   IncompatibleAddressException
        Does the bitwise disjunction with this address. Useful when subnetting.

        If the mask is a different version than this, then the default conversion is applied to the other address first using toIPv4() or toIPv6()

        Any existing prefix length is dropped for the new prefix length and the mask is applied up to the end the new prefix length. It is similar to how the maskNetwork(IPAddress, int) method does the bitwise conjunction.

        Parameters:
        mask -
        networkPrefixLength - the new prefix length for the address
        Returns:
        Throws:
        IncompatibleAddressException - if this is a range of addresses and applying the mask results in an address that cannot be represented as a contiguous range within each segment
        AddressConversionException - if the address argument could not be converted to the same address version as this
      • adjustPrefixLength

        public abstract IPAddress adjustPrefixLength​(int adjustment)
        Increases or decreases prefix length by the given increment.

        When prefix length is increased, the bits moved within the prefix become zero. When the prefix is extended beyond the segment series boundary, it is removed. When a prefix length is decreased, the bits moved outside the prefix become zero, and if the entire host address contains the zero address, then the resulting address is determined AddressNetwork.getPrefixConfiguration().

        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

        Specified by:
        adjustPrefixLength in interface AddressSegmentSeries
        Specified by:
        adjustPrefixLength in interface IPAddressSegmentSeries
        Specified by:
        adjustPrefixLength in class Address
        Parameters:
        adjustment -
        Returns:
      • setPrefixLength

        public abstract IPAddress setPrefixLength​(int prefixLength,
                                                  boolean zeroed,
                                                  boolean zeroHostIsBlock)
        Sets the prefix length while allowing the caller to control whether bits moved in or out of the prefix become zero, and whether a zero host for the new prefix bits can be translated into a prefix block. The latter behaviour only applies to the default prefix handling configuration, PREFIXED_ZERO_HOSTS_ARE_SUBNETS. The methods setPrefixLength(int, boolean) and setPrefixLength(int) use a value of true for zeroed and for zeroHostIsBlock.

        For example, when zeroHostIsBlock is true, applying to 1.2.0.0 the prefix length 16 results in 1.2.*.*/16

        Or if you start with 1.2.0.0/24, setting the prefix length to 16 results in a zero host followed by the existing prefix block, which is then converted to a full prefix block, 1.2.*.*/16

        When both zeroed and zeroHostIsBlock are true, applying the prefiix length of 16 to 1.2.4.0/24 also results in a zero host followed by the existing prefix block, which is then converted to a full prefix block, 1.2.*.*/16.

        When both zeroed and zeroHostIsBlock are false, the resulting address always encompasses the same set of addresses as the original, albeit with a different prefix length.

        Parameters:
        prefixLength -
        zeroed -
        zeroHostIsBlock -
        Returns:
      • getMatchesSQLClause

        public void getMatchesSQLClause​(java.lang.StringBuilder builder,
                                        java.lang.String sqlExpression)
        Returns a clause for matching this address.

        If this address is a subnet, this method will attempt to match every address in the subnet. Therefore it is much more efficient to use getNetworkSection().getStartsWithSQLClause() for a CIDR subnet.

        Parameters:
        builder -
        sqlExpression -
      • getMatchesSQLClause

        public void getMatchesSQLClause​(java.lang.StringBuilder builder,
                                        java.lang.String sqlExpression,
                                        IPAddressSQLTranslator translator)
        Returns a clause for matching this address.

        Similar to getMatchesSQLClause(StringBuilder builder, String sqlExpression) but allows you to tailor the SQL produced.

        Parameters:
        builder -
        sqlExpression -
        translator -
      • removeBitCountPrefixLength

        public IPAddress removeBitCountPrefixLength()
        Removes the prefix length from addresses with a prefix length extending to the end of the address.
        Returns: