Store network data and provide a parsing interface.
Reader provides a way to extract typed data from a sequence of bytes. The Reader manages the underlying data structures to provide a read cursor over a contiguous sequence of bytes. It is useful for decoding data that is received over a network or stored in a file. Chunk of bytes are added to the Reader using the append method, and typed data is extracted using the getter methods.
For example, suppose we have a UDP-based network data protocol where messages consist of the following:
list_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 Reader to decode a message of this type and print them:
use "buffered"
use "collections"
class Notify is InputNotify
let _env: Env
new create(env: Env) =>
_env = env
fun ref apply(data: Array[U8] iso) =>
let rb = Reader
rb.append(consume data)
try
while true do
let len = rb.i32_be()?
let items = rb.i32_be()?.usize()
for range in Range(0, items) do
let f = rb.f32_be()?
let str_len = rb.i32_be()?.usize()
let str = String.from_array(rb.block(str_len)?)
_env.out.print("[(" + f.string() + "), (" + str + ")]")
end
end
end
actor Main
new create(env: Env) =>
env.input(recover Notify(env) end, 1024)
class ref Reader
new iso create() : Reader iso^
Return the number of available bytes.
fun box size() : USize val
Discard all pending data.
fun ref clear() : None val
Add a chunk of data.
fun ref append( data: (String val | Array[U8 val] val)) : None val
Skip n bytes.
fun ref skip( n: USize val) : None val ?
Return a block as a contiguous chunk of memory. Will throw an error if you request a block larger than what is currently stored in the Reader.
fun ref block( len: USize val) : Array[U8 val] iso^ ?
Find the first occurrence of the separator and return the block of bytes before its position. The separator is not included in the returned array, but it is removed from the buffer. To read a line of text, prefer line() that handles \n and \r\n.
fun ref read_until( separator: U8 val) : Array[U8 val] iso^ ?
Return a \n or \r\n terminated line as a string. By default the newline is not included in the returned string, but it is removed from the buffer. Set keep_line_breaks to true to keep the line breaks in the returned line.
fun ref line( keep_line_breaks: Bool val = false) : String iso^ ?
Get a U8. Raise an error if there isn't enough data.
fun ref u8() : U8 val ?
Get an I8.
fun ref i8() : I8 val ?
Get a big-endian U16.
fun ref u16_be() : U16 val ?
Get a little-endian U16.
fun ref u16_le() : U16 val ?
Get a big-endian I16.
fun ref i16_be() : I16 val ?
Get a little-endian I16.
fun ref i16_le() : I16 val ?
Get a big-endian U32.
fun ref u32_be() : U32 val ?
Get a little-endian U32.
fun ref u32_le() : U32 val ?
Get a big-endian I32.
fun ref i32_be() : I32 val ?
Get a little-endian I32.
fun ref i32_le() : I32 val ?
Get a big-endian U64.
fun ref u64_be() : U64 val ?
Get a little-endian U64.
fun ref u64_le() : U64 val ?
Get a big-endian I64.
fun ref i64_be() : I64 val ?
Get a little-endian I64.
fun ref i64_le() : I64 val ?
Get a big-endian U128.
fun ref u128_be() : U128 val ?
Get a little-endian U128.
fun ref u128_le() : U128 val ?
Get a big-endian I129.
fun ref i128_be() : I128 val ?
Get a little-endian I128.
fun ref i128_le() : I128 val ?
Get a big-endian F32.
fun ref f32_be() : F32 val ?
Get a little-endian F32.
fun ref f32_le() : F32 val ?
Get a big-endian F64.
fun ref f64_be() : F64 val ?
Get a little-endian F64.
fun ref f64_le() : F64 val ?
Peek at a U8 at the given offset. Raise an error if there isn't enough data.
fun box peek_u8( offset: USize val = 0) : U8 val ?
Peek at an I8.
fun box peek_i8( offset: USize val = 0) : I8 val ?
Peek at a big-endian U16.
fun box peek_u16_be( offset: USize val = 0) : U16 val ?
Peek at a little-endian U16.
fun box peek_u16_le( offset: USize val = 0) : U16 val ?
Peek at a big-endian I16.
fun box peek_i16_be( offset: USize val = 0) : I16 val ?
Peek at a little-endian I16.
fun box peek_i16_le( offset: USize val = 0) : I16 val ?
Peek at a big-endian U32.
fun box peek_u32_be( offset: USize val = 0) : U32 val ?
Peek at a little-endian U32.
fun box peek_u32_le( offset: USize val = 0) : U32 val ?
Peek at a big-endian I32.
fun box peek_i32_be( offset: USize val = 0) : I32 val ?
Peek at a little-endian I32.
fun box peek_i32_le( offset: USize val = 0) : I32 val ?
Peek at a big-endian U64.
fun box peek_u64_be( offset: USize val = 0) : U64 val ?
Peek at a little-endian U64.
fun box peek_u64_le( offset: USize val = 0) : U64 val ?
Peek at a big-endian I64.
fun box peek_i64_be( offset: USize val = 0) : I64 val ?
Peek at a little-endian I64.
fun box peek_i64_le( offset: USize val = 0) : I64 val ?
Peek at a big-endian U128.
fun box peek_u128_be( offset: USize val = 0) : U128 val ?
Peek at a little-endian U128.
fun box peek_u128_le( offset: USize val = 0) : U128 val ?
Peek at a big-endian I129.
fun box peek_i128_be( offset: USize val = 0) : I128 val ?
Peek at a little-endian I128.
fun box peek_i128_le( offset: USize val = 0) : I128 val ?
Peek at a big-endian F32.
fun box peek_f32_be( offset: USize val = 0) : F32 val ?
Peek at a little-endian F32.
fun box peek_f32_le( offset: USize val = 0) : F32 val ?
Peek at a big-endian F64.
fun box peek_f64_be( offset: USize val = 0) : F64 val ?
Peek at a little-endian F64.
fun box peek_f64_le( offset: USize val = 0) : F64 val ?
Get a single byte.
fun ref _byte() : U8 val ?
Get the byte at the given offset without moving the cursor forward. Raise an error if the given offset is not yet available.
fun box _peek_byte( offset: USize val = 0) : U8 val ?
Get the distance to the first occurrence of the given byte
fun ref _distance_of( byte: U8 val) : USize val ?
Get the length of a pending line. Raise an error if there is no pending line.
fun ref _search_length() : USize val ?
© 2016-2018, The Pony Developers
© 2014-2015, Causality Ltd.
Licensed under the BSD 2-Clause License.
https://stdlib.ponylang.io/buffered-Reader