eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Array':

Home

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

Class: Array


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.189 date: 2017/06/12 11:44:18
user: mawalch
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:

instance creation
o  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.

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

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


Instance protocol:

accessing
o  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:

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

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

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

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

o  asImmutableArray
return a write-protected copy of myself

o  asNewArray
return the receiver as a unique new array.

o  beImmutable
make myself write-protected

copying
o  , aCollection

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

enumerating
o  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

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

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

o  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

o  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

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

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

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

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

filling & replacing
o  from: index1 to: index2 put: anObject
reimplemented for speed if receiver is an Array

o  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

inspecting
o  inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )
returns a string to be shown in the inspector's selection list

printing & storing
o  displayStringName
redefinable helper for displayString

o  printOn: aStream
append a printed representation of the receiver to aStream

o  storeArrayElementOn: aStream
Store as element of an array. Omit the leading '#'
usage example(s):
     #(1 2 3 4 5) storeOn:Transcript
     #(1 2 3 4 5) storeArrayElementOn:Transcript

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

queries
o  basicSize
return the number of indexed elements in the receiver

o  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

o  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

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

searching
o  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

o  identityIndexOf: anElement startingAt: start
search the array for anElement; return index if found, 0 otherwise
- reimplemented for speed

o  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

o  indexOf: anElement startingAt: start
search the array for anElement; return index if found, 0 otherwise
- reimplemented for speed

o  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

testing
o  includes: anObject
return true, if the argument, anObject is contained in the array
- reimplemented for speed

o  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

o  isArray
return true, if the receiver is some kind of array (or weakArray etc).
true is returned here.

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

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

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)

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

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

tracing
o  traceInto: aRequestor level: level from: referrer
double dispatch into tracer, passing my type implicitely in the selector



ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Fri, 22 Mar 2019 10:06:21 GMT