xtd::uri Class Reference

Inheritance diagram for xtd::uri:

Definition

Provides an object representation of a uniform resource identifier (URI) and easy access to the parts of the URI.

class uri : public xtd::iequatable<uri>, public xtd::object

Inheritance

xtd::object → xtd::uri

Implements

xtd::iequatable <>

Namespace

xtd

Library

xtd.core

Examples

The following example creates an instance of the xtd::uri class and uses it to create a xtd::net::web_request instance.

uri contoso("http://www.contoso.com/");
 
auto wr = web_request::create(contoso);

The following code snippet shows example values of the various properties on the class.

#include <xtd/console>
#include <xtd/startup>
#include <xtd/uri>
 
namespace uri_example {
  class program {
  public:
    // The main entry point for the application.
    static auto main() {
      auto uri = xtd::uri {"https://user:password@www.contoso.com:80/Home/Index.htm?q1=v1&q2=v2#FragmentName"};
      
      xtd::console::write_line("absolute_path: {}", uri.absolute_path());
      xtd::console::write_line("absolute_uri: {}", uri.absolute_uri());
      xtd::console::write_line("dns_safe_host: {}", uri.dns_safe_host());
      xtd::console::write_line("fragment: {}", uri.fragment());
      xtd::console::write_line("host: {}", uri.host());
      xtd::console::write_line("host_name_type: {}", uri.host_name_type());
      xtd::console::write_line("idn_host: {}", uri.idn_host());
      xtd::console::write_line("is_absolute_uri: {}", uri.is_absolute_uri());
      xtd::console::write_line("is_default_port: {}", uri.is_default_port());
      xtd::console::write_line("is_file: {}", uri.is_file());
      xtd::console::write_line("is_loopback: {}", uri.is_loopback());
      xtd::console::write_line("is_unc: {}", uri.is_unc());
      xtd::console::write_line("local_path: {}", uri.local_path());
      xtd::console::write_line("original_string: {}", uri.original_string());
      xtd::console::write_line("path_and_query: {}", uri.path_and_query());
      xtd::console::write_line("port: {}", uri.port());
      xtd::console::write_line("query: {}", uri.query());
      xtd::console::write_line("scheme: {}", uri.scheme());
      xtd::console::write_line("segments: {}", xtd::ustring::join(", ", uri.segments()));
      xtd::console::write_line("user_info: {}", uri.user_info());
    }
  };
}
 
startup_(uri_example::program::main);
 
// This code can produce the following output:
//
// absolute_path: /Home/Index.htm
// absolute_uri: https://user:password@www.contoso.com:80/Home/Index.htm?q1=v1&q2=v2#FragmentName
// dns_safe_host: www.contoso.com
// fragment: #FragmentName
// host: www.contoso.com
// host_name_type: Dns
// idn_host: www.contoso.com
// is_absolute_uri: true
// is_default_port: false
// is_file: false
// is_loopback: false
// is_unc: false
// local_path: /Home/Index.htm
// original_string: https://user:password@www.contoso.com:80/Home/Index.htm?q1=v1&q2=v2#FragmentName
// path_and_query: /Home/Index.htm?q1=v1&q2=v2
// port: 80
// query: ?q1=v1&q2=v2
// scheme: https
// segments: /, Home/, Index.htm
// user_info: user:password

Remarks

A URI is a compact representation of a resource available to your application on the intranet or Internet. The xtd::uri class defines the properties and methods for handling URIs, including parsing, comparing, and combining. The xtd::uri class properties are read-only; to create a modifiable object, use the xtd::uri_builder class.

Relative URIs (for example, "/new/index.htm") must be expanded with respect to a base URI so that they are absolute. The xtd::uri::make_relative_uri method is provided to convert absolute URIs to relative URIs when necessary.

The xtd::uri constructors do not escape URI strings if the string is a well-formed URI including a scheme identifier.

The xtd::uri properties return a canonical data representation in escaped encoding, with all characters with Unicode values greater than 127 replaced with their hexadecimal equivalents. To put the URI in canonical form, the xtd::uri constructor performs the following steps:

• Converts the URI scheme to lowercase.
• Converts the host name to lowercase.
• If the host name is an IPv6 address, the canonical IPv6 address is used. ScopeId and other optional IPv6 data are removed.
• Removes default and empty port numbers.
• Canonicalizes the path for hierarchical URIs by compacting sequences such as /./, /../, //, including escaped representations. Note that there are some schemes for which escaped representations are noy compacted.
• For hierarchical URIs, if the host is not terminated with a forward slash (/), one is added.
• By default, any reserved characters in the URI are escaped in accordance with RFC 2396. This behavior changes if International Resource Identifiers or International Domain Name parsing is enabled in which case reserved characters in the URI are escaped in accordance with RFC 3986 and RFC 3987.

As part of canonicalization in the constructor for some schemes, escaped representations are compacted. The schemes for which URI will compact escaped sequences include the following: file, http, https, net.pipe, and net.tcp. For some other schemes, these sequences are not compacted. The following code snippet shows how compacting looks in practice. The escaped sequences are unescaped, if necessary, and then compacted.

auto uri = xtd::uri("http://myUrl/../.."); // http scheme, unescaped
// OR
auto uri = xtd::uri("http://myUrl/%2E%2E/%2E%2E"); // http scheme, escaped
// OR
var uri = xtd::uri("ftp://myUrl/../.."); // ftp scheme, unescaped
// OR
var uri = xtd:::uri("ftp://myUrl/%2E%2E/%2E%2E"); // ftp scheme, escaped
 
console::write_line("Absolute uri: {}", uri.absolute_uri());
console::write_line("Path And query: {}", uri.path_and_query());

When this code executes, it returns output similar to the following text.

Absolute uri: http://myurl/
Path And query: /

You can transform the contents of the xtd::uri class from an escape encoded URI reference to a readable URI reference by using the xtd::uri::to_string method. Note that some reserved characters might still be escaped in the output of the xtd::uri::to_string method. This is to support unambiguous reconstruction of a URI from the value returned by xtd::uri::to_string.

Some URIs include a fragment identifier or a query or both. A fragment identifier is any text that follows a number sign (#), not including the number sign; the fragment text is stored in the xtd::uri::fragment property. Query information is any text that follows a question mark (?) in the URI; the query text is stored in the xtd::uri::query property.

Note

The URI class supports the use of IP addresses in both quad-notation for IPv4 protocol and colon-hexadecimal for IPv6 protocol. Remember to enclose the IPv6 address in square brackets, as in http://[::1].

International Resource Identifier Support

Web addresses are typically expressed using uniform resource identifiers that consist of a very restricted set of characters:

• Upper and lower case ASCII letters from the English alphabet.
• Digits from 0 to 9.
• A small number of other ASCII symbols. The specifications for URIs are documented in RFC 2396, RFC 2732, RFC 3986, and RFC 3987 published by the Internet Engineering Task Force (IETF).
  
  With the growth of the Internet, there is a growing need to identify resources using languages other than English. Identifiers which facilitate this need and allow non-ASCII characters (characters in the Unicode/ISO 10646 character set) are known as International Resource Identifiers (IRIs). The specifications for IRIs are documented in RFC 3987 published by IETF. Using IRIs allows a URL to contain Unicode characters.

Implicit File Path Support

xtd::uri can also be used to represent local file system paths. These paths can be represented explicitly in URIs that begin with the file:// scheme, and implicitly in URIs that do not have the file:// scheme. As a concrete example, the following two URIs are both valid, and represent the same file path:

auto uri1 = uri("C:/test/path/file.txt") // Implicit file path.
auto uri2 = uri("file:

These implicit file paths are not compliant with the URI specification and so should be avoided when possible. When using Unix-based systems, implicit file paths can be especially problematic, because an absolute implicit file path is indistinguishable from a relative path. When such ambiguity is present, xtd::uri default to interpreting the path as an absolute URI.

Security Considerations

Because of security concerns, your application should use caution when accepting xtd::uri instances from untrusted sources and with dont_escape set to true in the constructor. You can check a URI string for validity by calling the xtd::uri::is_well_formed_original_string method.

When dealing with untrusted user input, confirm assumptions about the newly created xtd::uri instance before trusting its properties. This can be done in the following way:

ustring user_input = ...;
 
auto base_uri = uri("https://myWebsite/files/");
 
if (!uri::try_create(base_uri, user_input, new_uri)) {
  // Fail: invalid input.
}
 
if (!base_uri.isbase_of(new_uri)) {
  // Fail: the uri base has been modified - the created uri is not rooted in the original directory.
}

This validation can be used in other cases, like when dealing with UNC paths, by simply changing the base_uri:

aauto base_uri = uri(@"\\host\share\some\directory\name\");

Examples

uri.cpp.

Public Fields
static const xtd::ustring	scheme_delimiter
	Specifies the characters that separate the communication protocol scheme from the address portion of the URI. This field is read-only.
static const xtd::ustring	uri_scheme_file
	Specifies that the URI is a pointer to a file. This field is read-only.
static const xtd::ustring	uri_scheme_ftp
	Specifies that the URI is accessed through the File Transfer Protocol (FTP). This field is read-only.
static const xtd::ustring	uri_scheme_gopher
	Specifies that the URI is accessed through the Gopher protocol. This field is read-only.
static const xtd::ustring	uri_scheme_http
	Specifies that the URI is accessed through the Hypertext Transfer Protocol (HTTP). This field is read-only.
static const xtd::ustring	uri_scheme_https
	Specifies that the URI is accessed through the Hypertext Transfer Protocol (HTTPS). This field is read-only.
static const xtd::ustring	uri_scheme_mailto
	Specifies that the URI is an e-mail address and is accessed through the Simple Mail Transport Protocol (SMTP). This field is read-only.
static const xtd::ustring	uri_scheme_net_pipe
	Specifies that the URI is accessed through the NetPipe scheme used by Windows Communication Foundation (WCF). This field is read-only.
static const xtd::ustring	uri_scheme_net_tcp
	Specifies that the URI is accessed through the NetTcp scheme used by Windows Communication Foundation (WCF). This field is read-only.
static const xtd::ustring	uri_scheme_news
	Specifies that the URI is an Internet news group and is accessed through the Network News Transport Protocol (NNTP). This field is read-only.
static const xtd::ustring	uri_scheme_nntp
	Specifies that the URI is an Internet news group and is accessed through the Network News Transport Protocol (NNTP). This field is read-only.

Public Constructors
	uri ()=default
	Initializes a new instance of the xtd::uri class.
	uri (const xtd::ustring &uri_string)
	Initializes a new instance of the xtd::uri class with the specified URI.
	uri (const xtd::ustring &uri, xtd::uri_kind uri_kind)
	Initializes a new instance of the xtd::uri class with the specified URI. This constructor allows you to specify if the URI string is a relative URI, absolute URI, or is indeterminate.
	uri (const uri &base_uri, const xtd::ustring &relative_uri)
	Initializes a new instance of the xtd::uri class based on the specified base URI and relative URI string.
	uri (const uri &base_uri, const uri &relative_uri)
	Initializes a new instance of the xtd::uri class based on the combination of a specified base xtd::uri instance and a relative xtd::uri instance.

Public Properties
xtd::ustring	absolute_path () const
	Gets the absolute path of the URI.
xtd::ustring	absolute_uri ()
	Gets the absolute URI.
xtd::ustring	authority () const
	Gets the Domain Name System (DNS) host name or IP address and the port number for a server.
xtd::ustring	dns_safe_host () const
	Gets an unescaped host name that is safe to use for DNS resolution.
xtd::ustring	fragment () const
	Gets the escaped URI fragment.
xtd::ustring	host () const
	Gets the host component of this instance.
xtd::uri_host_name_type	host_name_type () const
	Gets the type of the host name specified in the URI.
xtd::ustring	idn_host () const
	Gets the RFC 3490 compliant International Domain Name of the host, using Punycode as appropriate. This string, after being unescaped if necessary, is safe to use for DNS resolution.
bool	is_absolute_uri () const
	Gets whether the xtd::uri instance is absolute.
bool	is_default_port () const
	Gets whether the port value of the URI is the default for this scheme.
bool	is_file () const
	Gets a value indicating whether the specified xtd::uri is a file URI.
bool	is_loopback () const
	Gets whether the specified xtd::uri references the local host.
bool	is_unc () const
	Gets whether the specified xtd::uri is a universal naming convention (UNC) path.
xtd::ustring	local_path () const
	Gets the original URI string that was passed to the xtd::uri constructor.
const xtd::ustring &	original_string () const
	Gets the original URI string that was passed to the xtd::uri constructor.
xtd::ustring	path_and_query () const
	Gets the absolute_path and query properties separated by a question mark (?).
int32	port () const
	Gets the port number of this URI.
xtd::ustring	query () const
	Gets any query information included in the specified URI.
xtd::ustring	scheme () const
	Gets the scheme name for this URI.
std::vector< xtd::ustring >	segments () const
	Gets an array containing the path segments that make up the specified URI.
xtd::ustring	user_info () const
	Gets the user name, password, or other user-specific information associated with the specified URI.

Public Methods
xtd::ustring	get_components (xtd::uri_components components, xtd::uri_format format) const
	Gets the specified components of the current instance using the specified escaping for special characters.
xtd::ustring	get_left_part (xtd::uri_partial part) const
	Gets the specified portion of a xtd::uri instance.
bool	is_base_of (const xtd::uri &uri) const
	Determines whether the current xtd::uri instance is a base of the specified xtd::uri instance.
bool	is_well_formed_original_string ()
	Indicates whether the string used to construct this xtd::uri was well-formed and is not required to be further escaped.
bool	equals (const xtd::uri &uri) const noexcept override
	Indicates whether the current object is equal to another object of the same type.
xtd::ustring	to_string () const noexcept override
	Gets a canonical string representation for the specified xtd::uri instance.
static bool	check_scheme_name (const xtd::ustring &scheme)
	Determines whether the specified scheme name is valid.
static xtd::ustring	escape_data_string (const xtd::ustring &value)
	Converts a string to its escaped representation.
static xtd::ustring	escape_uri_string (const xtd::ustring &value)
	Converts a URI string to its escaped representation.
static int32	from_hex (char digit)
	Gets the decimal value of a hexadecimal digit.
static xtd::ustring	hex_escape (char character)
	Converts a specified character into its hexadecimal equivalent.
static char	hex_unescape (const xtd::ustring &pattern, size_t &index)
	Converts a specified hexadecimal representation of a character to the character.
static bool	is_hex_digit (char character)
	Determines whether a specified character is a valid hexadecimal digit.
static bool	is_hex_encoding (const xtd::ustring &pattern, size_t index)
	Determines whether a character in a string is hexadecimal encoded.
static bool	is_well_formed_uri_string (const xtd::ustring &uri_string, xtd::uri_kind uri_kind)
	Indicates whether the string is well-formed by attempting to construct a URI with the string and ensures that the string does not require further escaping.
static xtd::ustring	unescape_data_string (const xtd::ustring &value)
	Converts a string to its unescaped representation.

Additional Inherited Members
Public Member Functions inherited from xtd::iequatable< uri >
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object.
Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal.
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

uri() [1/5]

xtd::uri::uri ( )

default

Initializes a new instance of the xtd::uri class.

uri() [2/5]

xtd::uri::uri ( const xtd::ustring &  uri_string )

explicit

Initializes a new instance of the xtd::uri class with the specified URI.

Parameters

uri_string

: A string that identifies the resource to be represented by the xtd::uri instance. Note that an IPv6 address in string form must be enclosed within brackets. For example, "http://[2607:f8b0:400d:c06::69]".

Exceptions

xtd::uri_format_exception

uri_string is empty. -or- The scheme specified in uri_string is not correctly formed. See xtd::uricheck_scheme_name. -or- The password specified in uri_string is not valid. -or- The host name specified in uri_string is not valid. -or- The file name specified in uri_string is not valid. -or- The user name specified in uri_string is not valid. -or-<or>The host or authority name specified in uri_string cannot be terminated by backslashes. -or- The port number specified in uri_string is not valid or cannot be parsed. -or- The length of uri_string exceeds 65519 characters. -or- The length of the scheme specified in uri_string exceeds 1023 characters. -or- There is an invalid character sequence in uri_string. -or- The MS-DOS path specified in uri_string must start with c:\.

Examples

The following example creates a xtd::uri instance with the URI http://www.contoso.com/.

auto my_uri = uri("http://www.contoso.com/");

Remarks

This constructor creates a xtd::uri instance from a URI string. It parses the URI, puts it in canonical format, and makes any required escape encodings.

This constructor does not ensure that the xtd::uri refers to an accessible resource.

This constructor assumes that the string parameter references an absolute URI and is equivalent to calling the xtd::uri constructor with xtd::uri_kind set to xtd::uri_kind::absolute. If the string parameter passed to the constructor is a relative URI, this constructor will throw a xtd::uri_format_exception.

uri() [3/5]

xtd::uri::uri	(	const xtd::ustring &	uri,
		xtd::uri_kind	uri_kind
	)

Initializes a new instance of the xtd::uri class with the specified URI. This constructor allows you to specify if the URI string is a relative URI, absolute URI, or is indeterminate.

Parameters

uri_string	: A string that identifies the resource to be represented by the xtd::uri instance. Note that an IPv6 address in string form must be enclosed within brackets. For example, "http://[2607:f8b0:400d:c06::69]".
uri_kind	: Specifies whether the URI string is a relative URI, absolute URI, or is indeterminate.

Exceptions

xtd::uri_format_exception

uri_string contains a relative URI and uri_kind is xtd::uri_kind::absolute. -or- uri_string contains an absolute URI and uri_kind is xtd::uri_kind::relative. -or- uri_string is empty. -or- The scheme specified in uri_string is not correctly formed. See CheckSchemeName(String). -or- uri_string contains too many slashes. -or- The password specified in uri_string is not valid. -or- The host name specified in uri_string is not valid. -or- The file name specified in uri_string is not valid. -or- The user name specified in uri_string is not valid. -or- The host or authority name specified in uri_string cannot be terminated by backslashes. -or- The port number specified in uri_string is not valid or cannot be parsed. -or- The length of uri_string exceeds 65519 characters. -or- The length of the scheme specified in uri_string exceeds 1023 characters. -or- There is an invalid character sequence in uri_string. -or- The MS-DOS path specified in uri_string must start with c:\.

Remarks

Relative and absolute URIs have different restrictions on their format. For example, a relative URI does not require a scheme or an authority. The value you specify in uri_kind must match the type of URI passed in uri_string. However, if xtd::uri::relative_orA_asolute is specified, the URI string can be relative or absolute.

uri() [4/5]

xtd::uri::uri	(	const uri &	base_uri,
		const xtd::ustring &	relative_uri
	)

Initializes a new instance of the xtd::uri class based on the specified base URI and relative URI string.

Parameters

base_uri	: The base URI.
relative_uri	: The relative URI to add to the base URI.

Exceptions

xtd::uri_format_exception

The URI formed by combining base_uri and relative_uri is empty or contains only spaces. -or- The scheme specified in the URI formed by combining base_uri and relative_uri is not valid. -or- The URI formed by combining base_uri and relative_uri contains too many slashes. -or- The password specified in the URI formed by combining base_uri and relative_uri is not valid. -or- The host name specified in the URI formed by combining base_uri and relative_uri is not valid. -or- The file name specified in the URI formed by combining base_uri and relative_uri is not valid. -or- The user name specified in the URI formed by combining base_uri and relative_uri is not valid. -or- The host or authority name specified in the URI formed by combining base_uri and relative_uri cannot be terminated by backslashes. -or- The port number specified in the URI formed by combining base_uri and relative_uri is not valid or cannot be parsed. -or- The length of the URI formed by combining base_uri and relative_uri exceeds 65519 characters. -or- The length of the scheme specified in the URI formed by combining base_uri and relative_uri exceeds 1023 characters. -or- There is an invalid character sequence in the URI formed by combining base_uri and relative_uri. -or- The MS-DOS path specified in uriString must start with c:\.

Examples

The following example creates a new instance of the xtd::uri class by combining the relative URIs http://www.contoso.com and catalog/shownew.htm to form the absolute URI http://www.contoso.com/catalog/shownew.htm.

auto base_uri = uri("http://www.contoso.com");
auto my_uri = uri(base_uri, "catalog/shownew.htm");
 
console::write_line(my_uri.to_string());

Remarks

This constructor creates a xtd::uri instance by combining the base_uri and the relative_uri. If relative_uri is an absolute URI (containing a scheme, host name, and optionally a port number), the xtd::uri instance is created using only relative_uri.

If the base_uri has relative parts (like /api), then the relative part must be terminated with a slash, (like /api/), if the relative part of base_uri is to be preserved in the constructed xtd::uri.

Additionally, if the relative_uri begins with a slash, then it will replace any relative part of the base_uri

This constructor does not ensure that the xtd::uri refers to an accessible resource.

uri() [5/5]

xtd::uri::uri	(	const uri &	base_uri,
		const uri &	relative_uri
	)

Initializes a new instance of the xtd::uri class based on the combination of a specified base xtd::uri instance and a relative xtd::uri instance.

Parameters

base_uri	: An absolute xtd::uri that is the base for the new xtd::uri instance.
relative_uri	: A relative xtd::uri instance that is combined with base_uri.

Exceptions

xtd::uri_format_exception

The URI formed by combining base_uri and relative_uri is empty or contains only spaces. -or- The scheme specified in the URI formed by combining base_uri and relative_uri is not valid. -or- The URI formed by combining base_uri and relative_uri contains too many slashes. -or- The password specified in the URI formed by combining base_uri and relative_uri is not valid. -or- The host name specified in the URI formed by combining base_uri and relative_uri is not valid. -or- The file name specified in the URI formed by combining base_uri and relative_uri is not valid. -or- The user name specified in the URI formed by combining base_uri and relative_uri is not valid. -or- The host or authority name specified in the URI formed by combining base_uri and relative_uri cannot be terminated by backslashes. -or- The port number specified in the URI formed by combining base_uri and relative_uri is not valid or cannot be parsed. -or- The length of the URI formed by combining base_uri and relative_uri exceeds 65519 characters. -or- The length of the scheme specified in the URI formed by combining base_uri and relative_uri exceeds 1023 characters. -or- There is an invalid character sequence in the URI formed by combining base_uri and relative_uri. -or- The MS-DOS path specified in uriString must start with c:\.

Examples

This example creates an absolute xtd::uri instance, absolute_uri, and a relative xtd::uri instance, relative_uri. A new xtd::uri instance, combined_uri, is then created from these two instances.

// Create an absolute xtd::ri from a string.
auti absolute_uri = uri("http://www.contoso.com/");
 
// Create a relative xtd::uri from a string and uri_kind::relative for
// creating a relative xtd::uri.
auto relative_uri = uri("/catalog/shownew.htm?date=today", uri_kind::relative);
 
// Check whether the new xtd::uri is absolute or relative.
if (!relative_uri.is_absolute_uri())
  console::write_line("{0} is a relative xtd::uri.", relative_uri);
 
// Create a new xtd::uri from an absolute xtd::uri and a relative xtd::uri.
auto combined_uri = uri(absolute_uri, relative_uri);
console::write_line(combined_uri.absolute_uri());

Remarks

This constructor creates a new xtd::uri instance by combining an absolute xtd::uri instance, base_uri, with a relative xtd::uri instance, relative_uri. If relative_uri is an absolute xtd::uri instance (containing a scheme, host name, and optionally a port number), the xtd::uri instance is created using only relative_uri.

If the base_uri has relative parts (like /api), then the relative part must be terminated with a slash, (like /api/), if the relative part of base_uri is to be preserved in the constructed xtd::uri.

Additionally, if the relative_uri begins with a slash, then it will replace any relative part of the base_uri

This constructor does not ensure that the xtd::uri refers to an accessible resource.

Member Function Documentation

absolute_path()

xtd::ustring xtd::uri::absolute_path

(

)

const

Gets the absolute path of the URI.

Returns

The absolute path to the resource.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Examples

The following example writes the path /catalog/shownew.htm to the console.

auto base_uri = uri("http://www.contoso.com/");
auto my_uri = uri(base_uri, "catalog/shownew.htm?date=today");
 
console::write_line(my_uri.absolute_path());

Remarks

The xtd::uri::absolute_path property contains the path information that the server uses to resolve requests for information. Typically this is the path to the desired information on the server's file system, although it also can indicate the application or script the server must run to provide the information.

The path information does not include the scheme, host name, or query portion of the URI.

absolute_uri()

xtd::ustring xtd::uri::absolute_uri

(

)

Gets the absolute URI.

Returns

The entire URI.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Examples

The following example writes the complete contents of the xtd::uri instance to the console. In the example shown, http://www.contoso.com/catalog/shownew.htm?date=today is written to the console.

auto base_uri = uri("http://www.contoso.com");
auto my_uri = uri(base_uri,"catalog/shownew.htm?date=today");
console::write_line(my_uri.absolute_uri());

Remarks

The xtd::uri::absolute_uri property includes the entire URI stored in the xtd::uri instance, including all fragments and query strings.

authority()

xtd::ustring xtd::uri::authority

(

)

const

Gets the Domain Name System (DNS) host name or IP address and the port number for a server.

Returns

The authority component of the URI represented by this instance.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Examples

The following example writes the host name (www.contoso.com) and port number (8080) of the server to the console.

auto base_uri = uri("http://www.contoso.com:8080/");
auto my_uri = uri(base_uri,"shownew.htm?date=today");
 
console::write_line(my_uri.authority());

Remarks

The xtd::uri::authority property is typically a server DNS host name or IP address. This property might include the service port number if it differs from the default port for the URI. If the xtd::uri::authority component contains reserved characters, these are escaped in the string value returned by this property.

check_scheme_name()

static bool xtd::uri::check_scheme_name ( const xtd::ustring &  scheme )

static

Determines whether the specified scheme name is valid.

Parameters

scheme

The scheme name to validate.

Returns

bool A bool value that is true if the scheme name is valid; otherwise, false.

Remarks

This method checks the scheme name for validity according to RFC 2396 by default. If International Resource Identifiers (IRIs) or Internationalized Domain Name (IDN) parsing is enabled, this method checks the scheme name for validity according to RFC 3986. The scheme name must begin with a letter and must contain only letters, digits, and the characters ".", "+", or "-".

For more information on URI support, see the Remarks section for the xtd::uri class.

dns_safe_host()

xtd::ustring xtd::uri::dns_safe_host

(

)

const

Gets an unescaped host name that is safe to use for DNS resolution.

Returns

The host part of the URI in a format suitable for DNS resolution; or the original host string, if it is already suitable for resolution.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Examples

The following example creates a xtd::uri instance from a string. It illustrates the difference between the value returned from xtd::uri::host, which returns the host name or address specified in the URI, and the value returned from xtd::uri::dns_safe_host, which returns an address that is safe to use in DNS resolution.

// Create new Uri using a string address.
auto address = uri("http://[fe80::200:39ff:fe36:1a2d%254]/temp/example.htm");
 
// Make the address DNS safe.
 
// The following outputs "[fe80::200:39ff:fe36:1a2d]".
console::write_line(address.host());
 
// The following outputs "fe80::200:39ff:fe36:1a2d%254".
console::write_line(address.dns_safe_host());

As explained in Remarks, unescape the host name before resolving it. You can use the xtd::uri::unescape_data_string method to unescape the host name, and you can resolve it by calling the xtd::uri::get_host_entry method.

Remarks

For IPv6 addresses, the brackets ([]) are removed and the xtd::uri::scope_id property is set, if one was specified when this instance was constructed.

equals()

bool xtd::uri::equals ( const xtd::uri &  ) const

overridevirtualnoexcept

Indicates whether the current object is equal to another object of the same type.

Parameters

obj	An object to compare with this object.

Returns

true if the current object is equal to the other parameter; otherwise, false.

Implements xtd::iequatable< uri >.

escape_data_string()

static xtd::ustring xtd::uri::escape_data_string ( const xtd::ustring &  value )

static

Converts a string to its escaped representation.

Parameters

value

The string to escape.

Returns

string A string that contains the escaped representation of stringToEscape.

Exceptions

ArgumentNullException	value is null.
UriFormatException	The length of value exceeds 32766 characters.

Remarks

By default, the escape_data_string method converts all characters except for RFC 2396 unreserved characters to their hexadecimal representation. If International Resource Identifiers (IRIs) or Internationalized Domain Name (IDN) parsing is enabled, the escape_data_string method converts all characters, except for RFC 3986 unreserved characters, to their hexadecimal representation. All Unicode characters are converted to UTF-8 format before being escaped.

This method assumes that stringToEscape has no escape sequences in it.

By default, the string is escaped according to RFC 2396. If International Resource Identifiers (IRIs) or Internationalized Domain Name (IDN) parsing is enabled, the string is escaped according to RFC 3986 and RFC 3987. See these RFCs for a definition of reserved and unreserved characters.

For more information on URI support, see the Remarks section for the xtd::uri class.

escape_uri_string()

static xtd::ustring xtd::uri::escape_uri_string ( const xtd::ustring &  value )

static

Converts a URI string to its escaped representation.

Parameters

value

The string to escape.

Returns

string A string that contains the escaped representation of stringToEscape.

Exceptions

ArgumentNullException	value is null.
UriFormatException	The length of value exceeds 32766 characters.

Remarks

Use the escape_uri_string method to prepare an unescaped URI string to be a parameter to the xtd::uri constructor.

By default, the escape_uri_string method converts all characters, except RFC 2396 unreserved characters, to their hexadecimal representation. If International Resource Identifiers (IRIs) or Internationalized Domain Name (IDN) parsing is enabled, the escape_uri_string method converts all characters, except for RFC 3986 unreserved characters, to their hexadecimal representation. All Unicode characters are converted to UTF-8 format before being escaped.

This method assumes that stringToEscape has no escape sequences in it.

By default, the string is escaped according to RFC 2396. If International Resource Identifiers (IRIs) or Internationalized Domain Name (IDN) parsing is enabled, the string is escaped according to RFC 3986 and RFC 3987. See these RFCs for a definition of reserved and unreserved characters.

For more information on URI support, see the Remarks section for the xtd::uri class.

fragment()

xtd::ustring xtd::uri::fragment

(

)

const

Gets the escaped URI fragment.

Returns

string A string that contains any URI fragment information.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

The fragment property gets any text following a fragment marker (#) in the URI, including the fragment marker itself. Given the URI http://www.contoso.com/index.htm#main, the fragment property would return #main.

The fragment property is not considered in any equals comparison.

from_hex()

static int32 xtd::uri::from_hex ( char  digit )

static

Gets the decimal value of a hexadecimal digit.

Parameters

digit

The hexadecimal digit (0-9, a-f, A-F) to convert.

Returns

int32 An int32 value that contains a number from 0 to 15 that corresponds to the specified hexadecimal digit.

Exceptions

ArgumentException

digit is not a valid hexadecimal digit (0-9, a-f, A-F).

Remarks

The from_hex method converts a character representing a hexadecimal digit (0-9, a-f, A-F) to its decimal value (0 to 15). If digit is not a valid hexadecimal digit, an ArgumentException exception is thrown.

get_components()

xtd::ustring xtd::uri::get_components	(	xtd::uri_components	components,
		xtd::uri_format	format
	)		const

Gets the specified components of the current instance using the specified escaping for special characters.

Parameters

components	A bitwise combination of the xtd::uri_components values that specifies which parts of the current instance to return to the caller.
format	One of the xtd::uri_format values that controls how special characters are escaped.

Returns

string A string that contains the components.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

When query or fragment is specified alone, the return value includes the delimiter. The scheme, user_info, host, port, and Path components do not include the delimiter. For all other xtd::uri_components values, and combinations of values, the delimiters are included in the returned value.

The components are returned in the order that they appear in the URI. For example, if scheme is specified, it appears first.

When International Resource Identifier (URI) and Internationalized Domain Name (IDN) support are enabled, the number of characters returned in the string increases. Punycode names used to support URI contain only ASCII characters and always start with the xn– prefix. When URI and IDN are enabled, Unicode surrogate characters are handled correctly by the get_components method.

For more information on URI support, see the Remarks section for the xtd::uri class.

get_left_part()

xtd::ustring xtd::uri::get_left_part

(

xtd::uri_partial

part

)

const

Gets the specified portion of a xtd::uri instance.

Parameters

part	= One of the xtd::uri_partial values that specifies the end of the URI portion to return.

Returns

string A string that contains the specified portion of the xtd::uri instance.

Exceptions

xtd::invalid_operation_exception	This instance represents a relative URI, and this property is valid only for absolute URIs.
ArgumentException	The specified part is not valid.

Remarks

The get_left_part method returns a string containing the leftmost portion of the URI string, ending with the portion specified by part.

get_left_part includes delimiters in the following cases:

* scheme includes the scheme delimiter.

* authority does not include the path delimiter.

* Path includes any delimiters in the original URI up to the query or fragment delimiter.

* query includes the Path, plus the query and its delimiter.

The following examples show a URI and the results of calling get_left_part with scheme, authority, Path, or query.

URI	Scheme	Autority	Path	Query
http://www.contoso.com/index.htm?date=today	http://	http://www.contoso.com	http://www.contoso.com/index.htm	http://www.contoso.com/index.htm?date=today
http://www.contoso.com/index.htm#main	http://	http://www.contoso.com	http://www.contoso.com/index.htm	http://www.contoso.com/index.htm
user@.nosp@m.cont.nosp@m.oso.c.nosp@m.om?subject=uri	mailto:	user@.nosp@m.cont.nosp@m.oso.c.nosp@m.om	user@.nosp@m.cont.nosp@m.oso.c.nosp@m.om?subject=uri	<None>
nntp://news.contoso.com/123456@contoso.com	nntp://	nntp://news.contoso.com	nntp://news.contoso.com/123456@contoso.com	nntp://news.contoso.com/123456@contoso.com
news:123456@contoso.com	news:	news:123456@contoso.com	news:123456@contoso.com	<None>
file://server/filename.ext	file://	file://server	file://server/filename.ext	file://server/filename.ext

hex_escape()

static xtd::ustring xtd::uri::hex_escape ( char  character )

static

Converts a specified character into its hexadecimal equivalent.

Parameters

character

The character to convert to hexadecimal representation.

Returns

string The hexadecimal representation of the specified character.

Exceptions

ArgumentOutOfRangeException

character is greater than 255.

hex_unescape()

static char xtd::uri::hex_unescape ( const xtd::ustring &  pattern, size_t &  index  )

static

Converts a specified hexadecimal representation of a character to the character.

Parameters

pattern	The hexadecimal representation of a character.
index	The location in pattern where the hexadecimal representation of a character begins.

Returns

Char The character represented by the hexadecimal encoding at position index. If the character at index is not hexadecimal encoded, the character at index is returned. The value of index is incremented to point to the character following the one returned.

Exceptions

ArgumentOutOfRangeException

index is less than 0 or greater than or equal to the number of characters in pattern.

host()

xtd::ustring xtd::uri::host

(

)

const

Gets the host component of this instance.

Returns

string A string that contains the host name. This is usually the DNS host name or IP address of the server.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

Unlike the authority property, this property value does not include the port number.

host_name_type()

xtd::uri_host_name_type xtd::uri::host_name_type

(

)

const

Gets the type of the host name specified in the URI.

Returns

xtd::uri_host_name_type A member of the xtd::uri_host_name_type enumeration.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

idn_host()

xtd::ustring xtd::uri::idn_host

(

)

const

Gets the RFC 3490 compliant International Domain Name of the host, using Punycode as appropriate. This string, after being unescaped if necessary, is safe to use for DNS resolution.

Returns

The hostname, formatted with Punycode according to the IDN standard.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

This property is provided for the use of lower-level networking protocols that require the domain name in Punycode form. If your code does not require that specific format, use xtd::uri::host for the hostname.

The deprecated xtd::uri::dns_safe_host property is dependent on app.config settings, which cannot be changed by Windows Store applications. xtd::uri::idn_host is provided as the preferred alternative to using xtd::uri::dns_safe_host, because xtd::uri::idn_host is guaranteed to always be DNS safe, no matter what the current app.config settings might be.

If you used an escaped string to construct this instance (for example, "http://[fe80::200:39ff:fe36:1a2d%254]/temp/example.htm"), then xtd::uri::idn_host returns an escaped string. You should unescape any escaped string returned from IdnHost before using that string for DNS resolution. Be aware that if you used an invalid unescaped string to construct this instance (for example, "http://[fe80::200:39ff:fe36:1a2d%4]/temp/example.htm"), then IdnHost returns an unescaped string.

is_absolute_uri()

bool xtd::uri::is_absolute_uri

(

)

const

Gets whether the xtd::uri instance is absolute.

Returns

bool A bool value that is true if the xtd::uri instance is absolute; otherwise, false.

Remarks

This property is true if the string or xtd::uri instance that was passed into the constructor can be parsed as an absolute xtd::uri instance, which contains a scheme, an authority, and a path. Otherwise, the xtd::uri instance is treated as relative and might omit the scheme or other URI components.

is_base_of()

bool xtd::uri::is_base_of

(

const xtd::uri &

uri

)

const

Determines whether the current xtd::uri instance is a base of the specified xtd::uri instance.

Parameters

uri	The specified xtd::uri instance to test.

Returns

bool true if the current xtd::uri instance is a base of uri; otherwise, false.

Exceptions

ArgumentNullException

uri is null.

Remarks

IsBaseOf is used to compare the current xtd::uri instance to a specified xtd::uri to determine whether this URI is a base for the specified xtd::uri. When comparing two xtd::uri objects to determine a base relationship, the user information (user_info) is not evaluated. When comparing two URIs (uri1 and uri2), uri1 is the base of uri2 if, when you ignore everything in uri2 after the last slash (/), the two URIs are identical. Using http://host/path/path/file?query as the base URI, the following table shows whether it is a base for other URIs.

URI	http://host/path/path/file?query is base of
http://host/path/path/file/	yes
http://host/path/path/#fragment	yes
http://host/path/path/MoreDir/"	yes
http://host/path/path/OtherFile?Query	yes
http://host/path/path/	yes
http://host/path/path/file	yes
http://host/path/path	no
http://host/path/path?query	no
http://host/path/path#fragment	no
http://host/path/path2/	no
http://host/path/path2/MoreDir	no
http://host/path/File	no

is_default_port()

bool xtd::uri::is_default_port

(

)

const

Gets whether the port value of the URI is the default for this scheme.

Returns

bool A bool value that is true if the value in the port property is the default port for this scheme; otherwise, false.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

is_file()

bool xtd::uri::is_file

(

)

const

Gets a value indicating whether the specified xtd::uri is a file URI.

Returns

bool A bool value that is true if the xtd::uri is a file URI; otherwise, false.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

The is_file property is true when the scheme property equals uri_scheme_file.

is_hex_digit()

static bool xtd::uri::is_hex_digit ( char  character )

static

Determines whether a specified character is a valid hexadecimal digit.

Parameters

character

The character to validate.

Returns

bool A bool value that is true if the character is a valid hexadecimal digit; otherwise false.

Remarks

Hexadecimal digits are the digits 0 to 9 and the letters A-F or a-f.

is_hex_encoding()

static bool xtd::uri::is_hex_encoding ( const xtd::ustring &  pattern, size_t  index  )

static

Determines whether a character in a string is hexadecimal encoded.

Parameters

pattern	The string to check.
index	The location in pattern to check for hexadecimal encoding.

Returns

bool A bool value that is true if pattern is hexadecimal encoded at the specified location; otherwise, false.

Remarks

The is_hex_encoding method checks for hexadecimal encoding that follows the pattern "%hexhex" in a string, where "hex" is a digit from 0 to 9 or a letter from A-F (case-insensitive).

is_loopback()

bool xtd::uri::is_loopback

(

)

const

Gets whether the specified xtd::uri references the local host.

Returns

bool A bool value that is true if this xtd::uri references the local host; otherwise, false.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

is_loopback returns true if the URI specified when this instance was created was 127.0.0.1, loopback, or localhost, or if the URI did not specify host information (for example, file:///c:Dir/file.txt). All other URIs return false.

is_unc()

bool xtd::uri::is_unc

(

)

const

Gets whether the specified xtd::uri is a universal naming convention (UNC) path.

Returns

bool A bool value that is true if the xtd::uri is a UNC path; otherwise, false.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

The is_unc property is true if the specified xtd::uri instance is a UNC path (such as \server\folder or file://server/folder). This property always returns true if the URI has the file:// scheme and specifies a host component.

is_well_formed_original_string()

bool xtd::uri::is_well_formed_original_string

(

)

Indicates whether the string used to construct this xtd::uri was well-formed and is not required to be further escaped.

Returns

bool A bool value that is true if the string was well-formed; else false.

Remarks

The string is considered to be well-formed in accordance with RFC 2396 and RFC 2732 by default. If International Resource Identifiers (IRIs) or Internationalized Domain Name (IDN) parsing is enabled, the string is considered to be well-formed in accordance with RFC 3986 and RFC 3987

The string is considered poorly formed, causing the method to return false, if any of the following conditions occur.

Error	Example
The string is not correctly escaped.	http://www.contoso.com/path???/file name
The string is an absolute xtd::uri that represents an implicit file xtd::uri.	c:\directory\filename
The string is an absolute URI that is missing a slash before the path.	file://c:/directory/filename
The string contains unescaped backslashes even if they are treated as forward slashes.	http:\host/path/file
The string represents a hierarchical absolute xtd::uri and does not contain "://".	www.contoso.com/path/file
The parser for the xtd::uri.scheme indicates that the original string was not well-formed.	The example depends on the scheme of the URI.

By default, the string used to construct this xtd::uri are considered well-formed in accordance with RFC 2396 and RFC 2732.

When International Resource Identifier (URI) and Internationalized Domain Name (IDN) support are enabled, the string used to construct this xtd::uri are considered well-formed in accordance with RFC 3986 and RFC 3987. Punycode names used to support URI contain only ASCII characters and always start with the xn– prefix.

For more information on URI support, see the Remarks section for the xtd::uri class.

is_well_formed_uri_string()

static bool xtd::uri::is_well_formed_uri_string ( const xtd::ustring &  uri_string, xtd::uri_kind  uri_kind  )

static

Indicates whether the string is well-formed by attempting to construct a URI with the string and ensures that the string does not require further escaping.

Parameters

uri_string	The string used to attempt to construct a xtd::uri.
uri_kind	The type of the xtd::uri in uri_string.

Returns

bool A bool value that is true if the string was well-formed; else false.

Remarks

By default, the string is considered well-formed in accordance with RFC 2396 and RFC 2732. If International Resource Identifiers (IRIs) or Internationalized Domain Name (IDN) parsing is enabled, the string is considered well-formed in accordance with RFC 3986 and RFC 3987.

The string is considered poorly formed, causing the method to return false, if any of the following conditions occur

Error	Example
The string is not correctly escaped.	http://www.contoso.com/path???/file name
The string is an absolute xtd::uri that represents an implicit file xtd::uri.	c:\directory\filename
The string is an absolute URI that is missing a slash before the path.	file://c:/directory/filename
The string contains unescaped backslashes even if they are treated as forward slashes.	http:\host/path/file
The string represents a hierarchical absolute xtd::uri and does not contain "://".	www.contoso.com/path/file
The parser for the xtd::uri.scheme indicates that the original string was not well-formed.	The example depends on the scheme of the URI.

For more information on URI support, see the Remarks section for the xtd::uri class.

local_path()

xtd::ustring xtd::uri::local_path

(

)

const

Gets the original URI string that was passed to the xtd::uri constructor.

Returns

string A string containing the exact URI specified when this instance was constructed; otherwise, Empty.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

If the URI specified to the constructor contained leading or trailing spaces, these spaces are preserved.

The value returned by this property differs from to_string and absolute_uri. to_string returns the canonically unescaped form of the URI. absolute_uri returns the canonically escaped form of the URI.

When International Resource Identifier (URI) and Internationalized Domain Name (IDN) support are enabled, original_string returns the original non normalized string with Punycode host name if one was used to initialize the xtd::uri instance. Punycode names contain only ASCII characters and always start with the xn– prefix.

For more information on URI support, see the Remarks section for the xtd::uri class.

When a xtd::uri object is serialized, the original_string is not preserved. The serialization process uses the fully escaped and canonicalized absolute_uri property when serializing. For a xtd::uri that contains an IPv6 address, the IPv6 address and the scope ID are included in the serialized xtd::uri object.

original_string()

const xtd::ustring & xtd::uri::original_string

(

)

const

Gets the original URI string that was passed to the xtd::uri constructor.

Returns

string A string containing the exact URI specified when this instance was constructed; otherwise, Empty.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

If the URI specified to the constructor contained leading or trailing spaces, these spaces are preserved.

The value returned by this property differs from to_string and absolute_uri. to_string returns the canonically unescaped form of the URI. absolute_uri returns the canonically escaped form of the URI.

When International Resource Identifier (URI) and Internationalized Domain Name (IDN) support are enabled, original_string returns the original non normalized string with Punycode host name if one was used to initialize the xtd::uri instance. Punycode names contain only ASCII characters and always start with the xn– prefix.

For more information on URI support, see the Remarks section for the xtd::uri class.

When a xtd::uri object is serialized, the original_string is not preserved. The serialization process uses the fully escaped and canonicalized absolute_uri property when serializing. For a xtd::uri that contains an IPv6 address, the IPv6 address and the scope ID are included in the serialized xtd::uri object.

path_and_query()

xtd::ustring xtd::uri::path_and_query

(

)

const

Gets the absolute_path and query properties separated by a question mark (?).

Returns

string A string that contains the absolute_path and query properties separated by a question mark (?).

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

The path_and_query property contains the absolute path on the server and the query information sent with the request. It is identical to concatenating the absolute_path and query properties.

The path_and_query property is escaped according to RFC 2396 by default. If International Resource Identifiers (IRIs) or Internationalized Domain Name (IDN) parsing is enabled, the path_and_query property is escaped according to RFC 3986 and RFC 3987.

For more information on URI support, see the Remarks section for the xtd::uri class.

port()

int32 xtd::uri::port

(

)

const

Gets the port number of this URI.

Returns

int32 An int32 value that contains the port number for this URI.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

The port number defines the protocol port used for contacting the server referenced in the URI. If a port is not specified as part of the URI, the port property returns the default value for the protocol. If there is no default port number, this property returns -1.

query()

xtd::ustring xtd::uri::query

(

)

const

Gets any query information included in the specified URI.

Returns

string A string that contains any query information included in the specified URI.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

The query property contains any query information included in the URI. query information is separated from the path information by a question mark (?) and continues to the end of the URI. The query information returned includes the leading question mark.

The query information is escaped according to RFC 2396 by default. If International Resource Identifiers (IRIs) or Internationalized Domain Name (IDN) parsing is enabled, the query information is escaped according to RFC 3986 and RFC 3987.

For more information on URI support, see the Remarks section for the xtd::uri class.

scheme()

xtd::ustring xtd::uri::scheme

(

)

const

Gets the scheme name for this URI.

Returns

string A string that contains the scheme for this URI, converted to lowercase.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

The scheme property returns the scheme used to initialize the xtd::uri instance. This property does not indicate that the scheme used to initialize the xtd::uri instance was recognized.

The following table shows examples of some possible values returned by the scheme property.

Scheme	Description
file	The resource is a file on the local computer.
ftp	The resource is accessed through FTP.
gopher	The resource is accessed through the Gopher protocol.
http	The resource is accessed through HTTP.
https	The resource is accessed through SSL-encrypted HTTP.
ldap	The resource is accessed through the LDAP protocol.
mailto	The resource is an e-mail address and accessed through the SMTP protocol.
net.pipe	The resource is accessed through a named pipe.
net.tcp	The resource is accessed from TCP endpoint.
news	The resource is accessed through the NNTP protocol.
nntp	The resource is accessed through the NNTP protocol.
telnet	The resource is accessed through the TELNET protocol.
uuid	The resource is accessed through a unique UUID endpoint name for communicating with a service.

segments()

std::vector< xtd::ustring > xtd::uri::segments

(

)

const

Gets an array containing the path segments that make up the specified URI.

Returns

Array<Srtring> A string array that contains the path segments that make up the specified URI.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

The segments property returns an array of strings containing the "segments" (substrings) that form the URI's absolute path. The first segment is obtained by parsing the absolute path from its first character until you reach a slash (/) or the end of the path. Each additional segment begins at the first character after the preceding segment, and terminates with the next slash or the end of the path. (A URI's absolute path contains everything after the host and port and before the query and fragment.)

The following example shows the absolute path and segments for two URIs. The second example illustrates that the fragment and query are not part of the absolute path and therefore are not segments.

Absolute URI

http://www.contoso.com/Chapters/Chapter1/Sections/Section1.htm

Absolute path

/Chapters/Chapter1/Sections/Section1.htm

segments

/Chapters/Chapter1/Sections/Section1.htm

Absolute URI

http://www.contoso.com/Chapters/Chapter1/Sections/Section1.htm#page1?answer=NO

Absolute path

/Chapters/Chapter1/Sections/Section1.htm

segments

/Chapters/Chapter1/Sections/Section1.htm

Note that because the absolute path starts with a '/', the first segment contains it and nothing else.

to_string()

xtd::ustring xtd::uri::to_string ( ) const

overridevirtualnoexcept

Gets a canonical string representation for the specified xtd::uri instance.

Returns

string A string instance that contains the unescaped canonical representation of the xtd::uri instance. All characters are unescaped except #, ?, and %.

Remarks

The string returned by this method does not contain port information when the port is the default port for the scheme.

Reimplemented from xtd::object.

unescape_data_string()

static xtd::ustring xtd::uri::unescape_data_string ( const xtd::ustring &  value )

static

Converts a string to its unescaped representation.

Parameters

value

The string to unescape.

Returns

string A string that contains the unescaped representation of stringToUnescape.

Exceptions

ArgumentNullException

value is null.

Remarks

You should use this method with care. Unescaping a string that has been previously unescaped can lead to ambiguities and errors.

Many Web browsers escape spaces inside of URIs into plus ("+") characters; however, the unescape_data_string method does not convert plus characters into spaces because this behavior is not standard across all URI schemes.

user_info()

xtd::ustring xtd::uri::user_info

(

)

const

Gets the user name, password, or other user-specific information associated with the specified URI.

Returns

string A string that contains the user information associated with the URI. The returned value does not include the '@' character reserved for delimiting the user information part of the URI.

Exceptions

xtd::invalid_operation_exception

This instance represents a relative URI, and this property is valid only for absolute URIs.

Remarks

The value returned by this property is usually in the format "userName:password".

Member Data Documentation

scheme_delimiter

const xtd::ustring xtd::uri::scheme_delimiter

inlinestatic

Specifies the characters that separate the communication protocol scheme from the address portion of the URI. This field is read-only.

Examples

The following example creates a string from xtd::uri::uri_scheme_http, xtd::uri::scheme_delimiter, and an address. A xtd::uri instance is then created from the string.

ustring address = "www.contoso.com";
ustring uri_string = ustring::format("{0}{1}{2}/", uri::uri_scheme_http, uri::scheme_delimiter, address);
uri result(uri_string);
if (result.is_well_formed_original_string())
  console::write_line("{0} is a well formed uri", uri_string);
else
  console::write_line("{0} is not a well formed uri", uri_string);

uri_scheme_file

const xtd::ustring xtd::uri::uri_scheme_file

inlinestatic

Specifies that the URI is a pointer to a file. This field is read-only.

Examples

The following example creates a xtd::uri instance and determines whether the scheme is xtd::uri::uri_scheme_file.

uri address2("file://server/filename.ext");
if (address2.scheme() == uri::uri_scheme_file)
  console::write_line("uri is a file");

uri_scheme_ftp

const xtd::ustring xtd::uri::uri_scheme_ftp

inlinestatic

Specifies that the URI is accessed through the File Transfer Protocol (FTP). This field is read-only.

Examples

The following example creates a xtd::uri instance and determines whether the scheme is xtd::uri::uri_scheme_ftp.

uri address7("ftp://contoso/files/testfile.txt");
if (address7.scheme() == uri::uri_scheme_ftp)
  console::write_line("uri is ftp protocol");

uri_scheme_gopher

const xtd::ustring xtd::uri::uri_scheme_gopher

inlinestatic

Specifies that the URI is accessed through the Gopher protocol. This field is read-only.

Examples

The following example creates a xtd::uri instance and determines whether the scheme is xtd::uri::uri_scheme_gopher.

uri address6("gopher://example.contoso.com/");
if (address6.scheme() == uri::uri_scheme_gopher)
  console::write_line("uri is gopher protocol");

uri_scheme_http

const xtd::ustring xtd::uri::uri_scheme_http

inlinestatic

Specifies that the URI is accessed through the Hypertext Transfer Protocol (HTTP). This field is read-only.

Examples

The following example creates a xtd::uri instance and determines whether the scheme is xtd::uri::uri_scheme_http.

uri address1("http://www.contoso.com/index.htm#search");
console::write_line("address 1 {0} a valid scheme name",
                    uri::check_scheme_name(address1.scheme()) ? " has" : " does not have");
 
if (address1.scheme == uri::uri_scheme_http)
  console::write_line("uri is HTTP type");
 
console::write_line(address1.host_name_type());

uri_scheme_https

const xtd::ustring xtd::uri::uri_scheme_https

inlinestatic

Specifies that the URI is accessed through the Hypertext Transfer Protocol (HTTPS). This field is read-only.

Examples

The following example creates a xtd::uri instance and determines whether the scheme is xtd::uri::uri_scheme_https.

uri address8("https://example.contoso.com");
if (address8.scheme() == uri::uri_scheme_https)
  console::write_line("uri is HTTPS protocol.");

uri_scheme_mailto

const xtd::ustring xtd::uri::uri_scheme_mailto

inlinestatic

Specifies that the URI is an e-mail address and is accessed through the Simple Mail Transport Protocol (SMTP). This field is read-only.

Examples

The following example creates a xtd::uri instance and determines whether the scheme is xtd::uri::uri_scheme_mailto.

uri address3("mailto:user@contoso.com?subject=uri");
if (address3.scheme() == uri::uri_scheme_mailto)
  console::write_line("uri is an email address");

uri_scheme_net_pipe

const xtd::ustring xtd::uri::uri_scheme_net_pipe

inlinestatic

Specifies that the URI is accessed through the NetPipe scheme used by Windows Communication Foundation (WCF). This field is read-only.

uri_scheme_net_tcp

const xtd::ustring xtd::uri::uri_scheme_net_tcp

inlinestatic

Specifies that the URI is accessed through the NetTcp scheme used by Windows Communication Foundation (WCF). This field is read-only.

uri_scheme_news

const xtd::ustring xtd::uri::uri_scheme_news

inlinestatic

Specifies that the URI is an Internet news group and is accessed through the Network News Transport Protocol (NNTP). This field is read-only.

Examples

The following example creates a xtd::uri instance and determines whether the scheme is xtd::uri::uri_scheme_news.

uri address4("news:123456@contoso.com");
if (address4.scheme() == uri::uri_scheme_news)
  console::write_line("uri is an Internet news group");

uri_scheme_nntp

const xtd::ustring xtd::uri::uri_scheme_nntp

inlinestatic

Specifies that the URI is an Internet news group and is accessed through the Network News Transport Protocol (NNTP). This field is read-only.

Examples

The following example creates a xtd::uri instance and determines whether the scheme is xtd::uri::uri_scheme_nntp.

Uri address5("nntp://news.contoso.com/123456@contoso.com");
if (address5.scheme() == uri::uri_scheme_nntp)
  console::write_line("uri is nntp protocol");

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/uri.h