10
1
mirror of https://gitlab.com/scemama/QCaml.git synced 2024-12-23 04:43:32 +01:00
QCaml/common/lib/bitstring.mli

167 lines
4.6 KiB
OCaml
Raw Normal View History

2023-06-27 10:15:50 +02:00
(** Bitstring
We define here a data type to handle bit strings efficiently. When
the bit string contains less than 64 bits, it is stored internally
in a 63-bit integer and uses bitwise instructions. When more than
63 bits are required, the =zarith= library is used to consider the
bit string as a multi-precision integer.
*)
2020-12-26 01:47:55 +01:00
type t
2023-06-27 10:15:50 +02:00
val of_int : int -> t
(** Creates a bit string from an ~int~
2020-12-26 01:47:55 +01:00
2023-06-27 10:15:50 +02:00
Bitstring.of_int 15;;
- : Bitstring.t =
++++------------------------------------------------------------
*)
2020-12-26 01:47:55 +01:00
2020-12-27 23:08:12 +01:00
val of_z : Z.t -> t
2023-06-27 10:15:50 +02:00
(** Creates a bit string from an ~Z.t~ multi-precision integer *)
2020-12-27 23:08:12 +01:00
val zero : int -> t
2023-06-27 10:15:50 +02:00
(** ~zero n~ creates a zero bit string with ~n~ bits *)
2020-12-26 01:47:55 +01:00
val is_zero : t -> bool
2023-06-27 10:15:50 +02:00
(** True if all the bits of the bit string are zero. *)
2020-12-27 23:08:12 +01:00
val numbits : t -> int
2023-06-27 10:15:50 +02:00
(** Returns the number of bits used to represent the bit string *)
2020-12-26 01:47:55 +01:00
val testbit : t -> int -> bool
2023-06-27 10:15:50 +02:00
(** ~testbit t n~ is true if the ~n~-th bit of the bit string ~t~ is set to ~1~
Bitstring.(testbit (of_int 15) 3);;
- : bool = true
Bitstring.(testbit (of_int 15) 4);;
- : bool = false
*)
2020-12-26 01:47:55 +01:00
2020-12-27 23:08:12 +01:00
val neg : t -> t
2023-06-27 10:15:50 +02:00
(** Returns the negative of the integer interpretation of the bit string *)
2020-12-27 23:08:12 +01:00
val shift_left : t -> int -> t
2023-06-27 10:15:50 +02:00
(** ~shift_left t n~ returns a new bit strings with all the bits shifted ~n~
positions to the left
Bitstring.(shift_left (of_int 15) 2);;
- : Bitstring.t =
--++++----------------------------------------------------------
*)
2020-12-27 23:08:12 +01:00
val shift_right : t -> int -> t
2023-06-27 10:15:50 +02:00
(** ~shift_right t n~ returns a new bit strings with all the bits shifted ~n~
positions to the right
Bitstring.(shift_right (of_int 15) 2);;
- : Bitstring.t =
++--------------------------------------------------------------
*)
2020-12-27 23:08:12 +01:00
val shift_left_one : int -> int -> t
2023-06-27 10:15:50 +02:00
(** 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
Bitstring.shift_left_one 32 4;;
- : Bitstring.t =
----+-----------------------------------------------------------
*)
2020-12-26 01:47:55 +01:00
2020-12-27 23:08:12 +01:00
val logor : t -> t -> t
2023-06-27 10:15:50 +02:00
(** Bitwise logical or
Bitstring.(logor (of_int 15) (of_int 73));;
- : Bitstring.t =
++++--+---------------------------------------------------------
*)
2020-12-26 01:47:55 +01:00
val logxor : t -> t -> t
2023-06-27 10:15:50 +02:00
(** Bitwise logical exclusive or
Bitstring.(logxor (of_int 15) (of_int 73));;
- : Bitstring.t =
-++---+---------------------------------------------------------
*)
2020-12-26 01:47:55 +01:00
val logand : t -> t -> t
2023-06-27 10:15:50 +02:00
(** Bitwise logical and
Bitstring.(logand (of_int 15) (of_int 10));;
- : Bitstring.t =
-+-+------------------------------------------------------------
*)
2020-12-26 01:47:55 +01:00
val lognot : t -> t
2023-06-27 10:15:50 +02:00
(** Bitwise logical negation *)
2020-12-26 01:47:55 +01:00
2020-12-27 23:08:12 +01:00
val plus_one : t -> t
2023-06-27 10:15:50 +02:00
(** Takes the integer representation of the bit string and adds one
Bitstring.(plus_one (of_int 15));;
- : Bitstring.t =
----+-----------------------------------------------------------
*)
2020-12-26 01:47:55 +01:00
val minus_one : t -> t
2023-06-27 10:15:50 +02:00
(** Takes the integer representation of the bit string and removes one
Bitstring.(minus_one (of_int 15));;
- : Bitstring.t =
-+++------------------------------------------------------------
*)
2020-12-26 01:47:55 +01:00
2020-12-27 23:08:12 +01:00
val hamdist : t -> t -> int
2023-06-27 10:15:50 +02:00
(** Returns the Hamming distance, i.e. the number of bits differing between two
bit strings
Bitstring.(hamdist (of_int 15) (of_int 73));;
- : int = 3
*)
2020-12-26 01:47:55 +01:00
val trailing_zeros : t -> int
2023-06-27 10:15:50 +02:00
(** Returns the number of trailing zeros in the bit string
Bitstring.(trailing_zeros (of_int 12));;
- : int = 2
*)
2020-12-27 23:08:12 +01:00
val popcount : t -> int
2023-06-27 10:15:50 +02:00
(** Returns the number of bits set to one in the bit string
Bitstring.(popcount (of_int 15));;
- : int = 4
*)
2020-12-26 01:47:55 +01:00
2020-12-27 23:08:12 +01:00
val to_list : ?accu:(int list) -> t -> int list
2023-06-27 10:15:50 +02:00
(** 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~
Bitstring.(to_list (of_int 45));;
- : int list = [1; 3; 4; 6]
*)
2020-12-26 01:54:39 +01:00
val permutations : int -> int -> t list
2023-06-27 10:15:50 +02:00
(** ~permutations 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]]
Bitstring.permutations 2 4;;
- : Bitstring.t list =
[++--------------------------------------------------------------;
+-+-------------------------------------------------------------;
-++-------------------------------------------------------------;
+--+------------------------------------------------------------;
-+-+------------------------------------------------------------;
--++------------------------------------------------------------]
*)
2020-12-26 01:47:55 +01:00
2023-06-27 10:15:50 +02:00
(** Printers *)
2020-12-26 01:47:55 +01:00
val pp : Format.formatter -> t -> unit