<Default Package>
Type dictionary
<
KEY,VALUE
>
- Type Parameters:
- KEY - Key type
- VALUE - Value type
An associative key-value map for EPL types.
A dictionary is a means of storing and retrieving data based on an entry key. This enables, for example, a user's name to be retrieved from a unique user ID.
The syntax of a dictionary definition is: dictionary<KEY,VALUE> varname
Dictionaries are dynamic, and new entries can be added and existing entries deleted as desired.
The dictionary key type must be a comparable type. The value type can be any Apama type.
Two dictionaries are equal only if they contain the same keys and the same value for each key. When dictionaries are not equal they are ordered as though they were sequences of key-value pairs, sorted in key order.
Example: // A simple stock dictionary, each stock's name is gained and
// stored from a numerical key
dictionary<integer,string> stockdict;
// A dictionary that can be used to store the number of times
// that a given event is received
dictionary<StockChoice,integer> stockCounterDict;
Note that a dictionary of sequences or dictionaries is supported. For example: dictionary<integer,sequence<float>> dictOfSeq;
A global variable of type dictionary is initialized by default to an empty instance of the type defined. On the other hand, a local variable must be explicitly initialized using the new operator, as follows: dictionary<integer,string> stockdict;
stockdict := new dictionary<integer,string>;
It is also possible to both declare and populate a variable of type dictionary as a single statement, regardless of the scope in which the variable is declared, as follows: dictionary<integer,string> stockdict := {1:"IBM", 2:"MSFT", 3:"ORCL"}; using {} to delimit the dictionary, a comma (,) to delimit individual entries, and a colon (:) to separate keys and values.
Dictionary types do not allow duplicate keys. Ensure that you do not specify duplicate keys when initializing a dictionary or in a string that will be parsed to produce a dictionary. An IllegalArgumentException is thrown at runtime if a dictionary is initialized with duplicate keys and a ParseException is thrown when parsing from a string which contains duplicate keys.
A dictionary variable can be a potentially cyclic type — a type that directly or indirectly refers to itself.
The default value of a dictionary is an empty dictionary.
Dictionaries are parseable, routable and comparable as long as their key and value types are.
Dictionary entries can be accessed using the [key] operator. If you assign to this value and the key does not exist, then the key will be inserted. If you read from this value and the key does not exist, then an exception will be thrown. For example: dictionary<string,integer> dict := new dictionary<string,integer>;
dict["A"] := 1; // insert an entry
integer a := dict["A"]; // retrieve an entry
integer b := dict["B"]; // throws an exception because "B" does not exist
To iterate over a dictionary use a "for" loop: string key;
for key in dict.keys() {
log "Got dictionary value: "+dict[key] at INFO;
}
| Action summary |
|---|
void | add(KEY key, VALUE item)
Add an entry to the dictionary. |
boolean | static canParse(string s)
Check if the string argument can be successfully parsed as a dictionary. |
void | clear()
Set the size of the dictionary to 0, deleting all entries. |
dictionary<KEY, VALUE> | clone()
Create a deep copy of this dictionary. |
VALUE | getOr(KEY key, VALUE default)
Return the item for the specified key if it exists, or the default if it does not. |
VALUE | getOrAdd(KEY key, VALUE default)
Return the item for the specified key if it exists, or add and return a specified default if it does not. |
VALUE | getOrAddDefault(KEY key)
Return the item for the specified key if it exists, or add and return a default-initialized VALUE if not. |
VALUE | getOrDefault(KEY key)
Return the item for the specified key if it exists, or a default-initialized VALUE if it does not. |
integer | hash()
Get an integer hash representation of the underlying object. |
boolean | hasKey(KEY key)
Check whether a key exists in this dictionary. |
sequence<KEY> | keys()
Return all the keys in the dictionary. |
dictionary<KEY, VALUE> | static parse(string s)
Parse a string into a dictionary. |
void | remove(KEY key)
Remove the entry with this key. |
integer | size()
Return the size of the dictionary. |
string | toString()
Convert the dictionary to a string. |
sequence<VALUE> | values()
Return all the values in the dictionary. |
add
void add(KEY key, VALUE item)
Add an entry to the dictionary.
Add the item as the value for the corresponding key. If the key already exists, then this method will replace the original value.- Parameters:
- key - The key to set.
- item - The value to set it to.
canParse
boolean static canParse(string s)
Check if the string argument can be successfully parsed as a dictionary.
This method only exists when both the KEY and VALUE types can be parsed.- Parameters:
- s - The string to test for parseability.
- Returns:
- True if the string could be parsed as this dictionary type, false otherwise.
- See Also:
- dictionary#parse() - See the parse method for how dictionaries are parsed.
clear
void clear()
Set the size of the dictionary to 0, deleting all entries.
clone
dictionary<KEY, VALUE> clone()
Create a deep copy of this dictionary.
When the dictionary contains a potentially cyclic type, then all aliases to the same object are preserved as well as cycles. If the dictionary cannot be cyclic (but could still contain aliased elements), all the references will be flattened to multiple copies.- Returns:
- A deep copy of this dictionary.
getOr
VALUE getOr(KEY key, VALUE default)
Return the item for the specified key if it exists, or the default if it does not.
Unlike using the [] operator, this method does not throw if the key does not exist.- Parameters:
- key - The key to look up.
- default - The value to return if the key does not exist.
- Returns:
- The value for key or default.
- See Also:
- dictionary#getOrDefault() - Use getOrDefault() to return a default-initialized VALUE instead of specifying the default.
- dictionary#getOrAdd() - Use getOrAdd() to also add the specified key and default value to the dictionary if it does not already exist.
- dictionary#getOrAddDefault() - Use getOrAddDefault() to also add the specified key and a default-initialized VALUE to the dictionary if it does not already exist.
getOrAdd
VALUE getOrAdd(KEY key, VALUE default)
Return the item for the specified key if it exists, or add and return a specified default if it does not.
Unlike using the [] operator, this method does not throw if the key does not exist.
This will modify the dictionary and add the item key = value if the key is not already in the dictionary.- Parameters:
- key - The key to look up.
- default - The value to add to the dictionary if the key does not exist.
- Returns:
- The existing value for key or the newly added value.
- See Also:
- dictionary#getOr() - Use getOr() to return default without adding it to the dictionary.
- dictionary#getOrDefault() - Use getOrDefault() to return a default-initialized VALUE instead of adding anything to the dictionary.
- dictionary#getOrAddDefault() - Use getOrAddDefault() to also add the specified key and a default-initialized VALUE to the dictionary if it does not already exist.
getOrAddDefault
VALUE getOrAddDefault(KEY key)
Return the item for the specified key if it exists, or add and return a default-initialized VALUE if not.
Unlike using the [] operator, this method does not throw if the key does not exist.
This will modify the dictionary and add a default-initialized VALUE for key.- Parameters:
- key - The key to look up.
- Returns:
- The existing value for key or the newly added value.
- See Also:
- dictionary#getOr() - Use getOr() to return default without adding it to the dictionary.
- dictionary#getOrDefault() - Use getOrDefault() to return a default-initialized VALUE instead of adding anything to the dictionary.
- dictionary#getOrAdd() - Use getOrAdd() to add a specified value instead of a default-initialized VALUE.
getOrDefault
VALUE getOrDefault(KEY key)
Return the item for the specified key if it exists, or a default-initialized VALUE if it does not.
Unlike using the [] operator, this method does not throw if the key does not exist.- Parameters:
- key - The key to look up.
- Returns:
- The value for key or a default-initialized VALUE.
- See Also:
- dictionary#getOr() - Use getOr() to return a specified default rather than a default-initialized VALUE.
- dictionary#getOrAdd() - Use getOrAdd() to also add the specified key and default value to the dictionary if it does not already exist.
- dictionary#getOrAddDefault() - Use getOrAddDefault() to also add the specified key and a default-initialized VALUE to the dictionary if it does not already exist.
hash
integer hash()
Get an integer hash representation of the underlying object.
This function will return an integer evenly distributed over the whole range suitable for partitioning or indexing of that structure. Multiple different object can resolve to the same hash value.
KEY must be hashable, but if VALUE is not hashable the type will not have a hash method implemented.- Returns:
- An integer respresentation of the underlying object.
hasKey
boolean hasKey(KEY key)
Check whether a key exists in this dictionary.- Parameters:
- key
- Returns:
- True if this dictionary contains the specified key, false otherwise.
keys
sequence<KEY> keys()
Return all the keys in the dictionary.
The sequence values are deep copies of the keys from the dictionary and are returned sorted in ascending order. The dictionary can be modified after calling keys() without invalidating the sequence, but changes to the dictionary keys will not be reflected until you call keys() and vice-versa.- Returns:
- An ordered sequence of all the keys in this dictionary.
parse
dictionary<KEY, VALUE> static parse(string s)
Parse a string into a dictionary.
This method only exists on dictionary types where both KEY and VALUE are parseable types.
The string form of a dictionary is:
"{" ENTRY ["," ENTRY]* "}"
Where ENTRY is:
KEY ":" VALUE
KEY and VALUE are the string forms of their respective types.- Parameters:
- s - The string to parse.
- Returns:
- The dictionary parsed from s.
- Throws:
- Throws ParseException if the string cannot be parsed as a dictionary.
- See Also:
- dictionary#canParse() - Call canParse to test whether the string can be parsed without throwing an exception.
remove
void remove(KEY key)
Remove the entry with this key.- Parameters:
- key - The key to remove.
- Throws:
- Throws IllegalArgumentException if the specified key does not exist in the dictionary.
size
integer size()
Return the size of the dictionary.- Returns:
- The number of entries in the dictionary.
toString
string toString()
Convert the dictionary to a string.
The keys in the dictionary will be sorted before conversion to a string.
If the dictionary is cyclic, then object references will appear in the string.- Returns:
- The string representation of this dictionary.
- See Also:
- dictionary#parse() - See the parse() method for the string form of a dictionary.
- event#toString() - See the toString() method of the event type for how cyclic types are converted to strings.
values
sequence<VALUE> values()
Return all the values in the dictionary.
The sequence values are references to the values from the dictionary and are returned sorted in ascending order of their keys (this is the same order that keys() returns). Adding or removing entries in the dictionary after calling values() will not invalidate the sequence, but changes to the dictionary keys will not be reflected until you call values() and vice-versa.- Returns:
- A sequence of all the values sorted by key.
- See Also:
- dictionary#keys() - The sort order is the same as for keys().