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
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.