Class: ArrayedCollection

• Inheritance
• Description
• Class protocol
  • inspecting - helpers
  • instance creation
  • queries
• Instance protocol
  • adding & removing
  • copying
  • error handling
  • growing
  • inspecting
  • printing & storing
  • queries

Inheritance:

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

Package:

stx:libbasic

Category:

Collections-Abstract

Version:

rev: 1.96 date: 2024/03/05 15:25:39

user: cg

file: ArrayedCollection.st directory: libbasic

module: stx stc-classLibrary: libbasic

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.

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:

 hexDumpViewFor: instOrHolder
( 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.

 inspector2TabForHexDumpFor: anInstance
( 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.

 from: anArray

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

Usage example(s):

Array from: #(1 2 3)

 newFrom: aCollection

Return an instance of me containing the same elements as aCollection.
Same as #withAll:

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

 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)

 with: element

return a new instance with one element:anObject

Usage example(s):

Array with:1

 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

 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

 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

 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

 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

 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

 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

 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:8 with:9

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

return a new SequenceableCollection with ten elements

Usage example(s):

OrderedCollection with:1 with:2 with:3 with:4 with:5 with:6 with:7 with:8 with:9 with:10 Array with:1 with:2 with:3 with:4 with:5 with:6 with:7 with:8 with:9 with:10

 withAll: aCollection

return a new Collection with all elements taken from the argument,
aCollection. Same as #newFrom:

Usage example(s):

OrderedCollection withAll:#(1 2 3 4 5) SortedCollection withAll:#(99 17 53 1 101)

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

Instance protocol:

 addAll: aCollection

add all elements of the argument, aCollection to the receiver.
Returns the argument, aCollection.

Redefined here, to perform only a single slow grow operation

Usage example(s):

#(1 2 3 4) addAll:#(5 6 7 8); yourself

 dropAllSuchThat: aBlock

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

Usage example(s):

|coll| coll := Array withAll:(1 to:10). Transcript showCR:(coll dropAllSuchThat:[:el | el even]).

 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

 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.

Usage example(s):

|coll| coll := Array withAll:(1 to:10). Transcript showCR:(coll removeAllSuchThat:[:el | el even]). Transcript showCR:coll

 copyEmptyAndGrow: size

return a new instance of the receiver's 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 ...

 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

 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.

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

returns the icon to be shown alongside the value list of an inspector

 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)