Classes
class	ImplPtr
	The ImplPtr class provides a convenient away to achieve the Rule of Zero while keeping all the benefits of PIMPL. This saves us from writing an enormous amount of boilerplate code for each class. More...

class	NeverDestroyed

class	Subprocess
	Create a RAII-type object that encapsulates a subprocess. More...

Typedefs
using	EnvironmentMap = std::unordered_map< std::string, std::string >
	Type alias for a collection of environment variables. More...

using	EnvironmentStrings = std::vector< std::string >
	Type alias for a collection of environment variables Each entry is of the form KEY=VAL. More...

template<class T , class Deleter = void ()(T)>
using	UniqueImplPtr = std::unique_ptr< T, Deleter >
	This is an alternative to ImplPtr<T> which serves the same purpose, except it only provide move semantics (i.e. it does not allow copying). This should be used in cases where it is not safe (or not possible) to copy the underlying state of an implementation class. More...

Functions
bool	clearenv ()
	Unset all environment variables. More...

EnvironmentMap	env ()
	Retrieve all current environment variables. More...

bool	env (const std::string &_name, std::string &_value, bool _allowEmpty=false)
	Find the environment variable '_name' and return its value. More...

EnvironmentStrings	envMapToStrings (const EnvironmentMap &_envMap)
	Convert a map of environment variables to a vector. More...

EnvironmentMap	envStringsToMap (const EnvironmentStrings &_envStrings)
	Convert a vector of environment variables to a map. More...

template<class T , typename... Args>
ImplPtr< T >	MakeImpl (Args &&..._args)
	Pass this to the constructor of an ImplPtr object to easily initialize it. All the arguments passed into this function will be perfectly forwarded to the implementation class that gets created. More...

template<class T , typename... Args>
UniqueImplPtr< T >	MakeUniqueImpl (Args &&..._args)
	Pass this to the constructor of a UniqueImplPtr object to easily initialize it. All the arguments passed into this function will be perfectly forwarded to the implementation class that gets created. More...

std::string	printenv ()
	Print the entire current environment to a string. More...

bool	setenv (const EnvironmentMap &_vars)
	Set the environment variable '_name'. More...

bool	setenv (const std::string &_name, const std::string &_value)
	Set the environment variable '_name'. More...

bool	unsetenv (const std::string &_name)
	Unset the environment variable '_name'. More...

Typedef Documentation

◆ EnvironmentMap

using EnvironmentMap = std::unordered_map<std::string, std::string>

Type alias for a collection of environment variables.

◆ EnvironmentStrings

using EnvironmentStrings = std::vector<std::string>

Type alias for a collection of environment variables Each entry is of the form KEY=VAL.

◆ UniqueImplPtr

using UniqueImplPtr = std::unique_ptr<T, Deleter>

This is an alternative to ImplPtr<T> which serves the same purpose, except it only provide move semantics (i.e. it does not allow copying). This should be used in cases where it is not safe (or not possible) to copy the underlying state of an implementation class.

Note that when creating an implementation class that is unsafe to copy, you should explicitly delete its copy constructor (unless one of its members has an explicitly deleted copy constructor). Doing so will force you to use UniqueImplPtr instead of ImplPtr, and it will signal to future developers or maintainers that the implementation class is not meant to be copiable.

Use MakeUniqueImpl<T>() to construct UniqueImplPtr objects.

Function Documentation

◆ clearenv()

bool gz::utils::clearenv ( )

Unset all environment variables.

Note: This function is not thread-safe and should not be called concurrently with env or setenv

Returns: True if the environment was unset or false otherwise.

◆ env() [1/2]

EnvironmentMap gz::utils::env ( )

Retrieve all current environment variables.

Note: This function is not thread-safe and should not be called concurrently with setenv or unsetenv

Returns: A collection of current environment variables

◆ env() [2/2]

bool gz::utils::env	(	const std::string &	_name,
		std::string &	_value,
		bool	_allowEmpty = `false`
	)

Find the environment variable '_name' and return its value.

Note: This function is not thread-safe and should not be called concurrently with setenv or unsetenv

Parameters

[in]	_name	Name of the environment variable.
[out]	_value	Value if the variable was found.
[in]	_allowEmpty	Allow set-but-empty variables. (Unsupported on Windows)

Returns: True if the variable was found or false otherwise.

◆ envMapToStrings()

EnvironmentStrings gz::utils::envMapToStrings ( const EnvironmentMap & _envMap )

Convert a map of environment variables to a vector.

Parameters

[in] _envMap Collection of mapped environment variables.

Returns: Vector collection of environment variables.

◆ envStringsToMap()

EnvironmentMap gz::utils::envStringsToMap ( const EnvironmentStrings & _envStrings )

Convert a vector of environment variables to a map.

Parameters

[in] _envStrings Vector collection of environment variables

Returns: Mapped collection of environment variables.

◆ MakeImpl()

ImplPtr<T> gz::utils::MakeImpl ( Args &&... _args )

Pass this to the constructor of an ImplPtr object to easily initialize it. All the arguments passed into this function will be perfectly forwarded to the implementation class that gets created.

E.g.:

MyClass::MyClass(Arg1 arg1, Arg2 arg2, Arg3 arg3)
  : dataPtr(utils::MakeImpl<Implementation>(arg1, arg2, arg3))
{
  // Do nothing
}

Template Parameters

T	The typename of the implementation class. This must be set explicitly.
Args	The argument types. These will be inferred automatically.

Parameters

[in] _args The arguments to be forwarded to the implementation class.

Returns: A new ImplPtr<T>. Passing this along to a class's ImplPtr object's constructor will efficiently move this newly created object into it.

◆ MakeUniqueImpl()

UniqueImplPtr<T> gz::utils::MakeUniqueImpl ( Args &&... _args )

Pass this to the constructor of a UniqueImplPtr object to easily initialize it. All the arguments passed into this function will be perfectly forwarded to the implementation class that gets created.

E.g.:

MyClass::MyClass(Arg1 arg1, Arg2 arg2, Arg3 arg3)
  : dataPtr(utils::MakeUniqueImpl<Implementation>(arg1, arg2, arg3))
{
  // Do nothing
}

Template Parameters

T	The typename of the implementation class. This must be set explicitly.
Args	The argument types. These will be inferred automatically.

Parameters

[in] _args The arguments to be forwarded to the implementation class.

Returns: A new UniqueImplPtr<T>. Passing this along to a class's UniqueImplPtr object's constructor will efficiently move this newly created object into it.

◆ printenv()

std::string gz::utils::printenv ( )

Print the entire current environment to a string.

This prints each variable in the form KEY=VALUE
Note: This function is not thread-safe and should not be called concurrently with setenv or unsetenv

Returns: A string containing all environment variables NOLINTNEXTLINE - This is incorrectly parsed as a global variable

◆ setenv() [1/2]

bool gz::utils::setenv ( const EnvironmentMap & _vars )

Set the environment variable '_name'.

Note: On Windows setting an empty string (_value=="") is the equivalent of unsetting the variable. Note: This function is not thread-safe and should not be called concurrently with env or unsetenv

Parameters

[in] _vars Collection of environment variables to set

Returns: True if all variables were set or false otherwise.

◆ setenv() [2/2]

bool gz::utils::setenv	(	const std::string &	_name,
		const std::string &	_value
	)

Set the environment variable '_name'.

Note: On Windows setting an empty string (_value=="") is the equivalent of unsetting the variable. Note: This function is not thread-safe and should not be called concurrently with env or unsetenv

Parameters

[in]	_name	Name of the environment variable.
[in]	_value	Value of the variable to be set.

Returns: True if the variable was set or false otherwise.

◆ unsetenv()

bool gz::utils::unsetenv ( const std::string & _name )

Unset the environment variable '_name'.

Note: This function is not thread-safe and should not be called concurrently with env or setenv

Parameters

[in] _name Name of the environment variable.

Returns: True if the variable was unset or false otherwise.

Gazebo Utils

API Reference

Classes

Typedefs

Functions

Typedef Documentation

◆ EnvironmentMap

◆ EnvironmentStrings

◆ UniqueImplPtr

Function Documentation

◆ clearenv()

◆ env() [1/2]

◆ env() [2/2]

◆ envMapToStrings()

◆ envStringsToMap()

◆ MakeImpl()

◆ MakeUniqueImpl()

◆ printenv()

◆ setenv() [1/2]

◆ setenv() [2/2]

◆ unsetenv()