Writer

A buffer for building messages.

Writer provides an way to create byte sequences using common data encodings. The Writer manages the underlying arrays and sizes. It is useful for encoding data to send over a network or store in a file. Once a message has been built you can call done() to get the message's ByteSeqs, and you can then reuse the Writer for creating a new message.

For example, suppose we have a TCP-based network data protocol where messages consist of the following:

  • message_length - the number of bytes in the message as a big-endian 32-bit integer
  • list_size - the number of items in the following list of items as a big-endian 32-bit integer
  • zero or more items of the following data:
  • a big-endian 64-bit floating point number
  • a string that starts with a big-endian 32-bit integer that specifies the length of the string, followed by a number of bytes that represent the string

A message would be something like this:

[message_length][list_size][float1][string1][float2][string2]...

The following program uses a write buffer to encode an array of tuples as a message of this type:

use "buffered"

actor Main
  new create(env: Env) =>
    let wb = Writer
    let messages = [[(F32(3597.82), "Anderson"); (F32(-7979.3), "Graham")]
                    [(F32(3.14159), "Hopper"); (F32(-83.83), "Jones")]]
    for items in messages.values() do
      wb.i32_be((items.size() / 2).i32())
      for (f, s) in items.values() do
        wb.f32_be(f)
        wb.i32_be(s.size().i32())
        wb.write(s.array())
      end
      let wb_msg = Writer
      wb_msg.i32_be(wb.size().i32())
      wb_msg.writev(wb.done())
      env.out.writev(wb_msg.done())
    end
class ref Writer

Constructors

create

new iso create()
: Writer iso^

Returns


Public Functions

reserve_chunks

Reserve space for size' chunks.

This needs to be recalled after every call to done as done resets the chunks.

fun ref reserve_chunks(
  size': USize val)
: None val

Parameters

Returns


reserve_current

Reserve space for size bytes in _current.

fun ref reserve_current(
  size': USize val)
: None val

Parameters

Returns


size

fun box size()
: USize val

Returns


u8

Write a byte to the buffer.

fun ref u8(
  data: U8 val)
: None val

Parameters

  • data: U8 val

Returns


u16_le

Write a U16 to the buffer in little-endian byte order.

fun ref u16_le(
  data: U16 val)
: None val

Parameters

  • data: U16 val

Returns


u16_be

Write a U16 to the buffer in big-endian byte order.

fun ref u16_be(
  data: U16 val)
: None val

Parameters

  • data: U16 val

Returns


i16_le

Write an I16 to the buffer in little-endian byte order.

fun ref i16_le(
  data: I16 val)
: None val

Parameters

  • data: I16 val

Returns


i16_be

Write an I16 to the buffer in big-endian byte order.

fun ref i16_be(
  data: I16 val)
: None val

Parameters

  • data: I16 val

Returns


u32_le

Write a U32 to the buffer in little-endian byte order.

fun ref u32_le(
  data: U32 val)
: None val

Parameters

  • data: U32 val

Returns


u32_be

Write a U32 to the buffer in big-endian byte order.

fun ref u32_be(
  data: U32 val)
: None val

Parameters

  • data: U32 val

Returns


i32_le

Write an I32 to the buffer in little-endian byte order.

fun ref i32_le(
  data: I32 val)
: None val

Parameters

  • data: I32 val

Returns


i32_be

Write an I32 to the buffer in big-endian byte order.

fun ref i32_be(
  data: I32 val)
: None val

Parameters

  • data: I32 val

Returns


f32_le

Write an F32 to the buffer in little-endian byte order.

fun ref f32_le(
  data: F32 val)
: None val

Parameters

  • data: F32 val

Returns


f32_be

Write an F32 to the buffer in big-endian byte order.

fun ref f32_be(
  data: F32 val)
: None val

Parameters

  • data: F32 val

Returns


u64_le

Write a U64 to the buffer in little-endian byte order.

fun ref u64_le(
  data: U64 val)
: None val

Parameters

  • data: U64 val

Returns


u64_be

Write a U64 to the buffer in big-endian byte order.

fun ref u64_be(
  data: U64 val)
: None val

Parameters

  • data: U64 val

Returns


i64_le

Write an I64 to the buffer in little-endian byte order.

fun ref i64_le(
  data: I64 val)
: None val

Parameters

  • data: I64 val

Returns


i64_be

Write an I64 to the buffer in big-endian byte order.

fun ref i64_be(
  data: I64 val)
: None val

Parameters

  • data: I64 val

Returns


f64_le

Write an F64 to the buffer in little-endian byte order.

fun ref f64_le(
  data: F64 val)
: None val

Parameters

  • data: F64 val

Returns


f64_be

Write an F64 to the buffer in big-endian byte order.

fun ref f64_be(
  data: F64 val)
: None val

Parameters

  • data: F64 val

Returns


u128_le

Write a U128 to the buffer in little-endian byte order.

fun ref u128_le(
  data: U128 val)
: None val

Parameters

Returns


u128_be

Write a U128 to the buffer in big-endian byte order.

fun ref u128_be(
  data: U128 val)
: None val

Parameters

Returns


i128_le

Write an I128 to the buffer in little-endian byte order.

fun ref i128_le(
  data: I128 val)
: None val

Parameters

Returns


i128_be

Write an I128 to the buffer in big-endian byte order.

fun ref i128_be(
  data: I128 val)
: None val

Parameters

Returns


write

Write a ByteSeq to the buffer.

fun ref write(
  data: (String val | Array[U8 val] val))
: None val

Parameters

Returns


writev

Write ByteSeqs to the buffer.

fun ref writev(
  data: ByteSeqIter val)
: None val

Parameters

Returns


done

Return an array of buffered ByteSeqs and reset the Writer's buffer.

fun ref done()
: Array[(String val | Array[U8 val] val)] iso^

Returns


Private Functions

_append_current

fun ref _append_current()
: None val

Returns


_check

fun ref _check(
  size': USize val)
: None val

Parameters

Returns


_byte

fun ref _byte(
  data: U8 val)
: None val

Parameters

  • data: U8 val

Returns