Class ReadFile

java.lang.Object
  |
  +--ReadFile

public class ReadFile

extends java.lang.Object

This class provides a set of simplified read-only text file methods that hide some of the details of file streams for new programmers.

Constructor Summary

ReadFile()
Constructs a new ReadFile object and sets the file to null.

Method Summary

void	closeFile() Closes an open file.
boolean	openFile(java.lang.String name) Opens a new read-only text file for reading data.
java.lang.Double	readDouble() Reads an double value from the currently opened file.
java.lang.Integer	readInt() Reads an integer value from the currently opened file.
java.lang.String	readString() Reads a string of text from the currently opened text file.

Methods inherited from class java.lang.Object

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

Constructor Detail

ReadFile

public ReadFile()

Constructs a new ReadFile object and sets the file to null. Example usage:

ReadFile rf = new ReadFile();

Creates a new ReadFile object for subsequent usage (see openFile() method).

Method Detail

openFile

public boolean openFile(java.lang.String name)

Opens a new read-only text file for reading data. Name is the name of a file in the working directory, or a full path and file name. Once a ReadFile object is created (above) it can be used as follows to open a file:

boolean success = rf.openFile("myfile.txt");

Opens the file myfile.txt if it exists in the working directory. The file will have a position pointer pointing at the first character in the file. Each read operation from the file, advances the pointer past the next end-of-line marker (<EOL>), which is an <ENTER> character.

Text files consist of strings of characters. Lines are defined as a string of characters up to the EOL character (which is filtered out of the line when it is read. For example:

This is an example of a text file line<EOL>
^
This is a second line in the file<EOL>
22.2222<EOL>
The above line is a line of text also, even though it is numbers.<EOL>
The file ends with an end-of-line and an end-of-file<EOL>
<EOF>

In the above, the caret character does not show up, it only represents the pointer to the character. A read operation from the file would advance the pointer to the first character ('T') in the next line. A file must be opened before any read operation will work on the file. See examples of read*() methods.

Note that each data object (String, Integer or Double) must be on its own line, as in the above example.

Returns: true if file is successfully opened, false otherwise.

closeFile

public void closeFile()

Closes an open file. If no file is open, there is no effect. Usage:

rf.closeFile();

Once a file has been closed, the ReadFile object may be reused to open a new text file.

readString

public java.lang.String readString()

Reads a string of text from the currently opened text file. The string will be a complete line of text (characters) up to the next end-of-line (<EOL>) character. For example, if the text file contains the following lines of text:

Hello world<EOL>
22.22345<EOL>
<EOF>

the following operation

String s = rf.readString();

would result in the variable s containing the string "Hello world" and the pointer pointing to the first digit '2' in the next line. A subsequent use of readString() on the file would result in a String containing the string "22.22345". If the intent is to read a double, then use the readDouble() method rather than readString().

Returns a String object containing the line of text. If the returned string has a zero length, then the line was empty. If the String object is null, then no text was available and should be considered as an end-of-file condition.

readInt

public java.lang.Integer readInt()

Reads an integer value from the currently opened file. The integer is returned as an Integer object so the calling program needs to extract the int value from the Integer object. Usage:

Integer iObj = rf.readInt();
if (iObj != null) {
int i = iObj.intValue();
// use integer
}
else {
// assume end-of-file
}

Advances the pointer past the end-of-line. Note that if the object read is not an integer, the method returns a null object. This could either indicate an error (such as a non-integer being read) or an end-of-file condition. It is the programmer's responsibility to understand the file format being read in order to properly use a readInt() method. It is best to use this readInt() method for files that contain a list of integer values (as opposed to mixed data). To read mixed data files, it is best to use the readString() method and then use a try {} catch(NumberFormatException e){} to check the data contents, e.g.:

String s = rf.readString();
try {
int i = Integer.parseInt(s);
}
catch (NumberFormatException e) {
// check for another data type and do whatever is necessary
}

Returns an Integer object if the read was successful, otherwise it returns a null.

readDouble

public java.lang.Double readDouble()

Reads an double value from the currently opened file. The double is returned as a Double object so the calling program needs to extract the double value from the Double object. Usage:

Double dObj = rf.readDouble();
if (dObj != null) {
double d = dObj.doubleValue();
// use double
}
else {
// assume end-of-file
}

Advances the pointer past the end-of-line. Note that if the object read is not an double, the method returns a null object. This could either indicate an error (such as a non-double being read) or an end-of-file condition. It is the programmer's responsibility to understand the file format being read in order to properly use a readDouble() method. It is best to use this readDouble() method for files that contain a list of double values (as opposed to mixed data). To read mixed data files, it is best to use the readString() method and then use a try {} catch(NumberFormatException e){} to check the data contents, e.g.:

String s = rf.readString();
try {
double d = Double.parseDouble(s);
}
catch (NumberFormatException e) {
// check for another data type and do whatever is necessary
}

Returns a Double object if the read was successful, otherwise it returns a null.