.. default-domain:: chpl

.. module:: BitArrays64

BitArrays64
===========
**Usage**

.. code-block:: chapel

   use BitArrays.BitArrays64;


or

.. code-block:: chapel

   import BitArrays.BitArrays64;

.. type:: type bit64Index = int

.. class:: BitArray64

   BitArray64 is an array of boolean values packed together as 64 bit words. All boolean values are mapped one-to-one to a bit in a 64 bit unsigned integer. 


   .. method:: proc init(size: bit64Index, locales = Locales)

      Create a bit array of a given size.
      
      :arg size: The size of the bit array
      :arg locales: What nodes to distibute the values over
      

   .. method:: proc init(ref values: [] uint(64), size: bit64Index)

      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 64 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 any of 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: bit64Index): bool throws

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

   .. method:: proc equals(rhs: BitArray64): 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 set(idx: bit64Index, 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()

      Get the number of values.
      
      :returns: bit vector size.
      :rtype: int(64)
      

   .. 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: BitArray64, rhs: BitArray64)

      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: BitArray64, rhs: BitArray64)

      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: `BitArray64`
      

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

      Copies the values from an rhs bit array.
      
      :arg lhs: the left hand bit array to assign
      :arg rhs: The right hand array to copy
      

   .. method:: proc type <<(lhs: BitArray64, shift: integral): BitArray64 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: `BitArray64`
      
      :throws ShiftRangeError: If `shift` is less than zero or bigger than the size of the bit array.
      

   .. method:: proc type <<=(ref lhs: BitArray64, 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: BitArray64, shift: integral): BitArray64 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: `BitArray64`
      
      :throws ShiftRangeError: If `shift` is less than zero or bigger than the size of the bit array.
      

   .. method:: proc type >>=(ref lhs: BitArray64, 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: BitArray64, rhs: BitArray64)

      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: `BitArray64`
      

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

      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: BitArray64, rhs: BitArray64): BitArray64

      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 results
      :rtype: `BitArray64`
      

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

      Perform the and operation on the values in this bit array with the values in another bit array.
      `lhs` is updated with the result of the operation.
      
      :arg lhs: this bit array
      :arg rhs: bit array to perform and with
      

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

      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: A copy of the values from `lhs` or `rhs`
      :rtype: BitArray64
      

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

      Perform the or operation on the values in this bit array with the values in another bit array.
       `lhs` is updated with the result of the operation.
      
      :arg lhs: this bit array
      :arg rhs: bit array to perform or with
      

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

      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: `BitArray64`
      

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

      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