FileStream Class

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

// the file this example creates, in the system's temporary directory
// (Environment.getTempPath() does not include a trailing separator)
const path = `${Environment.getTempPath()}/stream.bin`;

// create a binary file; File.open() returns a FileStream
let stream = File.open(path,
                       FileMode.Create,
                       FileAccess.ReadWrite,
                       FileShare.None);

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

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

// close the stream
stream.close();

// check to make sure the file exists
if (File.exists(path)) {
    alert("file created successfully.");
}

// open up the file for reading
stream = File.open(path,
                   FileMode.Open,
                   FileAccess.Read,
                   FileShare.None);
buf.clear();

// read 3 bytes from the stream
stream.read(buf, 0, 3);
stream.close();

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.