xtd 0.2.0
Loading...
Searching...
No Matches
xtd::uri Class Reference
Inheritance diagram for xtd::uri:
xtd::iequatable< uri > xtd::object xtd::interface xtd::equality_operators< type_t, equatable_t >

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
Defines a generalized method that a value type or class implements to create a type-specific method f...
Definition iequatable.h:22
Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.h:42
Provides an object representation of a uniform resource identifier (URI) and easy access to the parts...
Definition uri.h:103
Inheritance
xtd::objectxtd::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("host_name_type: {}", uri.host_name_type());
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_loopback: {}", uri.is_loopback());
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("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
static basic_string join(const basic_string separator, const collection_t &values) noexcept
Concatenates a specified separator basic_string between each element of a specified object array,...
Definition basic_string.h:2296
static void write_line()
Writes the current line terminator to the standard output stream using the specified format informati...
xtd::string local_path() const
Gets the original URI string that was passed to the xtd::uri constructor.
bool is_absolute_uri() const
Gets whether the xtd::uri instance is absolute.
xtd::string dns_safe_host() const
Gets an unescaped host name that is safe to use for DNS resolution.
xtd::string user_info() const
Gets the user name, password, or other user-specific information associated with the specified URI.
bool is_loopback() const
Gets whether the specified xtd::uri references the local host.
xtd::string absolute_uri()
Gets the absolute URI.
xtd::string query() const
Gets any query information included in the specified URI.
xtd::string fragment() const
Gets the escaped URI fragment.
xtd::string absolute_path() const
Gets the absolute path of the URI.
xtd::string idn_host() const
Gets the RFC 3490 compliant International Domain Name of the host, using Punycode as appropriate....
xtd::string path_and_query() const
Gets the absolute_path and query properties separated by a question mark (?).
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.
xtd::string host() const
Gets the host component of this instance.
std::vector< xtd::string > segments() const
Gets an array containing the path segments that make up the specified URI.
xtd::string scheme() const
Gets the scheme name for this URI.
int32 port() const
Gets the port number of this URI.
const xtd::string & original_string() const
Gets the original URI string that was passed to the xtd::uri constructor.
bool is_unc() const
Gets whether the specified xtd::uri is a universal naming convention (UNC) path.
xtd::uri_host_name_type host_name_type() const
Gets the type of the host name specified in the URI.
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.h:175
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());
uri()=default
Initializes a new instance of the xtd::uri class.
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10
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:
string 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::string 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::string uri_scheme_file
 Specifies that the URI is a pointer to a file. This field is read-only.
 
static const xtd::string uri_scheme_ftp
 Specifies that the URI is accessed through the File Transfer Protocol (FTP). This field is read-only.
 
static const xtd::string uri_scheme_gopher
 Specifies that the URI is accessed through the Gopher protocol. This field is read-only.
 
static const xtd::string uri_scheme_http
 Specifies that the URI is accessed through the Hypertext Transfer Protocol (HTTP). This field is read-only.
 
static const xtd::string uri_scheme_https
 Specifies that the URI is accessed through the Hypertext Transfer Protocol (HTTPS). This field is read-only.
 
static const xtd::string 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::string 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::string 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::string 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::string 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::string &uri_string)
 Initializes a new instance of the xtd::uri class with the specified URI.
 
 uri (const xtd::string &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::string &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::string absolute_path () const
 Gets the absolute path of the URI.
 
xtd::string absolute_uri ()
 Gets the absolute URI.
 
xtd::string authority () const
 Gets the Domain Name System (DNS) host name or IP address and the port number for a server.
 
xtd::string dns_safe_host () const
 Gets an unescaped host name that is safe to use for DNS resolution.
 
xtd::string fragment () const
 Gets the escaped URI fragment.
 
xtd::string 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::string 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::string local_path () const
 Gets the original URI string that was passed to the xtd::uri constructor.
 
const xtd::stringoriginal_string () const
 Gets the original URI string that was passed to the xtd::uri constructor.
 
xtd::string 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::string query () const
 Gets any query information included in the specified URI.
 
xtd::string scheme () const
 Gets the scheme name for this URI.
 
std::vector< xtd::stringsegments () const
 Gets an array containing the path segments that make up the specified URI.
 
xtd::string user_info () const
 Gets the user name, password, or other user-specific information associated with the specified URI.
 

Public Methods

xtd::string 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::string 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::string to_string () const noexcept override
 Gets a canonical string representation for the specified xtd::uri instance.
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object.
 
static bool check_scheme_name (const xtd::string &scheme)
 Determines whether the specified scheme name is valid.
 
static xtd::string escape_data_string (const xtd::string &value)
 Converts a string to its escaped representation.
 
static xtd::string escape_uri_string (const xtd::string &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::string hex_escape (char character)
 Converts a specified character into its hexadecimal equivalent.
 
static char hex_unescape (const xtd::string &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::string &pattern, size_t index)
 Determines whether a character in a string is hexadecimal encoded.
 
static bool is_well_formed_uri_string (const xtd::string &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::string unescape_data_string (const xtd::string &value)
 Converts a string to its unescaped representation.
 
template<typename object_a_t , typename object_b_t >
static bool equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are considered equal.
 

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.
 
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 >
xtd::uptr< object_t > memberwise_clone () const
 Creates a shallow copy of the current object.
 
- Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename object_b_t >
static bool equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are considered equal.
 
template<typename object_a_t , typename object_b_t >
static bool reference_equals (const object_a_t &object_a, const object_b_t &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::string 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_exceptionuri_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::string 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_exceptionuri_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::string 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_exceptionThe 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_exceptionThe 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());
@ relative
The xtd::uri is a relative xtd::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::string xtd::uri::absolute_path ( ) const

Gets the absolute path of the URI.

Returns
The absolute path to the resource.
Exceptions
xtd::invalid_operation_exceptionThis 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::string xtd::uri::absolute_uri ( )

Gets the absolute URI.

Returns
The entire URI.
Exceptions
xtd::invalid_operation_exceptionThis 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::string 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_exceptionThis 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.

◆ dns_safe_host()

xtd::string 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_exceptionThis 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.

◆ fragment()

xtd::string xtd::uri::fragment ( ) const

Gets the escaped URI fragment.

Returns
string A string that contains any URI fragment information.
Exceptions
xtd::invalid_operation_exceptionThis 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.

◆ host()

xtd::string 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_exceptionThis 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_exceptionThis instance represents a relative URI, and this property is valid only for absolute URIs.

◆ idn_host()

xtd::string 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_exceptionThis 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_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_exceptionThis 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_exceptionThis 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_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_exceptionThis 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_exceptionThis 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.

◆ local_path()

xtd::string 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_exceptionThis 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::string & 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_exceptionThis 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::string 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_exceptionThis 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_exceptionThis 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::string 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_exceptionThis 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::string 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_exceptionThis 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::string > 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_exceptionThis 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.

◆ user_info()

xtd::string 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_exceptionThis 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".

◆ get_components()

xtd::string 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
componentsA bitwise combination of the xtd::uri_components values that specifies which parts of the current instance to return to the caller.
formatOne 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_exceptionThis 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::string 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_exceptionThis instance represents a relative URI, and this property is valid only for absolute URIs.
ArgumentExceptionThe 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

◆ 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
uriThe specified xtd::uri instance to test.
Returns
bool true if the current xtd::uri instance is a base of uri; otherwise, false.
Exceptions
ArgumentNullExceptionuri 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_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.

◆ equals() [1/3]

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

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

Parameters
objAn object to compare with this object.
Returns
true if the current object is equal to the other parameter; otherwise, false.

Implements xtd::iequatable< uri >.

◆ to_string()

xtd::string 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.

◆ check_scheme_name()

static bool xtd::uri::check_scheme_name ( const xtd::string scheme)
static

Determines whether the specified scheme name is valid.

Parameters
schemeThe 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.

◆ escape_data_string()

static xtd::string xtd::uri::escape_data_string ( const xtd::string value)
static

Converts a string to its escaped representation.

Parameters
valueThe string to escape.
Returns
string A string that contains the escaped representation of stringToEscape.
Exceptions
ArgumentNullExceptionvalue is null.
UriFormatExceptionThe 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::string xtd::uri::escape_uri_string ( const xtd::string value)
static

Converts a URI string to its escaped representation.

Parameters
valueThe string to escape.
Returns
string A string that contains the escaped representation of stringToEscape.
Exceptions
ArgumentNullExceptionvalue is null.
UriFormatExceptionThe 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.

◆ from_hex()

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

Gets the decimal value of a hexadecimal digit.

Parameters
digitThe 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
ArgumentExceptiondigit 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.

◆ hex_escape()

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

Converts a specified character into its hexadecimal equivalent.

Parameters
characterThe character to convert to hexadecimal representation.
Returns
string The hexadecimal representation of the specified character.
Exceptions
ArgumentOutOfRangeExceptioncharacter is greater than 255.

◆ hex_unescape()

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

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

Parameters
patternThe hexadecimal representation of a character.
indexThe 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
ArgumentOutOfRangeExceptionindex is less than 0 or greater than or equal to the number of characters in pattern.

◆ is_hex_digit()

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

Determines whether a specified character is a valid hexadecimal digit.

Parameters
characterThe 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::string pattern,
size_t  index 
)
static

Determines whether a character in a string is hexadecimal encoded.

Parameters
patternThe string to check.
indexThe 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_well_formed_uri_string()

static bool xtd::uri::is_well_formed_uri_string ( const xtd::string 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_stringThe string used to attempt to construct a xtd::uri.
uri_kindThe 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.

◆ unescape_data_string()

static xtd::string xtd::uri::unescape_data_string ( const xtd::string value)
static

Converts a string to its unescaped representation.

Parameters
valueThe string to unescape.
Returns
string A string that contains the unescaped representation of stringToUnescape.
Exceptions
ArgumentNullExceptionvalue 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.

◆ equals() [2/3]

virtual bool xtd::object::equals ( const object obj) const
virtualnoexcept

Determines whether the specified object is equal to the current object.

Parameters
objThe object to compare with the current object.
Returns
true if the specified object is equal to the current object. otherwise, false.
Examples
The following code example compares the current instance with another object.
#include <xtd/console>
using namespace xtd;
auto main() -> int {
auto object1 = new_ptr<object>();
auto object2 = new_ptr<object>();
auto object3 = object2;
console::write_line(object1->equals(*object3));
console::write_line(*object1 == *object3);
object3 = object1;
console::write_line(object1->equals(*object3));
console::write_line(*object1 == *object3);
}
// This code produces the following output :
//
// false
// false
// true
// true

Reimplemented from xtd::object.

◆ equals() [3/3]

template<typename object_a_t , typename object_b_t >
static bool xtd::object::equals ( const object_a_t &  object_a,
const object_b_t &  object_b 
)
inlinestaticnoexcept

Determines whether the specified object instances are considered equal.

Parameters
object_aThe first object to compare.
object_bThe second object to compare.
Returns
true if object_a is the same instance as object_b or if both are null references or if object_a(object_b) returns true. otherwise, false.
Examples
The following code example compares different objects.
#include <xtd/console>
using namespace xtd;
auto main() -> int {
string s1 = "Tom";
string s2 = "Carol";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "Tom";
s2 = "Tom";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "";
s2 = "Tom";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "Carol";
s2 = "";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "";
s2 = "";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
}
// This code produces the following output :
//
// object::equals("Tom", "Carol") => false
// object::equals("Tom", "Tom") => true
// object::equals("", "Tom") => false
// object::equals("Carol", "") => false
// object::equals("", "") => true
virtual bool equals(const object &obj) const noexcept
Determines whether the specified object is equal to the current object.

Member Data Documentation

◆ scheme_delimiter

const xtd::string 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.
string address = "www.contoso.com";
string uri_string = string::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);
static const xtd::string scheme_delimiter
Specifies the characters that separate the communication protocol scheme from the address portion of ...
Definition uri.h:120
static const xtd::string uri_scheme_http
Specifies that the URI is accessed through the Hypertext Transfer Protocol (HTTP)....
Definition uri.h:165
static basic_string format(const basic_string< char > &fmt, args_t &&... args)
Writes the text representation of the specified arguments list, to string using the specified format ...

◆ uri_scheme_file

const xtd::string 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");
static const xtd::string uri_scheme_file
Specifies that the URI is a pointer to a file. This field is read-only.
Definition uri.h:130

◆ uri_scheme_ftp

const xtd::string 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");
static const xtd::string uri_scheme_ftp
Specifies that the URI is accessed through the File Transfer Protocol (FTP). This field is read-only.
Definition uri.h:140

◆ uri_scheme_gopher

const xtd::string 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");
static const xtd::string uri_scheme_gopher
Specifies that the URI is accessed through the Gopher protocol. This field is read-only.
Definition uri.h:150

◆ uri_scheme_http

const xtd::string 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());
static bool check_scheme_name(const xtd::string &scheme)
Determines whether the specified scheme name is valid.

◆ uri_scheme_https

const xtd::string 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.");
static const xtd::string uri_scheme_https
Specifies that the URI is accessed through the Hypertext Transfer Protocol (HTTPS)....
Definition uri.h:175

◆ uri_scheme_mailto

const xtd::string 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");
static const xtd::string uri_scheme_mailto
Specifies that the URI is an e-mail address and is accessed through the Simple Mail Transport Protoco...
Definition uri.h:185

◆ uri_scheme_net_pipe

const xtd::string 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::string 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::string 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");
static const xtd::string uri_scheme_news
Specifies that the URI is an Internet news group and is accessed through the Network News Transport P...
Definition uri.h:201

◆ uri_scheme_nntp

const xtd::string 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");
static const xtd::string uri_scheme_nntp
Specifies that the URI is an Internet news group and is accessed through the Network News Transport P...
Definition uri.h:211

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