Toit
Libraries
bignum
binary
bitmap
ble
bytes
core
crypto
device
encoding
esp32
expect
fixed-point
flash
font
gpio
i2c
i2s
icons
io
line-wrap
log
math
monitor
net
pulse-counter
reader
reader-writer
rmt
serial
spi
statistics
system
tls
uart
uuid
writer
zlib

Class Buffer

extends CloseableWriter
A buffer that can be used to build byte data.
Aliases
  • BytesBuilder: Dart
  • ByteArrayOutputStream: Java

Class summary

constructor bytes/ByteArray --growable/bool=
Constructs a new buffer, using the given bytes as backing array.
constructor
Constructs a new buffer.

Constructors

constructor bytes/ByteArray --growable/bool=false
Constructs a new buffer, using the given bytes as backing array.
If growable is true, then the bytes array might be replaced with a bigger one if needed.
The current backing array can be accessed with backing-array.
A view, only containing the data that has been written so far, can be accessed with bytes.
constructor
Constructs a new buffer.
The backing byte array is allocated with a default size and will grow if needed.

Statics

with-capacity size/int --growable/bool=true -> Buffer
Constructs a new buffer with the given initial size.
If growable is true (the default), then the backing array might be replaced with a bigger one if needed.
The current backing array can be accessed with backing-array.
A view, only containing the data that has been written so far, can be accessed with bytes.

Methods

backing-array -> ByteArray
The backing array of this buffer.
If is-growable is false, always returns the array that was passed to the constructor.
This array might have a bigger size than the number of bytes that have been written.
big-endian -> EndianBuffer
Provides endian-aware functions to write to this instance.
The big-endian byte order writes higher-order (big) bytes first. For example, if the target of the write operation is a byte array, then the first byte written (at position 0) is the most significant byte of the number that is written.
Examples

import io

main:
  buffer := io.Buffer
  buffer.big-endian.write-int32 0x12345678
  // The most significant byte 0x12 is at index 0.
  print buffer.bytes  // => #[0x12, 0x34, 0x56, 0x78]

  // The buffer version also supports 'put' operations
  buffer.big-endian.put-int32 --at=0 0x11223344
bytes -> ByteArray
A view of the backing array that only contains the bytes that have been written so far.
clear -> none
Resets this instance, discarding all accumulated data.
close -> none
Closes this instance.
If this instance is growable, trims the backing store to avoid waste.
See is-growable.
flush -> none
Flushes any buffered data to the underlying resource.
Often, one can just use the --flush flag of the write, write-byte or write-from functions instead.
Inheritance
This method may be overwritten by subclasses. The default implementation does nothing.
grow-by amount/int --value/int=0 -> none
Grows the buffer by the given amount.
The new bytes are initialized to value.
is-closed -> bool
Whether this writer is closed.
is-growable -> bool
Whether this instance is allowed to replace the backing store with a bigger one.
If false, then the backing-array is always equal to the array that was passed to the constructor.
little-endian -> EndianBuffer
Provides endian-aware functions to write to this instance.
The little-endian byte order writes lower-order ("little") bytes first. For example, if the target of the write operation is a byte array, then the first byte written (at position 0) is the least significant byte of the number that is written.
Examples

import io

main:
  buffer := io.Buffer
  buffer.little-endian.write-int32 0x12345678
  // The least significant byte 0x78 is at index 0.
  print buffer.bytes  // => #[0x78, 0x56, 0x34, 0x12]

  // The buffer version also supports 'put' operations
  buffer.little-endian.put-int32 --at=0 0x11223344
operator [] index/int -> int
Returns the byte at the given index.
The parameter must satisfy 0 <= index < size.
operator []= index/int value/int -> none
Sets the byte at the given index to the given value.
The parameter index must satisfy 0 <= index < size.
operator == other/any -> bool
Whether this object is equal to the other.
By default, identical is used for equality.
Inheritance
Classes overwrite this operator to get an equality specific to their needs. Equality operators often compare the type and field contents. For example:

class Pin:
  number/int

  constructor .number:

  operator == other:
    if other is not Pin: return false
    return number == other.number
A class doesn't have to follow the above format, but it must keep the operator in sync with any hash-code method. That is, if a class has a hash-code member, then the equality and hash-code must agree. If two instances are equal (a == b), then their hash codes must also be equal (a.hash-code == b.hash-code).
pad --alignment/int --value/int=0 -> none
Pads the buffer to the given alignment.
If the buffer is already aligned, then this method does nothing.
Fills the new bytes with the given value.
pad-to --size/int --value/int=0 -> none
Pads the buffer to the given size.
If the buffer is already bigger than size, then this method does nothing.
Fills the new bytes with the given value.
processed -> int
The number of bytes that have been written into the buffer.
If the buffer was cleared, then this value is reset to 0.
put --at/int data/Data from/int=0 to/int=data.byte-size -> none
Writes the given data to this buffer at the given index at.
The parameters must satisfy 0 <= at <= (at + data-size) <= size, where data-size is the byte-size of data.
See grow-by, resize for ways to ensure that the buffer is big enough.
reserve amount/int -> none
Reserves amount bytes.
Ensures that the backing array has amount unused bytes available.
If this is not the case replaces the backing array with a bigger one. In this case this instance must be growable. (See is-growable.)
This method is purely for efficiency, so that this consumer doesn't need to regrow its internal backing store too often.
resize new-size/int -> none
Changes the size of the buffer to the given new-size.
If new-size is smaller than the current size, then the buffer is truncated.
If new-size is bigger than the current size, then the buffer is padded with zeros.
size -> int
The amount of bytes that have been written to this buffer.
This is not necessarily the size of the backing array.
stringify -> string
Stringifies this object.
Inheritance
Objects that need a human-friendly string representation should overwrite this method. The default string is based on the internal class-ID.
to-string -> string
Converts the consumed data to a string.
This operation is equivalent to bytes.to-string.
try-write data/Data from/int=0 to/int=data.byte-size -> int
Tries to write the given data to this writer.
If the writer can't write all the data at once, it writes as much as possible.
If the writer is closed while writing, throws, or returns the number of bytes written.
Otherwise always returns the number of bytes written.
Inheritance
Implementations are not required to check whether the writer is closed.
If the writer is closed while this operation is in progress, the writer may throw an exception or return a number smaller than to - from.
write data/Data from/int=0 to/int=data.byte-size --flush/bool=false -> int
Writes the given data to this writer.
Returns the amount of bytes written (to - from).
If the writer can't write all the data at once tries again until all of the data is written. This method is blocking.
write-byte b/int -> none
Writes a single byte b.
write-byte value/int --flush/bool=false -> none
Writes a single byte.
write-from reader/Reader --flush/bool=false -> none
Writes all data that is provided by the given reader.