"

 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.

"

Collection subclass:#SequenceableCollection

       instanceVariableNames:''

       classVariableNames:''

       poolDictionaries:''

       category:'Collections-Abstract'

!

SequenceableCollection comment:'

COPYRIGHT (c) 1989 by Claus Gittinger

              All Rights Reserved

SequenceableCollections have ordered elements which can be accessed via

an index. SequenceableCollection is an abstract class - there are no

instances of it in the system.

$Header: /cvs/stx/stx/libbasic/Attic/SeqColl.st,v 1.8 1994-01-16 03:45:26 claus Exp $

written spring 89 by claus

'!

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

    newCollection atAllPut:element.

    ^ newCollection

! !

!SequenceableCollection methodsFor:'accessing'!

first

    "return the first element"

    ^ self at:1

!

last

    "return the last element"

    ^ self at:(self size)

!

at:index ifAbsent:exceptionBlock

    "return the element at index if valid. If the index is invalid,

     return the result of evaluating the exceptionblock"

    ((index < 1) or:[index > self size]) ifTrue:[

        ^ exceptionBlock value

    ].

    ^ self at:index

    "#(1 2 3) at:4 ifAbsent:['no such index']"

! !

!SequenceableCollection methodsFor:'queries'!

firstIndex

    "return the first elements index"

    ^ 1

!

lastIndex

    "return the last elements index"

    ^ self size

!

size

    "return the number of elements in the collection.

     concrete implementations must define this"

    ^ self subclassResponsibility

! !

!SequenceableCollection methodsFor:'comparing'!

= aCollection

    "return true if the receiver and aCollection represent collections

     with equal contents."

    |index "{ Class: SmallInteger }"

     stop  "{ Class: SmallInteger }" |

    (aCollection == self) ifTrue:[^true].

    (aCollection isKindOf:SequenceableCollection) ifFalse:[^false].

    stop := self size.

    stop == (aCollection size) ifFalse:[^false].

    index := 1.

    [index <= stop] whileTrue:[

        (self at:index) = (aCollection at:index) ifFalse:[^false].

        index := index + 1

    ].

    ^ true

    "#(1 2 3 4 5) = #(1 2 3 4 5)"

    "#($1 $2 $3 $4 $5) = #(1 2 3 4 5)"

    "#($1 $2 $3 $4 $5) = '12345'"

    "#($1 $2 $3 $4 $5) = '54321' asSortedCollection"

!

startsWith:aCollection

    "return true, if the receivers first elements match those

     of aCollection"

    |index "{ Class: SmallInteger }"

     stop  "{ Class: SmallInteger }" |

    (aCollection == self) ifTrue:[^true].

    (aCollection isKindOf:SequenceableCollection) ifFalse:[^false].

    stop := aCollection size.

    stop > self size ifTrue:[^false].

    index := 1.

    [index <= stop] whileTrue:[

        (self at:index) = (aCollection at:index) ifFalse:[^false].

        index := index + 1

    ].

    ^ true

    "'abcde' startsWith:#($a $b $c)"

    "#[1 2 3 4] startsWith:#(1 2 3)"

    "#(1 2 3 4) asOrderedCollection startsWith:#(1 2 3)"

!

endsWith:aCollection

    "return true, if the receivers last elements match those

     of aCollection"

    |index1 "{ Class: SmallInteger }"

     index2 "{ Class: SmallInteger }" 

     stop   "{ Class: SmallInteger }" |

    (aCollection == self) ifTrue:[^true].

    (aCollection isKindOf:SequenceableCollection) ifFalse:[^false].

    stop := aCollection size.

    stop > self size ifTrue:[^false].

    index1 := self size.

    index2 := stop.

    [index2 > 0] whileTrue:[

        (self at:index1) = (aCollection at:index2) ifFalse:[^false].

        index1 := index1 - 1.

        index2 := index2 - 1

    ].

    ^ true

    "'abcde' endsWith:#($d $e)"

    "#[1 2 3 4] endsWith:#(3 4)"

    "#(1 2 3 4) asOrderedCollection endsWith:#(3 4)"

! !

!SequenceableCollection methodsFor:'copying'!

, aCollection

    "return a new collection formed from concatenating the receiver with

     the argument. The class of the new collection is determined by the

     receivers class, so mixing classes is possible, if the second collections

     elements can be stored into instances of the receivers class."

    |newCollection 

     mySize    "{ Class: SmallInteger }"

     newSize   "{ Class: SmallInteger }"

     otherSize "{ Class: SmallInteger }"

     dstIndex  "{ Class: SmallInteger }"|

    mySize := self size.

    otherSize := aCollection size.

    newSize := mySize + otherSize.

    newCollection := self species new:newSize.

    newCollection replaceFrom:1 to:mySize with:self startingAt:1.

    dstIndex := mySize + 1.

    (aCollection isKindOf:SequenceableCollection) ifTrue:[

        "yes, aCollection has indexed elements"

        newCollection replaceFrom:dstIndex to:newSize

                             with:aCollection startingAt:1.

        ^ newCollection

    ] ifFalse:[

        "no, enumerate aCollection"

        aCollection do:[:element |

            newCollection at:dstIndex put:element.

            dstIndex := dstIndex + 1

        ]

    ].

    ^ newCollection

    "#($a $b $c) , #(1 2 3)"

    "#($a $b $c) , '123'"

    "'abc' , '123'"

    "'abc' , #($q $w $e $r $t $y) asSortedCollection"

    "'abc' , #(1 2 3 4 5)"  "-- will fail, since strings cannot store integers"

!

copyWith:newElement

    "return a new collection consisting of receivers elements

     plus the argument."

    |newCollection mySize newSize|

    mySize := self size.

    newSize := mySize + 1.

    newCollection := self species new:newSize.

    newCollection replaceFrom:1 to:mySize with:self startingAt:1.

    newCollection at:newSize put:newElement.

    ^newCollection

    "#(1 2 3 4 5) copyWith:$a"

    "'abcdefg' copyWith:$h"

    "'abcdefg' copyWith:'123'"  "-- will fail: string cannot be stored into string"

    "'abcdefg' copyWith:1"      "-- will fail: integer cannot be stored into string"

!

copyWithout:elementToSkip

    "return a new collection consisting of receivers elements

     without elementToSkip, if it was present. No error is reported,

     if elementToSkip is not in the collection."

    |copy skipIndex sz|

    skipIndex := self indexOf:elementToSkip startingAt:1.

    (skipIndex == 0) ifTrue:[^ self copy].

    sz := self size.

    copy := self class new:(sz - 1).

    copy replaceFrom:1 to:(skipIndex - 1) with:self startingAt:1.

    copy replaceFrom:skipIndex to:(sz - 1) with:self startingAt:(skipIndex + 1).

    ^ copy

    "#($a $b $c $d $e $f $g) copyWithout:$d"

    "#($a $b $c $d $e $f $g) copyWithout:$x"

    "#(90 80 70 60 50) asSortedCollection copyWithout:70"

!

copyFrom:start to:stop

    "return a new collection consisting of receivers elements

     between start and stop"

    |newCollection newSize|

    newSize := stop - start + 1.

    newCollection := self class new:newSize.

    newCollection replaceFrom:1 to:newSize with:self startingAt:start.

    ^ newCollection

    "#($a $b $c $d $e $f $g) copyFrom:2 to:5"

    "'1234567890' copyFrom:2 to:5"

!

copyFrom:start

    "return a new collection consisting of receivers elements

     from start to the end of the collection"

    ^ self copyFrom:start to:(self size)

    "#($a $b $c $d $e $f $g) copyFrom:2"

    "'1234567890' copyFrom:2"

!

copyTo:stop

    "return a new collection consisting of receivers elements

     from 1 up to index stop"

    ^ self copyFrom:1 to:stop

    "#($a $b $c $d $e $f $g) copyTo:5"

    "'1234567890' copyTo:4"

!

copyWithoutIndex:omitIndex

    "return a new collection consisting of receivers elements

     without the argument stored at omitIndex"

    |copy|

    copy := self class new:(self size - 1).

    copy replaceFrom:1 to:(omitIndex - 1) with:self startingAt:1.

    copy replaceFrom:omitIndex to:(copy size) 

                with:self startingAt:(omitIndex + 1).

    ^ copy

    "#(1 2 3 4 5 6 7 8 9 0) copyWithoutIndex:3"

    "'abcdefghijkl' copyWithoutIndex:5"

! !

!SequenceableCollection methodsFor:'filling and replacing'!

from:index1 to:index2 put:anObject

    "replace the elements from index1 to index2 of the collection

     by the argument, anObject.

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

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

    |index "{ Class: SmallInteger }"

     end   "{ Class: SmallInteger }"|

    index := index1.

    end := index2.

    [index <= end] whileTrue:[

        self at:index put:anObject.

        index := index + 1

    ]

    "#(1 2 3 4 5 6 7 8 9 0) from:3 to:6 put:$X"

    "'abcdefghijkl' from:3 to:6 put:$X"

!

atAllPut:anObject

    "replace all elements of the collection by the argument, anObject.

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

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

    self from:1 to:(self size) put:anObject

!

atAll:indexCollection put:anObject

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

     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"

!

replaceAll:oldObject by:newObject

    "replace all oldObjects by newObject in the receiver.

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

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

    1 to:self size do:[:index |

        (self at:index) = oldObject ifTrue:[

            self at:index put:newObject

        ]

    ]

    "'123123abc123' replaceAll:$1 by:$*"

    "#($a $b $a $c $a $d $a $e) replaceAll:$a by:$A"

!

replaceFrom:start with:replacementCollection

    "replace elements in the receiver starting at start,

     with elements taken from replacementCollection starting at 1

     to the end of replacementCollection.

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

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

    ^ self replaceFrom:start 

                    to:(start + replacementCollection size - 1)

                  with:replacementCollection

            startingAt:1

    "'1234567890' replaceFrom:5 with:'abc'"

    "#($a $b $c $d $e) replaceFrom:2 with:'123'"

!

replaceFrom:start with:replacementCollection startingAt:offset

    "replace elements in the receiver starting at start,

     with elements taken from replacementCollection starting at offset

     to the end of replacementCollection.

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

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

    ^ self replaceFrom:start 

                    to:(start + replacementCollection size - offset)

                  with:replacementCollection

            startingAt:offset

    "'1234567890' replaceFrom:5 with:'abcdef' startingAt:3"

    "#($a $b $c $d $e) replaceFrom:2 with:'12345' startingAt:4"

!

replaceFrom:start to:stop with:replacementCollection

    "replace elements in the receiver between index start and stop,

     with elements taken from replacementCollection starting at 1.

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

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

    ^ self replaceFrom:start

                    to:stop

                  with:replacementCollection

            startingAt:1

!

replaceFrom:start to:stop with:replacementCollection startingAt:repStart

    "replace elements in the receiver between index start and stop,

     with elements  taken from replacementCollection starting at repStart.

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

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

    |srcIndex "{ Class: SmallInteger }"

     dstIndex "{ Class: SmallInteger }"

     end      "{ Class: SmallInteger }" |

    (replacementCollection == self) ifTrue:[

        (repStart < start) ifTrue:[

            " must do reverse copy "

            srcIndex := repStart + (stop - start).

            dstIndex := stop.

            end := start.

            [dstIndex >= end] whileTrue:[

                self at:dstIndex put:(replacementCollection at:srcIndex).

                srcIndex := srcIndex - 1.

                dstIndex := dstIndex - 1

            ].

            ^ self

        ]

    ].

    srcIndex := repStart.

    dstIndex := start.

    end := stop.

    [dstIndex <= end] whileTrue:[

        self at:dstIndex put:(replacementCollection at:srcIndex).

        srcIndex := srcIndex + 1.

        dstIndex := dstIndex + 1

    ]

!

withCRs

    "return a new collection consisting of receivers elements

     with all \-characters replaced by cr-characters.

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

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

    ^ self copy replaceAll:$\ by:(Character cr)

!

withoutCRs

    "return a new collection consisting of receivers elements

     with all cr-characters replaced by \-characters.

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

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

    ^ self copy replaceAll:(Character cr) by:$\

! !

!SequenceableCollection methodsFor:'adding & removing'!

addFirst:anElement

    "prepend the argument, anElement to the collection."

    |newSize|

    newSize := self size + 1.

    self grow:newSize.

    self replaceFrom:2 to:newSize with:self startingAt:1.

    self at:1 put:anElement

    "#(1 2 3 4 5 6 7 8) addFirst:'hello'"

!

add:anElement

    "append the argument, anElement to the collection"

    |newSize|

    newSize := self size + 1.

    self grow:newSize.

    self at:newSize put:anElement

    "#(1 2 3 4 5 6 7 8) add:'hello'"

!

add:anElement beforeIndex:index

    "insert the first argument, anObject into the collection before slot index"

    |newSize|

    newSize := self size + 1.

    self grow:newSize.

    self replaceFrom:index + 1 to:newSize with:self startingAt:index.

    self at:index put:anElement

    "#(1 2 3 4 5 6 7 8) add:'hello' beforeIndex:5"

!

remove:anElement ifAbsent:aBlock

    "search for anElement and, if present remove it; if not present

     return the value of evaluating aBlock"

    |any 

     dstIndex "{ Class: SmallInteger }"

     sz       "{ Class: SmallInteger }"|

    dstIndex := 1.

    any := false.

    sz := self size.

    1 to:sz do:[:srcIndex |

        (anElement = (self at:srcIndex)) ifTrue:[