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
               |
               +--CacheDictionaryWithLimitedLifetime::ArrayWithLimitedLiveTime
               |
               +--ChangeNotificationParameter
               |
               +--ChangeSet::ChangePair
               |
               +--Class::ArrayWithSequenceNumberValidation
               |
               +--DoWhatIMeanSupport::InputCompletionResult
               |
               +--HTMLElement
               |
               +--ImmutableArray
               |
               +--JavaScriptEnvironment::Array
               |
               +--ScannerTable
               |
               +--TSMultiTreeNode::ValueArray
               |
               +--TraceBuffer
Package:
stx:libbasic
Category:
Collections-Arrayed
Version:
rev: 1.249 date: 2024/03/11 14:23:53
user: cg
file: Array.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


Instances of Array store general objects (actually: references to them).
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.
Notice, that the compilers are configured by default
to create ImmutableArray instances for literals.

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)



[complexity:]
    access by index:                O(1)
    access first:                   O(1)
    access last:                    O(1)
    insertion at either end:        -
    removal at either end:          -
    insertion in the middle:        -
    removal in the middle:          -
    searching:                      O(n)
    min/max:                        O(n)


copyright
COPYRIGHT (c) 1989 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.

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

o  readFrom: aStringOrStream onError: exceptionBlock
return a new Array, reading a printed representation from aStringOrStream.

Usage example(s): 

	self readFrom:'#(1 abc ''def'' 2.0 true nil)'.
	self readFrom:{Dictionary new. 'two'->2. self} storeString.
	self readFrom:'#[1 2 3 4]'.                          --- must fail

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

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

o  asImmutableCollection
return a write-protected copy of myself

Usage example(s): 

	(#(1 2 3), #(1.1 1.2 1.3)) asImmutableCollection

o  asNewArray
return the receiver as a unique new array.

Usage example(s): 

     |a b|

     a := #(1 2 3 4).
     b := a asNewArray.
     self assert:(a = b).
     self assert:(a == b) not

o  beImmutable
make myself write-protected

copying
o  , aCollection
(comment from inherited method)
return a new collection formed from concatenating the receiver with the argument.
The class of the new collection is determined by the
receiver's class, so mixing classes is possible, if the second collection's
elements can be stored into instances of the receiver's class.

o  copyEmptyAndGrow: size
performance optimization:
Arrays are always grown to size after #new: (containing nil elements)

Usage example(s): 

     #('some' 'text' 'bla') copyEmptyAndGrow:6 => #(nil nil nil nil nil nil)

enumerating
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  nonNilElementsDo: aBlock
evaluate the argument, aBlock for each non-nil element in the collection.
- reimplemented for speed, since this is used by many higher
level collections

Usage example(s): 

     #(1 2 3 nil nil nil 4 5 nil 6 7 nil nil) nonNilElementsDo:#transcribeCR
     ((Array new:10000) at:500 put:'xxx';yourself) nonNilElementsDo:#transcribeCR

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

Usage example(s): 

     #(1 2 3 nil nil nil 4 5 nil 6 7 nil nil) nonNilElementsDoWithIndex:[:v :i | (i->v) transcribeCR]
     ((Array new:10000) at:500 put:'xxx';yourself) nonNilElementsDoWithIndex:[:v :i | (i->v) transcribeCR]

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

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  = anArray
Compare the receiver with the argument and return true if the
receiver is equal to the argument (i.e. has the same size and elements).
Otherwise return false.
Redefined for speed, if the argument is of the same class as myself
(and there are no named instvars to compare)

Usage example(s): 

     #() = nil     false
     #() = 123     false
     #() = #()     true
     #(1) = #()    false
     #() = #(1)    false
     #(1) = #(1)   true
     #(1 2 3 4) = #(1 2 3 4)             true
     #(1 2 3.0 4 5) = #(1 2 3 4 5)       true
     #(1 2 3.0 4.0 5.0) = #(1 2 3 4 5)   true
     #(1 2 3 4 5.0) = #(1 2 3 4 5)       true
     #(1.0 2 3 4 5.0) = #(1 2 3 4 5)     true
     #(1.0 2 3 4 5.0) = #(1.0 2 3 4 5.0) true

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 aCollection starting at repStart.
Return the receiver.
Reimplemented for speed if both receiver and aCollection are Arrays

inspecting
o  inspector2GraphTabUseful
( an extension from the stx:libtool package )
(comment from inherited method)
is a graph tab useful (in general for this type of collection)?

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

Usage example(s): 

     #(1 2 $a $Š 'hello' sym kewordSymbol:with: #'funny symbol') printString
     #(1 2 $a [1 2 3] true false nil #true #false #nil) printString
     #(1 2 $a [1 2 3] true false nil #true #false #nil) printOn: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.

private array element printing
o  displayAsArrayElementOn: aStream
Display myself as an element of an array. Omit the leading '#'

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

o  printAsArrayElementOn: aStream
Print myself as element of an array. Omit the leading '#'

o  storeAsArrayElementOn: 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 storeOn: #true #false #nil #'hokus pokus fidibus') storeAsArrayElementOn:Transcript

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

Usage example(s): 

     #(1 2 3 4) perform:#basicSize

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

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.

Usage example(s): 

     #(1 2 3 4) perform:#size
     self assert:(TraceBuffer new:10) size == 20

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  identityIndexOf: anElement startingAt: start step: stepArg
search the array for anElement; return index if found, 0 otherwise
- reimplemented for speed

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

o  indexOf: searchedElement startingAt: start endingAt: stop
search the array for searchedElement in the range start..stop;
Return the index if found, 0 otherwise.
- reimplemented for speed when searching in OrderedCollections

o  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

o  indexOfNonNilElementStartingAt: start
search the array for the first non-nil element;
return index if found, 0 otherwise
- reimplemented for speed

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

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)

Usage example(s): 

	#(1 2 3 4 (a b (aa bb cc) c d) 5 6 7) isLiteral

	|arr|

	arr := #(nil 1 2 3 4 5 6 7).
	arr at:1 put:arr.
	arr isLiteral

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


ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Thu, 21 Nov 2024 16:46:36 GMT