readdictionary

Create dictionary from file

Since R2024b

Syntax

d = readdictionary(filename)

d = readdictionary(filename,Name=Value)

Description

d = readdictionary(filename) creates a dictionary by reading structured data from a file. The input file must contain valid JSON content.

d = readdictionary(filename,Name=Value) specifies options using one or more name-value arguments. For example, you can read the contents of the input file as JSON when the file extension in filename is not .json by calling d = readdictionary(filename,FileType="json").

Examples

Dictionary from JSON File Data

Create a MATLAB dictionary from the data in a JSON file.

Display the JSON file citytemps.json.

type citytemps.json

{
    "Boston": 55,
    "New York": 62,
    "Denver": 48,
    "Chicago": 50,
    "Dallas": 75
}

Create a MATLAB dictionary from the data in the JSON file citytemps.json. The resulting dictionary uses string keys and double values.

d = readdictionary("citytemps.json")

d =

  dictionary (string --> double) with 5 entries:

    "Boston"   --> 55
    "New York" --> 62
    "Denver"   --> 48
    "Chicago"  --> 50
    "Dallas"   --> 75

Dictionary from Heterogeneous JSON File Data

Create a MATLAB dictionary from the heterogeneous data in a JSON file.

Display the JSON file msginfo.json.

type msginfo.json

{
    "Message": "Hello JSON!",
    "ID": 12345,
    "In-Reply-To": null,
    "Received": true,
    "Status": [7]
}

Create a MATLAB dictionary from the data in the JSON file msginfo.json. Because the values in the file have different data types, the resulting MATLAB dictionary uses the cell type for the values.

d = readdictionary("msginfo.json")

d =

  dictionary (string --> cell) with 5 entries:

    "Message"     --> {["Hello JSON!"]}
    "ID"          --> {[12345]}
    "In-Reply-To" --> {[<missing>]}
    "Received"    --> {[1]}
    "Status"      --> {1x1 cell}

Input Arguments

filename — Name of file to read

string scalar | character vector

Name of the file to read, specified as a string scalar or character vector. The file must contain valid JSON content that represents dictionary keys and values. The readdictionary function interprets files with a .json extension as JSON files. Files with other file extensions require the FileType name-value argument.

Depending on the location of your file, filename can take one of these forms.

Location	Form
Current folder or folder on the MATLAB® path	Specify the name of the file in filename. Example: "myFile.json"
File in a folder	If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative pathname in filename. Example: "C:\myFolder\myFile.json" Example: "dataDir\myFile.json"
Internet URL	If the file is specified as an internet uniform resource locator (URL), then filename must contain the protocol type "http://" or "https://". Example: "http://hostname/path_to_file/my_file.json"
Remote location	If the file is stored at a remote location, then filename must contain the full path of the file specified with the form: scheme_name://path_to_file/my_file.ext Based on the remote location, scheme_name can be one of the values in this table. Remote Location scheme_name Amazon S3™ s3 Windows Azure® Blob Storage wasb, wasbs HDFS™ hdfs For more information, see Work with Remote Data. Example: "s3://bucketname/path_to_file/my_file.json"

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: d = readdictionary(filename,ValueType="string") imports values as strings.

FileType — Type of file

"auto" (default) | "json"

Type of file, specified as one of these values:

• "auto" — Automatically detect the file format of the input file from the extension specified in filename.

• "json" — Read the contents of the input file as JSON.

If you specify a file extension in filename that is not .json, you can specify FileType as "json" to read the contents of the input file as JSON.

DateLocale — Locale for reading dates

string scalar | character vector

Locale for reading dates, specified as a string scalar or character vector of the form xx_YY, where:

• xx is a lowercase ISO 639-1 two-letter code indicating a language.

• YY is an uppercase ISO 3166-1 alpha-2 code indicating a country.

This table lists some common values for the locale.

Locale	Language	Country
"de_DE"	German	Germany
"en_GB"	English	United Kingdom
"en_US"	English	United States
"es_ES"	Spanish	Spain
"fr_FR"	French	France
"it_IT"	Italian	Italy
"ja_JP"	Japanese	Japan
"ko_KR"	Korean	Korea
"nl_NL"	Dutch	Netherlands
"zh_CN"	Chinese (simplified)	China

DictionaryNodeName — Name of starting element

string scalar | character vector

Name of the starting element, specified as a string scalar or character vector. To specify where to start reading the input file, readdictionary finds the first node in the file whose name matches the value specified in DictionaryNodeName. readdictionary reads the contents of the input file starting with that node. If you do not specify DictionaryNodeName, then readdictionary starts reading at the root of the file.

Example: DictionaryNodeName="RootName"

Example: DictionaryNodeName="Instrumentation"

DictionarySelector — JSON Pointer to starting element

string scalar | character vector

JSON Pointer to starting element, specified as a string scalar or character vector. readdictionary reads the contents of the input file starting with the element at the specified JSON Pointer.

You can specify a JSON Pointer using the syntaxes in this table.

JSON Selection Operation	Syntax	Example
Select a JSON object key by name.	Prefix the name with one forward slash (/).	d = readdictionary("music.json",DictionarySelector="/Musicians")
Select a JSON array element by index.	Provide the index of the node after one forward slash (/). This index is zero-based.	d = readdictionary("music.json", ... DictionarySelector="/Musicians/4")

WebOptions — HTTP or HTTPS request options

weboptions object

HTTP or HTTPS request options, specified as a weboptions object. The weboptions object determines how to import data when the specified filename is an internet URL containing the protocol type "http://" or "https://".

ValueType — Type of dictionary values

"auto" (default) | "cell" | "string" | "double" | "int8" | ...

Type of dictionary values, specified as one of the values in this table.

Value	Description
"auto"	Data type detected automatically
"cell"	Cell and its contents
"string"	String text
"double"	Double-precision number
"single"	Single-precision number
"int8"	8-bit integer, signed
"int16"	16-bit integer, signed
"int32"	32-bit integer, signed
"int64"	64-bit integer, signed
"uint8"	8-bit integer, unsigned
"uint16"	16-bit integer, unsigned
"uint32"	32-bit integer, unsigned
"uint64"	64-bit integer, unsigned
"logical"	Logical value
"datetime"	Datetime value
"duration"	Duration value

DuplicateKeyRule — Rule for duplicate key names in objects

"auto" (default) | "preserveLast" | "makeUnique" | "error"

Rule for duplicate key names in objects, specified as one of these values:

• "auto" – Select behavior based on key type.

• "preserveLast" – Overwrite the values of previous duplicate key entries.

• "makeUnique" – Modify duplicate keys to be unique.

• "error" – Return an error upon encountering duplicate key names.

ParsingMode — Mode for following JSON standards while parsing

"lenient" (default) | "strict"

Mode for following JSON standards while parsing, specified as one of these values:

• "lenient" – The values of AllowComments, AllowInfAndNaN, and AllowTrailingCommas are set to true.

• "strict" – The values of AllowComments, AllowInfAndNaN, and AllowTrailingCommas are set to false.

AllowComments — Allow comments

true or 1 (default) | false or 0

Allow comments in the input file, specified as one of these values:

• Numeric or logical 1 (true) – Comments do not cause an error during import. Comments in the file are not considered data and are not read into MATLAB. Comments can start with // for single-line comments or start with /* and end with */ for multi-line comments.

• Numeric or logical 0 (false) – Comments cause an error during import.

AllowInfAndNaN — Read Inf and NaN literals

true or 1 (default) | false or 0

Read Inf and NaN literals in the input file, specified as one of these values:

• Numeric or logical 1 (true) – Inf and NaN literals (including Infinity, -Inf, and -Infinity) are read into MATLAB.

• Numeric or logical 0 (false) – Inf and NaN literals cause an error during import.

AllowTrailingCommas — Read trailing commas

true or 1 (default) | false or 0

Read trailing commas in the input file, specified as one of these values:

• Numeric or logical 1 (true) – Trailing commas after a JSON array or JSON object do not cause an error during import.

• Numeric or logical 0 (false) – Trailing commas cause an error during import.

Output Arguments

d — Output dictionary

MATLAB dictionary

Output dictionary, returned as a MATLAB dictionary. For more information on dictionaries, see dictionary.

Version History

Introduced in R2024b