"

 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.

"

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:

    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 := ErrorSignal newSignalMayProceed:true.

        InvalidKeySignal nameClass:self message:#invalidKeySignal.

        InvalidKeySignal notifierString:'invalid key:'.

        ValueNotFoundSignal := NotFoundSignal newSignalMayProceed:true.

        ValueNotFoundSignal nameClass:self message:#valueNotFoundSignal.

        ValueNotFoundSignal notifierString:'value not found:'.

        NotEnoughElementsSignal := NotFoundSignal 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]

!

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

! !

!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

! !

!Collection methodsFor:'accessing'!

anElement

    "return any element from the collection, or nil if there is none"

    self do: [:each | ^ each].

    ^ nil

!

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]

    "

     (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: 11.5.1996 / 11:04:59 / cg"

!

first

    "return the first element of the collection.

     This should be redefined in subclasses."

    self do:[:e | ^ e].

    "error if collection is empty"

    ^ self emptyCollectionError

!

firstIfEmpty:exceptionValue

    "return the first element of the collection.

     If its empty, return the excveptionValue.

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

    self isEmpty ifTrue:[^ exceptionValue value].

    ^  self first

    "Modified: 6.2.1996 / 15:27:17 / cg"

!

last

    "return the last element of the collection.

     This should be redefined in subclasses."

    |theLastOne any|

    any := false.

    self do:[:e | any := true. theLastOne := e].

    any ifTrue:[

	^ theLastOne

    ].

    "error if collection is empty"

    ^ self emptyCollectionError

!

lastIfEmpty:exceptionValue

    "return the last element of the collection.

     If its empty, return the exceptionValue.

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

    self isEmpty ifTrue:[^ exceptionValue value].

    ^ self last

    "Modified: 6.2.1996 / 15:27:17 / cg"

    "Created: 6.2.1996 / 15:27:49 / cg"

! !

!Collection methodsFor:'adding & removing'!

add:anObject

    "add the argument, anObject to the receiver.

     If the receiver is ordered, the position of the new element is undefined

     (i.e. dont depend on where it will be put).

     An error is raised here - it is to be implemented by a concrete subclass."

    ^ self subclassResponsibility

    "Modified: 1.2.1997 / 11:57:08 / cg"

!

add:newObject withOccurrences:anInteger

    "add the argument, anObject anInteger times to the receiver.

     Returns the object."

    anInteger timesRepeat:[self add:newObject].

    ^ newObject

    "Created: 11.5.1996 / 12:13:48 / cg"

!

addAll:aCollection

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

     Returns the argument, aCollection."

    aCollection do:[:element |

        self add:element

    ].

    ^ aCollection

    "

     #(1 2 3 4) copy addAll:#(5 6 7 8)

     #(1 2 3 4) asOrderedCollection addAll:#(5 6 7 8)

    "

    "Modified: 12.4.1996 / 13:29:20 / cg"

!

addAllFirst:aCollection

    "insert all elements of the argument, aCollection at the beginning

     of the receiver. Returns the argument, aCollection."

    aCollection reverseDo:[:element | 

        self addFirst:element 

    ].

    ^ aCollection

    "

     |c|

     c := #(4 3 2 1) asOrderedCollection.

     c addAllFirst:#(9 8 7 6 5).

     c   

    "

    "Modified: 12.4.1996 / 13:30:10 / cg"

!

addAllLast:aCollection

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

     Returns the argument, aCollection."

    aCollection do:[:element | 

        self addLast:element 

    ].

    ^ aCollection

    "

     |c|

     c := #(4 3 2 1) asOrderedCollection.

     c addAllLast:#(9 8 7 6 5)

    "

    "Modified: 12.4.1996 / 13:30:54 / cg"

!

addFirst:anObject

    "add the argument, anObject to the receiver.

     If the receiver is ordered, the new element will be added at the beginning.

     An error is raised here - it is to be implemented by a concrete subclass."

    ^ self subclassResponsibility

    "Modified: 1.2.1997 / 11:57:19 / cg"

!

addLast:anObject

    "add the argument, anObject to the receiver. 

     If the receiver is ordered, the new element will be added at the end.

     Return the argument, anObject."

    ^ self add:anObject

    "Modified: 12.4.1996 / 13:31:12 / cg"

!

contents:aCollection

    ^self removeAll; addAll:aCollection

!

remove:anObject

    "search for the first element, which is equal to anObject;

     if found, remove and return it.

     If not found, report a 'value not found'-error.

     Uses equality compare (=) to search for the occurrence."

    ^ self remove:anObject ifAbsent:[self errorValueNotFound:anObject]

    "Modified: 1.2.1997 / 11:58:48 / cg"

!

remove:anObject ifAbsent:exceptionBlock

    "search for the first element, which is equal to anObject;

     if found, remove and return it.

     If not found, return the the value of the exceptionBlock.

     Uses equality compare (=) to search for the occurrence.

     An error is raised here - it is to be implemented by a concrete subclass."

    ^ self subclassResponsibility

    "Modified: 1.2.1997 / 11:56:53 / cg"

!

removeAll

    "remove all elements from the receiver. Returns the receiver.

     This should be reimplemented in subclasses for better

     performance."

    [self isEmpty] whileFalse:[

        self removeFirst

    ].

    "Modified: 12.2.1997 / 12:40:29 / cg"

!

removeAll:aCollection

    "remove all elements of the argument, aCollection from the receiver.

     Return the argument, aCollection.

     Notice: for some collections (those not tuned for

             resizing themself) this may be very slow.

             If the number of removed elements is big compared to to

             the receivers size, it may be better to copy the

             ones which are not to be removed into a new collection."

    aCollection do:[:element | self remove:element].

    ^ aCollection

    "Modified: 12.4.1996 / 13:35:48 / cg"

!

removeFirst

    "remove the first element from the receiver.

     Return the removed element."

    self do:[:element |

        self remove:element.

        ^ element.

    ].

    ^ self emptyCollectionError

    "

     (Set with:3 with:2 with:1) removeFirst 

    "

    "Modified: 28.6.1996 / 18:55:33 / cg"

!