lookup

Find value in dictionary by key

Since R2023b

Syntax

value = lookup(d,key)

value = lookup(d,key,FallbackValue=fallback)

Description

value = lookup(d,key) returns the value corresponding to key in dictionary, d. If no entry corresponds to key then lookup throws an error.

value = lookup(d,key) is equivalent to value = d(key).

value = lookup(d,key,FallbackValue=fallback) specifies a fallback value to return if key is not found in d.

The lookup function does not validate fallback unless a fallback value is required. An error is not thrown unless key is not found, even if lookup is invalid.

Examples

Look Up Value in Dictionary

Create a dictionary containing several key-value pairs.

names = ["Unicycle" "Bicycle" "Tricycle"];
wheels = [1 2 3];
d = dictionary(wheels,names)

d =

  dictionary (double ⟼ string) with 3 entries:

    1 ⟼ "Unicycle"
    2 ⟼ "Bicycle"
    3 ⟼ "Tricycle"

Look up a value.

v = lookup(d,1)

v = 
"Unicycle"

Look Up Value in Dictionary with Fallback Value

Create a dictionary containing several key-value pairs.

names = ["Unicycle" "Bicycle" "Tricycle"];
wheels = [1 2 3];
d = dictionary(wheels,names)

d =

  dictionary (double ⟼ string) with 3 entries:

    1 ⟼ "Unicycle"
    2 ⟼ "Bicycle"
    3 ⟼ "Tricycle"

Look up a value with a fallback value if it is not found.

v = lookup(d,[3,5],FallbackValue="Wheeled Vehicle")

v = 1×2 string
    "Tricycle"    "Wheeled Vehicle"

Input Arguments

d — Dictionary

dictionary object

Dictionary, specified as a dictionary object. If d is unconfigured, lookup throws an error.

key — Key set

array

Key set, specified as an array. The data type of key must match or be convertible to the data type of keys in d.

fallback — Fallback value

scalar

Fallback value, specified as a scalar containing the value to return if key is not found. The data type of fallback must match or be convertible to the data type of values in d. fallback is not validated unless key is not found.

Example: FallbackValue="Wheeled Vehicle"

Tips

• A dictionary maps keys to values element-wise, allowing vectorized lookup and insert. Keys and values must each consist of elements of the same or compatible data type. To store nonscalar or heterogeneous values, use a cell array.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The fallback value must be the same type as the values in the dictionary.

• The code generator does not treat a dictionary as a constant, even if the dictionary is constant at code generation time. This means that the lookup function does not return a constant. You cannot pass the output of the lookup function to a function that requires constant inputs. You cannot use the output of the lookup function for operations that require constants, such as indexing into a heterogeneous cell array. The code generator also cannot perform optimizations that depend on constants, such as constant folding, on the output of the lookup function.

For additional considerations that apply when generating C/C++ code for MATLAB^® dictionaries, see Dictionary Limitations for Code Generation (MATLAB Coder).

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Version History

Introduced in R2023b

R2024b: Code generation support

You can generate C/C++ code for the dictionary lookup function.