RunMat
GitHub

View all functions

CategoryContainers: Map

What does the containers.Map function do in MATLAB / RunMat?

containers.Map builds dictionary objects that associate unique keys with values. Keys can be character vectors, string scalars, or numeric scalars (double/int32/uint32/int64/uint64/logical). Values default to MATLAB's 'any' semantics, letting you store arbitrary scalars, arrays, structs, or handle objects. Each map tracks insertion order, supports key-based indexing, and exposes methods such as keys, values, isKey, and remove.

How does the containers.Map function behave in MATLAB / RunMat?

  • Keys must be unique. Constructing a map or assigning a key that already exists overwrites the stored value (matching MATLAB's behaviour).
  • The KeyType, ValueType, and Count properties are readable with dot-indexing.
  • map(key) returns the associated value; requesting a missing key raises the MATLAB-compatible error "The specified key is not present in this container."
  • Assignments of the form map(key) = value update or insert entries.
  • Methods keys(map), values(map), isKey(map, keySpec), and remove(map, keySpec) are fully compatible. When keySpec is a cell or string array, the result matches MATLAB's shape.
  • GPU tensors presented as values are gathered to host memory before insertion. When values or keys arrive on the GPU and need to be expanded element-wise (for example, vector-valued constructor arguments), RunMat downloads them to materialise individual scalars.
  • The 'UniformValues' flag is accepted; when true, RunMat validates that every inserted value has the same MATLAB class. Retrieval still returns a cell array, matching MATLAB behaviour when the value type is 'any'.

containers.Map Function GPU Execution Behaviour

The data structure itself resides on the CPU. When you construct a map with GPU arrays, RunMat first downloads the inputs so it can perform MATLAB-compatible validation and coercion. Maps never retain device buffers internally, so the GPU provider does not need to implement special hooks for this builtin.

Examples of using the containers.Map function in MATLAB / RunMat

Create an empty map with default types

m = containers.Map();
m.KeyType
m.ValueType
m.Count

Expected output:

ans =
    'char'
ans =
    'any'
ans =
     0

Build a map from paired cell arrays

keys = {'apple', 'pear', 'banana'};
vals = {42, [1 2 3], true};
fruit = containers.Map(keys, vals);
energy = fruit('apple');

Expected output:

energy =
    42

Update an existing key and add a new one

fruit('apple') = 99;
fruit('peach') = struct('ripe', true);

Expected output:

fruit('apple')
ans =
    99

Query keys, values, and membership

allKeys = keys(fruit);
allVals = values(fruit);
mask = isKey(fruit, {'apple', 'durian'});

Expected output:

allKeys =
  1×4 cell array
    {'apple'}    {'pear'}    {'banana'}    {'peach'}

allVals =
  1×4 cell array
    {[99]}    {[1 2 3]}    {[1]}    {1×1 struct}

mask =
  1×2 logical array
     1     0

Remove keys and inspect the map length

remove(fruit, {'pear', 'banana'});
n = length(fruit);
remaining = keys(fruit);

Expected output:

n =
     2
remaining =
  1×2 cell array
    {'apple'}    {'peach'}

FAQ

Which key types are supported?

containers.Map accepts 'char', 'string', 'double', 'single', 'int32', 'uint32', 'int64', 'uint64', and 'logical'. Keys supplied during construction or assignment are coerced to the declared type and must be scalar.

What happens when I provide duplicate keys at construction time?

Duplicate keys raise the same error as MATLAB: "Duplicate key name was provided." During assignment, duplicate keys overwrite the existing value.

Does RunMat honour 'UniformValues', true?

Yes. When this option is set, RunMat enforces that each inserted value matches the MATLAB class of the first value. Retrieval still uses cell arrays, mirroring MATLAB when 'ValueType' is 'any'.

Can I store GPU arrays as map values?

Yes. RunMat automatically gathers GPU tensors to host memory before inserting them so it can apply the same validation and coercion rules as MATLAB. This ensures constructors that rely on vector expansion continue to produce predictable host-side values.

How does length(map) behave?

length(map) returns the number of stored keys (identical to the Count property). size(map) remains [1 1], matching MATLAB's handle semantics.

What error is raised when a key is missing?

Indexing a missing key produces the MATLAB-compatible error message "The specified key is not present in this container."

Does the map preserve insertion order?

Yes. keys(map) and values(map) return entries in the order they were first inserted, matching the behaviour of MATLAB's containers.Map.

Is the implementation thread-safe?

Yes. A global read/write lock guards the backing storage so concurrent reads are allowed while write operations remain exclusive.

How do I remove every entry?

Call remove(map, keys(map)) or reassign a new empty map. RunMat currently keeps the internal storage until the handle is cleared, matching MATLAB's lifetime semantics.

What happens if I pass a non-scalar key?

Keys must be scalar. Passing vectors, matrices, or nested cell arrays of keys raises a descriptive error pointing to the offending argument.

See Also

keys, values, isKey, remove, length