Skip to content
FutureBlitz

    Install

    Import std.io.file_stream

    std.io.file_stream

    Open files, which read, write, and seek as streams.

    std.io's open files: File.Open gives a FileStream, a Reader, Writer, and Seeker over a file, which reads and writes where it is, as Seek moves it, with Async twins that libuv's thread pool does while the main thread goes on.

    std/io/file_stream.fb

    Types

    OpenOptions struct 

    Public Struct OpenOptions

    How File.Open opens a file: to read, to write, or both, and, for one it writes, whether each write goes at its end, whether it's made when it isn't there, or only then, and whether what it held is gone first.

    Examples

    Local file = Try TempFile()
Try File.WriteText(file.Path, "start")
Local options = OpenOptions()
options.Write = True
options.Append = True
Local stream = Try File.Open(file.Path, options)
Try stream.WriteText(", then more")
stream.Close()
Expect((Try File.ReadText(file.Path)) == "start, then more")
Try file.Close()

    std/io/file_stream.fb, line 53

    • Public Field Read: Bool field #

      Whether it reads the file.

    • Public Field Write: Bool field #

      Whether it writes the file.

    • Public Field Append: Bool field #

      Each write goes at the file's end, wherever the stream is, which is a write too.

    • Public Field Create: Bool field #

      The file is made, empty, when it isn't there.

    • Public Field CreateNew: Bool field #

      The file is made, and one that's there is an IOError of ALREADY_EXISTS.

    • Public Field Truncate: Bool field #

      What the file held is gone once it's open.

    FileStream class 

    Public Class FileStream Implements Reader, Writer, Seeker

    A file opened to read, write, or both, at a place in it that each read and write moves on, and Seek moves anywhere, until it's closed, or its last reference goes. It holds nothing back, so Flush has nothing to do, and Sync puts what's been written onto the disk. A BufferedReader or a BufferedWriter around it takes fewer calls for small reads and writes. One call at a time goes on it: a call while an Async one is under way panics, and so does using it once it's closed, reading one not opened to read, and writing one not opened to write.

    Examples

    Local folder = Try TempDir()
Local path = folder.Path / "greeting.txt"
Local stream = Try File.Create(path)
Try stream.WriteText("hello, world")
Try stream.Seek(7, SeekOrigin.START)
Try stream.WriteText("there")
stream.Close()
Expect((Try File.ReadText(path)) == "hello, there")
Try folder.Close()

    std/io/file_stream.fb, line 109

    • Public ReadOnly Field Path: Path field #

      The file it's open on.

    • Public ReadOnly Field IsReadable: Bool field #

      Whether it was opened to read.

    • Public ReadOnly Field IsWritable: Bool field #

      Whether it was opened to write.

    • Public ReadOnly Field IsAppending: Bool field #

      Whether each write goes at the end.

    • Public Method IsOpen(): Bool method #

      Whether it's still open.

    • @PanicsAtCaller Public Method Read(into: Buffer<UInt8>): Int64 Throws IOError method #

      Reads up to into.Count bytes from where it is, and moves on past them.

    • @PanicsAtCaller Public Async Method ReadAsync(into: Buffer<UInt8>): Int64 Throws IOError method #

      Read's Async twin, which libuv's thread pool does while the main thread goes on.

    • @PanicsAtCaller Public Method Write(from: Buffer<UInt8>) Throws IOError method #

      Writes all of from's bytes where it is, or at the end when it appends, and moves on past them.

    • @PanicsAtCaller Public Async Method WriteAsync(from: Buffer<UInt8>) Throws IOError method #

      Write's Async twin, which libuv's thread pool does while the main thread goes on.

    • @PanicsAtCaller Public Method Flush() Throws IOError method #

      Holds nothing back, so there's nothing to send on, but it panics once it's closed too.

    • @PanicsAtCaller Public Async Method FlushAsync() Throws IOError method #

      Flush's Async twin, which has nothing to send on either, but panics once it's closed too.

    • @PanicsAtCaller Public Method Sync() Throws IOError method #

      Puts what's been written to the file onto the disk, as File's atomic writes do theirs, so it's there even if the machine stops. One not opened to write has nothing to put there.

    • @PanicsAtCaller Public Async Method SyncAsync() Throws IOError method #

      What Sync does, without blocking its thread: a call gives its Task.

    • @PanicsAtCaller Public Method Seek(offset: Int64, origin: SeekOrigin): Int64 Throws IOError method #

      Moves to offset bytes from origin, as Seeker says, where the next read reads and the next write writes, unless it appends. A place past the end is where a write makes the file longer, with 0s before it.

    • @PanicsAtCaller Public Method Size(): Int64 Throws IOError method #

      How many bytes the file has now.

    • @PanicsAtCaller Public Method Close() method #

      Closes the file, which a second Close leaves alone. What was written stays in the file, for the OS to put onto the disk.

    Report an issue with this page or with FutureBlitz on GitHub.