eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'BitArray':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: BitArray


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:

instance creation
o  fromBytes: aByteArray
return a new instance, capable of holding aByteArray size*8 bits, initialized from aByteArray

Usage example(s):

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

o  new
return a new instance, capable of holding size bits

Usage example(s):

     BitArray new

o  new: size
return a new instance, capable of holding size bits

Usage example(s):

     BitArray new:10
     (BitArray new:10) atAllPut:1

o  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

queries
o  isValidElement: anObject
return true, if instances of me can hold this kind of object

o  literalTokenPrefix

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

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


Instance protocol:

accessing
o  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

o  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

o  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

o  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

o  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

converting
o  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).

o  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 ]).

filling & replacing
o  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'

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

logical operations
o  bitOr: aBitArray
}

Usage example(s):

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

private
o  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

o  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

o  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)

queries
o  defaultElement

o  size
return the size of the receiver

visiting
o  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).


ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Thu, 30 May 2024 09:46:38 GMT