Class: ImmutableArray

• Inheritance
• Description
• Related information
• Class protocol
  • queries
  • testing
• Instance protocol
  • accessing
  • converting
  • copying
  • copying-private
  • inspecting
  • private
  • queries
  • specials

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--Array
               |
               +--ImmutableArray

Package:

stx:libbasic

Category:

System-Compiler-Support

Version:

rev: 1.48 date: 2019/07/21 06:30:32

user: cg

file: ImmutableArray.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

By default, array literals in smalltalk are mutable objects. That
may lead to some subtle (and hard to find errors), if some method passes
a literal array constant as argument to someone else, who changes the
array using at:put: like messages. Since the array object is kept in
the first methods literals, the array 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 ImmutableArray instead of Arrays
for array literals. Instances of ImmutableArray 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 array literals entered in
 a workspace somewhat strange: you cannot modify it any longer).

Turn the ImmutableArray feature on by setting the Parsers 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 Array
    (both in Smalltalk and in primitive code). All code like foo 'class == Array'
    or '__isArray' will not work with ImmutableArrays; consider using '__isArrayLike'.
    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
    ImmutableByteArray
    Parser
    Scanner

Class protocol:

 mutableClass

answer an equivalent mustable class

 hasImmutableInstances

Instance protocol:

 at: index put: value

Trigger an error if an immutable array is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger.

 basicAt: index put: value

Trigger an error if an immutable array is stored into.
The store will be performed (for compatibility reasons) if you continue
in the debugger.

 asArray

return the receiver as an array. I am already.
Use asNewArray, or asMutableCollection if you need a copy for modification

 asImmutableArray

 asImmutableCollection

(comment from inherited method)
return a write-protected copy of myself

 asMutableCollection

return a writable copy of myself

 asNewArray

return the receiver as a unique new array.

 beImmutable

that's what I am

 beMutable

you never go back

 shallowCopy

when copying, return a real (mutable) Array

usage example(s):

#(1 2 3 4) asImmutableArray shallowCopy

 postCopy

when copied, make it me a real (mutable) Array

 postDeepCopy

when copied, make it me a real (mutable) Array

 inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )

returns a string to be shown in the inspector's list

 species

Copies should be mutable

 speciesForCopy

Copies should be mutable

 isImmutable

return true, if the receiver is immutable.
Since I am an immutable array, return always true here

 isLiteral

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

 become: anotherObject

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

 becomeNil

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

 becomeSameAs: anotherObject

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

 grow: newSize

trigger an error if I should change my size