Reference

Types

type endian =
| BigEndian
| LittleEndian
| NativeEndian

val string_of_endian : endian -> string

Endianness.

type bitstring = string * int * int

bitstring is the basic type used to store bitstrings.

The type contains the underlying data (a string), the current bit offset within the string and the current bit length of the string (counting from the bit offset). Note that the offset and length are in bits, not bytes.

Normally you don't need to use the bitstring type directly, since there are functions and syntax extensions which hide the details.

See also Bitstring.bitstring_of_string, Bitstring.bitstring_of_file, Bitstring.hexdump_bitstring, Bitstring.bitstring_length.

type t = bitstring

t is a synonym for the Bitstring.bitstring type. This allows you to use this module with functors like Set and Map from the stdlib.

Exceptions

exception Construct_failure of string * string * int * int

Construct_failure (message, file, line, char) may be raised by the BITSTRING constructor. Common reasons are that values are out of range of the fields that contain them, or that computed lengths are impossible (eg. negative length bitfields).

message is the error message.

file, line and char point to the original source location of the BITSTRING constructor that failed.

Bitstring comparison

val compare : bitstring -> bitstring -> int

compare bs1 bs2 compares two bitstrings and returns zero if they are equal, a negative number if bs1 < bs2, or a positive number if bs1 > bs2. This tests "semantic equality" which is not affected by the offset or alignment of the underlying representation (see Bitstring.bitstring).

The ordering is total and lexicographic.

val equals : bitstring -> bitstring -> bool

equals returns true if and only if the two bitstrings are semantically equal. It is the same as calling compare and testing if the result is 0, but usually more efficient.

Bitstring manipulation

val bitstring_length : bitstring -> int

bitstring_length bitstring returns the length of the bitstring in bits. Note this just returns the third field in the Bitstring.bitstring tuple.

val subbitstring : bitstring -> int -> int -> bitstring

subbitstring bits off len returns a sub-bitstring of the bitstring, starting at offset off bits and with length len bits. If the original bitstring is not long enough to do this then the function raises Invalid_argument "subbitstring".

Note that this function just changes the offset and length fields of the Bitstring.bitstring tuple, so is very efficient.

val dropbits : int -> bitstring -> bitstring

Drop the first n bits of the bitstring and return a new bitstring which is shorter by n bits. If the length of the original bitstring is less than n bits, this raises Invalid_argument "dropbits".

Note that this function just changes the offset and length fields of the Bitstring.bitstring tuple, so is very efficient.

val takebits : int -> bitstring -> bitstring

Take the first n bits of the bitstring and return a new bitstring which is exactly n bits long. If the length of the original bitstring is less than n bits, this raises Invalid_argument "takebits".

Note that this function just changes the offset and length fields of the Bitstring.bitstring tuple, so is very efficient.

val concat : bitstring list -> bitstring

Concatenate a list of bitstrings together into a single bitstring.

Constructing bitstrings

val empty_bitstring : bitstring

empty_bitstring is the empty, zero-length bitstring.

val create_bitstring : int -> bitstring

create_bitstring n creates an n bit bitstring containing all zeroes.

val make_bitstring : int -> char -> bitstring

make_bitstring n c creates an n bit bitstring containing the repeated 8 bit pattern in c. For example, make_bitstring 16 '\x5a'will create the bitstring 0x5a5a or in binary 0101 1010 0101 1010.

Note that the length is in bits, not bytes. The length does NOT need to be a multiple of 8.

val zeroes_bitstring : int -> bitstring

zeroes_bitstring creates an n bit bitstring of all 0's. Actually this is the same as Bitstring.create_bitstring.

val ones_bitstring : int -> bitstring

ones_bitstring creates an n bit bitstring of all 1's.

val bitstring_of_string : string -> bitstring

bitstring_of_string strcreates a bitstring of length String.length str * 8 (bits) containing the bits in str.

Note that the bitstring uses str as the underlying string (see the representation of Bitstring.bitstring) so you should not change str after calling this.

val bitstring_of_file : string -> bitstring

bitstring_of_file filename loads the named file into a bitstring.

val bitstring_of_chan : Pervasives.in_channel -> bitstring

bitstring_of_chan chanloads the contents of the input channel chan as a bitstring. The length of the final bitstring is determined by the remaining input in chan, but will always be a multiple of 8 bits.

See also Bitstring.bitstring_of_chan_max.

val bitstring_of_chan_max : Pervasives.in_channel -> int -> bitstring

bitstring_of_chan_max chan max works like Bitstring.bitstring_of_chan but will only read up to max bytes from the channel (or fewer if the end of input occurs before that).

val bitstring_of_file_descr : Unix.file_descr -> bitstring

bitstring_of_file_descr fd loads the contents of the file descriptor fd as a bitstring. See also Bitstring.bitstring_of_chan, Bitstring.bitstring_of_file_descr_max.

val bitstring_of_file_descr_max : Unix.file_descr -> int -> bitstring

bitstring_of_file_descr_max fd max works like Bitstring.bitstring_of_file_descr but will only read up to max bytes from the channel (or fewer if the end of input occurs before that).

Converting bitstrings

val string_of_bitstring : bitstring -> string

string_of_bitstring bitstring converts a bitstring to a string (eg. to allow comparison). This function is inefficient. In the best case when the bitstring is nicely byte-aligned we do a String.sub operation. If the bitstring isn't aligned then this involves a lot of bit twiddling and is particularly inefficient.

If the bitstring is not a multiple of 8 bits wide then the final byte of the string contains the high bits set to the remaining bits and the low bits set to 0.

val bitstring_to_file : bitstring -> string -> unit

bitstring_to_file bits filename writes the bitstring bits to the file filename. It overwrites the output file. Some restrictions apply, see Bitstring.bitstring_to_chan.

val bitstring_to_chan : bitstring -> Pervasives.out_channel -> unit

bitstring_to_file bits filename writes the bitstring bits to the channel chan. Channels are made up of bytes, bitstrings can be any bit length including fractions of bytes. So this function only works if the length of the bitstring is an exact multiple of 8 bits (otherwise it raises Invalid_argument "bitstring_to_chan").

Furthermore the function is efficient only in the case where the bitstring is stored fully aligned, otherwise it has to do inefficient bit twiddling like Bitstring.string_of_bitstring.

In the common case where the bitstring was generated by the BITSTRING operator and is an exact multiple of 8 bits wide, then this function will always work efficiently.

Printing bitstrings

val hexdump_bitstring : Pervasives.out_channel -> bitstring -> unit

hexdump_bitstring chan bitstring prints the bitstring to the output channel in a format similar to the Unix command hexdump -C.

Bitstring buffer

module Buffer: sig .. end

Buffers are mainly used by the BITSTRING constructor, but may also be useful for end users.

Get/set bits

These functions let you manipulate individual bits in the bitstring. However they are not particularly efficient and you should generally use the bitmatch and BITSTRING operators when building and parsing bitstrings.

These functions all raise Invalid_argument "index out of bounds" if the index is out of range of the bitstring.

val set : bitstring -> int -> unit

set bits n sets the nth bit in the bitstring to 1.

val clear : bitstring -> int -> unit

clear bits n sets the nth bit in the bitstring to 0.

val is_set : bitstring -> int -> bool

is_set bits n is true if the nth bit is set to 1.

val is_clear : bitstring -> int -> bool

is_clear bits n is true if the nth bit is set to 0.

val put : bitstring -> int -> int -> unit

put bits n v sets the nth bit in the bitstring to 1 if v is not zero, or to 0 if v is zero.

val get : bitstring -> int -> int

get bits n returns the nth bit (returns non-zero or 0).