Class: BitArray

• Inheritance
• Description
• Related information
• Class protocol
  • instance creation
  • queries
• Instance protocol
  • accessing
  • converting
  • filling & replacing
  • logical operations
  • private
  • queries
  • visiting
• Examples

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--BitArray
               |
               +--BooleanArray

Package:

stx:libbasic

Category:

Collections-Arrayed

Version:

rev: 1.5 date: 2019/06/03 06:21:38

user: cg

file: BitArray.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

BitArrays are specially tuned to store bits, and are useful for bulk bit/boolean data. 
They require only 1/32th (32bit machines) or 1/64th (64bit machines) of the memory 
compared to an array of booleans.

They store 8 bits per byte. Since instances store bits in multiples
of 8, the real size of the collection is kept in an extra instance variable (tally).
It may be useful if huge boolean arrays are needed.

There are 10 types of people in this world: 
    Those who understand binary, & those who don't.

ATTENTION:
    Bits 1 to 8 of the BooleanArray are stored in bits 8 to 1 of the
    corresponding byte, to allow easy mapping to ASN.1 BIT STRING encoding
    in the BER. (i.e. MSB-first)
    Do not change this.
    
[memory requirements:]
    OBJ-HEADER + ((size + 7) // 8)

Related information:

    BooleanArray
    ByteArray
    WordArray
    Array

Class protocol:

 fromBytes: aByteArray

return a new instance, capable of holding aByteArray size*8 bits, initialized from aByteArray

usage example(s):

BitArray fromBytes:#[ 2r00001111 2r10101010 2r01010101]

 new

return a new instance, capable of holding size bits

usage example(s):

BitArray new

 new: size

return a new instance, capable of holding size bits

usage example(s):

BitArray new:10

 uninitializedNew: size

 maxVal

the minimum value which can be stored in instances of me.
For BitArrays, this is 1

 minVal

the minimum value which can be stored in instances of me.
For BitArrays, this is 0

Instance protocol:

 at: index

retrieve the bit at index (1..)

usage example(s):

(BitArray new:1000) at:555 (BitArray new:1000) at:400 put:1; at:400

 at: index put: aNumber

store the argument, aNumber at index (1..);
return the argument, aNumber (sigh).

 byteAt: index

retrieve 8 bits at index; the index is 1 for the first 8 bits, 2 for the next 8 bits etc.

usage example(s):

((BitArray new:8) at:1 put:1); byteAt:1

 byteAt: index put: aByte

store 8 bits at index; the index is 1 for the first 8 bits, 2 for the next 8 bits etc.

usage example(s):

((BitArray new:8) byteAt:1 put:128); at:1

 occurrencesOf: anElement

count the occurrences of the argument, anElement in the receiver

usage example(s):

(BitArray new:10) at:4 put:1; at:6 put:1; at:7 put:1; occurrencesOf:1 (BitArray new:10) at:4 put:1; at:6 put:1; at:7 put:1; occurrencesOf:0

 bytes

answer myself as a ByteArray containing my bytes

 atAllPut: aNumber

replace all elements of the collection by the argument, aNumber.
Return the receiver.
The argument, aBoolean must be 0 or 1.
Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

usage example(s):

((self new:10) atAllPut:1) countOnes ((self new:8) atAllPut:1) countOnes

 bitOr: aBitArray

}

usage example(s):

((BitArray new:5) at:3 put:1; yourself) bitOr:((BitArray new:8) at:5 put:1; yourself)

 countOnes

count the 1-bits in the receiver

usage example(s):

(BooleanArray new:100) at:14 put:true; at:55 put:true; countOnes (BooleanArray new:100) at:14 put:true; at:55 put:true; occurrencesOf:true (BooleanArray new:100) at:14 put:true; at:55 put:true; occurrencesOf:false

 indexOfNth: n occurrenceOf: what

return the index of the nTh occurrence of a value, or 0 if there are not that many

usage example(s):

(BooleanArray new:100) at:1 put:true; at:2 put:true; at:4 put:true; at:5 put:true; at:6 put:true; at:7 put:true; at:8 put:true; at:10 put:true; indexOfNth:8 occurrenceOf:false

 setTally: size

set my tally - that is the actual number of bits in me
(usually a little less than the number of bits in my byte array)

 defaultElement

 isValidElement: anObject

return true, if I can hold this kind of object

 size

return the size of the receiver

 acceptVisitor: aVisitor with: aParameter

dispatch for visitor pattern; send #visitBitArray:with: to aVisitor

Examples:

    (BitArray new:7) inspect

    (BitArray new:7) basicInspect

    |bits|

    bits := BitArray new:1000000.
    (bits at:9999) printCR.
    bits at:9999 put:1.
    (bits at:9999) printCR.