com.upokecenter.text

Class CharacterReader

java.lang.Object

com.upokecenter.text.CharacterReader

All Implemented Interfaces:

ICharacterInput

public final class CharacterReader
extends Object
implements ICharacterInput

A general-purpose character input for reading text from byte streams and text strings. When reading byte streams, this class supports the UTF-8 character encoding by default, but can be configured to support UTF-16 and UTF-32 as well.

Constructor Summary

Constructors

Constructor and Description
CharacterReader(InputStream stream) Initializes a new instance of the CharacterReader class; will read the stream as UTF-8, skip the byte-order mark (U + FEFF) if it appears first in the stream, and replace invalid byte sequences with replacement characters (U + FFFD).
CharacterReader(InputStream stream, int mode) Initializes a new instance of the CharacterReader class; will skip the byte-order mark (U + FEFF) if it appears first in the stream and replace invalid byte sequences with replacement characters (U + FFFD).
CharacterReader(InputStream stream, int mode, boolean errorThrow) Initializes a new instance of the CharacterReader class; will skip the byte-order mark (U + FEFF) if it appears first in the stream.
CharacterReader(InputStream stream, int mode, boolean errorThrow, boolean dontSkipUtf8Bom) Initializes a new instance of the CharacterReader class.
CharacterReader(String str) Initializes a new instance of the CharacterReader class using a Unicode 16-bit string; if the string begins with a byte-order mark (U + FEFF), it won't be skipped, and any unpaired surrogate code points (U+D800 to U + DFFF) in the string are replaced with replacement characters (U + FFFD).
CharacterReader(String str, boolean skipByteOrderMark) Initializes a new instance of the CharacterReader class using a Unicode 16-bit string; any unpaired surrogate code points (U + D800 to U + DFFF) in the string are replaced with replacement characters (U + FFFD).
CharacterReader(String str, boolean skipByteOrderMark, boolean errorThrow) Initializes a new instance of the CharacterReader class using a Unicode 16-bit string.
CharacterReader(String str, int offset, int length) Initializes a new instance of the CharacterReader class.
CharacterReader(String str, int offset, int length, boolean skipByteOrderMark, boolean errorThrow) Initializes a new instance of the CharacterReader class.

Method Summary

Modifier and Type	Method and Description
int	Read(int[] chars, int index, int length) Reads a series of code points from a Unicode stream or a string.
int	ReadChar() Reads the next character from a Unicode stream or a string.

Methods inherited from class java.lang.Object

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

Constructor Detail

CharacterReader

public CharacterReader(String str)

Initializes a new instance of the CharacterReader class using a Unicode 16-bit string; if the string begins with a byte-order mark (U + FEFF), it won't be skipped, and any unpaired surrogate code points (U+D800 to U + DFFF) in the string are replaced with replacement characters (U + FFFD).

Parameters:

str - The string to read.

Throws:

NullPointerException - The parameter str is null.

CharacterReader

public CharacterReader(String str,
                       boolean skipByteOrderMark)

Initializes a new instance of the CharacterReader class using a Unicode 16-bit string; any unpaired surrogate code points (U + D800 to U + DFFF) in the string are replaced with replacement characters (U + FFFD).

Parameters:

str - The string to read.

skipByteOrderMark - If true and the string begins with a byte-order mark (U + FEFF), will skip that code point as it reads the string.

Throws:

NullPointerException - The parameter str is null.

CharacterReader

public CharacterReader(String str,
                       boolean skipByteOrderMark,
                       boolean errorThrow)

Initializes a new instance of the CharacterReader class using a Unicode 16-bit string.

Parameters:

str - The string to read.

skipByteOrderMark - If true and the string begins with a byte-order mark (U + FEFF), will skip that code point as it reads the string.

errorThrow - If true, will throw an exception if unpaired surrogate code points (U + D800 to U + DFFF) are found in the string. If false, replaces those byte sequences with replacement characters (U + FFFD) as the stream is read.

Throws:

NullPointerException - The parameter str is null.

CharacterReader

public CharacterReader(String str,
                       int offset,
                       int length)

Initializes a new instance of the CharacterReader class.

Parameters:

str - The parameter str is a text string.

offset - A zero-based index showing where the desired portion of str begins.

length - The number of elements in the desired portion of str (but not more than str 's length).

CharacterReader

public CharacterReader(String str,
                       int offset,
                       int length,
                       boolean skipByteOrderMark,
                       boolean errorThrow)

Initializes a new instance of the CharacterReader class.

Parameters:

str - The parameter str is a text string.

offset - A zero-based index showing where the desired portion of str begins.

length - The number of elements in the desired portion of str (but not more than str 's length).

skipByteOrderMark - If true and the string begins with a byte-order mark (U + FEFF), will skip that code point as it reads the string.

errorThrow - If true, will throw an exception if unpaired surrogate code points (U + D800 to U + DFFF) are found in the string. If false, replaces those byte sequences with replacement characters (U + FFFD) as the stream is read.

Throws:

NullPointerException - The parameter str is null.

CharacterReader

public CharacterReader(InputStream stream)

Initializes a new instance of the CharacterReader class; will read the stream as UTF-8, skip the byte-order mark (U + FEFF) if it appears first in the stream, and replace invalid byte sequences with replacement characters (U + FFFD).

Parameters:

stream - A readable data stream.

Throws:

NullPointerException - The parameter stream is null.

CharacterReader

public CharacterReader(InputStream stream,
                       int mode,
                       boolean errorThrow)

Initializes a new instance of the CharacterReader class; will skip the byte-order mark (U + FEFF) if it appears first in the stream.

Parameters:

stream - A readable byte stream.

mode - The method to use when detecting encodings other than UTF-8 in the byte stream. This usually involves checking whether the stream begins with a byte-order mark (BOM, U + FEFF) or a non-zero basic code point (NZB, U + 0001 to U + 007F) before reading the rest of the stream. This value can be one of the following:

• 0: UTF-8 only.
• 1: Detect UTF-16 using BOM or NZB, otherwise UTF-8.
• 2: Detect UTF-16/UTF-32 using BOM or NZB, otherwise UTF-8. (Tries to detect UTF-32 first.)
• 3: Detect UTF-16 using BOM, otherwise UTF-8.
• 4: Detect UTF-16/UTF-32 using BOM, otherwise UTF-8. (Tries to detect UTF-32 first.)

.

errorThrow - If true, will throw an exception if invalid byte sequences (in the detected encoding) are found in the byte stream. If false, replaces those byte sequences with replacement characters (U + FFFD) as the stream is read.

Throws:

NullPointerException - The parameter stream is null.

CharacterReader

public CharacterReader(InputStream stream,
                       int mode)

Initializes a new instance of the CharacterReader class; will skip the byte-order mark (U + FEFF) if it appears first in the stream and replace invalid byte sequences with replacement characters (U + FFFD).

Parameters:

stream - A readable byte stream.

mode - The method to use when detecting encodings other than UTF-8 in the byte stream. This usually involves checking whether the stream begins with a byte-order mark (BOM, U + FEFF) or a non-zero basic code point (NZB, U + 0001 to U + 007F) before reading the rest of the stream. This value can be one of the following:

• 0: UTF-8 only.
• 1: Detect UTF-16 using BOM or NZB, otherwise UTF-8.
• 2: Detect UTF-16/UTF-32 using BOM or NZB, otherwise UTF-8. (Tries to detect UTF-32 first.)
• 3: Detect UTF-16 using BOM, otherwise UTF-8.
• 4: Detect UTF-16/UTF-32 using BOM, otherwise UTF-8. (Tries to detect UTF-32 first.)

.

Throws:

NullPointerException - The parameter stream is null.

CharacterReader

public CharacterReader(InputStream stream,
                       int mode,
                       boolean errorThrow,
                       boolean dontSkipUtf8Bom)

Initializes a new instance of the CharacterReader class.

Parameters:

stream - A readable byte stream.

mode - The method to use when detecting encodings other than UTF-8 in the byte stream. This usually involves checking whether the stream begins with a byte-order mark (BOM, U + FEFF) or a non-zero basic code point (NZB, U + 0001 to U + 007F) before reading the rest of the stream. This value can be one of the following:

• 0: UTF-8 only.
• 1: Detect UTF-16 using BOM or NZB, otherwise UTF-8.
• 2: Detect UTF-16/UTF-32 using BOM or NZB, otherwise UTF-8. (Tries to detect UTF-32 first.)
• 3: Detect UTF-16 using BOM, otherwise UTF-8.
• 4: Detect UTF-16/UTF-32 using BOM, otherwise UTF-8. (Tries to detect UTF-32 first.)

.

errorThrow - If true, will throw an exception if invalid byte sequences (in the detected encoding) are found in the byte stream. If false, replaces those byte sequences with replacement characters (U + FFFD) as the stream is read.

dontSkipUtf8Bom - If the stream is detected as UTF-8 and this parameter is true, won't skip the BOM character if it occurs at the start of the stream.

Throws:

NullPointerException - The parameter stream is null.

Method Detail

Read

public int Read(int[] chars,
                int index,
                int length)

Reads a series of code points from a Unicode stream or a string.

Specified by:

Read in interface ICharacterInput

Parameters:

chars - An array where the code points that were read will be stored.

index - A zero-based index showing where the desired portion of chars begins.

length - The number of elements in the desired portion of chars (but not more than chars 's length).

Returns:

The number of code points read from the stream. This can be less than the length parameter if the end of the stream is reached.

Throws:

NullPointerException - The parameter chars is null.

IllegalArgumentException - Either index or length is less than 0 or greater than chars 's length, or chars 's length minus index is less than length.

ReadChar

public int ReadChar()

Reads the next character from a Unicode stream or a string.

Specified by:

ReadChar in interface ICharacterInput

Returns:

The next character, or -1 if the end of the string or stream was reached.