Dictionaries
4 min read
2 min read
3 min read
3 min read
2 min read
2 min read
2 min read
2 min read
2 min read
Dictionary Syntax and Semantics
A dictionary is an associative array: a collection of key-value pairs in which each key is unique.
For example:
module M{ struct Employee { long number; string firstName; string lastName; }
dictionary<long, Employee> EmployeeMap;}This definition creates a dictionary named EmployeeMap that maps from an employee number to a structure containing the details for an employee.
Allowable Types for Dictionary Keys and Values
The value type of a dictionary can be any Slice type. However, the key type of a dictionary is limited to one of the following types:
- Integral types (
short,int,long) - bool
- byte
- string
- enum
- Structures containing only fields of legal key types
Language Mapping
Default Dictionary Mapping
Here is the definition of our EmployeeMap once more:
dictionary<long, Employee> EmployeeMap;The following code is generated for this definition:
using EmployeeMap = std::map<std::int64_t, Employee>;A Slice dictionary maps to a std::map. For example:
EmployeeMap em;Employee e;
e.number = 42;e.firstName = "Stan";e.lastName = "Lippman";em[e.number] = e;
e.number = 77;e.firstName = "Herb";e.lastName = "Sutter";em[e.number] = e;Customizing the Dictionary Mapping with cpp:type
cpp:typeYou can override the default mapping of Slice dictionaries to C++ with a cpp:type metadata directive, for example:
[["cpp:include:unordered_map"]]
["cpp:type:std::unordered_map<std::int64_t, Employee>"]dictionary<long, Employee> EmployeeMap;The cpp:type directive maps EmployeeMap to a std::unordered_map, and the cpp:include file directive adds the matching include directive to the generated header:
#include <unordered_map>
using EmployeeMap = std::unordered_map<std::int64_t, Employee>;Instead of std::unordered_map, you can specify a type of your own as the dictionary type, for example:
[["cpp:include:CustomMap.h"]]
["cpp:type:MyCustomMap<std::int64_t, Employee>"]dictionary<long, Employee> EmployeeMap;With these metadata directives, the compiler will use a C++ type MyCustomMap as the dictionary type, and add an include directive for the header file CustomMap.h to the generated code.
The class or template class you provide must meet the following requirements:
- The class must have a default constructor.
- The class must have a copy constructor.
- The class must provide nested types named
key_type,mapped_typeandvalue_type. - The class must provide
iteratorandconst_iteratortypes and providebeginandendmember functions with the usual semantics; these iterators must be comparable for equality and inequality. - The class must provide a
clearfunction. - The class must provide a
sizefunction that returns the number of entries. - The class must provide an
insertfunction that takes aniterator(as location hint) plus avalue_typeparameter, and returns aniteratorto the new entry or to the existing entry with the given key.
In addition to modifying the type of a dictionary itself, you can also modify the mapping for particular return values or parameters. For example:
[["cpp:include:unordered_map"]]
interface Office{ ["cpp:type:std::unordered_map<std::int64_t, Employee>"] EmployeeMap getAllEmployees();}With this definition, getAllEmployees returns an unordered_map, while other parameters and return values of type EmployeeMap use the default mapping (to a std::map).
Default Mapping
Here is the definition of our EmployeeMap once more:
dictionary<long, Employee> EmployeeMap;By default, the Slice-to-C# compiler maps the dictionary to the following type:
// Standard Dictionary from System.Collections.GenericDictionary<long, Employee>Custom Mapping for Dictionaries
You can use the "cs:generic:SortedDictionary" or "cs:generic:SortedList" metadata directives to change the default mapping to use a sorted dictionary or sorted list instead. For example:
["cs:generic:SortedDictionary"]dictionary<long, Employee> EmployeeMap;With this definition, the type of the dictionary becomes:
// From namespace System.Collections.GenericSortedDictionary<long, Employee>Default Mapping
Here is the definition of our EmployeeMap once more:
dictionary<long, Employee> EmployeeMap;As for sequences, the Java mapping does not create a separate named type for this definition. A Slice dictionary maps to the interface java.util.Map<K, V>, where K is the mapping of the key type and V is the mapping of the value type: EmployeeMap maps to java.util.Map<Long, Employee>. When Ice unmarshals a dictionary, it creates a java.util.HashMap. The following code demonstrates how to allocate and use an instance of EmployeeMap:
var em = new java.util.HashMap<Long, Employee>();
Employee e = new Employee();e.number = 31;e.firstName = "James";e.lastName = "Gosling";
em.put(e.number, e);Custom Mapping for Dictionaries
If the semantics of a HashMap are not suitable for your application, you can specify another instance type with the java:type metadata directive:
["java:type:java.util.TreeMap<String, String>"]dictionary<string, string> StringMap;Ice then creates a java.util.TreeMap<String, String> when it unmarshals a StringMap, and the generated code keeps using java.util.Map<String, String>, the default formal type, everywhere else. A formal type you specify must implement java.util.Map<K, V>.
The instance type must have an accessible parameterless constructor and must be modifiable: when unmarshaling a dictionary, the generated code creates the instance with this constructor and fills it with put.
The type parameters (String above) are the Java mappings of the key and value types. See Sequences for the full syntax of java:type.
A Slice dictionary maps to:
- A JavaScript
Mapwhen the key is a Slice basic type or an enumeration. - An
Ice.HashMapwhen the key is a Slice structure.
This distinction is necessary because:
- A JavaScript
Mapuses the===operator for key equality. Ice.HashMapaccepts a key comparator, so struct keys can use theirequalsmethod for equality.
Example: Dictionary with a Basic Key Type
struct Employee{ long number; string firstName; string lastName;}
dictionary<long, Employee> EmployeeMap;In this example, EmployeeMap maps to a JavaScript Map with:
- key type =
BigInt(from Slicelong) - value type =
Employee(the JavaScript class generated from the Slice struct).
Example: Dictionary with Struct Key
If the key is a Slice struct, the compiler generates code that uses Ice.HashMap.
dictionary<Employee, string> EmployeeDeptMap;The generated TypeScript declaration is:
class EmployeeDeptMap extends Ice.HashMap<Employee, string> {}You create and use an EmployeeDeptMap like a Map:
const departments = new EmployeeDeptMap();departments.set(new Employee(42n, "Stan", "Lippman"), "Engineering");departments.get(new Employee(42n, "Stan", "Lippman")); // "Engineering"A Slice dictionary maps to a MATLAB dictionary.
The key type of the MATLAB dictionary is the mapped type for the Slice dictionary key. For example, a Slice string key maps to a MATLAB char key, which MATLAB interprets as a string type.
The value type of the MATLAB dictionary depends on the Slice value type:
| Slice Value Type | MATLAB Value Type |
|---|---|
bool, numeric type, enum, struct | Corresponding MATLAB type |
string | MATLAB string |
class, proxy, sequence, dictionary | Cell of the corresponding MATLAB type |
Consider the definition of our EmployeeMap once more:
struct Employee{ ["matlab:identifier:Number"] long number;
["matlab:identifier:FirstName"] string firstName;
["matlab:identifier:LastName"] string lastName;}
dictionary<long, Employee> EmployeeMap;EmployeeMap maps to a dictionary with key type = int64 and value type = Employee (a MATLAB class mapped from a Slice struct).
em = configureDictionary('int64', 'M.Employee');
e = M.Employee();e.Number = 31;e.FirstName = 'James';e.LastName = 'Gosling';
em(e.Number) = e;A Slice dictionary maps to a native PHP associative array: a dictionary whose key type is an enumeration or one of bool, byte, short, int, or long maps to an array with integer keys, and a dictionary with a string key type maps to an array with string keys.
Ice for PHP does not support dictionaries whose key type is a structure.
Here is the definition of our EmployeeMap:
dictionary<long, Employee> EmployeeMap;You can create an instance of this dictionary as shown below:
$e1 = new Employee;$e1->number = 42;$e1->firstName = "Stan";$e1->lastName = "Lippman";
$e2 = new Employee;$e2->number = 77;$e2->firstName = "Herb";$e2->lastName = "Sutter";
$em = [$e1->number => $e1, $e2->number => $e2];Here is the definition of our EmployeeMap once more:
dictionary<long, Employee> EmployeeMap;As for sequences, the Python mapping does not create a separate named type for this definition. A Slice dictionary maps to a Python dict: in the generated type hints, EmployeeMap is dict[int, Employee] where Ice creates the dictionary (a proxy return value, a servant parameter) and Mapping[int, Employee] where your code supplies it (a proxy parameter, a servant return value). For example:
em = {}
e = Employee()e.number = 31e.firstName = "James"e.lastName = "Gosling"
em[e.number] = eHere is the definition of our EmployeeMap once more:
dictionary<long, Employee> EmployeeMap;As for sequences, the Ruby mapping does not create a separate named type for this definition. Instead, all dictionaries are simply instances of Ruby's hash collection type. For example:
em = {}
e = Employee.newe.number = 31e.firstName = "James"e.lastName = "Gosling"
em[e.number] = eHere is the definition of our EmployeeMap once more:
dictionary<long, Employee> EmployeeMap;The following code is generated for this definition:
public typealias EmployeeMap = [Int64: Employee]A Slice dictionary maps to a Swift dictionary. For example:
let stan = Employee(number: 42, firstName: "Stan", lastName: "Lippman")let herb = Employee(number: 77, firstName: "Herb", lastName: "Sutter")
let em: EmployeeMap = [stan.number: stan, herb.number: herb]