Class: CollectionBuilder

• Inheritance
• Description
• Class protocol
  • instance creation
• Instance protocol
  • accessing
  • adding & removing
  • copying
  • enumerating
  • inspecting
  • private
  • queries
• Examples

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--CollectionBuilder

Package:

stx:libbasic2

Category:

Collections-Sequenceable

Version:

rev: 1.4 date: 2023/07/05 17:44:43

user: cg

file: CollectionBuilder.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Description:

I look like an indexable (ordered) collection to the outside, but internally keep slices
which were added before a subcollections. I am only faster in adding; and then only when longer
element-slices are added with addAll:. Don't use me when adding individual elements.

When building large collections by concatenation, this helper can speedup this operation.
It non-destructively creates a list of the slices added during the concatenation process, 
thus (usually) reducing the amount of storage and time required to construct the collection.
Especially, if the slices are constants (strings) and even reused (same string occurring multiple times),
the saving in memory may be significant.

However, there is a tradeof: the times to access, to enumerate and to query the size of
the resulting collection is longer. 
Therefore, this is (usually) only useful if a throw-away collection is
constructed to be used only a small number of times for enumeration (or writing to a file).

It is very similar to Java's StringBuffer, but can handle any kind of collection.
(however, please see also Stream / #streamContents:, for yet another (better?) way of building collections ...)



[example:]
    |coll|

    coll := CollectionBuilder new.
    1 to:100000 do:[:i |
        coll addAll:#(1 2 3 4 5 6 7 8 9 0)
    ].
    coll

copyright
COPYRIGHT (c) 1996 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:

 withAll: collections and: aCollection

Instance protocol:

 at: index

|c|

c := CollectionBuilder new.
c := c , #(1 2 3 4).
c := c , #(5 6 7 8).
c := c , #(9 10 11 12).
c inspect.
c at:13

 add: anObject

(comment from inherited method)
append the argument, anObject to the collection.
Return the argument, anObject.

Notice that this modifies the receiver, NOT a copy.
Also note that it may be a slow operation for some collections,
due to the grow:-message, which is inefficient for fixed size
collections (i.e. for Strings and Arrays it is not recommended).

 addAll: aCollection

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

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

 do: aBlock

(comment from inherited method)
evaluate the argument, aBlock for every element in the collection in
sequence order.

 keysAndValuesDo: aBlock

(comment from inherited method)
evaluate the argument, aBlock for every element in the collection,
passing both index and element as arguments.

 inspectorClass

redefined to launch an OrderedCollectionInspector
(instead of the default InspectorView).

 withAll: collections1 and: collections2

 size

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

Examples:

  Time millisecondsToRun:[
      |coll|

      coll := OrderedCollection new.
      1 to:100000 do:[:i |
          coll addAll:i printString
      ]
  ]   => 57 53

  Time millisecondsToRun:[
      |coll|

      coll := OrderedCollection new.
      1 to:1000000 do:[:i |
          coll addAll:i printString
      ]
  ]  => 621 623

  Time millisecondsToRun:[
      |coll|

      coll := CollectionBuilder new.
      1 to:100000 do:[:i |
          coll addAll:i printString
      ]
  ]  => 32 31 

  Time millisecondsToRun:[
      |coll|

      coll := CollectionBuilder new.
      1 to:1000000 do:[:i |
          coll addAll:i printString
      ]
  ]  => 364 329 

  |coll|

  coll := OrderedCollection new.
  1 to:100000 do:[:i |
      coll addAll:i printString
  ].
  Time millisecondsToRun:[
      coll do:[:each | each ].
  ]  => 24 25  

  |coll|

  coll := CollectionBuilder new.
  1 to:100000 do:[:i |
      coll addAll:i printString
  ].
  Time millisecondsToRun:[
      coll do:[:each | each ].
  ]   => 33 37