org.dellroad.stuff.string
Class StringEncoder

java.lang.Object
  org.dellroad.stuff.string.StringEncoder

public final class StringEncoder
extends Object

Encodes/decodes Java strings, escaping control and XML-invalid characters.

Method Summary

static String	decode(String text) Decode a string encoded by encode(java.lang.String, boolean).
static String	dequote(String quotedString) Dequote a string previously enquoted by enquote(java.lang.String).
static String	encode(String value, boolean escapeTABNLCR) Encode a string, escaping control and XML-invalid characters.
static String	enquote(byte[] data, int off, int len) Enquote bytes, treating them as an ASCII string.
static String	enquote(String string) Enquote a string.
static int	enquotedLength(String string) Determine the length of a string previously enquoted by enquote(java.lang.String) when it appears as the prefix of a longer string.
static boolean	isValidXMLChar(char ch) Determine if the given character is a valid XML character according to the XML 1.0 specification.

Methods inherited from class java.lang.Object

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

Method Detail

encode

public static String encode(String value,
                            boolean escapeTABNLCR)

Encode a string, escaping control and XML-invalid characters. Whether tab, newline, and carriage return are escaped is optional; these are the three control characters that are valid inside XML documents.

Characters are escaped using \uNNNN notation like Java unicode characters, e.g., 0x001f would appear in the encoded string as \u001f. Normal Java backslash escapes are used for tab, newline, carriage return, backspace, and formfeed. Backslash characters are themselves encoded with a double backslash.

Parameters:

value - string to encode (possibly null)

escapeTABNLCR - escape tab, newline, and carriage return characters as well

Returns:

the encoded version of value, or null if value was null

See Also:

decode(java.lang.String), isValidXMLChar(char)

decode

public static String decode(String text)

Decode a string encoded by encode(java.lang.String, boolean).

The parsing is strict; any ill-formed backslash escape sequence (i.e., not of the form \uNNNN, \b, \t, \n, \f, \r or \\) will cause an exception to be thrown.

Parameters:

text - string to decode (possibly null)

Returns:

the decoded version of text, or null if text was null

Throws:

IllegalArgumentException - if text contains an invalid escape sequence

See Also:

encode(java.lang.String, boolean)

enquote

public static String enquote(String string)

Enquote a string. Functions like encode(string, true) but in addition the resulting string is surrounded by double quotes and double quotes in the string are backslash-escaped.

Note: the strings returned by this method are not suitable for decoding by decode(java.lang.String). Use dequote(java.lang.String) instead.

enquote

public static String enquote(byte[] data,
                             int off,
                             int len)

Enquote bytes, treating them as an ASCII string.

See Also:

enquote(String)

dequote

public static String dequote(String quotedString)

Dequote a string previously enquoted by enquote(java.lang.String).

Parameters:

quotedString - a string returned by enquote(java.lang.String)

Throws:

IllegalArgumentException - if quotedString has an invalid format (i.e., it could not have ever been returned by enquote(java.lang.String))

enquotedLength

public static int enquotedLength(String string)

Determine the length of a string previously enquoted by enquote(java.lang.String) when it appears as the prefix of a longer string. This method assumes that the prefix is a valid quoted string; use dequote(java.lang.String) to verify.

Parameters:

string - a string containing a prefix returned by enquote(java.lang.String)

Throws:

IllegalArgumentException - if a starting or terminating quote character is not found

isValidXMLChar

public static boolean isValidXMLChar(char ch)

Determine if the given character is a valid XML character according to the XML 1.0 specification.

Valid characters are tab, newline, carriage return, and characters in the ranges \u0020 - \ud7ff and \ue000 - \fffdf (inclusive).

See Also:

The XML 1.0 Specification