X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=bitmatch.mli;h=90f6acccdfd664602b443e43ba780a8fc18e3819;hb=e87f0879fef8e32e7ae7f7103f420c1612f3863f;hp=f1c7ed1a43b4a26d4e8dc7499691b1691584fa4c;hpb=4853c75eb968f482dc8d9919cb56fc12fec8e3d2;p=ocaml-bitstring.git diff --git a/bitmatch.mli b/bitmatch.mli index f1c7ed1..90f6acc 100644 --- a/bitmatch.mli +++ b/bitmatch.mli @@ -15,7 +15,7 @@ * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA * - * $Id: bitmatch.mli,v 1.16 2008-04-25 12:55:39 rjones Exp $ + * $Id: bitmatch.mli,v 1.20 2008-05-08 21:28:28 rjones Exp $ *) (** @@ -29,7 +29,7 @@ this module to both parse and generate binary formats, for example, communications protocols, disk formats and binary files. - {{:http://et.redhat.com/~rjones/bitmatch/}OCaml bitmatch website} + {{:http://code.google.com/p/bitmatch/}OCaml bitmatch website} {2 Examples} @@ -186,7 +186,7 @@ let make_message typ subtype param = match then the standard library [Match_failure] exception is thrown. - Patterns look a bit different from normal match patterns. The + Patterns look a bit different from normal match patterns. They consist of a list of bitfields separated by [;] where each bitfield contains a bind variable, the width (in bits) of the field, and other information. Some example patterns: @@ -381,9 +381,8 @@ Bitmatch.hexdump_bitstring stdout bits ;; computed expression. Detection of compile-time constants is quite simplistic so only an - immediate, simple integer is recognised as a constant and anything - else is considered a computed expression, even expressions such as - [5-2] which are obviously (to our eyes) constant. + simple integer literals and simple expressions (eg. [5*8]) are + recognized as constants. In any case the bit size of an integer is limited to the range \[1..64\]. This is detected as a compile-time error if that is @@ -533,13 +532,15 @@ type bitstring = string * int * int 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 offsets are bits, not bytes. + bit offset). Note that the offset and length are + in {b 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 {!bitstring_of_file}, {!hexdump_bitstring}, - {!bitstring_length}. + + See also {!bitstring_of_string}, {!bitstring_of_file}, + {!hexdump_bitstring}, {!bitstring_length}. *) (** {3 Exceptions} *) @@ -576,22 +577,46 @@ val make_bitstring : int -> char -> bitstring Note that the length is in bits, not bytes. *) +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}) 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 : 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. *) + be a multiple of 8 bits. -val bitstring_of_file : string -> bitstring -(** [bitstring_of_file filename] loads the named file - into a bitstring. *) + See also {!bitstring_of_chan_max}. *) -val hexdump_bitstring : 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]. *) +val bitstring_of_chan_max : in_channel -> int -> bitstring +(** [bitstring_of_chan_max chan max] works like + {!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_of_chan}, {!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_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 bitstring_length : bitstring -> int (** [bitstring_length bitstring] returns the length of @@ -606,6 +631,13 @@ val string_of_bitstring : bitstring -> string bitstring isn't aligned then this involves a lot of bit twiddling and is particularly inefficient. *) +(** {3 Printing bitstrings} *) + +val hexdump_bitstring : 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]. *) + (** {3 Bitstring buffer} *) module Buffer : sig @@ -652,10 +684,16 @@ val extract_int32_le_unsigned : string -> int -> int -> int -> int32 * int * int val extract_int64_be_unsigned : string -> int -> int -> int -> int64 * int * int -val construct_bit : Buffer.t -> bool -> int -> unit +val extract_int64_le_unsigned : string -> int -> int -> int -> int64 * int * int + +val construct_bit : Buffer.t -> bool -> int -> exn -> unit val construct_char_unsigned : Buffer.t -> int -> int -> exn -> unit val construct_int_be_unsigned : Buffer.t -> int -> int -> exn -> unit +val construct_int32_be_unsigned : Buffer.t -> int32 -> int -> exn -> unit + val construct_int64_be_unsigned : Buffer.t -> int64 -> int -> exn -> unit + +val construct_string : Buffer.t -> string -> unit