dictionary

Methods

⌂ dictionary

Method Reference: dictionary.dictionary

dictionary: d = dictionary ()

dictionary: d = dictionary (keys, values)

dictionary: d = dictionary (k1, v1, …, kN, vN)

Create a dictionary object.

d = dictionary () returns an unconfigured dictionary, with no entries and no key and value types.

d = dictionary (keys, values) returns a dictionary mapping each element of the array keys to the element of values in the same position, in that order. The two must be of the same size, or values a single value given to every key; an empty keys gives a configured dictionary with no entries. A key repeated keeps its first position and takes its last value. The class of keys is the key type and that of values the value type, except that a character array is a string array of its rows.

The key type must be one that keyHash can hash: a built-in type or a class with a keyHash method; a cell array is a key type of its own, each cell one key. An array of objects holds one key or value per object, but a table or timetable of any size is one value, where MATLAB accepts only a 1-by-1 one.

d = dictionary (k1, v1, …, kN, vN) adds each pair of keys and values in turn, the first pair setting the key and value types and later pairs converted to them. Keys and values of another class are converted by the function of the type’s name, as in MATLAB: string (x), double (x), categorical (x) and so on, and refused where that fails or gives another class. So 5 becomes "5" as a string, "3.5" becomes 3.5 as a double but is refused by single and the integer types, a character array gives its character codes as a number, a categorical its code, and missing gives NaN, NaT or an undefined category. The exceptions:

  • a 'cell' type takes only cell arrays, which are never wrapped, as in MATLAB;
  • a 'struct' type takes only structures, where MATLAB turns an object into a structure of its private properties;
  • a 'table' type makes a table of the variable Var1 and refuses character arrays, as in MATLAB;
  • a 'logical' type takes a character as true for a nonzero code, as in MATLAB;
  • a 'datetime' type reads dates given as text in the time zone of the dictionary, and moves a key with a time zone to that of the keys; a value keeps its own.

A date with a time zone and one without are different keys, so that looking up one as the other finds nothing, and keys cannot join a dictionary holding both. Dates given as text to a dictionary whose keys have a time zone are read in that zone, so that they find its keys; MATLAB reads them without one, a key that no date with a zone matches.

See also: configureDictionary, dictionary.isConfigured, dictionary.keys, keyHash, keyMatch

Source Code: dictionary

A dictionary maps unique keys to values, of one key type and one value type. In Octave both 'a' and "a" are character vectors, which a dictionary stores as strings, one per row. A cell array is a key type of its own, each cell one key, so text keys are given as a string array.

 fruit = dictionary (string ({'apple', 'pear', 'fig'}), [3, 5, 2])
fruit =

  dictionary (string ⟼ double) with 3 entries:

    "apple" ⟼ 3
    "pear"  ⟼ 5
    "fig"   ⟼ 2
 types (fruit)
ans =
  string

   "string"
 types (dictionary ('apple', 3))
ans =
  string

   "string"
 types (dictionary ({'apple', 'pear'}, [3, 5]))
ans =
  string

   "cell"

A dictionary is a scalar object, whatever it holds: numel and size describe the object, and numEntries counts the entries.

 fruit = dictionary (string ({'apple', 'pear', 'fig'}), [3, 5, 2]);
 numel (fruit)
ans = 1
 numEntries (fruit)
ans = 3

Entries keep the order their keys were first added. Replacing a value keeps the key in place, and a key repeated in the constructor keeps its first position and takes its last value.

 d = dictionary (string ({'b', 'a', 'b'}), [1, 2, 3])
d =

  dictionary (string ⟼ double) with 2 entries:

    "b" ⟼ 3
    "a" ⟼ 2
 d('b') = 10
d =

  dictionary (string ⟼ double) with 2 entries:

    "b" ⟼ 10
    "a" ⟼ 2

Index with keys to read values, assign to add or replace entries, and assign [] to remove them. Keys are converted to the key type, so a dictionary of double keys accepts integers and logical values.

 sq = dictionary ([1, 2, 3], [1, 4, 9])
sq =

  dictionary (double ⟼ double) with 3 entries:

    1 ⟼ 1
    2 ⟼ 4
    3 ⟼ 9
 sq([3, 1])
ans =

   9   1
 sq(int8 (4)) = 16;
 sq(2) = []
sq =

  dictionary (double ⟼ double) with 3 entries:

    1 ⟼ 1
    3 ⟼ 9
    4 ⟼ 16

Several pairs of keys and values can be given at once: the first pair sets the types, and later pairs are converted to them. Here the dates of a dictionary of datetime keys are also given as text.

 marks = dictionary (datetime (2024, 3, 1), 'start', '2024-03-15', 'middle')
marks =

  dictionary (datetime ⟼ string) with 2 entries:

    01-Mar-2024 ⟼ "start"
    15-Mar-2024 ⟼ "middle"

Values of the class cell hold anything, one cell per key, and {} reaches their contents.

 cfg = dictionary (string ({'size', 'name', 'when'}), ...
                   {[640, 480], 'demo', duration(1, 30, 0)})
cfg =

  dictionary (string ⟼ cell) with 3 entries:

    "size" ⟼ {[640 480]}
    "name" ⟼ {'demo'}
    "when" ⟼ {[01:30:00]}
 cfg{'size'}
ans =

   640   480
 cfg{'name'} = 'renamed';
 cfg('name')
ans =
  1x1 cell array

    {'renamed'}

A value can be any object, a table of any size or another dictionary included, and indexing continues into it.

 shelf = dictionary (string ({'north', 'south'}), ...
                     {table([1; 2], {'pen'; 'ink'}, 'VariableNames', ...
                            {'Qty', 'Item'}), ...
                      table(5, {'tape'}, 'VariableNames', {'Qty', 'Item'})});
 shelf{'north'}
ans =
  2x2 table

    Qty     Item      
    ___    _______    

      1    {'pen'}    
      2    {'ink'}
 nested = dictionary ('inner', dictionary (string ({'x', 'y'}), [1, 2]))
nested =

  dictionary (string ⟼ dictionary) with 1 entry:

    "inner" ⟼ dictionary (string ⟼ double) with 2 entries
 nested('inner')('y')
ans = 2