carb::launcher::ArgCollector

Defined in carb/launcher/LauncherUtils.h

class ArgCollector

A simple child process argument collector helper class.

This allows arguments of different types to be accumulated into a list that can then later be retrieved as a Unix style argument list that can be passed to ILauncher::launchProcess() in its LaunchDesc::argv descriptor member. This allows for string arguments and various integer type arguments to be trivially added to the argument list without needing to locally convert all of them to strings. The argument count is also tracked as the arguments are collected. Once all arguments have been collected, the final Unix style argument list can be retrieved with getArgs() and the count with getCount(). All collected arguments will remain in the order they are originally added in.

The basic usage of this is to create a new object, add one or more arguments of various types to it using the ‘+=’ operators, then retrieve the Unix style argument list with getArgs() to assign to LaunchDesc::argv and getCount() to assign to LaunchDesc::argc before calling ILauncher::launchProcess(). Copy and move operators and constructors are also provided to make it easier to assign other argument lists to another object to facilitate more advanced multiple process launches (ie: use a set of base arguments for each child process then add other child specific arguments to each one before launching).

This helper class is not thread safe. It is the caller’s responsibility to ensure thread safe access to objects of this class if needed.

Public Functions

ArgCollector() = default

inline ArgCollector(const ArgCollector &rhs)

Copy constructor: copies another argument collector object into this one.

Parameters

rhs – [in] The argument collector object to copy from. This will be left unmodified.

inline ArgCollector(ArgCollector &&rhs)

Move constructor: moves the contents of another argument collector object into this one.

Parameters

rhs – [in] The argument collector object to move from. This object will be reset to an empty state.

inline ~ArgCollector()

inline void clear()

Clears out this object and resets it back to its initially constructed state.

Remark

This clears out all content collected into this object so far. This object will be reset back to its original constructed state and will be suitable for reuse.

Returns

No return value.

inline const char *const *getArgs(size_t *argCountOut = nullptr)

Retrieves the final argument list as a Unix style null terminated list.

Remark

This retrieves the final argument list for this object. The list object is owned by this object and should not be freed or deleted. The returned list will be valid until this object is destroyed or until getArgs() is called again after adding new arguments. If the caller needs to keep a copy of the returned argument list, the caller must perform a deep copy on the returned object. This task is out of the scope of this object and is left as an exercise for the caller.

Parameters

argCountOut – [out] Optionally receives the number of arguments as by via getCount().

Returns

A Unix style argument list. This list will always be terminated by a nullptr entry so that it can be self-counted if needed. This returned argument list object is owned by this object and should not be deleted or freed. See the remarks below for more information on the lifetime and use of this object.

Returns

nullptr if the buffer for the argument list could not be allocated.

inline size_t getCount() const

Retrieves the argument count for this object.

Returns

The number of arguments that have been collected into this object so far. This is incremented each time the ‘+=’ operator is used.

inline ArgCollector &operator=(const ArgCollector &rhs)

Copy assignment operator.

Parameters

rhs – [in] The argument collector object to copy from. This object will receive a copy of all the arguments currently listed in the rhs argument collector object. The rhs object will not be modified.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &operator=(ArgCollector &&rhs)

Move assignment operator.

Parameters

rhs – [inout] The argument collector object to move from. This object will steal all arguments from rhs and will clear out the other object before returning.

Returns

A reference to this object suitable for chaining other operators or calls.

inline bool operator==(const ArgCollector &rhs)

Compare this object to another argument collector object for equality.

Parameters

rhs – [in] The argument collector object to compare to this one.

Returns

true if the two objects contain the same list of arguments. Note that each object must contain the same arguments in the same order in order for them to match.

Returns

false if the argument lists in the two objects differ.

inline bool operator!=(const ArgCollector &rhs)

Compare this object to another argument collector object for inequality.

Parameters

rhs – [in] The argument collector object to compare to this one.

Returns

true if the two objects contain a different list of arguments. Note that each object must contain the same arguments in the same order in order for them to match. If either the argument count differs or the order of the arguments differs, this will succeed.

Returns

false if the argument lists in the two objects match.

inline bool operator!() const

Tests whether this argument collector is empty.

Returns

true if this argument collector object is empty.

Returns

false if argument collector has at least one argument in its list.

inline explicit operator bool() const

Tests whether this argument collector is non-empty.

Returns

true if argument collector has at least one argument in its list.

Returns

false if this argument collector object is empty.

inline ArgCollector &format(const char *fmt, ...)

Adds a formatted string as an argument.

Parameters

• fmt – [in] The printf-style format string to use to create the new argument. This may not be nullptr.

• ... – [in] The arguments required by the format string.

Returns

A references to this object suitable for chaining other operators or calls.

inline ArgCollector &add(const char *value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &add(const std::string &value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &add(const ArgCollector &value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &add(const char *const *value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &add(const std::vector<const char*> &value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &add(const std::vector<std::string> &value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &operator+=(const char *value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &operator+=(const std::string &value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &operator+=(const ArgCollector &value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &operator+=(const char *const *value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &operator+=(const std::vector<const char*> &value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &operator+=(const std::vector<std::string> &value)

Adds a new argument or set of arguments to the end of the list.

Parameters

value – [in] The value to add as a new argument. This may be a string or any primitive integer or floating point type value. For integer and floating point values, they will be converted to a string before being added to the argument list. For the variants that add another argument collector list or a nullptr terminated string list, or a vector of strings to this one, all arguments in the other object will be copied into this one in the same order. All new argument(s) will always be added at the end of the list.

Returns

A reference to this object suitable for chaining other operators or calls.

inline ArgCollector &add(unsigned char value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(unsigned char value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(unsigned short value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(unsigned short value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(unsigned int value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(unsigned int value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(unsigned long value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(unsigned long value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(unsigned long long value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(unsigned long long value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(char value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(char value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(short value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(short value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(int value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(int value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(long value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(long value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(long long value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(long long value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(float value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(float value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(double value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &operator+=(double value)

Adds a new primitive value to this argument collector object.

Parameters

value – [in] The primitive numerical value to add to this argument collector object. This will be converted to a string before adding to the collector.

Returns

A reference to this argument collector object.

inline ArgCollector &add(const char *root, const char *prefix, SettingsEnumFlags flags = 0, AddSettingPredicateFn predicate = nullptr, void *context = nullptr)

Adds all settings under a branch in the settings registry to this object.

Remark

This adds echoes of all settings under a given root branch as arguments in this argument collector. Each setting that is found is given the prefix prefix (typically something like “–/”). This is useful for passing along certain subsets of a parent process’s settings tree to a child process.

Note

It is the caller’s responsibility to ensure that only expected settings are added to this argument collector. A predicate function can be provided to allow per-item control over which settings get added. By default, the search is not recursive. This is intentional since adding a full tree could potentially add a lot of new arguments to this object.

Parameters

• root – [in] The root of the settings tree to copy into this argument collector. This may be nullptr or an empty string to add all settings starting from the root of the settings registry. This string should start with a ‘/’ so that it is always an absolute settings path.

• prefix – [in] The prefix to add to each option before adding it to this argument collector. This may be nullptr or an empty string to not use any prefix.

• flags – [in] Flags to control the behavior of this operation. This may be zero or more of the SettingsEnumFlags flags. This defaults to 0.

• predicate – [in] A predicate function that will be called for each value to give the caller a chance to decide whether it should be added to this object or not. This may be nullptr if all settings under the given root should always be added. This defaults to nullptr.

• context – [in] An opaque context value that will be passed to the predicate function predicate. This will not be accessed or used in any way except to pass to the predicate function. This defaults to nullptr.

Returns

A reference to this argument collector object.

inline const std::string &at(size_t index) const

Retrieves the argument string at a given index.

Remark

This retrieves the argument string stored at the given index in the argument list. This string will be the one stored in the list itself and should not be modified.

Parameters

index – [in] The zero based index of the argument to retrieve. This must be strictly less than the number of arguments in the list as returned by getCount(). If this index is out of range, an empty string will be returned instead.

Returns

A reference to the string contained in the requested argument in the list. This returned string should not be modified by the caller.

inline const std::string &operator[](size_t index) const

Retrieves the argument string at a given index.

Remark

This retrieves the argument string stored at the given index in the argument list. This string will be the one stored in the list itself and should not be modified.

Parameters

index – [in] The zero based index of the argument to retrieve. This must be strictly less than the number of arguments in the list as returned by getCount(). If this index is out of range, an empty string will be returned instead.

Returns

A reference to the string contained in the requested argument in the list. This returned string should not be modified by the caller.

inline void pop()

Removes the last argument from the list.

Remark

This removes the last argument from the list. If this is called, any previous returned object from getArgs() will no longer be valid. The updated list object must be retrieved again with another call to getArgs().

Returns

No return value.

inline bool erase(size_t index)

Removes an argument from the list by its index.

Remark

This removes an argument from the list. If this is called, any previous returned object from getArgs() will no longer be valid. The updated list object must be retrieved again with another call to getArgs().

Returns

true if the item is successfully removed.

Returns

false if the given index is out of range of the argument list’s size.

inline std::string toString() const

Returns a string of all arguments for debugging purposes.

Returns

A std::string of all arguments concatenated. This is for debugging/logging purposes only.