QCaml/common/lib/bitstring.mli

(* Type *)


(* [[file:../bitstring.org::*Type][Type:1]] *)
type t
(* Type:1 ends here *)

(* ~of_int~
 *     
 *     Creates a bit string from an ~int~. *)


(* [[file:../bitstring.org::*~of_int~][~of_int~:1]] *)
val of_int : int -> t
(* ~of_int~:1 ends here *)

(* ~of_z~
 *     
 *     Creates a bit string from an ~Z.t~ multi-precision integer. *)


(* [[file:../bitstring.org::*~of_z~][~of_z~:1]] *)
val of_z : Z.t -> t
(* ~of_z~:1 ends here *)

(* ~zero~
 * 
 *     ~zero n~ creates a zero bit string with ~n~ bits. *)
    

(* [[file:../bitstring.org::*~zero~][~zero~:1]] *)
val zero : int -> t
(* ~zero~:1 ends here *)

(* ~numbits~
 * 
 *     Returns the number of bits used to represent the bit string. *)
    

(* [[file:../bitstring.org::*~numbits~][~numbits~:1]] *)
val numbits : t -> int
(* ~numbits~:1 ends here *)

(* ~is_zero~
 * 
 *     True if all the bits of the bit string are zero. *)
    

(* [[file:../bitstring.org::*~is_zero~][~is_zero~:1]] *)
val is_zero : t -> bool
(* ~is_zero~:1 ends here *)

(* ~neg~
 * 
 *     Returns the negative of the integer interpretation of the bit string.
 * 
 *     #+begin_example
 * neg (of_int x) = neg (of_int (-x))
 *     #+end_example *)


(* [[file:../bitstring.org::*~neg~][~neg~:1]] *)
val neg : t -> t
(* ~neg~:1 ends here *)

(* ~shift_left~
 * 
 *     ~shift_left t n~ returns a new bit strings with all the bits
 *     shifted ~n~ positions to the left. *)
    

(* [[file:../bitstring.org::*~shift_left~][~shift_left~:1]] *)
val shift_left : t -> int -> t
(* ~shift_left~:1 ends here *)

(* ~shift_right~
 * 
 *     ~shift_right t n~ returns a new bit strings with all the bits
 *     shifted ~n~ positions to the right. *)
    

(* [[file:../bitstring.org::*~shift_right~][~shift_right~:1]] *)
val shift_right : t -> int -> t
(* ~shift_right~:1 ends here *)

(* ~shift_left_one~
 * 
 *     ~shift_left_one size n~ returns a new bit strings with the ~n~-th
 *     bit set to one.
 *     It is equivalent as shifting ~1~ by ~n~ bits to the left.
 *     ~size~ is the total number of bits of the bit string. *)
    

(* [[file:../bitstring.org::*~shift_left_one~][~shift_left_one~:1]] *)
val shift_left_one : int -> int -> t
(* ~shift_left_one~:1 ends here *)

(* ~testbit~
 * 
 *     ~testbit t n~ is true if the ~n~-th bit of the bit string ~t~ is
 *     set to ~1~. *)
    

(* [[file:../bitstring.org::*~testbit~][~testbit~:1]] *)
val testbit : t -> int -> bool
(* ~testbit~:1 ends here *)

(* ~logor~
 * 
 *     Bitwise logical or. *)


(* [[file:../bitstring.org::*~logor~][~logor~:1]] *)
val logor : t -> t -> t
(* ~logor~:1 ends here *)

(* ~logxor~
 * 
 *     Bitwise logical exclusive or. *)


(* [[file:../bitstring.org::*~logxor~][~logxor~:1]] *)
val logxor : t -> t -> t
(* ~logxor~:1 ends here *)

(* ~logand~
 * 
 *     Bitwise logical and. *)


(* [[file:../bitstring.org::*~logand~][~logand~:1]] *)
val logand : t -> t -> t
(* ~logand~:1 ends here *)

(* ~lognot~
 * 
 *     Bitwise logical negation. *)


(* [[file:../bitstring.org::*~lognot~][~lognot~:1]] *)
val lognot : t -> t
(* ~lognot~:1 ends here *)

(* ~minus_one~
 * 
 *     Takes the integer representation of the bit string and removes one.
 * 
 *     #+begin_example
 * minus_one (of_int 10) = of_int 9
 *     #+end_example *)


(* [[file:../bitstring.org::*~minus_one~][~minus_one~:1]] *)
val minus_one : t -> t
(* ~minus_one~:1 ends here *)

(* ~plus_one~
 * 
 *     Takes the integer representation of the bit string and adds one.
 * 
 *     #+begin_example
 * plus_one (of_int 10) = of_int 11
 *     #+end_example *)


(* [[file:../bitstring.org::*~plus_one~][~plus_one~:1]] *)
val plus_one : t -> t
(* ~plus_one~:1 ends here *)

(* ~trailing_zeros~
 * 
 *     Returns the number of trailing zeros in the bit string. *)
    

(* [[file:../bitstring.org::*~trailing_zeros~][~trailing_zeros~:1]] *)
val trailing_zeros : t -> int
(* ~trailing_zeros~:1 ends here *)

(* ~hamdist~
 * 
 *     Returns the Hamming distance, i.e. the number of bits differing
 *     between two bit strings. *)
    

(* [[file:../bitstring.org::*~hamdist~][~hamdist~:1]] *)
val hamdist : t -> t -> int
(* ~hamdist~:1 ends here *)

(* ~popcount~
 * 
 *     Returns the number of bits set to one in the bit string. *)
    

(* [[file:../bitstring.org::*~popcount~][~popcount~:1]] *)
val popcount : t -> int
(* ~popcount~:1 ends here *)

(* ~to_list~
 * 
 *     Converts a bit string into a list of integers indicating the
 *     positions where the bits are set to ~1~. The first value for the
 *     position is not ~0~ but ~1~.
 *     
 *     #+begin_example
 * Bitstring.to_list (of_int 5);;
 * - : int list = [1; 3]
 *     #+end_example *)


(* [[file:../bitstring.org::*~to_list~][~to_list~:1]] *)
val to_list : ?accu:(int list) -> t -> int list
(* ~to_list~:1 ends here *)

(* ~permtutations~
 * 
 *     ~permtutations m n~ generates the list of all possible ~n~-bit
 *     strings with ~m~ bits set to ~1~.
 *     Algorithm adapted from [[https://graphics.stanford.edu/~seander/bithacks.html#NextBitPermutation][Bit twiddling hacks]].
 *     
 *     #+begin_example
 * Bitstring.permtutations 2 4                                                                   |> List.map (fun x -> Format.asprintf "%a" Bitstring.pp x) ;;
 * |> List.map (fun x -> Format.asprintf "%a" Bitstring.pp x) ;;
 * - : string list =
 * ["++--------------------------------------------------------------";
 *  "+-+-------------------------------------------------------------";
 *  "-++-------------------------------------------------------------";
 *  "+--+------------------------------------------------------------";
 *  "-+-+------------------------------------------------------------";
 *  "--++------------------------------------------------------------"]
 *     #+end_example *)
    

(* [[file:../bitstring.org::*~permtutations~][~permtutations~:1]] *)
val permtutations : int -> int -> t list
(* ~permtutations~:1 ends here *)

(* Printers
 * 
 *    Printers can print as a string (~pp_string~) or as an integer (~pp_int~). *)


(* [[file:../bitstring.org::*Printers][Printers:1]] *)
val pp : Format.formatter -> t -> unit
(* Printers:1 ends here *)