Package org.antlr.v4.runtime

Enum Class CharStreams

java.lang.Object

java.lang.Enum<CharStreams>

org.antlr.v4.runtime.CharStreams

All Implemented Interfaces:

Serializable, Comparable<CharStreams>, Constable

public enum CharStreams
extends Enum<CharStreams>

This class represents the primary interface for creating CharStreams from a variety of sources as of 4.7. The motivation was to support Unicode code points > U+FFFF. ANTLRInputStream and ANTLRFileStream are now deprecated in favor of the streams created by this interface. DEPRECATED: new ANTLRFileStream("myinputfile") NEW: CharStreams.fromFileName("myinputfile") WARNING: If you use both the deprecated and the new streams, you will see a nontrivial performance degradation. This speed hit is because the Lexer's internal code goes from a monomorphic to megamorphic dynamic dispatch to get characters from the input stream. Java's on-the-fly compiler (JIT) is unable to perform the same optimizations so stick with either the old or the new streams, if performance is a primary concern. See the extreme debugging and spelunking needed to identify this issue in our timing rig: https://github.com/antlr/antlr4/pull/1781 The ANTLR character streams still buffer all the input when you create the stream, as they have done for ~20 years. If you need unbuffered access, please note that it becomes challenging to create parse trees. The parse tree has to point to tokens which will either point into a stale location in an unbuffered stream or you have to copy the characters out of the buffer into the token. That defeats the purpose of unbuffered input. Per the ANTLR book, unbuffered streams are primarily useful for processing infinite streams *during the parse.* The new streams also use 8-bit buffers when possible so this new interface supports character streams that use half as much memory as the old ANTLRFileStream, which assumed 16-bit characters. A big shout out to Ben Hamilton (github bhamiltoncx) for his superhuman efforts across all targets to get true Unicode 3.1 support for U+10FFFF.

Since:

4.7

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Field Summary

Fields

Modifier and Type	Field	Description
private static final int	DEFAULT_BUFFER_SIZE

Constructor Summary

Constructors

Modifier	Constructor	Description
private	CharStreams()

Method Summary

Modifier and Type	Method	Description
static CodePointBuffer	bufferFromChannel(ReadableByteChannel channel, Charset charset, int bufferSize, CodingErrorAction decodingErrorAction, long inputSize)
static CharStream	fromChannel(ReadableByteChannel channel)	Creates a CharStream given an opened ReadableByteChannel containing UTF-8 bytes.
static CodePointCharStream	fromChannel(ReadableByteChannel channel, int bufferSize, CodingErrorAction decodingErrorAction, String sourceName)	Creates a CharStream given an opened ReadableByteChannel containing UTF-8 bytes.
static CharStream	fromChannel(ReadableByteChannel channel, Charset charset)	Creates a CharStream given an opened ReadableByteChannel and the charset of the bytes contained in the channel.
static CodePointCharStream	fromChannel(ReadableByteChannel channel, Charset charset, int bufferSize, CodingErrorAction decodingErrorAction, String sourceName, long inputSize)
static CharStream	fromFile(File file)	Creates a CharStream given a path to a UTF-8 encoded file on disk.
static CharStream	fromFile(File file, Charset charset)	Creates a CharStream given a path to a file on disk and the charset of the bytes contained in the file.
static CharStream	fromFileName(String fileName)	Creates a CharStream given a string containing a path to a UTF-8 file on disk.
static CharStream	fromFileName(String fileName, Charset charset)	Creates a CharStream given a string containing a path to a file on disk and the charset of the bytes contained in the file.
static CodePointCharStream	fromReader(Reader r)	Creates a CharStream given a Reader.
static CodePointCharStream	fromReader(Reader r, String sourceName)	Creates a CharStream given a Reader and its source name.
static CharStream	fromStream(InputStream is)	Creates a CharStream given an opened InputStream containing UTF-8 bytes.
static CharStream	fromStream(InputStream is, Charset charset)	Creates a CharStream given an opened InputStream and the charset of the bytes contained in the stream.
static CharStream	fromStream(InputStream is, Charset charset, String sourceName, long inputSize)
static CodePointCharStream	fromString(String s)	Creates a CharStream given a String.
static CodePointCharStream	fromString(String s, String sourceName)	Creates a CharStream given a String and the sourceName from which it came.
static CharStreams	valueOf(String name)	Returns the enum constant of this class with the specified name.
static CharStreams[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Details

DEFAULT_BUFFER_SIZE

private static final int DEFAULT_BUFFER_SIZE

See Also:

• Constant Field Values

Constructor Details

CharStreams

private CharStreams()

Method Details

values

public static CharStreams[] values()

Returns an array containing the constants of this enum class, in the order they are declared.

Returns:

an array containing the constants of this enum class, in the order they are declared

valueOf

public static CharStreams valueOf(String name)

Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum class has no constant with the specified name

NullPointerException - if the argument is null

fromFile

public static CharStream fromFile(File file)
                           throws IOException

Creates a CharStream given a path to a UTF-8 encoded file on disk. Reads the entire contents of the file into the result before returning.

Throws:

IOException

fromFile

public static CharStream fromFile(File file,
 Charset charset)
                           throws IOException

Creates a CharStream given a path to a file on disk and the charset of the bytes contained in the file. Reads the entire contents of the file into the result before returning.

Throws:

IOException

fromFileName

public static CharStream fromFileName(String fileName)
                               throws IOException

Creates a CharStream given a string containing a path to a UTF-8 file on disk. Reads the entire contents of the file into the result before returning.

Throws:

IOException

fromFileName

public static CharStream fromFileName(String fileName,
 Charset charset)
                               throws IOException

Creates a CharStream given a string containing a path to a file on disk and the charset of the bytes contained in the file. Reads the entire contents of the file into the result before returning.

Throws:

IOException

fromStream

public static CharStream fromStream(InputStream is)
                             throws IOException

Creates a CharStream given an opened InputStream containing UTF-8 bytes. Reads the entire contents of the InputStream into the result before returning, then closes the InputStream.

Throws:

IOException

fromStream

public static CharStream fromStream(InputStream is,
 Charset charset)
                             throws IOException

Creates a CharStream given an opened InputStream and the charset of the bytes contained in the stream. Reads the entire contents of the InputStream into the result before returning, then closes the InputStream.

Throws:

IOException

fromStream

public static CharStream fromStream(InputStream is,
 Charset charset,
 String sourceName,
 long inputSize)
                             throws IOException

Throws:

IOException

fromChannel

public static CharStream fromChannel(ReadableByteChannel channel)
                              throws IOException

Creates a CharStream given an opened ReadableByteChannel containing UTF-8 bytes. Reads the entire contents of the channel into the result before returning, then closes the channel.

Throws:

IOException

fromChannel

public static CharStream fromChannel(ReadableByteChannel channel,
 Charset charset)
                              throws IOException

Creates a CharStream given an opened ReadableByteChannel and the charset of the bytes contained in the channel. Reads the entire contents of the channel into the result before returning, then closes the channel.

Throws:

IOException

fromReader

public static CodePointCharStream fromReader(Reader r)
                                      throws IOException

Creates a CharStream given a Reader. Closes the reader before returning.

Throws:

IOException

fromReader

public static CodePointCharStream fromReader(Reader r,
 String sourceName)
                                      throws IOException

Creates a CharStream given a Reader and its source name. Closes the reader before returning.

Throws:

IOException

fromString

public static CodePointCharStream fromString(String s)

Creates a CharStream given a String.

fromString

public static CodePointCharStream fromString(String s,
 String sourceName)

Creates a CharStream given a String and the sourceName from which it came.

UTF-16 code units are converted directly into CodePointBuffer's compact byte / char / int storage via CodePointBuffer.Builder.append(String). That path shares the same conversion state machine as CodePointBuffer.Builder.append(CharBuffer) (including read-only CharBuffer.wrap(CharSequence) views) and does not allocate a temporary mutable CharBuffer or char array solely to feed the builder.

fromChannel

public static CodePointCharStream fromChannel(ReadableByteChannel channel,
 int bufferSize,
 CodingErrorAction decodingErrorAction,
 String sourceName)
                                       throws IOException

Creates a CharStream given an opened ReadableByteChannel containing UTF-8 bytes. Reads the entire contents of the channel into the result before returning, then closes the channel.

Throws:

IOException

fromChannel

public static CodePointCharStream fromChannel(ReadableByteChannel channel,
 Charset charset,
 int bufferSize,
 CodingErrorAction decodingErrorAction,
 String sourceName,
 long inputSize)
                                       throws IOException

Throws:

IOException

bufferFromChannel

public static CodePointBuffer bufferFromChannel(ReadableByteChannel channel,
 Charset charset,
 int bufferSize,
 CodingErrorAction decodingErrorAction,
 long inputSize)
                                         throws IOException

Throws:

IOException