"

 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' }"

Object subclass:#Collection

	instanceVariableNames:''

	classVariableNames:'InvalidKeySignal EmptyCollectionSignal ValueNotFoundSignal

		NotEnoughElementsSignal RecursiveCollectionStoreStringSignal'

	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:

    keyed collections:

        at:ifAbsent:            - fetching an element

        at:                     - fetching an element

        at:put:                 - storing an element

    unkeyed collections:

        add:                    - add an element

        remove:ifAbsent:        - remove an element

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

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 ) 

    "

!

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

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

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

    ^ self new: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 withSize: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:'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

    ^ self == Collection

! !

!Collection methodsFor:'Compatibility-Dolphin'!

identityIncludes:anObject

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

     Same as #includesIdentical for Dolphin compatibility."

    ^ self includesIdentical:anObject.

!

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)

    "

! !

!Collection methodsFor:'Compatibility-Squeak'!

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

!

groupBy:keyBlock having:selectBlock 

    "Like in SQL operation - Split the recievers 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:ifEmptyValue ifNotEmpty:ifNotEmptyValue

    |action|

    action := self isEmpty ifTrue:[ ifEmptyValue ] ifFalse:[ ifNotEmptyValue ].

    action isBlock ifTrue:[

        action numArgs == 1 ifTrue:[

            ^ action value:self 

        ]

    ].

    ^ action value 

!

ifEmpty:ifEmptyValue ifNotEmptyDo:ifNotEmptyValue

    ^ self ifEmpty:ifEmptyValue ifNotEmpty:ifNotEmptyValue

!

ifEmptyDo:ifEmptyValue ifNotEmpty:ifNotEmptyValue

    ^ self ifEmpty:ifEmptyValue ifNotEmpty:ifNotEmptyValue

!

ifNotEmpty:ifNotEmptyValue

    ^ self ifEmpty:nil ifNotEmpty:ifNotEmptyValue

!

ifNotEmptyDo:ifNotEmptyValue

    ^ self ifEmpty:nil ifNotEmpty:ifNotEmptyValue

!

ifNotEmptyDo:ifNotEmptyValue ifEmpty:ifEmptyValue

    ^ self ifEmpty:ifEmptyValue ifNotEmpty:ifNotEmptyValue

!

withIndexDo:aTwoArgBlock 

    "evaluate the argument, aBlock for every element in the collection,

     passing both element and index as arguments."

    ^ self keysAndValuesDo:[:key :index |

        aTwoArgBlock value:index value:key

    ].

! !

!Collection methodsFor:'accessing'!

anElement

    "return any element from the collection, 

     report an error if there is none"

    self do: [:each | ^ each].

    self emptyCollectionError.

!

atAll:indexCollection put:anObject

    "put anObject into all indexes from indexCollection in the receiver.

     This abstract implementation requires that the receiver supports

     access via a key (and indexCollection contains valid keys).

     Notice: This operation modifies the receiver, NOT a copy;

     therefore the change may affect all others referencing the receiver."

    indexCollection do:[:index | self at:index put:anObject]

    "

     args:    indexCollection : <Collection of keys<object> >

     returns: self

    "

    "

     (Array new:10) atAll:(1 to:5) put:0

     (Array new:10) atAll:#(1 5 6 9) put:0

     (Dictionary new) atAll:#(foo bar baz) put:'hello' 

    raises an error:

     (Set new) atAll:#(foo bar baz) put:'hello' 

    "

    "Modified: / 20.5.1998 / 14:50:46 / cg"

!

fifth

    "return the fifth element of the collection.

     For unordered collections, this simply returns the fifth

     element when enumerating them.

     This should be redefined in subclasses."

    ^ self nth:5

    "

     #(1 2 3 4 5) fifth

    "

!

first

    "return the first element of the collection.

     For unordered collections, this simply returns the first

     element when enumerating them.

     This should be redefined in subclasses."

    self do:[:e | ^ e].

    "error if collection is empty"

    ^ self emptyCollectionError

!

first:n

    "return the n first elements of the collection.

     Raises an error if there are not enough elements in the receiver.

     For unordered collections, this simply returns the first

     n elements when enumerating them 

     (Warning: the contents of the returned collection is not deterministic in this case).

     This should be redefined in subclasses."

    |coll remain|

    n < 0 ifTrue:[self error:'bad (negative) argument'].

    coll := OrderedCollection new.

    remain := n.    

    self do:[:e | 

                coll add:e.

                remain := remain - 1.

                remain == 0 ifTrue:[

                    ^ coll

                ].

            ].

    "error if collection has not enough elements"

    ^ self notEnoughElementsError

    "

     #(1 2 3 4 5) first:3           

     #(1 2 3 4 5) asSet first:3           

    "

!

firstIfEmpty:exceptionValue

    "return the first element of the collection.

     If its empty, return the exceptionValue.

     (i.e. dont trigger an error as done in #first)"

    self isEmpty ifTrue:[^ exceptionValue value].

    ^ self first

    "Modified: / 04-06-2007 / 22:36:14 / cg"

!

firstOrNil

    "return the first element of the collection.

     If its empty, return nil.

     (i.e. dont trigger an error as done in #first)"

    ^ self firstIfEmpty:nil

    "Created: / 04-06-2007 / 22:36:07 / cg"

!

fourth

    "return the fourth element of the collection.