You.i Engine
Public Member Functions | List of all members
CYIUrlQuery Class Reference
Network

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 eEncoding=CYIUrl::ENCODED)
 
bool operator== (const CYIUrlQuery &other) const
 
bool operator!= (const CYIUrlQuery &other) const
 
void Add (const CYIString &key, const CYIString &value, CYIUrl::ENCODING eEncoding=CYIUrl::DECODED)
 
void Remove (const CYIString &rKey, CYIUrl::ENCODING eEncoding=CYIUrl::DECODED)
 
void RemoveAll (const CYIString &rKey, CYIUrl::ENCODING eEncoding=CYIUrl::DECODED)
 
const CYIString & GetValue (const CYIString &key, bool *pbNotFound=nullptr) const
 
CYIString GetValue (const CYIString &key, CYIUrl::ENCODING eEncoding, bool *pbNotFound=nullptr) const
 
std::vector< CYIString > GetValues (const CYIString &key, CYIUrl::ENCODING eEncoding=CYIUrl::DECODED) const
 
bool HasKey (const CYIString &key, CYIUrl::ENCODING eEncoding=CYIUrl::DECODED) const
 
void Clear ()
 
void SetParameters (const std::vector< std::pair< CYIString, CYIString > > &parameters, CYIUrl::ENCODING eEncoding=CYIUrl::DECODED)
 
void SetString (const CYIString &query, CYIUrl::ENCODING eEncoding=CYIUrl::ENCODED)
 
bool IsEmpty () const
 
const std::vector< std::pair< CYIString, CYIString > > & GetParameters () const
 
std::vector< std::pair< CYIString, CYIString > > GetParameters (CYIUrl::ENCODING eEncoding) const
 
CYIString ToString (CYIUrl::ENCODING eEncoding=CYIUrl::ENCODED) const
 

Constructor & Destructor Documentation

CYIUrlQuery::CYIUrlQuery ( )
CYIUrlQuery::CYIUrlQuery ( const CYIUrl &  url)
CYIUrlQuery::CYIUrlQuery ( const CYIString &  query,
CYIUrl::ENCODING  eEncoding = CYIUrl::ENCODED 
)

Creates a CYIUrlQuery object from the query string query.

The eEncoding 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

void CYIUrlQuery::Add ( const CYIString &  key,
const CYIString &  value,
CYIUrl::ENCODING  eEncoding = CYIUrl::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 eEncoding 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.
void CYIUrlQuery::Clear ( )

Remove all parameters from this query.

Note
This function runs in O(1) time.
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 eEncoding parameter can be used to specify the encoding of the returned keys and values. By default, this function returns decoded keys and values.

std::vector<std::pair<CYIString, CYIString> > CYIUrlQuery::GetParameters ( CYIUrl::ENCODING  eEncoding) const

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

const CYIString& CYIUrlQuery::GetValue ( const CYIString &  key,
bool *  pbNotFound = 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, pbNotFound, 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.
CYIString CYIUrlQuery::GetValue ( const CYIString &  key,
CYIUrl::ENCODING  eEncoding,
bool *  pbNotFound = 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, pbNotFound, can optionally be provided – if the key is not found, its pointed-to boolean will be set to true.

The eEncoding 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.
std::vector<CYIString> CYIUrlQuery::GetValues ( const CYIString &  key,
CYIUrl::ENCODING  eEncoding = CYIUrl::DECODED 
) const

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

The eEncoding 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.
bool CYIUrlQuery::HasKey ( const CYIString &  key,
CYIUrl::ENCODING  eEncoding = CYIUrl::DECODED 
) const

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

The eEncoding 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.
bool CYIUrlQuery::IsEmpty ( ) const

Returns true if this query has no parameters.

bool CYIUrlQuery::operator!= ( const CYIUrlQuery &  other) const
bool CYIUrlQuery::operator== ( const CYIUrlQuery &  other) const
void CYIUrlQuery::Remove ( const CYIString &  rKey,
CYIUrl::ENCODING  eEncoding = CYIUrl::DECODED 
)

Remove the first parameter whose key is rKey.

The eEncoding 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.
void CYIUrlQuery::RemoveAll ( const CYIString &  rKey,
CYIUrl::ENCODING  eEncoding = CYIUrl::DECODED 
)

Remove all parameters which use the key rKey.

The eEncoding 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.
void CYIUrlQuery::SetParameters ( const std::vector< std::pair< CYIString, CYIString > > &  parameters,
CYIUrl::ENCODING  eEncoding = CYIUrl::DECODED 
)

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

The eEncoding 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.

void CYIUrlQuery::SetString ( const CYIString &  query,
CYIUrl::ENCODING  eEncoding = CYIUrl::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 eEncoding 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.
CYIString CYIUrlQuery::ToString ( CYIUrl::ENCODING  eEncoding = CYIUrl::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 eEncoding 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: