file_streams/file_stream

Work with file streams in Gleam.

Types

FileStream

opaque </>

A file stream that data can be read from and/or written to depending on the modes specified when it was opened.

pub opaque type FileStream

FileStreamLocation

</>

A file stream location defined relative to the beginning of the file, the end of the file, or the current position in the file stream. This type is used with the position() function.

pub type FileStreamLocation {
  BeginningOfFile(offset: Int)
  CurrentLocation(offset: Int)
  EndOfFile(offset: Int)
}

Constructors

```
BeginningOfFile(offset: Int)
```
A location relative to the beginning of the file, i.e. an absolute offset in the file stream. The offset should not be negative.
```
CurrentLocation(offset: Int)
```
A location relative to the current position in the file stream. The offset can be either positive or negative.
```
EndOfFile(offset: Int)
```
A location relative to the end of the file stream. The offset should not be positive.

Functions

open

</>

pub fn open(
  filename: String,
  modes: List(FileOpenMode),
) -> Result(FileStream, FileStreamError)

Opens a new file stream that can read and/or write data from the specified file. See FileOpenMode for all of the available file modes.

For simple cases of opening a file stream prefer one of the open_read(), open_write(), open_read_text(), or open_write_text() helper functions to avoid needing to manually specify the file mode.

Once the file stream is no longer needed it should be closed with close().

open_read

</>

pub fn open_read(
  filename: String,
) -> Result(FileStream, FileStreamError)

Opens a new file stream for reading from the specified file. Allows for efficient reading of binary data and lines of UTF-8 text.

The modes used are:

Read
ReadAhead(size: 64 * 1024)
Raw

open_read_text

</>

pub fn open_read_text(
  filename: String,
  encoding: TextEncoding,
) -> Result(FileStream, FileStreamError)

Opens a new file stream for reading encoded text from a file. If only reading of UTF-8 lines of text is needed then prefer open_read() as it is much faster due to using Raw mode.

The modes used are:

Read
ReadAhead(size: 64 * 1024)
Encoding(encoding)

The text encoding for a file stream can be changed with set_encoding.

This function is not supported on the JavaScript target.

open_write

</>

pub fn open_write(
  filename: String,
) -> Result(FileStream, FileStreamError)

Opens a new file stream for writing to a file. Allows for efficient writing of binary data and UTF-8 text.

The modes used are:

Write
DelayedWrite(size: 64 * 1024, delay: 2000)
Raw

open_write_text

</>

pub fn open_write_text(
  filename: String,
  encoding: TextEncoding,
) -> Result(FileStream, FileStreamError)

Opens a new file stream for writing encoded text to a file. If only writing of UTF-8 text is needed then prefer open_write() as it is much faster due to using Raw mode.

The modes used are:

Write
DelayedWrite(size: 64 * 1024, delay: 2000)
Encoding(encoding)

The text encoding for a file stream can be changed with set_encoding.

This function is not supported on the JavaScript target.

position

</>

pub fn position(
  stream: FileStream,
  location: FileStreamLocation,
) -> Result(Int, FileStreamError)

Sets the position of a file stream to the given location, where the location can be relative to the beginning of the file, the end of the file, or the current position in the file. On success, returns the current position in the file stream as an absolute offset in bytes.

If a file stream is opened in Append mode then data is always written at the end of the file, regardless of the current file position.

read_bytes

</>

pub fn read_bytes(
  stream: FileStream,
  byte_count: Int,
) -> Result(BitArray, FileStreamError)

Reads bytes from a file stream. The returned number of bytes may be fewer than the number that was requested if the end of the file stream was reached.

If the end of the file stream is encountered before any bytes can be read then Error(Eof) is returned.

This function is supported when the file stream was opened in Raw mode or it uses the default Latin1 text encoding. If this is not the case then use read_chars() or read_line().

read_bytes_exact

</>

pub fn read_bytes_exact(
  stream: FileStream,
  byte_count: Int,
) -> Result(BitArray, FileStreamError)

Reads the requested number of bytes from a file stream. If the requested number of bytes can’t be read prior to reaching the end of the file stream then Error(Eof) is returned.

This function is supported when the file stream was opened in Raw mode or it uses the default Latin1 text encoding. If this is not the case then use read_chars() or read_line() should be used instead.

read_chars

</>

pub fn read_chars(
  stream: FileStream,
  count: Int,
) -> Result(String, FileStreamError)

Reads the next count characters from a file stream. The returned number of characters may be fewer than the number that was requested if the end of the stream is reached.

This function is not supported for file streams opened in Raw mode. Use the read_line() function instead.

This function is not supported on the JavaScript target.

read_float32_be

</>

pub fn read_float32_be(
  stream: FileStream,
) -> Result(Float, FileStreamError)

Reads a big-endian 32-bit float from a file stream.

read_float32_le

</>

pub fn read_float32_le(
  stream: FileStream,
) -> Result(Float, FileStreamError)

Reads a little-endian 32-bit float from a file stream.

read_float64_be

</>

pub fn read_float64_be(
  stream: FileStream,
) -> Result(Float, FileStreamError)

Reads a big-endian 64-bit float from a file stream.

read_float64_le

</>

pub fn read_float64_le(
  stream: FileStream,
) -> Result(Float, FileStreamError)

Reads a little-endian 64-bit float from a file stream.

read_int16_be

</>

pub fn read_int16_be(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a big-endian 16-bit signed integer from a file stream.

read_int16_le

</>

pub fn read_int16_le(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a little-endian 16-bit signed integer from a file stream.

read_int32_be

</>

pub fn read_int32_be(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a big-endian 32-bit signed integer from a file stream.

read_int32_le

</>

pub fn read_int32_le(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a little-endian 32-bit signed integer from a file stream.

read_int64_be

</>

pub fn read_int64_be(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a big-endian 64-bit signed integer from a file stream.

read_int64_le

</>

pub fn read_int64_le(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a little-endian 64-bit signed integer from a file stream.

read_int8

</>

pub fn read_int8(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads an 8-bit signed integer from a file stream.

read_line

</>

pub fn read_line(
  stream: FileStream,
) -> Result(String, FileStreamError)

Reads the next line of text from a file stream. The returned string will include the newline \n character. If the stream contains a Windows newline \r\n then only the \n will be returned.

This function always reads UTF-8 for file streams opened in Raw mode. Otherwise, it uses the text encoding specified when the file was opened.

This function is not supported on the JavaScript target.

read_list

</>

pub fn read_list(
  stream: FileStream,
  item_read_fn: fn(FileStream) -> Result(a, FileStreamError),
  item_count: Int,
) -> Result(List(a), FileStreamError)

Reads the specified type the requested number of times from a file stream, e.g. two little-endian 32-bit integers, or four big-endian 64-bit floats, and returns the values in a list.

Examples

read_list(stream, read_int32_le, 2)
|> Ok([1, 2])

read_list(stream, read_float64_be, 4)
|> Ok([1.0, 2.0])

read_remaining_bytes

</>

pub fn read_remaining_bytes(
  stream: FileStream,
) -> Result(BitArray, FileStreamError)

Reads all remaining bytes from a file stream. If no more data is available in the file stream then this function will return an empty bit array. It never returns Error(Eof).

read_uint16_be

</>

pub fn read_uint16_be(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a big-endian 16-bit unsigned integer from a file stream.

read_uint16_le

</>

pub fn read_uint16_le(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a little-endian 16-bit unsigned integer from a file stream.

read_uint32_be

</>

pub fn read_uint32_be(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a big-endian 32-bit unsigned integer from a file stream.

read_uint32_le

</>

pub fn read_uint32_le(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a little-endian 32-bit unsigned integer from a file stream.

read_uint64_be

</>

pub fn read_uint64_be(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a big-endian 64-bit unsigned integer from a file stream.

read_uint64_le

</>

pub fn read_uint64_le(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads a little-endian 64-bit unsigned integer from a file stream.

read_uint8

</>

pub fn read_uint8(
  stream: FileStream,
) -> Result(Int, FileStreamError)

Reads an 8-bit unsigned integer from a file stream.

set_encoding

</>

pub fn set_encoding(
  stream: FileStream,
  encoding: TextEncoding,
) -> Result(FileStream, FileStreamError)

Changes the text encoding of a file stream from what was configured when it was opened. Returns a new FileStream that should be used for subsequent calls.

This function is not supported for file streams opened in Raw mode.

This function is not supported on the JavaScript target.

sync

</>

pub fn sync(stream: FileStream) -> Result(Nil, FileStreamError)

Syncs a file stream that was opened for writing. This ensures that any write buffers kept by the operating system (not by the Erlang runtime system) are written to disk.

When a file stream is opened with delayed writes enabled to improve performance, syncing can return an error related to flushing recently written data to the underlying device.

write_bytes

</>

pub fn write_bytes(
  stream: FileStream,
  bytes: BitArray,
) -> Result(Nil, FileStreamError)

Writes raw bytes to a file stream.

This function is supported when the file stream was opened in Raw mode or it uses the default Latin1 text encoding. If this is not the case then use write_chars().

write_chars

</>

pub fn write_chars(
  stream: FileStream,
  chars: String,
) -> Result(Nil, FileStreamError)

Writes characters to a file stream. This will convert the characters to the text encoding specified when the file stream was opened.

For file streams opened in Raw mode, this function always writes UTF-8.

This function is not supported on the JavaScript target.