"{ Encoding: utf8 }"

"

 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.

"

"{ Package: 'stx:libbasic2' }"

"{ NameSpace: Smalltalk }"

ArrayedCollection subclass:#CollectionBuilder

	instanceVariableNames:'collections'

	classVariableNames:''

	poolDictionaries:''

	category:'Collections-Sequenceable'

!

!CollectionBuilder class methodsFor:'documentation'!

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.

"

!

documentation

"

    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 mey be significant.

    However, there is a tradeof: the time to access, to enumerate and to query the size of

    the resulting collection is slower. 

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

    [see also:]

        WriteStream

    [author:]

        Claus Gittinger

    [example:]

        |coll|

        coll := CollectionBuilder new.

        1 to:100000 do:[:i |

            coll addAll:#(1 2 3 4 5 6 7 8 9 0)

        ].

        coll

"

!

examples

"

  when building large collections by concatenation,

  the following standard creation is time consuming:

                                                                        [exBegin]

    Time millisecondsToRun:[

        |coll|

        coll := OrderedCollection new.

        1 to:100000 do:[:i |

            coll addAll:i printString

        ]

    ]    

                                                                        [exEnd]

  the following is faster, and does not actually create a new collection:

                                                                        [exBegin]

    Time millisecondsToRun:[

        |coll|

        coll := CollectionBuilder new.

        1 to:100000 do:[:i |

            coll addAll:i printString

        ]

    ]     

                                                                        [exEnd]

   Time to enumerate:

                                                                        [exBegin]

    |coll|

    coll := OrderedCollection new.

    1 to:100000 do:[:i |

        coll addAll:i printString

    ].

    Time millisecondsToRun:[

        coll do:[:each | each ].

    ]     

                                                                        [exEnd]

                                                                        [exBegin]

    |coll|

    coll := CollectionBuilder new.

    1 to:100000 do:[:i |

        coll addAll:i printString

    ].

    Time millisecondsToRun:[

        coll do:[:each | each ].

    ]     

                                                                        [exEnd]

"

! !

!CollectionBuilder class methodsFor:'instance creation'!

withAll:collections and:aCollection

    ^ self new withAll:collections and:aCollection

! !

!CollectionBuilder methodsFor:'accessing'!

at:index

    |collFirst collLast|

    index < 1 ifTrue:[^ self subscriptBoundsError:index].

    collFirst := 0.

    collections do:[:eachSlice |

        collLast := collFirst + eachSlice size.

        index <= collLast ifTrue:[

            ^ eachSlice at:(index - collFirst)

        ].

        collFirst := collLast.

    ].

    ^ self indexNotIntegerOrOutOfBounds: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  

    "

    "Modified: 1.2.1996 / 17:01:16 / cg"

! !

!CollectionBuilder methodsFor:'adding & removing'!

add:anObject

    collections := collections copyWith:(Array with:anObject).

    ^ anObject

    "Created: 1.2.1996 / 17:09:15 / cg"

!

addAll:aCollection

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

     Returns the argument, aCollection."

    collections isNil ifTrue:[

        collections := OrderedCollection with:aCollection

    ] ifFalse:[

        collections add:aCollection

    ].

    ^ aCollection

    "Created: 1.2.1996 / 17:09:29 / cg"

    "Modified: 1.2.1996 / 17:14:54 / cg"

! !

!CollectionBuilder methodsFor:'copying'!

, aCollection

    ^ CollectionBuilder withAll:collections and:aCollection

    "Created: 1.2.1996 / 16:43:18 / cg"

! !

!CollectionBuilder methodsFor:'enumerating'!

do:aBlock

    collections do:[:coll |

	coll do:aBlock

    ]

    "Created: 1.2.1996 / 17:05:36 / cg"

!

keysAndValuesDo:aBlock

    |idx|

    idx := 1.

    collections do:[:coll |

	coll do:[:element |

	    aBlock value:idx value:element.

	    idx := idx + 1

	]

    ]

    "Created: 1.2.1996 / 17:06:13 / cg"

! !

!CollectionBuilder methodsFor:'inspecting'!

inspectorClass

    "redefined to launch an OrderedCollectionInspector

     (instead of the default InspectorView)."

    ^ OrderedCollectionInspectorView

    "Created: 1.2.1996 / 17:07:53 / cg"

! !

!CollectionBuilder methodsFor:'private'!

withAll:collections1 and:collections2

    collections1 isEmptyOrNil ifTrue:[

        collections := OrderedCollection with:collections2

    ] ifFalse:[

        collections := OrderedCollection withAll:collections1.

        collections2 notEmptyOrNil ifTrue:[

            collections add:collections2

        ].

    ].

    "Created: 1.2.1996 / 16:44:15 / cg"

    "Modified: 1.2.1996 / 17:00:17 / cg"

! !

!CollectionBuilder methodsFor:'queries'!

size

    ^ collections inject:0 into:[:sumSoFar :subColl | sumSoFar + subColl size]

    "Created: 1.2.1996 / 16:42:31 / cg"

! !

!CollectionBuilder class methodsFor:'documentation'!

version_CVS

    ^ '$Header$'

! !