eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ArrayedCollection':

Home

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

Class: ArrayedCollection


Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--Array
            |
            +--BitArray
            |
            +--FileDirectory::DirectoryEntry
            |
            +--LazyArray
            |
            +--UninterpretedBytes
            |
            +--WeakArray

Package:
stx:libbasic
Category:
Collections-Abstract
Version:
rev: 1.74 date: 2018/04/13 12:07:28
user: stefan
file: ArrayedCollection.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


ArrayedCollection is an abstract superclass for all collections where
the elements can be accessed via an integer index,
AND the collection is a fixed size collection.

Those fixed size collections cannot easily grow, since they store the
elements directly within the object and a grow operation can only be done
by #becoming another object.
(many other collections keep a reference to the physical container,
 which can be easily replaced)


    Therefore, you SHOULD rewrite any application that does this,
    to make use of OrderedCollections or any other collection which can grow fast.
    To remind you of that, a warning message is sent to stdErr,
    whenever such an operation is performed (see #grow).

    Also note that some other Smalltalk systems do NOT allow
    fix size collection to change their size, and that future
    ST/X versions may be changed to trigger an error
    (instead of a warning) in those situations.


Warning:


currently, ST/X supports growing fix-size collections
(such as Arrays, ByteArrays and Strings).
However, this is done in a very slow way (using #become).
Become is a very slow operation in a direct-pointer Smalltalk system
(which ST/X and many other 'modern' Smalltalks are).

Related information:

    OrderedCollection
    Array

Class protocol:

instance creation
o  newFrom: aCollection
Return an instance of me containing the same elements as aCollection.
usage example(s):
     Array newFrom: #[1 2 3]
     #[1 2 3] as: Array      
     #[1 2 3] as: ByteArray  
     #($c  $h  $r) as: String 
     #($c  $h  $r) as: Text

o  newWithSize: size
return a new collection of size.
For variable size collections, this is different from #new:,
in that #new: creates an empty collection with preallocated size,
while #withSize: creates a non empty one.
usage example(s):
     (OrderedCollection new:10)  
     (OrderedCollection newWithSize:10) 
     (Array new:10) 
     (Array newWithSize:10) 

o  with: element
return a new SequenceableCollection with one element:anObject
usage example(s):
     OrderedCollection with:1
     SortedCollection with:99 

o  with: first with: second
return a new SequenceableCollection with two elements
usage example(s):
     OrderedCollection with:1 with:2
     SortedCollection with:99 with:3
     Array with:1 with:2

o  with: a1 with: a2 with: a3
return a new SequenceableCollection with three elements
usage example(s):
     OrderedCollection with:1 with:2 with:3
     Array with:1 with:2 with:3

o  with: a1 with: a2 with: a3 with: a4
return a new SequenceableCollection with four elements
usage example(s):
     OrderedCollection with:1 with:2 with:3 with:4
     Array with:1 with:2 with:3 with:4

o  with: a1 with: a2 with: a3 with: a4 with: a5
return a new SequenceableCollection with five elements
usage example(s):
     OrderedCollection with:1 with:2 with:3 with:4 with:5
     Array with:1 with:2 with:3 with:4 with:5

o  with: a1 with: a2 with: a3 with: a4 with: a5 with: a6
return a new SequenceableCollection with six elements
usage example(s):
     OrderedCollection with:1 with:2 with:3 with:4 with:5 with:6
     Array with:1 with:2 with:3 with:4 with:5 with:6

o  with: a1 with: a2 with: a3 with: a4 with: a5 with: a6 with: a7
return a new SequenceableCollection with seven elements
usage example(s):
     OrderedCollection with:1 with:2 with:3 with:4 with:5 with:6 with:7
     Array with:1 with:2 with:3 with:4 with:5 with:6 with:7

o  with: a1 with: a2 with: a3 with: a4 with: a5 with: a6 with: a7 with: a8
return a new SequenceableCollection with eight elements
usage example(s):
     OrderedCollection with:1 with:2 with:3 with:4 with:5 with:6 with:7 with:8
     Array with:1 with:2 with:3 with:4 with:5 with:6 with:7 with:8

o  with: a1 with: a2 with: a3 with: a4 with: a5 with: a6 with: a7 with: a8 with: a9
return a new SequenceableCollection with nine elements
usage example(s):
     OrderedCollection with:1 with:2 with:3 with:4 with:5 with:6 with:7 with:8 with:9
     Array with:1 with:2 with:3 with:4 with:5 with:6 with:7 with:8w ith:9

o  withAll: aCollection
return a new Collection with all elements taken from the argument,
aCollection
usage example(s):
     OrderedCollection withAll:#(1 2 3 4 5)
     SortedCollection withAll:#(99 17 53 1 101) 

queries
o  growIsCheap
return true, if this collection can easily grow
(i.e. without a need for become:).
Since this is the superclass of all indexed fix-size collections,
return false here.

o  isAbstract
Return if this class is an abstract class.
True is returned for ArrayedCollection here; false for subclasses.
Abstract subclasses must redefine this again.


Instance protocol:

adding & removing
o  addAll: aCollection
add all elements of the argument, aCollection to the receiver.
Returns the argument, aCollection (sigh).

Redefined here, to perform only a single slow grow operation
usage example(s):
        #(1 2 3 4) addAll:#(5 6 7 8); yourself

o  removeAll
remove all elements from the receiver. Returns the receiver.

For ArrayedCollections (which are actually fixed-size collections),
this is a slow operation, since a #become: is required to update
all owners. Better use a collection which is prepared for growing
(i.e. an OrderedCollection).
We output a warning message here, to remind you about that.
usage example(s):
     #(1 2 3 4 5) copy removeAll    
     #(1 2 3 4 5) removeAll    

o  removeAllSuchThat: aBlock
remove all elements that meet a test criteria as specified in aBlock.
The argument, aBlock is evaluated for successive elements and all those,
for which it returns true, are removed.
Return a collection containing the removed elements.
Redefined to do a single become operation.

copying
o  copyEmptyAndGrow: size
return a new instance of the receiver's species with size
nilled elements and any named instance variables copied.

error handling
o  fixedSizeError
report an error that size of the collection cannot be changed.
This is not used right now (instead, a warning is sent to stderr
in the #grow method); however, future versions of ST/X may no longer
allow fixed size collection to grow.
Read the documentation on why things are that way ...

growing
o  grow: newSize
grow the receiver i.e. cut off everything after newSize.
Warning: this may be a slow operation due to the use of become
- you should write your collection classes to avoid the use of become.
You have been warned.
usage example(s):
to use some collection which implements grow: more efficient
usage example(s):
     #(1 2 3 4 5 6) add:7
     #(1 2 3 4 5 6) remove:5 
     #(1 2 3 4 5 6) copy grow:3  
     #(1 2 3 4 5 6) copy grow:10  
     'hello world' copy grow:5   
     'hello' copy grow:20   

inspecting
o  inspector2TabForHexDump
( an extension from the stx:libtool package )
a tab, showing a hex dump; defined here, so that both byteArrays and other bulk data
containers can define it in their inspector2Tabs methods.

printing & storing
o  storeOn: aStream
output a printed representation (which can be re-read with readFrom:)
onto the argument aStream. Redefined to output index access.

queries
o  size
redefined to re-enable size->basicSize forwarding
(it is caught in SequencableCollection)

o  speciesForAdding
redefined here, since grow is not cheap.
Used by functions which create a growing collection (see collect:with:, for example)



ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Sun, 19 May 2019 06:25:42 GMT