Class: ArrayedCollection

• Inheritance
• Description
• Warning
• Related information
• Class protocol
  • instance creation
  • queries
• Instance protocol
  • adding
  • copying
  • error handling
  • printing & storing
  • queries
  • resizing

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--Array
            |
            +--BitArray
            |
            +--DoubleArray
            |
            +--FileDirectory::DirectoryEntry
            |
            +--FloatArray
            |
            +--UnboxedIntegerArray
            |
            +--UninterpretedBytes
            |
            +--WeakArray

Package:

stx:libbasic

Category:

Collections-Abstract

Version:

rev: 1.58 date: 2009/01/16 13:06:26

user: cg

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.
(other collections keep a reference to the physical container, which
 can be easily replaced)

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.

Therefore, you SHOULD rewrite any application that does this,
to make use of OrderedCollections or any other collection which
can grow faster.
To remind you of that, a warning message is sent to the
standard error 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.

Related information:

    OrderedCollection
    Array

Class protocol:

 newFrom: aCollection

Return an instance of me containing the same elements as aCollection.

 with: element

return a new SequenceableCollection with one element:anObject

 with: first with: second

return a new SequenceableCollection with two elements

 with: a1 with: a2 with: a3

return a new SequenceableCollection with three elements

 with: a1 with: a2 with: a3 with: a4

return a new SequenceableCollection with four elements

 with: a1 with: a2 with: a3 with: a4 with: a5

return a new SequenceableCollection with five elements

 with: a1 with: a2 with: a3 with: a4 with: a5 with: a6

return a new SequenceableCollection with six elements

 with: a1 with: a2 with: a3 with: a4 with: a5 with: a6 with: a7

return a new SequenceableCollection with seven elements

 with: a1 with: a2 with: a3 with: a4 with: a5 with: a6 with: a7 with: a8

return a new SequenceableCollection with eight elements

 withAll: aCollection

return a new Collection with all elements taken from the argument,
aCollection

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

 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.

 isAbstract

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

Instance protocol:

 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

 copyEmptyAndGrow: size

return a new instance of the receivers species with size
nilled elements and any named instance variables copied.

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

 storeOn: aStream

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

 size

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

 speciesForAdding

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

 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.

 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.