matlab.net.URI Class

Namespace: matlab.net

Uniform resource identifier (URI)

Description

The matlab.net.URI class constructs an internet uniform resource identifier (URI), such as a web address or a URL. An internet URI is a string divided into components. Each component is represented by a property of the URI class. The following text shows the properties and their associated punctuation, separated by spaces for clarity. The spaces do not appear in the encoded URI. The associated punctuation is not part of the property value.

Scheme: //Authority /Path(1) /Path(2) ... /Path(end) ?Query #Fragment

where Authority contains these properties:

UserInfo@ Host :Port

Use the matlab.net.URI string or char methods to create an internet URI. These methods encode the properties by adding punctuation to nonempty properties and by escaping reserved characters.

All properties are optional. However, different uses might require certain properties to be set.

To eliminate a property and its punctuation from the output string, set the property value to [].

Creation

Description

obj = matlab.net.URI creates an empty URI.

obj = matlab.net.URI(destination) creates the URI specified by destination.

obj = matlab.net.URI(destination,queryVector) sets the Query property to queryVector. Query values are appended to any query parameters already specified in destination.

obj = matlab.net.URI(destination,queryName,queryValue) adds one or more queryName,queryValue parameters to the Query property.

obj = matlab.net.URI(destination,queryVector,queryName,queryValue) adds queryVector and the queryName,queryValue parameters to the Query property.

obj = matlab.net.URI(___,format) specifies the format of the output when an array appears in a queryValue argument. You can use any of the input arguments in the previous syntaxes.

obj = matlab.net.URI(___,'literal') indicates that destination is already encoded. Use this option if you copy and paste an already-encoded URI, for example, from the address bar of a browser. When you read properties of this URI directly, you see the decoded version. The 'literal' option does not permit you to construct an illegal URI. It prevents reencoding of '%' characters. Characters that must always be encoded, such as '\' and ' ' in the Host or Path, are still percent-encoded.

This option has no effect on Query (matlab.net.QueryParameter) arguments.

Input Arguments

destination — Destination

string | character vector | matlab.net.URI object

Destination, specified as a string or a character vector specifying a URI or portions of one, or a matlab.net.URI object. If destination is a matlab.net.URI object, then destination must be the only argument.

Example: https://user:[e-mail]:8000/product/matlab?abc=def&this=that#xyz All properties

Example: Host and Scheme properties: https://www.mathworks.com

Example: Host only: //www.mathworks.com

Example: Host and Path: //www.mathworks.com/products/matlab/

Example: Path only: products/matlab/live-editor

Example: Host and Query: //www.mathworks.com/search/site_search.html?q=weboptions

queryVector — Query property

matlab.net.QueryParameter object

Query property, specified as a vector of matlab.net.QueryParameter objects. A query is of the form:

name1=value1&name2=value2&name3=value3

Example: matlab.net.QueryParameter('hl','en','ie','utf8','num',50)

queryName — Query name

string | character vector

Query name, specified as a string or a character vector. The web service defines queryName,queryValue pairs that it accepts as part of a request. Do not encode characters in queryName.

queryValue — Query value

character array | numeric | logical | datetime

Query value, specified as a character array, or a numeric, logical, or datetime value or array. Do not encode characters in queryValue.

format — Output format

matlab.net.ArrayFormat object

Output format, specified as a matlab.net.ArrayFormat object when an array appears in a queryValue argument. For allowed values, see ArrayFormat.

The format argument does not affect the format of values in the queryVector argument.

Properties

Scheme — URI scheme

string | character vector

URI scheme, sometimes called protocol, appearing before the :// characters, specified as a string or a character vector. Scheme always returns a string. If not empty, then Scheme must be http or https. However, this convention is not enforced. MATLAB^® does not support other schemes, such as file.

Example: http

Example: https

UserInfo — User information

string | character vector

User information, specified as a string or a character vector. UserInfo appears before the Host property followed by an @ character. The string method percent-encodes special characters. When setting UserInfo, do not encode the value.

Example: name

Example: name:password

Host — Host name

string or character vector in DNS name format | IPv4 or IPv6 address

Host name, specified as a string or a character vector. The value is in Domain Name System (DNS) format or as an Internet Protocol version 4 (IPv4) or version 6 (IPv6) address. The string method percent-encodes characters that are not allowed in the host portion of a URI. Period characters (.) are unchanged. When setting Host, do not encode the value.

Example: www.mathworks.com

Example: 2222:7344:0db8:0000:0100:8a2e:0370:85a3 IPv6 address

Port — Port number

number | string | character vector

Port number, specified as a number, or as a string or a character vector representing a number in the range 0–65535, stored as a uint16.

Example: 8000

Path — Path segments

string | string vector | character vector | cell array of character vectors

Path segments, specified as a string or string vector or as a character vector or cell array of character vectors. The result is always a vector of strings. To see the value of the encoded path, use the EncodedPath property.

A path in a URI is specified by the EncodedPath property. EncodedPath is a series of segments separated by the / character, where each of those segments is a member of Path.

Path(1)/Path(2)/Path(3)/.../Path(end)

The / characters do not appear in Path, but EncodedPath contains them. For example,

uri = matlab.net.URI;
uri.Path = {'products' 'matlab'};
P = uri.Path

P = 
    "products"    "matlab"

EP = uri.EncodedPath

EP = products/matlab

If you set Path to a character vector or scalar string that contains a / character, then the value is split into segments at the / characters. The result is the same as specifying a vector of strings or cell array of character vectors.

uri.Path = 'products/matlab';
P = uri.Path

P = 
    "products"    "matlab"

There is always one more Path segment than the number of / characters in EncodedPath. Any segment can be an empty string. If Path(1) is an empty string, then EncodedPath begins with /. If Path(end) is an empty string, then EncodedPath ends with /.

uri.Path = '/products/matlab/';
EP = uri.EncodedPath

EP = /products/matlab/

When setting Path to a nonscalar string or cell array, characters not allowed in the path portion of a URI are percent-encoded in EncodedPath. To include the # character,

uri.Path = {'foo#bar'};EP = uri.EncodedPath

EP = foo%23bar

Do not encode the # character. If you do, then the encoded characters are encoded again.

uri.Path = {'foo%23Fbar'};
EP = uri.EncodedPath

EP = foo%2523Fbar

Path can be relative or absolute. An absolute path is one with more than one segment, whose first segment is empty. It is encoded as a string beginning with / character followed by the second string. This definition of absolute path corresponds to path-absolute, defined in RFC 3986 Uniform Resource Identifier (URI): Generic Syntax, section 3.3 Path on the RFC Editor website. A relative path is one whose first string is nonempty. It is encoded without a leading /. For example, create an absolute path:

uri1 = matlab.net.URI;
uri1.Path = {'' 'products' 'matlab'};
EP = uri1.EncodedPath

EP = /products/matlab

Create a relative path:

uri2 = matlab.net.URI;
uri2.Path = {'products' 'matlab'};
EP = uri2.EncodedPath

EP = products/matlab

If the URI contains a Scheme, Host, UserInfo or Port property, and Path is not empty, then EncodedPath has a leading /. The / character separates Path from the other properties. Therefore, the distinction between absolute and relative paths exists only for URIs that do not contain Scheme, Host, UserInfo, or Port properties. For example, uri1 is an absolute path.

uri1.EncodedPath

ans = /products/matlab

Set the Host:

uri1.Host = 'www.mathworks.com';
disp(string(uri1))

//www.mathworks.com/products/matlab

Set Host of relative path uri2:

uri2.EncodedPath

ans = products/matlab

uri2.Host = 'www.mathworks.com';
disp(string(uri2))

//www.mathworks.com/products/matlab

To create a URI with a path that points to the root, set Path to string.empty or ["" ""].

uri.Path = {'products' 'matlab' ''};
EP = uri.EncodedPath

EP = products/matlab/

To set Path to a folder, add an empty string to the end of the vector. This convention adds a trailing / to EncodedPath.

uri.Path = {'products' 'matlab' ''};
EP = uri.EncodedPath

EP = products/matlab/

Query — Query of URI

matlab.net.QueryParameter object | string

Query of URI, specified as a vector of matlab.net.QueryParameter objects or a string containing the encoded query with an optional leading ? character.

Fragment — Direction to secondary resource

string | character vector

Direction to a secondary resource, specified as a string or a character vector. The string method percent-encodes characters that are not allowed in the fragment portion of a URI. When setting Fragment, do not encode the value.

Example: In the URI https://www.mathworks.com/help/matlab/ref/weboptions.html#examples, the Fragment property is examples.

Absolute — Whether URI is absolute (read-only)

true | false

Whether URI is absolute, specified as true or false. An absolute URI has a nonempty Scheme property. If the URI is not absolute, then it is relative. For a definition of absolute-URI, see RFC 3986 Uniform Resource Identifier (URI): Generic Syntax, Section 4.3 Absolute URI.

The Path property in an absolute URI is always treated as an absolute path and the EncodedPath property always contains a leading / character. To send a message, the URI must be absolute and must also contain a nonempty Host property.

Data Types: logical

EncodedAuthority — Encoded authority portion of URI

string | character vector

Encoded authority portion of a URI, specified as a string or a character vector with associated punctuation appearing only if the property is nonempty. The format of EncodedAuthority is UserInfo@Host:Port. Setting EncodedAuthority is a shortcut to setting the UserInfo, Host, and Port properties, except that you must encode special characters.

Example: In the URI https://user:[e-mail]:8000/product/matlab?abc=def&this=that#xyz, the EncodedAuthority property is user:[e-mail]:8000.

EncodedPath — Encoded path

string | character vector

Encoded path, specified as a string or a character vector. Read this property to obtain the Path property as an encoded string as it would appear in the encoded URI. If you have an already-encoded path as a string, then set the EncodedPath property instead of the Path property to prevent further encoding. When reading EncodedPath, it has a leading / if Path is not [] and there are nonempty components in the URI before Path.

Setting EncodedPath to an empty array ('', [] or string.empty) is equivalent to setting Path to that value.

If there is no Path property in an encoded URI, then EncodedPath returns an empty string, "". However, EncodedPath is never an empty array.

Example: In the URI https://www.mathworks.com/solutions/robotics, the EncodedPath property is /solutions/robotics.

EncodedQuery — Encoded query

string | character vector

Encoded query, specified as a string or a character vector. EncodedQuery returns the same value as calling the string method on the Query property. Setting EncodedQuery is equivalent to setting the Query property.

Example: In the URI https://www.mathworks.com/support/search_results.html?q=+weboptions+product:"MATLAB+Compiler", the EncodedQuery property is q=+weboptions+product:%22MATLAB+Compiler%22.

EncodedURI — Entire encoded URI

string | character vector

Entire encoded URI, specified as a string or a character vector. EncodedURI returns the same value as the matlab.net.URI.string method. Setting EncodedURI is equivalent to calling the URI constructor with the 'literal' argument.

Methods

Specialized Operators and Functions

These methods specialize standard MATLAB operators and functions for objects in this class.

eq	Compare URIs for equality. Two URIs are considered equal if they refer to the same resource. An empty string or empty Path property is considered equal to [].
char	URI as character vector
string	URI as string

Examples

Search mathworks.com for Term weboptions

Create a URI.

U = matlab.net.URI('https://www.mathworks.com');
U.Query = matlab.net.QueryParameter('q','weboptions');
U.Path = 'search/site_search.html';

Display the search results containing weboptions.

 web(char(U))

Create URI for Simulink Product Web Page

U = matlab.net.URI('//www.mathworks.com/products/simulink/');
U.EncodedURI

ans = 

  string

    "//www.mathworks.com/products/simulink/"

Version History

Introduced in R2016b