Class TextIO

java.lang.Object
  TextIO

public class TextIO
extends java.lang.Object

TextIO provides a set of static methods for reading and writing text. By default, it reads from standard input and writes to standard output, but it is possible to redirect the input and output to files or to other input and output streams. When the standard input and output streams are being used, the input methods will not produce an error; instead, the user is repeatedly prompted for input until a legal input is entered. (If standard input has been changed externally, as by file redirection on the command line, this is not a reasonable behavior; to handle this case, TextIO will give up after 10 consecutive illegal inputs and will throw an IllegalArgumentException.) For the most part, any other error will be translated into an IllegalArguementException.

For writing to standard output, the output methods in this class pretty much duplicate the functionality of System.out, and System.out can be used interchangeably with them.

This class does not use optimal Java programming practices. It is designed specifically to be easily usable even by a beginning programmer who has not yet learned about objects and exceptions. Therefore, everything is in a single source file that compiles into a single class file, all the methods are static methods, and none of the methods throw exceptions that would require try...catch statements. Also for this reason, all exceptions are converted into IllegalArgumentExceptions, even when this exception type doesn't really make sense.

This class requires Java 5.0 or higher. (A previous version of TextIO required only Java 1.1; this version should work with any source code that used the previous version, but it has some new features, including the type of formatted output that was introduced in Java 5 and the ability to use files and streams.

EOF

public static final char EOF

The value returned by the peek() method when the input is at end-of-file. (The value of this constant is (char)0xFFFF.)

See Also:

Constant Field Values

EOLN

public static final char EOLN

The value returned by the peek() method when the input is at end-of-line. The value of this constant is the character '\n'.

See Also:

Constant Field Values

TextIO

public TextIO()

eof

public static boolean eof()

Test whether the next character in the current input source is an end-of-file. Note that this method does NOT skip whitespace before testing for end-of-line -- if you want to do that, call skipBlanks() or skipWhitespace() first.

eoln

public static boolean eoln()

Test whether the next character in the current input source is an end-of-line. Note that this method does NOT skip whitespace before testing for end-of-line -- if you want to do that, call skipBlanks() first.

getAnyChar

public static char getAnyChar()

Reads the next character from the current input source. The character can be a whitespace character; compare this to the getChar() method, which skips over whitespace and returns the next non-whitespace character. An end-of-line is always returned as the character '\n', even when the actual end-of-line in the input source is something else, such as '\r' or "\r\n". This method will throw an IllegalArgumentException if the input is at end-of-file (which will not ordinarily happen if reading from standard input).

getBoolean

public static boolean getBoolean()

Skips whitespace characters and then reads a value of type boolean from input. Any additional characters on the current line of input are retained, and will be read by the next input operation. When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

Legal inputs for a boolean input are: true, t, yes, y, 1, false, f, no, n, and 0; letters can be either upper case or lower case. One "word" of input is read, using the getWord() method, and it must be one of these; note that the "word" must be terminated by a whitespace character (or end-of-file).

getByte

public static byte getByte()

Skips whitespace characters and then reads a value of type byte from input. Any additional characters on the current line of input are retained, and will be read by the next input operation. When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getChar

public static char getChar()

Skips whitespace characters and then reads a single non-whitespace character from input. Any additional characters on the current line of input are retained, and will be read by the next input operation. When using standard IO, this will not produce an error. In other cases, an IllegalArgumentException will be thrown if an end-of-file is encountered.

getDouble

public static double getDouble()

Skips whitespace characters and then reads a value of type double from input. Any additional characters on the current line of input are retained, and will be read by the next input operation. When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getFloat

public static float getFloat()

Skips whitespace characters and then reads a value of type float from input. Any additional characters on the current line of input are retained, and will be read by the next input operation. When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getInputFileName

public static java.lang.String getInputFileName()

If TextIO is currently reading from a file, then the return value is the name of the file. If the class is reading from standard input or from a stream, then the return value is null.

getInt

public static int getInt()

Skips whitespace characters and then reads a value of type int from input. Any additional characters on the current line of input are retained, and will be read by the next input operation. When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getln

public static java.lang.String getln()

Reads all the charcters from the current input source, up to the next end-of-line. The end-of-line is read but is not included in the return value. Any other whitespace characters on the line are retained, even if they occur at the start of input. The return value will be an empty string if there are no no characters before the end-of-line. When using standard IO, this will not produce an error. In other cases, an IllegalArgumentException will be thrown if an end-of-file is encountered.

getlnBoolean

public static boolean getlnBoolean()

Skips whitespace characters and then reads a value of type boolean from input, discarding the rest of the current line of input (including the next end-of-line character, if any). When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

Legal inputs for a boolean input are: true, t, yes, y, 1, false, f, no, n, and 0; letters can be either upper case or lower case. One "word" of input is read, using the getWord() method, and it must be one of these; note that the "word" must be terminated by a whitespace character (or end-of-file).

getlnByte

public static byte getlnByte()

Skips whitespace characters and then reads a value of type byte from input, discarding the rest of the current line of input (including the next end-of-line character, if any). When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getlnChar

public static char getlnChar()

Skips whitespace characters and then reads a value of type char from input, discarding the rest of the current line of input (including the next end-of-line character, if any). Note that the value that is returned will be a non-whitespace character; compare this with the getAnyChar() method. When using standard IO, this will not produce an error. In other cases, an error can occur if an end-of-file is encountered.

getlnDouble

public static double getlnDouble()

Skips whitespace characters and then reads a value of type double from input, discarding the rest of the current line of input (including the next end-of-line character, if any). When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getlnFloat

public static float getlnFloat()

Skips whitespace characters and then reads a value of type float from input, discarding the rest of the current line of input (including the next end-of-line character, if any). When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getlnInt

public static int getlnInt()

Skips whitespace characters and then reads a value of type int from input, discarding the rest of the current line of input (including the next end-of-line character, if any). When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getlnLong

public static long getlnLong()

Skips whitespace characters and then reads a value of type long from input, discarding the rest of the current line of input (including the next end-of-line character, if any). When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getlnShort

public static short getlnShort()

Skips whitespace characters and then reads a value of type short from input, discarding the rest of the current line of input (including the next end-of-line character, if any). When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getlnString

public static java.lang.String getlnString()

This is identical to getln().

getlnWord

public static java.lang.String getlnWord()

Skips whitespace characters and then reads one "word" from input, discarding the rest of the current line of input (including the next end-of-line character, if any). A word is defined as a sequence of non-whitespace characters (not just letters!). When using standard IO, this will not produce an error. In other cases, an IllegalArgumentException will be thrown if an end-of-file is encountered.

getLong

public static long getLong()

Skips whitespace characters and then reads a value of type long from input. Any additional characters on the current line of input are retained, and will be read by the next input operation. When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getOutputFileName

public static java.lang.String getOutputFileName()

If TextIO is currently writing to a file, then the return value is the name of the file. If the class is writing to standard output or to a stream, then the return value is null.

getShort

public static short getShort()

Skips whitespace characters and then reads a value of type short from input. Any additional characters on the current line of input are retained, and will be read by the next input operation. When using standard IO, this will not produce an error; the user will be prompted repeatedly for input until a legal value is input. In other cases, an IllegalArgumentException will be thrown if a legal value is not found.

getWord

public static java.lang.String getWord()

Skips whitespace characters and then reads one "word" from input. Any additional characters on the current line of input are retained, and will be read by the next input operation. A word is defined as a sequence of non-whitespace characters (not just letters!). When using standard IO, this will not produce an error. In other cases, an IllegalArgumentException will be thrown if an end-of-file is encountered.

peek

public static char peek()

Returns the next character in the current input source, without actually removing that character from the input. The character can be a whitespace character and can be the end-of-file character (specfied by the constant TextIO.EOF).An end-of-line is always returned as the character '\n', even when the actual end-of-line in the input source is something else, such as '\r' or "\r\n". This method never causes an error.

put

public static void put(java.lang.Object x)

Write a single value to the current output destination, using the default format and no extra spaces. This method will handle any type of parameter, even one whose type is one of the primitive types.

put

public static void put(java.lang.Object x,
                       int minChars)

Write a single value to the current output destination, using the default format and outputting at least minChars characters (with extra spaces added before the output value if necessary). This method will handle any type of parameter, even one whose type is one of the primitive types.

Parameters:

x - The value to be output, which can be of any type.

minChars - The minimum number of characters to use for the output. If x requires fewer then this number of characters, then extra spaces are added to the front of x to bring the total up to minChars. If minChars is less than or equal to zero, then x will be printed in the minumum number of spaces possible.

putf

public static void putf(java.lang.String format,
                        java.lang.Object... items)

Writes formatted output values to the current output destination. This method has the same function as System.out.printf(); the details of formatted output are not discussed here. The first parameter is a string that describes the format of the output. There can be any number of additional parameters; these specify the values to be output and can be of any type. This method will throw an IllegalArgumentException if the format string is null or if the format string is illegal for the values that are being output.

putln

public static void putln()

Write an end-of-line character to the current output destination.

putln

public static void putln(java.lang.Object x)

This is equivalent to put(x), followed by an end-of-line.

putln

public static void putln(java.lang.Object x,
                         int minChars)

This is equivalent to put(x,minChars), followed by an end-of-line.

readFile

public static void readFile(java.lang.String fileName)

Opens a file with a specified name for input. If the file name is null, this has the same effect as calling readStandardInput(); that is, input will be read from standard input. If an error occurs while trying to open the file, an exception of type IllegalArgumentException is thrown, and the input source is not changed. If the file is opened successfully, then after this method is called, all of the input routines will read from the file, instead of from standard input.

readStandardInput

public static void readStandardInput()

After this method is called, input will be read from standard input (as it is in the default state). If a file or stream was previously the input source, that file or stream is closed.

readStream

public static void readStream(java.io.InputStream inputStream)

After this method is called, input will be read from inputStream, provided it is non-null. If inputStream is null, then this method has the same effect as calling readStandardInput(); that is, future input will come from the standard input stream.

readStream

public static void readStream(java.io.Reader inputStream)

After this method is called, input will be read from inputStream, provided it is non-null. If inputStream is null, then this method has the same effect as calling readStandardInput(); that is, future input will come from the standard input stream.

readUserSelectedFile

public static boolean readUserSelectedFile()

Puts a GUI file-selection dialog box on the screen in which the user can select an input file. If the user cancels the dialog instead of selecting a file, it is not considered an error, but the return value of the subroutine is false. If the user does select a file, but there is an error while trying to open the file, then an exception of type IllegalArgumentException is thrown. Finally, if the user selects a file and it is successfully opened, then the return value of the subroutine is true, and the input routines will read from the file, instead of from standard input. If the user cancels, or if any error occurs, then the previous input source is not changed.

NOTE: Calling this method starts a GUI user interface thread, which can continue to run even if the thread that runs the main program ends. If you use this method in a non-GUI program, it might be necessary to call System.exit(0) at the end of the main() routine to shut down the Java virtual machine completely.

skipBlanks

public static void skipBlanks()

Skips over any whitespace characters, except for end-of-lines. After this method is called, the next input character is either an end-of-line, an end-of-file, or a non-whitespace character. This method never causes an error. (Ordinarly, end-of-file is not possible when reading from standard input.)

writeFile

public static void writeFile(java.lang.String fileName)

Opens a file with a specified name for output. If the file name is null, this has the same effect as calling writeStandardOutput(); that is, output will be sent to standard output. If an error occurs while trying to open the file, an exception of type IllegalArgumentException is thrown. If the file is opened successfully, then after this method is called, all of the output routines will write to the file, instead of to standard output. If an error occurs, the output destination is not changed.

NOTE: Calling this method starts a GUI user interface thread, which can continue to run even if the thread that runs the main program ends. If you use this method in a non-GUI program, it might be necessary to call System.exit(0) at the end of the main() routine to shut down the Java virtual machine completely.

writeStandardOutput

public static void writeStandardOutput()

After this method is called, output will be written to standard output (as it is in the default state). If a file or stream was previously open for output, it will be closed.

writeStream

public static void writeStream(java.io.OutputStream outputStream)

After this method is called, output will be sent to outputStream, provided it is non-null. If outputStream is null, then this method has the same effect as calling writeStandardOutput(); that is, future output will be sent to the standard output stream.

writeStream

public static void writeStream(java.io.PrintWriter outputStream)

After this method is called, output will be sent to outputStream, provided it is non-null. If outputStream is null, then this method has the same effect as calling writeStandardOutput(); that is, future output will be sent to the standard output stream.

writeUserSelectedFile

public static boolean writeUserSelectedFile()

Puts a GUI file-selection dialog box on the screen in which the user can select an output file. If the user cancels the dialog instead of selecting a file, it is not considered an error, but the return value of the subroutine is false. If the user does select a file, but there is an error while trying to open the file, then an exception of type IllegalArgumentException is thrown. Finally, if the user selects a file and it is successfully opened, then the return value of the subroutine is true, and the output routines will write to the file, instead of to standard output. If the user cancels, or if an error occurs, then the current output destination is not changed.