# nibbles

nibbles is a library for accessing multibyte integers from octet arrays and streams. While such accessors are straightforward to write, nibbles aims to centralize such facilities and also provide optimizations for them when appropriate.

## Installation

nibbles can be downloaded at http://www.method-combination.net/lisp/files/nibbles.tar.gz. The latest version is 0.11.

It comes with an ASDF system definition, so `(ASDF:OOS 'ASDF:LOAD-OP :NIBBLES)` should be all that you need to get started.

## License

nibbles is released under a MIT-like license; you can do pretty much anything you want to with the code except claim that you wrote it.

## Integer array accessors

`ub16ref/le vector index => value`
`ub32ref/le vector index => value`
`ub64ref/le vector index => value`

This family of functions accesses an unsigned 16-bit, 32-bit or 64-bit value stored in little-endian order starting at index in vector. vector must be a `(VECTOR (UNSIGNED-BYTE 8))`. These functions are SETFable. For instance:

    CL-USER> (nibbles:ub16ref/le (coerce #(42 53) '(vector (unsigned-byte 8))) 0)
    13610
    CL-USER> (format nil "~X" *)
    "352A"

`ub16ref/be vector index => value`
`ub32ref/be vector index => value`
`ub64ref/be vector index => value`

As the above, only the value is accessed in big-endian order. For instance:

    CL-USER> (nibbles:ub16ref/be (coerce #(42 53) '(vector (unsigned-byte 8))) 0)
    10805
    CL-USER> (format nil "~X" *)
    "2A35"

`sb16ref/le vector index => value`
`sb32ref/le vector index => value`
`sb64ref/le vector index => value`
`sb16ref/be vector index => value`
`sb32ref/be vector index => value`
`sb64ref/be vector index => value`

As the above, only the value accessed is a signed value. For instance:

    CL-USER> (nibbles:sb16ref/be (coerce #(81 92) '(vector (unsigned-byte 8))) 0)
    20828
    CL-USER> (nibbles:sb16ref/be (coerce #(129 135) '(vector (unsigned-byte 8))) 0)
    -32377
    CL-USER> (format nil "~X ~X" ** *)
    "515C -7E79"
    CL-USER> (nibbles:sb16ref/le (coerce #(81 92) '(vector (unsigned-byte 8))) 0)
    23633
    CL-USER> (nibbles:sb16ref/le (coerce #(129 135) '(vector (unsigned-byte 8))) 0)
    -30847
    CL-USER> (format nil "~X ~X" ** *)
    "5C51 -787F"

## Stream readers

`read-ub16/le stream => value`
`read-ub32/le stream => value`
`read-ub64/le stream => value`

This family of functions reads an unsigned 16-bit, 32-bit, or 64-bit value from stream in little-endian order. stream must have an element-type of `(UNSIGNED-BYTE 8)`.

`read-ub16/be stream => value`
`read-ub32/be stream => value`
`read-ub64/be stream => value`

As the above, only the value is read in big-endian order.

`read-sb16/le stream => value`
`read-sb32/le stream => value`
`read-sb64/le stream => value`
`read-sb16/be stream => value`
`read-sb32/be stream => value`
`read-sb64/be stream => value`

As the above, only the value is signed, rather than unsigned.

## Stream writers

`write-ub16/le integer stream => value`
`write-ub32/le integer stream => value`
`write-ub64/le integer stream => value`

This family of functions writes an unsigned 16-bit, 32-bit, or 64-bit integer to stream in little-endian order. stream must have an element-type of `(UNSIGNED-BYTE 8)`. The value written is returned.

`write-ub16/be integer stream => value`
`write-ub32/be integer stream => value`
`write-ub64/be integer stream => value`

As the above, only the value is read in big-endian order.

`write-sb16/le integer stream => value`
`write-sb32/le integer stream => value`
`write-sb64/le integer stream => value`
`write-sb16/be integer stream => value`
`write-sb32/be integer stream => value`
`write-sb64/be integer stream => value`

As the above, only the value is signed, rather than unsigned.