com.github.robtimus.net.ip

Class IPAddressFormatter<IP extends IPAddress<?>>

java.lang.Object

com.github.robtimus.net.ip.IPAddressFormatter<IP>

Type Parameters:

IP - The supported type of IP address.

public abstract class IPAddressFormatter<IP extends IPAddress<?>>
extends Object

Formatter for printing and parsing IP addresses. Instances returned from one of the factory methods or a IPAddressFormatter.Builder are immutable.

Author:

Rob Spoor

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	IPAddressFormatter.Builder<IP extends IPAddress<?>> A builder for formatters for printing and parsing IP addresses.

Method Summary

Modifier and Type	Method and Description
static IPAddressFormatter.Builder<IPAddress<?>>	anyVersion() Returns a new builder for formatters for printing and parsing IP addresses of any version.
static IPAddressFormatter<IPAddress<?>>	anyVersionWithDefaults() Returns a formatter for printing and parsing IP addresses of any version.
abstract <A extends Appendable> A	append(byte[] address, A dest) Appends an IP address to an Appendable.
abstract <A extends Appendable> A	append(IP address, A dest) Appends an IP address to an Appendable.
abstract IPAddressFormat<IP>	asFormat() Returns an IPAddressFormat that delegates to this object.
abstract String	format(byte[] address) Formats an IP address.
StringBuffer	format(byte[] address, StringBuffer sb) Formats an IP address, appending it to a StringBuffer.
StringBuilder	format(byte[] address, StringBuilder sb) Formats an IP address, appending it to a StringBuilder.
abstract String	format(IP address) Formats an IP address.
StringBuffer	format(IP address, StringBuffer sb) Formats an IP address, appending it to a StringBuffer.
StringBuilder	format(IP address, StringBuilder sb) Formats an IP address, appending it to a StringBuilder.
static IPAddressFormatter<IPv4Address>	ipv4() Returns a formatter for printing and parsing IPv4 addresses.
static IPAddressFormatter.Builder<IPv6Address>	ipv6() Returns a new builder for formatters for printing and parsing IPv6 addresses.
static IPAddressFormatter<IPv6Address>	ipv6WithDefaults() Returns a formatter for printing and parsing IPv6 addresses.
IP	parse(CharSequence source) Parses a CharSequence to an IP address.
abstract IP	parse(CharSequence source, int start, int end) Parses a portion of a CharSequence to an IP address.
abstract IP	parse(CharSequence source, ParsePosition position) Attempts to parse a CharSequence to an IP address.
byte[]	parseToBytes(CharSequence source) Parses a CharSequence to an IP address.
abstract byte[]	parseToBytes(CharSequence source, int start, int end) Parses a portion of a CharSequence to an IP address.
abstract byte[]	parseToBytes(CharSequence source, ParsePosition position) Attempts to parse a CharSequence to an IP address.
Optional<IP>	tryParse(CharSequence source) Attempts to parse a CharSequence to an IP address.
abstract Optional<IP>	tryParse(CharSequence source, int start, int end) Attempts to parse a portion of a CharSequence to an IP address.
Optional<byte[]>	tryParseToBytes(CharSequence source) Attempts to parse a CharSequence to an IP address.
abstract Optional<byte[]>	tryParseToBytes(CharSequence source, int start, int end) Attempts to parse a portion of a CharSequence to an IP address.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

format

public StringBuilder format(IP address,
                            StringBuilder sb)

Formats an IP address, appending it to a StringBuilder.

Parameters:

address - The IP address to format.

sb - The StringBuilder to append to.

Returns:

The given StringBuilder.

Throws:

NullPointerException - If the given IP address or StringBuilder is null.

format

public StringBuffer format(IP address,
                           StringBuffer sb)

Formats an IP address, appending it to a StringBuffer.

Parameters:

address - The IP address to format.

sb - The StringBuffer to append to.

Returns:

The given StringBuffer.

Throws:

NullPointerException - If the given IP address or StringBuffer is null.

Since:

1.2

format

public abstract String format(IP address)

Formats an IP address.

Parameters:

address - The IP address to format.

Returns:

The formatted IP address.

Throws:

NullPointerException - If the given IP address is null.

append

public abstract <A extends Appendable> A append(IP address,
                                                A dest)
                                         throws IOException

Appends an IP address to an Appendable.

Type Parameters:

A - The type of Appendable.

Parameters:

address - The IP address to append.

dest - The Appendable to append to.

Returns:

The given Appendable.

Throws:

NullPointerException - If the given IP address or Appendable is null.

IOException - If an I/O error occurs while appending to the Appendable.

Since:

1.1

format

public StringBuilder format(byte[] address,
                            StringBuilder sb)

Formats an IP address, appending it to a StringBuilder.

Parameters:

address - A byte array representing the IP address to format.

sb - The StringBuilder to append to.

Returns:

The given StringBuilder.

Throws:

NullPointerException - If the given array or StringBuilder is null.

IllegalArgumentException - If the length of the given array is invalid.

format

public StringBuffer format(byte[] address,
                           StringBuffer sb)

Formats an IP address, appending it to a StringBuffer.

Parameters:

address - A byte array representing the IP address to format.

sb - The StringBuffer to append to.

Returns:

The given StringBuffer.

Throws:

NullPointerException - If the given array or StringBuffer is null.

IllegalArgumentException - If the length of the given array is invalid.

Since:

1.2

format

public abstract String format(byte[] address)

Formats an IP address.

Parameters:

address - A byte array representing the IP address to format.

Returns:

The formatted IP address.

Throws:

NullPointerException - If the given array is null.

IllegalArgumentException - If the length of the given array is invalid.

append

public abstract <A extends Appendable> A append(byte[] address,
                                                A dest)
                                         throws IOException

Appends an IP address to an Appendable.

Type Parameters:

A - The type of Appendable.

Parameters:

address - A byte array representing the IP address to format.

dest - The Appendable to append to.

Returns:

The given Appendable.

Throws:

NullPointerException - If the given array or Appendable is null.

IllegalArgumentException - If the length of the given array is invalid.

IOException - If an I/O error occurs while appending to the Appendable.

Since:

1.1

parse

public IP parse(CharSequence source)
         throws ParseException

Parses a CharSequence to an IP address.

Parameters:

source - The CharSequence to parse.

Returns:

The parsed IP address.

Throws:

NullPointerException - If the given CharSequence is null.

ParseException - If the CharSequence could not be parsed to an IP address.

parse

public abstract IP parse(CharSequence source,
                         int start,
                         int end)
                  throws ParseException

Parses a portion of a CharSequence to an IP address.

Parameters:

source - The CharSequence to parse.

start - The start index in the CharSequence to start parsing, inclusive.

end - The end index in the CharSequence to end parsing, exclusive.

Returns:

The parsed IP address.

Throws:

NullPointerException - If the given CharSequence is null.

IndexOutOfBoundsException - If the start index is negative, or if the end index is larger than the length of the CharSequence, or if the start index is larger than the end index.

ParseException - If the CharSequence could not be parsed to an IP address.

Since:

1.1

parse

public abstract IP parse(CharSequence source,
                         ParsePosition position)

Attempts to parse a CharSequence to an IP address. Parsing starts at the current index of the given ParsePosition.

If parsing succeeds, the given ParsePosition's index is updated to the index after the last character that was used for parsing. The updated position can be used as a starting point for other parsing.

If parsing fails, the given ParsePosition's index is not modified, but its error index is set to the index of the character that caused parsing to fail.

Parameters:

source - The CharSequence to parse.

position - The ParsePosition to update as described.

Returns:

The parsed IP address if parsing succeeded, or null if parsing fails.

Throws:

NullPointerException - If the given CharSequence or ParsePosition is null.

tryParse

public Optional<IP> tryParse(CharSequence source)

Attempts to parse a CharSequence to an IP address.

Parameters:

source - The CharSequence to parse.

Returns:

An Optional with the parsed IP address if parsing succeeded, or Optional#empty() if parsing fails.

tryParse

public abstract Optional<IP> tryParse(CharSequence source,
                                      int start,
                                      int end)

Attempts to parse a portion of a CharSequence to an IP address.

Parameters:

source - The CharSequence to parse.

start - The start index in the CharSequence to start parsing, inclusive.

end - The end index in the CharSequence to end parsing, exclusive.

Returns:

An Optional with the parsed IP address if parsing succeeded, or Optional#empty() if parsing fails.

Throws:

IndexOutOfBoundsException - If the start index is negative, or if the end index is larger than the length of the CharSequence, or if the start index is larger than the end index (unless if the CharSequence is null).

Since:

1.1

parseToBytes

public byte[] parseToBytes(CharSequence source)
                    throws ParseException

Parses a CharSequence to an IP address.

Parameters:

source - The CharSequence to parse.

Returns:

A byte array representing the parsed IP address.

Throws:

NullPointerException - If the given CharSequence is null.

ParseException - If the CharSequence could not be parsed to an IP address.

parseToBytes

public abstract byte[] parseToBytes(CharSequence source,
                                    int start,
                                    int end)
                             throws ParseException

Parses a portion of a CharSequence to an IP address.

Parameters:

source - The CharSequence to parse.

start - The start index in the CharSequence to start parsing, inclusive.

end - The end index in the CharSequence to end parsing, exclusive.

Returns:

A byte array representing the parsed IP address.

Throws:

NullPointerException - If the given CharSequence is null.

IndexOutOfBoundsException - If the start index is negative, or if the end index is larger than the length of the CharSequence, or if the start index is larger than the end index.

ParseException - If the CharSequence could not be parsed to an IP address.

Since:

1.1

parseToBytes

public abstract byte[] parseToBytes(CharSequence source,
                                    ParsePosition position)

Attempts to parse a CharSequence to an IP address. Parsing starts at the current index of the given ParsePosition.

If parsing succeeds, the given ParsePosition's index is updated to the index after the last character that was used for parsing. The updated position can be used as a starting point for other parsing.

If parsing fails, the given ParsePosition's index is not modified, but its error index is set to the index of the character that caused parsing to fail.

Parameters:

source - The CharSequence to parse.

position - The ParsePosition to update as described.

Returns:

A byte array representing the parsed IP address if parsing succeeded, or null if parsing fails.

Throws:

NullPointerException - If the given CharSequence or ParsePosition is null.

tryParseToBytes

public Optional<byte[]> tryParseToBytes(CharSequence source)

Attempts to parse a CharSequence to an IP address.

Parameters:

source - The CharSequence to parse.

Returns:

An Optional with a byte array representing the parsed IP address if parsing succeeded, or Optional#empty() if parsing fails.

tryParseToBytes

public abstract Optional<byte[]> tryParseToBytes(CharSequence source,
                                                 int start,
                                                 int end)

Attempts to parse a portion of a CharSequence to an IP address.

Parameters:

source - The CharSequence to parse.

start - The start index in the CharSequence to start parsing, inclusive.

end - The end index in the CharSequence to end parsing, exclusive.

Returns:

An Optional with a byte array representing the parsed IP address if parsing succeeded, or Optional#empty() if parsing fails.

Throws:

IndexOutOfBoundsException - If the start index is negative, or if the end index is larger than the length of the CharSequence, or if the start index is larger than the end index (unless if the CharSequence is null).

Since:

1.1

asFormat

public abstract IPAddressFormat<IP> asFormat()

Returns an IPAddressFormat that delegates to this object. As a result, its formatting and parsing with a ParsePosition will be identical to the printing and parsing of this object. However, its parseObject(String) method behaves slightly differently - as per the contract of Format.parseObject(String), it may not use the entire input for its parsing. Its parse(CharSequence) method on the other hand will use the entire input.

Returns:

An IPAddressFormat that delegates to this object.

Since:

1.2

See Also:

parse(CharSequence, ParsePosition), format(IPAddress, StringBuffer), format(byte[], StringBuffer)

ipv4

public static IPAddressFormatter<IPv4Address> ipv4()

Returns a formatter for printing and parsing IPv4 addresses.

Returns:

A formatter for printing and parsing IPv4 addresses.

ipv6WithDefaults

public static IPAddressFormatter<IPv6Address> ipv6WithDefaults()

Returns a formatter for printing and parsing IPv6 addresses. When printing IPv6 addresses, it will use a short format that will omit the longest consecutive section of zeroes. For example, it will print ::1 or :: and not 0:0:0:0:0:0:0:1 or 0:0:0:0:0:0:0:0.

Returns:

A formatter for printing and parsing IPv6 addresses.

anyVersionWithDefaults

public static IPAddressFormatter<IPAddress<?>> anyVersionWithDefaults()

Returns a formatter for printing and parsing IP addresses of any version. When printing IPv6 addresses, it will use a short format that will omit the longest consecutive section of zeroes. For example, it will print ::1 or :: and not 0:0:0:0:0:0:0:1 or 0:0:0:0:0:0:0:0.

Returns:

A formatter for printing and parsing IP addresses of any version.

ipv6

public static IPAddressFormatter.Builder<IPv6Address> ipv6()

Returns a new builder for formatters for printing and parsing IPv6 addresses.

Note: the builder specific settings are only relevant for printing. If only parsing is required, use ipv6WithDefaults() instead.

Returns:

A new builder for formatters for printing and parsing IPv6 addresses.

anyVersion

public static IPAddressFormatter.Builder<IPAddress<?>> anyVersion()

Returns a new builder for formatters for printing and parsing IP addresses of any version.

Note: the builder specific settings are only relevant for printing. If only parsing is required, use ipv6WithDefaults() instead.

Returns:

A new builder for formatters for printing and parsing IP addresses of any version.