#lang scribble/doc
@(require
  scribble/manual
  (for-label "../packing.rkt" "../chunk.rkt"))

@title[#:tag "chunk"]{Chunk Packings}

@local-table-of-contents[]

@defmodule[(planet murphy/packed-io/chunk)]{

  This module provides packings of variable size chunks of data.
  
}

@section{Sizes and Counts}

@defproc[(with-size/p [size (or/c 1 2 4 8)]
		      [packing packing?]
		      [#:adjustment adjustment 0]) packing?]{

  Limits the size of input that can be consumed by @racket[packing],
  adding a @racket[size] bytes long unsigned integer to the packed
  representation that determines the size of the following data.

  The given @racket[adjustment] is added to the size of the data
  packed by @racket[packing] while packing and subtracted while
  unpacking.

}

@defproc[(with-count/p [size (or/c 1 2 4 8)]
		       [packing packing?]
		       [#:adjustment adjustment 0]) packing?]{

  Produces a packing for a vector of elements packed using
  @racket[packing]. The length of the vector is stored as a
  @racket[size] bytes long unsigned integer.

  The given @racket[adjustment] is added to the length of the packed
  vector packing and subtracted while unpacking.

}

@section{Blocks of Unlimited Packed Size}

@defthing[bytes/p packing?]{

  Reads all remaining input into a byte string when unpacking and
  writes a plain byte string to the output when packing.

  Combine this with @racket[with-size/p] to pack a byte string
  together with length information.

}

@defthing[string/p packing?]{

  Reads all remaining input into a string when unpacking and writes a
  plain string to the output when packing.

  Combine this with @racket[with-size/p] to pack a string together
  with length information.

}

@section[#:tag "chunk-derived"]{Derived Types}

@defthing[symbol/p packing?]{

  Reads all remaining input into a string and converts it into a
  symbol when unpacking and writes a plain string representation of a
  symbol to the output when packing.

  Combine this with @racket[with-size/p] to pack a symbol together
  with length information.

}