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#

  • MsgpackError with MsgpackReason.TooLong for a length or count above 4294967295, which MessagePack cannot write. Nothing is written.

  • WriterError if the Writer fails.

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#

silk
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#

silk
pub struct MsgpackOutput

The owner of the functions that write single MessagePack values. It has no fields and is never constructed.

Implementation MsgpackOutput#

silk
impl MsgpackOutput

Associated function writeNil#

silk
pub effect fn writeNil() -> ()
    ! WriterError
    ? &mut Writer

Writes nil, the byte 0xc0.

Errors#

  • WriterError if the Writer fails.

Associated function writeBool#

silk
pub effect fn writeBool(value: bool) -> ()
    ! WriterError
    ? &mut Writer

Writes true as the byte 0xc3, or false as 0xc2.

Errors#

  • WriterError if the Writer fails.

Associated function writeUnsigned#

silk
pub effect fn writeUnsigned(value: u64) -> ()
    ! WriterError
    ? &mut Writer

Writes 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#

  • WriterError if the Writer fails.

Associated function writeSigned#

silk
pub effect fn writeSigned(value: i64) -> ()
    ! WriterError
    ? &mut Writer

Writes 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#

  • WriterError if the Writer fails.

Associated function writeFloat#

silk
pub effect fn writeFloat(value: f64) -> ()
    ! WriterError
    ? &mut Writer

Writes a number as a float 64: 9 bytes, for every value including NaN and the infinities.

Errors#

  • WriterError if the Writer fails.

Associated function writeString#

silk
pub effect fn writeString(value: string) -> ()
    ! MsgpackError | WriterError
    ? &mut Writer

Writes text as a MessagePack string: a fixstr up to 31 bytes, or str 8, str 16 or str 32.

Errors#

  • MsgpackError with MsgpackReason.TooLong if value is longer than 4294967295 bytes. Nothing is written.

  • WriterError if the Writer fails.

Associated function writeBinary#

silk
pub effect fn writeBinary(value: &[u8]) -> ()
    ! MsgpackError | WriterError
    ? &mut Writer

Writes 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#

  • MsgpackError with MsgpackReason.TooLong if value is longer than 4294967295 bytes. Nothing is written.

  • WriterError if the Writer fails.

Associated function writeArrayHeader#

silk
pub effect fn writeArrayHeader(count: usize) -> ()
    ! MsgpackError | WriterError
    ? &mut Writer

Writes the header of an array of count elements. Write exactly count values after it.

Errors#

  • MsgpackError with MsgpackReason.TooLong if count is above 4294967295. Nothing is written.

  • WriterError if the Writer fails.

Associated function writeMapHeader#

silk
pub effect fn writeMapHeader(count: usize) -> ()
    ! MsgpackError | WriterError
    ? &mut Writer

Writes the header of a map of count entries. Write exactly count keys after it, each followed by its value.

Errors#

  • MsgpackError with MsgpackReason.TooLong if count is above 4294967295. Nothing is written.

  • WriterError if the Writer fails.

Associated function writeExtension#

silk
pub effect fn writeExtension(kind: i8, data: &[u8]) -> ()
    ! MsgpackError | WriterError
    ? &mut Writer

Writes 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#

  • MsgpackError with MsgpackReason.TooLong if data is longer than 4294967295 bytes. Nothing is written.

  • WriterError if the Writer fails.

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.

View the source of this page