Smalltalk/X Webserver

Documentation of class 'ByteArray':

Class: ByteArray

Inheritance
Description
Warning
Related information
Class protocol
- instance creation
- queries
Instance protocol

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--ByteArray
                  |
                  +--ImmutableByteArray
                  |
                  +--SignedByteArray
                  |
                  +--UUID

Package:: stx:libbasic

Category:: Collections-Arrayed

Version:: rev: 1.267 date: 2019/07/28 10:02:48; user: cg; file: ByteArray.st directory: libbasic; module: stx stc-classLibrary: libbasic

Author:: Claus Gittinger

Description:

ByteArrays store integers in the range 0..255.
In contrast to normal arrays (which store pointers to their elements),
byteArrays store the values in a dense & compact way. 
ByteArrays can be used to hold the data for bitmaps, images and other bulk data
(instances are returned eg. when reading a binary file or socket).
ByteArrays are also used to store the bytecode-instructions of an
interpreted method and are used as superclass for Strings.

ByteArrays can be used as literals i.e. you can enter ByteArray-constants
as #[ element1 element2 .... elementN] and also use byteArray constants
as elements in a constant array.
As in: #( #[1 1 1] #[2 2 2] #[3 3 3])

If you have to communicate structure-data (in the C-sense) with external
programs/data-bases, see companion classes (Structure, ExternalBytes and ExternalStructure).
It allows the definition of subclasses of ByteArray, which transparently fetch
and store C-structure fields.

[memory requirements:]
    OBJ-HEADER + size

Warning:

read the warning about 'growing fixed size collection'
in ArrayedCollection's documentation

Related information:

    Array
    CharacterArray
    String

Class protocol:

instance creation

uninitializedNew: anInteger: return a new instance of the receiver with uninitialized
(i.e. undefined) contents. The indexed elements have any random
value. However, any named instance variables are still nilled.
For use, when contents will be set anyway shortly after - this
is a bit faster than the regular basicNew:, which clears the bytes.
Of course, it only makes a difference for very big ByteArrays, such
as used for images/bitmaps.

Notice: if you want to port code using uninitializedNew: to another
smalltalk, you have to add an 'uninitializedNew: -> basicNew:'-calling
method to the ByteArray class of the other smalltalk.

queries

elementByteSize: for bit-like containers, return the number of bytes stored per element.
Here, 1 is returned
isBuiltInClass: return true if this class is known by the run-time-system.
Here, true is returned for myself, false for subclasses.
maxVal: the minimum value which can be stored in instances of me.
For ByteArrays, this is 255
minVal: the minimum value which can be stored in instances of me.
For ByteArrays, this is 0

ST-80 compatibility: encode the receiver into an ascii String
with 6bits encoded per character. Each group of 6 bits is encoded
as a corresponding character (32+value) and the resulting string
is returned. The resulting string is always a multiple of 4 (since
24 is the lcm of 6 and 8) and the number of remaining characters is
encoded in the last character.
ST-80 uses this encoding for Images...
This is a base64 encoding, very similar (but not equal) to the algorithm used in RFC1421.
PS: I don't like it ;-)
See also: fromPackedString: - the reverse operation

usage example(s):

     #[ 16r00 16r01 16r02 16r04 16r08 16r10 16r20 16r40 16r80 ] asPackedString

asSignedByteArray

return the receiver as a signed byteArray.
elements > 127 are converted to negative numbers.

usage example(s):

     'hello world' asSignedByteArray
     #[1 2 3 4 5 6 7] asSignedByteArray
     #[1 2 129 4 5 6 7] asSignedByteArray

asString

speed up string conversions

usage example(s):

      #[16r41 16r42 16r43] asString
      #[16r41 16r42 16r43] asImmutableByteArray asString

beImmutable

make myself write-protected

beSigned

destructively make mayself signed.
elements > 127 are converted to negative numbers.
WARNING: this changes the receiver itself
- use this only for initialization of new instances

usage example(s):

     #[ 1 2 3 128 255 ] copy beSigned
     #[ 1 2 3 128 255 ] beImmutable beSigned

beUnsigned

that's what I am (but I don't know if this is true for subclasses).

usage example(s):

     #[ 1 2 3 128 255 ] copy beUnsigned

decodeAsLiteralArray

given a literalEncoding in the receiver,
create & return the corresponding object.
The inverse operation to #literalArrayEncoding.

literalArrayEncoding

encode myself as an array literal, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.

usage example(s):

     #[1 2 3] literalArrayEncoding

copying

copy

redefined for a bit more speed

copyFrom: start to: stop

return the subcollection starting at index start, anInteger and ending
at stop, anInteger.
- reimplemented here for speed

usage example(s):

     #[1 2 3 4 5 6 7 8 9 10] copyFrom:1 to:10
     #[1 2 3 4 5 6 7 8 9 10] copyFrom:5 to:7

     #[1 2 3 4 5 6 7 8 9 10] copyFrom:5 to:11
     #[1 2 3 4 5 6 7 8 9 10] copyFrom:0 to:10
     #[1 2 3 4 5 6 7 8 9 10] copyFrom:0 to:9

shallowCopy

redefined for a bit more speed

symbolFrom: start to: stop

make a symbol from the characters of the subcollection starting
at index start, anInteger and ending at stop, anInteger.
This saves us garbage and character copying.

usage example(s):

     'abcdefghijklmnop' symbolFrom:1 to:3
     'abcdefghijklmnop' symbolFrom:3 to:16
     'abcdefghijklmnop' symbolFrom:3 to:17

filling & replacing

from: start to: stop put: aNumber

fill part of the receiver with aNumber.
- reimplemented here for speed

usage example(s):

     (ByteArray new:10) from:1 to:10 put:1
     (ByteArray new:20) from:10 to:20 put:1
     (ByteArray new:20) from:1 to:10 put:1

image manipulation support

bitAndBytesFrom: dstStart to: dstEnd with: sourceBytes startingAt: sourceStart

replace bytes in the receiver with the result of a bitAnd operation.
Warning: this is a destructive operation - elements in the receiver are overwritten.

usage example(s):

     #[1 2 3 4 5 6 7 8]
	bitAndBytesFrom:1 to:8 with:#[1 2 3 4 5 6 7 8] startingAt:1
     #[1 2 3 4 5 6 7 8]
	bitAndBytesFrom:1 to:8 with:#[1 1 1 1 1 1 1 1] startingAt:1

bitBlitBytesFrom: dstStart to: dstEnd with: sourceBytes startingAt: sourceStart rule: ruleSymbol

perform a special case of an aligned bitBlit operation.
Bytes in the receiver from dstStart to dstEnd are destructively replaced by the result
of some logical operation, as specified by the ruleSymbol.
SourceBytes are fetched starting at sourceOffset.
Valid rule symbols are:
#copy - trivial; same as replaceBytesFrom:to:with:startingAt:
#bitXor: - xoring; byte[dI] = byte[dI] bitXor:(srcByte[sI])
#bitAnd: - anding; byte[dI] = byte[dI] bitAnd:(srcByte[sI])
#bitOr: - oring; byte[dI] = byte[dI] bitOr:(srcByte[sI])
#+ - adding; byte[dI] = (byte[dI] + (srcByte[sI])) mod: 256
#- - subtract; byte[dI] = (byte[dI] - (srcByte[sI])) mod: 256
Warning: this is a destructive operation - elements in the receiver are overwritten.

usage example(s):

     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:3 with:#[1 2 3 4 5 6 7 8] startingAt:1 rule:#bitXor:
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:8 with:#[1 2 3 4 5 6 7 8] startingAt:1 rule:#bitXor:
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:8 with:#[1 1 1 1 1 1 1 1] startingAt:1 rule:#bitAnd:
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:8 with:#[1 2 3 4 5 6 7 8] startingAt:1 rule:#+
     #[255 0 0 0 0 0 0 0]
	bitBlitBytesFrom:1 to:8 with:#[1 2 3 4 5 6 7 8] startingAt:1 rule:#+
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:4 with:#[1 1 1 1 1 1 1 1] startingAt:1 rule:#+
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:4 with:#[1 1 1 1 2 2 2 2] startingAt:5 rule:#+
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:4 with:#[1 1 1 1 2 2 2 2] startingAt:5 rule:#copyNot

     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:8 with:(1 to:8) startingAt:1 rule:#+

bitBlitBytesFrom: dstStart to: dstEnd withConstant: sourceByte rule: ruleSymbol

perform a special case of an aligned bitBlit operation.
Bytes in the receiver from dstStart to dstEnd are destructively replaced by the result
of some logical operation, as specified by the ruleSymbol.
Valid rule symbols are:
#copy - trivial; same as from:to:put:
#bitXor: - xoring; byte[dI] = byte[dI] bitXor:sourceConst
#bitAnd: - anding; byte[dI] = byte[dI] bitAnd:sourceConst
#bitOr: - oring; byte[dI] = byte[dI] bitOr:sourceConst
#+ - adding; byte[dI] = (byte[dI] + sourceConst) mod: 256
#- - subtract; byte[dI] = (byte[dI] - sourceConst) mod: 256
Warning: this is a destructive operation - elements in the receiver are overwritten.

usage example(s):

     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:3 withConstant:1 rule:#bitXor:
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:8 withConstant:1 rule:#bitXor:
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:8 withConstant:1 rule:#bitAnd:
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:8 withConstant:1 rule:#+
     #[255 0 0 0 0 0 0 0]
	bitBlitBytesFrom:1 to:8 withConstant:1 rule:#+
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:4 withConstant:1 rule:#+
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:4 withConstant:1 rule:#-
     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:4 withConstant:1 rule:#copyNot

     #[1 2 3 4 5 6 7 8]
	bitBlitBytesFrom:1 to:8 withConstant:1 rule:#+

bitOrBytesFrom: dstStart to: dstEnd with: sourceBytes startingAt: sourceStart

replace bytes in the receiver with the result of a bitOr operation.
Warning: this is a destructive operation - elements in the receiver are overwritten.

usage example(s):

     #[1 2 3 4 5 6 7 8]
	bitOrBytesFrom:1 to:8 with:#[1 2 3 4 5 6 7 8] startingAt:1
     #[1 2 3 4 5 6 7 8]
	bitOrBytesFrom:1 to:8 with:#[1 1 1 1 1 1 1 1] startingAt:1

bitXorBytesFrom: dstStart to: dstEnd with: sourceBytes startingAt: sourceStart

replace bytes in the receiver with the result of an bitXor operation.
Warning: this is a destructive operation - elements in the receiver are overwritten.

usage example(s):

     #[1 2 3 4 5 6 7 8]
	bitXorBytesFrom:1 to:3 with:#[1 2 3 4 5 6 7 8] startingAt:1
     #[1 2 3 4 5 6 7 8]
	bitXorBytesFrom:1 to:8 with:#[1 2 3 4 5 6 7 8] startingAt:1
     #[1 2 3 4 5 6 7 8]
	bitXorBytesFrom:1 to:8 with:#[1 1 1 1 1 1 1 1] startingAt:1

compressPixels: nBitsPerPixel width: width height: height into: aByteArray mapping: aMapByteArray

given the receiver with 8-bit pixels, compress them into aByteArray
with nBitsPerPixel-depth pixels. The width/height-arguments are needed
to allow for any padding. On the fly, the source bytes are translated
using aMapByteArray (if non-nil).
Notice that smalltalk indexing begins at 1; thus the map-index for a byte
value of n is found in map at:(n + 1).
Output bits are filled left-to right, i.e. the first byte in the input
corresponds to the high bit(s) if the first byte in the input.
This method can be used to convert 8-bit image data to mono, 2-bit and 4-bit
bitmaps.
It can also be used to compress byte-arrays into bitArrays.

expandPixels: nBitsPerPixel width: width height: height into: aByteArray mapping: aMapByteArray

given the receiver with nBitsPerPixel-depth pixels, expand them into
aByteArray with 8-bit pixels. The width/height-arguments are needed
to skip any padded src-bits. On the fly, the destination pixels
are translated using aMapByteArray (if non-nil).
Input bits are read left-to right, i.e. the first byte in the output
corresponds to the high bit(s) in the inputs first byte.
This is used to display mono, 2-bit and 4-bit bitmaps on grey-scale/color
machines. With nBitsPerPixel==8, this is a translate operation.
Notice that smalltalk indexing begins at 1; thus the map-index for a byte
value of n is found in map at:(n + 1).
It can also be used to expand bit-arrays into byteArrays.
This method is specialized for ByteArray arguments - it will not handle
anything else.

invert

invert all bytes inplace - used with image manipulations
written as a primitive for speed.
Warning: destructive; modifies the receiver - not a copy.
Q: is this really needed ?

usage example(s):

     #[1 2 3 4 5 6 7 8 9 10] copy invert
     #[1 2 3 4 5 6 7 8 9 10] copy
        bitBlitBytesFrom:1 to:10 withConstant:16rFF rule:#bitXor:

     |l|
     l := ByteArray fromHexString:'0102030405060708090a0b0c0d0e0f1112131415161718191a1b1c1d1e1f'.
     Time millisecondsToRun:[
        1000000 timesRepeat:[ l invert ].
     ]

reverse

reverse the order of my elements inplace -
WARNING: this is a destructive operation, which modifies the receiver.
Please use reversed (with a 'd' at the end) for a functional version.
Written as a primitive for speed on image manipulations (mirror)

usage example(s):

     #[1 2 3 4 5] copy reverse
     #[] copy reverse
     #[1] copy reverse
     #[1 2] copy reverse
     #[1 2 3] copy reverse
     #[1 2 3 4] copy reverse
     #[1 2 3 4 5] copy reverse
     #[1 2 3 4 5 6] copy reverse
     #[1 2 3 4 5 6 7] copy reverse
     #[1 2 3 4 5 6 7 8] copy reverse
     #[1 2 3 4 5 6 7 8] copy reverseFrom:2 to:5
     #[1 2 3 4 5 6 7 8 9] copy reverse
     #[1 2 3 4 5 6 7 8 9 10] copy reverse
     #[1 2 3 4 5 6 7 8 9 10 11 12] copy reverse
     #[1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16] copy reverse
     #[1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20] copy reverse
     (1 to:255) asByteArray reverse

     1 to:1024 do:[:i|
        |bytes test rBytes|

        bytes := ((1 to:i) asArray collect:[:i | i bitAnd:255]) asByteArray.
        test := ((i to:1 by:-1) asArray collect:[:i | i bitAnd:255]) asByteArray.
        rBytes := bytes copy.
        rBytes reverse ~= test ifTrue:[
            self halt
        ].
        rBytes := bytes copy.
        rBytes reverse reverse ~= bytes ifTrue:[
            self halt
        ]
     ].

     Time millisecondsToRun:[
        10000000 timesRepeat:[
            #[1 2 3 4 5 6 7 8] reverse
        ]
     ]

     |b|
     b := (0 to:255) asByteArray.
     Time millisecondsToRun:[
        10000000 timesRepeat:[
            b reverse
        ]
     ]

swap: i1 with: i2

spap the bytes at i1 and i2

swapBytes

swap bytes (of int16s) inplace -
Expects that the receiver has an even number of bytes;
if not, only the pairs excluding the last byte are swapped.
written as a primitive for speed on image grabbing (if display order is different).

usage example(s):

     #[1 2 3 4 5 6 7 8 9 10] copy swapBytes     -> #[2 1 4 3 6 5 8 7 10 9]
     #[1 2 3 4 5 6 7 8 9 10 11] copy swapBytes  -> #[2 1 4 3 6 5 8 7 10 9 11]
     #[1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18] copy swapBytes

swapLongs

swap long bytes inplace
- any partial longs at the end are not swapped.

usage example(s):

     #[1 2 3 4 5 6 7 8 9] copy swapLongs
     #[1 2 3 4 5 6 7 8 9 10] copy swapLongs
     #[1 2 3 4 5 6 7 8 9 10 11] copy swapLongs
     #[1 2 3 4 5 6 7 8 9 10 11 12] copy swapLongs

swapLongsFrom: startIndex to: endIndex

swap longs (int32s) inplace
- any partial longs at the end are not swapped.
Swapping is from startIndex to (exclusiv) endIndex;
indexing starts at 1.

usage example(s):

     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:3
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:4
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:5
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:6
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:7
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:8
     #[1 2 3 4 5 6 7 8 9 10] copy swapLongsFrom:1 to:11
     #[1 2 3 4 5 6 7 8 9 10 11] copy swapLongsFrom:1 to:12
     #[1 2 3 4 5 6 7 8 9 10 11 12] copy swapLongsFrom:1 to:13
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:5 to:10

inspecting

inspectorExtraAttributes
( an extension from the stx:libtool package ): extra (pseudo instvar) entries to be shown in an inspector.
inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package ): returns a string to be shown in the inspector's list

printing & storing

displayOn: aGCOrStream

return a printed representation of the receiver for displaying

printOn: aStream

append a printed representation to aStream

usage example(s):

     #[1 2 3 4 5] printOn:Transcript


     #[1 2 3 4 5] storeString
     #[1 2 3 4 5] displayString
     #[1 2 3 4 5] printString

printOn: aStream base: radix

append a printed representation to aStream in the given number base.

usage example(s):

     #[1 2 3 4 5] printOn:Transcript base:2
     'Hello World' printOn:Transcript base:2

     #[1 2 3 4 5] storeString
     #[1 2 3 4 5] displayString
     #[1 2 3 4 5] printString

printOn: aStream base: radix showRadix: showRadix

append a printed representation to aStream in the given number base.

usage example(s):

     #[1 2 3 4 5] printOn:Transcript base:2
     'Hello World' printOn:Transcript base:2

     #[1 2 3 4 5] storeString
     #[1 2 3 4 5] displayString
     #[1 2 3 4 5] printString

storeOn: aStream

append a printed representation from which the receiver can be
reconstructed to aStream. (reimplemented to make it look better)

usage example(s):

     #[1 2 3 4 5] storeOn:Transcript

     #[1 2 3 4 5] storeString
     #[1 2 3 4 5] displayString
     #[1 2 3 4 5] printString

queries

characterSize

answer the size in bits of my largest character (actually only 7, 8, 16 or 32).
Needed in case someone writes bytes to a CharacterWriteStream (comanche response)

containsNon7BitAscii

return true, if any byte in the receiver has the 7th bit on.
This my look as a too specific operation to be put here,
put it is very helpful for UTF8 string reading (Java class reader),
to quickly determine, if UTF8 decoding is needed or not.
As most strings in a class file are in fact only containing 7bit ascii,
this should speedup class file reading considerably

usage example(s):

     #[1 2 3 1 2 3 1 2 127 ] containsNon7BitAscii
     #[1 2 3 1 2 3 1 2 250 251 250 251 255] containsNon7BitAscii

containsNon8BitElements

return true, if one of my elements is larger than a single byte.
Per definition not.

isEmpty

return true if the receiver is empty (i.e. if size == 0)
Redefined here for performance

isValidElement: anObject

return true, if I can hold this kind of object

max

return the maximum value in the receiver -
redefined to speedup image processing and sound-player
(which need a fast method for this on byteArrays)

usage example(s):

     #[1 2 3 1 2 3 1 2 19] max
     #[] max

notEmpty

return true if the receiver is not empty (i.e. if size ~~ 0)
Redefined here for performance

startsWith: aByteOrByteArray

return true, if the receiver starts with something, aStringOrChar.
If the argument is empty, true is returned.
Notice, that this is similar to, but slightly different from VW's and Squeak's beginsWith:,
which are both inconsistent w.r.t. an empty argument.

usage example(s):

     #[1 2 3 4 5 6 7 8 9 10] startsWith:#[ 1 2 3 4 5]
     #[1 2 3 4] startsWith:#[ 1 3 4 5]
     #[1 2 3 4 5 6 7 8 9 10] startsWith:#[ 0 1 2 3 4 5]
     #[1 2 3 4 5 6 7 8 9 10] startsWith:#(1 2 3 4 5)
     #[1 2 3 4 5 6 7 8 9 10] startsWith:1
     #[1 2 3 4 5 6 7 8 9 10] startsWith:2

usageCounts

return an array filled with value-counts -
This is needed in the bitmap/image classes to get info on color usage.
(i.e. to build up a histogram of color usage within an image).

usage example(s):

     #[1 2 3 1 2 3 1 2 250 251 250 251 255] usageCounts

usedValues

return a new ByteArray with all used values (actually a kind of Set);
This is needed specially in the bitmap/Imageclasses to find used colors
of an image.

usage example(s):

     #[1 2 3 1 2 3 1 2 3 1 2 3 4 5 6 4 5 6] usedValues

searching

indexOf: aByte startingAt: start

return the index of the first occurrence of the argument, aByte
in the receiver starting at start, anInteger; return 0 if not found.
- reimplemented here for speed

usage example(s):

     #[1 2 3 4 5 6 7 8 9 0 1 2 3 4 5] indexOf:0 startingAt:1

testing

isByteArray: return true, if the receiver is some kind of bytearray;
true is returned here - the method is redefined from Object.
isIntegerArray: return true if the receiver has integer elements.
These are Byte- and Integer arrays; both signed and unsigned
isLiteral: return true, if the receiver can be used as a literal constant in ST syntax
(i.e. can be used in constant arrays)

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Wed, 24 Apr 2024 07:57:29 GMT

Smalltalk/X Webserver

Documentation of class 'ByteArray':

Class: ByteArray

Inheritance:

Description:

Warning:

Related information:

Class protocol:

Instance protocol: