Main Content

parse

Class: matlab.net.http.HeaderField
Package: matlab.net.http

Parse header field value and return as strings

Description

value = parse(obj) parses the Value property of the header field and returns strings. Use this method to process header fields for which there is no class in the matlab.net.http.field package. Use the matlab.net.http.HeaderField.displaySubclasses method to display classes in the package. For classes in the package, use the corresponding convert method to parse the value.

The parsing rules are based on sections 3.2.4-3.2.6 of RFC 7230 Message Syntax and Routing on the Internet Engineering Task Force (IETF®) website and are augmented to interpret multiple values.

example

value = parse(obj,fields) specifies the names to use for unnamed struct fields.

If the Nth field of a struct has no name, the corresponding Nth name in fields exists and is nonempty. It is used instead of Arg_N. Using this syntax forces the returned value to be a struct (or vector of struct objects) with at least as many fields as the length of fields. Typically this pattern occurs in header fields that begin with a token followed by attribute pairs.

value = parse(___,Name,Value) specifies one or more delimiters. The default delimiters are commas and semicolons. You can use any of the input arguments in the previous syntaxes.

Input Arguments

expand all

Header field, specified as a matlab.net.http.HeaderField object or a vector of HeaderField objects.

Names of struct fields, specified as a string vector, a character vector, or a cell array of character vectors.

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Delimiters separating array elements, specified as:

  • A string vector, character vector, or cell vector of regular expressions specifying the possible delimiters, interpreted in the order they appear in the vector.

  • '' — Do not parse obj as an array. MATLAB® inserts quotes and escape characters.

  • [] — Do not parse obj as an array. MATLAB does not insert quotes or escape characters into array elements.

Delimiters separating structure fields, specified as:

  • A string vector, character vector, or cell vector of regular expressions specifying the possible delimiters, interpreted in the order they appear in the vector.

  • '' — Do not parse obj as a struct. MATLAB inserts quotes and escape characters.

  • [] — Do not parse obj as a struct. MATLAB does not insert quotes or escape characters into struct values.

Output Arguments

expand all

Header field Value property, returned as a string vector, a struct array, or a cell array of struct values.

MATLAB parses the Value property as a list of comma-separated strings. Each string becomes an element of the value vector. An element is one of the following:

  • struct of name=value pairs

  • struct of semicolon-separated values

  • string, if the field does not contain a semicolon or an equal sign or does not appear to be a structure.

parse converts the name of each struct field to a valid MATLAB identifier using matlab.lang.makeValidName. For the following Value property, parse creates field name x_p1 from _p1.

To resolve duplicate names, parse calls matlab.lang.makeUniqueStrings. For the following Value property, parse creates field name p11 from duplicate field name p1.

If a struct field contains only a Value, but not a name=value pair, then the field name is Arg_N. The N is the ordinal position of the field in the struct. For the following Value property, parse creates field name Arg_2 for the missing name.

Value Property

Output Argument

Description

"p1=first p2=second"
    p1: "first"
    p2: "second"

parse returns a struct for name=value pairs.

"first;second"
    Arg_1: "first"
    Arg_2: "second"

parse returns a struct and assigns default field names for semicolon-separated values.

"first second"
"first second"

parse returns a string if the field does not contain a semicolon or an equal sign or does not appear to be a structure.

"_p1=first p2=second"
    x_p1: "first"
      p2: "second"

parse converts invalid field name _p1 to x_p1.

"p1=first p1=second"
     p1: "first"
    p11: "second"

parse converts duplicate field name p1 to p11.

"p1=first; second"
       p1: "first"
    Arg_2: "second"

parse creates field name Arg_2 for the missing name for Value second.

"p1=first; p3=(a comment here)"
    p1: "first"
    p3: "(a comment here)"

parse retains comments.

If obj is a vector of header fields, then the parse method concatenates the results of parsing each of the fields into a single array. If the values are not of the same type, then value is a cell array.

Value Property of Header Field Vector

Element of Cell Array Output Argument

"p1=first p2=second"
x{1} =
 
    p1: "first"
    p2: "second"
"third"
x{2} =
 
third

Examples

expand all

Assume that you receive a header field H in a response message from a server with the Value property media-type; name1=value1; name2=value2. To run this example, create the variable H.

H = matlab.net.http.HeaderField('Test-Name','media-type; name1=value1; name2=value2')
H = 

  HeaderField with properties:

     Name: "Test-Name"
    Value: "media-type; name1=value1; name2=value2"

Parse the Value property of H. MATLAB creates a default field name Arg_1.

var = parse(H)
var = 

  struct with fields:

    Arg_1: "media-type"
    name1: "value1"
    name2: "value2"

Change the default to a more meaningful name MediaType.

var = parse(H,'MediaType')
var = 

  struct with fields:

    MediaType: "media-type"
        name1: "value1"
        name2: "value2"

Attributes

Sealedtrue

To learn about attributes of methods, see Method Attributes.

Version History

Introduced in R2016b