Smalltalk/X Webserver

Documentation of class 'UninterpretedBytes':

Class: UninterpretedBytes

Inheritance
Description
Class protocol
Instance protocol

Inheritance:

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

Package:: stx:libbasic

Category:: Collections-Abstract

Version:: rev: 1.223 date: 2024/02/14 11:30:28; user: cg; file: UninterpretedBytes.st directory: libbasic; module: stx stc-classLibrary: libbasic

Description:

UninterpretedBytes provides the common protocol for byte-storage
containers; concrete subclasses are
    ByteArray (which store the bytes within the Smalltalk object memory)
    String    (knows that the bytes represent characters)
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 did 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)

copyrightCOPYRIGHT (c) 1993 by 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.

return new instance which contains the bytes of anUnboxedValuesArray.
anUnboxedValuesArray can be an integer array, a floatArray, etc.
For ExternalBytes, the memory is under the control of the garbage collector
(i.e. the instance will be finalized and the malloc'd memory will be freed,
if the instance goes away).

Usage example(s):

     ByteArray fromBytesOf:#[40 41 42 43 44]
     ByteArray fromBytesOf:#u32(40 41 42)

     ExternalBytes fromBytesOf:#[40 41 42 43 44]
     ExternalBytes fromBytesOf:#u32(40 41 42)

fromHexString: aString

decode a byteArray from a hex string (as generated by hexPrintOn:).
aString should not contain whitespace (only hex chars);
see fromHexStringWithSeparators: for an alternative

Usage example(s):

     ByteArray fromHexString:'1234FEFF'
     ExternalBytes fromHexString:'1234FEFF'

Usage example(s):

     |s|
     s := String streamContents:[:s | #[1 2 3] hexPrintOn:s].
     ByteArray fromHexString:s

Usage example(s):

     Time millisecondsToRun:[
	1000000 timesRepeat:[ ByteArray fromHexString:'1234FEFF1234FEFF1234FEFF1234FEFF' ]
     ].

fromHexString: aString withSeparator: sepChar

read a bytearray from a printed string representation,
where individual bytes are encoded as two hex digits, separated by sepChar.
If the argument sepChar is nil, any character is allowed;
otherwise, the bytes MUST be separated by sepChar.
See also fromHexString:, which does something similar,
but does not allow for separators

Usage example(s):

     ByteArray fromHexString:'1234FEFF'
     ByteArray fromHexStringWithSeparators:'  12  34 FE   FF'
     ByteArray fromHexString:'12:34:FE:FF' withSeparator:$:
     ByteArray fromHexString:'12:34:FE:FF' withSeparator:$$
     ByteArray fromHexString:'12:34:FE:FF' withSeparator:nil

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

Usage example(s):

     ByteArray fromHexString:'1234FEFF'
     ByteArray fromHexStringWithSeparators:'   12  34 FE FF'

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).
Every 6 bit packet is encoded as a character in 32..95.
Characters below 32 are ignored (so line breaks can be inserted at any place).
An addition final byte defines how many bytes of the last triple are valid.
This is somewhat like the radix-encoding used in good old PDP11 times ;-)
ST-80 uses this encoding for Images ...
This is a base64 encoding, very similar (but not equal) to the algorithm used in RFC1421.
PS: It took a while to figure that one out ...
PPS: I don't like it ;-)

Usage example(s):

     ByteArray fromPackedString:(#[1 1 1 1] asPackedString)
     ByteArray fromPackedString:(#[1 1 1 1 1] asPackedString)
     ByteArray fromPackedString:(#[1 1 1 1 1 1] asPackedString)
     ByteArray fromPackedString:(#[1 1 1 1 1 1 1] asPackedString)
     ByteArray fromPackedString:(#[1 1 1 1 1 1 1 1] asPackedString)
     ByteArray fromPackedString:((ByteArray new:256) asPackedString)
     ByteArray fromPackedString:((ByteArray new:128) asPackedString)
     ByteArray fromPackedString:((ByteArray new:129) asPackedString)
     ByteArray fromPackedString:((ByteArray new:130) asPackedString)
     ByteArray fromPackedString:((ByteArray new:131) asPackedString)
     ByteArray fromPackedString:((ByteArray new:132) asPackedString)
     ByteArray fromPackedString:((ByteArray new:64) asPackedString)

     0 to:256 do:[:l |
	|orig copy|

	0 to:255 do:[:fill |
	    orig := ByteArray new:l withAll:fill.
	    copy := ByteArray fromPackedString:(orig asPackedString).
	    self assert:(orig = copy).
	 ]
     ]

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.

with: aByteArray from: start to: stop

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

Usage example(s):

      String with:#[40 41 42 43 44 45 46 47 48 49 50] from:2 to:5
      ByteArray with:'abcdefghijklmnopq' from:2 to:5

queries

isAbstract

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

isBigEndian

return true, if words/shorts store the most-significant
byte first (MSB), false if least-sign.-first (LSB).
Returns
false for vax, intel,
true for m68k, m88k, power, sparc.

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

Usage example(s):

     UninterpretedBytes isBigEndian

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:

Compatibility

doubleWordAt: index: OBSOLETE: please use unsignedInt32At: to make the size explicit

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 machine's natural byte order.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
doubleWordAt: index MSB: msb: OBSOLETE: please use unsignedInt32At:MSB: to make the size explicit

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
doubleWordAt: byteIndex put: anInteger: OBSOLETE: please use unsignedInt32At:put: to make the size explicit

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 machine's natural byte order.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
doubleWordAt: byteIndex put: anInteger MSB: msb: OBSOLETE: please use unsignedInt32At:put:MSB: to make the size explicit

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
doubleWordAtDoubleWordIndex: int32Index: marked as obsolete by Stefan Vogel at 20-Mrz-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **
doubleWordAtDoubleWordIndex: int32Index MSB: msb: marked as obsolete by Stefan Vogel at 20-Mrz-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **
doubleWordAtDoubleWordIndex: int32Index put: anInteger: marked as obsolete by Stefan Vogel at 20-Mrz-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **
doubleWordAtDoubleWordIndex: int32Index put: anInteger MSB: msb: marked as obsolete by Stefan Vogel at 20-Mrz-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **
int16At: byteIndex: OBSOLETE: please use signedInt16At: to make the meaning explicit

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 machine's natural byte order.
This may be worth a primitive.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
int16At: byteIndex MSB: msb: OBSOLETE: please use signedInt16At:MSB: to make the meaning explicit

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 an obsolete interface - do not use it (it may vanish in future versions) **
int16At: index put: anInteger: OBSOLETE: please use signedInt16At:put: to make the meaning explicit

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 machine's natural byteorder

** This is an obsolete interface - do not use it (it may vanish in future versions) **
int16At: index put: anInteger MSB: bigEndian: OBSOLETE: please use signedInt16At:put:MSB: to make the meaning explicit

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
longAt: index: OBSOLETE: please use signedInt32At:MSB: to make the size explicit
(what is a long 32, 64 or more?)

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 machine's 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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
longAt: index bigEndian: msb: OBSOLETE: please use signedInt32At:MSB: to make the size explicit
(what is a long 32, 64 or more?)

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
longAt: index put: value: OBSOLETE: please use signedInt32At:put:MSB: to make the size explicit
(what is a long 32, 64 or more?)

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 machine's natural byte order.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
longAt: byteIndex put: anInteger bigEndian: msb: OBSOLETE: please use signedInt32At:put:MSB: to make the size explicit
(what is a long 32, 64 or more?)

store a signed long (32bit) integer.
The index is a smalltalk index (i.e. 1-based).

** This is an obsolete interface - do not use it (it may vanish in future versions) **
longLongAt: index: OBSOLETE: please use signedInt64At: to make the size explicit
(what is a long long 64, 128 or more?)

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 machine's natural byte order.
This may be worth a primitive.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
longLongAt: index bigEndian: msb: OBSOLETE: please use signedInt64At:MSB: to make the size explicit
(what is a long long 64, 128 or more?)

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
longLongAt: byteIndex put: anInteger: OBSOLETE: please use signedInt64At:put: to make the size explicit
(what is a long long 64, 128 or more?)

store a signed longLong (64bit) integer.
The index is a smalltalk index (i.e. 1-based).
The value is stored in the machine's natural byte order.
Same as #signedQuadWordAt:put: - for ST80 compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
longLongAt: byteIndex put: anInteger bigEndian: msb: OBSOLETE: please use signedInt64At:put:MSB: to make the size explicit
(what is a long long 64, 128 or more?)

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

** This is an obsolete interface - do not use it (it may vanish in future versions) **
quadWordAt: index MSB: msb: OBSOLETE: please use unsignedInt64At:MSB: to make the size explicit
(what is a word 16,32,64? and what are four of them then?)

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
quadWordAt: index put: anInteger MSB: msb: OBSOLETE: please use unsignedInt64At:put:MSB: to make the size explicit
(what is a word 16,32,64? and what are four of them then?)

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
shortAt: index: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
shortAt: index bigEndian: msb: OBSOLETE: please use signedInt16At:MSB: to make the sign explicit

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:

** This is an obsolete interface - do not use it (it may vanish in future versions) **
shortAt: index put: value: OBSOLETE: please use signedInt16At:put: to make the sign explicit

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 machine's natural byteorder.
This may be worth a primitive.
This is the ST80 equivalent of #signedWordAt:put:

** This is an obsolete interface - do not use it (it may vanish in future versions) **
shortAt: index put: value bigEndian: bigEndian: OBSOLETE: please use signedInt16At:put:MSB: to make the sign explicit

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedDoubleWordAt: index: OBSOLETE: please use signedInt32At: to make the size explicit
(what is a word 16,32,64 bits? and what are two of them then)

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 machine's natural byte order.
This may be worth a primitive.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedDoubleWordAt: index MSB: msb: OBSOLETE: please use signedInt32At:MSB: to make the size explicit
(what is a word 16,32,64 bits? and what are two of them then)

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedDoubleWordAt: index put: value: OBSOLETE: please use signedInt32At:put: to make the size explicit
(what is a word 16,32,64 bits? and what are two of them then)

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 machine's natural byte order.
This may be worth a primitive.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedDoubleWordAt: index put: value MSB: msb: OBSOLETE: please use signedInt32At:put:MSB: to make the size explicit
(what is a word 16,32,64 bits? and what are two of them then)

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.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedLongAt: index: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedLongAt: index put: newValue: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedShortAt: index: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedShortAt: index bigEndian: msb: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedShortAt: index put: value: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedShortAt: index put: value bigEndian: msb: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedWordAt: index: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedWordAt: index MSB: msb: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedWordAt: byteIndex put: anInteger: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
signedWordAt: byteIndex put: anInteger MSB: msb: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedLongAt: index: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedLongAt: index bigEndian: msb: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedLongAt: index put: value: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedLongAt: index put: aNumber bigEndian: msb: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedLongLongAt: index: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedLongLongAt: index bigEndian: msb: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedLongLongAt: index put: anInteger: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedLongLongAt: index put: anInteger bigEndian: msb: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedShortAt: index: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedShortAt: index bigEndian: msb: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedShortAt: index put: value: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
unsignedShortAt: index put: value bigEndian: msb: marked as obsolete by Stefan Vogel at 23-Jul-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **
wordAt: index: OBSOLETE: please use unsignedInt16At: to make the size explicit
(what is a word)

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 machine's natural byte order
Subclasses may redefine this for better performance.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
wordAt: index MSB: msb: OBSOLETE: please use unsignedInt16At:MSB: to make the size explicit
(what is a word)

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 it's false.
Notice:
the index is a byte index; thus, this allows for unaligned access to
words on any boundary.
Question: should it be retrieve signed values ? (see ByteArray>>signedWordAt:)

** This is an obsolete interface - do not use it (it may vanish in future versions) **
wordAt: index put: value: OBSOLETE: please use unsignedInt16At:put: to make the size explicit
(what is a word)

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 machine's natural byteorder.
Question: should it accept signed values ? (see ByteArray>>signedWordAt:put:)

** This is an obsolete interface - do not use it (it may vanish in future versions) **
wordAt: index put: value MSB: msb: OBSOLETE: please use unsignedInt16At:put:MSB: to make the size explicit
(what is a word)

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

** This is an obsolete interface - do not use it (it may vanish in future versions) **
wordAtWordIndex: int16Index: marked as obsolete by Stefan Vogel at 20-Mrz-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **
wordAtWordIndex: int16Index MSB: msb: marked as obsolete by Stefan Vogel at 20-Mrz-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **
wordAtWordIndex: int16Index put: anInteger: marked as obsolete by Stefan Vogel at 20-Mrz-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **
wordAtWordIndex: int16Index put: anInteger MSB: msb: marked as obsolete by Stefan Vogel at 20-Mrz-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **

Compatibility-Squeak

copyFromByteArray: aByteArray: copy as much as possible from aByteArray

Compatibility-V'Age

uint32At: zeroBasedIndex

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

Usage example(s):

     |b|

     b := ByteArray withAll:#(0 0 0 0).
     b uint32At:0 put:16r12345678.
     b uint32At:0.
     b

uint32At: zeroBasedIndex put: anInteger

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

Usage example(s):

     |b|

     b := ByteArray withAll:#(0 0 0 0).
     b uint32At:0 put:16r12345678.
     b

accessing-128bit ints

signedInt128At: index

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

signedInt128At: index MSB: msb

return the 16-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.

Usage example(s):

     |b|
     b := ByteArray new:16.
     b unsignedInt128At:1 put:16rFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF MSB:true.
     (b signedInt128At:1 MSB:true)

signedInt128At: byteIndex put: anInteger

store a signed 128bit integer in native byteorder.
The index is a smalltalk index (i.e. 1-based).

signedInt128At: byteIndex put: anInteger MSB: msb

store a signed 128bit integer.
The index is a smalltalk index (i.e. 1-based).

Usage example(s):

     |b|
     b := ByteArray new:16.
     b signedInt128At:1 put:-1 MSB:true.
     (b unsignedInt128At:1 MSB:true)

unsignedInt128At: index

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

unsignedInt128At: byteIndex MSB: msb

return the 16-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.

Usage example(s):

     |b|

     b := ByteArray withAll:#(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16).
     (b unsignedInt128At:1 MSB:false) printStringRadix:16

unsignedInt128At: byteIndex put: anInteger

store a signed 128bit integer in native byteorder.
The index is a smalltalk index (i.e. 1-based).

unsignedInt128At: byteIndex put: anInteger MSB: msb

set the 18-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 16rFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.
Depending on msb, the value is stored MSB-first or LSB-first.

Usage example(s):

     |b|
     b := ByteArray new:16.
     b unsignedInt128At:1 put:16r100F0E0D0C0B0A090807060504030201 MSB:false.
     b inspect

accessing-arbitrary-long ints

nativeIntAt: index

return the 4- or 8-bytes (depending on the native integer/pointer size)
starting at index as a signed Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machine's natural byte order,
therefore, this should only be used for byte-data which is
only used inside this machine.

Usage example(s):

     |b|
     b := ByteArray new:8.
     b nativeIntAt:1 put:SmallInteger maxVal.
     b nativeIntAt:1

nativeIntAt: index put: value

set the 4- or 8-bytes (depending on INT-/pointer size) starting at index from the signed Integer value.
The index is a smalltalk index (i.e. 1-based).
The value is stored in the machine's natural byte order.

Usage example(s):

     |b|
     b := ByteArray new:8.
     b nativeIntAt:1 put:SmallInteger maxVal.
     (b nativeIntAt:1)

signedIntAt: index

return the integer starting at index as a (signed) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machine's natural byte order and the machines natural
int size.
Subclasses may redefine this for better performance.

Usage example(s):

     |b|

     b := ByteArray withAll:#(1 2 3 4 5 6 7 8 9).
     (b signedIntAt:1) printStringRadix:16

signedIntAt: index put: aValue

write the integer starting at index as a (signed) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is written in the machine's natural byte order and the machines natural
int size.
Subclasses may redefine this for better performance.

Usage example(s):

     |b|

     b := ByteArray withAll:#(1 2 3 4 5 6 7 8 9).
     (b signedIntAt:1) printStringRadix:16

signedIntegerAt: index length: len MSB: bigEndian

return the n-byte signed integer starting at index.
With n=1, this returns the single signed byte's value,
n=2, a signed short, n=4 a signed int etc.
Useful to extract arbitrary long integers

Usage example(s):

     |b|
     b := #[ 16r01 16rFF 16r00 16r04 16r05 ].
     (b signedIntegerAt:2 length:2 MSB:false). ' -> 255 (00FF) '.
     (b signedIntegerAt:2 length:2 MSB:true).  ' -> -256 (FF00) '.

     b := #[ 16r01 16r00 16rFF 16r04 16r05 ].
     (b signedIntegerAt:2 length:2 MSB:false). ' -> -256 (FF00) '.
     (b signedIntegerAt:2 length:2 MSB:true).  ' -> 255 (00FF) '.

     b := #[ 16r01 16r7F 16r00 16r04 16r05 ].
     (b signedIntegerAt:2 length:2 MSB:false). ' -> 127 (007F) '.
     (b signedIntegerAt:2 length:2 MSB:true).  ' -> 32512 (7F00) '.

Usage example(s):

     |b|
     b := #[ 16r01 16r02 16r03 16r04 16r05 ].
     (b signedIntegerAt:2 length:4 MSB:false).
     (b signedIntegerAt:2 length:4 MSB:true).

     b := #[ 16r01 16r82 16r03 16r04 16r05 ].
     (b signedIntegerAt:2 length:4 MSB:false).
     (b signedIntegerAt:2 length:4 MSB:true).

     b := #[ 16r01 16r82 16r03 16r04 16r85 ].
     (b signedIntegerAt:2 length:4 MSB:false).
     (b signedIntegerAt:2 length:4 MSB:true).

signedIntegerAt: index length: len bigEndian: bigEndian

OBSOLETE: use ***:MSB:
return the n-byte signed integer starting at index.
With n=1, this returns the single signed byte's value,
n=2, a signed short, n=4 a signed int etc.
Useful to extract arbitrary long integers

** This is an obsolete interface - do not use it (it may vanish in future versions) **

unsignedIntAt: index

return the integer starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved in the machine's natural byte order and the machines natural
int size.
Subclasses may redefine this for better performance.

Usage example(s):

     |b|

     b := ByteArray withAll:#(1 2 3 4 5 6 7 8 9).
     (b unsignedIntAt:1) printStringRadix:16

unsignedIntAt: index put: aValue

write aValue starting at index as an (unsigned) Integer.
The index is a smalltalk index (i.e. 1-based).
The value is stored in the machine's natural byte order and the machines natural
int size.
Subclasses may redefine this for better performance.

Usage example(s):

     |b|

     b := ByteArray withAll:#(1 2 3 4 5 6 7 8 9).
     (b unsignedIntAt:1) printStringRadix:16

unsignedIntegerAt: index length: len

return the n-byte unsigned integer starting at index.
With n=1, this returns the single byte's value,
n=2, an unsigned short, n=4 an unsigned int32 etc.
Useful to extract arbitrary long integers.
Reads the value in the machine's natural byte order

Usage example(s):

     |b|
     b := #[ 16r01 16r02 16r03 16r04 16r05 ].
     (b unsignedIntegerAt:2 length:4 bigEndian:false).
     (b unsignedIntegerAt:2 length:4 bigEndian:true).
     (b unsignedIntegerAt:2 length:4).

unsignedIntegerAt: index length: len MSB: bigEndian

return the n-byte unsigned integer starting at index.
With n=1, this returns the single byte's value,
n=2, an unsigned short, n=4 an unsigned int32 etc.
Useful to extract arbitrary long integers

Usage example(s):

     |b|
     b := #[ 16r01 16r02 16r03 16r04 16r05 ].
     (b unsignedIntegerAt:2 length:4 bigEndian:false).
     (b unsignedIntegerAt:2 length:4 bigEndian:true).

unsignedIntegerAt: index length: len bigEndian: bigEndian

OBSOLETE: use ***:MSB:
return the n-byte unsigned integer starting at index.
With n=1, this returns the single byte's value,
n=2, an unsigned short, n=4 an unsigned int32 etc.
Useful to extract arbitrary long integers

** This is an obsolete interface - do not use it (it may vanish in future versions) **

unsignedIntegerAt: index put: newValue length: len

store the n-byte unsigned integer starting at index.
With n=1, this stores a single byte's value,
n=2, an unsigned short, n=4 an unsigned int32 etc.
Useful to replace arbitrary long integers.
Writes the value in the machine's natural byte order

Usage example(s):

     |b|
     b := #[ 16r01 16r02 16r03 16r04 16r05 ] copy.
     (b unsignedIntegerAt:2 put:16r11223344 length:3 bigEndian:false). b.
     (b unsignedIntegerAt:2 put:16r11223344 length:3 bigEndian:true). b.

unsignedIntegerAt: index put: newValue length: len MSB: bigEndian

store the n-byte unsigned integer starting at index.
With n=1, this stores a single byte's value,
n=2, an unsigned short, n=4 an unsigned int32 etc.
Useful to replace arbitrary long integers

Usage example(s):

     |b|
     b := #[ 16r01 16r02 16r03 16r04 16r05 ] copy.
     (b unsignedIntegerAt:2 put:16r11223344 length:3 bigEndian:false). b.
     (b unsignedIntegerAt:2 put:16r11223344 length:3 bigEndian:true). b.

unsignedIntegerAt: index put: newValue length: len bigEndian: bigEndian

OBSOLETE: use ***:MSB:
store the n-byte unsigned integer starting at index.
With n=1, this stores a single byte's value,
n=2, an unsigned short, n=4 an unsigned int32 etc.
Useful to replace arbitrary long integers

** This is an obsolete interface - do not use it (it may vanish in future versions) **

accessing-bytes

atAllPutByte: byteValue

replace all elements of the collection by the argument, anObject.
Return the receiver.
Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

bcdByteAt: index

return the bcd-value for a byte at index in the range 0..99.
BCD treats nibbles (4-bit) as an encoded decimal number's digits
(i.e. the value n is encoded as: ((n // 10) * 16) + (n \\ 10)

Usage example(s):

     #[ 16r55 ] bcdByteAt:1
     #[ 16r99 ] bcdByteAt:1
     #[ 16rAA ] bcdByteAt:1

bcdByteAt: index put: aNumber

set the byte at index as bcd-value in the range 0..99.
BCD treats nibbles (4-bit) as an encoded decimal number's digits
(i.e. the value n is encoded as: ((n // 10) * 16) + (n \\ 10)

Usage example(s):

     (((ByteArray new:1) bcdByteAt:1 put:55; yourself) at:1) hexPrintString
     (((ByteArray new:1) bcdByteAt:1 put:99; yourself) at:1) hexPrintString
     (((ByteArray new:1) bcdByteAt:1 put:100; yourself) at:1) hexPrintString
     (((ByteArray new:1) bcdByteAt:1 put:-1; yourself) at:1) hexPrintString

byteAt: byteIndex

return the byte at byteIndex as an unsigned 8 bit value in the range 0..255.
The index is a smalltalk index (i.e. 1-based).

byteAt: byteIndex put: anInteger

set the byte at byteIndex as an unsigned 8 bit value in the range 0..255.
The index is a smalltalk index (i.e. 1-based).

Usage example(s):

     |b|
     b := String new:3.
     b byteAt:1 put:16rFF.
     b byteAt:2 put:16r7F.
     b byteAt:3 put:16r80.
     b byteAt:1.
     b byteAt:2.
     b byteAt:3.

clearContents

to be used with cryptographic keys, to wipe their contents after use.
Fills the string's memory with zeros

Usage example(s):

        '1234567' copy clearContents

intValAt: byteIndex

return the byte at byteIndex as an unsigned 8 bit value in the range 0..255.
The index is a smalltalk index (i.e. 1-based).
Use this instead of: '(aString at:index) asInteger'
Same as #byteAt.
Compatible with Unicode16String and Unicode32String.

signedByteAt: byteIndex

return the byte at byteIndex as a signed 8 bit value in the range -128..+127.
The index is a smalltalk index (i.e. 1-based).

Usage example(s):

     |b|
     b := ByteArray new:3.
     b at:1 put:16rFF.
     b at:2 put:16r7F.
     b at:3 put:16r80.
     b signedByteAt:1.
     b signedByteAt:2.
     b signedByteAt:3.

signedByteAt: byteIndex put: aSignedByteValue

set the byte at byteIndex to aSignedByteValue in the range -128 .. 255
The index is a smalltalk index (i.e. 1-based).
Return the signedByteValue argument.

unsignedByteAt: byteIndex

return the byte at byteIndex as an unsigned 8 bit value in the range -128..+127.
The index is a smalltalk index (i.e. 1-based).

accessing-floats & doubles

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 machine's
float representation and byte order - if the bytearray originated from another
machine, some conversion is usually needed.

Usage example(s):

     |b|

     b := ByteArray new:20.
     b doubleAt:1 put:(Float pi).
     Transcript showCR:b.
     Transcript showCR:(b doubleAt:1)

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 machine's
float representation and byte order - 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 machine's
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 machine's
float representation and byte 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 machine's
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 and byte order - 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 in the native byte order.

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 in the native byte order).

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 in the native byte order.

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 in the native byte order).
Since ST/X floats are really doubles,
the low- order 4 bytes of the precision are lost.

longDoubleAt: index

return the 16-bytes starting at index as a LongDouble.
The index is a smalltalk index (i.e. 1-based).

Notice, that the C-type long double might have different sizes on different
machines and may only use part of the 16 bytes;
i.e. 10bytes (80bit) as on intel CPUS, 12 bytes (96bits) or 16 bytes (128bits).

Notice also, that the bytes are expected to be in this machine's
long double representation and byte order
- if the bytearray originated from another
machine, some conversion is usually needed.

Usage example(s):

     |b|

     b := ByteArray new:20.
     b longDoubleAt:1 put:(LongFloat pi).
     Transcript showCR:b.
     Transcript showCR:(b longDoubleAt:1)

longDoubleAt: index MSB: msb

return the 16-bytes starting at index as a LongDouble.
The index is a smalltalk index (i.e. 1-based).

Notice, that the C-type long double has different sizes on different
machines and may only use part of the 16 bytes;
i.e. 10bytes (80bit) as on intel CPUS, 12 bytes (96bits) or 16 bytes (128bits).

Notice also, that the bytes are expected to be in this machine's
long double representation - if the bytearray originated from another
machine, some conversion is usually needed.

longDoubleAt: index put: aLongFloat

store the value of the argument, aLongFloat as 16 bytes into the receiver
starting at index.
The index is a smalltalk index (i.e. 1-based).
LongFloats are the machine's long double numbers.

Notice that the bytes are expected to be in this machine's
long double representation and byte order - if the bytearray originated from another
machine, some conversion is usually needed.

longDoubleAt: index put: aLongFloat MSB: msb

store the value of the argument, aLongFloat as 16 bytes into the receiver
starting at index.
The index is a smalltalk index (i.e. 1-based).

Notice that the bytes are expected to be in this machine's
long double representation - if the bytearray originated from another
machine, some conversion is usually needed.

accessing-longlongs (64bit)

signedInt64At: 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 machine's natural byte order.
This may be worth a primitive.

Usage example(s):

     |b|
     b := ByteArray new:8.
     b unsignedInt64At:1 put:16rFFFFFFFFFFFFFFFF MSB:true.
     (b signedInt64At:1 MSB:true)

signedInt64At: index MSB: 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.

Usage example(s):

     |b|
     b := ByteArray new:8.
     b unsignedInt64At:1 put:16rFFFFFFFFFFFFFFFF MSB:true.
     (b signedInt64At:1 MSB:true)

signedInt64At: byteIndex put: anInteger

store a signed longLong (64bit) integer.
The index is a smalltalk index (i.e. 1-based).
The value is stored in the machine's natural byte order.
Same as #signedQuadWordAt:put: - for ST80 compatibility.

signedInt64At: byteIndex put: anInteger MSB: msb

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

signedInt64AtLSB: byteIndex

return the 8-bytes starting at index as a signed 64bit Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved with least significant byte first

signedInt64AtLSB: byteIndex put: anInteger

set the 8-bytes starting at index from the signed Integer anInteger.
The index is a smalltalk index (i.e. 1-based).
The integer is stored with least significant byte first.

signedInt64AtMSB: byteIndex

return the 8-bytes starting at index as a signed 64bit Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved with most significant byte first

signedInt64AtMSB: byteIndex put: anInteger

set the 8-bytes starting at index from the signed Integer anInteger.
The index is a smalltalk index (i.e. 1-based).
The integer is stored with least significant byte first.

unsignedInt64At: byteIndex

return the 8-bytes starting at index in the machine's native
byteorder as an unsigned integer.
The value is retrieved in the machine's natural byte order.
The index is a smalltalk index (i.e. 1-based)

Usage example(s):

     |b|

     b := ByteArray withAll:#(1 2 3 4 5 6 7 8).
     (b unsignedInt64At:1) printStringRadix:16

unsignedInt64At: byteIndex 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.

Usage example(s):

     |b|

     b := ByteArray withAll:#(1 2 3 4 5 6 7 8).
     (b unsignedInt64At:1 MSB:false) printStringRadix:16

Usage example(s):

     |b|
     b := ByteArray new:8.
     b signedInt64At:1 put:-1 MSB:true.
     (b unsignedInt64At:1 MSB:true)

unsignedInt64At: byteIndex 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 the machine's natural byteorder.

Usage example(s):

     |b|
     b := ByteArray new:10.
     b unsignedInt64At:1 put:16r0807060504030201 MSB:false.
     b unsignedInt64At:1 put:16r0807060504030201 MSB:true.
     b inspect

unsignedInt64At: byteIndex 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.

Usage example(s):

     |b|
     b := ByteArray new:8.
     b unsignedInt64At:1 put:16r0807060504030201 MSB:false.
     b inspect

Usage example(s):

     |b|
     b := ByteArray new:8.
     b unsignedInt64At:1 put:16r1FFFFFFFFFFFFFFFF MSB:false.
     b inspect

unsignedInt64AtLSB: byteIndex

return the 8-bytes starting at index as an unsigned 64bit Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved with most significant byte first

unsignedInt64AtLSB: byteIndex put: anInteger

set the 8-bytes starting at index from the unsigned Integer anInteger.
The index is a smalltalk index (i.e. 1-based).
The integer is stored with least significant byte first.

unsignedInt64AtMSB: byteIndex

return the 8-bytes starting at index as an unsigned 64bit Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved with most significant byte first

unsignedInt64AtMSB: byteIndex put: anInteger

set the 8-bytes starting at index from the unsigned Integer anInteger.
The index is a smalltalk index (i.e. 1-based).
The integer is stored with least significant byte first.

accessing-longs (32bit)

signedInt32At: byteIndex

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

Usage example(s):

     |b|
     b := ByteArray new:4.
     b signedInt32At:1 put:16r7FFFFFFF.
     (b signedInt32At:1)

Usage example(s):

     |b|
     b := ByteArray new:4.
     b signedInt32At:1 put:-2.
     (b signedInt32At:1)

signedInt32At: byteIndex MSB: msb

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

Usage example(s):

     |b|

     b := ByteArray withAll:#(1 2 3 4).
     (b signedInt32At:1 MSB:true) printStringRadix:16.
     (b signedInt32At:1 MSB:false) printStringRadix:16

signedInt32At: byteIndex put: anInteger

set the 4-bytes starting at index from the signed Integer anInteger.
The index is a smalltalk index (i.e. 1-based).
The integer is stored in the machine's natural byte order.

signedInt32At: byteIndex put: anInteger MSB: msb

set the 4-bytes starting at byteIndex from the signed Integer value.
The byteIndex is a smalltalk index (i.e. 1-based).

This is the ST80 version of #signedDoubleWordAt:put:

signedInt32AtLSB: byteIndex

return the 4-bytes starting at index as a signed 32bit Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved with least significant byte first

signedInt32AtLSB: byteIndex put: anInteger

set the 4-bytes starting at index from the signed Integer anInteger.
The index is a smalltalk index (i.e. 1-based).
The integer is stored with least significant byte first.

signedInt32AtMSB: byteIndex

return the 4-bytes starting at index as a signed 32bit Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved with most significant byte first

signedInt32AtMSB: byteIndex put: anInteger

set the 4-bytes starting at index from the signed Integer anInteger.
The index is a smalltalk index (i.e. 1-based).
The integer is stored with most significant byte first.

unsignedInt32At: byteIndex

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 machine's natural byte order.

Usage example(s):

     |b|

     b := ByteArray withAll:#(1 2 3 4).
     (b unsignedInt32At:1) printStringRadix:16

unsignedInt32At: byteIndex 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.

Usage example(s):

     |b|

     b := ByteArray withAll:#(1 2 3 4).
     (b unsignedInt32At:1 MSB:true) printStringRadix:16.     '=> 1020304'.
     (b unsignedInt32At:1 MSB:false) printStringRadix:16.    '=> 4030201'.
     b := ByteArray withAll:#(1 2 3 4 5).
     (b unsignedInt32At:2 MSB:true) printStringRadix:16.     '=> 2030405'.
     (b unsignedInt32At:2 MSB:false) printStringRadix:16.    '=> 5040302'.
     b := ByteArray withAll:#(1 2 3 4 5 6).
     (b unsignedInt32At:3 MSB:true) printStringRadix:16.     '=> 3040506'.
     (b unsignedInt32At:3 MSB:false) printStringRadix:16.    '=> 6050403'.

unsignedInt32At: byteIndex put: anInteger

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 in the machine's native byte order

unsignedInt32At: byteIndex put: anInteger MSB: msb

set the 4-bytes starting at byteIndex from the unsigned Integer value.
The byteIndex is a smalltalk index (i.e. 1-based).

This is the ST80 version of #doubleWordAt:put:

Usage example(s):

     |b|
     b := ByteArray new:4.
     b signedInt32At:1 put:-1.
     (b unsignedInt32At:1) printStringRadix:16

Usage example(s):

     |b|
     b := ByteArray new:4.
     b unsignedInt32At:1 put:16rFFFFFFFF.
     (b signedInt32At:1)

unsignedInt32AtLSB: byteIndex

return the 4-bytes starting at index as an unsigned 32bit Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved with least significant byte first

unsignedInt32AtLSB: byteIndex put: anInteger

set the 4-bytes starting at index from the unsigned Integer anInteger.
The index is a smalltalk index (i.e. 1-based).
The integer is stored with least significant byte first.

unsignedInt32AtMSB: byteIndex

return the 4-bytes starting at index as an unsigned 32bit Integer.
The index is a smalltalk index (i.e. 1-based).
The value is retrieved with most significant byte first

unsignedInt32AtMSB: byteIndex put: anInteger

set the 4-bytes starting at index from the unsigned Integer anInteger.
The index is a smalltalk index (i.e. 1-based).
The integer is stored with most significant byte first.

accessing-pointers

pointerAt: byteIndex

get a pointer starting at byteIndex as ExternalAddress.
The byteIndex is a smalltalk index (i.e. 1-based).
Only aligned accesses are allowed.
The pointer is of native cpu's size (4 or 8 bytes).
This returns an external adress.

pointerAt: byteIndex put: value

set the pointer starting at byteIndex from the integer or externalAddress value.
The byteIndex is a smalltalk index (i.e. 1-based).
Only aligned accesses are allowed.
The pointer is of native cpu's size (4 or 8 bytes).
The value may be either an ExternalAddress, ExternalBytes or an Integer

Usage example(s):

     |b|
     b := ByteArray new:ExternalAddress pointerSize.
     b pointerAt:1 put:(ExternalAddress newAddress:16r12345678).
     (b unsignedLongAt:1) printStringRadix:16

pointerValueAt: byteIndex

get a pointer value starting at byteIndex as unsigned integer.
The byteIndex is a smalltalk index (i.e. 1-based).
Only aligned accesses are allowed.
The pointer is of native cpu's size (4 or 8 bytes).
This returns an int with sizeof the machines's native pointer (4 or 8 bytes)

Usage example(s):

     |b|
     b := ByteArray new:(ExternalAddress pointerSize).
     b pointerAt:1 put:(ExternalAddress newAddress:16r12345678).
     Transcript showCR:((b unsignedLongAt:1) printStringRadix:16).
     Transcript showCR:((b pointerAt:1)).
     Transcript showCR:((b pointerValueAt:1)).

accessing-shorts (16bit)

signedInt16At: byteIndex

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 machine's natural byte order.

signedInt16At: byteIndex 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 (high 8 bits at lower index) if msb is true;
LSB-first (i.e. low 8-bits at lower byte index) if it's false.
Notice:
the index is a byte index; thus, this allows for unaligned access to
words on any boundary.

signedInt16At: index put: anInteger

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 machine's natural byte order.

Usage example(s):

     |b|
     b := ByteArray new:4.
     b signedInt16At:1 put:-2.
     b signedInt16At:3 put:-3.
     b inspect

signedInt16At: byteIndex put: anInteger MSB: msb

set the 2-bytes starting at byteIndex from the signed integer value.
The byteIndex 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.

Usage example(s):

     |b|
     b := ByteArray new:4.
     b signedInt16At:1 put:-1.
     b signedInt16At:3 put:-2.
     b inspect

signedInt16AtLSB: byteIndex

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 with least significant byte first

Usage example(s):

     |b|
     b := ByteArray new:2.
     b wordAt:1 put:16rFFFE.
     b signedInt16AtLSB:1.
     b signedInt16AtMSB:1.

signedInt16AtLSB: index put: anInteger

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 0 .. 16rFFFF.
The value is stored with least significant byte first

signedInt16AtMSB: byteIndex

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 with most significant byte first

Usage example(s):

     |b|
     b := ByteArray new:2.
     b wordAt:1 put:16rFFFE.
     b signedInt16AtLSB:1.
     b signedInt16AtMSB:1.

signedInt16AtMSB: index put: anInteger

unsignedInt16At: 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 machine's natural byte order

unsignedInt16At: byteIndex 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 it's false.
Notice:
the index is a byte index; thus, this allows for unaligned access to
words on any boundary.

Usage example(s):

     #[ 16rFF 16r00 ] unsignedInt16At:1 MSB:true
     #[ 16rFF 16r00 ] unsignedInt16At:1 MSB:false

     #[ 16rFF 16r00 ] unsignedInt16At:2 MSB:true
     #[ 16rFF 16r00 ] unsignedInt16At:2 MSB:false

unsignedInt16At: index put: anInteger

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 machine's natural byteorder.

Usage example(s):

     |b|
     b := ByteArray new:4.
     b unsignedInt16At:1 put:16r0102.
     b unsignedInt16At:3 put:16r0304.
     b inspect

unsignedInt16At: byteIndex put: anInteger 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

Usage example(s):

     |b|
     b := ByteArray new:8.
     b unsignedInt16At:1 put:16r0102 MSB:false.
     b unsignedInt16At:3 put:16r0304 MSB:false.
     b unsignedInt16At:5 put:16r0102 MSB:true.
     b unsignedInt16At:7 put:16r0304 MSB:true.
     b inspect

unsignedInt16AtLSB: byteIndex

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 with least significant byte first

Usage example(s):

     |b|
     b := ByteArray new:2.
     b wordAt:1 put:16rFFFE.
     b unsignedInt16AtLSB:1.
     b unsignedInt16AtMSB:1.

unsignedInt16AtLSB: index put: anInteger

unsignedInt16AtMSB: byteIndex

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 with most significant byte first

unsignedInt16AtMSB: index put: anInteger

accessing-strings

stringAt: index

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

Usage example(s):

      #[71 72 73 74 75 76 77 0] stringAt:1                      => 'GHIJKLM'
      #[71 72 73 74 75 76 77 0] stringAt:2                      => 'HIJKLM'
      #[71 72 73 74 75 76 77] stringAt:1                        => 'GHIJKLM'
      #[71 72 73 74 75 76 77] stringAt:2                        => 'HIJKLM'
      #[71 72 73 74 75 0 77] stringAt:1                         => 'GHIJK' 
      #[71 72 73 74 75 0 77] stringAt:2                         => 'HIJK' 
      #[1 2 3 4 5 6 7 8 9 10 71 72 73 74 75 0 77] stringAt:11   => 'GHIJK'    
      #[1 2 3 4 5 6 7 8 9 10 71 72 73 74 75 0 77] stringAt:12   => 'HIJK'     
      '1234567890' stringAt:2                                   => '234567890'
      '1234567890' asText stringAt:2                            => '234567890'
      '1234567890' asExternalBytes stringAt:2                   => '234567890'
      '1234567890' asByteArray stringAt:2                       => '234567890'

stringAt: index put: aString

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

Usage example(s):

     |bytes|

     bytes := ExternalBytes new:10.
     bytes stringAt:1 put:'hello'.
     1 to:bytes size do:[:i |
	Transcript showCR:(bytes at:i)
     ].

Usage example(s):

     (String new:20) stringAt:1 put:'hello'; stringAt:6 put:' world'; yourself

stringAt: index put: aString size: maxSize

copy aString to the receiver, 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).

Usage example(s):

     |bytes|

     bytes := ExternalBytes new:10.
     bytes stringAt:1 put:'hello' size:3.
     1 to:bytes size do:[:i |
	Transcript showCR:(bytes at:i)
     ]

Usage example(s):

     |bytes|

     bytes := ByteArray new:10 withAll:16rFF.
     bytes stringAt:1 put:'he' size:3.
     1 to:bytes size do:[:i |
	Transcript showCR:(bytes at:i)
     ]

Usage example(s):

     (String new:20) stringAt:1 put:'hello' size:3 ; stringAt:4 put:' world' size:4; yourself

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

Usage example(s):

      #[71 72 73 74 75 76 77] stringAt:1 size:7   
      #[71 72 73 74 75 76 77] stringAt:2 size:6  
      #[71 72 73 74 75 76 77] stringAt:2 size:10  
      #[71 72 73 74 75 76 77 00 55] stringAt:2 size:10
      '1234567890' stringAt:2 size:6
      '1234567890' asText stringAt:2 size:6
      '1234567890' asExternalBytes stringAt:2 size:6

twoByteStringAt: index put: aTwoByteString

copy aTwoByteString to the receiver, starting at index.
The index is a smalltalk index (i.e. 1-based).

Usage example(s):

     |bytes|

     bytes := '12345678901234567890' asExternalBytes.
     bytes twoByteStringAt:1 put:'hello' asUnicode16String.
     1 to:bytes size do:[:i |
        Transcript showCR:(bytes at:i)
     ].

Usage example(s):

     (ByteArray new:30) twoByteStringAt:1 put:'hello'; twoByteStringAt:10 put:' world'; yourself

twoByteStringAt: index put: aTwoByteString size: maxSize

copy aTwoByteString to the receiver, starting at index up to either maxSize characters,
or the and of aTwoByteString.
The final 0-bytes are only written, if the string is shorter than maxSize.
The index is a smalltalk index (i.e. 1-based).

Usage example(s):

     |bytes|

     bytes := '12345678901234567890' asExternalBytes.
     bytes twoByteStringAt:6 put:'hello' asUnicode16String size:3.
     bytes.

Usage example(s):

     |bytes|

     bytes := '12345678901234567890' asExternalBytes.
     bytes twoByteStringAt:1 put:'hello' asUnicode16String size:8.
     bytes.

Usage example(s):

     (ByteArray new:30) twoByteStringAt:1 put:'hello' size:4; twoByteStringAt:8 put:' world'; yourself

unicode16StringAt: index size: maxSize

fetch and return a Unicode16String starting at byte index up to maxSize.
The index is a smalltalk index (i.e. 1-based) into the bytes.

Usage example(s):

     |bytes|

     bytes := '12345678901234567890' asExternalBytes.
     bytes twoByteStringAt:1 put:'hello' asUnicode16String.
     bytes unicode16StringAt:1 size:53.

Usage example(s):

     |bytes|

     bytes := '12345678901234567890' asExternalBytes.
     bytes twoByteStringAt:1 put:'hello' asUnicode16String.
     bytes unicode16StringAt:3 size:53.

Usage example(s):

     |bytes|

     bytes := ExternalBytes new:10.
     bytes twoByteStringAt:1 put:'hello' asUnicode16String.
     bytes unicode16StringAt:1 size:53.

zeroByteStringAt: index maximumSize: count

** This is an obsolete interface - do not use it (it may vanish in future versions) **

byte swapping and reversing

copyReverse

create a copy of myself with elements reversed in order

** This is an obsolete interface - do not use it (it may vanish in future versions) **

swapBytes

swap bytes (of int16s) inplace -
i.e. #[a b c d e f ...] will be changed inplace to #[b a d c f e ...].
This is a destructive operation - meaning that the receiver is modified.
Expects that the receiver has an even number of bytes;
if not, only the pairs excluding the last byte are swapped

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

Usage example(s):

     #[1 2 3 4 5] copy swapBytes  => #[2 1 4 3 5]
     #[1 2 3 4] copy swapBytes    => #[2 1 4 3]
     #u16(1 2 3 4) copy swapBytes => WordArray(256 512 768 1024)
     #u32(1 2 3 4) copy swapBytes => WordArray(256 512 768 1024)

swapLongs

swap long bytes inplace
i.e. #[a b c d e f g h...] will be changed inplace to #[d c b a h g f e ...].
- any partial longs at the end are not swapped.

Usage example(s):

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

swapLongsFrom: startByteIndex to: endByteIndex

swap longs (int32s) inplace
- any partial longs at the end are not swapped.
Swapping is from startIndex to (exclusiv) endIndex;
both being byte indices, 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]
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:4            => #[4 3 2 1 5 6 7 8 9]
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:5            => #[4 3 2 1 5 6 7 8 9]
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:6            => #[4 3 2 1 5 6 7 8 9]
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:7            => #[4 3 2 1 5 6 7 8 9]
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:1 to:8            => #[4 3 2 1 8 7 6 5 9]
     #[1 2 3 4 5 6 7 8 9 10] copy swapLongsFrom:1 to:11        => #[4 3 2 1 8 7 6 5 9 10]
     #[1 2 3 4 5 6 7 8 9 10 11] copy swapLongsFrom:1 to:12     => #[4 3 2 1 8 7 6 5 9 10 11]
     #[1 2 3 4 5 6 7 8 9 10 11 12] copy swapLongsFrom:1 to:13  => #[4 3 2 1 8 7 6 5 12 11 10 9]
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:5 to:8            => #[1 2 3 4 8 7 6 5 9]
     #[1 2 3 4 5 6 7 8 9] copy swapLongsFrom:5 to:10           => #[1 2 3 4 8 7 6 5 9]

     #u32(1 2 3 4 5 6 7 8 9) copy swapLongsFrom:1 to:3
     #u32(1 2 3 4 5 6 7 8 9) copy swapLongsFrom:1 to:4
     #u32(1 2 3 4 5 6 7 8 9) copy swapLongs

converting

asExternalBytes

in earlier times, this use to return protected memory
(i.e. it would not be garbage collected, and the user had to free it manually).
This was changed to now return garbage collected memory.

Usage example(s):

      #[1 2 3 4 5 6 7] asExternalBytes
      'Hello World' asExternalBytes
      'Hello World' asUnicodeString asExternalBytes

asExternalBytesUnprotected

Like asExternalBytes, but does not protect the bytes from the collector,
so the bytes are GARBAGE-COLLECTED
(i.e. free is called when the smalltalk object is no longer referenced).

Usage example(s):

     |x|
     x := 'fooBar' asExternalBytesUnprotected.
     ObjectMemory garbageCollect

asSingleByteString

return the receiver converted to a 'normal' string.
Raises an error if unrepresentable characters are encountered.
See also: #asSingleByteStringIfPossible and #asSingleByteStringReplaceInvalidWith:

Usage example(s):

     #[60 61 62 63] asSingleByteString
     #[60 61 62 63] asExternalBytes  asSingleByteString
     #[67 68 69 70] asIntegerArray asSingleByteString
     'abc' asText asSingleByteString
     (Unicode16String with:(Character value:16rFF)) asSingleByteString
     (Unicode16String with:(Character value:16rFFFF)) asSingleByteString

asSingleByteStringIfPossible

if possible, return the receiver converted to a 'normal' string.
It is only possible, if there are no characters with codePoints above 255 in the receiver.
If not possible, the (wideString) receiver is returned.

Usage example(s):

     #[67 68 69 70] asSingleByteStringIfPossible
     #[67 68 69 70] asIntegerArray asSingleByteStringIfPossible
     'hello' asUnicodeString asSingleByteStringIfPossible

asUUID

encoding & decoding

base64Decoded

decode myself from base64, returning a byteArray

Usage example(s):

     'abc' base64Encoded base64Decoded
     #[1 2 3] base64Encoded base64Decoded

base64DecodedString

decode myself from base64, returning a string.
convenient as most often, we want a string

Usage example(s):

     'abc' base64Encoded base64DecodedString
     #[1 2 3] base64Encoded base64DecodedString

base64Encoded

encode myself to base64, returning a string

Usage example(s):

     'abc' base64Encoded
     #[1 2 3] base64Encoded

decodeFrom: encodingSymbol

given the receiver encoded as described by encodingSymbol,
convert it into internal ST/X (unicode) encoding and return a corresponding CharacterArray.

encodeFrom: oldEncoding into: newEncoding

'äüö' encodeFrom:#iso8859 into:#utf8
('äüö' encodeFrom:#iso8859 into:#utf8) encodeFrom:#utf8 into:#unicode
'äüö' encodeInto:#iso8859.
'äüö' encodeFrom:#iso8859 into:#ebcdic
#[67 220 204] asString encodeFrom:#ebcdic into:#iso8859

encodeInto: newEncoding

'äüö' encodeInto:#utf8
('äüö' encodeInto:#utf8) decodeFrom:#utf8

utf8Decoded

Interpreting myself as an UTF-8 representation, decode and return the decoded string.

Usage example(s):

     #[16rC8 16rA0] utf8Decoded
     #[16rC8 16rA0] asString utf8Decoded
     #[16rC8 16rA0] asExternalBytes utf8Decoded
     (Character value:16r220) utf8Encoded utf8Decoded

     (Character value:16r800) utf8Encoded
     (Character value:16r220) utf8Encoded utf8Decoded

utf8DecodedWithTwoByteCharactersReplacedBy: replacementCharacter

Interpreting myself as an UTF-8 representation, decode and return
the decoded string. Suppress all 2-byte (above 16rFF) characters,
and replace them with replacementCharacter

Usage example(s):

     'Hello World' utf8Encoded
	utf8DecodedWithTwoByteCharactersReplacedBy:$@

     'Hello World здрависване' utf8Encoded
	utf8DecodedWithTwoByteCharactersReplacedBy:$@

     (Character value:16r220) utf8Encoded
	utf8DecodedWithTwoByteCharactersReplacedBy:(Character space)

     (Character value:16r220) utf8Encoded asExternalBytes copyButLast
	utf8DecodedWithTwoByteCharactersReplacedBy:(Character space)

filling & replacing

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.

replaceBytesWith: replacementCollection

replace elements from another collection, which must be byte-array-like.
Replace stops at whichever collection is smaller.

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

Usage example(s):

     (ByteArray new:10) replaceBytesWith:'hello'
     (ByteArray new:10) replaceBytesWith:'hello world bla bla bla'

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

replace elements in the receiver between index start and stop,
with elements taken from aCollection 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.

hashing

computeXorHashFrom: startIndex to: endIndex

compute and answer the 32bit 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.

Also NOTE:
used to return a 32bit hash on 32bit machines and a 64bit integer on 64bit cpus.
changed to return the same for all (in case hash values are used for other purposes).

Usage example(s):

     #[1 2 3 4] computeXorHashFrom:1 to:4.
     #[1 2 3 4] computeXorHashFrom:1 to:32.
     #[1 2 3 4] computeXorHashFrom:1 to:0.
     #[1 2 3 4 5] computeXorHashFrom:1 to:4.
     #[1 2 3 4 1 2 3 4] computeXorHashFrom:1 to:8.
     #[1 2 3 4 5 6 7 8] computeXorHashFrom:2 to:8.
     #[2 3 4 5 6 7 8] computeXorHashFrom:1 to:7.
     #[2 3 4 5 6 7 8] computeXorHashFrom:1 to:8.

hash

the code below is actually not doing what was intended (to take the hashes of the first 16

Usage example(s):

However, we will not change it, but keep it that way, in case the hashvalue already found

Usage example(s):

	#[1 2 3 4] hash
	#[1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 ] hash

	#[1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4
	  1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 ] hash

	#[1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4
	  1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1] hash

inspecting

inspector2TabForImage
( an extension from the stx:libtool package ): a tab, showing the png image read from the receiver

misc

copyToEndInto: aStream

copy all of myself into aStream. Compatibility with Stream

swapLongAt: byteIndex

swap the byteOrder of a long.
The index is a smalltalk index (i.e. 1-based).
i.e. #[ ... a b c d ...] will be changed inplace to #[... d c b a ...].

Usage example(s):

     #[1 2 3 4 5 6 7 8 9 0] swapLongAt:1   => #[4 3 2 1 5 6 7 8 9 0]
     #[1 2 3 4 5 6 7 8 9 0] swapLongAt:4   => #[1 2 3 7 6 5 4 8 9 0]

printing & storing

hexPrintOn: aStream

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

Usage example(s):

      #[1 2 3 4 10 17] hexPrintOn:Transcript

Usage example(s):

     |s|
     s := String streamContents:[:s | #[1 2 3 4 10 17] hexPrintOn:s].
     ByteArray fromHexString:s

hexPrintOn: aStream withSeparator: aSeparatorStringOrCharacterOrNil

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

Usage example(s):

      #[1 2 3 4 10 17] hexPrintOn:Transcript withSeparator:$:
      #[1 2 3 4 10 17] hexPrintOn:Transcript withSeparator:(Character space)
      #[1 2 3 4 10 17] hexPrintOn:Transcript withSeparator:'-'
      #[1 2 3 4 10 17] hexPrintOn:Transcript withSeparator:nil
      'hello' hexPrintOn:Transcript withSeparator:'.'

hexPrintString

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

Usage example(s):

     #[1 2 3 4 10 17] hexPrintString                            -> '010203040A11'
     ByteArray fromHexString:(#[1 2 3 4 10 17] hexPrintString)  -> #[1 2 3 4 10 17]
     'hello' hexPrintString                                     -> '68656C6C6F'
     'hello' hexPrintStringWithSeparator:' '                    -> '68 65 6C 6C 6F'

hexPrintStringWithSeparator: aSeparatorStringOrCharacterOrNil

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

Usage example(s):

      #[1 2 3 4 10 17] hexPrintStringWithSeparator:$:
      #[1 2 3 4 10 17] hexPrintStringWithSeparator:Character space
      #[1 2 3 4 10 17] hexPrintStringWithSeparator:' - '
      #[1 2 3 4 10 17] hexPrintStringWithSeparator:nil
      'hello' hexPrintStringWithSeparator:'.'

private

reportError: failReason with: parameter: common helper
slowReplaceBytesFrom: startArg to: stopArg with: sourceBytes startingAt: sourceIndex: fallback if primitive code fails

queries

containsNon7BitAscii

return true, if the underlying collection contains elements longer than 7 bits
(i.e. if it is non-ascii)

containsNon8BitElements

return true, if the underlying structure contains elements larger than a single byte

defaultElement

isAllocated

for compatibility with ExternalBytes

isNull

for compatibility with ExternalBytes

isValidUTF8

returns true, if the receiver contains a valid UTF8 encoded string

Usage example(s):

     'abc' isValidUTF8
     'abcöäü' isValidUTF8
     'abcöäü' utf8Encoded isValidUTF8
     (Character value:16r800) utf8Encoded isValidUTF8
     (Character value:16r1000) utf8Encoded isValidUTF8

     1 to:255 do:[:c1 |
	 1 to:255 do:[:c2 |
	     1 to:255 do:[:c3 |
		 self assert:(c1 asCharacter , c2 asCharacter , c3 asCharacter) utf8Encoded isValidUTF8
	     ]
	 ]
     ]

     |s|
     1 to:10000 do:[:c1 |
	 1 to:255 do:[:c2 |
	     s := (c1 asCharacter , c2 asCharacter).
	     self assert:s utf8Encoded isValidUTF8
	 ]
     ]

referencesAny: aCollection

redefined to speed up searching when many of my instances are present

Usage example(s):

	'abc' referencesAny:#()

sizeInBytes

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

utf8DecodedSize

return the number of characters needed when this string is
decoded from UTF-8

Usage example(s):

     'hello world' asByteArray utf8DecodedSize
     'ä' utf8Encoded asByteArray utf8DecodedSize
     'äΣΔΨӕἤῴ' utf8Encoded asByteArray utf8DecodedSize
     'äΣΔΨӕἤῴ' utf8Encoded asUnicode16String utf8DecodedSize

testing

isByteCollection: return true, if the receiver has access methods for bytes;
This is different from 'self class isBytes',
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.
isSingleByteCollection: return true, if the receiver has access methods for bytes;
i.e. #at: and #at:put: accesses a byte and are equivalent to #byteAt: and byteAt:put:
and #replaceFrom:to: is equivalent to #replaceBytesFrom:to:.
This is different from 'self class isBytes',
true is returned here - the method is redefined from Object.

visiting

acceptVisitor: aVisitor with: aParameter: dispatch for visitor pattern; send #visitByteArray:with: to aVisitor.

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 21 Dec 2024 14:54:05 GMT

Smalltalk/X Webserver

Documentation of class 'UninterpretedBytes':

Class: UninterpretedBytes

Inheritance:

Description:

copyright

Class protocol:

Instance protocol: