Class: BitArray

• Inheritance
• Description
• 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.19 date: 2024/02/24 17:00:13

user: cg

file: BitArray.st directory: libbasic

module: stx stc-classLibrary: libbasic

Description:

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

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.

BitArrays can be used as literals i.e. you can enter BitArrays-constants as:
    #u1( element1 element2 .... elementN )         // u1 stands for unsigned-1bit integer
or
    #b( element1 element2 .... elementN )          // b stands for bit
for example:
    #u1(1 0 1 0 )
    #b(1 0 1 0 )

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)

[complexity:]
    see Array

copyright
COPYRIGHT (c) 1997 by eXept Software AG / Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

This is a demo example:

THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTOR ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE CONTRIBUTOR BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

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 (BitArray new:10) atAllPut:1

 uninitializedNew: size

return a new instance with undefined contents.
Only useful if all bits are overwritten anyway

Usage example(s):

BitArray new:1000 BitArray uninitializedNew:1000000

 isValidElement: anObject

return true, if instances of me can hold this kind of object

 literalTokenPrefix

 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

Usage example(s):

|b| b := BitArray new:1000. b at:555 put:1. b at:555

 at: index put: aNumber

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

Usage example(s):

|b| b := BitArray new:1000. b at:555 put:1. b at:555

 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

 asInteger

|bits|
bits := BitArray new:16.
bits at:1 put:1.
self assert:(bits asInteger == 1).
bits at:3 put:1.
self assert:(bits asInteger == (1+4)).
bits at:5 put:1.
self assert:(bits asInteger == (1+4+16)).
bits at:7 put:1.
self assert:(bits asInteger == (1+4+16+64)).
bits at:9 put:1.
self assert:(bits asInteger == (1+4+16+64+256)).
bits at:11 put:1.
self assert:(bits asInteger == (1+4+16+64+256+1024)).
bits at:13 put:1.
self assert:(bits asInteger == (1+4+16+64+256+1024+4096)).

Usage example(s):

|bits| bits := BitArray new:100. bits at:100 put:1. self assert:(bits asInteger = (2**99)). self assert:(bits asInteger highBit = 100).

 bytes

answer myself as a ByteArray containing my bytes

Usage example(s):

bytes at:index put:(self byteAt:index)

Usage example(s):

|bits| bits := BitArray new:16. bits at:1 put:1. self assert:(bits bytes = #[ 0x80 0x00 ]). bits at:3 put:1. self assert:(bits bytes = #[ 0xA0 0x00 ]). bits at:5 put:1. self assert:(bits bytes = #[ 0xA8 0x00 ]). bits at:7 put:1. self assert:(bits bytes = #[ 0xAA 0x00 ]). bits at:9 put:1. self assert:(bits bytes = #[ 0xAA 0x80 ]). bits at:11 put:1. self assert:(bits bytes = #[ 0xAA 0xA0 ]). bits at:13 put:1. self assert:(bits bytes = #[ 0xAA 0xA8 ]). bits at:15 put:1. self assert:(bits bytes = #[ 0xAA 0xAA ]).

Usage example(s):

|bits| bits := BitArray new:32. bits at:24 put:1. self assert:(bits bytes = #[ 0x00 0x00 0x01 0x00 ]). bits at:32 put:1. self assert:(bits bytes = #[ 0x00 0x00 0x01 0x01 ]).

 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 ((self new:6) atAllPut:1) countOnes ((self new:30) atAllPut:1; atAllPut:0) countOnes ((self new:30) atAllPut:0; atAllPut:1) countOnes |bits| bits := BitArray new:1000000. [ bits atAllPut:1 ] benchmark:'fill'

 fillWithByte: aByte

bulk replace all elements with aByte; only useful if byte is 0 or 1

 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

 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.
    Transcript showCR:(bits at:9999).
    bits at:9999 put:1.
    Transcript showCR:(bits at:9999).