eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'List':

Home

Documentation
www.exept.de
Everywhere
for:
 [back]

Class: List

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--OrderedCollection
            |
            +--List
               |
               +--AbstractFileBrowser::DirectoryHistory
               |
               +--HierarchicalList
               |
               +--Tools::TagList
Package:
stx:libbasic2
Category:
Collections-Sequenceable
Version:
rev: 1.76 date: 2023/12/19 20:44:21
user: cg
file: List.st directory: libbasic2
module: stx stc-classLibrary: libbasic2

Description:


Lists are mostly like OrderedCollections, but keep their dependents
locally (which is adding a bit of performance - not functionality).
In addition, special detail change notifications are emitted, whenever
a list's contents is changed, so that list views can update the
redraw on changes.
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 SharedCollection)
    
[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)
    


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.

Class protocol:

instanceCreation
o  newSynchronized
instantiate a new synchronized List

Usage example(s): 

        self newSynchronized

Instance protocol:

accessing
o  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.

o  list

o  synchronizationSemaphore
return a synchronization semaphore for myself;
this will be used by synchronized:[...]

adding & removing
o  add: anObject
add the argument, anObject to the end of the collection
Return the argument, anObject.

o  add: anObject after: oldObject
insert the argument, newObject after oldObject.
oldObject is searched by equality.
If oldObject is not in the receiver, report an error,
otherwise return the argument, anObject.

o  add: anObject afterIdentical: oldObject
insert the argument, newObject after oldObject.
oldObject is searched by identity.
If oldObject is not in the receiver, report an error,
otherwise return the argument, anObject.

o  add: anObject before: oldObject
insert the argument, newObject before oldObject.
oldObject is searched by equality.
If oldObject is not in the receiver, report an error,
otherwise return the argument, anObject.

o  add: anObject beforeIdentical: oldObject
insert the argument, newObject before oldObject.
oldObject is searched by identity.
If oldObject is not in the receiver, report an error,
otherwise return the argument, anObject.

o  add: anObject beforeIndex: index
add the argument, anObject to the end of the collection.
Return the receiver (sigh - ST-80 compatibility).

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

o  addAll: aCollection from: startIndex to: endIndex beforeIndex: index
insert elements start to stop from the argument
Return the receiver.

o  addAllLast: aCollection
add all elements of the argument, aCollection to the end of the collection.
Return the argument, aCollection.

o  addFirst: anObject
add the argument, anObject to the beginning of the collection.
Return the argument, anObject.

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

o  dropAllSuchThat: 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.
Differs from #removeAllSuchThat: returns self
instead of a collection containing the removed elements.

o  dropFirst: n
remove the first n elements from the collection;
Return the receiver.

o  dropLast: n
remove the last n elements from the receiver collection.
Return the receiver.

o  removeAll
remove all elements from the collection.
Returns the receiver.

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

o  removeFirst
remove the first element from the collection; return the element.

o  removeFirst: n
remove the first n elements from the collection;
Return a collection containing the removed elements.

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

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

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

o  removeLast
remove the last element from the collection; return the element

o  removeLast: n
remove the last n elements from the receiver collection.
Destructive: modifies the receiver.
Return a collection of removed elements.

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

o  reset
logically remove all elements from the collection.
That's almost the same as #removeAll, but keeps the contentsArray.
Returns the receiver.

converting
o  asList
return the receiver as it is already a list

o  asOrderedCollection
return a new collection with the same elements as the receiver

Usage example(s): 

     (List withAll:#(1 2 3 4 5 6)) asOrderedCollection

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

o  skippedInJSONEncoding
( an extension from the stx:goodies/communication package )
return the names of inst-slots which are to be skipped when generating a jsonEncoding;
(to skip the ones with default or irrelevant values.)

copying
o  skipInstvarIndexInDeepCopy: index
a helper for deepCopy; only indices for which this method returns
false are copied in a deep copy.

dependents access
o  addDependent: anObject
make the argument, anObject be a dependent of the receiver.

o  dependents
return the dependents of the receiver

o  dependents: aCollection
set the dependents of the receiver

o  nonWeakDependents
return a Collection of dependents - empty if there is none.
Since all dependencies are nonWeak in List, this is a dummy.

o  nonWeakDependents: newDeps
return a Collection of dependents - empty if there is none.
Since all dependencies are nonWeak in List, this is a dummy.

o  removeDependent: anObject
make the argument, anObject be independent of the receiver.
Since all dependencies are nonWeak in Model, this is simply
forwarded to removeDependent:

o  withoutSendingUpdatesDo: aBlock
execute aBlock with updates to dependents temporarily suppressed
(i.e. I will not notify the dependents during aBlock)
Warning:
do not change any dependencies inside the block,
as the original dependencies from before will be restored and such changes
are lost then.
Same code as in Model

filling & replacing
o  contents: aCollection
replace all elements in the receiver by aCollection,
Redefined - can be done faster

Usage example(s): 

      |l|
      l := List new.
      l contents:#(1 2 3 4 5).
      l        

      |l|
      l := List new.
      l addAll:#(1 2 3 4 5).
      l contents:#(10 20 30).
      l       

      |l|
      l := List new.
      l addAll:#(1 2 3 4 5).
      l contents:#(10 20 30 40 50 60 70 80).
      l      

      |l|
      l := List new.
      l addAll:#(1 2 3 4 5).
      l contents:#(10 20 30 40 50).
      l      

      |l|
      l := List new.
      l addAll:#(1 2 3 4 5) asSet.
      l contents:#(10 20 30 40 50) asSet.
      l

o  list: aCollection
replace all elements in the receiver by aCollection.
For compatibility with other smalltalks
(allows List to be sometimes used as a ListPresenter in ported Dolphin apps)

Usage example(s): 

     |l|
     l := List new.
     l list:#(1 2 3 4 5).
     l        

     |l|
     l := List new.
     l addAll:#(1 2 3 4 5).
     l list:#(10 20 30).
     l       

     |l|
     l := List new.
     l addAll:#(1 2 3 4 5).
     l list:#(10 20 30 40 50 60 70 80).
     l      

     |l|
     l := List new.
     l addAll:#(1 2 3 4 5).
     l list:#(10 20 30 40 50).
     l

o  replaceFrom: start to: stop with: aCollection startingAt: repStart
replace elements in the receiver between index start and stop,
with elements taken from aCollection starting at repStart.
Redefined - can be done faster

o  setContents: aCollection
replace the receiver's underlying collection by aCollection

private
o  possiblySynchronized: aBlock

o  synchronized: aBlock
a shortcut, if the sync-sema is already present;
return the value from aBlock

setup
o  beSynchronized
make the receiver a synchronized List

Usage example(s): 

        |list oldSema|

        list := List new.
        list synchronized:[list add:1].
        oldSema := list synchronizationSemaphore.
        list beSynchronized.
        self assert:oldSema == list synchronizationSemaphore.
        oldSema

testing
o  isList
return true, if the receiver is some kind of list collection;
true is returned here - the method is redefined from Object.


ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 02:46:43 GMT