ucb.io
Class FormatReader

java.lang.Object
  |
  +--java.io.Reader
        |
        +--java.io.FilterReader
              |
              +--ucb.io.FormatReader

public class FormatReader

extends java.io.FilterReader

Provides formatted input of text, with format specifications similar to scanf from the standard C library. Each FormatReader is connected to an InputStream or Reader from which it extracts characters. Under control of a format argument, the member function scan will read characters from the the connected stream and convert them into a sequence of InputItems. Here is a typical use of this class for formatted input (assume stream is a FormatReader):

    // Read a string of up to 5 characters, followed by two integers,
    // separated by whitespace.
    stream.scan("%5s%d%d");  
    // Exit if end-of-file occurred before first data item could
    // be read.
    if (stream.eof())
	 break;
    // Test for error.
    if (stream.error())
       ReportError("bad input");
    // stream now contains 3 items scanned from the input stream to which 
    // it is connected.
    name = stream.item(0).toString(); // The first token read (a string) 
    size = stream.item(1).toInt();    // The second token read (an int) 
    number = stream.intItem(2);       // The third token read (shorthand
					// for stream.item(2).toInt()). 
 

See Also:

InputItem

Fields inherited from class java.io.FilterReader

in

Fields inherited from class java.io.Reader

lock

Constructor Summary

FormatReader(java.io.InputStream inp)
A new FormatReader filtering input from INP.

FormatReader(java.io.Reader inp)
A new FormatReader filtering input from INP.

Method Summary

int	charCount() Number of characters consumed by the last call to scan.
char	charItem(int i) Short for item(i).toChar().
void	clear(boolean flag) Set the return value of error() to the indicated value.
void	close() Closes this stream and its source Reader and releases associated system resources.
double	doubleItem(int i) Short for item(i).toDouble().
boolean	eof() True if the last call to scan encountered end-of-file.
boolean	error() Set true when a call to scan encounters an error in the input.
float	floatItem(int i) Short for item(i).toFloat().
int	getc() Returns the next character, as would be read by scan("%c"), and returns either it, or -1 on end of file or error.
int	intItem(int i) Short for item(i).toInt().
InputItem	item(int i) A value scanned by the last call to scan.
int	itemCount() Number of InputItems set by last call to scan.
long	longItem(int i) Short for item(i).toLong().
void	mark(int readAheadLimit)
boolean	markSupported()
int	read()
int	read(char[] cbuf)
int	read(char[] cbuf, int off, int len)
boolean	ready()
void	reset()
void	scan(java.lang.String format) Extract data items from the attached InputStream according to a specified format string, and put them in item(0), item(1), etc.
void	skip(int n)
java.lang.String	stringItem(int i) Short for item(i).toString().
void	tie(java.io.OutputStream out) Arrange for OUT to be flushed before every input operation on THIS.
void	tie(java.io.Writer out) Arrange for OUT to be flushed before every input operation on THIS.
void	unread(int ch) Insert character at the beginning of the remaining input stream.

Methods inherited from class java.io.FilterReader

skip

Methods inherited from class java.lang.Object

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

Constructor Detail

FormatReader

public FormatReader(java.io.Reader inp)

A new FormatReader filtering input from INP.

FormatReader

public FormatReader(java.io.InputStream inp)

A new FormatReader filtering input from INP.

Method Detail

scan

public void scan(java.lang.String format)
          throws FormatException

Extract data items from the attached InputStream according to a specified format string, and put them in item(0), item(1), etc. The format string may contain

1. White-space characters (blanks, tabs, newlines, or form-feeds), which cause input to be read up to the next non-white-space character.
2. An ordinary character, c other than `%', which causes the next character of the input stream to be discarded if it is c, and otherwise causes scanning to stop and flag an error.
3. Conversion specifications of the form `%swc', where s is an optional asterisk, indicating that the item is to be skipped; w is an optional numerical field width, indicating the maximum number of input characters to be converted in the item; and c is one of the valid conversion codes, indicating the type of value expected.

For each conversion specification other than `%' and those that are flagged with an asterisk, scan places the value represented by the next field in the input stream into an InputItem, which is retrievable by the item member function. An input field is defined as a string of characters that extends to the next character that is inappropriate for the given conversion specification (so that, for example, a comma or space will delimit a field that is supposed to be an integer), or until the the field width, when specified, is filled, whichever is shorter. With the exception of the `%c' and `%[' conversion specifications, the conversion first skips leading white space, and white space characters are always deemed "inappropriate".

The valid conversion codes are as follows:

%

A single `%' is expected in the input at this point (otherwise conversion terminates with an error). No corresponding InputItem is created.

d, u, ld, Ld, lu, Lu

Match an optionally signed decimal integer. The two-character codes produce an item containing a long value; plain `d' or `u' produces an int value.

o, lo, Lo

Match an optionally signed octal integer. The interpretation of `l' and `L' is as for the `d' or `u' format code.

x, lx, Lx

Match an optionally signed hexadecimal integer. An initial `0x' or `0X' is ignored. The interpretation of `l' and `L' is as for the `d' or `u' format code.

i, li, Li

Match an optionally signed integer, which is taken to be hexadecimal if it begins with `0x' or `0X', otherwise octal if it begins with `0', and otherwise decimal. The interpretation of `l' and `L' is as for the `d' or `u' format code.

e, f, g, le, lf, lg, Le, Lf, Lg

Match an optionally signed floating-point number. Converts to a double for the two-letter codes, and otherwise to a float.

s

Matches a character string delimited by whitespace (or the exhaustion of the field width). Produces a String-valued InputItem.

c

Scans in the number of characters indicated by the field width, which defaults to 1. The resulting input item is a String, but when interpreted yields the first character read. There is no initial skipping of whitespace.

[

Matches a nonempty sequence of characters from a set of expected characters (the scanset). The conversion specifier includes all subsequent char- acters in the format string, up to and including the matching right bracket (]). The characters between the brackets constitute the scanset, unless the character after the left bracket is a circumflex (^), in which case the scanset contains all characters that do not appear in the scanlist between the circumflex and the right bracket. If the conversion specifier begins with [] or [^], the right bracket character is in the scanlist and the next right bracket character is the matching right bracket that ends the specification; otherwise the first right bracket character is the one that ends the specification. A range of characters in the scanset may be represented by the construct first-last, where first is lexically less than or equal to last. Thus [0123456789] may be expressed [0-9]. When used otherwise, the character `-' will stand for itself. At least one character must match for this conversion to be considered successful.

Parameters:

format - the specification for the conversions to be performed.

Throws:

FormatException - raised if the format string has an invalid form.

See Also:

InputItem, item(int)

unread

public void unread(int ch)

Insert character at the beginning of the remaining input stream. The next scan operation will see this character first.

Parameters:

ch - the character to insert.

tie

public void tie(java.io.OutputStream out)

Arrange for OUT to be flushed before every input operation on THIS.

Parameters:

out - the OutputStream that is to be flushed.

See Also:

OutputStream.flush()

tie

public void tie(java.io.Writer out)

Arrange for OUT to be flushed before every input operation on THIS.

Parameters:

out - the Writer that is to be flushed.

See Also:

Writer.flush()

eof

public boolean eof()

True if the last call to scan encountered end-of-file. In addition, error() will also be set true unless the only characters read by the scan were whitespace that was being skipped.

See Also:

error(), scan(java.lang.String)

error

public boolean error()

Set true when a call to scan encounters an error in the input. This indication may be reset using clear(). It is initially false.

See Also:

clear(boolean)

clear

public void clear(boolean flag)

Set the return value of error() to the indicated value.

Parameters:

flag - value that next call to error() will return.

See Also:

error()

itemCount

public int itemCount()

Number of InputItems set by last call to scan. This count includes all `%' conversion items that created items up to but not including the first erroneous conversion, if any.

See Also:

scan(String), item(int)

charCount

public int charCount()

Number of characters consumed by the last call to scan. This includes all skipped inputs and whitespace.

See Also:

scan(String)

item

public InputItem item(int i)
               throws java.lang.IndexOutOfBoundsException

A value scanned by the last call to scan. item(0) corresponds to the first format conversion that created a value, item(1) to the second, etc., up to item(itemCount()-1). It is an error to give an argument less than 0 or greater than itemCount(). The result of item(i) is always the same (when it succeeds). That is, the InputItems that are returned are recycled. You should clone them if you need them to persist over calls to scan.

Throws:

java.lang.IndexOutOfBoundsException - if i is negative or greater than itemCount()-1.

intItem

public int intItem(int i)
            throws java.lang.IndexOutOfBoundsException,
                   java.lang.IllegalArgumentException

Short for item(i).toInt().

longItem

public long longItem(int i)
              throws java.lang.IndexOutOfBoundsException,
                     java.lang.IllegalArgumentException

Short for item(i).toLong().

charItem

public char charItem(int i)
              throws java.lang.IndexOutOfBoundsException,
                     java.lang.IllegalArgumentException

Short for item(i).toChar().

getc

public int getc()

Returns the next character, as would be read by scan("%c"), and returns either it, or -1 on end of file or error.

floatItem

public float floatItem(int i)
                throws java.lang.IndexOutOfBoundsException,
                       java.lang.IllegalArgumentException

Short for item(i).toFloat().

doubleItem

public double doubleItem(int i)
                  throws java.lang.IndexOutOfBoundsException,
                         java.lang.IllegalArgumentException

Short for item(i).toDouble().

stringItem

public java.lang.String stringItem(int i)
                            throws java.lang.IndexOutOfBoundsException,
                                   java.lang.IllegalArgumentException

Short for item(i).toString().

close

public void close()

Closes this stream and its source Reader and releases associated system resources.

Overrides:

close in class java.io.FilterReader

read

public int read()
         throws java.io.IOException

Overrides:

read in class java.io.FilterReader

read

public int read(char[] cbuf,
                int off,
                int len)
         throws java.io.IOException

Overrides:

read in class java.io.FilterReader

read

public int read(char[] cbuf)
         throws java.io.IOException

Overrides:

read in class java.io.Reader

reset

public void reset()
           throws java.io.IOException

Overrides:

reset in class java.io.FilterReader

markSupported

public boolean markSupported()

Overrides:

markSupported in class java.io.FilterReader

mark

public void mark(int readAheadLimit)
          throws java.io.IOException

Overrides:

mark in class java.io.FilterReader

ready

public boolean ready()
              throws java.io.IOException

Overrides:

ready in class java.io.FilterReader

skip

public void skip(int n)
          throws java.io.IOException