org.cip4.jdflib.cformat

Class ScanfReader

java.lang.Object

java.io.Reader

org.cip4.jdflib.cformat.ScanfReader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, java.lang.Readable

Direct Known Subclasses:

SScanf

public class ScanfReader
extends java.io.Reader

A Reader which implements C scanf functionality. Once created, an application can read various primitive types from the underlying stream using various scan methods that implement scanf type input formatting.

There are scan methods to read float, double, long, int, char, char[], and String. The methods take as an argument either a format string, a pre-allocated ScanfFormat object which is created from a format string, or no argument (implying a default format). The format string is modeled after that accepted by the C scanf() methodName, and is described in the documentation for the class ScanfFormat.

Because Java does not permit variable-length argument lists, only one primitive type may be returned per method, and the format used may contain only one conversion specification (which must be appropriate to the type being scanned).

Input errors in the underlying Reader result in a java.io.IOException being thrown, while a java.io.EOFException is thrown if the end of input is reached before the scan can complete successfully. If the input does not match the specified format, then a ScanfMatchException is thrown. In the event of a match error, scanning stops at the first character from which it can be determined that the match will fail. This character is remembered by the stream (see the discussion of the look-ahead character, below) and will be the first character seen by the next scan or read method which is called. Finally, an invalid format string (or ScanfFormat object) will trigger an InvalidArgumentException.

The class keeps track of the current line number (accessible with the methods getLineNumber and setLineNumber), as well as the number of characters which have been consumed (accesible with the methods getCharNumber and setCharNumber).

The class usually keeps one character of look-ahead which has been read from the underlying reader but not yet consumed by any scan method. If the underlying reader is used later in some other capacity, this look-ahead character may have to be taken into account. If a look-ahead character is actually being stored, the lookAheadCharValid method will return true, and the look-ahead character itself can then be obtained using the getLookAheadChar method. The look-ahead character can be cleared using the clearLookAheadChar method.

Field Summary

Fields inherited from class java.io.Reader

lock

Constructor Summary

Constructors

Constructor and Description
ScanfReader(java.io.Reader in) Create a new ScanfReader from the given reader.

Method Summary

Modifier and Type	Method and Description
void	clearLookAheadChar() Clears the look-ahead character.
void	close() Closes the stream.
int	getCharNumber() Gets the current character number (equal to the number of characters that have been consumed by the stream).
int	getLineNumber() Gets the current line number.
int	getLookAheadChar() Returns the look-ahead character.
boolean	lookAheadCharValid() Returns whether or not a look-ahead character is currently begin stored.
int	read(char[] cbuf, int off, int len) Reads characters into a portion of a character array.
char	scanChar() Scan and return a single character, using the default format string "%c".
char	scanChar(ScanfFormat fmt) Scan and return a single character, using a pre-allocated ScanfFormat object.
char	scanChar(java.lang.String s) Scan and return a single character.
char[]	scanChars(int n) Scan and return a character array, using the default format string "%c", with the field width (number of characters to read) supplanted by the argument n.
char[]	scanChars(ScanfFormat fmt) Scan and return a character array, using a pre-allocated ScanfFormat object.
char[]	scanChars(java.lang.String s) Scan and return a character array, whose size is determined by the field width specified in the format string (with a default width of 1 being assumed if no width is specified).
long	scanDec() Scan and return a signed decimal (long) integer, using the default format string "%d".
long	scanDec(ScanfFormat fmt) Scan and return a signed decimal (long) integer, using a pre-allocated ScanfFormat object.
long	scanDec(java.lang.String s) Scan and return a signed decimal (long) integer.
double	scanDouble() Scan and return a double, using the default format string "%f".
double	scanDouble(ScanfFormat fmt) Scan and return a double, using a pre-allocated ScanfFormat object.
double	scanDouble(java.lang.String s) Scan and return a double.
float	scanFloat() Scan and return a float, using the default format string "%f".
float	scanFloat(ScanfFormat fmt) Scan and return a float, using a pre-allocated ScanfFormat object.
float	scanFloat(java.lang.String s) Scan and return a float.
long	scanHex() Scan and return a hex (long) integer, using the default format string "%x".
long	scanHex(ScanfFormat fmt) Scan and return a hex (long) integer, using a pre-allocated ScanfFormat object.
long	scanHex(java.lang.String s) Scan and return a hex (long) integer.
int	scanInt() Scan and return a signed integer, using the default format string "%i".
int	scanInt(ScanfFormat fmt) Scan and return a signed integer, using a pre-allocated ScanfFormat object.
int	scanInt(java.lang.String s) Scan and return a signed integer.
long	scanLong() Scan and return a signed (long) integer, using the default format string "%i".
long	scanLong(ScanfFormat fmt) Scan and return a signed (long) integer, using a pre-allocated ScanfFormat object.
long	scanLong(java.lang.String s) Scan and return a signed (long) integer.
long	scanOct() Scan and return an octal (long) integer, using the default format string "%o".
long	scanOct(ScanfFormat fmt) Scan and return an octal (long) integer, using a pre-allocated ScanfFormat object.
long	scanOct(java.lang.String s) Scan and return an octal (long) integer.
java.lang.String	scanString() Scan and return a String, using the default format string "%s".
java.lang.String	scanString(ScanfFormat fmt) Scan and return a String, using a pre-allocated ScanfFormat object.
java.lang.String	scanString(java.lang.String s) Scan and return a String.
void	setCharNumber(int n) Sets the current character number.
void	setLineNumber(int n) Sets the current line number.
boolean	useCstandard() White spaces are skipped at the beginning of a line if flag is true otherwise spaces are counted as valid characters.
void	useCstandard(boolean flag) White spaces are skipped at the beginning of a line if flag is true otherwise spaces are counted as valid characters.

Methods inherited from class java.io.Reader

mark, markSupported, read, read, read, ready, reset, skip

Methods inherited from class java.lang.Object

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

Constructor Detail

ScanfReader

public ScanfReader(java.io.Reader in)

Create a new ScanfReader from the given reader.

Parameters:

reader - Underlying Reader

Method Detail

clearLookAheadChar

public void clearLookAheadChar()

Clears the look-ahead character.

close

public void close()
           throws java.io.IOException

Closes the stream.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in class java.io.Reader

Throws:

java.io.IOException - An I/O error occurred

getCharNumber

public int getCharNumber()

Gets the current character number (equal to the number of characters that have been consumed by the stream).

Returns:

Current character number

See Also:

setCharNumber(int)

getLineNumber

public int getLineNumber()

Gets the current line number. The initial value (when the Reader is created) is 1. A new line is recorded upon reading a carriage return, a line feed, or a carriage return immediately followed by a line feed.

Returns:

Current line number

See Also:

setLineNumber(int)

getLookAheadChar

public int getLookAheadChar()

Returns the look-ahead character.

Returns:

Look-ahead character, -1 if EOF has been reached, or 0 if no look-ahead character is being stored.

lookAheadCharValid

public boolean lookAheadCharValid()

Returns whether or not a look-ahead character is currently begin stored.

Returns:

True if a look-ahead character is being stored.

read

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

Reads characters into a portion of a character array. The method will block until input is available, an I/O error occurs, or the end of the stream is reached.

Specified by:

read in class java.io.Reader

Parameters:

cbuf - Buffer to write characters into

off - Offset to start writing at

len - Number of characters to read

Returns:

The number of characters read, or -1 if the end of the stream is reached.

Throws:

java.io.IOException - An I/O error occurred

scanChar

public char scanChar()
              throws java.io.IOException,
                     ScanfMatchException

Scan and return a single character, using the default format string "%c".

Parameters:

s - Format string

Returns:

Scanned character

Throws:

ScanfMatchException - Input did not match format

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanChar(String)

scanChar

public char scanChar(java.lang.String s)
              throws java.io.IOException,
                     ScanfMatchException,
                     java.lang.IllegalArgumentException

Scan and return a single character.

The format string s must have the form described by the documentation for the class ScanfFormat , and must contain the conversion character 'c' or '['. If the conversion character is '[', then each character scanned must match the sequence specified between the '[' and the closing ']' (see the documentation for ScanfFormat).

White space preceding the character is not skipped.

Parameters:

s - Format string

Returns:

Scanned character

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat

scanChar

public char scanChar(ScanfFormat fmt)
              throws java.io.IOException,
                     java.lang.IllegalArgumentException

Scan and return a single character, using a pre-allocated ScanfFormat object. This saves the overhead of parsing the format from a string.

Parameters:

fmt - Format object

Returns:

Scanned character

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanChar(String)

scanChars

public char[] scanChars(java.lang.String s)
                 throws java.io.IOException,
                        ScanfMatchException,
                        java.lang.IllegalArgumentException

Scan and return a character array, whose size is determined by the field width specified in the format string (with a default width of 1 being assumed if no width is specified).

The format string s must have the form described by the documentation for the class ScanfFormat , and must contain the conversion characters 'c' or '['. If the conversion character is '[', then each character scanned must match the sequence specified between the '[' and the closing ']' (see the documentation for ScanfFormat).

White space preceding the character sequence is not skipped.

Parameters:

s - Format string

Returns:

Scanned character array

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat

scanChars

public char[] scanChars(int n)
                 throws java.io.IOException,
                        ScanfMatchException,
                        java.lang.IllegalArgumentException

Scan and return a character array, using the default format string "%c", with the field width (number of characters to read) supplanted by the argument n.

Parameters:

n - Number of characters to read

Returns:

Scanned character array

Throws:

java.lang.IllegalArgumentException - n not a positive number

ScanfMatchException - Input did not match format

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanChars(String)

scanChars

public char[] scanChars(ScanfFormat fmt)
                 throws java.io.IOException,
                        java.lang.IllegalArgumentException

Scan and return a character array, using a pre-allocated ScanfFormat object. This saves the overhead of parsing the format from a string.

Parameters:

fmt - Format object

Returns:

Scanned character array

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanChars(String)

scanDec

public long scanDec()
             throws java.io.IOException,
                    ScanfMatchException

Scan and return a signed decimal (long) integer, using the default format string "%d".

Parameters:

s - Format string

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanDec(String)

scanDec

public long scanDec(java.lang.String s)
             throws java.io.IOException,
                    ScanfMatchException,
                    java.lang.IllegalArgumentException

Scan and return a signed decimal (long) integer.

The format string s must have the form described by the documentation for the class ScanfFormat , and must contain the conversion character 'd'. The integer itself must consist of an optional sign ('+' or '-') followed by a sequence of digits. White space preceding the number is skipped.

Parameters:

s - Format string

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat

scanDec

public long scanDec(ScanfFormat fmt)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException

Scan and return a signed decimal (long) integer, using a pre-allocated ScanfFormat object. This saves the overhead of parsing the format from a string.

Parameters:

fmt - Format object

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanDec(String)

scanDouble

public double scanDouble()
                  throws java.io.IOException,
                         ScanfMatchException

Scan and return a double, using the default format string "%f".

Returns:

Scanned double value

Throws:

ScanfMatchException - Input did not match format

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanDouble(String)

scanDouble

public double scanDouble(java.lang.String s)
                  throws java.io.IOException,
                         ScanfMatchException,
                         java.lang.IllegalArgumentException

Scan and return a double.

The format string s must have the form described by the documentation for the class ScanfFormat , and must contain the conversion character 'f'. The number itself may consist of (a) an optional sign ('+' or '-'), (b) a sequence of decimal digits, with an optional decimal point, (c) an optional exponent ('e' or 'E'), which must by followed by an optionally signed sequence of decimal digits. White space immediately before the number is skipped.

Parameters:

s - Format string

Returns:

Scanned double value

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat

scanDouble

public double scanDouble(ScanfFormat fmt)
                  throws java.io.IOException,
                         ScanfMatchException,
                         java.lang.IllegalArgumentException

Scan and return a double, using a pre-allocated ScanfFormat object. This saves the overhead of parsing the format from a string.

Parameters:

fmt - Format object

Returns:

Scanned double value

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanDouble(String)

scanFloat

public float scanFloat()
                throws java.io.IOException,
                       ScanfMatchException

Scan and return a float, using the default format string "%f".

Returns:

Scanned float value

Throws:

ScanfMatchException - Input did not match format

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanDouble(String)

scanFloat

public float scanFloat(java.lang.String s)
                throws java.io.IOException,
                       ScanfMatchException,
                       java.lang.IllegalArgumentException

Scan and return a float. The format string s takes the same form as that described in the documentation for scanDouble(String).

Parameters:

s - Format string

Returns:

Scanned float value

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanDouble(String)

scanFloat

public float scanFloat(ScanfFormat fmt)
                throws java.io.IOException,
                       ScanfMatchException,
                       java.lang.IllegalArgumentException

Scan and return a float, using a pre-allocated ScanfFormat object. This saves the overhead of parsing the format from a string.

Parameters:

fmt - Format object

Returns:

Scanned float value

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanDouble(String)

scanHex

public long scanHex()
             throws java.io.IOException,
                    ScanfMatchException

Scan and return a hex (long) integer, using the default format string "%x".

Parameters:

s - Format string

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanHex(String)

scanHex

public long scanHex(java.lang.String s)
             throws java.io.IOException,
                    ScanfMatchException,
                    java.lang.IllegalArgumentException

Scan and return a hex (long) integer.

The format string s must have the form described by the documentation for the class ScanfFormat , and must contain the conversion character 'x'. The integer itself must be formed from the characters [0-9a-fA-F], and white space which immediately precedes it is skipped.

Parameters:

s - Format string

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat

scanHex

public long scanHex(ScanfFormat fmt)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException

Scan and return a hex (long) integer, using a pre-allocated ScanfFormat object. This saves the overhead of parsing the format from a string.

Parameters:

fmt - Format object

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanHex(String)

scanInt

public int scanInt()
            throws java.io.IOException,
                   ScanfMatchException

Scan and return a signed integer, using the default format string "%i".

Parameters:

s - Format string

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanInt(String)

scanInt

public int scanInt(java.lang.String s)
            throws java.io.IOException,
                   ScanfMatchException,
                   java.lang.IllegalArgumentException

Scan and return a signed integer.

The format string s must have the form described by the documentation for the class ScanfFormat , and must contain one of the conversion characters "doxi".

Specifying the conversion characters 'd', 'o', or 'x' is equivalent to calling (int versions of) scanDec, scanOct, and scanHex, respectively.

If the conversion character is 'i', then after an optional sign ('+' or '-'), if the number begins with an 0x, then it is scanned as a hex number; if it begins with an 0, then it is scanned as an octal number, and otherwise it is scanned as a decimal number. White space preceding the number is skipped.

Parameters:

s - Format string

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanDec(String), scanOct(String), scanHex(String)

scanInt

public int scanInt(ScanfFormat fmt)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException

Scan and return a signed integer, using a pre-allocated ScanfFormat object. This saves the overhead of parsing the format from a string.

Parameters:

fmt - Format object

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanInt(String)

scanLong

public long scanLong()
              throws java.io.IOException,
                     ScanfMatchException

Scan and return a signed (long) integer, using the default format string "%i".

Parameters:

s - Format string

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanInt(String)

scanLong

public long scanLong(java.lang.String s)
              throws java.io.IOException,
                     ScanfMatchException,
                     java.lang.IllegalArgumentException

Scan and return a signed (long) integer. Functionality is identical to that for scanInt(String).

Parameters:

s - Format string

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

scanInt(String)

scanLong

public long scanLong(ScanfFormat fmt)
              throws java.io.IOException,
                     java.lang.IllegalArgumentException

Scan and return a signed (long) integer, using a pre-allocated ScanfFormat object.

Parameters:

fmt - Format object

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

scanInt(String)

scanOct

public long scanOct()
             throws java.io.IOException,
                    ScanfMatchException

Scan and return an octal (long) integer, using the default format string "%o".

Parameters:

s - Format string

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanOct(String)

scanOct

public long scanOct(java.lang.String s)
             throws java.io.IOException,
                    ScanfMatchException,
                    java.lang.IllegalArgumentException

Scan and return an octal (long) integer.

The format string s must have the form described by the documentation for the class ScanfFormat , and must contain the conversion character 'o'. The integer itself must be composed of the digits [0-7], and white space which immediately precedes it is skipped.

Parameters:

s - Format string

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat

scanOct

public long scanOct(ScanfFormat fmt)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException

Scan and return an octal (long) integer, using a pre-allocated ScanfFormat object. This saves the overhead of parsing the format from a string.

Parameters:

fmt - Format object

Returns:

Scanned integer

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanOct(String)

scanString

public java.lang.String scanString()
                            throws java.io.IOException,
                                   ScanfMatchException

Scan and return a String, using the default format string "%s".

Parameters:

s - Format string

Returns:

Scanned String

Throws:

ScanfMatchException - Input did not match format

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanString(String)

scanString

public java.lang.String scanString(java.lang.String s)
                            throws java.io.IOException,
                                   ScanfMatchException,
                                   java.lang.IllegalArgumentException

Scan and return a String.

The format string s must have the form described by the documentation for the class ScanfFormat , and must contain the conversion character 's'. The string returned corresponds to the next non-white-space sequence of characters found in the input, with preceding white space skipped.

Parameters:

s - Format string

Returns:

Scanned String

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat

scanString

public java.lang.String scanString(ScanfFormat fmt)
                            throws java.io.IOException,
                                   java.lang.IllegalArgumentException

Scan and return a String, using a pre-allocated ScanfFormat object. This saves the overhead of parsing the format from a string.

Parameters:

fmt - Format object

Returns:

Scanned String

Throws:

ScanfMatchException - Input did not match format

java.lang.IllegalArgumentException - Error in format specification

java.io.EOFException - End of file

java.io.IOException - Other input error

See Also:

ScanfFormat, scanString(String)

setCharNumber

public void setCharNumber(int n)

Sets the current character number.

Parameters:

n - New character number

See Also:

getCharNumber()

setLineNumber

public void setLineNumber(int n)

Sets the current line number.

Parameters:

n - New line number

See Also:

setLineNumber(int)

useCstandard

public boolean useCstandard()

White spaces are skipped at the beginning of a line if flag is true otherwise spaces are counted as valid characters.

useCstandard

public void useCstandard(boolean flag)

White spaces are skipped at the beginning of a line if flag is true otherwise spaces are counted as valid characters.