|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Objectjava.io.Reader
org.tbull.util.CharSequenceReader
public class CharSequenceReader
Like StringReader
, but reads arbitrary CharSequence
s and is unsynchronized.
StringReader
has some weird behaviour. Not only are all methods synchronized (which may or may not
be desirable), also it throws IOException
s around without reason. And it is very sloppily documented.
You have to read the source code to find out the aforementioned facts.
This class is not synchronized, you can decide yourself if you need sync. It does not throw checked
exceptions except for mark
/reset
. (Only unchecked exceptions, which indicate
programming errors at your side, are otherwise thrown.) And it generalizes the source material to any
CharSequence
, which String
is only one example of, so you can read from a
StringBuilder
or something without constructing an intermediate String
.
The last point, however, has some implications. In contrast to a String
, a CharSequence
is not necessarily immutable. For the mark/reset (rewind) mechanism to work reliably, the reader would have to
buffer character data separately from the backing sequence, thus degrading performance, sucking memory and making
everything more complicated. Therefore we decided to support rewinding only for character sequences known to be
immutable. If you need rewinding with a mutable stream, you can easily wrap a BufferedReader
around, which
performs the necessary buffering.
The reader knows that String
s are immutable. Any other classes implementing CharSequence
are
assumed to be mutable unless you tell otherwise. Use setImmutable
to tell the
reader that the backing sequence is immutable, enabling direct mark/reset support. Make sure you tell the truth,
as misuse of this feature may cause unpredictable behaviour!
Note well: Obviously, if the source sequence is sync'd on its own, like a StringBuffer
,
that sync will not cease to operate only because the sequence is wrapped with this reader. Yet you must not rely
on that sync, because it only syncs the internals of the sequence, not the internals of the reader. Thus, in a
concurrent environment, you must provide external sync, regardless of the implementation of the underlying
sequence.
Ceterum censeo HTML in Javadoc is the dumbest idea ever.
StringBuilderWriter
Constructor Summary | |
---|---|
CharSequenceReader(CharSequence cs)
Constructs a reader that reads from cs . |
Method Summary | |
---|---|
void |
close()
Does nothing. |
int |
length()
Returns the current length of the underlying char sequence. |
void |
mark(int readAheadLimit)
Marks the current position in the stream for later repositioning. |
boolean |
markSupported()
Tells whether this stream supports the mark(int) operation. |
int |
read()
|
int |
read(char[] cbuf)
|
int |
read(char[] cbuf,
int off,
int len)
|
int |
read(CharBuffer target)
|
boolean |
ready()
Tells whether this stream is ready to be read without blocking, which is always true. |
int |
remaining()
Returns the current number of characters remaining to be read from the underlying char sequence. |
void |
reset()
Repositions the stream to the previously marked position. |
void |
setImmutable(boolean immutable)
Sets the immutable flag for the underlying sequence. |
long |
skip(long n)
|
Methods inherited from class Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public CharSequenceReader(CharSequence cs)
cs
.
If cs
happens to be a String
, the sequence is automatically
flagged immutable
.
Method Detail |
---|
public void setImmutable(boolean immutable)
The mark
/reset
mechanism is only supported for immutable sequences,
such as String
. Unless flagged immutable, rewinding is denied by the reader.
Use this, if you know the backing CharSequence
is immutable or a mutable sequence
will not change over the lifetime of this reader as per your application logic.
The flag is set to false
upon the reader's construction, except if the sequence happens to be a
String
, in which case the flag is set to true
, because strings are always immutable.
Use with care! Misuse of this feature may cause unpredictable behaviour!
immutable
- Whether the reader should treat the backing sequence as immutable.public int length()
public int remaining()
public boolean markSupported()
mark(int)
operation.
This reader supports rewinding the stream if and only if the underlying CharSequence
is immutable.
markSupported
in class Reader
setImmutable(boolean)
public void mark(int readAheadLimit) throws IOException
readAheadLimit
parameter is ignored.
Due to the specification of this method by Reader
we are forced to use IOException
to signal that the mark/reset mechanism is not available for this reader
(where UnsupportedOperationException
would be more appropriate). But we promise that we
throw it only if this reader is not backed by an immutable sequence, i.e. markSupported()
would
return false
.
mark
in class Reader
IOException
- If mark/reset is not supported for the underlying sequence.reset()
,
setImmutable(boolean)
public void reset() throws IOException
mark()
each time.
Due to the specification of this method by Reader
we are forced to use IOException
to signal that the mark/reset mechanism is not available for this reader
(where UnsupportedOperationException
would be more appropriate). But we promise that we
throw it only if this reader is not backed by an immutable sequence, i.e. markSupported()
would
return false
.
reset
in class Reader
IOException
- If mark/reset is not supported for the underlying sequence.mark(int)
,
setImmutable(boolean)
public int read()
read
in class Reader
public int read(char[] cbuf, int off, int len) throws IndexOutOfBoundsException
read
in class Reader
IndexOutOfBoundsException
public int read(char[] cbuf)
read
in class Reader
public int read(CharBuffer target)
read
in interface Readable
read
in class Reader
public boolean ready()
ready
in class Reader
true
public long skip(long n) throws IllegalArgumentException
skip
in class Reader
IllegalArgumentException
public void close()
close
in interface Closeable
close
in class Reader
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |