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 CYIString &	GetScheme () 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 CYIString &	GetPortString () 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
CYIString	GetLocalPath (Encoding encoding=Encoding::Encoded) const
bool	IsEmpty () const
void	Clear ()

Static Public Member Functions
static const CYIUrl &	EmptyUrl ()
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.

GetLocalPath()

CYIString CYIUrl::GetLocalPath

(

Encoding

encoding = Encoding::Encoded

)

const

Returns the path portion of this URL formatted to be used with the local filesystem.

Returns empty string if the scheme portion of this URL is not 'file'.

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:

• network/YiUrl.h