Class: ByteArray

• Inheritance
• Description
• Warning
• Related information
• Class protocol
  • binary storage
  • instance creation
  • queries
• Instance protocol
  • Compatibility-Squeak
  • Compatibility-VW
  • accessing
  • accessing-bytes
  • accessing-longs
  • accessing-shorts
  • binary storage
  • comparing
  • converting
  • copying
  • filling & replacing
  • image manipulation support
  • inspecting
  • printing & storing
  • queries
  • searching
  • testing

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--ByteArray
                  |
                  +--CharacterArray
                  |
                  +--ImmutableByteArray
                  |
                  +--UUID
                  |
                  +--Win32FileDialog::OpenFilenameStructure

Package:

stx:libbasic

Category:

Collections-Arrayed

Version:

rev: 1.201 date: 2010/04/14 08:33:59

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.
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 a companion class (Structure) in the goodies directory.
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:

 binaryDefinitionFrom: stream manager: manager

get a ByteArray from the binary stream.
ByteArrays are stored as 4-byte size, followed by the bytes.
This is only invoked for long bytearrays.
Short ones are stored with 1byte length.

 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.

 isBuiltInClass

return true if this class is known by the run-time-system.
Here, true is returned for myself, false for subclasses.

Instance protocol:

 bitXor: aByteArray

return a new byteArray containing the bitWise-xor of the receiver's and the
argument's bytes

 asByteString

 basicAt: index

return the indexed instance variable with index, anInteger
- redefined here to be slighly faster than the default in Object.
Q: is it worth the extra code ?

 basicAt: index put: value

set the indexed instance variable with index, anInteger to value.
Returns value (sigh).
- redefined here to be slighly faster than the default in Object.
Q: is it worth the extra code ?

 bitAt: index

return the bit at index (1 based index) as 0 or 1

 bitClearAt: index

clear the bit at index (index starts with 1)

 bitSetAt: index

set the bit at index (index starts with 1)

 byteAt: index

return the byte at index.
For ByteArray, this is the same as basicAt:;
however, for strings or symbols, this returns a numeric byteValue
instead of a character.

 byteAt: index put: value

set the byte at index. For ByteArray, this is the same as basicAt:put:.
However, for Strings, this expects a byteValue to be stored.

 doubleWordAt: index put: value

set the 4-bytes starting at index from the (unsigned) Integer value.
The value should be in the range 0 to 16rFFFFFFFF
(for negative values, the stored value is not defined).
The value is stored in the machines natural byte order.
Q: should it store signed values ? (see ByteArray signedDoubleWordAt:put:)

 doubleWordAt: index put: value MSB: msb

set the 4-bytes starting at index from the (unsigned) Integer value.
The value must be in the range 0 to 16rFFFFFFFF.
The value is stored MSB-first if msb is true; LSB-first otherwise.
question: should it store signed values ? (see ByteArray signedDoubleWordAt:put:)

 wordAt: index

return the 2-bytes starting at index as an (unsigned) Integer.
The value is retrieved in the machines natural byte order
Question: should it be retrieve signed values ? (see ByteArray>>signedWordAt:)

 wordAt: index MSB: msb

return the 2-bytes starting at index as an (unsigned) Integer.
The value is retrieved MSB (high 8 bits at lower index) if msb is true;
LSB-first (i.e. low 8-bits at lower byte index) if its false.
Question: should it be retrieve signed values ? (see ByteArray>>signedWordAt:)

 wordAt: index put: value

set the 2-bytes starting at index from the (unsigned) Integer value.
The stored value must be in the range 0 .. 16rFFFF.
The value is stored in the machines natural byteorder,
i.e. this method should only be used to fill byteArrays which are
used internally (not passed to other machines).
Question: should it accept signed values ? (see ByteArray>>signedWordAt:put:)

 wordAt: index put: value MSB: msb

set the 2-bytes starting at index from the (unsigned) Integer value.
The stored value must be in the range 0 .. 16rFFFF.
The value is stored LSB-first (i.e. the low 8bits are stored at the
lower index) if msb is false, MSB-first otherwise.
Question: should it accept signed values ? (see ByteArray>>signedWordAt:put:)

 storeBinaryDefinitionOn: stream manager: manager

append a binary representation of the receiver onto stream.
Redefined since short ByteArrays can be stored with a special type code
in a more compact way.
This is an internal interface for the binary storage mechanism.

 storeBinaryElementsOn: aStream

 = aByteArray

Compare the receiver with the argument and return true if the
receiver is equal to the argument (i.e. has the same size and elements).
Otherwise return false.

 asByteArray

return the receiver as a byteArray

 asImmutableByteArray

return a write-protected copy of myself

 asInteger

convert myself to an integer - the first byte is most significant.
This is also in Squeak.

 asIntegerMSB: isMSBFirst

convert myself to an integer - the first byte is most significant.
This is also in Squeak.

 asPackedString

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 very similar (but not equal) to the algorithm used in RFC1421.
PS: I dont like it ;-)

 asString

speed up string conversions

 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.

 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

 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.

 from: start to: stop put: aNumber

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

 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.

 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.

 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.

 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.

 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.

 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 - used with image manipulations
written as a primitive for speed.
Q: is this really needed ?

 reverse

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

 swapBytes

swap bytes inplace -
written as a primitive for speed on image grabbing (if display order is different)

 swapIndex: i1 and: i2

spap the bytes with i1 and i2

 swapLongs

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

 swapLongsFrom: startIndex to: endIndex

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

 inspectorExtraAttributes

extra (pseudo instvar) entries to be shown in an inspector.

 displayString

return a printed representation of the receiver for displaying

 hexPrintOn: aStream

print as hex string, eg: 'FF0243'.
This string can be used in #fromHexString: to recreate the byteArray

 hexPrintOn: aStream withSeparator: aSeparatorStringOrCharacter

print as hex string, eg: 'FF:02:43'

 hexPrintString

print as hex string, eg: 'FF0243'.
This string can be used in #fromHexString: to recreate the byteArray

 hexPrintStringWithSeparator: aSeparatorStringOrCharacter

print as hex string, eg: 'FF:02:43'.

 printOn: aStream

append a printed representation to aStream

 printOn: aStream base: radix

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

 printOn: aStream base: radix showRadix: showRadix

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

 storeArrayElementOn: aStream

Store as element of an array. Omit the leading '#'

 storeOn: aStream

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

 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)

 referencesAny: aCollection

redefined to speed up searching when many byteArray instances are present

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

 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.

 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

 isByteArray

return true, if the receiver is some kind of bytearray;
true is returned here - the method is redefined from Object.

 isLiteral

return true, if the receiver can be used as a literal constant in ST syntax
(i.e. can be used in constant arrays)