"

 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'

       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 := (Signal new) mayProceed:true.

        InvalidKeySignal notifierString:'invalid key'.

    ]

! !

!Collection class methodsFor:'signal access'!

invalidKeySignal

    "return the signal used to report bad key usage"

    ^ InvalidKeySignal

! !

!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

!

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"

! 

errorInvalidKey

    "report an error that the given key was invalid"

    ^ InvalidKeySignal raise

! !

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

!

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"

!

anElement

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

    self do: [:each | ^ each].

    ^ nil

! !

!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 argument, anObject from the receiver - if it was not

     in the collection returns the the value of the exceptionBlock"

    ^ self subclassResponsibility

!

remove:anObject

    "remove the argument, anObject from the receiver"

    self remove:anObject ifAbsent:[self errorNotFound]

!

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"

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

    ^ aCollection

! !

!Collection methodsFor:'growing'!

growSize

    "return a suitable size increment for growing"

    ^ self size max:2

!

grow

    "make the receiver larger"

    self grow:(self size + self growSize)

!

grow:howBig

    "change the receivers size"

    ^ self subclassResponsibility

! !

!Collection methodsFor:'testing'!

isEmpty

    "return true, if the receiver is empty"

    ^ self size == 0

!

notEmpty

    "return true, if the receiver is not empty"

    ^ self isEmpty not

!

includes:anElement

    "return true, if the argument, anObject is in the list"

    self do:[:element |

        (anElement = element) ifTrue:[^ true].

    ].

    ^ false

!

includesAll:aCollection

    "return true, if the the receiver includes all elements of

     the argument, aCollection; false if any is missing"

    aCollection do:[:element |

        (self includes:element) ifFalse:[^ false].

    ].

    ^ true

    "

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

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

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

    "

!

includesAny:aCollection

    "return true, if the the receiver includes any elements of

     the argument, aCollection; false if it includes none"

    aCollection do:[:element |

        (self includes:element) ifTrue:[^ true].

    ].

    ^ false

    "

     #(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)

    "

!

occurrencesOf:anElement

    "return the number of occurrences of the argument, anElement in

     the receiver"

    |count "<SmallInteger>" |

    count := 0.

    self do:[:element |

        (anElement = element) ifTrue:[

            count := count + 1

        ].

    ].

    ^ count

!

size

    "return the number of elements in the receiver.

     This is usually redefined in subclasses for more performance."

    |count "<SmallInteger>" |

    count := 0.

    self do:[:element |

        count := count + 1

    ].

    ^ count

! !

!Collection methodsFor:'enumerating'!

do:aBlock

    "evaluate the argument, aBlock for each element"

    ^ self subclassResponsibility

!

reverseDo:aBlock

    "evaluate the argument, aBlock for each element in reverse order."

    "it could be defined in terms of do: - but very inefficient.

     Better force programmer to define a better version ..."

    ^ self subclassResponsibility

!

keysAndValuesDo:aTwoArgBlock

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

     passing both index and element as arguments."

    ^ self errorNotKeyed

!

with:aSequenceableCollection do:aTwoArgBlock

    "evaluate the argument, aBlock for successive elements from

     each the receiver and the argument, aSequenceableCollection.

     The second argument, aBlock must be a two-argument block.

     The receiver may be any enumeratable collection, while the other

     collection must implement access via a numeric key."

    |index  "{ Class: SmallInteger }" |

    index := 1.

    self do:[:element |

        aTwoArgBlock value:element value:(aSequenceableCollection at:index).

        index := index + 1

    ]

    "

     (1 to:3) with:#(one two three) do:[:num :sym |

        Transcript showCr:(num->sym)

     ]

    "

!

collect:aBlock

    "for each element in the receiver, evaluate the argument, aBlock

     and return a new collection with the results"

    |newCollection|

    newCollection := self species new finalizeCopyFrom:self.

    self do:[:each | newCollection add:(aBlock value:each)].

    ^ newCollection

    "

     #(1 2 3 4) collect:[:n | n * 2]  

    "

!

with:aSequenceableCollection collect:aTwoArgBlock

    "evaluate the argument, aBlock for successive elements from

     each the receiver and the argument, aSequenceableCollection;

     The second argument, aBlock must be a two-argument block, which is

     evaluated for each element-pair.

     Collect the results and return a collection containing them.

     The receiver may be any enumeratable collection, while the other

     collection must implement access via a numeric key."

    |index  "{ Class: SmallInteger }" 

     newCollection|

    newCollection := self species new finalizeCopyFrom:self.

    index := 1.

    self do:[:element |

        newCollection add:(aTwoArgBlock value:element value:(aSequenceableCollection at:index)).

        index := index + 1

    ].

    ^ newCollection

    "

     (1 to:3) with:#(one two three) collect:[:num :sym | (num->sym)]

     #(1 2 3) with:#(10 20 30) collect:[:x :y | (x@y)]

    "

!

detect:aBlock

    "evaluate the argument, aBlock for each element in the receiver until

     the block returns true; in this case return the element which caused

     the true evaluation.

     If none of the evaluations return true, report an error"

    ^ self detect:aBlock ifNone:[self errorNotFound]