Search results

std.io.BufferedWriter

type pub BufferedWriter[T: mut + Write[E], E]

A type that wraps a Write type and buffers the output.

Writing to a Write type can be expensive. The BufferedWriter type maintains an in-memory buffer of data to write, flushing it to an underlying stream whenever necessary. This can improve performance when performing many small writes using the same stream. If writes instead involve large data sizes or the writes are rare, the use of this type isn't likely to bring any benefits.

It's recommended to call BufferedWriter.flush before dropping a BufferedWriter. While this type implements std.drop.Drop and tries to flush the buffer when it's dropped, any errors produced by the flush are ignored.

Examples

import std.fs.file (WriteOnlyFile)
import std.io (BufferedWriter)

let file = WriteOnlyFile
  .new('out.txt')
  .or_panic_with('failed to open the file')
let writer = BufferedWriter.new(file)

writer.write('hello') # => Result.Ok(nil)
writer.flush          # => Result.Ok(nil)

Fields

inner

let pub @inner: T: mut

The Write type to write data to.

Static methods

new

Show source code

fn pub static new(writer: T) -> Self {
  with_capacity(writer, WRITE_BUFFER_SIZE)
}

fn pub static new(writer: T: mut) -> BufferedWriter[T: mut, E]

Returns a BufferedWriter that writes to writer, using the default buffer size of 8 KiB.

Examples

import std.fs.file (WriteOnlyFile)
import std.io (BufferedWriter)

let file = WriteOnlyFile
  .new('out.txt'.to_path)
  .or_panic_with('failed to open the file')

BufferedWriter.new(file)

with_capacity

Show source code

fn pub static with_capacity(writer: T, size: Int) -> Self {
  if size <= 0 { invalid_buffer_size(size) }

  Self(inner: writer, buffer: ByteArray.new, size: size)
}

fn pub static with_capacity(writer: T: mut, size: Int) -> BufferedWriter[T: mut, E]

Returns a BufferedWriter that writes to writer with a custom buffer size (in bytes).

Panics

This method panics if capacity is less than or equal to zero.

Examples

import std.fs.file (WriteOnlyFile)
import std.io (BufferedWriter)

let file = WriteOnlyFile
  .new('out.txt'.to_path)
  .or_panic_with('failed to open the file')

BufferedWriter.with_capacity(file, capacity: 16 * 1024)

Instance methods

flush

Show source code

fn pub mut flush -> Result[Nil, E] {
  if @buffer.size > 0 {
    try @inner.write(@buffer)
    @buffer.clear
  }

  Result.Ok(nil)
}

fn pub mut flush -> Result[Nil, E]

Writes any data stored in the buffer to the underlying stream, clearing the buffer in the process.

Refer to the documentation of Writer.flush for more details.

Errors

This method returns a std.io.Error if the data can't be written to the underlying stream.

print

Show source code

fn pub mut print[B: Bytes](bytes: ref B) -> Result[Nil, E] {
  try write(bytes)
  write('\n')
}

fn pub mut print[B: Bytes](bytes: ref B) -> Result[Nil, E]

Writes the entirety of bytes to the underlying stream, followed by a Unix newline.

write

Show source code

fn pub mut write[B: Bytes](bytes: ref B) -> Result[Nil, E] {
  let len = bytes.size

  # If the data size is the same as the buffer size we might as well just
  # write to the stream directly.
  if len >= @size {
    try flush
    try @inner.write(bytes)
    return Result.Ok(nil)
  }

  if @buffer.size == @size { try flush }

  let rem = @size - @buffer.size

  if len <= rem {
    @buffer.append(bytes)
    return Result.Ok(nil)
  }

  # The buffer isn't full but our data doesn't fit into it. We fill it up and
  # flush it, then write the data to the buffer. This ensures future calls to
  # this method have more buffer space to work with, compared to just a flush
  # plus appending the _entire_ data to the now empty buffer.
  @buffer.append(Slice.new(bytes, start: 0, end: rem))

  let _ = try flush

  @buffer.append(Slice.new(bytes, start: rem, end: len))
  Result.Ok(nil)
}

fn pub mut write[B: Bytes](bytes: ref B) -> Result[Nil, E]

Writes the entirety of bytes to the buffer, flushing it if necessary.

Errors

This method returns a std.io.Error if the data can't be written to the underlying stream.

Implemented traits

std.drop.

Drop

impl Drop for BufferedWriter

std.io.

Write

impl Write[E] for BufferedWriter