"{ Encoding: utf8 }"

"

 COPYRIGHT (c) 1996 by eXept Software AG

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

"{ NameSpace: Smalltalk }"

OrderedCollection subclass:#List

	instanceVariableNames:'dependents optionalAccessLock'

	classVariableNames:''

	poolDictionaries:''

	category:'Collections-Sequenceable'

!

!List class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1996 by eXept Software AG

              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

"

    Lists are mostly like OrderedCollections, but keep their dependents

    locally (which is adding a bit of performance - not functionality).

    In addition, special change notifications are emitted, whenever

    a list's contents is changed.

    Some views (SelectionIn*View and DataSetView) react specially on

    those messages and perform optimized updates.

    (the change messages pass the range-of-change as parameter).

    In ST/X, most functionality is already provided by OrderedCollection,

    so there is not much new stuff found here.

    It has been mostly provided, for ST-80 compatibility,

    where it adds sorting capabilities.

    New: 

        if the optional optionalAccessLock is set, all operations

        are protected by a critical region.

        (i.e. the List is a SynchronizedCollection)

    [caveat:]

        'List' is probably a bad name, which may confuse beginners.

        I have nothing in common with LinkedLists.

        Instances are just regular ordered collections, with the added benefit of

        sending out information about changes, and an optional synchronization lock.

        Thus, they can be used as a model of textviews or selection list views,

        which need to redraw whenever the contents of the list changes.

        (and Lists not only send out change notifications when modified,

         but also include information about the range of changed elements.

         So the view can optimize its redraws)

    [see also:]

        Array OrderedCollection

    [author:]

        Claus Gittinger

"

! !

!List methodsFor:'accessing'!

at:anIndex put:anObject

    "set the element at index, to be anIndex.

     Return anObject (sigh).

     In contrast to OrderedCollection, Lists allow putting an object

     right after the last element and auto-grow in this case;

     however, putting 2 or more indices after the last element is 

     reported as an error."

    |idx "{ Class: SmallInteger }"|

    self possiblySynchronized:[

        idx := anIndex + firstIndex - 1.

        ((anIndex < 1) or:[idx > lastIndex]) ifTrue:[

            idx == (lastIndex+1) ifTrue:[

                self makeRoomAtLast.

                lastIndex := lastIndex + 1.

            ] ifFalse:[

                ^ self subscriptBoundsError:anIndex

            ]

        ].

        contentsArray basicAt:idx put:anObject.

        dependents notNil ifTrue:[self changed:#at: with:anIndex].

    ].

    ^ anObject

    "Modified: / 28-01-1998 / 16:44:49 / cg"

    "Modified: / 01-08-2018 / 11:46:40 / Claus Gittinger"

!

list

    ^ self

!

synchronizationSemaphore

    "return a synchronization semaphore for myself"

    optionalAccessLock notNil ifTrue:[

        ^ optionalAccessLock

    ].

    ^ super synchronizationSemaphore.

    "Created: / 01-08-2018 / 13:22:45 / Claus Gittinger"

! !

!List methodsFor:'adding & removing'!

add:anObject

    "add the argument, anObject to the end of the collection

     Return the argument, anObject."

    self possiblySynchronized:[

        super add:anObject.

        dependents notNil ifTrue:[self changed:#insert: with:(self size)].

    ].

    ^ anObject

    "Modified: / 29-01-1998 / 10:52:32 / cg"

    "Modified: / 01-08-2018 / 11:46:58 / Claus Gittinger"

!

add:anObject after:oldObject

    "insert the argument, newObject after oldObject.

     If oldObject is not in the receiver, report an error,

     otherwise return the argument, anObject."

    self possiblySynchronized:[

        super add:anObject after:oldObject.

    ].

    "Created: / 19-02-2019 / 23:48:35 / Claus Gittinger"

!

add:anObject beforeIndex:index

    "add the argument, anObject to the end of the collection.

     Return the receiver (sigh - ST-80 compatibility)."

    self possiblySynchronized:[

        super add:anObject beforeIndex:index.

        dependents notNil ifTrue:[

            self changed:#insert: with:index

        ].

    ].

    "Modified (format): / 01-08-2018 / 11:47:24 / Claus Gittinger"

!

addAll:aCollection beforeIndex:index

    "insert all elements of the argument, anObject to become located at index.

     The collection may be unordered, but then the order of the sliced-in elements

     is undefined.

     Return the receiver."

    self possiblySynchronized:[

        super addAll:aCollection beforeIndex:index.

        dependents notNil ifTrue:[

            self changed: #insertCollection: with:(Array with:index with:(aCollection size))

        ]

    ]

    "Modified: / 01-08-2018 / 11:47:17 / Claus Gittinger"

!

addAll:aCollection from:startIndex to:endIndex beforeIndex:index

    "insert elements start to stop from the argument

     Return the receiver."

    self possiblySynchronized:[

        super addAll:aCollection from:startIndex to:endIndex beforeIndex:index.

        dependents notNil ifTrue:[

            self changed: #insertCollection: with:(Array with:index with:(endIndex - startIndex + 1))

        ]

    ]

    "Modified: / 29-01-1998 / 10:52:57 / cg"

    "Modified: / 30-07-2018 / 11:16:31 / Stefan Vogel"

    "Modified: / 01-08-2018 / 11:47:38 / Claus Gittinger"

!

addAllLast:aCollection

    "add all elements of the argument, aCollection to the end of the collection.

     Return the argument, aCollection."

    self possiblySynchronized:[

        self addAll:aCollection beforeIndex:self size + 1.

    ].    

    ^ aCollection

    "Modified: / 01-08-2018 / 11:47:55 / Claus Gittinger"

!

addFirst:anObject

    "add the argument, anObject to the beginning of the collection.

     Return the argument, anObject."

    self possiblySynchronized:[

        super addFirst:anObject.

        dependents notNil ifTrue:[self changed:#insert: with:1].

    ].

    ^ anObject

    "Modified: / 29-01-1998 / 10:53:09 / cg"

    "Modified: / 01-08-2018 / 11:48:05 / Claus Gittinger"

!

clearContents

    "remove all elements from the collection but keep the contentsArray.

     Useful for huge lists, if the contents will be rebuild soon (using #add:) 

     to a size which is similar to the lists current size.

     Returns the receiver."

    self possiblySynchronized:[

        |prevSize|

        prevSize := self size.

        super clearContents.

        dependents notNil ifTrue:[

            prevSize ~~ 0 ifTrue:[

                self changed:#removeFrom: with:(Array with:1 with:prevSize)

            ]

        ]

     ]

    "Modified (format): / 01-08-2018 / 11:51:29 / Claus Gittinger"

!

dropLast:n

    "remove the last n elements from the receiver collection. 

     Return the receiver."

    self possiblySynchronized:[

        | stop |

        stop := self size.

        super dropLast:n.

        dependents notNil ifTrue:[

            self changed:#removeFrom: with:(Array with:(stop - n + 1) with:stop).

        ].

    ].

    ^ self

    "Created: / 03-04-2019 / 12:40:35 / Claus Gittinger"

!

removeAll

    "remove all elements from the collection.

     Returns the receiver."

    self possiblySynchronized:[

        |prevSize|

        prevSize := self size.

        super removeAll.

        dependents notNil ifTrue:[

            prevSize ~~ 0 ifTrue:[

               self changed:#removeFrom: with:(Array with:1 with:prevSize)

           ]

        ]

    ]

    "Modified: / 29-01-1998 / 10:53:28 / cg"

    "Modified (format): / 01-08-2018 / 11:51:21 / Claus Gittinger"

!

removeAllSuchThat:aBlock

    "remove all elements that meet a test criteria as specified in aBlock.

     The argument, aBlock is evaluated for successive elements and all those,

     for which it returns true, are removed.

     Destructive: modifies the receiver.

     Return a collection containing the removed elements."

    |removedElements|

    self possiblySynchronized:[

        removedElements := super removeAllSuchThat:aBlock.

        removedElements notEmpty ifTrue:[

            self changed.

        ].

    ].

    ^ removedElements.

    "Modified: / 01-08-2018 / 11:49:44 / Claus Gittinger"

!

removeFirst

    "remove the first element from the collection; return the element."

    |deletedObject|

    self possiblySynchronized:[

        deletedObject := super removeFirst.

        dependents notNil ifTrue:[self changed:#remove: with:1].

    ].

    ^ deletedObject

    "Modified: / 29-01-1998 / 10:53:36 / cg"

    "Modified: / 01-08-2018 / 11:49:58 / Claus Gittinger"

!

removeFirst:n

    "remove the first n elements from the collection; 

     Return a collection containing the removed elements."

    |deletedObjects|

    self possiblySynchronized:[

        deletedObjects := super removeFirst:n.

        dependents notNil ifTrue:[self changed:#removeFrom: with:(Array with:1 with:n)].

    ].

    ^ deletedObjects

    "Modified: / 29-01-1998 / 10:53:40 / cg"

    "Modified: / 01-08-2018 / 11:50:10 / Claus Gittinger"

!

removeFirstIfAbsent:exceptionBlock

    "remove the first element from the collection; return the element.

     If there is no element in the receiver collection, return the value from

     exceptionBlock."

    self possiblySynchronized:[

        self notEmpty ifTrue:[ ^ self removeFirst ].

    ].

    ^ exceptionBlock value

    "Modified: / 21-10-2006 / 23:03:46 / cg"

    "Modified: / 11-04-2018 / 11:52:30 / stefan"

    "Modified: / 01-08-2018 / 11:50:26 / Claus Gittinger"

!

removeFromIndex:startIndex toIndex:stopIndex

    "remove the elements stored under startIndex up to and including

     the elements under stopIndex.

     Return the receiver.

     Returning the receiver here is a historic leftover - it may change."

    |ret|

    stopIndex < startIndex ifTrue:[^ self].

    self possiblySynchronized:[

        ret := super removeFromIndex:startIndex toIndex:stopIndex.

        dependents notNil ifTrue:[

            self changed:#removeFrom: with:(Array with:startIndex with:stopIndex).

        ].

    ].    

    ^ ret

    "Modified: / 29-01-1998 / 10:54:03 / cg"

    "Modified: / 01-08-2018 / 11:50:42 / Claus Gittinger"

!

removeIdentical:anObject ifAbsent:exceptionBlock

    "remove the first element which is identical to anObject;

     if found, remove and return it; 

     if not, return the value from evaluating exceptionBlock.

     Uses identity compare (==) to search for the element."

    self possiblySynchronized:[

        |index|

        index := self identityIndexOf:anObject.

        index == 0 ifTrue:[ ^ exceptionBlock value ].

        self removeFromIndex:index toIndex:index.

    ].    

    ^ anObject

    "Modified: / 21-10-2006 / 23:03:29 / cg"

    "Modified (format): / 01-08-2018 / 11:51:07 / Claus Gittinger"

!

removeLast

    "remove the last element from the collection; return the element"

    |deletedObject|

    self possiblySynchronized:[

        deletedObject :=  super removeLast.

        dependents notNil ifTrue:[self changed:#remove: with:(1 + self size)].

    ].

    ^ deletedObject

    "Modified: / 29-01-1998 / 10:54:15 / cg"

    "Modified: / 01-08-2018 / 11:51:51 / Claus Gittinger"

!

removeLast:n

    "remove the last n elements from the receiver collection. 

     Return a collection of removed elements."

    |deletedObjects|

    self possiblySynchronized:[

        | stop |

        stop := self size.

        deletedObjects := super removeLast:n.

        dependents notNil ifTrue:[

            self changed:#removeFrom: with:(Array with:(stop - n + 1) with:stop).

        ].

    ].

    ^ deletedObjects

    "Modified: / 29-01-1998 / 10:54:25 / cg"

    "Modified: / 01-08-2018 / 11:52:10 / Claus Gittinger"

!

removeLastIfAbsent:exceptionBlock

    "remove the last element from the collection; return the element.

     If there is no element in the receiver collection, return the value from

     exceptionBlock."

    self possiblySynchronized:[

        self notEmpty ifTrue:[ ^ self removeLast ].

    ].    

    ^ exceptionBlock value

    "Modified: / 21-10-2006 / 23:03:53 / cg"

    "Modified: / 30-07-2018 / 11:12:56 / Stefan Vogel"

    "Modified: / 01-08-2018 / 11:52:25 / Claus Gittinger"

!

reset

    "logically remove all elements from the collection.

     That's almost the same as #removeAll, but keeps the contentsArray.

     Returns the receiver."

    self possiblySynchronized:[

        |prevSize|

        prevSize := self size.

        super reset.

        dependents notNil ifTrue:[

            prevSize ~~ 0 ifTrue:[

               self changed:#removeFrom: with:(Array with:1 with:prevSize)

           ]

        ].

    ].

    "Modified: / 01-08-2018 / 11:52:46 / Claus Gittinger"

! !

!List methodsFor:'converting'!

asList

    ^ self

    "Created: 14.2.1997 / 16:25:55 / cg"

!

asSharedCollection

    "return a shared collection on the receiver.

     If the receiver is already synchronized, itself is returned. 

     This implements synchronized (i.e. mutually excluded) access to me.

     Use this for safe access when multiple processes access me concurrently."

    optionalAccessLock notNil ifTrue:[

        "I am alreay protected against concurrent access"

        ^ self

    ].

    ^ (List withAll:self)

            beSynchronized;

            yourself.