"

 COPYRIGHT (c) 1998 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:libbasic' }"

"{ NameSpace: Smalltalk }"

Collection subclass:#KeyedCollection

	instanceVariableNames:''

	classVariableNames:''

	poolDictionaries:''

	category:'Collections-Abstract'

!

!KeyedCollection class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1998 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

"

    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

    [author:]

        Claus Gittinger

"

! !

!KeyedCollection class methodsFor:'instance creation'!

withAssociations:aCollectionOfAssociations

    "return a new instance where associations are taken from the argument"

    |newDict sz "{ Class: SmallInteger }"|

    sz := aCollectionOfAssociations size.

    newDict := self new:sz.

    aCollectionOfAssociations do:[:assoc |

        newDict at:assoc key put:assoc value

    ].

    ^ newDict

    "

     KeyValueList withAssociations:{ #'one'->1 .

                                   #'two'->2 .

                                   #'three'->3 .

                                   #'four'->4 }

    "

    "Created: / 16-03-2017 / 12:15:38 / stefan"

!

withKeys:keyArray andValues:valueArray

    "return a new instance where keys and values are taken from

     the argumentArrays."

    |newColl sz "{ Class: SmallInteger }"|

    sz := keyArray size.

    newColl := self new:sz.

    1 to:sz do:[:index |

        newColl at:(keyArray at:index) put:(valueArray at:index).

    ].

    ^ newColl

    "Created: / 16-03-2017 / 11:06:51 / stefan"

    "Modified (format): / 16-03-2017 / 12:12:09 / stefan"

!

withKeysAndValues:anArray

    "return a new instance where keys and values are taken from alternating

     elements of anArray"

    |newDict sz "{ Class: SmallInteger }"|

    sz := anArray size.

    newDict := self new:(sz // 2).

    1 to:sz by:2 do:[:i |

        newDict at:(anArray at:i) put:(anArray at:i+1)

    ].

    ^ newDict

    "

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

    "

    "Created: / 16-03-2017 / 12:13:27 / stefan"

! !

!KeyedCollection class methodsFor:'queries'!

isAbstract

    "Return if this class is an abstract class.

     True is returned for KeyedCollection here; false for subclasses.

     Abstract subclasses must redefine this again."

    ^ self == KeyedCollection

! !

!KeyedCollection methodsFor:'accessing'!

    "return an association consisting of aKey and the element indexed 

     by aKey - 

     report an error, if no element is stored under aKey."

!

at:key

    "return the value stored under akey.

     Raise an error if not found"

    ^ self at:key ifAbsent:[self errorKeyNotFound:key].

    "Modified: / 19.6.1998 / 00:48:27 / cg"

!

at:key ifAbsent:exceptionBlock

    "return the value stored under akey.

     Return the value from evaluating exceptionBlock if not found"

    ^ self subclassResponsibility

    "Created: / 19.6.1998 / 00:48:23 / cg"

!

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"

    ^ self keyAtEqualValue:value ifAbsent:[self errorValueNotFound:value].

    "Created: / 07-02-2017 / 11:11:41 / cg"

!

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"

    self keysAndValuesDo:[:elKey :elValue |

        value = elValue ifTrue:[^ elKey]

    ].

    ^ exceptionBlock value

    "Created: / 07-02-2017 / 11:12:03 / cg"

!

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"

    ^ self keyAtIdenticalValue:value ifAbsent:[self errorValueNotFound:value].

    "Created: / 07-02-2017 / 11:12:23 / cg"

!

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"

    self keysAndValuesDo:[:elKey :elValue |

        value == elValue ifTrue:[^ elKey]

    ].

    ^ exceptionBlock value

    "Created: / 07-02-2017 / 11:12:46 / cg"

!

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:

    "Created: / 19-06-1998 / 00:49:16 / cg"

    "Modified (comment): / 07-02-2017 / 11:13:29 / cg"

!

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:

    "Created: / 19-06-1998 / 00:50:34 / cg"

    "Modified: / 07-02-2017 / 11:13:20 / cg"

!

keys

    "return a collection containing the keys of the receiver"

    |keyCollection|

    keyCollection := OrderedCollection new.

    self keysDo:[:aKey |

        keyCollection add:aKey

    ].

    ^ keyCollection

    "Modified: / 19.6.1998 / 00:48:27 / cg"

    "Created: / 19.6.1998 / 00:51:49 / cg"

! !

!KeyedCollection methodsFor:'enumerating'!

do:aBlock

    "evaluate aBlock for each value"

    self keysAndValuesDo:[:elKey :elValue | aBlock value:elValue]

    "Created: / 19.6.1998 / 00:56:24 / cg"

!

keysAndValuesDo:aBlock

    "evaluate aBlock for each key and value"

    ^ self subclassResponsibility

    "Created: / 19.6.1998 / 00:56:52 / cg"

! !

!KeyedCollection methodsFor:'removing'!

removeKey:aKey

    "remove key (and the value stored under that key) from the

     receiver; raise an error if no such element is contained"

    ^ self removeKey:aKey ifAbsent:[self errorKeyNotFound:aKey]

    "Created: / 19.6.1998 / 00:53:25 / cg"

    "Modified: / 19.6.1998 / 00:54:02 / cg"

!

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"

    ^ self subclassResponsibility

    "Created: / 19.6.1998 / 00:53:58 / cg"

! !

!KeyedCollection methodsFor:'testing'!

includesIdenticalKey:aKey

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

    self keysDo:[:elKey | aKey == elKey ifTrue:[^ true]].

    ^ false

    "Created: / 19.6.1998 / 00:55:05 / cg"

!

includesKey:aKey

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

    self keysDo:[:elKey | aKey = elKey ifTrue:[^ true]].

    ^ false

    "Created: / 19.6.1998 / 00:55:05 / cg"

! !

!KeyedCollection class methodsFor:'documentation'!

version

    ^ '$Header$'

!

version_CVS

    ^ '$Header$'

! !