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 integerlist_size - the number of items in the following list of items as a big-endian 32-bit integerA 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
new iso create() : Writer iso^
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
Reserve space for size bytes in _current.
fun ref reserve_current( size': USize val) : None val
fun box size() : USize val
Write a byte to the buffer.
fun ref u8( data: U8 val) : None val
Write a U16 to the buffer in little-endian byte order.
fun ref u16_le( data: U16 val) : None val
Write a U16 to the buffer in big-endian byte order.
fun ref u16_be( data: U16 val) : None val
Write an I16 to the buffer in little-endian byte order.
fun ref i16_le( data: I16 val) : None val
Write an I16 to the buffer in big-endian byte order.
fun ref i16_be( data: I16 val) : None val
Write a U32 to the buffer in little-endian byte order.
fun ref u32_le( data: U32 val) : None val
Write a U32 to the buffer in big-endian byte order.
fun ref u32_be( data: U32 val) : None val
Write an I32 to the buffer in little-endian byte order.
fun ref i32_le( data: I32 val) : None val
Write an I32 to the buffer in big-endian byte order.
fun ref i32_be( data: I32 val) : None val
Write an F32 to the buffer in little-endian byte order.
fun ref f32_le( data: F32 val) : None val
Write an F32 to the buffer in big-endian byte order.
fun ref f32_be( data: F32 val) : None val
Write a U64 to the buffer in little-endian byte order.
fun ref u64_le( data: U64 val) : None val
Write a U64 to the buffer in big-endian byte order.
fun ref u64_be( data: U64 val) : None val
Write an I64 to the buffer in little-endian byte order.
fun ref i64_le( data: I64 val) : None val
Write an I64 to the buffer in big-endian byte order.
fun ref i64_be( data: I64 val) : None val
Write an F64 to the buffer in little-endian byte order.
fun ref f64_le( data: F64 val) : None val
Write an F64 to the buffer in big-endian byte order.
fun ref f64_be( data: F64 val) : None val
Write a U128 to the buffer in little-endian byte order.
fun ref u128_le( data: U128 val) : None val
Write a U128 to the buffer in big-endian byte order.
fun ref u128_be( data: U128 val) : None val
Write an I128 to the buffer in little-endian byte order.
fun ref i128_le( data: I128 val) : None val
Write an I128 to the buffer in big-endian byte order.
fun ref i128_be( data: I128 val) : None val
Write a ByteSeq to the buffer.
fun ref write( data: (String val | Array[U8 val] val)) : None val
Write ByteSeqs to the buffer.
fun ref writev( data: ByteSeqIter val) : None val
Return an array of buffered ByteSeqs and reset the Writer's buffer.
fun ref done() : Array[(String val | Array[U8 val] val)] iso^
fun ref _append_current() : None val
© 2016-2018, The Pony Developers
© 2014-2015, Causality Ltd.
Licensed under the BSD 2-Clause License.
https://stdlib.ponylang.io/buffered-Writer