Overview | File | Class | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## Class FileStream

    Object
       |
       +--FileStream

class FileStream

A FileStream allows reading or writing specific parts of a File.

The `FileStream` class exposes several ways of reading from and writing to Files. Examples include reading and writing bytes, strings and lines.

When the `FileStream` is created a pointer is usually set at the beginning of the file. As the read methods are called, the pointer moves through the file. Subsequent calls to the read methods read from that point and onward. When the end of the file is reached, the `eof` property is set to `true`.

This class supports Base64 data for use in cases like `XMLHttpRequest`. This object does not support writing binary data, so the Base64 methods can be used to write binary data encoded as strings.

By default, the `FileStream` object uses an UTF-8 encoding when writing. You can change this by setting the `encoding` property of the `FileStream` or by supplying a `charset` argument to the various methods that write characters.

Defined in file-io.js

Field Summary
`int` | `bytesAvailable` Number of of bytes available from the current position to the end of the `FileStream`.
`String` | `encoding` The encoding of this `FileStream`.
`boolean` | `eof` Whether or not the end of the `FileStream` has been reached.
`String` | `newLine` Newline character used for this particular `FileStream`.
`int` | `position` The current byte index position of this `FileStream`.
`String` | `systemNewLine` The system default character for separating lines in a file.

Constructor Summary
`FileStream()` This class has no public constructor.

Method Summary
`void` | `close( )` Close the `FileStream` for reading or writing.
`String` | `read( <int> length, <String> charset )` Read a number of characters from the FileStream.
`String` | `readBase64( <int> length )` Read bytes from the `FileStream` and encode it as Base64
`ByteArray` | `readBytes( <int> length )` Read a number of bytes from the `FileStream`
`String` | `readLine( <String> charset )` Read a line of characters from the `FileStream`
`void` | `write( <String> string, <String> charset )` Write a string of characters to the `FileStream`
`void` | `writeBase64( <String> string )` Decode a Base64 encoded string and write the data to the `FileStream`.
`void` | `writeBytes( <ByteArray> bytes, <int> length )` Write a set of bytes to the `FileStream`
`void` | `writeFile( <File> file )` Write a File to the `FileStream`.
`void` | `writeImage( <HTMLImageElement> image )` Write an image to the `FileStream`.
`void` | `writeLine( <String> string, <String> charset )` Write a line of characters to the FileStream

Field Detail

### bytesAvailable

    int bytesAvailable

Number of of bytes available from the current position to the end of the `FileStream`. The value of this property is effectively `fileSize` - `position`.

### encoding

    String encoding

The encoding of this `FileStream`. This property defaults to UTF-8. Change it to override the default encoding used when writing to the `FileStream`. This can be overridden on a case-by-case basis by supplying the `charset` argument to the various methods which write characters.

### eof

    boolean eof

Whether or not the end of the `FileStream` has been reached. If the `FileStream` is unreadable, this property is `true`.

### newLine

    String newLine

Newline character used for this particular `FileStream`. This is the same as systemNewLine when the `FileStream` is created. This can be set to override the default character used for splitting lines when calling readLine() or writeLine().

### position

    int position

The current byte index position of this `FileStream`. You may set the position programmatically. If it is set to < 0, the position will be 0. If it is set to > `fileSize`, the position will be `fileSize`.

### systemNewLine

    String systemNewLine

The system default character for separating lines in a file. Readonly.

Constructor Detail

### FileStream

    FileStream()

This class has no public constructor.

Method Detail

### close

    void close( )

Close the `FileStream` for reading or writing.

### read

    String read( <int> length, <String> charset )

Read a number of characters from the FileStream.

This function will read `length` number of characters from the stream.

If there are less than `length` characters left in the file, only the remaining characters in the file are read, and the `eof` property is set to `true`.

If `eof` is `true` when this method is called, null will be returned.

The resulting String is encoded with the charset in the `FileStream.encoding` property unless the optional `charset` argument is given.

Parameters:

`length` - Number of characters to read.

`charset` - The character set to use when reading.

Returns:

A String of characters, or null if there are no more characters left in the File.

Throws:

- GENERIC_ERR If it is not possible to read from the stream.

### readBase64

    String readBase64( <int> length )

Read bytes from the `FileStream` and encode it as Base64

This method will read `length` number of bytes from the `FileStream` and return the data as a Base64 encoded String.

This is typically used to encode data from binary files in order to transfer them for example over `XMLHttpRequest`.

As the method will read a number of bytes as specified in the length argument, and then encode it, a call to `stream.readBase64(100)` will not necessarily end up as a String with a length of 100.

If there are less than `length` bytes left in the file, only the remaining bytes in the file are read, and the `eof` property is set to `true`.

If `eof` is `true` when this method is called, null will be returned.

Parameters:

`length` - Number of bytes to read.

Returns:

The content of the `FileStream` as a Base64 encoded String, or null if there are no data to read.

Throws:

- GENERIC_ERR If it is not possible to read from the stream.

### readBytes

    ByteArray readBytes( <int> length )

Read a number of bytes from the `FileStream`

This function will read `length` number of bytes from the `FileStream`.

If there are less than `length` bytes left in the file, only the remaining bytes in the file are read, and the `eof` property is set to `true`.

If `eof` is `true` when this method is called, null will be returned.

Parameters:

`length` - The number of bytes to read.

Returns:

A ByteArray with the bytes read from the FileStream, or null if there are no data to read.

Throws:

- GENERIC_ERR If it is not possible to read from the stream.

### readLine

    String readLine( <String> charset )

Read a line of characters from the `FileStream`

This functions will read all characters up to and including the next newline in the `FileStream` as defined by the newLine property. If there are no newlines left in the stream, the resulting string will not have a newline character and the `eof` property is set to `true`.

If `eof` is `true` when this method is called, null is returned.

The resulting String is encoded with the charset in the `FileStream.encoding` property unless the optional charset argument is given.

Parameters:

`charset` - The character set to use when reading. Optional.

Returns:

A String of characters, or null if there are no data to read.

Throws:

- GENERIC_ERR If it is not possible to read from the stream.

### write

    void write( <String> string, <String> charset )

Write a string of characters to the `FileStream` This method will write the given String of characters to the `FileStream`, using the given `charset` or the charset in the `FileStream.encoding` property.

The `charset` argument is currently ignored.

Parameters:

`string` - The String of characters to write.

`charset` - The charset to use when writing. Optional.

Throws:

- GENERIC_ERR If it is not possible to write to the stream.

### writeBase64

    void writeBase64( <String> string )

Decode a Base64 encoded string and write the data to the `FileStream`. This method takes a String encoded as Base64, decodes it and writes the resulting data to the `FileStream`. It is typically used for binary data encoded as Base64 when its transferred for example over `XMLHttpRequest`.

Parameters:

`string` - Base64 encoded String to write.

Throws:

- GENERIC_ERR If it is not possible to write to the stream.

### writeBytes

    void writeBytes( <ByteArray> bytes, <int> length )

Write a set of bytes to the `FileStream` This method will write the `length` first bytes from the given `ByteArray` to the stream.

Parameters:

`bytes` - The bytes to write.

`length` - The number of bytes to write.

Throws:

- GENERIC_ERR If it is not possible to write to the stream.

### writeFile

    void writeFile( <File> file )

Write a File to the `FileStream`. This will write the entire contents of the given File to the `FileStream`.

Parameters:

`file` - The File to write.

Throws:

- GENERIC_ERR If it is not possible to write to the stream.

### writeImage

    void writeImage( <HTMLImageElement> image )

Write an image to the `FileStream`. This function will take either an `HTMLImageElement` or an `HTMLCanvasElement` and write the binary data to the `FileStream`. In the case of `HTMLCanvasElement`, the image is first encoded as a PNG image.

Parameters:

`image` - The `HTMLImageElement` or `HTMLCanvasElement` to write.

Throws:

- GENERIC_ERR If it is not possible to write to the stream.

### writeLine

    void writeLine( <String> string, <String> charset )

Write a line of characters to the FileStream

This method will write the given String with an appended newline character taken from the newLine property to the `FileStream`, using the given charset or the charset in the `FileStream.encoding` property.

The `charset` argument is currently ignored.

Parameters:

`string` - The string of characters to write.

`charset` - The `charset` to use when writing. Optional.

Throws:

- GENERIC_ERR If it is not possible to write to the stream.

Overview | File | Class | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Documentation generated by JSDoc on Fri Jan 29 17:08:19 2010