dictionary

Methods

⌂ dictionary

Method Reference: dictionary.writedictionary

dictionary: writedictionary (d, filename)

dictionary: writedictionary (d, filename, Name, Value)

Write a dictionary to a JSON or an OpenDocument spreadsheet file.

writedictionary (d, filename) writes d as a JSON object to the file filename, a character vector or a string scalar, replacing any file of that name. Each entry is a member, in the order of the keys, written as follows:

  • keys as text: numbers in their shortest form ("1.5"), logical values as "true" and "false", dates and durations as they display;
  • a double or single in the fewest digits that read back as its value, always with a point (1.0), with an exponent only from 10^21 up and below 10^-6; integers exactly;
  • NaN and Inf as NaN, Infinity and -Infinity, or as null under 'PreserveInfAndNaN' false; missing strings, NaT and missing as null; logical values as true and false;
  • dates and durations as text, as they display;
  • a dictionary as an object, nested ones too; the contents of a cell as the value they hold, a vector of them as an array, and an empty one as [].

writedictionary (d, filename, Name, Value) specifies options with the following Name-Value paired arguments, matched in any case.

NameValue
'FileType''auto' (the default) tells the type from the extension, .json, .ods or .fods; 'json' or 'ods' sets it.
'PrettyPrint'A logical scalar: true (the default) indents by four spaces, one member or element a line; false writes no spaces or line breaks.
'PreserveInfAndNaN'A logical scalar: true (the default) writes NaN and Inf, false writes null.

Nothing is written when any key or value cannot be. Values of types other than string, the numeric types, logical, datetime, duration, missing, dictionary and cell are refused, as in MATLAB, and so are matrices in cells and complex values, on which MATLAB fails; keys of types other than string, a cell array of text, the numeric types, logical, datetime and duration are refused, and so are missing string keys.

An OpenDocument spreadsheet, FileType 'ods', holds one sheet per entry, named by the key and holding its table or timetable, written by struct2ods, so that readdictionary reads it back as it was. The keys must be text and the values tables or timetables, in a cell or not. Writing ODS is an extension of this package; it takes no option but 'FileType'.

Remote locations, which MATLAB writes to, are not supported.

See also: readdictionary, struct2ods

Source Code: dictionary

writedictionary writes a dictionary as a JSON object, indented by four spaces. A double is always written with a point, and keys that are not text are written as text.

 f = [tempname() '.json'];
 d = dictionary (string ({'pi', 'one', 'big'}), [pi, 1, 1e20])
d =

  dictionary (string ⟼ double) with 3 entries:

    "pi"  ⟼ 3.1416
    "one" ⟼ 1
    "big" ⟼ 1.0000e+20
 writedictionary (d, f);
 disp (fileread (f))
{
    "pi": 3.141592653589793,
    "one": 1.0,
    "big": 100000000000000000000.0
}
 writedictionary (dictionary ([1.5, 2], [true, false]), f, ...
                  'PrettyPrint', false);
 disp (fileread (f))
{"1.5":true,"2":false}
 delete (f);

Nested dictionaries become objects and the contents of cells their values, a vector an array. NaN and Inf are written as such, or as null under 'PreserveInfAndNaN' false, as missing values are.

 f = [tempname() '.json'];
 inner = dictionary (string ({'mean', 'max'}), [NaN, Inf]);
 d = dictionary (string ({'stats', 'samples', 'note'}), ...
                 {inner, [3, 5, 8], string(missing)})
d =

  dictionary (string ⟼ cell) with 3 entries:

    "stats"   ⟼ {[dictionary (string ⟼ double) with 2 entries]}
    "samples" ⟼ {[3 5 8]}
    "note"    ⟼ {[<missing>]}
 writedictionary (d, f, 'PreserveInfAndNaN', false);
 disp (fileread (f))
{
    "stats": {
        "mean": null,
        "max": null
    },
    "samples": [
        3.0,
        5.0,
        8.0
    ],
    "note": null
}
 delete (f);

What JSON cannot hold is refused before anything is written: here a categorical value. Dates are written as text, and read back as dates.

 f = [tempname() '.json'];
 try
   writedictionary (dictionary ('size', categorical ({'large'})), f);
 catch err
   disp (err.message)
 end_try_catch
dictionary.writedictionary: unable to write values of type 'categorical' to JSON.
 days = dictionary (string ({'start', 'end'}), datetime (2024, 3, [1, 15]));
 writedictionary (days, f);
 disp (fileread (f))
{
    "start": "01-Mar-2024",
    "end": "15-Mar-2024"
}
 readdictionary (f)
ans =

  dictionary (string ⟼ datetime) with 2 entries:

    "start" ⟼ 01-Mar-2024
    "end"   ⟼ 15-Mar-2024
 delete (f);

A dictionary of tables or timetables can be written to an OpenDocument spreadsheet, one sheet per key, which readdictionary reads back.

 readings = dictionary (string ({'Lab A', 'Lab B'}), ...
                        {timetable(hours ([1; 2]), [20.5; 21.0]), ...
                         timetable(hours ([1; 2]), [19.8; 20.1])})
readings =

  dictionary (string ⟼ cell) with 2 entries:

    "Lab A" ⟼ {2x1 timetable}
    "Lab B" ⟼ {2x1 timetable}
 f = [tempname() '.ods'];
 writedictionary (readings, f);
 back = readdictionary (f);
 keys (back)
ans =
  2x1 string array

    "Lab A"    
    "Lab B"
 back('Lab B')
ans =
  2x1 timetable

    Time    Var1    
    ____    ____    

    1 hr    19.8    
    2 hr    20.1
 delete (f);