"

 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.

"

"{ Package: 'stx:libbasic' }"

"{ NameSpace: Smalltalk }"

Collection subclass:#SequenceableCollection

	instanceVariableNames:''

	classVariableNames:''

	poolDictionaries:''

	category:'Collections-Abstract'

!

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

"

    SequenceableCollections have ordered elements which can be accessed via a numeric index.

    SequenceableCollection is an abstract class - there are no direct instances of it in the system.

    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 detail of how elements are stored.

    Especially, bulk data manipulation (i.e. #replaceFrom:to:with:startingAt:)

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

    The most heavily used SequentialCollections in the system are probably Array, String, ByteArray

    OrderedCollection and SortedCollection.

    [author:]

        Claus Gittinger

    [see also:]

        Array ByteArray OrderedCollection SortedCollection 

        CharacterArray String

"

! !

!SequenceableCollection class methodsFor:'initialization'!

initialize

"/ now a class based exception

"/ method here left as a comment for a while.

"/ will go away soon...

"/    MissingClassInLiteralArrayErrorSignal isNil ifTrue:[

"/        MissingClassInLiteralArrayErrorSignal := Error newSignalMayProceed:true.

"/        MissingClassInLiteralArrayErrorSignal nameClass:self message:#missingClassInLiteralArrayErrorSignal.

"/        MissingClassInLiteralArrayErrorSignal notifierString:'Missing class in literal encoding'.

"/    ]

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

    |collection

     sz "{ Class: SmallInteger }"|

    sz := anArray size.

    collection := self mutableClass newWithSize:sz-1.

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

    ^ collection

    "

     Array decodeFromLiteralArray:#(Array 1 2 3)

    "

!

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|

    totalSize := aCollectionOfCollections

			inject:0

			into:[:sumSoFar :el | sumSoFar + el size].

    newColl := self new:totalSize.

    idx := 1.

    aCollectionOfCollections do:[:el |

	|sz|

	sz := el size.

	newColl replaceFrom:idx to:(idx+sz-1) with:el startingAt:1.

	idx := idx + sz

    ].

    ^ newColl

    "

     this method optimizes the following (common) operation:

	 |s|

	 s := ''.

	 #('hello' ' ' 'world' ' ' 'this is ' 'ST/X') do:[:e|

	    s := s , e.

	 ].

	 s

     String

	newWithConcatenationOfAll:#('hello' ' ' 'world' ' ' 'this is ' 'ST/X')

     String

	newWithConcatenationOfAll:#()

     Array

	newWithConcatenationOfAll:#( (1 2 3 4) (5 6 7 8) (9 10 11 12) )

     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 |

	 t := Time millisecondsToRun:[

	    cnt timesRepeat:[

		String

		    newWithConcatenationOfAll:arr

	    ]

	 ].

	 Transcript showCR:(arr size printString , ' elements - time for #newWithConcatenationOfAll :' , (t/cnt) asFloat printString , 'mS').

	 Transcript endEntry.

	 t := Time millisecondsToRun:[

	    cnt timesRepeat:[

		 |s|

		 s := ''.

		 arr do:[:e|

		    s := s , e.

		 ].

		 s

	    ]

	 ].

	 Transcript showCR:(arr size printString , ' elements - time for loop over #, :' , (t/cnt) asFloat printString , 'mS').

	 Transcript endEntry.

     ]

    "

!

newWithSize: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."

    ^ (self new:size) grow:size.

    "

     (OrderedCollection new:10) inspect.

     (OrderedCollection withSize:10) inspect.

     (Array new:10) inspect.

     (Array withSize:10) inspect.

    "

!

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

    ^ (self new:size) grow:size.

    "

     (OrderedCollection new:10) inspect.

     (OrderedCollection withSize:10) inspect.

     (Array new:10) inspect.

     (Array withSize:10) inspect.

    "

! !

!SequenceableCollection class methodsFor:'Signal constants'!

missingClassInLiteralArrayErrorSignal

    "raised when decoding a literal array spec,

     when a non-existing class is encountered

     (i.e. a spec-element of the form (ClassNameSymbol args...),

      where ClassNameSymbol refers to a non-existing class)"

    "/ now a class based exception.

    "/ method here will vanish sometime..

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

     I.e.

	Array[n]

     generates

	Array _at: n

    "

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

     I.e.

        Array[n,m]

     generates

        Array _at:n at:m

    "

    |data|

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

    ^ MultiDimensionalArrayAccessor

        collection:data

        dimensions:(Array with:dim1 with:dim2)

!

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

     I.e.

        Array[n,m,o]

     generates

        Array _at:n at:m at:o

    "

    |data|

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

    ^ MultiDimensionalArrayAccessor

        collection:data

        dimensions:(Array with:dim1 with:dim2 with:dim3)

! !

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

new:newSize streamContents:blockWithArg 

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

     evaluate blockWithArg, passing that stream,

     extract and return the streams contents."

    |stream|

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

    blockWithArg value:stream.

    ^ stream contents

!

new:initialSize withCollectedContents:blockWithArg

    "create an instance of the receiver-class,

     evaluate blockWithArg, passing that instance,

     return the instance.

     Similar to streamContents, but passes the collection to the block,

     instead of a stream."

    |inst|

    inst := self new:initialSize.

    blockWithArg value:inst.

    ^ inst

    "

     |rslt|

     rslt := OrderedCollection new:10 withCollectedContents:[:c | c add:'hello'; add:'world']

    "

!

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 := self writeStream.

    blockWithArg value:stream.

    ^ stream contents

    "

     |rslt|

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

    "

    "Modified: / 29-03-2007 / 15:20:20 / cg"

!

streamContents:blockWithArg limitedTo:limit

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

     evaluate blockWithArg, passing that stream,

     extract and return the streams contents (possibly truncated)."

    |stream|

    stream := self writeStream.

    stream writeLimit:limit.

    blockWithArg value:stream.

    ^ stream contents

    "Created: / 04-06-2007 / 17:22:38 / cg"

!

streamContentsEnumerating:aReceiver using:enumeratorSelector

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

     enumerate on aReceiver using enumeratorSelector as a do-block-selector,

     and return the collected values. Especially useful, if you have a do-like

     enumerator somewhere, and you want this as a collection."

    |stream|

    stream := self writeStream.

    aReceiver perform:enumeratorSelector with:[:each |stream nextPut:each].

    ^ stream contents

    "

     String streamContentsEnumerating:'hello' using:#reverseDo:

     Array streamContentsEnumerating:Method using:#allInstancesDo:

    "

    "Created: / 29-03-2007 / 15:21:12 / cg"

!

streamContentsOf:aReceiver enumerator:enumeratorSelector

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

     enumerate on aReceiver using enumeratorSelector as a do-block-selector,

     and return the collected values. Especially useful, if you have a do-like

     enumerator somewhere, and you want this as a collection."

    |stream|

    stream := self writeStream.

    aReceiver perform:enumeratorSelector with:[:each |stream nextPut:each].

    ^ stream contents

    "

     String streamContentsOf:'hello' enumerator:#reverseDo:

     Array streamContentsOf:Method enumerator:#allInstancesDo:

    "

    "Created: / 29-03-2007 / 15:05:30 / cg"

!

withCollectedContents:blockWithArg

    "create an instance of the receiver-class,

     evaluate blockWithArg, passing that instance,

     return the instance.

     Similar to streamContents, but passes the collection to the block,

     instead of a stream."

    |inst|

    inst := self new.

    blockWithArg value:inst.

    ^ inst

    "

     |rslt|

     rslt := OrderedCollection withCollectedContents:[:c | c add:'hello'; add:'world']

    "

!

writeStream

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

    ^ self writeStreamClass on:(self new:50).

    "

     OrderedCollection writeStream

     Text writeStream

    "

    "Modified: / 09-01-2011 / 10:37:35 / cg"

!

writeStreamWithInitialSize:l

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

    ^ self writeStreamClass on:(self new:l).

    "

     OrderedCollection writeStream

    "

    "Created: / 09-01-2011 / 10:36:28 / cg"

! !

!SequenceableCollection class methodsFor:'queries'!

isAbstract

    "Return if this class is an abstract class.

     True is returned for SequenceableCollection here; false for subclasses.

     Abstract subclasses must redefine this again."

    ^ self == SequenceableCollection

! !

!SequenceableCollection methodsFor:'Compatibility-Squeak'!

allButFirst

    "Return a copy of the receiver containing all but the first element.

     Returns an empty collection if there are not at least two elements.

     Differs from #copyButFirst in its error behavior."

    ^ self allButFirst:1

    "

     '1234567890' allButFirst

     'ab' allButFirst

     'a' allButFirst

     '' allButFirst

     '' copyButFirst

    "

!

allButFirst:n

    "Return a copy of the receiver containing all but the first n elements.

     Returns a short (or empty) collection if there are not enough elements.

     Differs from #copyButFirst: in its error behavior."

    n > self size ifTrue:[^ self copyEmpty].

    ^ self copyFrom:n+1

    "

     '1234567890' allButFirst:5 

     '123456' allButFirst:5       

     '12345' allButFirst:5       

     '1234' allButFirst:5       

     '1234' copyButFirst:5       

    "

!