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

A dictionary is an associative array: a collection of key-value pairs in which each key is unique.

For example:

Slice
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.

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:

Here is the definition of our EmployeeMap once more:

Slice
dictionary<long, Employee> EmployeeMap;

The following code is generated for this definition:

C++
using EmployeeMap = std::map<std::int64_t, Employee>;

A Slice dictionary maps to a std::map. For example:

C++
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;

You can override the default mapping of Slice dictionaries to C++ with a cpp:type metadata directive, for example:

Slice
[["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:

C++
#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:

Slice
[["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_type and value_type.
  • The class must provide iterator and const_iterator types and provide begin and end member functions with the usual semantics; these iterators must be comparable for equality and inequality.
  • The class must provide a clear function.
  • The class must provide a size function that returns the number of entries.
  • The class must provide an insert function that takes an iterator (as location hint) plus a value_type parameter, and returns an iterator to 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:

Slice
[["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).

Here is the definition of our EmployeeMap once more:

Slice
dictionary<long, Employee> EmployeeMap;

By default, the Slice-to-C# compiler maps the dictionary to the following type:

C#
// Standard Dictionary from System.Collections.Generic
Dictionary<long, Employee>

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:

Slice
["cs:generic:SortedDictionary"]
dictionary<long, Employee> EmployeeMap;

With this definition, the type of the dictionary becomes:

C#
// From namespace System.Collections.Generic
SortedDictionary<long, Employee>

Here is the definition of our EmployeeMap once more:

Slice
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:

Java
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);

If the semantics of a HashMap are not suitable for your application, you can specify another instance type with the java:type metadata directive:

Slice
["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 Map when the key is a Slice basic type or an enumeration.
  • An Ice.HashMap when the key is a Slice structure.

This distinction is necessary because:

  • A JavaScript Map uses the === operator for key equality.
  • Ice.HashMap accepts a key comparator, so struct keys can use their equals method for equality.
Slice
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 Slice long)
  • value type = Employee (the JavaScript class generated from the Slice struct).

If the key is a Slice struct, the compiler generates code that uses Ice.HashMap.

Slice
dictionary<Employee, string> EmployeeDeptMap;

The generated TypeScript declaration is:

TypeScript
class EmployeeDeptMap extends Ice.HashMap<Employee, string> {}

You create and use an EmployeeDeptMap like a Map:

JavaScript
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 TypeMATLAB 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:

Slice
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).

MATLAB
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:

Slice
dictionary<long, Employee> EmployeeMap;

You can create an instance of this dictionary as shown below:

PHP
$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:

Slice
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:

Python
em = {}
e = Employee()
e.number = 31
e.firstName = "James"
e.lastName = "Gosling"
em[e.number] = e

Here is the definition of our EmployeeMap once more:

Slice
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:

Ruby
em = {}
e = Employee.new
e.number = 31
e.firstName = "James"
e.lastName = "Gosling"
em[e.number] = e

Here is the definition of our EmployeeMap once more:

Slice
dictionary<long, Employee> EmployeeMap;

The following code is generated for this definition:

Swift
public typealias EmployeeMap = [Int64: Employee]

A Slice dictionary maps to a Swift dictionary. For example:

Swift
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]