CYIUrlQuery Class Reference

Detailed Description

An URL query builder.

Provides the ability to build an URL's query portion using an accumulation of key/value parameters.

Usage example:

CYIUrlQuery query;
query.Add("en", "ferret");
query.Add("latin", "Mustela putorius furo");

CYIString queryString = query.ToString(); // returns "en=ferret&latin=Mustela%20putorius%20furo"

#include <network/YiUrlQuery.h>

Public Member Functions
	CYIUrlQuery ()
	CYIUrlQuery (const CYIUrl &url)
	CYIUrlQuery (const CYIString &query, CYIUrl::Encoding encoding=CYIUrl::Encoding::Encoded)
bool	operator== (const CYIUrlQuery &other) const
bool	operator!= (const CYIUrlQuery &other) const
void	Add (const CYIString &key, const CYIString &value, CYIUrl::Encoding encoding=CYIUrl::Encoding::Decoded)
void	Remove (const CYIString &key, CYIUrl::Encoding encoding=CYIUrl::Encoding::Decoded)
void	RemoveAll (const CYIString &key, CYIUrl::Encoding encoding=CYIUrl::Encoding::Decoded)
const CYIString &	GetValue (const CYIString &key, bool *pNotFound=nullptr) const
CYIString	GetValue (const CYIString &key, CYIUrl::Encoding encoding, bool *pNotFound=nullptr) const
std::vector< CYIString >	GetValues (const CYIString &key, CYIUrl::Encoding encoding=CYIUrl::Encoding::Decoded) const
bool	HasKey (const CYIString &key, CYIUrl::Encoding encoding=CYIUrl::Encoding::Decoded) const
void	Clear ()
void	SetParameters (const std::vector< std::pair< CYIString, CYIString >> &parameters, CYIUrl::Encoding encoding=CYIUrl::Encoding::Decoded)
void	SetString (const CYIString &query, CYIUrl::Encoding encoding=CYIUrl::Encoding::Encoded)
bool	IsEmpty () const
const std::vector< std::pair< CYIString, CYIString > > &	GetParameters () const
std::vector< std::pair< CYIString, CYIString > >	GetParameters (CYIUrl::Encoding encoding) const
CYIString	ToString (CYIUrl::Encoding encoding=CYIUrl::Encoding::Encoded) const
CYIString	RetrieveAndRemoveQueryString (const CYIString &key, bool *pSuccess=nullptr)

Constructor & Destructor Documentation

CYIUrlQuery() [1/3]

CYIUrlQuery::CYIUrlQuery

(

)

CYIUrlQuery() [2/3]

CYIUrlQuery::CYIUrlQuery

(

const CYIUrl &

url

)

CYIUrlQuery() [3/3]

CYIUrlQuery::CYIUrlQuery	(	const CYIString &	query,
		CYIUrl::Encoding	encoding = CYIUrl::Encoding::Encoded
	)

Creates a CYIUrlQuery object from the query string query.

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

Warning

Some decoded query strings cannot be directly parsed into a CYIUrlQuery. This is because some keys or values may contain the '&' or '=' characters, which are recognised by the parser as delimiters for parameters.

Member Function Documentation

Add()

void CYIUrlQuery::Add	(	const CYIString &	key,
		const CYIString &	value,
		CYIUrl::Encoding	encoding = CYIUrl::Encoding::Decoded
	)

Add the key/value pair as a parameter using a CYIString value at the end of the parameters list.

Add("myKey", "myValue") is roughly equivalent to appending &myKey=myValue to the query.

Note

This function does not remove existing parameters with key key. If unique keys are desired, call RemoveAll prior to calling Add.

The encoding parameter can be used to specify the encoding of the provided key and value. By default, the key and value is assumed to be decoded.

Note

This function runs in O(1) time.

Clear()

void CYIUrlQuery::Clear

(

)

Remove all parameters from this query.

Note

This function runs in O(1) time.

GetParameters() [1/2]

const std::vector<std::pair<CYIString, CYIString> >& CYIUrlQuery::GetParameters

(

)

const

Returns the parameters list. The pairs in the returned vector are composed of keys and values, respectively.

The encoding parameter can be used to specify the encoding of the returned keys and values. By default, this function returns decoded keys and values.

GetParameters() [2/2]

std::vector<std::pair<CYIString, CYIString> > CYIUrlQuery::GetParameters

(

CYIUrl::Encoding

encoding

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

GetValue() [1/2]

const CYIString& CYIUrlQuery::GetValue	(	const CYIString &	key,
		bool *	pNotFound = nullptr
	)		const

Finds and returns the value associated with the first parameter whose key matches key. If no such parameter exists, an empty string is returned. A pointer to a boolean, pNotFound, can optionally be provided – if the key is not found, its pointed-to boolean will be set to true.

Note

This function expects a decoded key and returns a decoded value.

This function runs in O(n) time.

GetValue() [2/2]

CYIString CYIUrlQuery::GetValue	(	const CYIString &	key,
		CYIUrl::Encoding	encoding,
		bool *	pNotFound = nullptr
	)		const

Finds and returns the value associated with the first parameter whose key matches key. If no such parameter exists, an empty string is returned. A pointer to a boolean, pNotFound, can optionally be provided – if the key is not found, its pointed-to boolean will be set to true.

The encoding parameter can be used to specify the encoding of the provided key and of the returned value. By default, key and value are assumed to be decoded.

Note

This function runs in O(n) time.

GetValues()

std::vector<CYIString> CYIUrlQuery::GetValues	(	const CYIString &	key,
		CYIUrl::Encoding	encoding = CYIUrl::Encoding::Decoded
	)		const

Returns all values associated with keys that match key. If no parameter matches key key, an empty vector is returned.

The encoding parameter can be used to specify the encoding of the provided key and of the returned values. By default, the key is assumed to be decoded.

Note

This function runs in O(n) time.

HasKey()

bool CYIUrlQuery::HasKey	(	const CYIString &	key,
		CYIUrl::Encoding	encoding = CYIUrl::Encoding::Decoded
	)		const

Returns true if this query contains at least one parameter whose key matches key.

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

Note

This function runs in O(n) time.

IsEmpty()

bool CYIUrlQuery::IsEmpty

(

)

const

Returns true if this query has no parameters.

operator!=()

bool CYIUrlQuery::operator!=

(

const CYIUrlQuery &

other

)

const

operator==()

bool CYIUrlQuery::operator==

(

const CYIUrlQuery &

other

)

const

Remove()

void CYIUrlQuery::Remove	(	const CYIString &	key,
		CYIUrl::Encoding	encoding = CYIUrl::Encoding::Decoded
	)

Remove the first parameter whose key is key.

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

Note

This function runs in O(n) time.

RemoveAll()

void CYIUrlQuery::RemoveAll	(	const CYIString &	key,
		CYIUrl::Encoding	encoding = CYIUrl::Encoding::Decoded
	)

Remove all parameters which use the key Key.

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

Note

This function runs in O(n) time.

RetrieveAndRemoveQueryString()

CYIString CYIUrlQuery::RetrieveAndRemoveQueryString	(	const CYIString &	key,
		bool *	pSuccess = nullptr
	)

Returns a string generated from the specified query key of this URL Query Builder and removes it.

SetParameters()

void CYIUrlQuery::SetParameters	(	const std::vector< std::pair< CYIString, CYIString >> &	parameters,
		CYIUrl::Encoding	encoding = CYIUrl::Encoding::Decoded
	)

Sets the parameters contained in this query to parameters. All preexisting parameters are removed.

The encoding parameter can be used to specify the encoding of the provided keys and values. By default, the keys and values are assumed to be decoded.

SetString()

void CYIUrlQuery::SetString	(	const CYIString &	query,
		CYIUrl::Encoding	encoding = CYIUrl::Encoding::Encoded
	)

Sets the parameters of this query by parsing the provided query string.

Example: Calling this function with 'fruit=banana&vegetable=lettuce' will result in a query with the keys 'fruit' and 'vegetable' (with associated values 'banana' and 'lettuce').

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

Warning

Some decoded query strings cannot be directly parsed into a CYIUrlQuery. This is because some keys or values may contain the '&' or '=' characters, which are recognised by the parser as delimiters for parameters.

ToString()

CYIString CYIUrlQuery::ToString

(

CYIUrl::Encoding

encoding = CYIUrl::Encoding::Encoded

)

const

Returns a string generated from the components of this URL Query Builder.

If, for example, you have a parameter 'en' with a value of 'ferret', and another parameter 'latin' with the value of 'Mustela putorius furo', this function will return

en=ferret&latin=Mustela%20putorius%20furo

The encoding parameter can be used to specify the encoding of the returned query. By default, the parameters of this query are encoded prior to being combined into a query string.

---

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

• network/YiUrlQuery.h