module Bitstring:sig
..end
type
endian =
| |
BigEndian |
| |
LittleEndian |
| |
NativeEndian |
val string_of_endian : endian -> string
typebitstring =
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
.
typet =
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
Bitstring.zeroes_bitstring
)val is_ones_bitstring : bitstring -> bool
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
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
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
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
BITSTRING
constructor, but
may also be useful for end users.
val set : bitstring -> int -> unit
set bits n
sets the n
th bit in the bitstring to 1.val clear : bitstring -> int -> unit
clear bits n
sets the n
th bit in the bitstring to 0.val is_set : bitstring -> int -> bool
is_set bits n
is true if the n
th bit is set to 1.val is_clear : bitstring -> int -> bool
is_clear bits n
is true if the n
th bit is set to 0.val put : bitstring -> int -> int -> unit
put bits n v
sets the n
th 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 n
th bit (returns non-zero or 0).val package : string
"ocaml-bitstring"
val version : string
val debug : bool Pervasives.ref
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