A class for parsing and manipulating Uniform Resource Identifiers (URIs). More...

#include <CesiumUtility/Uri.h>

Public Types
typedef std::string	SubstitutionCallbackSignature(const std::string &placeholder)
	A callback to fill-in a placeholder value in a URL.

Public Member Functions
	Uri (const std::string &uri)
	Attempts to create a new Uri by parsing the given string. If the string fails to parse, isValid will return false.

	Uri (const Uri &base, const std::string &relative, bool useBaseQuery=false)
	Attempts to create a new Uri from a base URI and a relative URI. If the base URI is invalid, only the relative URI string will be used. If the relative URI fails to parse, isValid will return false.

std::string_view	toString () const
	Returns a string representation of the entire URI including path and query parameters.

bool	isValid () const
	Returns true if this URI has been successfully parsed.

	operator bool () const
	Equivalent to isValid.

std::string_view	getScheme () const
	Gets the scheme portion of the URI. If the URI was created without a scheme, this will return an empty string.

std::string_view	getHost () const
	Gets the host portion of the URI. If the URI also specifies a non-default port, it will be included in the returned host. If the URI contains no host, this will return an empty string.

std::string_view	getPath () const
	Gets the path portion of the URI. This will not include query parameters, if present.

std::string_view	getQuery () const
	Gets the query portion of the URI.

void	setPath (const std::string_view &path)
	Sets the path portion of a URI to a new value. The other portions of the URI are left unmodified, including any query parameters.

void	setQuery (const std::string_view &queryString)
	Sets the query portion of a URI to a new value. The other portions of the URI are left unmodified.

Static Public Member Functions
static std::string	resolve (const std::string &base, const std::string &relative, bool useBaseQuery=false, bool assumeHttpsDefault=true)
	Attempts to resolve a relative URI using a base URI.

static std::string	addQuery (const std::string &uri, const std::string &key, const std::string &value)
	Adds the given key and value to the query string of a URI. For example, `addQuery("https://api.cesium.com/v1/example", "key", "value")` would produce the URL `https://api.cesium.com/v1/example?key=value`.

static std::string	getQueryValue (const std::string &uri, const std::string &key)
	Obtains the value of the given key from the query string of the URI, if possible.

static std::string	substituteTemplateParameters (const std::string &templateUri, const std::function< SubstitutionCallbackSignature > &substitutionCallback)
	Substitutes the placeholders in a templated URI with their appropriate values obtained using a specified callback function.

static std::string	escape (const std::string &s)
	Escapes a portion of a URI, percent-encoding disallowed characters.

static std::string	unescape (const std::string &s)
	Unescapes a portion of a URI, decoding any percent-encoded characters.

static std::string	unixPathToUriPath (const std::string &unixPath)
	Converts a Unix file system path to a string suitable for use as the path portion of a URI. Characters that are not allowed in the path portion of a URI are percent-encoded as necessary.

static std::string	windowsPathToUriPath (const std::string &windowsPath)
	Converts a Windows file system path to a string suitable for use as the path portion of a URI. Characters that are not allowed in the path portion of a URI are percent-encoded as necessary.

static std::string	nativePathToUriPath (const std::string &nativePath)
	Converts a file system path on the current system to a string suitable for use as the path portion of a URI. Characters that are not allowed in the path portion of a URI are percent-encoded as necessary.

static std::string	uriPathToUnixPath (const std::string &uriPath)
	Converts the path portion of a URI to a Unix file system path. Percent-encoded characters in the URI are decoded.

static std::string	uriPathToWindowsPath (const std::string &uriPath)
	Converts the path portion of a URI to a Windows file system path. Percent-encoded characters in the URI are decoded.

static std::string	uriPathToNativePath (const std::string &uriPath)
	Converts the path portion of a URI to a file system path on the current system. Percent-encoded characters in the URI are decoded.

static std::string	getPath (const std::string &uri)
	Gets the path portion of the URI. This will not include path parameters, if present.

static std::string	setPath (const std::string &uri, const std::string &newPath)
	Sets the path portion of a URI to a new value. The other portions of the URI are left unmodified, including any path parameters.

Detailed Description

A class for parsing and manipulating Uniform Resource Identifiers (URIs).

The URI parser supports the WhatWG URL specification. It also supports protocol-relative URIs such as //example.com, and opaque paths such as a/b/c.

Definition at line 22 of file Uri.h.

Member Typedef Documentation

◆ SubstitutionCallbackSignature

std::string CesiumUtility::Uri::SubstitutionCallbackSignature(const std::string &placeholder)

A callback to fill-in a placeholder value in a URL.

Parameters

placeholder The text of the placeholder. For example, if the placeholder was {example}, the value of placeholder will be example.

Returns: The value to use in place of the placeholder.

Definition at line 184 of file Uri.h.

Constructor & Destructor Documentation

◆ Uri() [1/2]

CesiumUtility::Uri::Uri ( const std::string & uri )

Attempts to create a new Uri by parsing the given string. If the string fails to parse, isValid will return false.

Parameters

uri	A string containing the URI to attempt to parse.

◆ Uri() [2/2]

CesiumUtility::Uri::Uri	(	const Uri &	base,
		const std::string &	relative,
		bool	useBaseQuery = false )

Attempts to create a new Uri from a base URI and a relative URI. If the base URI is invalid, only the relative URI string will be used. If the relative URI fails to parse, isValid will return false.

Parameters

base	The base URI that the relative URI is relative to.
relative	A string containing a relative URI to attempt to parse.
useBaseQuery	If true, the resulting URI will include the query parameters of both the base URI and the relative URI. If false, only the relative URI's query parameters will be used (if any).

Member Function Documentation

◆ addQuery()

static std::string CesiumUtility::Uri::addQuery	(	const std::string &	uri,
		const std::string &	key,
		const std::string &	value )

static

Adds the given key and value to the query string of a URI. For example, addQuery("https://api.cesium.com/v1/example", "key", "value") would produce the URL https://api.cesium.com/v1/example?key=value.

Parameters

uri	The URI whose query string will be modified.
key	The key to be added to the query string.
value	The value to be added to the query string.

Returns: The modified URI including the new query string parameter.

Deprecated: Use the UriQuery class:

Uri parsedUri(uri);
UriQuery params(parsedUri);
params.setValue(key, value);
parsedUri.setQuery(params.toQueryString());

◆ escape()

static std::string CesiumUtility::Uri::escape ( const std::string & s )

static

Escapes a portion of a URI, percent-encoding disallowed characters.

Parameters

s	The string to escape.

Returns: The escaped string.

◆ getHost()

std::string_view CesiumUtility::Uri::getHost ( ) const

Gets the host portion of the URI. If the URI also specifies a non-default port, it will be included in the returned host. If the URI contains no host, this will return an empty string.

Returns: The host, or an empty string if the URI could not be parsed or has no host.

◆ getPath() [1/2]

std::string_view CesiumUtility::Uri::getPath ( ) const

Gets the path portion of the URI. This will not include query parameters, if present.

Returns: The path, or empty string if the URI could not be parsed.

◆ getPath() [2/2]

static std::string CesiumUtility::Uri::getPath ( const std::string & uri )

static

Gets the path portion of the URI. This will not include path parameters, if present.

Parameters

uri	The URI from which to get the path.

Returns: The path, or empty string if the URI could not be parsed.

Deprecated: Create a Uri instance and use Uri::getPath() instead.

◆ getQuery()

std::string_view CesiumUtility::Uri::getQuery ( ) const

Gets the query portion of the URI.

Returns: The path, or empty string if the URI could not be parsed.

◆ getQueryValue()

static std::string CesiumUtility::Uri::getQueryValue	(	const std::string &	uri,
		const std::string &	key )

static

Obtains the value of the given key from the query string of the URI, if possible.

If the URI can't be parsed, or the key doesn't exist in the query string, an empty string will be returned.

Parameters

uri	The URI with a query string to obtain a value from.
key	The key whose value will be obtained from the URI, if possible.

Returns: The value of the given key in the query string, or an empty string if not found.

Deprecated: Use the UriQuery class:

Uri parsedUri(uri);
UriQuery params(parsedUri);
params.getValue(key);

◆ getScheme()

std::string_view CesiumUtility::Uri::getScheme ( ) const

Gets the scheme portion of the URI. If the URI was created without a scheme, this will return an empty string.

Returns: The scheme, or an empty string if the URI could not be parsed or has no scheme.

◆ nativePathToUriPath()

static std::string CesiumUtility::Uri::nativePathToUriPath ( const std::string & nativePath )

static

Converts a file system path on the current system to a string suitable for use as the path portion of a URI. Characters that are not allowed in the path portion of a URI are percent-encoded as necessary.

If the _WIN32 preprocessor definition is defined when compiling cesium-native, this is assumed to be a Windows-like system and this function calls windowsPathToUriPath. Otherwise, this is assumed to be a Unix-like system and this function calls unixPathToUriPath.

Parameters

nativePath The file system path.

Returns: The URI path.

◆ operator bool()

CesiumUtility::Uri::operator bool ( ) const

inline

Equivalent to isValid.

Definition at line 58 of file Uri.h.

◆ resolve()

static std::string CesiumUtility::Uri::resolve	(	const std::string &	base,
		const std::string &	relative,
		bool	useBaseQuery = false,
		bool	assumeHttpsDefault = true )

static

Attempts to resolve a relative URI using a base URI.

For example, a relative URI /v1/example together with the base URI https://api.cesium.com would resolve to https://api.cesium.com/v1/example.

Parameters

base	The base URI that the relative URI is relative to.
relative	The relative URI to be resolved against the base URI.
useBaseQuery	If true, any query parameters of the base URI will be retained in the resolved URI.
assumeHttpsDefault	This parameter is ignored and is only kept for API compatibility.

Returns: The resolved URI.

Deprecated: Use the Uri constructor instead.

◆ setPath() [1/2]

static std::string CesiumUtility::Uri::setPath	(	const std::string &	uri,
		const std::string &	newPath )

static

Sets the path portion of a URI to a new value. The other portions of the URI are left unmodified, including any path parameters.

Parameters

uri	The URI for which to set the path.
newPath	The new path portion of the URI.

Returns: The new URI after setting the path. If the original URI cannot be parsed, it is returned unmodified.

Deprecated: Create a Uri instance and use Uri::setPath(const std::string_view&) instead.

◆ setPath() [2/2]

void CesiumUtility::Uri::setPath ( const std::string_view & path )

Sets the path portion of a URI to a new value. The other portions of the URI are left unmodified, including any query parameters.

Parameters

path	The new path portion of the URI.

◆ setQuery()

void CesiumUtility::Uri::setQuery ( const std::string_view & queryString )

Sets the query portion of a URI to a new value. The other portions of the URI are left unmodified.

Parameters

queryString The new query portion of the URI.

◆ substituteTemplateParameters()

static std::string CesiumUtility::Uri::substituteTemplateParameters	(	const std::string &	templateUri,
		const std::function< SubstitutionCallbackSignature > &	substitutionCallback )

static

Substitutes the placeholders in a templated URI with their appropriate values obtained using a specified callback function.

A templated URI has placeholders in the form of {name}. For example, https://example.com/{x}/{y}/{z} has three placeholders, x, y, and z. The callback will be called for each placeholder and they will be replaced with the return value of this callback.

Parameters

templateUri	The templated URI whose placeholders will be substituted by this method.
substitutionCallback	The callback that will be called for each placeholder in the provided URI. See SubstitutionCallbackSignature.

◆ unescape()

static std::string CesiumUtility::Uri::unescape ( const std::string & s )

static

Unescapes a portion of a URI, decoding any percent-encoded characters.

Parameters

s	The string to unescape.

Returns: The unescaped string.

◆ unixPathToUriPath()

static std::string CesiumUtility::Uri::unixPathToUriPath ( const std::string & unixPath )

static

Converts a Unix file system path to a string suitable for use as the path portion of a URI. Characters that are not allowed in the path portion of a URI are percent-encoded as necessary.

If the path is absolute (it starts with a slash), then the URI will start with a slash as well.

Parameters

unixPath The file system path.

Returns: The URI path.

◆ uriPathToNativePath()

static std::string CesiumUtility::Uri::uriPathToNativePath ( const std::string & uriPath )

static

Converts the path portion of a URI to a file system path on the current system. Percent-encoded characters in the URI are decoded.

If the _WIN32 preprocessor definition is defined when compiling cesium-native, this is assumed to be a Windows-like system and this function calls uriPathToWindowsPath. Otherwise, this is assumed to be a Unix-like system and this function calls uriPathToUnixPath.

Parameters

uriPath The URI path.

Returns: The file system path.

◆ uriPathToUnixPath()

static std::string CesiumUtility::Uri::uriPathToUnixPath ( const std::string & uriPath )

static

Converts the path portion of a URI to a Unix file system path. Percent-encoded characters in the URI are decoded.

If the URI path is absolute (it starts with a slash), then the file system path will start with a slash as well.

Parameters

uriPath The URI path.

Returns: The file system path.

◆ uriPathToWindowsPath()

static std::string CesiumUtility::Uri::uriPathToWindowsPath ( const std::string & uriPath )

static

Converts the path portion of a URI to a Windows file system path. Percent-encoded characters in the URI are decoded.

If the URI path is absolute (it starts with a slash), then the file system path will start with a slash or a drive letter.

Parameters

uriPath The URI path.

Returns: The file system path.

◆ windowsPathToUriPath()

static std::string CesiumUtility::Uri::windowsPathToUriPath ( const std::string & windowsPath )

static

Converts a Windows file system path to a string suitable for use as the path portion of a URI. Characters that are not allowed in the path portion of a URI are percent-encoded as necessary.

Either / or \ may be used as a path separator on input, but the output will contain only /.

If the path is absolute (it starts with a slash or with C:\ or similar), then the URI will start with a slash well.

Parameters

windowsPath The file system path.

Returns: The URI path.

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

/home/runner/work/cesium-native/cesium-native/CesiumUtility/include/CesiumUtility/Uri.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ SubstitutionCallbackSignature

Constructor & Destructor Documentation

◆ Uri() [1/2]

◆ Uri() [2/2]

Member Function Documentation

◆ addQuery()

◆ escape()

◆ getHost()

◆ getPath() [1/2]

◆ getPath() [2/2]

◆ getQuery()

◆ getQueryValue()

◆ getScheme()

◆ nativePathToUriPath()

◆ operator bool()

◆ resolve()

◆ setPath() [1/2]

◆ setPath() [2/2]

◆ setQuery()

◆ substituteTemplateParameters()

◆ unescape()

◆ unixPathToUriPath()

◆ uriPathToNativePath()

◆ uriPathToUnixPath()

◆ uriPathToWindowsPath()

◆ windowsPathToUriPath()