Skip to content

Pony Standard Library

class Writer

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¶

Writer iso^

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¶

size': USize val

Returns¶

None val

reserve_current¶

Reserve space for size bytes in _current.

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

Parameters¶

size': USize val

Returns¶

None val

size¶

fun box size()
: USize val

Returns¶

USize val

u8¶

Write a byte to the buffer.

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

Parameters¶

data: U8 val

Returns¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

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¶

None val

u128_le¶

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

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

Parameters¶

data: U128 val

Returns¶

None val

u128_be¶

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

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

Parameters¶

data: U128 val

Returns¶

None val

i128_le¶

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

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

Parameters¶

data: I128 val

Returns¶

None val

i128_be¶

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

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

Parameters¶

data: I128 val

Returns¶

None val

write¶

Write a ByteSeq to the buffer.

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

Parameters¶

data: (String val | Array[U8 val] val)

Returns¶

None val

writev¶

Write ByteSeqs to the buffer.

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

Parameters¶

data: ByteSeqIter val

Returns¶

None val

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¶

Array[(String val | Array[U8 val] val)] iso^