Represents a text input stream.
More...
#include <jem/io/Reader.h>
|
| virtual void | lock () |
| | Locks this input stream. More...
|
| |
| virtual void | unlock () |
| | Unlocks this input stream. More...
|
| |
| virtual void | close () |
| | Closes this input stream. More...
|
| |
| virtual int | poll () |
| | Returns the number of characters that can read without blocking. More...
|
| |
| virtual int | read (char *buf, int n) |
| | Extracts multiple characters from this input stream. More...
|
| |
| virtual int | readUntil (char *buf, int n, int delim) |
| | Reads characters until a specified character. More...
|
| |
| virtual void | skipUntil (int delim) |
| | Skips characters until a specified character. More...
|
| |
| virtual void | skipWhite () |
| | Skips over white space. More...
|
| |
| virtual int | skip (int n) |
| | Skips over a specified number of characters. More...
|
| |
| String | readLine () |
| | Reads the next line from this input stream. More...
|
| |
| virtual byte | parseByte () |
| | Reads a byte from this input stream. More...
|
| |
| virtual bool | parseBool () |
| | Reads a boolean from this input stream. More...
|
| |
| virtual long | parseInt () |
| | Reads a long integer from this input stream. More...
|
| |
| virtual double | parseFloat () |
| | Reads a double from this input stream. More...
|
| |
| virtual Class * | getClass () const |
| | Returns the Class instance representing the runtime class of this object. More...
|
| |
| virtual String | toString () const |
| | Returns a short textual description of this object. More...
|
| |
| virtual long | hashValue () const |
| | Returns a hash value for this object. More...
|
| |
| virtual bool | equals (const Ref< Object > &obj) const |
| | Tests whether two objects are equal. More...
|
| |
| Ref< Object > | clone () const |
| | Returns a copy of this object. More...
|
| |
| virtual int | read ()=0 |
| | Extracts the next character from this input stream. More...
|
| |
| virtual void | pushBack (int c)=0 |
| | Pushes back a previously read character. More...
|
| |
The Reader class implements the TextInput interface and provides various additional member functions for operating on text input streams. Since the Reader class also extends the Object class, Reader instances are subjected to garbage collection.
- See also
Writer.
- Examples:
- Properties.cpp, and System.cpp.
| virtual void jem::io::Reader::lock |
( |
| ) |
|
|
virtual |
This function locks this Reader object so that only the current thread can read from the input stream. All other threads calling this function will be blocked until the current thread calls the unlock() member function.
The lock() and unlock() member functions are guaranteed to be recursive. This means that a thread may call lock() multiple times without creating a deadlock situation. Each call to lock() must be balanced by a call to unlock() to ensure that this Reader instance does not become permanently inaccessible to other threads.
The lock() function does not have to lock this object. In fact, the default implementation provided by the Reader class does nothing. It is up to you to instantiate a class derived from the Reader class that implements an appropriate locking scheme.
- See also
Lock, IOMutex, ThreadSafeReader.
Reimplemented in jem::mt::ThreadSafeReader.
| virtual void jem::io::Reader::unlock |
( |
| ) |
|
|
virtual |
Unlocks this Reader object so that it can be accessed by other threads.
The default implementation provided by the Reader class does nothing.
- Precondition
- This object has been locked by a call to the
lock() member function.
Reimplemented in jem::mt::ThreadSafeReader.
| virtual void jem::io::Reader::close |
( |
| ) |
|
|
virtual |
| virtual int jem::io::Reader::poll |
( |
| ) |
|
|
virtual |
Returns the number of characters that can be read from this input stream without having to wait until the underlying device has become ready for reading. If you read more characters you may have to wait an unspecified amount of time before the read operation is completed.
Note that a call to one of the read() functions will not necessarily block if more characters are read than the number returned by this function.
Also note that if another thread reads from this stream after calling the poll() function, the current thread may no longer be able to read the returned number of characters without blocking. Use the lock() member function to avoid these types of situations.
The default implementation provided by the Reader class always returns zero.
- Returns
- The number of characters that can be read without blocking.
- Exceptions
-
| virtual int jem::io::Reader::read |
( |
char * |
buf, |
|
|
int |
n |
|
) |
| |
|
virtual |
Extracts up to n characters from this input stream and stores them into the the array buf. The implementation provided by the Reader class simply calls read() in a loop. Derived classes are encouraged to provide a more efficient implementation.
- Parameters
-
| buf | - a character array of which the size is at least n. |
| n | - the maximum number of characters to be extracted from the input stream. |
- Returns
- The number of characters that have been extracted from the input stream.
- Exceptions
-
Implements jem::io::TextInput.
- Examples:
- GzipFileReader.cpp, and GzipFileWriter.cpp.
| virtual int jem::io::Reader::readUntil |
( |
char * |
buf, |
|
|
int |
n, |
|
|
int |
delim |
|
) |
| |
|
virtual |
Reads characters until the delimiting character (delimiter) delim is encountered, or until n characters have been read, or until the end of the input stream has been reached. All read characters are stored in the array buf and the total number of read characters is returned. The delimiter is not extracted from the input stream.
The implementation of this function provided by the Reader class calls the read() member function in a loop.
- Parameters
-
| buf | - a character array of which the size is at least n. |
| n | - the maximum number of characters to be extracted from the input stream. |
| delim | - the delimiter. |
- Returns
- The number of characters that have been extracted from the input stream and that have been stored in the character array buf.
- Precondition
n >= 0
and the array buf is at least n characters long.
- Postcondition
- If k denotes the value returned by this function, then the array elements
buf[0], ..., buf[k - 1] have been filled.
- Exceptions
-
| virtual void jem::io::Reader::skipUntil |
( |
int |
delim | ) |
|
|
virtual |
| virtual void jem::io::Reader::skipWhite |
( |
| ) |
|
|
virtual |
| virtual int jem::io::Reader::skip |
( |
int |
n | ) |
|
|
virtual |
Extracts up to n characters from this input stream, and returns the number of characters that have been extracted. This number may be less than n if the end of the input stream has been reached.
The implementation of this function provided by the Reader class repeatedly calls the member function read( char*, int ).
- Parameters
-
| n | - the number of characters to be skipped. |
- Returns
- The number of characters that have been extracted from this input stream.
- Exceptions
-
| String jem::io::Reader::readLine |
( |
| ) |
|
Reads and returns the next line in the input stream. That is, it reads characters until a newline character '\n' is encountered, or until the end of file has been reached. The read characters are then returned as a String object.
- Returns
- A
String containing the next line in this input stream.
- Exceptions
-
| virtual byte jem::io::Reader::parseByte |
( |
| ) |
|
|
virtual |
Reads a byte from this input stream. The implementation provided by the Reader class first calls readInt(), and then tries to convert the read integer to a byte.
- Returns
- The byte that has been read from this input stream.
- Exceptions
-
Implements jem::io::TextInput.
| virtual bool jem::io::Reader::parseBool |
( |
| ) |
|
|
virtual |
Reads a boolean from this input stream. The boolean should be stored in one of the following formats:
"0" - which is converted to false "1" - which is converted to true "true" "false"
Any leading white space is skipped by calling in.skipWhite().
Note that this function is case insensitive. The input "True", for instance, is also considered to be valid.
- Returns
- The bool that has been read from this input stream.
- Exceptions
-
Implements jem::io::TextInput.
| virtual long jem::io::Reader::parseInt |
( |
| ) |
|
|
virtual |
Reads a long integer from this input stream. The integer should be stored in either a decimal or a hexadecimal format, and it may be preceded by a single '-' or '+' character. Any leading white space is skipped by calling in.skipWhite().
Valid long integers are:
"123" - a positive, decimal number; "0xfff" - a positive, hexadecimal number; "-222" - a negative, decimal number.
This function stops extracting characters from the input stream when it encounters a character that can not be part of an integer number.
- Returns
- The integer that has been read from this input stream.
- Exceptions
-
Implements jem::io::TextInput.
| virtual double jem::io::Reader::parseFloat |
( |
| ) |
|
|
virtual |
Reads a double precision number from this input stream. The double should be stored in the following format: an optional '+' or '-' character, followed by a sequence of decimal digits, followed by an optional decimal point and another sequence of decimal digits, optionally followed by an eponent. The exponent consists of a 'e' or 'E' character, followed by an optional '+' or '-' character, followed by a sequence of decimal digits. Any leading white space is skipped by calling in.skipWhite().
Valid double precision numbers are:
"1.0" - a positive number; "-1.0" - a negative number; "+1.0e-2" - a positive number with an exponent;
This function stops extracting characters from the input stream when it encounters a character that can not be part of an double precision number.
- Returns
- The double that has been read from this input stream.
- Exceptions
-
Implements jem::io::TextInput.
Public Member Functions inherited from jem::Object
