binary -- handling of binary data

The module contains functions to read and write binary data, encode it in textual form and decode it back.

Index

namespace bin

class Encoder

• Encoder()
• Encoder(sink: io::Stream)
• .stream(invar self: Encoder) => io::Stream
• .bytesWritten(invar self: Encoder) => int
• i8(self: Encoder, value: int) => Encoder
• u8(self: Encoder, value: int) => Encoder
• i16(self: Encoder, value: int) => Encoder
• u16(self: Encoder, value: int) => Encoder
• i32(self: Encoder, value: int) => Encoder
• u32(self: Encoder, value: int) => Encoder
• i64(self: Encoder, value: int) => Encoder
• u64(self: Encoder, value: int) => Encoder
• f32(self: Encoder, value: float) => Encoder
• f64(self: Encoder, value: float) => Encoder
• bytes(self: Encoder, bytes: string) => Encoder

class Decoder

• Decoder(sink: io::Stream)
• .stream(invar self: Encoder) => io::Stream
• .bytesWritten(invar self: Encoder) => int
• i8(self: Encoder) => int
• u8(self: Encoder) => int
• i16(self: Encoder) => int
• u16(self: Encoder) => int
• i32(self: Encoder) => int
• u32(self: Encoder) => int
• i64(self: Encoder) => int
• u64(self: Encoder) => int
• f32(self: Encoder) => float
• f64(self: Encoder) => float
• bytes(self: Encoder, count: int) => string

interface Encodable

• encode(invar self: Encodable, encoder: Encoder)

interface Decodable

• decode(decoder: Decoder) => Decodable

Functions:

• read(source: io::Stream, dest: array<@T<int|float|complex>>, count = 0) => int
• unpack(source: io::Stream, dest: array<int>, size: enum<byte,word,dword>, count = 0) => int
• pack(invar source: array<int>, dest: io::Stream, size: enum<byte,word,dword>, count = 0) => int
• write(invar source: array<@T<int|float|complex>>, dest: io::Stream, count = 0) => int
• get(invar source: array<int>|string, what: enum<byte,ubyte,word,uword,dword,udword,qword,uqword>, offset: int) => int
• get(invar source: array<int>|string, what: enum<float>, offset: int) => float
• get(invar source: array<int>|string, what: enum<bits>, offset: int, count: int) => int
• set(dest: array<int>, what: enum<byte,ubyte,word,uword,dword,udword,qword,uqword>, offset: int, value: int)
• set(dest: array<int>, what: enum<float>, offset: int, value: float)
• set(dest: array<int>, what: enum<bits>, offset: int, count: int, value: int)
• encode(str: string, codec: enum<base64,z85,hex>) => string
• decode(str: string, codec: enum<base64,z85,hex>) => string

Classes

bin::Encoder

Stateful binary encoder which uses an io::Stream as sink

Methods

Encoder()
Encoder(sink: io::Stream)

Creates an encoder writing to sink (if omitted, new string stream is created)

Errors: Param when sink is not writable

.stream(invar self: Encoder) => io::Stream

Sink stream

.bytesWritten(invar self: Encoder) => int

Number of bytes successfully written to the sink

i8(self: Encoder, value: int) => Encoder
u8(self: Encoder, value: int) => Encoder
i16(self: Encoder, value: int) => Encoder
u16(self: Encoder, value: int) => Encoder
i32(self: Encoder, value: int) => Encoder
u32(self: Encoder, value: int) => Encoder
i64(self: Encoder, value: int) => Encoder
u64(self: Encoder, value: int) => Encoder
f32(self: Encoder, value: float) => Encoder
f64(self: Encoder, value: float) => Encoder

Writes value and returns self.

Note: Multibyte integer values are written with big-endian byte order Warning: Floating point value representation may vary on different platforms

Errors: Value if the stream was closed

bytes(self: Encoder, bytes: string) => Encoder

Writes bytes to the sink and returns self

Errors: 'Value' if the stream was closed

---

bin::Decoder

Stateful binary decoder which uses an io::Stream as source

Methods

Decoder(source: io::Stream)

Creates a decoder readin from source

Errors: Param when source is not readable

.stream(invar self: Decoder) => io::Stream

Source stream

.bytesRead(invar self: Decoder) => int

Number of bytes successfully written to the sink

i8(self: Decoder) => int
u8(self: Decoder) => int
i16(self: Decoder) => int
u16(self: Decoder) => int
i32(self: Decoder) => int
u32(self: Decoder) => int
i64(self: Decoder) => int
u64(self: Decoder) => int
f32(self: Decoder) => float
f64(self: Decoder) => float

Reads a value from the source.

Note: Multibyte integer values are assumed to be in big-endian byte order Warning: Floating point value representation may vary on different platforms

Errors: Value if the stream was closed

bytes(self: Encoder, bytes: string) => Encoder

Reads at most count bytes from the source

Errors: Value if the stream was closed

Interfaces

bin::Encodable

A type which can be encoded to binary form. Use it to define conversions to specific serialization formats

Methods

encode(invar self: Encodable, encoder: Encoder)

Serializes self using the provided encoder

---

bin::Decodable

A type which can be decoded from binary form. Use it to define conversions from specific serialization formats

Methods

decode(decoder: Decoder) => Decodable

Deserializes self using the provided decoder

Functions

read(source: io::Stream, dest: array<@T<int|float|complex>>, count = 0) => int

Reads count elements from source to dest. If count is zero, or greater than dest size, dest size is assumed. Returns the number of elements actually read

Errors: Param when source is not readable

unpack(source: io::Stream, dest: array<int>, size: enum<byte,word,dword>, count = 0) => int

Reads count chunks of size size from source into dest so that each chunk corresponds to a single dest element (with possible widening). If count is zero, or greater than dest element size, dest element size is assumed. Returns the number of chunks actually read

Errors: Param when source is not readable

pack(invar source: array<int>, dest: io::Stream, size: enum<byte,word,dword>, count = 0) => int

Writes count chunks of size size to dest so that each source element corresponds to a single chunk (with possible narrowing). Returns the number of chunks actually written

Errors: Param when dest is not writable

write(invar source: array<@T<int|float|complex>>, dest: io::Stream, count = 0) => int

Writes count elements from source to dest. If count is zero, or greater than dest size, all dest data is written. Returns the number of elements actually written

Errors: Param when dest is not writable

get(invar source: array<int>|string, what: enum<byte,ubyte,word,uword,dword,udword,qword,uqword>, offset: int) => int
get(invar source: array<int>|string, what: enum<float>, offset: int) => float

Reads value described by what from source at the given byte offset

Errors: Index::Range when offset is invalid

get(invar source: array<int>|string, what: enum<bits>, offset: int, count: int) => int

Reads count bits from source at the given bit offset

Note: count must not exceed 32 Errors: Index::Range for invalid offset, Param for invalid count

set(dest: array<int>, what: enum<byte,ubyte,word,uword,dword,udword,qword,uqword>,offset: int, value: int)
set(dest: array<int>, what: enum<float>, offset: int, value: float)

Writes value described by what to dest at the given byte offset

Errors: Index::Range when offset is invalid

set(dest: array<int>, what: enum<bits>, offset: int, count: int, value: int)

Writes count lower bits of value to dest at the given offset

Note: count must not exceed 32 Errors: Index::Range for invalid offset, Param for invalid count

encode(str: string, codec: enum<base64,z85,hex>) => string

Returns str encoded with the given codec.

Note: For Z85 codec, str size must be a multiple of 4 Errors: Bin when the above does not hold

decode(str: string, codec: enum<base64,z85,hex>) => string

Returns str decoded with the given codec

Errors: Bin when str is not a valid codec-encoded string