com.aquenos.epics.jackie.common.util

Class NullTerminatedStringUtil

java.lang.Object

com.aquenos.epics.jackie.common.util.NullTerminatedStringUtil

public final class NullTerminatedStringUtil
extends java.lang.Object

Utility methods for converting between Java strings and the null-terminated byte-sequences used over the wire.

Author:

Sebastian Marsching

Method Summary

Modifier and Type	Method and Description
static java.lang.String	nullTerminatedBytesToString(byte[] bytes, java.nio.charset.Charset encoding) Converts a null-terminated array of bytes to a string.
static java.lang.String	nullTerminatedBytesToString(byte[] bytes, java.nio.charset.Charset encoding, boolean strict) Converts a null-terminated array of bytes to a string.
static java.lang.String	nullTerminatedBytesToString(byte[] bytes, int offset, int length, java.nio.charset.Charset encoding, boolean strict) Converts a null-terminated part of an array of bytes to a string.
static Pair<byte[],java.lang.Integer>	stringToSizeLimitedNullTerminatedBytesOrNull(java.lang.String string, int maximumLength, java.nio.charset.Charset encoding) Converts a string to an array of null-terminated bytes.
static Pair<byte[],java.lang.Integer>	stringToSizeLimitedNullTerminatedBytesOrNull(java.lang.String string, int maximumLength, int alignTo, java.nio.charset.Charset encoding) Converts a string to an array of null-terminated bytes.
static Pair<byte[],java.lang.Integer>	stringToTruncatedNullTerminatedBytes(java.lang.String string, int maximumLength, java.nio.charset.Charset encoding) Converts a string to an array of null-terminated bytes, truncating the string if necessary.
static Pair<byte[],java.lang.Integer>	stringToTruncatedNullTerminatedBytes(java.lang.String string, int maximumLength, int alignTo, java.nio.charset.Charset encoding) Converts a string to an array of null-terminated bytes, truncating the string if necessary.
static byte[]	stringToTruncatedNullTerminatedFixedBytes(java.lang.String string, int fixedLength, java.nio.charset.Charset encoding) Converts a string to an array of null-terminated bytes, truncating the string if necessary.

Methods inherited from class java.lang.Object

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

Method Detail

nullTerminatedBytesToString

public static java.lang.String nullTerminatedBytesToString(byte[] bytes,
                                                           int offset,
                                                           int length,
                                                           java.nio.charset.Charset encoding,
                                                           boolean strict)

Converts a null-terminated part of an array of bytes to a string. This method is suitable for converting a string received from the network to a Java string. Only bytes that appear before the first null-byte are used. If there is no null-byte, the behavior depends on the strict option.

Parameters:

bytes - array of bytes

offset - offset into the bytes array. This method will start reading at this position.

length - maximum number of bytes that should be read from the bytes array.

encoding - character set to use for converting the bytes to a string.

strict - if true, this method throws an IllegalArgumentException if the string is not null terminated (there is no null byte in the range denoted by offset and length. If false, all bytes are used for the string (an implicit null byte after the end of the byte range is assumed).

Returns:

string representing the specified elements of the byte array that precede the first null-byte.

Throws:

java.lang.IndexOutOfBoundsException - if offset + length exceed the size of bytes.

nullTerminatedBytesToString

public static java.lang.String nullTerminatedBytesToString(byte[] bytes,
                                                           java.nio.charset.Charset encoding,
                                                           boolean strict)

Converts a null-terminated array of bytes to a string. This method is suitable for converting a string received from the network to a Java string. Only bytes that appear before the first null-byte are used. If there is no null-byte, the behavior depends on the strict option.

Parameters:

bytes - array of bytes

encoding - character set to use for converting the bytes to a string.

strict - if true, this method throws an IllegalArgumentException if the string is not null terminated. If false, all bytes are used for the string (an implicit null byte after the end of the byte array is assumed).

Returns:

string representing the elements of the byte array that precede the first null-byte.

nullTerminatedBytesToString

public static java.lang.String nullTerminatedBytesToString(byte[] bytes,
                                                           java.nio.charset.Charset encoding)

Converts a null-terminated array of bytes to a string. This method is suitable for converting a string received from the network to a Java string. Only bytes that appear before the first null-byte are used. If there is no null-byte, all bytes are used.

Parameters:

bytes - array of bytes

encoding - character set to use for converting the bytes to a string.

Returns:

string representing the elements of the byte array that precede the first null-byte.

stringToTruncatedNullTerminatedBytes

public static Pair<byte[],java.lang.Integer> stringToTruncatedNullTerminatedBytes(java.lang.String string,
                                                                                  int maximumLength,
                                                                                  int alignTo,
                                                                                  java.nio.charset.Charset encoding)

Converts a string to an array of null-terminated bytes, truncating the string if necessary. The resulting array is never longer than maximumLength and always has at least one terminating null-byte.

Parameters:

string - the string that shall be converted to bytes.

maximumLength - the maximum length of the resulting byte array (including the terminating null-byte).

alignTo - number of bytes that the string length (including the terminating null-bytes) should be aligned to. This means that some additional null-bytes will be added to match the alignment if needed. The total length is still guaranteed to be less than or equal to maximumLength.

encoding - the character set to be used for converting the string.

Returns:

a pair of a byte array containing the null-terminated and truncated (if needed) string and an integer specifying the number of bytes that are needed to store the string (including the first null-byte).

Throws:

java.lang.IllegalArgumentException - if maximumLength is negative, alignTo is less than or equal to zero, or maximumLength is less than alignTo.

stringToTruncatedNullTerminatedBytes

public static Pair<byte[],java.lang.Integer> stringToTruncatedNullTerminatedBytes(java.lang.String string,
                                                                                  int maximumLength,
                                                                                  java.nio.charset.Charset encoding)

Converts a string to an array of null-terminated bytes, truncating the string if necessary. The resulting array is never longer than maximumLength and always has at least one terminating null-byte.

Parameters:

string - the string that shall be converted to bytes.

maximumLength - the maximum length of the resulting byte array (including the terminating null-byte).

encoding - the character set to be used for converting the string.

Returns:

a pair of a byte array containing the null-terminated and truncated (if needed) string and an integer specifying the number of bytes that are needed to store the string (including the first null-byte).

Throws:

java.lang.IllegalArgumentException - if maximumLength is less than or equal to zero.

stringToTruncatedNullTerminatedFixedBytes

public static byte[] stringToTruncatedNullTerminatedFixedBytes(java.lang.String string,
                                                               int fixedLength,
                                                               java.nio.charset.Charset encoding)

Converts a string to an array of null-terminated bytes, truncating the string if necessary. The resulting array has exactly fixedLength bytes. If the string is shorter than the space available in the array, the remaining space is filled with null bytes.

Parameters:

string - the string that shall be converted to bytes.

fixedLength - the length of the resulting byte array (including the terminating null-byte).

encoding - the character set to be used for converting the string.

Returns:

a byte array containing the null-terminated and truncated (if needed) string

Throws:

java.lang.IllegalArgumentException - if fixedLength is less than or equal to zero.

stringToSizeLimitedNullTerminatedBytesOrNull

public static Pair<byte[],java.lang.Integer> stringToSizeLimitedNullTerminatedBytesOrNull(java.lang.String string,
                                                                                          int maximumLength,
                                                                                          int alignTo,
                                                                                          java.nio.charset.Charset encoding)

Converts a string to an array of null-terminated bytes. The resulting array is never longer than maximumLength and always has at least one terminating null-byte. If the string is too long to fit into maximumLength bytes, null is returned.

Parameters:

string - the string that shall be converted to bytes.

maximumLength - the maximum length of the resulting byte array (including the terminating null-byte).

alignTo - number of bytes that the string length (including the terminating null-bytes) should be aligned to. This means that some additional null-bytes will be added to match the alignment if needed. The total length is still guaranteed to be less than or equal to maximumLength.

encoding - the character set to be used for converting the string.

Returns:

a pair of a byte array containing the null-terminated string and an integer specifying the number of bytes that are needed to store the string (including the first null-byte). The return value is null if the byte representation of the string (including one terminating null-byte) is longer than maximumLength.

Throws:

java.lang.IllegalArgumentException - if maximumLength is negative or alignTo is less than or equal to zero.

stringToSizeLimitedNullTerminatedBytesOrNull

public static Pair<byte[],java.lang.Integer> stringToSizeLimitedNullTerminatedBytesOrNull(java.lang.String string,
                                                                                          int maximumLength,
                                                                                          java.nio.charset.Charset encoding)

Converts a string to an array of null-terminated bytes. The resulting array is never longer than maximumLength and always has at least one terminating null-byte. If the string is too long to fit into maximumLength bytes, null is returned.

Parameters:

string - the string that shall be converted to bytes.

maximumLength - the maximum length of the resulting byte array (including the terminating null-byte).

encoding - the character set to be used for converting the string.

Returns:

a pair of a byte array containing the null-terminated string and an integer specifying the number of bytes that are needed to store the string (including the first null-byte). The return value is null if the byte representation of the string (including one terminating null-byte) is longer than maximumLength.

Throws:

java.lang.IllegalArgumentException - if maximumLength is negative.