You.i Engine
CYIUrl Class Reference

Detailed Description

A class used to encapsulate an URL.

URL objects are created either from an input string, which is then parsed into URL components, or by setting one or more URL components individually.

Warning
While RFC 3986 is used as a base for this class, it is not followed to the letter.
No encoding/decoding is performed on the various URL sections. If an URL section contains characters that would be invalid for that section, it is up to the user to encode the string prior to setting it in the URL object.

#include <network/YiUrl.h>

Public Types

enum  Parts {
  Parts::Scheme = 0x1,
  Parts::Username = 0x2,
  Parts::Password = 0x4,
  Parts::Host = 0x8,
  Parts::Port = 0x10,
  Parts::Path = 0x20,
  Parts::Query = 0x40,
  Parts::Fragment = 0x80,
  Parts::Authentication = Username | Password,
  Parts::Authority = Authentication | Host | Port,
  Parts::AuthorityAndPath = Authority | Path,
  Parts::Everything = Scheme | AuthorityAndPath | Query | Fragment,
  Parts::NoScheme = Everything & (~Scheme),
  Parts::NoAuthentication = Everything & (~Authentication)
}
 
enum  Encoding {
  Encoding::Encoded,
  Encoding::Decoded
}
 

Public Member Functions

 CYIUrl ()
 
 CYIUrl (const CYIString &url, Encoding encoding=Encoding::Encoded)
 
bool operator== (const CYIUrl &other) const
 
bool operator!= (const CYIUrl &other) const
 
bool operator< (const CYIUrl &other) const
 
void SetScheme (const CYIString &scheme)
 
void SetAuthority (const CYIString &authority, Encoding encoding=Encoding::Decoded)
 
void SetAuthentication (const CYIString &authentication, Encoding encoding=Encoding::Decoded)
 
void SetUsername (const CYIString &username, Encoding encoding=Encoding::Decoded)
 
void SetPassword (const CYIString &password, Encoding encoding=Encoding::Decoded)
 
void SetHost (const CYIString &host, Encoding encoding=Encoding::Decoded)
 
void SetPort (int32_t port)
 
void SetPort (const CYIString &port)
 
void SetPath (const CYIString &path, CYIUrl::Encoding encoding=Encoding::Decoded)
 
void SetQuery (const CYIString &query, CYIUrl::Encoding encoding=Encoding::Decoded)
 
void SetQuery (const CYIUrlQuery &query)
 
void SetFragment (const CYIString &fragment, CYIUrl::Encoding encoding=Encoding::Decoded)
 
void SetString (const CYIString &url, Encoding encoding=Encoding::Encoded)
 
const CYIStringGetScheme () const
 
CYIString GetAuthority (Encoding encoding=Encoding::Decoded) const
 
CYIString GetAuthentication (Encoding encoding=Encoding::Decoded) const
 
CYIString GetUsername (Encoding encoding=Encoding::Decoded) const
 
CYIString GetPassword (Encoding encoding=Encoding::Decoded) const
 
CYIString GetHost (Encoding encoding=Encoding::Decoded) const
 
int32_t GetPort () const
 
const CYIStringGetPortString () const
 
CYIString GetPath (Encoding encoding=Encoding::Decoded) const
 
CYIString GetQuery (Encoding encoding=Encoding::Decoded) const
 
CYIString GetFragment (Encoding encoding=Encoding::Decoded) const
 
CYIUrlQuery GetQueryBuilder () const
 
CYIString ToString (Parts parts=Parts::Everything, Encoding encoding=Encoding::Encoded) const
 
bool IsEmpty () const
 
void Clear ()
 

Static Public Member Functions

static const CYIUrlEmptyUrl ()
 
static CYIString Encode (const CYIString &input)
 
static CYIString Decode (const CYIString &input)
 

Member Enumeration Documentation

◆ Encoding

enum CYIUrl::Encoding
strong
Enumerator
Encoded 
Decoded 

◆ Parts

enum CYIUrl::Parts
strong
Enumerator
Scheme 
Username 
Password 
Host 
Port 
Path 
Query 
Fragment 
Authentication 
Authority 
AuthorityAndPath 
Everything 
NoScheme 
NoAuthentication 

Constructor & Destructor Documentation

◆ CYIUrl() [1/2]

CYIUrl::CYIUrl ( )

Creates a blank URL.

Note
A blank URL also has a blank scheme.

◆ CYIUrl() [2/2]

CYIUrl::CYIUrl ( const CYIString url,
Encoding  encoding = Encoding::Encoded 
)
explicit

Creates an URL from the string url. The string will be parsed into URL components.

The encoding parameter can be used to specify the encoding of the provided url string. The various delimiters used in URLs are expected to be unencoded. By default, the provided string is expected to be encoded.

Member Function Documentation

◆ Clear()

void CYIUrl::Clear ( )

Clears this URL and resets it to a 'blank' URL. Note that blank URLs have no scheme.

◆ Decode()

static CYIString CYIUrl::Decode ( const CYIString input)
static

Decodes the string input using URL percent encoding.

All character sequences 'XX', where XX is two hexadecimal digits, are transformed to their single-byte representation. 'Orphan' percent characters (such as in '100% coverage') are left as-is, as are percent sequences with invalid data (such as 'AX').

Example: The string 'The%20100%%20quick%20brown%20fox' gets encoded to 'The 100% quick brown fox'.

Note
Escape character sequences with hexadecimal values above 7F are interpreted as being part of a UTF-8 sequence.

◆ EmptyUrl()

static const CYIUrl& CYIUrl::EmptyUrl ( )
static

Returns an instance of an empty URL. Useful for functions that return references.

◆ Encode()

static CYIString CYIUrl::Encode ( const CYIString input)
static

Encodes the string input using URL percent encoding.

The following characters are left as is: a-z, A-Z, 0-9, '-', '.', '_' and '~'. All other characters, including UTF-8 characters and controls characters, are encoded as follows XX, where XX is two uppercase hexadecimal digits. UTF-8 characters with codepoints above 127 are encoded as multiple bytes represented in XX format.

Example: The string 'The quick brown fox' gets encoded to 'The%20quick%20brown%20fox'.

Warning
Encoding the same string twice may yield unexpected results because the '' character itself would get encoded.

◆ GetAuthentication()

CYIString CYIUrl::GetAuthentication ( Encoding  encoding = Encoding::Decoded) const

Returns the authentication portion of this URL. The authentication portion is composted of the username and, password sections.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'myuser:mypassword'.

The encoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

Warning
Some data loss may occur when fetching decoded strings, as encoded delimiters may be decoded.

◆ GetAuthority()

CYIString CYIUrl::GetAuthority ( Encoding  encoding = Encoding::Decoded) const

Returns the authority portion of this URL. The authority portion is composted of the username, password, host and port sections.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'myuser:mypas.nosp@m.swor.nosp@m.d@www.nosp@m..exa.nosp@m.mple..nosp@m.com:123'.

The encoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

Warning
Some data loss may occur when fetching decoded strings, as encoded delimiters may be decoded.

◆ GetFragment()

CYIString CYIUrl::GetFragment ( Encoding  encoding = Encoding::Decoded) const

Returns the fragment portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'bookmark'.

The encoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

◆ GetHost()

CYIString CYIUrl::GetHost ( Encoding  encoding = Encoding::Decoded) const

Returns the host portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'www.example.com'.

The encoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

◆ GetPassword()

CYIString CYIUrl::GetPassword ( Encoding  encoding = Encoding::Decoded) const

Returns the password portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'mypassword'.

The encoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

◆ GetPath()

CYIString CYIUrl::GetPath ( Encoding  encoding = Encoding::Decoded) const

Returns the path portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'my/path'.

The encoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

Warning
Some data loss may occur when fetching decoded strings, as encoded delimiters may be decoded.
Note
What is considered the path in a URL differs depending on if an authority section is present or not. For example, in the URL 'http://server/my/path', the path is 'my/path', but in the URL 'scheme:/my/path' the path is '/my/path'.

◆ GetPort()

int32_t CYIUrl::GetPort ( ) const

Returns the port portion of this URL as an integer. Returns -1 if no port is set, or if the set port string cannot be parsed as a (valid) port.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 123.

◆ GetPortString()

const CYIString& CYIUrl::GetPortString ( ) const

Returns the port portion of this URL as a string.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return '123'.

◆ GetQuery()

CYIString CYIUrl::GetQuery ( Encoding  encoding = Encoding::Decoded) const

Returns the query portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'key=value'.

The encoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

Warning
Some data loss may occur when fetching decoded strings, as encoded delimiters may be decoded. For example, if the '&' or '=' characters are encoded as part of a parameter, the decoded query may no longer be parsable as a list of key-value pairs. Thus, calling SetQuery(GetQuery()) may result in corrupt data.

◆ GetQueryBuilder()

CYIUrlQuery CYIUrl::GetQueryBuilder ( ) const

Returns a CYIUrlQuery query object initialized from this URL's query.

Note
Modifying the returned query object does not modify this URL object – CYIUrl::SetQuery has to be called with the modified CYIUrlQuery.

◆ GetScheme()

const CYIString& CYIUrl::GetScheme ( ) const

Returns the scheme portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'http'.

◆ GetUsername()

CYIString CYIUrl::GetUsername ( Encoding  encoding = Encoding::Decoded) const

Returns the username portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'myuser'.

The encoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

◆ IsEmpty()

bool CYIUrl::IsEmpty ( ) const

Returns true if this URL has no non-empty sections.

◆ operator!=()

bool CYIUrl::operator!= ( const CYIUrl other) const

◆ operator<()

bool CYIUrl::operator< ( const CYIUrl other) const

◆ operator==()

bool CYIUrl::operator== ( const CYIUrl other) const

◆ SetAuthentication()

void CYIUrl::SetAuthentication ( const CYIString authentication,
Encoding  encoding = Encoding::Decoded 
)

Sets the authentication portion of this URL. The authentication is composed of the username and password, though both sections are optional.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'bob:smith' will result in the URL 'ftp://bob:smith@www.example.com:123/my/path?key=value#bookmark'.

The encoding parameter can be used to specify the encoding of the provided authentication string. The ':' delimiter is expected to be unencoded. By default, the authentication is assumed to be decoded.

◆ SetAuthority()

void CYIUrl::SetAuthority ( const CYIString authority,
Encoding  encoding = Encoding::Decoded 
)

Sets the authority portion of this URL. The authority is composed of the username, password, host and port, though all sections are optional.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'bob:smith.nosp@m.@mys.nosp@m.erver.nosp@m..com:42' will result in the URL 'ftp://bob:smith@myserver.com:42/my/path?key=value#bookmark'.

The encoding parameter can be used to specify the encoding of the provided authority string. The ':' and '@' delimiters are expected to be unencoded. By default, the authority is assumed to be decoded.

◆ SetFragment()

void CYIUrl::SetFragment ( const CYIString fragment,
CYIUrl::Encoding  encoding = Encoding::Decoded 
)

Sets the fragment portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'place' will result in the URL 'ftp://myuser:mypassword@www.example.com:123/my/path?fruit=banana#place'.

The encoding parameter can be used to specify the encoding of the provided fragment string. By default, the fragment is assumed to be decoded.

◆ SetHost()

void CYIUrl::SetHost ( const CYIString host,
Encoding  encoding = Encoding::Decoded 
)

Sets the host portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'myserver.com' will result in the URL 'ftp://myuser:mypassword@myserver.com:123/my/path?key=value#bookmark'.

The encoding parameter can be used to specify the encoding of the provided host string. By default, the host is assumed to be decoded.

Note
RFC 2396 specifies that hosts may only contain alpha numerical characters, along with the '-' and '.' characters. For compatibility, this function will percent-encode encountered invalid characters (when encoding is Encoding::Decoded). However, be warned that this does not create a valid URL.

◆ SetPassword()

void CYIUrl::SetPassword ( const CYIString password,
Encoding  encoding = Encoding::Decoded 
)

Sets the password portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'smith' will result in the URL 'ftp://myuser:smith@www.example.com:123/my/path?key=value#bookmark'.

The encoding parameter can be used to specify the encoding of the provided password string. By default, the password is assumed to be decoded.

◆ SetPath()

void CYIUrl::SetPath ( const CYIString path,
CYIUrl::Encoding  encoding = Encoding::Decoded 
)

Sets the path portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'differentPath' will result in the URL 'ftp://myuser:mypassword@www.example.com:123/differentPath?key=value#bookmark'.

The encoding parameter can be used to specify the encoding of the provided path string. By default, the path is assumed to be decoded.

Note
What is considered the path in a URL differs depending on if an authority section is present or not. For example, in the URL 'http://server/my/path', the path is 'my/path', but in the URL 'scheme:/my/path' the path is '/my/path'.

◆ SetPort() [1/2]

void CYIUrl::SetPort ( int32_t  port)

Sets the port portion of this URL. Negative values are interpreted as 'no port'.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with '42' will result in the URL 'ftp://myuser:mypassword@www.example.com:42/my/path?key=value#bookmark'.

◆ SetPort() [2/2]

void CYIUrl::SetPort ( const CYIString port)

Sets the port portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with '42' will result in the URL 'ftp://myuser:mypassword@www.example.com:42/my/path?key=value#bookmark'.

Note
RFC 2396 specifies that ports may only contain numerical characters. For compatibility, this function allows any string to be used as port. However, be warned that using non-numerical characters as part of the port may result in parsing errors.

◆ SetQuery() [1/2]

void CYIUrl::SetQuery ( const CYIString query,
CYIUrl::Encoding  encoding = Encoding::Decoded 
)

Sets the query portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'fruit=banana' will result in the URL 'ftp://myuser:mypassword@www.example.com:123/my/path?fruit=banana#bookmark'.

The encoding parameter can be used to specify the encoding of the query string. The parameter delimiters, '&' and '=', are expected to be unencoded. By default, the query string is assumed to be decoded.

Note
The CYIUrlQuery::ToString function returns encoded queries by default. To set a query to an URL from a CYIUrlQuery object, it is recommended to use the SetQuery(const CYIUrlQuery &) function instead.

◆ SetQuery() [2/2]

void CYIUrl::SetQuery ( const CYIUrlQuery query)

Sets the query portion of this URL from the data contained in a CYIUrlQuery object.

◆ SetScheme()

void CYIUrl::SetScheme ( const CYIString scheme)

Sets the scheme portion of this URL. The scheme must not be postfixed with ':' or '://'.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'ftp' will result in the URL 'ftp://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark'.

Note
RFC 2396 specifies that only alphanumeric characters, along with the '+', '-' and '.' characters, are allowed in schemes. The presence of any other character will result in an invalid URLs, which may not parse correctly.

◆ SetString()

void CYIUrl::SetString ( const CYIString url,
Encoding  encoding = Encoding::Encoded 
)

Sets the string representation of this URL. The string will be parsed into the individual string components.

The encoding parameter can be used to specify the encoding of the provided url string. The various delimiters used in URLs are expected to be unencoded. By default, the provided string is expected to be encoded.

See also
CYIUrl(const CYIString&, CYIUrl::Encoding)

◆ SetUsername()

void CYIUrl::SetUsername ( const CYIString username,
Encoding  encoding = Encoding::Decoded 
)

Sets the username portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'bob' will result in the URL 'ftp://bob:mypassword@www.example.com:123/my/path?key=value#bookmark'.

The encoding parameter can be used to specify the encoding of the provided username string. By default, the username is assumed to be decoded.

◆ ToString()

CYIString CYIUrl::ToString ( Parts  parts = Parts::Everything,
Encoding  encoding = Encoding::Encoded 
) const

Returns a string generated from the components of this URL.

The parts parameter can be used to specify which parts of the URL to include in the generated string. Note that some combinations don't really make sense (e.g. 'scheme + port'). By default, all parts of the URL are used to generate the returned string.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function, when called with EVERYTHING, would return 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark'. When called with HOST, it would return 'www.example.com'. When called with NO_SCHEME, it would return 'myuser:mypas.nosp@m.swor.nosp@m.d@www.nosp@m..exa.nosp@m.mple..nosp@m.com:123/my/path?key=value::bookmark'.

The encoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in encoded form.

Warning
Some data loss may occur when fetching decoded strings, as encoded delimiters may be decoded.

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