FileStream

Struct · namespace System · Since 0.19

struct FileStream : IDisposable

A file, read and written as bytes, with seeking. StreamReader reads lines of text, StreamWriter writes text. All of them are IDisposable, so using closes them:

using var reader = try StreamReader.Open("data.txt");
while (reader.ReadLine() is string line)
    Console.WriteLine(line);

using var writer = try StreamWriter.Create("out.txt");
writer.WriteLine("first line");

using var stream = try FileStream.OpenRead("image.bin");
var header = new uint8[16];
int got = stream.Read(header, 0, 16);

A stream is a struct around the C library’s FILE: copies of it share the open file, and Close (or Dispose) of one copy closes it for all; keep one owner. Text is UTF-8.

Static methods

Name	Description
OpenRead	Opens an existing file for reading.
OpenReadWrite	Opens an existing file for reading and writing, from the start, without truncating it.
Create	Creates a new, empty file for writing (an existing one is truncated).
Append	Opens a file for writing at its end; it is created if it does not exist.

OpenRead

static IoError<FileStream> OpenRead(StringSlice path)

Opens an existing file for reading.

Errors

• IoError.CannotOpen: the file does not exist or cannot be read.

OpenReadWrite

static IoError<FileStream> OpenReadWrite(StringSlice path)

Opens an existing file for reading and writing, from the start, without truncating it.

Errors

• IoError.CannotOpen: the file does not exist or cannot be opened.

Create

static IoError<FileStream> Create(StringSlice path)

Creates a new, empty file for writing (an existing one is truncated).

Errors

• IoError.CannotCreate: the file cannot be created (a missing folder, no permission).

Append

static IoError<FileStream> Append(StringSlice path)

Opens a file for writing at its end; it is created if it does not exist.

Errors

• IoError.CannotCreate: the file cannot be opened or created.

Methods

Name	Description
IsOpen	Whether the stream is open (not closed yet).
Read	Reads up to count bytes into buffer[offset..].
ReadByte	Reads one byte.
Write	Writes count bytes of buffer from offset.
WriteByte	Writes one byte.
WriteText	Writes text as UTF-8 bytes.
Position	The position in bytes from the start of the file.
Seek	Moves the position to offset bytes from origin.
Length	The size of the file in bytes (the position stays).
Flush	Writes what the C library still holds in its buffer to the file.
Close	Closes the file; the copies of the stream are closed as well.
Dispose	Closes the file (FileStream.Close); using calls it.

IsOpen

bool IsOpen()

Whether the stream is open (not closed yet).

Read

int Read(uint8[] buffer, int offset, int count)

Reads up to count bytes into buffer[offset..].

Returns the number of bytes read; 0 at the end of the file.

Panics when offset..offset + count is not inside of buffer.

ReadByte

int ReadByte()

Reads one byte.

Returns the byte, or -1 at the end of the file.

Write

IoError<void> Write(uint8[] buffer, int offset, int count)

Writes count bytes of buffer from offset.

Errors

• IoError.CannotWrite: the stream is closed or writing failed.

Panics when offset..offset + count is not inside of buffer.

IoError<void> Write(ReadOnlySlice<uint8> bytes)

Writes all of bytes: an array, a part of one, or the bytes of a text (text.AsBytes()).

Errors

• IoError.CannotWrite: the stream is closed or writing failed.

WriteByte

IoError<void> WriteByte(uint8 value)

Writes one byte.

Errors

• IoError.CannotWrite: the stream is closed or writing failed.

WriteText

IoError<void> WriteText(StringSlice text)

Writes text as UTF-8 bytes.

Errors

• IoError.CannotWrite: the stream is closed or writing failed.

Position

int64 Position()

The position in bytes from the start of the file.

Seek

bool Seek(int64 offset, SeekOrigin origin)

Moves the position to offset bytes from origin.

Returns false if that is not possible.

Length

int64 Length()

The size of the file in bytes (the position stays).

Flush

void Flush()

Writes what the C library still holds in its buffer to the file.

Close

void Close()

Closes the file; the copies of the stream are closed as well. Closing it again does nothing.

Dispose

void Dispose()

Closes the file (FileStream.Close); using calls it.