textio

## Class TextIO

- java.lang.Object
- - textio.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.)

  TextIO must be imported from package textio to be used. (Previous versions were in the default package. Alternatively, this class can be moved into the default package by deleting the "package" declaration on the first line of this file.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static char` | `EOF` The value returned by the peek() method when the input is at end-of-file.
    `static char` | `EOLN` The value returned by the peek() method when the input is at end-of-line.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TextIO()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `eof()` Test whether the next character in the current input source is an end-of-file.
    `static boolean` | `eoln()` Test whether the next character in the current input source is an end-of-line.
    `static char` | `getAnyChar()` Reads the next character from the current input source.
    `static boolean` | `getBoolean()` Skips whitespace characters and then reads a value of type boolean from input.
    `static byte` | `getByte()` Skips whitespace characters and then reads a value of type byte from input.
    `static char` | `getChar()` Skips whitespace characters and then reads a single non-whitespace character from input.
    `static double` | `getDouble()` Skips whitespace characters and then reads a value of type double from input.
    `static float` | `getFloat()` Skips whitespace characters and then reads a value of type float from input.
    `static java.lang.String` | `getInputFileName()` If TextIO is currently reading from a file, then the return value is the name of the file.
    `static int` | `getInt()` Skips whitespace characters and then reads a value of type int from input.
    `static java.lang.String` | `getln()` Reads all the characters from the current input source, up to the next end-of-line.
    `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).
    `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).
    `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).
    `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).
    `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).
    `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).
    `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).
    `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).
    `static java.lang.String` | `getlnString()` This is identical to getln().
    `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).
    `static long` | `getLong()` Skips whitespace characters and then reads a value of type long from input.
    `static java.lang.String` | `getOutputFileName()` If TextIO is currently writing to a file, then the return value is the name of the file.
    `static short` | `getShort()` Skips whitespace characters and then reads a value of type short from input.
    `static java.lang.String` | `getWord()` Skips whitespace characters and then reads one "word" from input.
    `static char` | `peek()` Returns the next character in the current input source, without actually removing that character from the input.
    `static void` | `put(java.lang.Object x)` Write a single value to the current output destination, using the default format and no extra spaces.
    `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).
    `static void` | `putf(java.lang.String format, java.lang.Object... items)` Writes formatted output values to the current output destination.
    `static void` | `putln()` Write an end-of-line character to the current output destination.
    `static void` | `putln(java.lang.Object x)` This is equivalent to put(x), followed by an end-of-line.
    `static void` | `putln(java.lang.Object x, int minChars)` This is equivalent to put(x,minChars), followed by an end-of-line.
    `static void` | `readFile(java.lang.String fileName)` Opens a file with a specified name for input.
    `static void` | `readStandardInput()` After this method is called, input will be read from standard input (as it is in the default state).
    `static void` | `readStream(java.io.InputStream inputStream)` After this method is called, input will be read from inputStream, provided it is non-null.
    `static void` | `readStream(java.io.Reader inputStream)` After this method is called, input will be read from inputStream, provided it is non-null.
    `static boolean` | `readUserSelectedFile()` Puts a GUI file-selection dialog box on the screen in which the user can select an input file.
    `static void` | `skipBlanks()` Skips over any whitespace characters, except for end-of-lines.
    `static void` | `writeFile(java.lang.String fileName)` Opens a file with a specified name for output.
    `static void` | `writeStandardOutput()` After this method is called, output will be written to standard output (as it is in the default state).
    `static void` | `writeStream(java.io.OutputStream outputStream)` After this method is called, output will be sent to outputStream, provided it is non-null.
    `static void` | `writeStream(java.io.PrintWriter outputStream)` After this method is called, output will be sent to outputStream, provided it is non-null.
    `static boolean` | `writeUserSelectedFile()` Puts a GUI file-selection dialog box on the screen in which the user can select an output file.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### 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

  - ### Constructor Detail

    - #### TextIO

          public TextIO()

  - ### Method Detail

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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 minimum number of spaces possible.

    - #### 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.

    - #### putln

          public static void putln()

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

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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).

    - #### 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 (specified 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.

    - #### 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. (Ordinarily, end-of-file is not possible when reading from standard input.)

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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).

    - #### 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.

    - #### getlnString

          public static java.lang.String getlnString()

      This is identical to getln().

    - #### getln

          public static java.lang.String getln()

      Reads all the characters 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 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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.

    - #### 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).