#lang scribble/doc
@(require
scribble/manual
(for-label "../packing.rkt" "../number.rkt"))
@title[#:tag "number"]{Numeric Packings}
@local-table-of-contents[]
@defmodule[(planet "number.rkt" ("murphy" "packed-io.plt" 1 1))]{
This module provides packings of data represented as numeric values
of a fixed size.
}
@section{Endianness Controls}
@defparam[packing-big-endian? v any/c]{
Parameter that determines whether data is stored in big-endian
format during packing or unpacking.
Defaults to the system's native endianness @racket[(system-big-endian?)].
}
@defproc[(big-endian/p [packing packing?]) packing?]{
Produces a wrapped version of @racket[packing] that sets
@racket[(packing-big-endian? #t)] while packing or unpacking.
}
@defproc[(little-endian/p [packing packing?]) packing?]{
Produces a wrapped version of @racket[packing] that sets
@racket[(packing-big-endian? #f)] while packing or unpacking.
}
@defproc[(native-endian/p [packing packing?]) packing?]{
Produces a wrapped version of @racket[packing] that sets
@racket[(packing-big-endian? (system-big-endian?))] while packing or
unpacking.
}
@section{Integers}
@defproc[(integer/p [size (or/c 1 2 4 8)] [signed? any/c]) packing?]{
Produces a packing for integral numbers into @racket[size]
bytes. @racket[signed?] determines whether the packed values are
signed or unsigned.
}
@deftogether[(
(defthing int8/p packing?)
(defthing sint8/p packing?)
(defthing uint8/p packing?)
(defthing int16/p packing?)
(defthing sint16/p packing?)
(defthing uint16/p packing?)
(defthing int32/p packing?)
(defthing sint32/p packing?)
(defthing uint32/p packing?)
(defthing int64/p packing?)
(defthing sint64/p packing?)
(defthing uint64/p packing?)
)]{
Standard integer packings with 8, 16, 32 and 64 bits representation
size. The packings whose names start with @racket[u] are unsigned,
the others are signed.
}
@deftogether[(
(defthing byte/p packing?)
(defthing sbyte/p packing?)
(defthing ubyte/p packing?)
(defthing short/p packing?)
(defthing sshort/p packing?)
(defthing ushort/p packing?)
(defthing int/p packing?)
(defthing sint/p packing?)
(defthing uint/p packing?)
(defthing long/p packing?)
(defthing slong/p packing?)
(defthing ulong/p packing?)
)]{
Aliases for the standard integer packings with friendly names:
@racket[byte] is 8 bits, @racket[short] is 16 bits, @racket[int] is
32 bits and @racket[long] is 64 bits.
}
@section{Reals}
@defproc[(real/p [size (or/c 4 8)]) packing?]{
Produces a packing for IEEE floating point numbers into
@racket[size] bytes.
}
@deftogether[(
(defthing float/p packing?)
(defthing double/p packing?)
)]{
Standard floating point packings: @racket[float/p] has 32 bits,
@racket[double/p] has 64 bits representation size.
}
@section[#:tag "number-derived"]{Derived Types}
@defproc[(character/p [size (or/c 1 2 4 8)]) packing?]{
Produces a packing of characters as @racket[size] bytes long
unsigned integers.
}
@deftogether[(
(defthing char/p packing?)
(defthing wchar/p packing?)
)]{
Standard character packings: @racket[char/p] has 8 bits,
@racket[wchar/p] has 16 bits representation size.
}
@defthing[bool/p packing?]{
Single byte packing of boolean values. @racket[#f] is represented by
@racket[0], any other value maps to @racket[1] while packing and any
other packed number maps to @racket[#t] when unpacking.
}