A class for building 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.

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 building and manipulating Uniform Resource Identifiers (URIs).

Definition at line 11 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 71 of file Uri.h.

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.

◆ 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.

◆ getPath()

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.

◆ 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.

◆ 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.

◆ 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	If true, protocol-relative URIs (such as `//api.cesium.com`) will be assumed to be `https`. If false, they will be assumed to be `http`.

Returns: The resolved URI.

◆ setPath()

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.

◆ 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

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ SubstitutionCallbackSignature

Member Function Documentation

◆ addQuery()

◆ escape()

◆ getPath()

◆ getQueryValue()

◆ nativePathToUriPath()

◆ resolve()

◆ setPath()

◆ substituteTemplateParameters()

◆ unescape()

◆ unixPathToUriPath()

◆ uriPathToNativePath()

◆ uriPathToUnixPath()

◆ uriPathToWindowsPath()

◆ windowsPathToUriPath()