.. default-domain:: chpl

.. module:: BitArrays32

BitArrays32
===========
**Usage**

.. code-block:: chapel

   use BitArrays.BitArrays32;


or

.. code-block:: chapel

   import BitArrays.BitArrays32;

.. type:: type bit32Index = int

.. class:: BitArray32

   BitArray32 is an array of boolean values stored packed together as 32 bit words. All boolean values are mapped one-to-one to a bit in a 32 bit integer. 


   .. method:: proc init(size: bit32Index, targetLocales = Locales)

      Create a bit array of a given size.
      The values are distributed across locales with a `Block` distribution.
      
      :arg size: The size of the bit array
      :arg locales: What nodes to distibute the values over
      

   .. method:: proc init(ref values: [] uint(32), size: bit32Index)

      Create a bit array from a given set of values.
      * The input values must be a rectangular 1-dimensional array.
      * The input values must not be a sparse array.
      * The input values must not be an associative array.
      
      :arg values: The valuess in the bit array stored as 32 bit integers.  If the size does is not a multiple of 32 then one extra value must be added to contain the reminder bits.
      :arg size: The number of individual bits in the bit array.
      

   .. method:: proc all(): bool

      Test if all the values are `true`.
      
      :returns: `true` if all the values are `true`
      :rtype: `bool`
      

   .. method:: proc any(): bool

      Test if any of the values are true
      
      :returns: `true` if any of the values are `true`
      :rtype: `bool`
      

   .. method:: proc at(idx: bit32Index): bool throws

      Look up value at index `idx`.
      
      :arg idx: The index in the bitarray to look up.
      
      :returns: value at `idx`
      :rtype: `bool`
      
      :throws BitRangeError: If `idx` is outside the range [1..size).
      

   .. method:: proc equals(rhs: BitArray32): bool

      Compares two bit arrays by values.
      
      :returns: `true` if the two bit arrays has identical values.
      :rtype: `bool`
      

   .. method:: proc fill()

      Set all the values to `true`.
      

   .. method:: proc popcount()

      Count the number of values set to `true`.
      
      :returns: The count.
      :rtype: `int`
      

   .. method:: proc reverse()

      Reverse the ordering of the values. The last value becomes the first value. The second last value becomes the second first value. And so on.
      

   .. method:: proc rotateLeft(shift: integral)

      Rotate all the values to the left. Values wrap around to the other side.
      
      :arg shift: number of bits to rotate
      

   .. method:: proc rotateRight(shift: integral)

      Rotate all the values to the right. Values wrap around to the other side.
      
      :arg shift: number of bits to rotate
      

   .. method:: proc set(idx: bit32Index, value: bool) throws

      Set the value at a given index.
      
      :arg idx: The index of the value.
      :arg value: The value to set.
      
      :throws BitRangeError: if the idx value is outside the range [0, size).
      

   .. method:: proc size(): bit32Index

      Get the number of values.
      
      :returns: bit vector size.
      :rtype: bit32Index
      

   .. itermethod:: iter these()

      Iterate over all the values.
      
      :yields: All the values
      :yields type: bool
      

   .. itermethod:: iter trueIndices()

      Iterate  over the index of all the values that are `true`.
      
      :yields: The index of a `true` value
      :yields type: `int`
      

   .. method:: proc unfill()

      Set all the values to `false`.
      

   .. method:: proc type ==(lhs: BitArray32, rhs: BitArray32)

      Compares parwise the values of the two bit arrays for equality.
      
      :arg lhs: left hand bit array
      :arg rhs: right hand bit array
      
      :returns: if the bits in the arrays are equal
      :rtype: `list`
      

   .. method:: proc type !=(lhs: BitArray32, rhs: BitArray32)

      Compares parwise the values of the two bit arrays for inequality
      
      :arg lhs: left hand bit array
      :arg rhs: right hand bit array
      
      :returns: if the bits in the arrays are equal
      :rtype: `list`
      

   .. method:: proc type =(ref lhs: BitArray32, rhs: BitArray32)

      Copies the values from a bit array.
      
      :arg lhs: the bit array to assign
      :arg rhs: The bit array to copy
      

   .. method:: proc type !(arg: BitArray32): BitArray32

      Nagation operator. Turn all `true` values into `false` values. Turn all `false` values into `true` values.
      
      :returns: A copy of this bit array negated.
      :rtype: `BitArray32`
      

   .. method:: proc type <<(lhs: BitArray32, shift: integral): BitArray32 throws

      Shift the values `shift` values to the right. Missing right values are padded with `false` values.
      
      :arg shift: the number of values to shift.
      
      :returns: A copy of the values shifted to the right.
      :rtype: `BitArray32`
      
      :throws ShiftRangeError: If `shift` is less than zero or bigger than the size of the bit array.
      

   .. method:: proc type <<=(ref lhs: BitArray32, shift: integral) throws

      Shift all the values to the right. Left values are padded with `false` values.
      
      :arg shift: the number of values to shift.
      
      :throws ShiftRangeError: If `shift` is less than zero or bigger than the size of the bit array.
      

   .. method:: proc type >>(lhs: BitArray32, shift: integral): BitArray32 throws

      Shift the values `shift` positions to the left. Missing left values are padded with `false` values.
      
      :arg shift: the number of values to shift.
      
      :returns: a copy of the values shifted `shift` positions to the left.
      :rtype: `BitArray32`
      
      :throws ShiftRangeError: If `shift` is less than zero or bigger than the size of the bit array.
      

   .. method:: proc type >>=(ref lhs: BitArray32, shift: integral) throws

      Shift all the values to the right. Left values are padded with `false` values.
      
      :arg shift: the number of values to shift.
      
      :throws ShiftRangeError: If `shift` is less than zero or bigger than the size of the bit array.
      

   .. method:: proc type ^(lhs: BitArray32, rhs: BitArray32)

      Perform xor the values with the corresponding values in the input bit array. X[i] ^ Y[i] is performed for all indices i where X and Y are bit arrays.
      If one of the two bit arrays has different size then indices fitting the shortes bit array are compared.
      
      :arg lhs: this bit array
      :arg rhs: bit array to perform xor with
      
      :returns: The results
      :rtype: `BitArray32`
      

   .. method:: proc type ^=(ref lhs: BitArray32, rhs: BitArray32)

      Perform xor the values with the corresponding values in the input bit array. X[i] ^ Y[i] is performed for all indices i where X and Y are bit arrays.
      If one of the two bit arrays has different size then indices fitting the shortes bit array are compared.
      
      :arg lhs: this bit array
      :arg rhs: bit array to perform xor with
      

   .. method:: proc type &(lhs: BitArray32, rhs: BitArray32): BitArray32

      Perform the and operation on the values in this bit array with the values in another bit array.
      If one of the two bit arrays has different size then indices fitting the shortes bit array are compared.
      
      :arg lhs: this bit array
      :arg rhs: bit array to perform and with
      
      :returns: the result of `lhs` or `rhs`
      :rtype: `BitArray32`
      

   .. method:: proc type &=(ref lhs: BitArray32, rhs: BitArray32): BitArray32

      Perform the and operation on the values in this bit array with the values in another bit array.
      If one of the two bit arrays has different size then indices fitting the shortes bit array are compared.
      
      :arg lhs: this bit array
      :arg rhs: bit array to perform and with
      

   .. method:: proc type +(lhs: BitArray32, rhs: BitArray32): BitArray32

      Perform the or operation on the values in this bit array with the values in another bit array.
      
      :arg lhs: this bit array
      :arg rhs: bit array to perform or with
      
      :returns: The result of `lhs` or `rhs`
      :rtype: `BitArray32`
      

   .. method:: proc type +=(ref lhs: BitArray32, rhs: BitArray32)

      Perform the or operation on the values in this bit array with the values in another bit array.
      
      :arg lhs: this bit array
      :arg rhs: bit array to perform or with
      

   .. method:: proc type -(lhs: BitArray32, rhs: BitArray32)

      Perform the minus operation on the values in this bit array with the values in another bit array.
       The result is all the values in `lhs` which are not present in `rhs`.
      
      :arg lhs: this bit array
      :arg rhs: bit array to perform minus with
      
      :returns: The result of `lhs` - `rhs`
      :rtype: `BitArray32`
      

   .. method:: proc type -=(ref lhs: BitArray32, rhs: BitArray32)

      Perform the minus operation on the values in this bit array with the values in another bit array.
       The result is all the values in `lhs` which are not present in `rhs`.
      
      :arg lhs: this bit array
      :arg rhs: bit array to perform minus with