Class: Array

• Inheritance
• Description
• Warning
• Related information
• Class protocol
  • instance creation
  • queries
• Instance protocol
  • accessing
  • converting
  • copying
  • enumerating
  • filling & replacing
  • inspecting
  • printing & storing
  • private array element printing
  • queries
  • searching
  • testing
  • tracing

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--Array
               |
               +--ChangeNotificationParameter
               |
               +--Class::ArrayWithSequenceNumberValidation
               |
               +--DoWhatIMeanSupport::InputCompletionResult
               |
               +--HTMLElement
               |
               +--ImmutableArray
               |
               +--JavaScriptEnvironment::Array
               |
               +--ScannerTable
               |
               +--TSMultiTreeNode::ValueArray
               |
               +--TraceBuffer

Package:

stx:libbasic

Category:

Collections-Arrayed

Version:

rev: 1.197 date: 2019/03/29 11:26:50

user: stefan

file: Array.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

Instances of Array store general objects;
an array's size is fixed, therefore add:/remove: are not allowed.
(actually, #add: is implemented for compatibility with smalltalks which
 provide it, but it is very slow and outputs an annoying warning message...)

Access to the individual elements is via an integer index,
using the well-known access messages #at: and #at:put:.

Since Arrays are used very often in the system (either directly or a data-container
of more complex collection classes), some methods have been tuned by reimplementing
them as primitives. Also, the compiler inline-codes some operations
(especially: the above accessing messages).

Notice that Array is a built-in class
(i.e. the VM knows about its representation).
Therefore it is NOT possible to add named instance variables or change Arrays inheritance.
However, subclassing is allowed of course
- even with added named instance variables.

Literal arrays (i.e. array-constants) are entered in source as:

    #( element1 element2 ... element-N)

where each element must be itself a literal constant.
Array, symbol and byteArray constants within an array can be written
without the initial #-character.
In addition, true, false and nil are also allowed as array-literal.

Examples:
  #(1 2 3)                -> 3 elements: 1, 2 and 3
  #('foo' 2 (1 2))        -> 3 elements: a String, 2 and anotherArray
  #('foo' #(1 2) #foo)    -> 3 elements: a String, another array and a symbol
  #('foo' (1 2) foo)      -> same as above
  #(nil true #true)       -> 3 elements: nil, true and a symbol (watch out)
  #(two [3 3 3] (4 4 4))  -> 3 elements: a symbol, a byteArray and another array

Also, a syntactic sugar piece allows for Array instances to be created dynamcially
at runtime with the brace syntax:

    { expr1 . expr2 . ... . expr-N }

where each expr-i evaluates to an element of the new array instance.
Notice that the expressions are separated by a period.
Semantically, this is equivalent to ``Array with:expr1 with:expr2 ... with:expr-N''
Examples:
    { 1 . 2 . 3 }         -> a new 3 element array; similar to #( 1 2 3 ),
                             but in contrast, a new array instance is created
    {
        { 'foo' . [ Transcript showCR:'foo' ] } .
        { 'bar' . [ Transcript showCR:'bar' ] }
        { 'baz' . [ Transcript showCR:'baz' ] }
    }
                          -> a new 3 element array, consisting of 3 new
                             2-element array instances, consisting of a string
                             and a block each

[memory requirements:]
    OBJ-HEADER + (size * ptr-size)

Warning:

read the warning about 'growing fixed size collection'
in ArrayedCollection's documentation

Related information:

    OrderedCollection
    ByteArray
    FloatArray
    DoubleArray
    IntegerArray
    BitArray
    CharacterArray
    String

Class protocol:

 basicNew: anInteger

return an instance of myself with anInteger indexed variables.
Since Array-creation is so common (all other collections use them),
it seems worth to have a specially tuned version here.

 new: anInteger

return an instance of myself with anInteger indexed variables.
Redefined here to save a few cycles when executed.
(Since this is often called, its worth giving it an extra ilc-slot.
Future versions of stc will do this automatically.)

 isBuiltInClass

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

Instance protocol:

 at: index

return the indexed instance variable with index, anInteger.
Reimplemented here to avoid the additional at:->basicAt: send
(which we can do here, since when arriving here, #at: is obviously not
redefined in a subclass).
This method is the same as basicAt:.

usage example(s):

^ super at:index

usage example(s):

knowing that super-#at: does #basicAt:

 at: index put: anObject

store the 2nd arg, anObject as indexed instvar with index, anInteger.
Returns anObject (sigh).
Reimplemented here to avoid the additional at:put:->basicAt:put: send
(which we can do here, since when arriving here, #atput:: is obviously not
redefined in a subclass).
This method is the same as basicAt:put:.

usage example(s):

^ super at:index put:anObject

usage example(s):

knowing that super-#at:put: does #basicAt:put:

 basicAt: index

return the indexed instance variable with index, anInteger
- added here for speed

 basicAt: index put: anObject

store the 2nd arg, anObject as indexed instvar with index, anInteger.
Returns anObject (sigh).
- added here for speed

 asArray

return the receiver as an array - that's the receiver itself.
Notice: Use asNewArray, if you intent to modify the returned collection.

 asImmutableArray

return a write-protected copy of myself

 asImmutableCollection

return a write-protected copy of myself

 asNewArray

return the receiver as a unique new array.

 beImmutable

make myself write-protected

 , aCollection

 copyWith: something

return a new collection containing the receiver's elements
and the single new element, newElement.
This is different from concatentation, which expects another collection
as argument, but equivalent to copy-and-addLast.
Reimplemented for speed if receiver is an Array.
(since the inherited copyWith uses replaceFromTo:, which is also
tuned, it is questionable, if we need this)

 addAllNonNilElementsTo: aCollection

add all nonNil elements of the receiver to aCollection.
Return aCollection.
Redefined here for slightly more speed.

usage example(s):

#(1 2 3 4 5 1 2 3 symbol 'string' nil) addAllNonNilElementsTo:Set new

 addAllTo: aCollection

add all elements of the receiver to aCollection.
Return aCollection.
Redefined here for slightly more speed.

 do: aBlock

evaluate the argument, aBlock for each element in the collection.
- reimplemented for speed, since this is used by many higher
level collections

 from: start to: stop do: aBlock

evaluate the argument, aBlock for the elements starting at index start
up to (and including) stop in the collection.
- reimplemented for speed, since this is used by many higher
level collections

 from: start to: stop reverseDo: aBlock

evaluate the argument, aBlock for the elements starting at index start
up to (and including) stop in the collection. Step in reverse order.
- reimplemented for speed

 keysAndValuesDo: aBlock

evaluate the argument, aBlock for each element in the collection.
Pass both index and element to the block.
- reimplemented for speed

 modifyingTraverse: aBlock

Evaluate aBlock for every element that is not an Array,
and recursively traverse Arrays.

aBlock may return the original element or a new element.
If a new element is returned, the element is changed to the new element.

 recursiveCollect: aBlock

return a copy of the receiver where non-array elements
are replaced by whatever aBlock returns,
and array elements are recursively processed by this method again.
Useful to rewrite ui specs on the fly

usage example(s):

#(1 2 3) recursiveCollect:[:el | el == 2 ifTrue:20 ifFalse:el] #(1 2 (1 2 (1 2 (1 2 3) 3) 3) 3) recursiveCollect:[:el | el == 2 ifTrue:20 ifFalse:el] #(1 2 (1 2 (1 2 (1 2 3) 3) 3) 3) recursiveCollect:[:el | el * 2]

 reverseDo: aBlock

evaluate the argument, aBlock for each element in the collection in reverse order.
- reimplemented for speed

 traverse: aBlock

Evaluate aBlock for every element that is not an Array,
and recursively traverse Arrays.
Implemented here to support better search for selectors in
literal arrays - might be a good idea to move it up in the collection
hierarchy, since this may be a useful method for other collections
as well.

 from: index1 to: index2 put: anObject

reimplemented for speed if receiver is an Array

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

replace elements in the receiver between index start and stop,
with elements taken from replacementCollection starting at repStart.
Return the receiver.
Reimplemented for speed if both receiver and aCollection are Arrays

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

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

 displayStringName

redefinable helper for displayString

 printOn: aStream

append a printed representation of the receiver to aStream

 storeOn: aStream

append a printed representation of the receiver to aStream,
which allows reconstructing it via readFrom:.
Redefined to output a somewhat more user friendly string.

 displayArrayElementOn: aStream

Display myself as an element of an array. Omit the leading '#'

 displayElement: element on: aStream

print a representation of the element on aGCOrStream.
Redefined to use ST syntax for symbols inside Array literals.

 printArrayElementOn: aStream

Print myself as element of an array. Omit the leading '#'

usage example(s):

#(1 2 3 4 5 Symbol String Integer (7 8 9)) print:Transcript #(1 2 3 4 5) printArrayElementOn:Transcript

 storeArrayElementOn: aStream

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

usage example(s):

#(1 2 3 4 5 Symbol String Integer (7 8 9)) storeOn:Transcript #(1 2 3 4 5) storeArrayElementOn:Transcript

 basicSize

return the number of indexed elements in the receiver

 includes: anObject

return true, if the argument, anObject is contained in the array
- reimplemented for speed

 includesIdentical: anObject

return true, if the argument, anObject is contained in the array
uses #== (instead of #=) when comparing; i.e. the search is for
the object, not some object being equal.

usage example(s):

#(1 2 3 4 5) includes:3.0 #(1 2 3 4 5) includesIdentical:3.0

 isEmpty

return true if the receiver contains no elements.
Reimplemented here for performance.

 isEmptyOrNil

return true if the receiver contains no elements.
Reimplemented here for performance.

 notEmpty

return true if the receiver contains elements.
Reimplemented here for performance.

 notEmptyOrNil

return true if the receiver contains elements.
Reimplemented here for performance.

 refersToLiteral: aLiteral

return true if the receiver or recursively any array element in the
receiver refers to aLiteral (i.e. a deep search)

usage example(s):

#(1 2 3) refersToLiteral:#foo #(1 2 3 foo bar baz) refersToLiteral:#foo #(1 2 3 (((bar foo))) bar baz) refersToLiteral:#foo

 refersToLiteralMatching: aMatchPattern

return true if the receiver or recursively any array element in the
receiver is symbolic and matches aMatchPattern (i.e. a deep search)

usage example(s):

#(1 2 3) refersToLiteralMatching:#foo #(1 2 3 foo bar baz) refersToLiteralMatching:#foo #(1 2 3 (((bar foo))) bar baz) refersToLiteralMatching:#foo

 size

return the number of indexed elements in the receiver.
Reimplemented here to avoid the additional size->basicSize send
(which we can do here, since when arriving here, #size is obviously not
redefined in a subclass).
This method is the same as basicSize.

 identityIndexOf: anElement or: alternative

search the array for anElement or alternative;
return the index of anElement if found, or the index of anAlternative,
if not found. If anAlternative is also not found, return 0.
This is a special interface for high-speed searching in an array
and at the same time searching for an empty slot.
Do not use this method for your application classes, since it is
not portable (i.e. other smalltalks do not offer this)

usage example(s):

#(1 2 3 4 5 6 7 8 9) identityIndexOf:3 or:5 #(1 2 0 4 5 6 7 8 9) identityIndexOf:3 or:5 #(1 2 0 4 5 6 7 3 9) identityIndexOf:3 or:5 #(1 2 3 4 5 nil 7 3 9) identityIndexOf:3 or:nil #(1 2 nil 4 5 6 7 3 9) identityIndexOf:3 or:nil #(1 2 nil 4 5 6 7 8 9) identityIndexOf:3 or:nil #() identityIndexOf:3 or:nil #(1 2) identityIndexOf:3 or:nil

 identityIndexOf: anElement startingAt: start

search the array for anElement; return index if found, 0 otherwise
- reimplemented for speed

 identityIndexOf: anElement startingAt: start endingAt: stop

search the array for anElement in the range start..stop;
return the index if found, 0 otherwise.
- reimplemented for speed when searching in OrderedCollections

 indexOf: anElement startingAt: start

search the array for anElement; return index if found, 0 otherwise
- reimplemented for speed

 indexOf: anElement startingAt: start endingAt: stop

search the array for anElement in the range start..stop;
Return the index if found, 0 otherwise.
- reimplemented for speed when searching in OrderedCollections

 indexOf: anElement startingAt: start step: stepArg

search the array for anElement; return index if found, 0 otherwise
- reimplemented for speed

usage example(s):

#(1 2 3 4 5 6 7) indexOf:5 startingAt:1 step:2 #(1 2 3 4 5 6 7) indexOf:6 startingAt:1 step:2 #(1 2 3 4 5 6 bla) indexOf:#bla startingAt:1 step:2 #(1 2 3 4 5 6 'bla') indexOf:'bla' startingAt:1 step:2 #(1 2 3 4 5 6 'bla') indexOf:#bla startingAt:1 step:2

 isArray

return true, if the receiver is some kind of array (or weakArray etc).
true is returned 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)

 traceInto: aRequestor level: level from: referrer

double dispatch into tracer, passing my type implicitely in the selector