matlab.net.URI - Uniform resource identifier (URI) - MATLAB (original) (raw)
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:
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](#mw%5F20a7bd78-bbb9-4cd9-bebf-519156a8a520)) creates the URI specified by destination.
obj = matlab.net.URI([destination](#mw%5F20a7bd78-bbb9-4cd9-bebf-519156a8a520),[queryVector](#mw%5F6cb28ac9-149f-4b7a-a3d9-af913bec28b1)) sets the Query property toqueryVector. Query values are appended to any query parameters already specified in destination.
obj = matlab.net.URI([destination](#mw%5F20a7bd78-bbb9-4cd9-bebf-519156a8a520),[queryName](#mw%5F0bbe05a7-6d21-4a26-8849-600f7ea6e728),[queryValue](#mw%5F67ab42ad-9937-45c3-b218-d4d46232d0b9)) adds one or more queryName,queryValue parameters to the Query property.
obj = matlab.net.URI([destination](#mw%5F20a7bd78-bbb9-4cd9-bebf-519156a8a520),[queryVector](#mw%5F6cb28ac9-149f-4b7a-a3d9-af913bec28b1),[queryName](#mw%5F0bbe05a7-6d21-4a26-8849-600f7ea6e728),[queryValue](#mw%5F67ab42ad-9937-45c3-b218-d4d46232d0b9)) adds queryVector and thequeryName,queryValue parameters to theQuery property.
obj = matlab.net.URI(___,[format](#mw%5Fb2dd8eb6-3881-494c-ba77-d2a1a8b5ae3f)) specifies the format of the output when an array appears in aqueryValue argument. You can use any of the input arguments in the previous syntaxes.
obj = matlab.net.URI(___,'literal') indicates thatdestination 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 theHost or Path, are still percent-encoded.
This option has no effect on Query (matlab.net.QueryParameter) arguments.
Input Arguments
Destination, specified as a string or a character vector specifying a URI or portions of one, or a matlab.net.URI object. Ifdestination is a matlab.net.URI object, thendestination must be the only argument.
Example: https://user:pwd@www.mathworks.com: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
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)
Query name, specified as a string or a character vector. The web service definesqueryName,queryValue pairs that it accepts as part of a request. Do not encode characters in queryName.
Query value, specified as a character array, or a numeric, logical, ordatetime value or array. Do not encode characters inqueryValue.
Output format, specified as a matlab.net.ArrayFormat object when an array appears in a queryValue argument. For allowed values, seeArrayFormat.
The format argument does not affect the format of values in the queryVector argument.
Properties
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 behttp or https. However, this convention is not enforced. MATLAB® does not support other schemes, such as file.
Example: http
Example: https
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 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 number, specified as a number, or as a string or a character vector representing a number in the range 0–65535, stored as auint16.
Example: 8000
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 ofPath.
Path(1)/Path(2)/Path(3)/.../Path(end)
The / characters do not appear in Path, butEncodedPath contains them. For example,
uri = matlab.net.URI; uri.Path = {'products' 'matlab'}; P = uri.Path
If you setPath 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
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, thenEncodedPath begins with /. IfPath(end) is an empty string, thenEncodedPath ends with /.
uri.Path = '/products/matlab/'; EP = uri.EncodedPath
When setting Path to a nonscalar string or cell array, characters not allowed in the path portion of a URI are percent-encoded inEncodedPath. To include the # character,
uri.Path = {'foo#bar'};EP = uri.EncodedPath
Do not encode the # character. If you do, then the encoded characters are encoded again.
uri.Path = {'foo%23Fbar'}; EP = uri.EncodedPath
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
Create a relative path:
uri2 = matlab.net.URI; uri2.Path = {'products' 'matlab'}; EP = uri2.EncodedPath
If the URI contains a Scheme, Host,UserInfo or Port property, andPath is not empty, then EncodedPath has a leading /. The / character separatesPath 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.
Set the Host:
uri1.Host = 'www.mathworks.com'; disp(string(uri1))
//www.mathworks.com/products/matlab
Set Host of relative path uri2:
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
To set Path to a folder, add an empty string to the end of the vector. This convention adds a trailing / toEncodedPath.
uri.Path = {'products' 'matlab' ''}; EP = uri.EncodedPath
Query of URI, specified as a vector of matlab.net.QueryParameter objects or a string containing the encoded query with an optional leading ? character.
Direction to a secondary resource, specified as a string or a character vector. Thestring 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 URIhttps://www.mathworks.com/help/matlab/ref/weboptions.html#examples, the Fragment property is examples.
Whether URI is absolute, specified as true orfalse. An absolute URI has a nonempty Scheme property. If the URI is not absolute, then it is relative. For a definition ofabsolute-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
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 ofEncodedAuthority is`UserInfo`@`Host`:`Port`. Setting EncodedAuthority is a shortcut to setting theUserInfo, Host, andPort properties, except that you must encode special characters.
Example: In the URIhttps://user:pwd@www.mathworks.com:8000/product/matlab?abc=def&this=that#xyz, the EncodedAuthority property isuser:pwd@www.mathworks.com:8000.
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 theEncodedPath 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 beforePath.
Setting EncodedPath to an empty array ('',[] or string.empty) is equivalent to settingPath to that value.
If there is no Path property in an encoded URI, thenEncodedPath 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.
Encoded query, specified as a string or a character vector.EncodedQuery returns the same value as calling thestring method on the Query property. SettingEncodedQuery is equivalent to setting theQuery property.
Example: In the URIhttps://www.mathworks.com/support/search_results.html?q=+weboptions+product:"MATLAB+Compiler", the EncodedQuery property isq=+weboptions+product:%22MATLAB+Compiler%22.
Entire encoded URI, specified as a string or a character vector.EncodedURI returns the same value as thematlab.net.URI.string method. Setting EncodedURI is equivalent to calling the URI constructor with the'literal' argument.
Methods
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
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.
U = matlab.net.URI('//www.mathworks.com/products/simulink/'); U.EncodedURI
ans =
string
"//www.mathworks.com/products/simulink/"Version History
Introduced in R2016b