"

 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 comment:'

COPYRIGHT (c) 1989 by Claus Gittinger

	      All Rights Reserved

'!

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

"

!

version

"

"

!

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.

"

! !

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

	ValueNotFoundSignal nameClass:self message:#valueNotFoundSignal.

	ValueNotFoundSignal notifierString:'value not found:'.

	NotEnoughElementsSignal := ErrorSignal 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'.

    ]

! !

!Collection class methodsFor:'Signal constants'!

invalidKeySignal

    "return the signal used to report bad key usage"

    ^ InvalidKeySignal

! 

valueNotFoundSignal

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

    ^ ValueNotFoundSignal

! 

emptyCollectionSignal

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

    ^ EmptyCollectionSignal

! 

notEnoughElementsSignal

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

     there are not enough elements in the collection"

    ^ NotEnoughElementsSignal

! !

!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 class methodsFor:'instance creation'!

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.

    newCollection add:secondObject.

    ^ newCollection

!

with:firstObject with:secondObject with:thirdObject

    "return a new Collection with three elements"

    |newCollection|

    newCollection := self new.

    newCollection add:firstObject.

    newCollection add:secondObject.

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

    newCollection add:secondObject.

    newCollection add:thirdObject.

    newCollection add:fourthObject.

    ^ newCollection

!

with:one with:two with:three with:four with:five

    "return a new Collection with five elements"

    |newCollection|

    newCollection := self new.

    newCollection add:one.

    newCollection add:two.

    newCollection add:three.

    newCollection add:four.

    newCollection add:five.

    ^ newCollection

!

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]

!

withAll:aCollection

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

     aCollection"

    |newCollection|

    newCollection := self new.

    newCollection addAll:aCollection.

    ^newCollection

! !

!Collection methodsFor:'error handling'!

errorNotKeyed

    "report an error that keyed access methods are not allowed"

    ^ self error:(self class name, 's do not respond to keyed accessing messages')

! 

errorInvalidKey:aKey

    "report an error that the given key was invalid"

    ^ InvalidKeySignal raiseRequestWith:aKey

!

errorValueNotFound:anObject

    "report an error that an object was not found in the collection"

    ^ ValueNotFoundSignal raiseRequestWith:anObject

!

emptyCollectionError

    "report an error that the operation is not allowed for

     empty collections"

    ^ EmptyCollectionSignal raise

!

notEnoughElementsError

    "report an error that the operation is not allowed,  

     since not enough elements are in the collection"

    ^ NotEnoughElementsSignal raise

!

emptyCheck 

    "check if the receiver is empty; report an error if so"

    self size == 0 ifTrue:[

	^ self emptyCollectionError.

    ].

! !

!Collection methodsFor:'copying'!

copyEmpty:size

    "return a copy of the receiver with no elements, but space for

     size elements. This is used by copying and enumeration methods

     to get a new instance which is similar to the receiver.

     This method should be redefined in subclasses with instance

     variables, which should be put into the copy too.

     For example, SortedCollection has to copy its sortBlock into the

     new collection."

    ^ self species new:size

!

copyEmpty

    "return a copy of the receiver with no elements.

     This is used by copying and enumeration methods

     to get a new instance which is similar to the receiver."

    ^ self species new

!

copyEmptyAndGrow:size

    "return a copy of the receiver with size nil elements.

     This is used by copying and enumeration methods

     to get a new instance which is similar to the receiver."

    ^ (self copyEmpty:size) grow:size

! !

!Collection methodsFor:'queries'!

isCollection

    "return true, if the receiver is some kind of collection;

     true is returned here - the method is redefined from Object."

    ^ true

! !

!Collection methodsFor:'accessing'!

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

!

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

!

anElement

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

    self do: [:each | ^ each].

    ^ nil

!

upTo:anElement

    "return a new collection consisting of the receivers elements upTo

     (but excluding) anElement.

     If anElement is not in the receiver, the returned collection

     will consist of all elements of the receiver"

    |s|

    s := ReadStream on:self.

    ^ s upTo:anElement

    "

     'test.text' upTo:$.  

     #(1 2 3 4 5) upTo:4  

    "

! !

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

    ^ self subclassResponsibility

!

addLast:anObject

    "add the argument, anObject to the receiver. 

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

    ^ self add:anObject

!

addFirst:anObject

    "add the argument, anObject to the receiver.

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

    ^ self subclassResponsibility

!

addAll:aCollection

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

    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)

    "

!

addAllLast:aCollection

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

    aCollection do:[:element | 

	self addLast:element 

    ].

    ^ aCollection

    "

     |c|

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

     c addAllLast:#(9 8 7 6 5)

    "

!

addAllFirst:aCollection

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

     of the receiver"

    aCollection reverseDo:[:element | 

	self addFirst:element 

    ].

    ^ aCollection

    "

     |c|

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

     c addAllFirst:#(9 8 7 6 5)

    "

!

remove:anObject ifAbsent:exceptionBlock

    "remove the (first occurrence of) argument, anObject from the receiver,

     and return it.

     If it was not in the collection, return the the value of the exceptionBlock"

    ^ self subclassResponsibility

!

remove:anObject

    "remove the (first occurrence of) argument, anObject from the receiver,

     and return it.

     If it was not in the collection, raise an error."

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

!

removeAll

    "remove all elements from the receiver.

     This should be reimplemented in subclasses for better

     performance."

    [self notEmpty] whileTrue:[

	self removeFirst

    ].

!

removeAll:aCollection

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

     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

!

removeFirst

    "remove the first element from the receiver.

     Return the removed element."

    ^ self subclassResponsibility

!

removeLast

    "remove the last element from the receiver.

     Return the removed element."

    ^ self subclassResponsibility