"

 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.

"

"{ Package: 'stx:libbasic' }"

"{ NameSpace: Smalltalk }"

Object subclass:#Collection

	instanceVariableNames:''

	classVariableNames:'EmptyCollectionSignal InvalidKeySignal NotEnoughElementsSignal

		ValueNotFoundSignal'

	poolDictionaries:''

	category:'Collections-Abstract'

!

!Collection class methodsFor:'documentation'!

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.

"

!

documentation

"

    Abstract superclass for all collections.

    This abstract class provides functionality common to all collections,

    without knowing how the concrete class implements things.

    Thus, all methods found here depend on some basic mechanisms

    to be defined in the concrete class.

    These basic methods are usually defined as #subclassResponsibility here.

    Some methods are also redefined for better performance.

    Subclasses should at least implement:

        do:     - enumerate elements

    they should implement one of the following set of access messages:

    For keyed collections:

        at:ifAbsent:            - fetching an element

        at:                     - fetching an element

        at:put:                 - storing an element

    For unkeyed collections:

        add:                    - add an element

        remove:ifAbsent:        - remove an element

    Given that the above is implemented in a concrete subclass,

    Collection provides protocol for enumeration, searching and others.

    However, for performance reasons, many of them are also redefined in

    concrete subclasses, as some can be implemented much faster if implementation

    details are known (for example, searching can be done faster if it is known that

    elements are sorted or accessible by a key).

    [author:]

        Claus Gittinger

"

! !

!Collection class methodsFor:'initialization'!

initialize

    "setup the signal"

    InvalidKeySignal isNil ifTrue:[

        InvalidKeySignal := Error newSignalMayProceed:true.

        InvalidKeySignal nameClass:self message:#invalidKeySignal.

        InvalidKeySignal notifierString:'invalid key:'.

        ValueNotFoundSignal := NotFoundError newSignalMayProceed:true.

        ValueNotFoundSignal nameClass:self message:#valueNotFoundSignal.

        ValueNotFoundSignal notifierString:'value not found:'.

        NotEnoughElementsSignal := NotFoundError newSignalMayProceed:true.

        NotEnoughElementsSignal nameClass:self message:#notEnoughElementsSignal.

        NotEnoughElementsSignal notifierString:'not enough elements in collection'.

        EmptyCollectionSignal := NotEnoughElementsSignal newSignalMayProceed:true.

        EmptyCollectionSignal nameClass:self message:#emptyCollectionSignal.

        EmptyCollectionSignal notifierString:'operation not allowed for empty collections'.

    ]

    "Modified: / 8.11.1997 / 19:18:17 / cg"

! !

!Collection class methodsFor:'instance creation'!

collect:aCollection usingEnumerator:aBlockOrEnumeratorSelector

    "apply aBlock or enumeratorSelector to the receiver

     and collect the enumerated elements.

     If the enumerator is a symbol, it should be the name of an enumerator method (i.e. do:, reverseDo:, etc.).

     If it is a block, it should be a two-arg block, expecting the collection first, and

     a block to be applied to each element.

     Can be used if the collection needs to be enumerated with a different enumerator

     (eg. a tree, which implements aka. childrenDo:)"

    |newCollection|

    newCollection := self streamContents:[:s |

        (aBlockOrEnumeratorSelector value:aCollection value:[:each | s nextPut:each])

    ].

    ^ newCollection

    "

     OrderedCollection collect:#(1 2 3 4 5) usingEnumerator:#do:

     OrderedCollection collect:#(1 2 3 4 5) usingEnumerator:#reverseDo:

     OrderedCollection collect:#(1 2 3 4 5) usingEnumerator:[:coll :block | coll do:block]

     OrderedCollection collect:#(1 2 3 4 5) usingEnumerator:[:coll :block | coll reverseDo:block]

    "

    "Created: / 05-06-2019 / 14:18:29 / Claus Gittinger"

!

combiningEach:collection1 withEach:collection2 using:aTwoArgBlock

    "evaluate aTwoArgBlock for each combination of elements from collection1

     and collection2 and return an instance of the receiver containing all those elements"

    |newColl idx useIndex newEl|

    newColl := self new:(collection1 size * collection2 size).

    useIndex := newColl isFixedSize.

    idx := 1.

    collection1 do:[:e1 |

        collection2 do:[:e2 |

            newEl := aTwoArgBlock value:e1 value:e2.

            useIndex ifTrue:[

                newColl at:idx put:newEl.

                idx := idx + 1.

            ] ifFalse:[

                newColl add:newEl

            ].

        ]

    ].

    ^ newColl

    "

     Set combiningEach:#(1 2 3 4 5) withEach:(10 to:100 by:10) using:[:a :b | a * b] 

     Set combiningEach:#(1 2 3 4 5) withEach:#(1 2 3 4 5) using:[:a :b | a * b] 

     Array combiningEach:#(1 2 3 4 5) withEach:#(1 2 3 4 5) using:[:a :b | a * b] 

    "

    "Created: / 25-08-2010 / 17:21:47 / cg"

    "Modified (comment): / 28-04-2017 / 14:38:41 / stefan"

!

new:size withAll:element

    "return a new Collection of size, where all elements are

     initialized to element"

    |newCollection|

    newCollection := self new:size.

    size timesRepeat:[newCollection add:element]

!

newFrom:aCollection 

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

    ^ self withAll:aCollection

    "

     Bag newFrom:#(1 2 3 4 4 5 6 7 7 7 )  

     Set newFrom:#(1 2 3 4 4 5 6 7 7 7 ) 

    "

!

newWithCapacity:n

    "return a new empty Collection preferrably with capacity for n elements.

     Redefined in StringCollection, where #new: returns a non-empty collection.

     This does not work for ArrayedCollections, which will be not empty.

     We return an empty collection here, because there are subclasses 

     which do not implement #new:."

    ^ self new

    "Created: / 09-10-2017 / 16:41:59 / stefan"

    "Modified: / 10-10-2017 / 17:47:56 / stefan"

!

newWithSize:n

    "return a new non-empty collection with n elements.

     Kludges around the inconsistent definition of #new: in 

        returning an empty collection in OrderedCollection and Set

     and

        returning an non-empty collection in ArrayedCollectins and StringCollection."

    ^ self new:n

    "Modified (comment): / 09-10-2017 / 16:56:34 / stefan"

!

with:anObject

    "return a new Collection with one element:anObject"

    ^ (self newWithCapacity:1)

        add:anObject;

        yourself.

    "Modified: / 09-10-2017 / 16:45:59 / stefan"

!

with:firstObject with:secondObject

    "return a new Collection with two elements:firstObject and secondObject"

    ^ (self newWithCapacity:2)

        add:firstObject; add:secondObject;

        yourself.

    "Modified: / 09-10-2017 / 16:45:52 / stefan"

!

with:firstObject with:secondObject with:thirdObject

    "return a new Collection with three elements"

    ^ (self newWithCapacity:3)

        add:firstObject; add:secondObject; add:thirdObject;

        yourself.

    "Modified: / 09-10-2017 / 16:45:46 / stefan"

!

with:firstObject with:secondObject with:thirdObject with:fourthObject

    "return a new Collection with four elements"

    ^ (self newWithCapacity:4)

        add:firstObject; add:secondObject; add:thirdObject; add:fourthObject;

        yourself.

    "Modified: / 09-10-2017 / 16:45:37 / stefan"

!

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

    "return a new Collection with five elements"

    ^ (self newWithCapacity:5)

        add:a1; add:a2; add:a3; add:a4; add:a5;

        yourself.

    "Modified: / 22-01-1997 / 19:34:01 / cg"

    "Modified: / 09-10-2017 / 16:45:29 / stefan"

!

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

    "return a new Collection with size elements"

    ^ (self newWithCapacity:6)

        add:a1; add:a2; add:a3; add:a4; add:a5; add:a6;

        yourself.

    "Created: / 22-01-1997 / 19:34:14 / cg"

    "Modified: / 09-10-2017 / 16:45:12 / stefan"

!

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

    "return a new Collection with seven elements"

    ^ (self newWithCapacity:7)

        add:a1; add:a2; add:a3; add:a4; add:a5; add:a6; add:a7;

        yourself.

    "Created: / 22-01-1997 / 19:34:24 / cg"

    "Modified: / 09-10-2017 / 16:44:59 / stefan"

!

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

    "return a new Collection with eight elements"

    ^ (self newWithCapacity:8)

        add:a1; add:a2; add:a3; add:a4; add:a5; add:a6; add:a7; add:a8;

        yourself.

    "Created: / 22-01-1997 / 19:34:34 / cg"

    "Modified: / 09-10-2017 / 16:44:45 / stefan"

!

withAll:aCollection

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

     aCollection"

"/ Doesn't work with Iterator:

"/    ^ (self newWithCapacity:aCollection size)

    ^ self new

        addAll:aCollection;

        yourself.

    "

        OrderedCollection withAll:#(1 2 3 4 5 6)

        Set withAll:#(1 2 3 4 5 6)

        StringCollection withAll:#('line1' 'line2' 'line3')

        String withAll:#($a $b $c)

        Set withAll:(Iterator on:[:whatToDo | 1 to:10 do:[:i | whatToDo value:i]]).

    "

    "Modified (comment): / 09-11-2017 / 07:03:53 / stefan"

!

withSize:n

    "obsolete: please use newWithSize:, for its better name"

    <resource: #obsolete>

    ^ self newWithSize:n

! !

!Collection class methodsFor:'Signal constants'!

emptyCollectionSignal

    "return the signal used to report non-allowed operation on empty collections"

    ^ EmptyCollectionSignal

!

invalidKeySignal

    "return the signal used to report bad key usage"

    ^ InvalidKeySignal

!

notEnoughElementsSignal

    "return the signal used to report attempts for an operation, for which

     there are not enough elements in the collection"

    ^ NotEnoughElementsSignal

!

valueNotFoundSignal

    "return the signal used to report a nonexisting element."

    ^ ValueNotFoundSignal

! !

writeStreamClass

    "the type of stream used in writeStream"

    ^ WriteStream

    "

     OrderedCollection writeStreamClass

    "

    "Created: / 09-01-2011 / 10:37:15 / cg"

! !

!Collection class methodsFor:'queries'!

growIsCheap

    "return true, if this collection can easily grow

     (i.e. without a need for become:).

     Returns true here; this method is redefined in fix-size

     collections"

    ^ true

!

isAbstract

    "Return if this class is an abstract class.

     True is returned for Collection here; false for subclasses.

     Abstract subclasses must redefine this again."

    ^ self == Collection

! !

!Collection methodsFor:'Compatibility-ANSI'!

identityIncludes:anObject

    "return true, if the argument, anObject is in the collection.

     Same as #includesIdentical for Dolphin/ANSI compatibility."

    ^ self includesIdentical:anObject.

! !

!Collection methodsFor:'Compatibility-Squeak'!

, aCollection

    "return a new collection formed from concatenating the receiver with the argument"

    ^ self copy addAll: aCollection; yourself

    "Created: / 14-09-2011 / 16:32:06 / cg"

!

addIfNotPresent:anObject

    "Include anObject as one of the receiver's elements, but only if there

     is no such element already. Answer anObject."

    (self includes: anObject) ifFalse: [self add: anObject].

    ^ anObject

    "Modified (comment): / 29-05-2019 / 03:43:32 / Claus Gittinger"

!

anyOne

    "return any element from the collection.

     Report an error if there is none.

     Same as #anElement - for Squeak compatibility"

    ^ self anElement

!

associationsDo: aBlock

    "cg: I think this is bad, but - well..."

    self do: aBlock

    "Created: / 12-09-2011 / 09:21:58 / cg"

!

contents

    "I am the contents of the collection"

    ^ self

    "Modified (comment): / 28-04-2017 / 14:32:04 / stefan"

!

difference: aCollection

    "Answer the set-theoretic difference of two collections."

    ^ self \ aCollection

    "

     #(0 2 4 6 8) difference:#(2 4)   

    "

    "Modified: / 20-01-2017 / 19:21:35 / stefan"

!

gather:aBlock

    "return an Array,

     containing all elements as returned from applying aBlock to each element of the receiver,

     where the block returns a collection of to-be-added elements.

     This could also be called: collectAllAsArray:"

    ^ self gather:aBlock as:Array

    "

     (Set withAll:#(10 20 30 10 20 40)) gather:[:el | Array with:el with:el * 2]

    "

!

gather:aBlock as:aClass

    "return an instance of the collection-class aClass,

     containing all elements as returned from applying aBlock to each element of the receiver.

     where the block returns a collection of to-be-added elements.

     This could also be called: collectAll:as:"

    ^ aClass streamContents:[:s |

        self do: [:ea | s nextPutAll: (aBlock value: ea)]

    ]

    "

     (Set withAll:#(10 20 30 10 20 40)) gather:[:el | Array with:el with:el * 2] as:OrderedCollection

     (Set withAll:#(10 20 30 10 20 40)) collectAll:[:el | Array with:el with:el * 2]

    "

!

groupBy:keyBlock having:selectBlock 

    "Like in SQL operation - Split the receiver's contents into collections of 

     elements for which keyBlock returns the same results, and return those 

     collections allowed by selectBlock. "