#Buffer
A growable byte buffer for building binary data and serializing values. Supports writing integers, floats, strings, and raw bytes in both big-endian and little-endian byte orders.
#Create
Create an empty buffer, optionally with a capacity hint to reduce reallocations:
///|
test {
let buf = @buffer.Buffer()
@test.assert_eq(buf.is_empty(), true)
let buf2 = @buffer.Buffer(size_hint=1024)
@test.assert_eq(buf2.length(), 0)
}Create from existing data:
///|
test {
let buf = @buffer.from_bytes(b"hello")
@test.assert_eq(buf.length(), 5)
let buf2 = @buffer.from_array([b'a', b'b', b'c'])
@test.assert_eq(buf2.length(), 3)
let buf3 = @buffer.from_iter(b"hi".iter())
@test.assert_eq(buf3.length(), 2)
}#Writing Bytes
Write individual bytes, byte slices, or byte iterators:
///|
test {
let buf = @buffer.Buffer()
buf.write_byte(b'H')
buf.write_byte(b'i')
buf.write_bytes(b" world")
inspect(buf.to_bytes(), content="b\"Hi world\"")
// write a sub-range via BytesView
let buf2 = @buffer.Buffer()
buf2.write_bytesview(b"Hello"[0:2])
inspect(buf2.to_bytes(), content="b\"He\"")
// write from an iterator
let buf3 = @buffer.Buffer()
buf3.write_iter(b"ok".iter())
inspect(buf3.to_bytes(), content="b\"ok\"")
}#Writing Integers
All integer writes come in _be (big-endian) and _le (little-endian) variants.
///|
test {
// 32-bit signed/unsigned
let buf = @buffer.Buffer()
buf.write_int_be(0x01020304)
inspect(
buf.to_bytes(),
content=(
#|b"\x01\x02\x03\x04"
),
)
let buf2 = @buffer.Buffer()
buf2.write_int_le(0x01020304)
inspect(
buf2.to_bytes(),
content=(
#|b"\x04\x03\x02\x01"
),
)
// unsigned 32-bit
let buf3 = @buffer.Buffer()
buf3.write_uint_be(0xAABBU)
inspect(
buf3.to_bytes(),
content=(
#|b"\x00\x00\xaa\xbb"
),
)
}16-bit and 64-bit variants:
///|
test {
// 16-bit signed
let buf = @buffer.Buffer()
buf.write_int16_be((0x0102 : Int16))
buf.write_int16_le((0x0102 : Int16))
inspect(
buf.to_bytes(),
content=(
#|b"\x01\x02\x02\x01"
),
)
// 16-bit unsigned
let buf2 = @buffer.Buffer()
buf2.write_uint16_be(Int::to_uint16(0x00AB))
inspect(
buf2.to_bytes(),
content=(
#|b"\x00\xab"
),
)
// 64-bit signed
let buf3 = @buffer.Buffer()
buf3.write_int64_be(0x0102030405060708L)
inspect(
buf3.to_bytes(),
content=(
#|b"\x01\x02\x03\x04\x05\x06\x07\x08"
),
)
// 64-bit unsigned
let buf4 = @buffer.Buffer()
buf4.write_uint64_le(0xAABBUL)
inspect(
buf4.to_bytes(),
content=(
#|b"\xbb\xaa\x00\x00\x00\x00\x00\x00"
),
)
}#Writing Floats
///|
test {
let buf = @buffer.Buffer()
buf.write_float_be(1.0)
@test.assert_eq(buf.length(), 4)
let buf2 = @buffer.Buffer()
buf2.write_double_le(1.0)
@test.assert_eq(buf2.length(), 8)
}#Writing Characters & Strings
Write individual characters or entire strings as UTF-8 or UTF-16 (LE/BE):
///|
test {
// UTF-8
let buf = @buffer.Buffer()
buf.write_char_utf8('A')
buf.write_string_utf8("BC")
inspect(buf.to_bytes(), content="b\"ABC\"")
// UTF-16 little-endian
let buf2 = @buffer.Buffer()
buf2.write_char_utf16le('A')
inspect(buf2.to_bytes(), content="b\"A\\x00\"")
// UTF-16 big-endian
let buf3 = @buffer.Buffer()
buf3.write_string_utf16be("AB")
inspect(buf3.to_bytes(), content="b\"\\x00A\\x00B\"")
}#Writing Show Objects
Write any type that implements Show as UTF-8 bytes via write_utf8(). The current write_object() and Logger implementation for Buffer write UTF-16LE bytes and are deprecated; a future breaking release may restore them with UTF-8 semantics.
///|
test {
let buf = @buffer.Buffer()
buf.write_utf8(42)
inspect(buf.to_bytes(), content="b\"42\"")
}#LEB128 Encoding
Write integers in LEB128 variable-length encoding. Supported for Int, UInt, Int64, and UInt64.
///|
test {
let buf = @buffer.Buffer()
buf.write_leb128(624485)
inspect(buf.to_bytes(), content="b\"\\xe5\\x8e&\"")
let buf2 = @buffer.Buffer()
buf2.write_leb128(300UL)
inspect(buf2.to_bytes(), content="b\"\\xac\\x02\"")
}#Reading Contents
to_bytes() (aliased as contents()) returns the buffer contents as Bytes. view() returns an ArrayView[Byte] without copying.
///|
test {
let buf = @buffer.Buffer()
buf.write_bytes(b"hello")
let bytes = buf.to_bytes()
inspect(bytes, content="b\"hello\"")
let v = buf.view()
@test.assert_eq(v.length(), 5)
}#Reset
reset() clears the buffer contents, allowing it to be reused:
///|
test {
let buf = @buffer.Buffer()
buf.write_bytes(b"data")
@test.assert_eq(buf.length(), 4)
buf.reset()
@test.assert_eq(buf.is_empty(), true)
}#Size Hints
Pre-allocate capacity to minimize reallocations when the final size is known:
///|
test {
let buf = @buffer.Buffer(size_hint=1024)
for i in 0..<100 {
buf.write_int_le(i)
}
@test.assert_eq(buf.length(), 400) // 100 × 4 bytes
}Leb128
trait Leb128Buffer
type BufferExtensible buffer.
It provides accumulative concatenation of bytes in linear time.
The capacity of buffer will automatically expand as necessary.
Note: StringBuilder is recommended for string concatenation in favor of
Buffer, since it is optimized for all targets.
Usage
let buf = Buffer(size_hint=100)
buf.write_string_utf16le("Tes")
buf.write_char_utf16le('t')
inspect(
buf.contents(),
content=(
#|b"T\x00e\x00s\x00t\x00"
),
)Writes a UTF-16LE encoded character into the buffer. Automatically grows the
buffer if necessary.
Parameters:
- buffer : The buffer to write to.
- char : The character to be written.
Buffer::Buffer
Creates a new extensible buffer. Enables the constructor-call syntax
Buffer() (also Buffer(size_hint=N)) when Buffer is in scope, e.g.
via the prelude.
Parameters:
- size_hint : Initial capacity of the buffer in bytes. Defaults to 0.
Returns a new Buffer.
Example:
test {
let buf = @buffer.Buffer()
buf.write_string_utf16le("test")
inspect(buf.length(), content="8")
}Buffer::is_empty
Returns whether the buffer is empty.
Parameters:
- buffer : The buffer to check.
Returns true if the buffer is empty (i.e., contains no bytes), false
otherwise.
Example:
test {
let buf = @buffer.Buffer()
inspect(buf.is_empty(), content="true")
buf.write_string_utf16le("test")
inspect(buf.is_empty(), content="false")
}Buffer::length
Returns the number of bytes currently stored in the buffer.
Parameters:
- buffer: The buffer to get the length from.
Returns the length of the buffer in bytes.
Example:
test {
let buf = @buffer.Buffer()
buf.write_string_utf16le("Test")
inspect(buf.length(), content="8") // each char takes 2 bytes in UTF-16
}Buffer::reset
Resets the buffer to an empty state by setting the internal offset to 0.
This makes the buffer appear empty without actually clearing the underlying data.
Parameters:
- self : The buffer to be reset.
Example:
test {
let buf = @buffer.Buffer()
buf.write_string_utf16le("Hello")
inspect(buf.length(), content="10")
buf.reset()
inspect(buf.length(), content="0")
inspect(buf.is_empty(), content="true")
}Buffer::to_bytes
Returns a copy of the buffer's contents as a Bytes object. The returned
bytes will have the same length as the buffer.
Parameters:
- buffer : The buffer whose contents will be converted to bytes.
Returns a Bytes object containing a copy of the buffer's contents.
Example:
test {
let buf = @buffer.Buffer()
buf.write_string_utf16le("Test")
let bytes = buf.to_bytes()
inspect(bytes.length(), content="8") //utf16
}Buffer::view
Return a read-only byte view over the current buffer contents.
The view length equals self.length(). It shares underlying storage with
the buffer, so later writes to the buffer may affect subsequent reads.
Example:
test {
let buf = @buffer.Buffer()
buf.write_byte(b'A')
let v = buf.view()
inspect(v.length(), content="1")
inspect(v[0], content="b'\\x41'")
}Buffer::write
#deprecated("`Buffer::write` is deprecated, use `Logger::write` instead.")
#deprecated("Buffer's current Logger impl writes UTF-16LE bytes; use StringBuilder or explicit Buffer encoders. A future breaking release may restore it with UTF-8 semantics.")
fn Buffer::write(self : Buffer, show : &Show) -> UnitBuffer::write_byte
Writes a single byte to the end of the buffer. The buffer will automatically
grow if necessary to accommodate the new byte.
Parameters:
- buffer : The buffer to write to.
- byte : The byte value to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_byte(b'\x41')
inspect(
buf.contents(),
content=(
#|b"A"
),
)
}Buffer::write_bytes
Writes a sequence of bytes into the buffer.
Parameters:
- buffer : An extensible buffer to write into.
- bytes : The sequence of bytes to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_bytes(b"Test")
inspect(
buf.contents(),
content=(
#|b"Test"
),
)
}Buffer::write_bytesview
Writes a sequence of bytes from a BytesView into the buffer.
Parameters:
- buffer : The buffer to write to.
- value : The View containing the bytes to write.
Example:
test {
let buf = @buffer.Buffer()
let view = b"Test"[1:3]
buf.write_bytesview(view)
inspect(
buf.contents(),
content=(
#|b"es"
),
)
}Buffer::write_char
#deprecated("`Buffer::write_char` is deprecated, use `Logger::write_char` instead.")
#deprecated("Buffer's current Logger impl writes UTF-16LE bytes; use StringBuilder or explicit Buffer encoders. A future breaking release may restore it with UTF-8 semantics.")
fn Buffer::write_char(self : Buffer, value : Char) -> UnitBuffer::write_char_utf16be
Write a char into buffer as UTF16BE.
Buffer::write_char_utf16le
Write a char into buffer as UTF16LE.
Buffer::write_char_utf8
Write a char into buffer as UTF8.
Buffer::write_double_be
Writes an IEEE 754 double-precision floating-point number into the buffer in
big-endian format (most significant byte first).
Parameters:
- buffer : The buffer to write to.
- value : The double-precision floating-point number to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_double_be(1.0)
inspect(
buf.contents(),
content=(
#|b"?\xf0\x00\x00\x00\x00\x00\x00"
),
)
}Buffer::write_double_le
Writes a double-precision floating-point number into the buffer in
little-endian format.
Parameters:
- buffer : The buffer to write to.
- value : The double-precision floating-point number to write.
Example:
test {
let buf = @buffer.Buffer()
buf.write_double_le(3.14)
inspect(
buf.contents(),
content=(
#|b"\x1f\x85\xebQ\xb8\x1e\x09@"
),
)
}Buffer::write_float_be
Writes a 32-bit floating-point number to the buffer in big-endian byte order.
The float value is first reinterpreted as a 32-bit unsigned integer before
writing.
Parameters:
- buffer : The buffer to write to.
- value : The floating-point number to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_float_be(3.14)
// In big-endian format, 3.14 is represented as [0x40, 0x48, 0xF5, 0xC3]
inspect(
buf.contents(),
content=(
#|b"@H\xf5\xc3"
),
)
}Buffer::write_float_le
Writes a Float value into the buffer in little-endian format. The float value
is converted to its binary representation and written as four bytes.
Parameters:
- buffer : The buffer to write to.
- value : The Float value to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_float_le(3.14)
// The bytes are written in little-endian format
inspect(
buf.contents(),
content=(
#|b"\xc3\xf5H@"
),
)
}Buffer::write_int16_be
Writes a 16-bit integer to the buffer in big-endian format. Big-endian means
the most significant byte is written first.
Parameters:
- buffer : The buffer to write to.
- value : The 16-bit integer to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_int16_be(0x1234)
inspect(
buf.contents(),
content=(
#|b"\x124"
),
)
}Buffer::write_int16_le
Writes a 16-bit integer into the buffer in little-endian format. The integer
is written as 2 bytes where the least significant byte is written first.
Parameters:
- buffer : The buffer to write into.
- value : The 16-bit integer value to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_int16_le(-1)
inspect(
buf.contents(),
content=(
#|b"\xff\xff"
),
)
}Buffer::write_int64_be
Writes a 64-bit integer into the buffer in big-endian format, where the most
significant byte is written first.
Parameters:
- buffer : The buffer to write into.
- value : The 64-bit integer to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_int64_be(0x0102030405060708L)
inspect(
buf.contents(),
content=(
#|b"\x01\x02\x03\x04\x05\x06\x07\x08"
),
)
}Buffer::write_int64_le
Writes a 64-bit signed integer to the buffer in little-endian byte order.
Parameters:
- buffer : The buffer to write to.
- value : The 64-bit signed integer to write.
Example:
test {
let buf = @buffer.Buffer()
buf.write_int64_le(-1L)
inspect(
buf.contents(),
content=(
#|b"\xff\xff\xff\xff\xff\xff\xff\xff"
),
)
}Buffer::write_int_be
Writes a 32-bit integer to the buffer in big-endian format. Big-endian means
the most significant byte is written first.
Parameters:
- buffer : The buffer to write to.
- value : The 32-bit integer to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_int_be(0x12345678)
inspect(
buf.contents(),
content=(
#|b"\x124Vx"
),
)
}Buffer::write_int_le
Writes a 32-bit integer into the buffer in little-endian format. The integer
is first reinterpreted as an unsigned integer, then written as 4 bytes where
the least significant byte is written first.
Parameters:
- buffer : The buffer to write into.
- value : The integer value to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_int_le(-1)
inspect(buf.contents(), content="b\"\\xff\\xff\\xff\\xff\"")
}Buffer::write_iter
Writes bytes from an iterator to the buffer.
Parameters:
- self : The buffer to write to.
- iter : An iterator yielding bytes to write.
Example:
test {
let buf = @buffer.Buffer()
let bytes = b"Hello"
buf.write_iter(bytes.iter())
inspect(
buf.contents(),
content=(
#|b"Hello"
),
)
}Buffer::write_leb128
Encode a value as LEB128 and append it to the buffer.
This works for types implementing Leb128: Int and Int64 are encoded as
signed LEB128 (SLEB128), while UInt and UInt64 are encoded as unsigned
LEB128 (ULEB128).
Parameters:
- buffer: destination buffer.
- value: value to encode.
Example:
test {
let buf = @buffer.Buffer()
buf.write_leb128(127)
inspect(buf.contents().length() > 0, content="true")
}Buffer::write_object
Writes a string representation of any value that implements the Show trait
into the buffer.
Parameters:
- buffer : The buffer to write to.
- value : Any value that implements the Show trait. The value will be converted to a string using its to_string method before being written to the buffer.
Buffer::write_string
#deprecated("`Buffer::write_string` is deprecated, use `Logger::write_string` instead.")
#deprecated("Buffer's current Logger impl writes UTF-16LE bytes; use StringBuilder or explicit Buffer encoders. A future breaking release may restore it with UTF-8 semantics.")
fn Buffer::write_string(self : Buffer, value : String) -> UnitBuffer::write_string_interpolation
#deprecated("`Buffer::write_string_interpolation` is deprecated, use `Logger::write_string_interpolation` instead.")
#deprecated("Buffer's current Logger impl writes UTF-16LE bytes; use StringBuilder or explicit Buffer encoders. A future breaking release may restore it with UTF-8 semantics.")
fn Buffer::write_string_interpolation(self : Buffer, show : &Show) -> UnitBuffer::write_string_utf16be
Write a string view into the buffer as UTF-16 big-endian code units.
Parameters:
- buf: destination buffer.
- string: string view to encode in UTF-16BE.
Example:
test {
let buf = @buffer.Buffer()
buf.write_string_utf16be("A")
inspect(buf.contents().length(), content="2")
}Buffer::write_string_utf16le
Write a string view into the buffer as UTF-16 little-endian code units.
Parameters:
- buf: destination buffer.
- string: string view to encode in UTF-16LE.
Example:
test {
let buf = @buffer.Buffer()
buf.write_string_utf16le("A")
inspect(buf.contents().length(), content="2")
}Buffer::write_string_utf8
Write a UTF-8 encoded string view into the buffer.
Parameters:
- buf: destination buffer.
- string: string view to encode as UTF-8 bytes.
Example:
test {
let buf = @buffer.Buffer()
buf.write_string_utf8("Hi")
inspect(buf.contents().length(), content="2")
}Buffer::write_substring
#deprecated("`Buffer::write_substring` is deprecated, use `Logger::write_substring` instead.")
#deprecated("Buffer's current Logger impl writes UTF-16LE bytes; use StringBuilder or explicit Buffer encoders. A future breaking release may restore it with UTF-8 semantics.")
fn Buffer::write_substring(self : Buffer, value : String, start : Int, len : Int) -> UnitBuffer::write_uint16_be
Writes a 16-bit unsigned integer into the buffer in big-endian format (most
significant byte first).
Parameters:
- buffer : The buffer to write to.
- value : The unsigned 16-bit integer value to write.
Example:
test {
let buf = @buffer.Buffer()
buf.write_uint16_be(0x1234)
inspect(
buf.contents(),
content=(
#|b"\x124"
),
)
}Buffer::write_uint16_le
Writes a 16-bit unsigned integer into the buffer in little-endian format. The
integer is split into 2 bytes and written in order from least significant to
most significant byte.
Parameters:
- buffer : The buffer to write to.
- value : A 16-bit unsigned integer to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_uint16_le(0x1234)
inspect(
buf.contents(),
content=(
#|b"4\x12"
),
)
}Buffer::write_uint64_be
Writes an unsigned 64-bit integer into the buffer in big-endian format (most
significant byte first).
Parameters:
- buffer : The buffer to write to.
- value : The unsigned 64-bit integer to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_uint64_be(0xAABBCCDD11223344)
// Bytes are written in big-endian order
inspect(
buf.contents(),
content=(
#|b"\xaa\xbb\xcc\xdd\x11\x223D"
),
)
}Buffer::write_uint64_le
Writes an unsigned 64-bit integer to the buffer in little-endian byte order.
Each byte is written sequentially from least significant to most significant.
Parameters:
- buffer : The buffer to write to.
- value : The UInt64 value to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_uint64_le(0x0123456789ABCDEF)
inspect(
buf.contents(),
content=(
#|b"\xef\xcd\xab\x89gE#\x01"
),
)
}Buffer::write_uint_be
Writes a 32-bit unsigned integer into the buffer in big-endian format (most
significant byte first).
Parameters:
- buffer : The buffer to write to.
- value : The unsigned integer value to write.
Example:
test {
let buf = @buffer.Buffer()
buf.write_uint_be(0x12345678)
inspect(
buf.contents(),
content=(
#|b"\x124Vx"
),
)
}Buffer::write_uint_le
Writes a 32-bit unsigned integer into the buffer in little-endian format. The
integer is split into 4 bytes and written in order from least significant to
most significant byte.
Parameters:
- buffer : The buffer to write to.
- value : A 32-bit unsigned integer to be written.
Example:
test {
let buf = @buffer.Buffer()
buf.write_uint_le(0x12345678)
inspect(
buf.contents(),
content=(
#|b"xV4\x12"
),
)
}Buffer::write_utf8
Writes the Show representation of any value into the buffer as UTF-8
encoded bytes.
Parameters:
- self : The buffer to write to.
- value : Any value that implements the Show trait. The value is converted to a string via Show::to_string and then encoded as UTF-8.
Example:
test {
let buf = @buffer.Buffer()
buf.write_utf8(42)
inspect(
buf.contents(),
content=(
#|b"42"
),
)
}Buffer::write_view
#deprecated("`Buffer::write_view` is deprecated, use `Logger::write_view` instead.")
#deprecated("Buffer's current Logger impl writes UTF-16LE bytes; use StringBuilder or explicit Buffer encoders. A future breaking release may restore it with UTF-8 semantics.")
fn Buffer::write_view(self : Buffer, value : StringView) -> Unitnew
#deprecated("use `Buffer()` instead (with `Buffer` in scope via the prelude)")
fn new(size_hint? : Int) -> BufferCreates a new extensible buffer with specified initial capacity. If the
initial capacity is less than 1, the buffer will be initialized with capacity
1.
Parameters:
- size_hint : Initial capacity of the buffer in bytes. Defaults to 0.
Returns a new buffer of type Buffer.
Example:
test {
let buf = @buffer.Buffer(size_hint=10)
inspect(buf.length(), content="0")
buf.write_string_utf16le("test")
inspect(buf.length(), content="8")
}Install
Installed by default
corestandard library
Apache-2.0
Updated 11 days ago