Class: KeyedCollection

• Inheritance
• Description
• Class protocol
  • instance creation
  • queries
• Instance protocol
  • accessing
  • enumerating
  • misc ui support
  • removing
  • searching
  • testing

Inheritance:

   Object
   |
   +--Collection
      |
      +--KeyedCollection
         |
         +--BTree
         |
         +--MethodDictionary
         |
         +--RBSmallDictionary
         |
         +--TSTree

Package:

stx:libbasic

Category:

Collections-Abstract

Version:

rev: 1.17 date: 2017/04/28 12:39:45

user: stefan

file: KeyedCollection.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

Abstract superclass for collections which have a key->value mapping.
This abstract class provides functionality common to those collections,
without knowing how the concrete class implements things. 
Thus, all methods found here depend on some basic mechanisms 
to be defined in the concrete class. 
These basic methods are usually defined as #subclassResponsibility here.
Some methods are also redefined for better performance.

Subclasses should at least implement:
    at:ifAbsent:        - accessing elements
    removeKey:ifAbsent  - removing
    keysAndValuesDo:    - enumerating

Class protocol:

 withAll: aDictionary

create a MethodDictionary from another Dictionary

 withAssociations: aCollectionOfAssociations

return a new instance where associations are taken from the argument

usage example(s):

KeyValueList withAssociations:{ #'one'->1 . #'two'->2 . #'three'->3 . #'four'->4 }

 withKeys: keyArray andValues: valueArray

return a new instance where keys and values are taken from
the argumentArrays.

 withKeysAndValues: anArray

return a new instance where keys and values are taken from alternating
elements of anArray

usage example(s):

KeyValueList withKeysAndValues:#('one' 1 'two' 2 'three' 3 'four' 4)

 isAbstract

Return if this class is an abstract class.
True is returned for KeyedCollection here; false for subclasses.
Abstract subclasses must redefine this again.

Instance protocol:

 associationAt: aKey

return an association consisting of aKey and the element indexed
by aKey -
report an error, if no element is stored under aKey.

 associationAt: aKey ifAbsent: exceptionBlock

return an association consisting of aKey and the element indexed by aKey -
return result of exceptionBlock if no element is stored under aKey.
Warning: this is a comatibility interface only, with a different semantic as
the original ST80 implementation. The returned assoc is created on the fly,
and not the one stored in the receiver (there are not assocs there)

 associations

return an ordered collection containing the receiver's associations.

 at: key

return the value stored under akey.
Raise an error if not found

 at: key ifAbsent: exceptionBlock

return the value stored under akey.
Return the value from evaluating exceptionBlock if not found

** This method raises an error - it must be redefined in concrete classes **

 at: aKey ifAbsent: default update: aBlock

update the element stored under aKey with the result from
evaluating aBlock with the previous stored value as argument, or with default,
if there was no such key initially.
Return the new value stored.

 at: aKey ifAbsentPut: valueBlock

return the element indexed by aKey if present,
if not present, store the result of evaluating valueBlock
under aKey and return it.
WARNING: do not add elements while iterating over the receiver.
Iterate over a copy to do this.

 at: aKey ifPresent: aBlock

try to retrieve the value stored at aKey.
If there is nothing stored under this key, do nothing.
Otherwise, evaluate aBlock, passing the retrieved value as argument.

 at: aKey put: anObject

add the argument anObject under key, aKey to the receiver.
Return anObject (sigh).
WARNING: do not add elements while iterating over the receiver.
Iterate over a copy to do this.

** This method raises an error - it must be redefined in concrete classes **

 at: aKey put: anObject ifPresent: aBlock

if the receiver contains an element stored under aKey,
retrieve it and evaluate aBlock passing the element as argument,
return the blocks value.
If not, store aValue under the key.
Use this with an error-reporting block, to ensure that no keys are reused

 at: aKey update: aBlock

update the element stored under aKey with the result from
evaluating aBlock with the previous stored value as argument.
Report an error if there was no such key initially.
Return the new value stored.

 keyAtEqualValue: value

return the key under which value is stored.
Raise an error if not found.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using equality compare

 keyAtEqualValue: value ifAbsent: exceptionBlock

return the key under which value is stored.
If not found, return the value from evaluating exceptionBlock.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using equality compare

 keyAtIdenticalValue: value

return the key under which value is stored.
Raise an error if not found.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using identity compare

 keyAtIdenticalValue: value ifAbsent: exceptionBlock

return the key under which value is stored.
If not found, return the value from evaluating exceptionBlock.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using identity compare

 keyAtValue: value

return the key under which value is stored.
Raise an error if not found.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using equality compare

 keyAtValue: value ifAbsent: exceptionBlock

return the key under which value is stored.
If not found, return the value from evaluating exceptionBlock.
This is a slow access, since the receiver is searched sequentially.
NOTICE:
The value is searched using equality compare

 keys

return a collection containing the keys of the receiver

 associationsDo: aBlock

perform the block for all associations in the collection.

See also:
#do: (which passes values to its block)
#keysDo: (which passes only keys to its block)
#keysAndValuesDo: (which passes keys&values)

This is much like #keysAndValuesDo:, but aBlock gets the
key and value as a single association argument.
#keysAndValuesDo: and is a bit faster therefore (no intermediate objects).

WARNING: do not add/remove elements while iterating over the receiver.
Iterate over a copy to do this.

 do: aBlock

evaluate aBlock for each value

 keysAndValuesDo: aBlock

evaluate aBlock for each key and value

** This method raises an error - it must be redefined in concrete classes **

 inspectorClass
( an extension from the stx:libtool package )

redefined to use DictionaryInspector
(instead of the default Inspector).

 removeAllKeys: aCollection

remove all keys of the argument, aCollection from the receiver.
Raises an error, if some element-to-remove is not in the receiver.

 removeKey: aKey

remove key (and the value stored under that key) from the
receiver; raise an error if no such element is contained

 removeKey: aKey ifAbsent: exceptionBlock

remove key (and the value stored under that key) from the
receiver; return the value which was stored previously there.
If no such element is contained, return the value
from evaluating exceptionBlock

** This method raises an error - it must be redefined in concrete classes **

 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.

Here we return the first key for which aBlock matches the value.
Note that there is no order in a Dictionary, so any element is first.

usage example(s):

(KeyValueList withKeys:#('a' 'b' 'c') andValues:#('bla' 'hello' 'hallo')) findFirst:[:v| v first = $h].

 findFirstKey: aBlock

find and return the first key, for which evaluation of the argument, aBlock
returns true; return nil if none is detected.

 includesIdenticalKey: aKey

return true, if the argument, aKey is a key in the receiver

 includesKey: aKey

return true, if the argument, aKey is a key in the receiver