You.i Engine
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:

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 &rKey, CYIUrl::Encoding encoding=CYIUrl::Encoding::Decoded)
 
void RemoveAll (const CYIString &rKey, CYIUrl::Encoding encoding=CYIUrl::Encoding::Decoded)
 
const CYIStringGetValue (const CYIString &key, bool *pNotFound=nullptr) const
 
CYIString GetValue (const CYIString &key, CYIUrl::Encoding encoding, bool *pNotFound=nullptr) const
 
std::vector< CYIStringGetValues (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 rKey,
CYIUrl::Encoding  encoding = CYIUrl::Encoding::Decoded 
)

Remove the first parameter whose key is rKey.

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

Note
This function runs in O(n) time.

◆ RemoveAll()

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

Remove all parameters which use the key rKey.

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: