Package org.antlr.v4.runtime
Class CharStreams
- java.lang.Object
-
- org.antlr.v4.runtime.CharStreams
-
public final class CharStreams extends Object
This class represents the primary interface for creatingCharStream
s from a variety of sources as of 4.7. The motivation was to support Unicode code points > U+FFFF.ANTLRInputStream
andANTLRFileStream
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 theLexer
'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 oldANTLRFileStream
, 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
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static CharStream
fromChannel(ReadableByteChannel channel)
Creates aCharStream
given an openedReadableByteChannel
containing UTF-8 bytes.static CodePointCharStream
fromChannel(ReadableByteChannel channel, int bufferSize, CodingErrorAction decodingErrorAction, String sourceName)
Creates aCharStream
given an openedReadableByteChannel
containing UTF-8 bytes.static CharStream
fromChannel(ReadableByteChannel channel, Charset charset)
Creates aCharStream
given an openedReadableByteChannel
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
fromFileName(String fileName)
Creates aCharStream
given a string containing a path to a UTF-8 file on disk.static CharStream
fromFileName(String fileName, Charset charset)
Creates aCharStream
given a string containing a path to a file on disk and the charset of the bytes contained in the file.static CharStream
fromPath(Path path)
Creates aCharStream
given a path to a UTF-8 encoded file on disk.static CharStream
fromPath(Path path, Charset charset)
Creates aCharStream
given a path to a file on disk and the charset of the bytes contained in the file.static CodePointCharStream
fromReader(Reader r)
Creates aCharStream
given aReader
.static CodePointCharStream
fromReader(Reader r, String sourceName)
Creates aCharStream
given aReader
and its source name.static CharStream
fromStream(InputStream is)
Creates aCharStream
given an openedInputStream
containing UTF-8 bytes.static CharStream
fromStream(InputStream is, Charset charset)
Creates aCharStream
given an openedInputStream
and the charset of the bytes contained in the stream.static CharStream
fromStream(InputStream is, Charset charset, long inputSize)
static CodePointCharStream
fromString(String s)
Creates aCharStream
given aString
.static CodePointCharStream
fromString(String s, String sourceName)
-
-
-
Method Detail
-
fromPath
public static CharStream fromPath(Path path) throws IOException
Creates aCharStream
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
-
fromPath
public static CharStream fromPath(Path path, Charset charset) throws IOException
Creates aCharStream
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 aCharStream
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 aCharStream
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 aCharStream
given an openedInputStream
containing UTF-8 bytes. Reads the entire contents of theInputStream
into the result before returning, then closes theInputStream
.- Throws:
IOException
-
fromStream
public static CharStream fromStream(InputStream is, Charset charset) throws IOException
Creates aCharStream
given an openedInputStream
and the charset of the bytes contained in the stream. Reads the entire contents of theInputStream
into the result before returning, then closes theInputStream
.- Throws:
IOException
-
fromStream
public static CharStream fromStream(InputStream is, Charset charset, long inputSize) throws IOException
- Throws:
IOException
-
fromChannel
public static CharStream fromChannel(ReadableByteChannel channel) throws IOException
Creates aCharStream
given an openedReadableByteChannel
containing UTF-8 bytes. Reads the entire contents of thechannel
into the result before returning, then closes thechannel
.- Throws:
IOException
-
fromChannel
public static CharStream fromChannel(ReadableByteChannel channel, Charset charset) throws IOException
Creates aCharStream
given an openedReadableByteChannel
and the charset of the bytes contained in the channel. Reads the entire contents of thechannel
into the result before returning, then closes thechannel
.- Throws:
IOException
-
fromReader
public static CodePointCharStream fromReader(Reader r) throws IOException
Creates aCharStream
given aReader
. Closes the reader before returning.- Throws:
IOException
-
fromReader
public static CodePointCharStream fromReader(Reader r, String sourceName) throws IOException
Creates aCharStream
given aReader
and its source name. Closes the reader before returning.- Throws:
IOException
-
fromString
public static CodePointCharStream fromString(String s)
Creates aCharStream
given aString
.
-
fromString
public static CodePointCharStream fromString(String s, String sourceName)
-
fromChannel
public static CodePointCharStream fromChannel(ReadableByteChannel channel, int bufferSize, CodingErrorAction decodingErrorAction, String sourceName) throws IOException
Creates aCharStream
given an openedReadableByteChannel
containing UTF-8 bytes. Reads the entire contents of thechannel
into the result before returning, then closes thechannel
.- Throws:
IOException
-
fromChannel
public static CodePointCharStream fromChannel(ReadableByteChannel channel, Charset charset, int bufferSize, CodingErrorAction decodingErrorAction, String sourceName, long inputSize) throws IOException
- Throws:
IOException
-
-