Class: UninterpretedBytes

• Inheritance
• Description
• Related information
• Class protocol
  • instance creation
  • queries
• Instance protocol
  • Compatibility-Squeak
  • Compatibility-V'Age
  • accessing-bytes
  • accessing-floats & doubles
  • accessing-longlongs
  • accessing-longs
  • accessing-shorts
  • accessing-strings
  • filling & replacing
  • hashing
  • image manipulation support
  • misc
  • private
  • queries
  • testing
  • visiting

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--ByteArray
               |
               +--ExternalBytes
               |
               +--SocketAddress

Package:

stx:libbasic

Category:

Collections-Abstract

Version:

rev: 1.76 date: 2010/03/08 07:42:57

user: stefan

file: UninterpretedBytes.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

UninterpretedBytes provides the common protocol for byte-storage 
containers; concrete subclasses are 
    ByteArray (which store the bytes within the
               Smalltalk object memory) 
and 
    ExternalBytes (which store the bytes in the malloc-heap).

UninterpretedBytes itself is abstract, so no instances of it can be created.



[Notice:]
    Notice the confusion due to multiple methods with the same
    functionality (i.e. 'xxxx:MSB:' vs. 'xxxx:bigEndian:').
    The reason is that at the time this class was written,
    ST80 sid not offer protocol to specify the byteOrder, and
    ST/X provided methods ending in 'MSB:' for this.
    In the meanwhile, VW added protocol ending in 'bigEndian:',
    which has been added here for compatibility.
    (certainly a point, where an ansi-standard will help)

Related information:

    ByteArray
    String
    ExternalBytes

Class protocol:

 from: aByteArray

return new instance which is a copy of aByteArray

 fromHexString: aString

Dolphin compatibility:
decode a byteArray from a hex string (as generated by hexPrintOn:)

 fromHexStringWithSeparators: aString

read a bytearray from a printed string representation, where
individual bytes are encoded as two hex digits, optionally separated by whiteSpace.
See also fromHexString:, which does something similar, but does not allow for spaces

 fromPackedString: aString

ST-80 compatibility: decode a byteArray from a packed string in which
6bits are encoded per character. The argument, aString must be a multiple
of 4 in size (since 24 is the lcm of 6 and 8). This is somewhat like
the radix-encoding used in good old PDP11 times ;-)
ST-80 uses this encoding for Images ...
This is very similar (but not equal) to the algorithm used in RFC1421.
PS: It took a while to figure that one out ... I dont like it ;-)

 with: aByteArray from: start to: stop

return new instance with a copy of aByteArray
beginning at index start up to and including index stop

 isAbstract

Return if this class is an abstract class.
True is returned for UninterpretedBytes here; false for subclasses.
Abstract subclasses must redefine again.

 isBigEndian

return true, if words/shorts store the most-significant
byte first (MSB), false if least-sign.-first (LSB).
I.e. false for vax, intel; true for m68k, sun.

Notice: UninterpretedBytes isBigEndian
this is inlined both by stc and the jit compiler

 isBuiltInClass

return true if this class is known by the run-time-system.
Here, true is returned, since UninterpretedBytes is the superclass of
some builtIn classes (ByteArray & ExternalBytes)

Instance protocol:

 copyFromByteArray: aByteArray

copy as much as possible from aByteArray

 uint32At: zeroBasedIndex

return the 4-bytes starting at index as (unsigned) Integer.
The index is a C index (i.e. 0-based).
The value is retrieved in the machines natural byte order.
Similar to unsignedLongAt:, except for the index base

 uint32At: zeroBasedIndex put: anInteger

set the 4-bytes starting at index to the value given by (unsigned) Integer.
The index is a C index (i.e. 0-based).
The value is stored in the machines natural byte order.
Similar to unsignedLongAt:put:, except for the index base

 bcdByteAt: index

return the bcd-value for a byte at index.

 bcdByteAt: index put: aNumber

set the byte at index as bcd-value.

 signedByteAt: index

return the byte at index as a signed 8 bit value.
The index is a smalltalk index (i.e. 1-based).
This may be worth a primitive.

 signedByteAt: index put: aSignedByteValue

return the byte at index as a signed 8 bit value.
The index is a smalltalk index (i.e. 1-based).
Return the signedByteValue argument.
This may be worth a primitive.

 doubleAt: index

return the 8-bytes starting at index as a Float.
The index is a smalltalk index (i.e. 1-based).
Notice, that (currently) ST/X Floats are what Doubles are in ST-80.
Notice also, that the bytes are expected to be in this machines
float representation - if the bytearray originated from another
machine, some conversion is usually needed.

 doubleAt: index MSB: msb

return the 8-bytes starting at index as a Float.
The index is a smalltalk index (i.e. 1-based).
Notice, that (currently) ST/X Floats are what Doubles are in ST-80.
Notice also, that the bytes are expected to be in this machines
float representation - if the bytearray originated from another
machine, some conversion is usually needed.

 doubleAt: index put: aFloat

store the value of the argument, aFloat into the receiver
starting at index.
The index is a smalltalk index (i.e. 1-based).
Notice, that (currently) ST/X Floats are what Doubles are in ST-80.
Notice also, that the bytes are expected to be in this machines
float representation - if the bytearray originated from another
machine, some conversion is usually needed.

 doubleAt: index put: aFloat MSB: msb

store the value of the argument, aFloat into the receiver
starting at index.
The index is a smalltalk index (i.e. 1-based).
Notice, that (currently) ST/X Floats are what Doubles are in ST-80.
Notice also, that the bytes are expected to be in this machines
float representation - if the bytearray originated from another
machine, some conversion is usually needed.

 floatAt: index

return the 4-bytes starting at index as a ShortFloat.
The index is a smalltalk index (i.e. 1-based).
Notice, that (currently) ST/X Floats are what Doubles are in ST-80;
therefore this method reads a 4-byte float from the byteArray and returns
a float object which keeps an 8-byte double internally.
Notice also, that the bytes are expected to be in this machines
float representation and order - if the bytearray originated from another
machine, some conversion is usually needed.

 floatAt: index MSB: msb

return the 4-bytes starting at index as a ShortFloat.
The index is a smalltalk index (i.e. 1-based).
Notice, that (currently) ST/X Floats are what Doubles are in ST-80;
therefore this method reads a 4-byte float from the byteArray and returns
a float object which keeps an 8-byte double internally.
Notice also, that the bytes are expected to be in this machines
float representation and order - if the bytearray originated from another
machine, some conversion is usually needed.

 floatAt: index put: aFloat

store the 4 bytes of value of the argument, aFloat into the receiver
starting at index.
The index is a smalltalk index (i.e. 1-based).
Notice, that (currently) ST/X Floats are what Doubles are in ST-80.
Notice also, that the bytes are expected to be in this machines
float representation - if the bytearray originated from another
machine, some conversion is usually needed.

 floatAt: index put: aFloat MSB: msb

store the 4 bytes of value of the argument, aFloat into the receiver
starting at index.
The index is a smalltalk index (i.e. 1-based).
Notice, that (currently) ST/X Floats are what Doubles are in ST-80.
Notice also, that the bytes are expected to be in this machines
float representation - if the bytearray originated from another
machine, some conversion is usually needed.

 ieeeDoubleAt: index

retrieve the 8 bytes starting at index as a float.
The index is a smalltalk index (i.e. 1-based).
The 8 bytes are assumed to be in IEEE floating point single precision
number format.

 ieeeDoubleAt: index put: aFloat

store the value of the argument, aFloat into the receiver
The index is a smalltalk index (i.e. 1-based).
starting at index. Storage is in IEEE floating point double precision format.
(i.e. 8 bytes are stored).

 ieeeFloatAt: index

retrieve the 4 bytes starting at index as a float.
The index is a smalltalk index (i.e. 1-based).
The 4 bytes are assumed to be in IEEE floating point single precision
number format.

 ieeeFloatAt: index put: aFloat

store the value of the argument, aFloat into the receiver
starting at index, which is a smalltalk index (i.e. 1-based).
Storage is in IEEE floating point single precision format.
(i.e. 4 bytes are stored). Since ST/X floats are really doubles, the low-
order 4 bytes of the precision is lost.

 longLongAt: index

return the 8-bytes starting at index as a signed Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machines natural byte order.
This may be worth a primitive.

 longLongAt: index bigEndian: msb

return the 8-bytes starting at index as a signed Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the given byte order.
This may be worth a primitive.

 longLongAt: byteIndex put: anInteger

store a signed longLong (64bit) integer.
The index is a smalltalk index (i.e. 1-based).
Same as #signedQuadWordAt:put: - for ST80 compatibility.

 longLongAt: byteIndex put: anInteger bigEndian: msb

store a signed longLong (64bit) integer.
The index is a smalltalk index (i.e. 1-based).
Same as #signedQuadWordAt:put: - for ST80 compatibility.

 quadWordAt: index MSB: msb

return the 8-bytes starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
Depending on msb, the value is retrieved MSB or LSB-first.

 quadWordAt: index put: anInteger MSB: msb

set the 8-bytes starting at index from the (unsigned) Integer value.
The index is a smalltalk index (i.e. 1-based).
The value must be in the range 0 to 16rFFFFFFFFFFFFFFFF.
Depending on msb, the value is stored MSB-first or LSB-first.

 unsignedLongLongAt: index bigEndian: msb

return the 8-bytes starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
Depending on msb, the value is retrieved MSB or LSB-first.

 unsignedLongLongAt: index put: anInteger

set the 8-bytes starting at index from the (unsigned) Integer value.
The index is a smalltalk index (i.e. 1-based).
The value must be in the range 0 to 16rFFFFFFFFFFFFFFFF.
The value is stored in natural byte order.

 unsignedLongLongAt: index put: anInteger bigEndian: msb

set the 8-bytes starting at index from the (unsigned) Integer value.
The index is a smalltalk index (i.e. 1-based).
The value must be in the range 0 to 16rFFFFFFFFFFFFFFFF.
Depending on msb, the value is stored MSB-first or LSB-first.

 doubleWordAt: index

return the 4-bytes starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machines natural byte order.

 doubleWordAt: index MSB: msb

return the 4-bytes starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved MSB-first, if the msb-arg is true;
LSB-first otherwise.

 doubleWordAt: index put: value

set the 4-bytes starting at index from the (unsigned) Integer value.
The index is a smalltalk index (i.e. 1-based).
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.

 doubleWordAt: index put: aNumber MSB: msb

set the 4-bytes starting at index from the (unsigned) Integer value.
The index is a smalltalk index (i.e. 1-based).
The value must be in the range 0 to 16rFFFFFFFF.
The value is stored MSB-first if msb is true; LSB-first otherwise.

 doubleWordAtDoubleWordIndex: index

return the unsigned long at index, anInteger.
Fetching in the machines natural byte order.
Indices are 1-based and scaled as appropriate to allow
accessing the memory as an array of doubleWord entries.
(i.e. indices are 1, 2, ...)

 doubleWordAtDoubleWordIndex: index MSB: msb

return the unsigned long at index, anInteger.
Fetching is MSB if msb is true, LSB otherwise.
Indices are 1-based and scaled as appropriate to allow
accessing the memory as an array of doubleWord entries.
(i.e. indices are 1, 2, ...)

 doubleWordAtDoubleWordIndex: index put: value

set the long at index, anInteger.
Storing in the machines natural byte order.
Indices are 1-based and scaled as appropriate to allow
accessing the memory as an array of doubleWord entries.
(i.e. indices are 1, 2, ...)

 doubleWordAtDoubleWordIndex: index put: value MSB: msb

set the long at index, anInteger.
Storing is MSB if msb is true, LSB otherwise.
Indices are 1-based and scaled as appropriate to allow
accessing the memory as an array of doubleWord entries.
(i.e. indices are 1, 2, ...)

 longAt: index

return the 4-bytes starting at index as a signed Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machines natural byte order,
therefore, this should only be used for byte-data which is
only used inside this machine.
To setup data packets which are to be sent to other machines,
or stored into a file, always use longAt:MSB: and specify
a definite byteOrder.

 longAt: index bigEndian: msb

return the 4-bytes starting at index as a signed Integer.
The index is a smalltalk index (i.e. 1-based).
Depending on msb, the value is retrieved MSB-first or LSB-first.
This may be worth a primitive.

 longAt: index put: value

set the 4-bytes starting at index from the signed Integer value.
The index is a smalltalk index (i.e. 1-based).
The value is stored in the machines natural byte order.
This may be worth a primitive.

This is the ST80 version of #signedDoubleWordAt:put:

 longAt: byteIndex put: anInteger bigEndian: msb

store a signed long (32bit) integer.
The index is a smalltalk index (i.e. 1-based).
Same as #signedQuadWordAt:put: - for ST80 compatibility.

 pointerAt: index

get a pointer starting at index as ExternalAddress.
The index is a smalltalk index (i.e. 1-based).
Only aligned accesses are allowed.

 pointerAt: index put: value

set the pointer starting at index from the signed Integer value.
The index is a smalltalk index (i.e. 1-based).
Only aligned accesses are allowed.
The value is either an ExternalAddress or ExternalBytes

 signedDoubleWordAt: index

return the 4-bytes starting at index as a signed Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machines natural byte order.
This may be worth a primitive.

 signedDoubleWordAt: index MSB: msb

return the 4-bytes starting at index as a (signed) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved MSB-first, if the msb-arg is true;
LSB-first otherwise.

 signedDoubleWordAt: index put: value

set the 4-bytes starting at index from the signed Integer value.
The index is a smalltalk index (i.e. 1-based).
The value is stored in the machines natural byte order.
This may be worth a primitive.

 signedDoubleWordAt: index put: value MSB: msb

set the 4-bytes starting at index from the signed Integer value.
The index is a smalltalk index (i.e. 1-based).
Depending on msb, the value is stored MSB-first or LSB-first.
This may be worth a primitive.

 unsignedLongAt: index

return the 4-bytes starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machines natural byte order.
Subclasses may redefine this for better performance.
Same as doubleWordAt: for protocol completeness

 unsignedLongAt: index bigEndian: msb

return the 4-bytes starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved MSB-first, if the msb-arg is true;
LSB-first otherwise.
Subclasses may redefine this for better performance.
Same as doubleWordAt:MSB: for protocol completeness

 unsignedLongAt: index put: value

set the 4-bytes starting at index from the (unsigned) Integer value.
The index is a smalltalk index (i.e. 1-based).
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.
Subclasses may redefine this for better performance.
Same as doubleWordAt:put: for protocol completeness

 unsignedLongAt: index put: aNumber bigEndian: msb

set the 4-bytes starting at index from the (unsigned) Integer value.
The index is a smalltalk index (i.e. 1-based).
The value must be in the range 0 to 16rFFFFFFFF.
The value is stored MSB-first if msb is true; LSB-first otherwise.
Subclasses may redefine this for better performance.
Same as doubleWordAt:put:MSB: for protocol completeness

 shortAt: index

return the 2-bytes starting at index as a signed Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machines natural byte order.
This may be worth a primitive.
This is the ST80 equivalent of #signedWordAt:

 shortAt: index bigEndian: msb

return the 2-bytes starting at index as a signed Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved MSB-first, if the msb-arg is true;
LSB-first otherwise.
This is the ST80 equivalent of #signedWordAt:

 shortAt: index put: value

set the 2-bytes starting at index from the signed Integer value.
The index is a smalltalk index (i.e. 1-based).
The stored value must be in the range -32768 .. +32676.
The value is stored in the machines natural byteorder.
This may be worth a primitive.
This is the ST80 equivalent of #signedWordAt:put:

 shortAt: index put: value bigEndian: bigEndian

set the 2-bytes starting at index from the signed Integer value.
The index is a smalltalk index (i.e. 1-based).
The stored value must be in the range -32768 .. +32676.
The value is stored in the byteorder given by bigEndian.
This may be worth a primitive.

 signedWordAt: index

return the 2-bytes starting at index as a signed Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machines natural byte order.
This may be worth a primitive.

 signedWordAt: index MSB: msb

return the 2-bytes starting at index as a signed Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved MSB-first if the msb-arg is true,
LSB-first otherwise.
This may be worth a primitive.

 signedWordAt: index put: value

set the 2-bytes starting at index from the signed Integer value.
The index is a smalltalk index (i.e. 1-based).
The stored value must be in the range -32768 .. +32676.
The value is stored in the machines natural byteorder.
This may be worth a primitive.
This is the ST80 equivalent of #signedWordAt:put:

 signedWordAt: index put: value MSB: msb

set the 2-bytes starting at index from the signed Integer value.
The index is a smalltalk index (i.e. 1-based).
The stored value must be in the range -32768 .. +32676.
The value is stored MSB-first, if the msb-arg is true;
LSB-first otherwise.
This may be worth a primitive.

 unsignedShortAt: index

return the 2-bytes starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machines natural byte order
Subclasses may redefine this for better performance.
This is the ST80 equivalent of #wordAt:

 unsignedShortAt: index bigEndian: msb

return the 2-bytes starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved MSB-first (high 8 bits at lower index) if msb is true;
LSB-first (i.e. low 8-bits at lower byte index) if its false)

 unsignedShortAt: index put: value

set the 2-bytes starting at index from the (unsigned) Integer value.
The index is a smalltalk index (i.e. 1-based).
The stored value must be in the range 0 .. 16rFFFF.
The value is stored in the machines natural byteorder.

 unsignedShortAt: index put: value bigEndian: msb

set the 2-bytes starting at index from the (unsigned) Integer value.
The index is a smalltalk index (i.e. 1-based).
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

 wordAt: index

return the 2-bytes starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machines natural byte order
Subclasses may redefine this for better performance.

 wordAt: index MSB: msb

return the 2-bytes starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
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 index is a smalltalk index (i.e. 1-based).
The stored value must be in the range 0 .. 16rFFFF.
The value is stored in the machines natural byteorder.
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 index is a smalltalk index (i.e. 1-based).
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:)

 wordAtWordIndex: index

return the unsigned short at index, anInteger.
Fetching in the machines natural byte order.
Indices are 1-based and scaled as appropriate to allow
accessing the memory as an array of word entries.
(i.e. indices are 1, 2, ...)

 wordAtWordIndex: index MSB: msb

return the unsigned short at index, anInteger.
Fetching is MSB if msb is true, LSB otherwise.
Indices are 1-based and scaled as appropriate to allow
accessing the memory as an array of word entries.
(i.e. indices are 1, 2, ...)

 wordAtWordIndex: index put: value

set the short at index, anInteger.
Storing in the machines natural byte order.
Indices are 1-based and scaled as appropriate to allow
accessing the memory as an array of word entries.
(i.e. indices are 1, 2, ...)

 wordAtWordIndex: index put: value MSB: msb

set the short at index, anInteger.
Storing is MSB if msb is true, LSB otherwise.
Indices are 1-based and scaled as appropriate to allow
accessing the memory as an array of word entries.
(i.e. indices are 1, 2, ...)

 stringAt: index

return a string starting at index up to the 0-byte.
The index is a smalltalk index (i.e. 1-based).

 stringAt: index put: aString

copy aString to the externalBytes, starting at index up to
(and including) the 0-byte (which is always written).
The index is a smalltalk index (i.e. 1-based).

 stringAt: index put: aString size: maxSize

copy aString to the externalBytes, starting at index up to either maxSize characters,
or (and including) the 0-byte, whichever is encountered first.
The final 0-byte is only written, if the string is shorter than maxSize.
The index is a smalltalk index (i.e. 1-based).

 stringAt: index size: maxSize

return a string starting at index up to maxSize, or a 0-byte.
The index is a smalltalk index (i.e. 1-based).

 zeroByteStringAt: index maximumSize: count

extract a zeroByte-delimited string, given initial index and
maximum number of characters (bytes).
The index is a smalltalk index (i.e. 1-based).

 replaceBytesFrom: start to: stop with: aCollection startingAt: repStart

replace elements from another collection, which must be a ByteArray-
like collection.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

 replaceBytesFrom: startIndex with: replacementCollection startingAt: repStartIndex

replace elements from another collection, which must be
byte-array-like.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

 replaceFrom: startIndex to: stopIndex with: aCollection startingAt: repStartIndex

replace elements in the receiver between index start and stop,
with elements taken from replacementCollection starting at repStart.
Return the receiver.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

 computeXorHashFrom: startIndex to: endIndex

compute and answer the SmallInteger-Hash of the bytes
from startIndex to endIndex.
If endindex = 0 or endIndex > size, hash up the size.

NOTE: startIndex and endIndex are only hints about what should be hashed.
In fact, more bytes could be involved in hashing.
SO ARRAYS MUST BE EQUAL TO HASH TO THE SAME VALUE

 copyReverse

create a copy of myself with elements reversed in order

 swapLongAt: byteIndex

swap the byteOrder of a long.
The index is a smalltalk index (i.e. 1-based).

 slowReplaceBytesFrom: start to: stop with: sourceBytes startingAt: sourceIndex

fallback if primitive code fails

 defaultElement

 sizeInBytes

return the number of 8-bit bytes in the receiver.
This is needed since subclasse may redefine #size (TwoByteString)

 isByteCollection

return true, if the receiver has access methods for bytes;
true is returned here - the method is redefined from Object.

 isNonByteCollection

return true, if the receiver is some kind of collection, but not a String, ByteArray etc.;
false is returned here - the method is redefined from Collection.

 acceptVisitor: aVisitor with: aParameter