Previous  Up  Next

Module Bitstring

module Bitstring: sig .. end
Bitstring library.
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.

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.

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.
val is_zeroes_bitstring : bitstring -> bool
Tests if the bitstring is all zero bits (cf. Bitstring.zeroes_bitstring)
val is_ones_bitstring : bitstring -> bool
Tests if the bitstring is all one bits (cf. Bitstring.ones_bitstring).
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.
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 str creates 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 chan loads 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).
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.

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.
module Buffer: sig .. end
Buffers are mainly used by the BITSTRING constructor, but may also be useful for end users. 
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).
val package : string
The package name, always "ocaml-bitstring"
val version : string
The package version as a string.
val debug : bool Pervasives.ref
Set this variable to true to enable extended debugging. This only works if debugging was also enabled in the pa_bitstring.ml file at compile time, otherwise it does nothing.
val extract_bit : string -> int -> int -> int -> bool
val extract_char_unsigned : string -> int -> int -> int -> int
val extract_char_signed : string -> int -> int -> int -> int
val extract_int_be_unsigned : string -> int -> int -> int -> int
val extract_int_be_signed : string -> int -> int -> int -> int
val extract_int_le_unsigned : string -> int -> int -> int -> int
val extract_int_le_signed : string -> int -> int -> int -> int
val extract_int_ne_unsigned : string -> int -> int -> int -> int
val extract_int_ne_signed : string -> int -> int -> int -> int
val extract_int_ee_unsigned : endian -> string -> int -> int -> int -> int
val extract_int_ee_signed : endian -> string -> int -> int -> int -> int
val extract_int32_be_unsigned : string -> int -> int -> int -> int32
val extract_int32_le_unsigned : string -> int -> int -> int -> int32
val extract_int32_ne_unsigned : string -> int -> int -> int -> int32
val extract_int32_ee_unsigned : endian -> string -> int -> int -> int -> int32
val extract_int64_be_unsigned : string -> int -> int -> int -> int64
val extract_int64_le_unsigned : string -> int -> int -> int -> int64
val extract_int64_ne_unsigned : string -> int -> int -> int -> int64
val extract_int64_ee_unsigned : endian -> string -> int -> int -> int -> int64
val extract_fastpath_int16_be_unsigned : string -> int -> int
val extract_fastpath_int16_le_unsigned : string -> int -> int
val extract_fastpath_int16_ne_unsigned : string -> int -> int
val extract_fastpath_int16_be_signed : string -> int -> int
val extract_fastpath_int16_le_signed : string -> int -> int
val extract_fastpath_int16_ne_signed : string -> int -> int
val extract_fastpath_int32_be_unsigned : string -> int -> int32
val extract_fastpath_int32_le_unsigned : string -> int -> int32
val extract_fastpath_int32_ne_unsigned : string -> int -> int32
val extract_fastpath_int32_be_signed : string -> int -> int32
val extract_fastpath_int32_le_signed : string -> int -> int32
val extract_fastpath_int32_ne_signed : string -> int -> int32
val extract_fastpath_int64_be_unsigned : string -> int -> int64
val extract_fastpath_int64_le_unsigned : string -> int -> int64
val extract_fastpath_int64_ne_unsigned : string -> int -> int64
val extract_fastpath_int64_be_signed : string -> int -> int64
val extract_fastpath_int64_le_signed : string -> int -> int64
val extract_fastpath_int64_ne_signed : string -> int -> int64
val construct_bit : Buffer.t -> bool -> int -> exn -> unit
val construct_char_unsigned : Buffer.t -> int -> int -> exn -> unit
val construct_char_signed : Buffer.t -> int -> int -> exn -> unit
val construct_int_be_unsigned : Buffer.t -> int -> int -> exn -> unit
val construct_int_le_unsigned : Buffer.t -> int -> int -> exn -> unit
val construct_int_ne_unsigned : Buffer.t -> int -> int -> exn -> unit
val construct_int_ee_unsigned : endian -> Buffer.t -> int -> int -> exn -> unit
val construct_int_be_signed : Buffer.t -> int -> int -> exn -> unit
val construct_int_le_signed : Buffer.t -> int -> int -> exn -> unit
val construct_int_ne_signed : Buffer.t -> int -> int -> exn -> unit
val construct_int_ee_signed : endian -> Buffer.t -> int -> int -> exn -> unit
val construct_int32_be_unsigned : Buffer.t -> int32 -> int -> exn -> unit
val construct_int32_le_unsigned : Buffer.t -> int32 -> int -> exn -> unit
val construct_int32_ne_unsigned : Buffer.t -> int32 -> int -> exn -> unit
val construct_int32_ee_unsigned : endian -> Buffer.t -> int32 -> int -> exn -> unit
val construct_int64_be_unsigned : Buffer.t -> int64 -> int -> exn -> unit
val construct_int64_le_unsigned : Buffer.t -> int64 -> int -> exn -> unit
val construct_int64_ne_unsigned : Buffer.t -> int64 -> int -> exn -> unit
val construct_int64_ee_unsigned : endian -> Buffer.t -> int64 -> int -> exn -> unit
val construct_string : Buffer.t -> string -> unit
val construct_bitstring : Buffer.t -> bitstring -> unit