eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'OrderedSet':

Home

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

Class: OrderedSet

Inheritance:

   Object
   |
   +--Collection
      |
      +--Set
         |
         +--OrderedSet
            |
            +--SortedSet
Package:
stx:libbasic
Category:
Collections-Sequenceable
Version:
rev: 1.57 date: 2024/01/24 08:53:26
user: cg
file: OrderedSet.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


I am a subclass of Set whose elements are ordered in a
similar fashion to OrderedCollection.
That is, I have both Set behavior (only keeping a single instance of
an element) but I also remember the original order, in which elements
were added.
Therefore, this combines fast access/check/add via hashing with a defined 
order when enumerating.

[instance variables:]
    order <OrderedCollection>       Ordered collection of values reflecting the order 
                                    in the set. 


copyright
COPYRIGHT (c) 2001 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:

instance creation
o  new: anInteger
(comment from inherited method)
return a new empty Set with space for anInteger elements

Instance protocol:

accessing
o  at: index
return the indexed instance variable with index, anInteger.
Report an error, if the index is wrong.

o  at: index ifAbsent: exceptionalValue
return the indexed instance variable with index, anInteger.
If not present, return the value from exceptionalValue.

o  atIndex: index
return an element at a given index.

o  atIndex: index ifAbsent: exceptionalValue
return an element at a given index

o  first
Return the first element in the receiver

o  last
Return the last element in the receiver

o  order
returns the values in the order of their appearance

Usage example(s): 

     |s|

     s := OrderedSet new.
     s add:'aaa'; add:'bbb'; add:'ccc'; add:'ddd'; add:'aaa'.
     s order

adding & removing
o  add: anObject
Add anObject to the receiver (if not already included).
Also, remember in the order (i.e. add to the end)
If anObject is already present in the set,
the order will not be changed. (See also: #addLast:)

Usage example(s): 

        self new 
                add:1;
                add:2;
                add:nil;
                add:1;
                yourself

o  addFirst: anObject
Add anObject to the receiver (if not already included).
Also, remember in the order (i.e. add to the beginning).
If anObject is already present in the receiver,
it will be moved to the beginning.

Usage example(s): 

        self new inspect
                addFirst:1;
                addFirst:nil;
                addFirst:2;
                yourself

o  addLast: anObject
Add anObject to the receiver (if not already included).
Also, remember in the order (i.e. add to the end)
If anObject is already present in the receiver,
it will be moved to the end. (See also: #add:)

Usage example(s): 

        self new 
                addLast:1;
                addLast:nil;
                addLast:1;
                yourself

o  addOrReplace: anObject
Add the argument, anObject to the receiver.
If it is already included, replace it by anObject.
Return nil, if anObject was not present in the receiver,
otherwise the element that has been replaced.
Notice: this sounds like a useless operation, but because sets compare by equality,
the old object may be replaced by another object when equeal, but not identical.
For example, a string by a symbol or a float by an integer...

Also, remember in the order (i.e. add to the end)
If anObject is already present in the set,
the order will not be changed.

Usage example(s): 

        Note that 1 is replaced by 1.0, but 1.0 is still at the beginning:

        self new 
                addOrReplace:1;
                addOrReplace:2;
                addOrReplace:nil;
                addOrReplace:1.0;
                yourself

o  clearContents
remove all elements from the receiver, but do not shrink. Returns the receiver.

o  remove: oldObject ifAbsent: exceptionValueProvider
remove oldObject from the collection and return it.
If it was not in the collection return the value of exceptionValueProvider.

WARNING: do not remove elements while iterating over the receiver.

Usage example(s): 

     OrderedSet new remove:nil

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

o  removeFirst
remove the first object from the collection and return it.
If it was not in the collection, raise an error.

WARNING: do not remove elements while iterating over the receiver.

o  removeFirstIfAbsent: exceptionalValue
remove the first object from the collection and return it.
If it was not in the collection, return the value from exceptionalValue.

WARNING: do not remove elements while iterating over the receiver.

o  removeIdentical: oldObject ifAbsent: exceptionValueProvider
remove oldObject from the collection and return it.
If it was not in the collection return the value of exceptionValueProvider.

WARNING: do not remove elements while iterating over the receiver.

Usage example(s): 

     |s ef er|

     s := OrderedSet new. 
     s add:'abc'.
     s add:'def'.
     s add:'ghi'.
     ef := s detect:[:el | el = 'def'].
     er := s removeIdentical:ef.
     s addFirst:er.
     s

o  removeLast
remove the last object from the collection and return it.
If it was not in the collection, raise an error.

WARNING: do not remove elements while iterating over the receiver.

o  removeLastIfAbsent: exceptionalValue
remove the last object from the collection and return it.
If it was not in the collection, return the value from exceptionalValue.

WARNING: do not remove elements while iterating over the receiver.

o  safeRemove: oldObject ifAbsent: exceptionValueProvider
remove the element, oldObject from the collection.
Return the element
(could be non-identical to oldObject, since I hash on equality, not on identity).
If it was not in the collection return the value of exceptionValueProvider.

In contrast to #remove:, this does not resize the underlying collection
and therefore does NOT rehash & change the elements order.
Therefor this can be used while enumerating the receiver,
which is not possible if #remove: is used.

WARNING: since no resizing is done, the physical amount of memory used
by the container remains the same, although the logical size shrinks.
You may want to manually resize the receiver using #emptyCheck.
(after the loop)

o  safeRemoveIdentical: oldObject ifAbsent: exceptionValueProvider
remove the element, oldObject from the collection.
Return the element
(could be non-identical to oldObject, since I hash on equality, not on identity).
If it was not in the collection return the value of exceptionValueProvider.

In contrast to #remove:, this does not resize the underlying collection
and therefore does NOT rehash & change the elements order.
Therefor this can be used while enumerating the receiver,
which is not possible if #remove: is used.

WARNING: since no resizing is done, the physical amount of memory used
by the container remains the same, although the logical size shrinks.
You may want to manually resize the receiver using #emptyCheck.
(after the loop)

o  testAndAdd: anObject
Test, if the element is present in the receiver.
Answer true, if the element was already in the collection, false otherwise.
If the element does not exist, add it to the collection.
Also, remember in the order (i.e. add to the end)
If anObject is already present in the set,
the order will not be changed. (See also: #addLast:)

converting
o  asArray
OrderedSet new asArray
stx_libtool allPreRequisitesWithMandatorySorted asArray

o  asNewOrderedCollection
safeguard to always return a new OrderedCollection:
superclass Collection implements this as 'self asOrderedCollection'

Usage example(s): 

        OrderedSet new asNewOrderedCollection
        stx_libtool allPreRequisitesWithMandatorySorted asNewOrderedCollection

o  asNewOrderedSet
make sure to return a unique new set

o  asOrderedCollection
OrderedSet new asOrderedCollection
stx_libtool allPreRequisitesWithMandatorySorted asOrderedCollection

o  asOrderedSet
make sure to return a unique new set

copying-private
o  postCopy
have to copy the keyArray too

enumerating
o  collect: collectBlock thenSelect: selectBlock
Evaluate aBlock for each of the sets's values
in the order they have been added.

Usage example(s): 

     |s|
     s := OrderedSet withAll:#(1 2 3 1 2 3 4 5 6 4 5 6).
     (s collect:[:el |el * 3]) select:#even.
     s collect:[:el |el * 3] thenSelect:#even.

o  do: aBlock
Evaluate aBlock for each of the sets's values
in the order they have been added.

o  doWithIndex: aBlock
Squeak/V'Age compatibility;
Evaluate aBlock for each of the sets's values and index
in the order they have been added.
like keysAndValuesDo:, but passes the index as second argument.
Same as withIndexDo:, due to parallel evolution of different Smalltalk dialects

o  keysAndValuesDo: aBlock
Evaluate aBlock for each of the sets's index and values
in the order they have been added.

o  reverseDo: aBlock
Evaluate aBlock for each of the sets's values
in the reverse order they have been added.

o  withIndexDo: aBlock
evaluate the argument, aBlock for every element in the collection,
passing both element and index as arguments.
Same as doWithIndex:, due to parallel evolution of different Smalltalk dialects

initialization
o  initializeOrder: count

private
o  orderContainerOfSize: n

searching
o  findFirst: aBlock ifNone: exceptionValue
find the index of the first element, for which evaluation of the argument, aBlock returns true;
return its index or the value from exceptionValue if none detected.
This is much like #detect:ifNone:, however, here an INDEX is returned,
while #detect:ifNone: returns the element.

o  findFirst: aBlock startingAt: startIndex
find the index of the first element, for which evaluation of the argument, aBlock returns true.
Start the search at startIndex.
Return its index or 0 if none detected.
This is much like #detect:startingAt:, however, here an INDEX is returned,
whereas #detect: returns the element.

o  findFirst: aBlock startingAt: startIndex ifNone: exceptionValue
find the index of the first element, for which evaluation of the argument, aBlock returns true;
return its index or the value from exceptionValue if none detected.
This is much like #detect:ifNone:, however, here an INDEX is returned,
while #detect:ifNone: returns the element.

Usage example(s): 

     |s|

     s := OrderedSet new.
     s add:1.
     s add:2.
     s add:1.
     s add:4.
     s add:2.
     s add:5.
     s.          
     self assert:(s findFirst:[:el | el even]) == 2.  
     self assert:(s findFirst:[:el | el > 3]) == 3.  
     self assert:(s findFirst:[:el | el odd]) == 1.

o  findLast: aBlock ifNone: exceptionValue
find the index of the last element, for which evaluation of the argument, aBlock returns true.
Return its index or the value from exceptionValue if none detected.

o  indexOf: anObject
return the index of anObject or 0 if not found in the collection.
Compare using =

testing
o  isOrdered
return true, if the receiver's elements are ordered.
Re-redefined to true here, as I do have an order

Examples:


        |s|

        s := OrderedSet new.
        s add:'one'.
        s add:'two'.
        s add:'one'.
        s add:'two'.
        s add:'three'.
        s size.         
        s do:[:each | Transcript showCR:each].         

        |s|

        s := OrderedSet new.
        s add:'one'.
        s add:'two'.
        s add:'one'.
        s add:'two'.
        s add:'three'.
        s remove:'one'.
        s size.         
        s do:[:each | Transcript showCR:each].         

        |s|

        s := OrderedSet new.
        s add:'one'.
        s addFirst:'two'.
        s addFirst:'three'.
        s add:'one'.
        s add:'two'.
        s add:'three'.
        s size.         
        s do:[:each | Transcript showCR:each].         

        |s|

        s := OrderedSet new.
        s add:'one'.
        s add:'two'.
        s add:'one'.
        s add:'two'.
        s add:'three'.
        s size.         
        s keysAndValuesDo:[:idx :each | Transcript showCR:idx->each].

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sun, 22 Dec 2024 02:45:53 GMT