"

 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:'InvalidKeySignal EmptyCollectionSignal ValueNotFoundSignal

		NotEnoughElementsSignal'

	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'!

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:(aTwoArgBlock value:e1 value:e2).

                idx := idx + 1.

            ] ifFalse:[

                newColl add:(aTwoArgBlock value:e1 value:e2)

            ].

        ]

    ].

    ^ 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] 

    "

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

!

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 ) 

    "

!

newWithSize:n

    "return a new collection which really provides space for n elements.

     Kludges around the stupid definition of OrderedCollection>>new:"

    ^ self new:n

!

with:anObject

    "return a new Collection with one element:anObject"

    |newCollection|

    newCollection := self new.

    newCollection add:anObject.

    ^ newCollection

!

with:firstObject with:secondObject

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

    |newCollection|

    newCollection := self new.

    newCollection add:firstObject; add:secondObject.

    ^ newCollection

!

with:firstObject with:secondObject with:thirdObject

    "return a new Collection with three elements"

    |newCollection|

    newCollection := self new.

    newCollection add:firstObject; add:secondObject; add:thirdObject.

    ^ newCollection

!

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

    "return a new Collection with four elements"

    |newCollection|

    newCollection := self new.

    newCollection add:firstObject; add:secondObject; add:thirdObject; add:fourthObject.

    ^ newCollection

!

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

    "return a new Collection with five elements"

    |newCollection|

    newCollection := self new.

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

    ^ newCollection

    "Modified: 22.1.1997 / 19:34:01 / cg"

!

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

    "return a new Collection with size elements"

    |newCollection|

    newCollection := self new.

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

    ^ newCollection

    "Created: 22.1.1997 / 19:34:14 / cg"

!

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

    "return a new Collection with seven elements"

    |newCollection|

    newCollection := self new.

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

    ^ newCollection

    "Created: 22.1.1997 / 19:34:24 / cg"

!

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

    "return a new Collection with eight elements"

    |newCollection|

    newCollection := self new.

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

    ^ newCollection

    "Created: 22.1.1997 / 19:34:34 / cg"

!

withAll:aCollection

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

     aCollection"

    |newCollection|

    newCollection := self new.

    newCollection addAll:aCollection.

    ^newCollection

!

withSize:n

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

     Return a new collection which really provides space for n elements.

     Kludges around the stupid definition of OrderedCollection>>new:"

    ^ self newWithSize:n

! !

!Collection class methodsFor:'Compatibility-Squeak'!

ofSize:n

    "return a new collection which really provides space for n elements.

     Kludges around the stupid definition of OrderedCollection>>new:"

    ^ 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

! !

!Collection class methodsFor:'instance creation-streaming'!

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-Dolphin'!

includesAnyOf:aCollection

    "same as #includesAny for Dolphin compatibility."

    ^ self includesAny:aCollection

    "

     #(1 2 3 4 5 6 7) includesAny:#(1 2 3)

     #('hello' 'there' 'world') includesAny:#('hello' 'world')

     #(1 2 3 4 5 6 7) includesAny:#(7 8 9)

     #(1 2 3 4 5 6 7) includesAny:#(8 9 10)

    "

!

symmetricDifference:aCollection

    "return a new set containing all elements, 

     which are contained in either the receiver or aCollection, but not in both.

     Same as xor: - for compatibility"

    ^ self xor:aCollection

    "

     |c1 c2|

     c1 := #( foo bar baz baloo ).

     c2 := #( foe bar banana baloo ).

     c1 symmetricDifference:c2.         

     self assert:(c1 symmetricDifference:c2) asSet = (c2 symmetricDifference:c1) asSet

    "

! !

!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. Anwser anObject."

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

    ^ anObject

!

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

    ^ self

!

difference: aCollection

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

    ^ self reject:[:each | aCollection includes: each]

    "

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

    "

!

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

    |result key|

    result := OrderedDictionary new.

    self do:[:e | 

        key := keyBlock value: e.

        (result includesKey: key) ifFalse: [

            result at: key put: OrderedCollection new

        ].

        (result at: key) add: e

    ].

    ^ result := result select: selectBlock

    "

     #(1 2 3 4 5 6 7 8 9) groupBy:[:e | e odd] having:[:a |true]  

    "

!

ifEmpty:alternativeValue

    "return the receiver if not empty, alternativeValue otherwise"

    ^ self size ~~ 0 ifTrue:[self] ifFalse:[alternativeValue value]

    "

     'foo' ifEmpty: 'bar'

     '' ifEmpty: 'bar'

     '' ifEmpty: [ Time now printString ]

    "

!