---
title: "Dictionaries"
url: https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Dictionaries

Parts of this page are for some programming languages only, and name them. For one language's text alone, see [C++](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/php.md), [Python](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/ruby.md), and [Swift](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/swift.md).

## Dictionary Syntax and Semantics

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.

## 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](https://docs.zeroc.com/ice/3.8/slice/basic-types.md) types (`short`, `int`, `long`)
- [bool](https://docs.zeroc.com/ice/3.8/slice/basic-types.md)
- [byte](https://docs.zeroc.com/ice/3.8/slice/basic-types.md)
- [string](https://docs.zeroc.com/ice/3.8/slice/basic-types.md)
- [enum](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations.md)
- [Structures](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/structures.md) containing only fields of legal key types

## Language Mapping

> **C++**
>
> ### Default Dictionary Mapping
>
> Here is the definition of our EmployeeMap once more:
>
> ```slice
> dictionary<long, Employee> EmployeeMap;
> ```
>
> The following code is generated for this definition:
>
> ```cpp
> using EmployeeMap = std::map<std::int64_t, Employee>;
> ```
>
> A Slice dictionary maps to a `std::map`. For example:
>
> ```cpp
> 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`
>
> 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:
>
> ```cpp
> #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](https://docs.zeroc.com/ice/3.8/slice/operations/cpp.md). 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`).

> **C#**
>
> ### Default Mapping
>
> 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:
>
> ```csharp
> // Standard Dictionary from System.Collections.Generic
> Dictionary<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:
>
> ```slice
> ["cs:generic:SortedDictionary"]
> dictionary<long, Employee> EmployeeMap;
> ```
>
> With this definition, the type of the dictionary becomes:
>
> ```csharp
> // From namespace System.Collections.Generic
> SortedDictionary<long, Employee>
> ```

> **Java**
>
> ### Default Mapping
>
> 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);
> ```
>
> ### 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:
>
> ```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](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/sequences/java.md) for the full syntax of `java:type`.

> **JavaScript**
>
> A Slice dictionary maps to:
>
> - A JavaScript [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) when the key is a Slice basic type or an enumeration.
> - An [`Ice.HashMap`](https://code.zeroc.com/ice/3.8/api/javascript/Ice/HashMap.html) 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.
>
> ### Example: Dictionary with a Basic Key Type
>
> ```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).
>
> ### Example: Dictionary with Struct Key
>
> If the key is a Slice struct, the compiler generates code that uses [Ice.HashMap](https://code.zeroc.com/ice/3.8/api/javascript/Ice/HashMap.html).
>
> ```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`:
>
> ```js
> const departments = new EmployeeDeptMap();
> departments.set(new Employee(42n, "Stan", "Lippman"), "Engineering");
> departments.get(new Employee(42n, "Stan", "Lippman")); // "Engineering"
> ```

> **MATLAB**
>
> 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:
>
> ```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;
> ```

> **PHP**
>
> 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.
>
> > **Note**
> >
> > Boolean values are treated as integers, with false equivalent to 0 (zero) and true equivalent to 1 (one).
>
> 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];
> ```

> **Python**
>
> 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:
>
> ```py
> em = {}
>
> e = Employee()
> e.number = 31
> e.firstName = "James"
> e.lastName = "Gosling"
>
> em[e.number] = e
> ```

> **Ruby**
>
> 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
> ```

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