Developer Resources

FileStream

Overview

The FileStream class represents a file access stream for reading and writing binary values to a file.

Methods

FileStream.close
Closes a file stream
FileStream.read
Reads data from a file.
FileStream.seek
Seeks to a location in a file.
FileStream.write
Writes data to a file.

Example

// create a binary file
var f = File.open("data.bin",
                  FileMode.Create,
                  FileAccess.ReadWrite,
                  FileShare.None);

// make a buffer with some data to write       
var buf = new MemoryBuffer(3);
buf[0] = 0;
buf[1] = 1;
buf[2] = 2;

// write the buffer to the file
f.write(buf, 0, 3);

// close the file
f.close();

// check to make sure it exists
if (File.exists("data.bin"))
{
    alert("file created successfully.");
}

// open up the file for reading
f = File.open("data.bin",
              FileMode.Open,
              FileAccess.Read,
              FileShare.None);
buf.clear();

// read 3 bytes from the file
f.read(buf, 0, 3);

alert("The following value should be 2.  It is: " + buf[2]);

FileStream.close

function FileStream.close() : Boolean

Returns

True if the file stream was successfully closed, or false if an error was encountered. If the file stream was not open when close() was called, false is returned.

Description

Calling the close() method will close an open file stream and free resources used during the file input/output operations

FileStream.read

function FileStream.read(buffer : MemoryBuffer, offset : Integer, num_bytes : Integer) : Integer

Arguments

buffer
Target memory buffer for the read operation.
offset
Offset inside the buffer at which to place the data.
num_bytes
Number of bytes to read.

Returns

The total number of bytes read, or zero if an end of file condition was encountered, or if an error occurred.

Description

Reads the number of bytes specified by the parameter num_bytes into the buffer specified by the buffer parameter. The bytes will be placed in the buffer at the offset specified in the offset parameter. The array needs to be large enough to hold the requested number of bytes, otherwise the call will fail.

FileStream.seek

function FileStream.seek(offset : Integer, origin : SeekOrigin) : Boolean

Arguments

offset
Offset to seek to, relative to the origin parameter.
origin
Place to start seek from, one of the values from the SeekOrigin enumeration.

Returns

Returns true upon success, and false otherwise.

Description

Seeks to the relative position specified by offset. The starting point for the seek is specified by the second parameter. The value of origin can be SeekOrigin.Begin, SeekOrigin.Current, or SeekOrigin.End.

FileStream.write

function FileStream.write(buffer : MemoryBuffer, offset : Integer, num_bytes : Integer) : Integer

Arguments

buffer
Source memory buffer for the write operation.
offset
Offset inside the buffer at which to write from.
num_bytes
Number of bytes to write.

Returns

The total number of bytes written by the operation or zero if an error occurred.

Description

Writes the number of bytes specified by the parameter num_bytes from the buffer specified by the buffer parameter. The bytes from the buffer will be written from the offset specified in the offset parameter.