readdictionary

Create dictionary from file

Since R2024b

collapse all in page

    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.

    example

    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

    collapse all

    Open Live Script

    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
    Open Live Script

    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"      ⟼ {1×1 cell}

    Input Arguments

    collapse all

    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 Locationscheme_name
    Amazon S3™s3
    Windows Azure® Blob Storagewasb, wasbs
    HDFS™hdfs

    For more information, see Work with Remote Data.

    Example: "s3://bucketname/path_to_file/my_file.json"

    Compressed file formats are read as files. Archived file formats are treated as folders. For example, the function interprets mydatafiles.zip as a folder, so you must specify a file within it, such as mydatafiles.zip/file1.xlsx. For files ending with the .gz extension, the function determines the file format by using the extension preceding .gz. For example, mydata.csv.gz is read as a CSV file. (since R2025a)

    Name-Value Arguments

    collapse all

    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.

    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.

    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 LanguageCountry
    "de_DE"GermanGermany
    "en_GB"EnglishUnited Kingdom
    "en_US"EnglishUnited States
    "es_ES"SpanishSpain
    "fr_FR"FrenchFrance
    "it_IT"ItalianItaly
    "ja_JP"JapaneseJapan
    "ko_KR"KoreanKorea
    "nl_NL"DutchNetherlands
    "zh_CN"Chinese (simplified)China

    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"

    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 OperationSyntaxExample
    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")

    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://".

    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

    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.

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

    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.

    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.

    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

    collapse all

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

    Version History

    Introduced in R2024b

    expand all

    See Also

    |