Search results

std.io.BufferedWriter

class pub BufferedWriter[T: mut + Write]

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('failed to open the file')
let writer = BufferedWriter.new(file)

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

Static methods

new

Show source code

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

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

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('failed to open the file')

BufferedWriter.new(file)

with_capacity

Show source code

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

  BufferedWriter(writer: writer, buffer: ByteArray.new, size: size)
}

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

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('failed to open the file')

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

Instance methods

flush

Show source code

fn pub mut flush -> Result[Nil, Error] {
  if @buffer.size > 0 {
    try @writer.write_bytes(@buffer)
    @buffer.clear
  }

  Result.Ok(nil)
}

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

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(string: String) -> Result[Nil, Error] {
  write_string(string).then(fn (_) { write_string('\n') })
}

fn pub mut print(string: String) -> Result[Nil, Error]

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

write_bytes

Show source code

fn pub mut write_bytes(bytes: ref ByteArray) -> Result[Nil, Error] {
  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 @writer.write_bytes(bytes)
    return Result.Ok(nil)
  }

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

  let rem = @size - @buffer.size

  if len <= rem {
    @buffer.copy_from(bytes, at: 0, size: len)
    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.
  let copied = @buffer.copy_from(bytes, at: 0, size: rem)

  try flush
  @buffer.copy_from(bytes, at: copied, size: len)
  Result.Ok(nil)
}

fn pub mut write_bytes(bytes: ref ByteArray) -> Result[Nil, Error]

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.

write_string

Show source code

fn pub mut write_string(string: String) -> Result[Nil, Error] {
  write_bytes(string.to_byte_array)
}

fn pub mut write_string(string: String) -> Result[Nil, Error]

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

Due to the internal buffer being a ByteArray, this method copies the bytes in string, rather than writing the String directly.

Refer to the documentation of BufferedWriter.write_bytes and Writer.write_bytes for more details.

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 for BufferedWriter