API for bytebuffer.buff
by
Unknown
Usage:
(ns your-namespace
(:require bytebuffer.buff))
Overview
Library for packing and unpacking binary data. Simplifies working
with java.nio.ByteBuffer objects.
Notable features:
1. Handles signed and unsigned values pleasantly. Usually reading or
writing unsigned fields with ByteBuffers is a pain because Java
doesn't have unsigned primitives. The unsigned take-* functions here
actually return a type that is one step larger than the requested
type, ex. take-ushort returns an int, and take-uint returns a
bigint. The larger types are big enough to handle the entire unsigned
range of the smaller type. Similarly, although there are not separate
signed and unsigned version, the put-* functions will accept any
number type and truncate it so both positive and negative numbers can
be stored. TODO: Should add an overflow check to avoid overflows in
put-* functions?
2. Provides pack and unpack functions inspired by Python's struct
module. Use simple format strings, similar to printf's, to define how
fields are layed out in the buffer.
Usage:
(pack buff "isbb" 123 43 23 3) ; puts an int, a short and two bytes into buff
(.flip buff) ; assuming nothing else was written to the buffer
(unpack buff "isbb") => (123 43 24 3)
3. Provides pack-bits and unpack-bits functions for working with bit
fields within numbers. These are useful for pulling apart flag fields.
See also:
java.nio.ByteBuffer Documentation
Public Variables and Functions
byte-buffer
function
Usage: (byte-buffer capacity)
Creates a ByteBuffer of capacity bytes
Source
pack
function
Usage: (pack buff fmt & vals)
Puts one or more numbers for vals into buff using field sizes
determined by the characters in the fmt sequence. Valid characters are
b - byte
s - short
i - int
l - long
The number of characters in fmt must match the number of numbers in vals.
Usage: (pack buff "isbb" 123 43 23 3) ; puts an int, a short and two bytes into buff
Returns buff.
Source
pack-bits
function
Usage: (pack-bits)
(pack-bits & fields)
Packs multiple numbers into a single number using explicit bit lengths.
fields => bit-length value
The value can also be a boolean. true is stored as 1, false as 0
Source
put-byte
function
Usage: (put-byte val)
(put-byte buff val)
Puts a byte into the buffer
Source
put-int
function
Usage: (put-int val)
(put-int buff val)
Puts an int (4 bytes) into the buffer
Source
put-long
function
Usage: (put-long val)
(put-long buff val)
Puts a long (8 bytes) into the buffer
Source
put-short
function
Usage: (put-short val)
(put-short buff val)
Puts a short (2 bytes) into the buffer
Source
take-byte
function
Usage: (take-byte)
(take-byte buff)
Takes a signed byte from the buffer
Source
take-int
function
Usage: (take-int)
(take-int buff)
Takes a signed int (4 bytes) from the buffer
Source
take-long
function
Usage: (take-long)
(take-long buff)
Takes a signed long (8 bytes) from the buffer
Source
take-short
function
Usage: (take-short)
(take-short buff)
Takes a signed short (2 bytes) from the buffer
Source
take-ubyte
function
Usage: (take-ubyte)
(take-ubyte buff)
Takes an unsigned signed byte from the buffer
Source
take-uint
function
Usage: (take-uint)
(take-uint buff)
Takes a unsigned int (4 bytes) from the buffer
Source
take-ulong
function
Usage: (take-ulong)
(take-ulong buff)
Takes a unsigned long (8 bytes) from the buffer
Source
take-ushort
function
Usage: (take-ushort)
(take-ushort buff)
Takes a unsigned short (2 bytes) from the buffer
Source
unpack
function
Usage: (unpack buff fmt)
Returns a sequence of one or more numbers taken from buff. The
number and type of numbers taken is determined by fmt which is a
sequence of characters. Valid characters in fmt:
b - byte
B - unsigned byte
s - short
S - unsigned short
i - int
I - unsigned int
l - long
L - unsigned long
Source
unpack-bits
function
Usage: (unpack-bits x & bit-lengths)
Pulls apart a number into a list of fields of various bit lengths.
Pass a non-positive bit length to skip that many bits without adding a
corresponding value to the result list.
Passing a field length of 1 will add either a 0 or a 1 to the
resulting sequence. To get a boolean value instead, pass \b.
Source
with-buffer
macro
Usage: (with-buffer buffer & body)
Sets the buffer currently being used by the put-* and take-*
functions which do not take buffers.
Source