X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=bitstring.mli;h=a29cb03b965ab2330dba714ba121fdc8342d1d1d;hb=64bcd448dc8787b82828a49edb709436ec2de93d;hp=6c35da8c22319eaa82f2a5a947ba214133b89771;hpb=1cd333c8aa3a51f02f36f97518006f502bfa4afa;p=ocaml-bitstring.git diff --git a/bitstring.mli b/bitstring.mli index 6c35da8..a29cb03 100644 --- a/bitstring.mli +++ b/bitstring.mli @@ -667,6 +667,12 @@ type bitstring = string * int * int {!hexdump_bitstring}, {!bitstring_length}. *) +type t = bitstring +(** [t] is a synonym for the {!bitstring} type. + + This allows you to use this module with functors like + [Set] and [Map] from the stdlib. *) + (** {3 Exceptions} *) exception Construct_failure of string * string * int * int @@ -683,6 +689,24 @@ exception Construct_failure of string * string * int * int location of the [BITSTRING] constructor that failed. *) +(** {3 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}). + + 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. *) + (** {3 Bitstring manipulation} *) val bitstring_length : bitstring -> int @@ -722,6 +746,10 @@ val takebits : int -> bitstring -> bitstring Note that this function just changes the offset and length fields of the {!bitstring} tuple, so is very efficient. *) +val concat : bitstring list -> bitstring +(** Concatenate a list of bitstrings together into a single + bitstring. *) + (** {3 Constructing bitstrings} *) val empty_bitstring : bitstring @@ -850,6 +878,36 @@ end may also be useful for end users. They work much like the standard library [Buffer] module. *) +(** {3 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 [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). *) + (** {3 Miscellaneous} *) val package : string @@ -870,38 +928,125 @@ val debug : bool ref * these directly - they are not safe. *) -val extract_bitstring : string -> int -> int -> int -> bitstring * int * int +(* 'extract' functions are used in bitmatch statements. *) + +val extract_bit : string -> int -> int -> int -> bool + +val extract_char_unsigned : string -> int -> int -> int -> int + +val extract_int_be_unsigned : string -> int -> int -> int -> int + +val extract_int_le_unsigned : string -> int -> int -> int -> int + +val extract_int_ne_unsigned : string -> int -> int -> int -> int + +val extract_int_ee_unsigned : endian -> string -> int -> int -> int -> int -val extract_remainder : string -> int -> int -> bitstring * int * int +val extract_int32_be_unsigned : string -> int -> int -> int -> int32 -val extract_bit : string -> int -> int -> int -> bool * int * int +val extract_int32_le_unsigned : string -> int -> int -> int -> int32 -val extract_char_unsigned : string -> int -> int -> int -> int * int * int +val extract_int32_ne_unsigned : string -> int -> int -> int -> int32 -val extract_int_be_unsigned : string -> int -> int -> int -> int * int * int +val extract_int32_ee_unsigned : endian -> string -> int -> int -> int -> int32 -val extract_int_le_unsigned : string -> int -> int -> int -> int * int * int +val extract_int64_be_unsigned : string -> int -> int -> int -> int64 -val extract_int_ne_unsigned : string -> int -> int -> int -> int * int * int +val extract_int64_le_unsigned : string -> int -> int -> int -> int64 -val extract_int_ee_unsigned : endian -> string -> int -> int -> int -> int * int * int +val extract_int64_ne_unsigned : string -> int -> int -> int -> int64 -val extract_int32_be_unsigned : string -> int -> int -> int -> int32 * int * int +val extract_int64_ee_unsigned : endian -> string -> int -> int -> int -> int64 + +external extract_fastpath_int16_be_unsigned : string -> int -> int = "ocaml_bitstring_extract_fastpath_int16_be_unsigned" "noalloc" + +external extract_fastpath_int16_le_unsigned : string -> int -> int = "ocaml_bitstring_extract_fastpath_int16_le_unsigned" "noalloc" + +external extract_fastpath_int16_ne_unsigned : string -> int -> int = "ocaml_bitstring_extract_fastpath_int16_ne_unsigned" "noalloc" + +external extract_fastpath_int16_be_signed : string -> int -> int = "ocaml_bitstring_extract_fastpath_int16_be_signed" "noalloc" + +external extract_fastpath_int16_le_signed : string -> int -> int = "ocaml_bitstring_extract_fastpath_int16_le_signed" "noalloc" + +external extract_fastpath_int16_ne_signed : string -> int -> int = "ocaml_bitstring_extract_fastpath_int16_ne_signed" "noalloc" + +(* +external extract_fastpath_int24_be_unsigned : string -> int -> int = "ocaml_bitstring_extract_fastpath_int24_be_unsigned" "noalloc" -val extract_int32_le_unsigned : string -> int -> int -> int -> int32 * int * int +external extract_fastpath_int24_le_unsigned : string -> int -> int = "ocaml_bitstring_extract_fastpath_int24_le_unsigned" "noalloc" + +external extract_fastpath_int24_ne_unsigned : string -> int -> int = "ocaml_bitstring_extract_fastpath_int24_ne_unsigned" "noalloc" + +external extract_fastpath_int24_be_signed : string -> int -> int = "ocaml_bitstring_extract_fastpath_int24_be_signed" "noalloc" + +external extract_fastpath_int24_le_signed : string -> int -> int = "ocaml_bitstring_extract_fastpath_int24_le_signed" "noalloc" + +external extract_fastpath_int24_ne_signed : string -> int -> int = "ocaml_bitstring_extract_fastpath_int24_ne_signed" "noalloc" +*) + +external extract_fastpath_int32_be_unsigned : string -> int -> int32 -> int32 = "ocaml_bitstring_extract_fastpath_int32_be_unsigned" "noalloc" + +external extract_fastpath_int32_le_unsigned : string -> int -> int32 -> int32 = "ocaml_bitstring_extract_fastpath_int32_le_unsigned" "noalloc" + +external extract_fastpath_int32_ne_unsigned : string -> int -> int32 -> int32 = "ocaml_bitstring_extract_fastpath_int32_ne_unsigned" "noalloc" + +external extract_fastpath_int32_be_signed : string -> int -> int32 -> int32 = "ocaml_bitstring_extract_fastpath_int32_be_signed" "noalloc" + +external extract_fastpath_int32_le_signed : string -> int -> int32 -> int32 = "ocaml_bitstring_extract_fastpath_int32_le_signed" "noalloc" + +external extract_fastpath_int32_ne_signed : string -> int -> int32 -> int32 = "ocaml_bitstring_extract_fastpath_int32_ne_signed" "noalloc" + +(* +external extract_fastpath_int40_be_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int40_be_unsigned" "noalloc" + +external extract_fastpath_int40_le_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int40_le_unsigned" "noalloc" + +external extract_fastpath_int40_ne_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int40_ne_unsigned" "noalloc" + +external extract_fastpath_int40_be_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int40_be_signed" "noalloc" + +external extract_fastpath_int40_le_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int40_le_signed" "noalloc" + +external extract_fastpath_int40_ne_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int40_ne_signed" "noalloc" + +external extract_fastpath_int48_be_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int48_be_unsigned" "noalloc" + +external extract_fastpath_int48_le_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int48_le_unsigned" "noalloc" + +external extract_fastpath_int48_ne_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int48_ne_unsigned" "noalloc" + +external extract_fastpath_int48_be_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int48_be_signed" "noalloc" + +external extract_fastpath_int48_le_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int48_le_signed" "noalloc" + +external extract_fastpath_int48_ne_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int48_ne_signed" "noalloc" + +external extract_fastpath_int56_be_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int56_be_unsigned" "noalloc" + +external extract_fastpath_int56_le_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int56_le_unsigned" "noalloc" + +external extract_fastpath_int56_ne_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int56_ne_unsigned" "noalloc" + +external extract_fastpath_int56_be_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int56_be_signed" "noalloc" + +external extract_fastpath_int56_le_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int56_le_signed" "noalloc" + +external extract_fastpath_int56_ne_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int56_ne_signed" "noalloc" +*) -val extract_int32_ne_unsigned : string -> int -> int -> int -> int32 * int * int +external extract_fastpath_int64_be_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int64_be_unsigned" "noalloc" -val extract_int32_ee_unsigned : endian -> string -> int -> int -> int -> int32 * int * int +external extract_fastpath_int64_le_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int64_le_unsigned" "noalloc" -val extract_int64_be_unsigned : string -> int -> int -> int -> int64 * int * int +external extract_fastpath_int64_ne_unsigned : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int64_ne_unsigned" "noalloc" -val extract_int64_le_unsigned : string -> int -> int -> int -> int64 * int * int +external extract_fastpath_int64_be_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int64_be_signed" "noalloc" -val extract_int64_ne_unsigned : string -> int -> int -> int -> int64 * int * int +external extract_fastpath_int64_le_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int64_le_signed" "noalloc" -val extract_int64_ee_unsigned : endian -> string -> int -> int -> int -> int64 * int * int +external extract_fastpath_int64_ne_signed : string -> int -> int64 -> int64 = "ocaml_bitstring_extract_fastpath_int64_ne_signed" "noalloc" +(* 'construct' functions are used in BITSTRING constructors. *) val construct_bit : Buffer.t -> bool -> int -> exn -> unit val construct_char_unsigned : Buffer.t -> int -> int -> exn -> unit