"

 COPYRIGHT (c) 1989 by Claus Gittinger

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

Collection subclass:#SequenceableCollection

	instanceVariableNames:''

	classVariableNames:'MissingClassInLiteralArrayErrorSignal'

	poolDictionaries:''

	category:'Collections-Abstract'

!

!SequenceableCollection class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1989 by Claus Gittinger

 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

"

    SequenceableCollections have ordered elements which can be accessed via

    The methods found here assume that implementations of (at least)

    #at:/#at:put: are implemented (which are always found in Object for

    indexable objects).

    For performance, some subclasses redefine more methods, knowing the details

    and search methods (i.e. #indexOf:startingAt:) are good candidates for this

    kind of tuneup.

    See concrete subclasses (such as OrderedCollection, Array or String).

    [author:]

    [see also:]

"

! !

!SequenceableCollection class methodsFor:'initialization'!

initialize

    MissingClassInLiteralArrayErrorSignal isNil ifTrue:[

    ]

    "Created: / 18.5.1999 / 14:49:51 / cg"

! !

!SequenceableCollection class methodsFor:'instance creation'!

decodeFromLiteralArray:anArray

    "create & return a new instance from information encoded in anArray.

     Redefined for faster creation."

     sz "{ Class: SmallInteger }"|

    sz := anArray size.

    collection := self withSize:sz-1.

    2 to:sz do:[:idx| collection at:idx-1 put:(anArray at:idx) decodeAsLiteralArray].

    ^ collection

    "

     Array

    "

!

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

!

newWithConcatenationOfAll:aCollectionOfCollections

    "this creates and returns a new collection consisting

     of the concatenation of all elements of the argument.

     I.e. it has the same effect as concatenating all elements

     of the argument using #, ,but is implemented more efficiently,

     by avoiding repeated garbage allocations.

     This is an O runtime algorithm, in contrast to the #, loop, which is O*O"

    |totalSize newColl idx|

    newColl := self new:totalSize.

    idx := 1.

    aCollectionOfCollections do:[:el |

    ].

    ^ newColl

    "

     this method optimizes the following (common) operation:

     Array

     timing:

     -------

     speed-break-even is at around 5 elements for strings;

     for more elements, #newWithConcatenationOfAll: is much faster.

     |arr1 arr2 arr3 t|

     arr1 := #('hello' ' ' 'world' ' ' 'this is ' 'ST/X').

     arr2 := Array new:1000 withAll:'hello'.

     arr3 := Array new:10000 withAll:'hello'.

     (Array with:arr1 with:arr2 with:arr3) with:#(10000 100 10) do:[:arr :cnt |

     ]

    "

!

withSize:size

    "return a new collection of size.

     For variable size collections, this is different from #new:,

     in that #new: creates an empty collection with preallocated size,

     while #withSize: creates a non empty one."

    |newCollection|

    newCollection := self new:size.

    newCollection grow:size.

    ^ newCollection

    "

     (OrderedCollection new:10) inspect.

     (OrderedCollection withSize:10) inspect.

     (Array new:10) inspect.

     (Array withSize:10) inspect.

    "

! !

!SequenceableCollection class methodsFor:'Compatibility-Squeak'!

streamContents:blockWithArg

    "create a write-stream on an instance of the receiver-class,

     evaluate blockWithArg, passing that stream,

     extract and return the streams contents."

    |stream|

    stream := WriteStream on:(self new:100).

    blockWithArg value:stream.

    ^ stream contents

    "

     |rslt|

     rslt := String streamContents:[:s | s nextPutAll:'hello'; space; nextPutAll:'world']

    "

    "Modified: / 31.10.2001 / 09:25:45 / cg"

!

writeStream

    "create a write-stream on an instance of the receiver-class"

    ^ WriteStream on:(self new:100).

    "

     String writeStream

    "

! !

!SequenceableCollection class methodsFor:'Signal constants'!

missingClassInLiteralArrayErrorSignal

    ^ MissingClassInLiteralArrayErrorSignal

    "Created: / 18.5.1999 / 14:50:04 / cg"

! !

!SequenceableCollection class methodsFor:'instance creation-multiDimensional'!

_at:nIndices

    "this is a synthetic selector, generated by the compiler,

     if a construct of the form expr[idx...] is parsed.

     generates

    "

    ^ self new:nIndices

!

_at:dim1 at:dim2

    "this is a synthetic selector, generated by the compiler,

     if a construct of the form expr[idx...] is parsed.

     generates

    "

    |data|

    data := self withSize:(dim1 * dim2).

    ^ MultiDimensionalArrayAccessor

!

_at:dim1 at:dim2 at:dim3

    "this is a synthetic selector, generated by the compiler,

     if a construct of the form expr[idx...] is parsed.

     generates

    "

    |data|

    data := self withSize:(dim1 * dim2 * dim3).

! !

!SequenceableCollection methodsFor:'Compatibility-Squeak'!

allButFirst

     Raise an error if there are not enough elements."

    ^ self copyFrom:2

    "

     '1234567890' allButFirst

    "

!

allButFirst:n

     Raise an error if there are not enough elements."

    ^ self copyFrom:n+1

    "

     '1234567890' allButFirst:5

    "

!

allButLast

     Raise an error if there are not enough elements."

    ^ self allButLast:1

    "

     '1234567890' allButLast

    "

    "Modified: / 13.11.2001 / 13:36:36 / cg"

!

allButLast:n

     Raise an error if there are not enough elements."

    ^ self copyFrom: 1 to: self size - n

    "

     '1234567890' allButLast:5

    "

    "Modified: / 13.11.2001 / 13:36:28 / cg"

!

    "Return the index'th element of me if possible.

     Return the first or last element if index is out of bounds."

    index < 1 ifTrue:[^ self first].

    index > self size ifTrue:[^ self last].

    ^ self at:index

    "

    "Return any random element from the receiver"

    ^ self atRandom:Random

    "

    "Return any random element from the receiver"

    |max idx|

    (max := self size) == 0 ifTrue:[

    ].

    idx := aRandomGenerator nextIntegerBetween:1 and:max.

    ^ self at:idx

    "

    "Return the index'th element of me if possible.

     Wrap the index modulu the receivers size if it is out of bounds."

    ^ self at:((index - 1) \\ (self size)) + 1

    "

    "

!

beginsWith:aCollection

    "Squeak & VW compatibility: same as #startsWith: - sigh"

    ^ self startsWith:aCollection

    "Modified: / 13.11.2001 / 13:49:18 / cg"

!

collect:aBlock from:startIndex to:stopIndex

    "squeak uses a different naming here - sigh.

     Notice, that the squeak name is actually wrong and misleading, as it suggests

     collecting first and then taking the subcollection; this is wrong, as conceptually,

     this method first takes a slice (from:to:) and then collects over that.

     I.e. it is equivalent to:

    ^ self from:startIndex to:stopIndex collect:aBlock

!

copyAfter: anElement

    |idx|

    idx := self indexOf:anElement.

    idx == 0 ifTrue:[idx := self size].

    ^ self copyFrom:idx + 1

    "

    "

!

copyAfterLast:element

     of element to the end; uses = for comparison"

    |idx|

    idx := self lastIndexOf:element.

    idx == 0 ifTrue:[idx := self size].

    ^ self copyFrom:idx + 1

    "

    "

!

copyUpToLast:element

     of element; uses = for comparison"

    |idx|

    idx := self lastIndexOf:element.

    idx == 0 ifTrue:[idx := self size + 1].

    ^ self copyTo:idx - 1

    "

    "

!

copyWithoutAll:elementsToSkip

    "return a new collection consisting of a copy of the receiver, with

     ALL elements equal to any in elementsToSkip are left out.