Libraries.System.AndroidAssetReader Documentation

This class allows for sequential file reading of assets on Android platforms. By "sequential," we mean that it is possible to only move forward in the file; re-reading data is not possible. This is most commonly used for reading plain text files.

Example Code

use Libraries.System.File
use Libraries.System.AndroidAssetReader

// Open an asset, read all of its contents, and then close it.
AndroidAssetReader reader
reader:OpenForRead("scores.txt")
text fileContents = reader:Read()
output "The contents are: " + fileContents
reader:Close()

// Open an asset, read the first two lines, and then close it.
File f
f:SetPath("settings.dat")
reader:OpenForRead(f)
text line1 = reader:ReadLine()
text line2 = reader:ReadLine()
reader:Close()

Inherits from: Libraries.System.Blueprints.FileReaderBlueprint, Libraries.Language.Object

Summary

Actions Summary Table

ActionsDescription
Close()When we open a file for reading, it is marked by the operating system as being in use by our application.
Compare(Libraries.Language.Object object)This action compares two object hash codes and returns an integer.
Equals(Libraries.Language.Object object)This action determines if two objects are equal based on their hash code values.
GetHashCode()This action gets the hash code for an object.
IsAtEndOfFile()Determine whether or not the end of the file has been reached.
Open(text assetName)Open an asset for sequential reading.
OpenForRead(Libraries.System.File file)Open a file for sequential reading.
Read(integer numberOfBytes)This action reads the specified number of bytes after our current position.
Read()This action reads all of the contents of our file from the current position.
ReadLine()Read a single line from the file.
ReadLines()This action reads all remaining lines from the file, starting from our current position and moving to the end of the file.

Actions Documentation

Close()

When we open a file for reading, it is marked by the operating system as being in use by our application. To make it possible for other files to use this file at a later point in time, it is necessary to tell the operating system when we are done with this file. To do this, we use the Close() action. We should call Close() as soon as we know that a file is no longer needed. If no file is open, Close() will do nothing. After Close() is called, a FileReader object is considered invalid, and no actions should be called on it, other than OpenForRead(), to open the same (or different) file.

Example Code

use Libraries.System.File
        use Libraries.System.FileReader

        // Open a file, read all the contents and close it.
        File f
        f:SetPath("To Do List.txt")
        FileReader reader
        reader:OpenForRead(f)

        output "Tim, your to do list says:"
        output reader:Read()
        
        // Close the file, as we no longer need it.
        reader:Close()

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns an integer. The result is larger if this hash code is larger than the object passed as a parameter, smaller, or equal. In this case, -1 means smaller, 0 means equal, and 1 means larger. This action was changed in Quorum 7 to return an integer, instead of a CompareResult object, because the previous implementation was causing efficiency issues.

Example Code

Object o
        Object t
        integer result = o:Compare(t) //1 (larger), 0 (equal), or -1 (smaller)

Parameters

Return

integer: The Compare result, Smaller, Equal, or Larger.

Equals(Libraries.Language.Object object)

This action determines if two objects are equal based on their hash code values.

Example Code

use Libraries.Language.Object
        use Libraries.Language.Types.Text
        Object o
        Text t
        boolean result = o:Equals(t)

Parameters

Return

boolean: True if the hash codes are equal and false if they are not equal.

GetHashCode()

This action gets the hash code for an object.

Example Code

Object o
        integer hash = o:GetHashCode()

Return

integer: The integer hash code of the object.

IsAtEndOfFile()

Determine whether or not the end of the file has been reached. The "end of file" signifies that no further text can be read from the file.

Example Code

use Libraries.System.File
        use Libraries.System.FileReader

        // Open the file for reading.
        File f
        f:SetPath("names.txt")
        FileReader reader
        reader:OpenForRead(f)

        // Read all the contents.
        text names = reader:Read()

        // We are now at the end of the file.
        boolean eof = reader:IsAtEndOfFile()
        if eof
            output "End of File has been reached."
        end

        // Always close the file.
        reader:Close()

Return

boolean: true if the end of the file has been detected; false otherwise.

Open(text assetName)

Open an asset for sequential reading. This is used to find assets stored in the Android application itself -- for files that are external to the application on the device itself, the FileReader class should be used instead.

Example Code

use Libraries.System.File
        use Libraries.System.AndroidAssetReader

        // Read the first two lines and then be done.
        AndroidAssetReader reader
        reader:Open(f)
        output reader:ReadLine()
        output reader:ReadLine()

        // Always close the file.
        reader:Close()

Parameters

OpenForRead(Libraries.System.File file)

Open a file for sequential reading. By "sequential reading," it is meant that it is impossible to go backwards in the file--we must make progress toward the end of the file with each successive read. This is extremely useful for reading plain text documents, but is much less useful for reading binary files. Binary files should use the FileRandomAccess class. The path of the file will be used to find the corresponding asset in the Android application. The working directory of the file is ignored.

Example Code

use Libraries.System.File
        use Libraries.System.AndroidAssetReader

        // Open the file for reading.
        File f
        f:SetPath("homework.txt")
        
        // Read the first two lines and then be done.
        AndroidAssetReader reader
        reader:OpenForRead(f)
        output reader:ReadLine()
        output reader:ReadLine()

        // Always close the file.
        reader:Close()

Parameters

Read(integer numberOfBytes)

This action reads the specified number of bytes after our current position. When we open a file, we start at the beginning--calling this action with a parameter of, for example, 2, would read the first two bytes of the file. If we perform some other reading action such as ReadLine(), and then call this action, the specified number of bytes will be read after our current position. If the number of bytes specified exceeds the end of the file, content up to the end of the file will be returned. If the end of the file has been reached before this action is called, an EndOfFileError will be raised.

Example Code

use Libraries.System.File
        use Libraries.System.FileReader

        // Open a file, output the first four bytes.
        File f
        f:SetPath("Settings.dat")
        FileReader reader
        reader:OpenForRead(f)
        output "The first four bytes are " + reader:Read(4)
        reader:Close()

Parameters

Return

text: the file contents we have read

Read()

This action reads all of the contents of our file from the current position. When we open a file, we start at the beginning--so calling this action immediately after opening a file will read the entire file. If we perform some other reading action, such as ReadLine(), and then call this action, we will receive all file contents after the point where we have read. If the end of file has already been reached before calling this action, an EndOfFileError will be raised.

Example Code

use Libraries.System.File
        use Libraries.System.FileReader

        // Open a file, read all of its contents to a text value and then  output the text value.
        File f
        f:SetPath("Settings.dat")
        FileReader reader
        reader:OpenForRead(f)
        text settings = reader:Read()

        output "The settings are:"
        output settings
        reader:Close()

Return

text: the file contents from our current position to the end of the file.

ReadLine()

Read a single line from the file. What constitutes a line is dependent upon the operating system. In general, a "line" is created by pressing the enter key in a text editor. Quite often, file contents are delimited by separate lines. For example, a file containing a list of words may have the contents, "hello textual inquire fizz" which may be easily read one at a time using the ReadLine() action.

Example Code

use Libraries.System.File
        use Libraries.System.FileReader

        // Open a file, read all of its contents to a text value and then output the text value.
        File f
        f:SetPath("words.txt")
        FileReader reader
        reader:OpenForRead(f)

        // We will assume 'words.txt' separates words by lines. Read the first two words.
        output reader:ReadLine()

Return

text: the text read from the line.

ReadLines()

This action reads all remaining lines from the file, starting from our current position and moving to the end of the file.

Example Code

use Libraries.Containers.Array
        use Libraries.System.File
        use Libraries.System.FileReader
        
        // Read all lines into a collection and output the third line. If there is no third line, the appropriate error will be raised.
        File f
        f:SetPath("/Users/jeff/helloWorld.txt")
        FileReader reader
        reader:OpenForRead(f)
        Array<text> lines = reader:ReadLines()

        output "The third line is " + lines:Get(2) // indices are zero-based.
        reader:Close()

Return

Libraries.Containers.Array: an indexable collection of text objects, representing all read lines.