eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ImmutableByteArray':

Home

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

Class: ImmutableByteArray


Inheritance:

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

Package:
stx:libbasic
Category:
System-Compiler-Support
Version:
rev: 1.25 date: 2018/03/23 10:45:38
user: cg
file: ImmutableByteArray.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


By default, byte array literals in smalltalk are mutable objects. That
may lead to some subtle (and hard to find errors), if some method passes
a literal byte-array object as argument to someone else, who changes the
bytearray using at:put: like messages. Since the bytearray object is kept in
the first methods literals, the bytearray constant has now been changed without
having the method's sourcecode reflect this. Thus, the method will
behave differently from what its source may make you think.

To help finding this kind of 'feature/bug', the compiler can be
configured to create instances of this ImmutableByteArray instead of ByteArrays
for literals. Instances of ImmutableByteArray catch storing accesses and
enter the debugger. Although useful, this feature is disabled by default
for compatibility to other smalltalk implementations.
(Also, if turned on, this makes inspecting bytearray literals entered in
 a workspace somewhat strange: you cannot modify it any longer).

Turn the ImmutableArray feature on, by setting the Parser's class variable
'ArraysAreImmutable' to true or use the new launchers settings menu.

This class should be used only by the compiler.

ATTENTION:
    there may be still code around which checks for explicit class being ByteArray
    (both in Smalltalk and in primitive code). All code like foo 'class == ByteArray'
    or '__isByteArray()' will not work with ImmutableByteArrays - consider using '__isByteArrayLike()'.
    A somewhat better approach would be to either add a flag to the object (mutability)
    and check this dynamically (expensive) or to place immutable objects into a readonly
    memory segment (the good solution). We will eventually implement the second in the future...


Related information:

    ImmutableString
    ImmutableArray
    Parser
    Scanner

Class protocol:

instance creation
o  fromPackedString: aString
(comment from inherited method)
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 ;-)

queries
o  mutableClass
answer an equivalent mustable class

testing
o  hasImmutableInstances


Instance protocol:

accessing
o  at: index put: value
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  basicAt: index put: value
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  byteAt: index put: value
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  doubleAt: index put: anInteger
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  doubleAt: index put: anInteger MSB: msb
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  floatAt: index put: anInteger
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  floatAt: index put: anInteger MSB: msb
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  signedInt128At: index put: anInteger MSB: msb
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  signedInt16At: index put: anInteger MSB: msb
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  signedInt32At: index put: anInteger MSB: msb
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  signedInt64At: index put: anInteger MSB: msb
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  unsignedInt128At: index put: anInteger MSB: msb
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  unsignedInt16At: index put: anInteger
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  unsignedInt16At: index put: anInteger MSB: msb
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  unsignedInt32At: index put: anInteger
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  unsignedInt32At: index put: anInteger MSB: msb
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  unsignedInt64At: index put: anInteger
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

o  unsignedInt64At: index put: anInteger MSB: msb
Trigger an error if an immutable bytearray is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger (or proceed in an exception handler).

converting
o  asByteArray
return the receiver as a (mutable) byteArray
usage example(s):
     #[1 2 3 4] asImmutableByteArray asByteArray

o  asImmutableByteArray
that's what I am-

o  asMutableCollection
return a writable copy of myself

o  beImmutable
that's what I am

o  beMutable
you never go back

o  beUnsigned
that's what I am-
usage example(s):
        #[1 2 3 128 255] asImmutableByteArray beUnsigned

copying
o  postCopy
when copied, make me a real (mutable) ByteArray

o  postDeepCopy
when copied, make me a real (mutable) ByteArray

o  shallowCopy
when copying, return a real (mutable) ByteArray
usage example(s):
     #[1 2 3 4] asImmutableByteArray shallowCopy

printing & storing
o  displayOn: aGCOrStream
what a kludge - Dolphin and Squeak mean: printOn: a stream;

private
o  species
Copies should be mutable

o  speciesForCopy
Copies should be mutable

queries
o  isImmutable

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

specials
o  become: anotherObject
trigger an error if I should become something else
(this would be an even more tricky manipulation)

o  becomeNil
trigger an error if I should become nil
(this would be an even more tricky manipulation)

o  becomeSameAs: anotherObject
trigger an error if I should become something else
(this would be an even more tricky manipulation)



ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Tue, 20 Nov 2018 15:51:36 GMT