silk.msgpack.output.
Write MessagePack values one at a time through the ambient Writer.
When to use#
Use MsgpackOutput to write MessagePack by hand, value by value, without a tree: a scalar with
one call, an array with MsgpackOutput.writeArrayHeader and then its elements, a map with
MsgpackOutput.writeMapHeader and then each key and its value. To write a tree, use
silk.msgpack.value.Msgpack.write. To write your own types, use
silk.schema.msgpack.SchemaMsgpack.encode.
Details#
Every value is written in the shortest MessagePack format that holds it: an integer from -32 to
127 takes one byte, a string of up to 31 bytes one header byte. A float is always written as a
float 64. Nothing is buffered and nothing is allocated; the functions do not flush the
Writer.
Errors#
MsgpackErrorwithMsgpackReason.TooLongfor a length or count above 4294967295, which MessagePack cannot write. Nothing is written.WriterErrorif theWriterfails.
Gotchas#
The functions do not check that the elements written after a header match its count. A wrong count gives bytes that a reader misreads.
Examples#
Write a map by hand#
import silk.collections.slice { Slice }
import silk.core.effect { Effect }
import silk.io.writer { Writer, WriterError }
import silk.msgpack.output { MsgpackOutput }
import silk.msgpack.scanner { MsgpackError }
struct Capture {
bytes: [u8; 32],
length: usize,
}
impl Writer for Capture {
effect fn writeAll(self: &mut Self, value: &[u8]) -> () ! WriterError ? &mut Writer {
if self.length + value.length > 32 { fail Writer.failure() }
Slice.copyInto<u8>(&mut self.bytes, self.length, value)
self.length = self.length + value.length
return ()
}
effect fn flush(self: &mut Self) -> () ! WriterError ? &mut Writer { return () }
}
effect fn write() -> () ! MsgpackError | WriterError ? &mut Writer {
// {"id": 7, "ok": true}
run MsgpackOutput.writeMapHeader(2)
run MsgpackOutput.writeString("id")
run MsgpackOutput.writeUnsigned(7)
run MsgpackOutput.writeString("ok")
return run MsgpackOutput.writeBool(true)
}
pub effect fn main() -> i32 ! MsgpackError | WriterError {
let mut capture = Capture { bytes: [0; 32], length: 0 }
run write() |> Effect.provideMut<Writer>(&mut capture)
if Slice.view<u8>(&capture.bytes, 0, capture.length) != b"\x82\xa2id\x07\xa2ok\xc3" {
return 1
}
return 0
}Import as MsgpackOutput with import silk.msgpack.output { MsgpackOutput }.
Public declarations: 1.
MsgpackOutput#
pub struct MsgpackOutputThe owner of the functions that write single MessagePack values. It has no fields and is never constructed.
Implementation MsgpackOutput#
impl MsgpackOutputAssociated function writeNil#
pub effect fn writeNil() -> ()
! WriterError
? &mut WriterWrites nil, the byte 0xc0.
Errors#
WriterErrorif theWriterfails.
Associated function writeBool#
pub effect fn writeBool(value: bool) -> ()
! WriterError
? &mut WriterWrites true as the byte 0xc3, or false as 0xc2.
Errors#
WriterErrorif theWriterfails.
Associated function writeUnsigned#
pub effect fn writeUnsigned(value: u64) -> ()
! WriterError
? &mut WriterWrites an integer in the shortest format that holds it: one byte from 0 to 127, or
uint 8, uint 16, uint 32 or uint 64.
Errors#
WriterErrorif theWriterfails.
Associated function writeSigned#
pub effect fn writeSigned(value: i64) -> ()
! WriterError
? &mut WriterWrites an integer in the shortest format that holds it.
Details#
A value of 0 or more is written as MsgpackOutput.writeUnsigned writes it, so the same
number has the same bytes whichever function wrote it. A negative value takes one byte from
-32 to -1, or int 8, int 16, int 32 or int 64.
Errors#
WriterErrorif theWriterfails.
Associated function writeFloat#
pub effect fn writeFloat(value: f64) -> ()
! WriterError
? &mut WriterWrites a number as a float 64: 9 bytes, for every value including NaN and the infinities.
Errors#
WriterErrorif theWriterfails.
Associated function writeString#
pub effect fn writeString(value: string) -> ()
! MsgpackError | WriterError
? &mut WriterWrites text as a MessagePack string: a fixstr up to 31 bytes, or str 8, str 16 or
str 32.
Errors#
MsgpackErrorwithMsgpackReason.TooLongifvalueis longer than 4294967295 bytes. Nothing is written.WriterErrorif theWriterfails.
Associated function writeBinary#
pub effect fn writeBinary(value: &[u8]) -> ()
! MsgpackError | WriterError
? &mut WriterWrites bytes as MessagePack binary data: bin 8, bin 16 or bin 32.
When to use#
Use it for data that is not text. A reader tells binary data from a string, so write text
with MsgpackOutput.writeString.
Errors#
MsgpackErrorwithMsgpackReason.TooLongifvalueis longer than 4294967295 bytes. Nothing is written.WriterErrorif theWriterfails.
Associated function writeArrayHeader#
pub effect fn writeArrayHeader(count: usize) -> ()
! MsgpackError | WriterError
? &mut WriterWrites the header of an array of count elements. Write exactly count values after it.
Errors#
MsgpackErrorwithMsgpackReason.TooLongifcountis above 4294967295. Nothing is written.WriterErrorif theWriterfails.
Associated function writeMapHeader#
pub effect fn writeMapHeader(count: usize) -> ()
! MsgpackError | WriterError
? &mut WriterWrites the header of a map of count entries. Write exactly count keys after it, each
followed by its value.
Errors#
MsgpackErrorwithMsgpackReason.TooLongifcountis above 4294967295. Nothing is written.WriterErrorif theWriterfails.
Associated function writeExtension#
pub effect fn writeExtension(kind: i8, data: &[u8]) -> ()
! MsgpackError | WriterError
? &mut WriterWrites an extension value: the type kind and the payload data, which MessagePack does
not interpret.
Details#
A payload of 1, 2, 4, 8 or 16 bytes is written as a fixext, any other as ext 8, ext 16
or ext 32. Applications use the types 0 to 127; MessagePack reserves the negative ones,
such as -1 for a timestamp.
Errors#
MsgpackErrorwithMsgpackReason.TooLongifdatais longer than 4294967295 bytes. Nothing is written.WriterErrorif theWriterfails.
Category: Data formats.
Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.