Ignition Common

API Reference

3.9.0
ignition::common Namespace Reference

Classes

class  Animation
 Manages an animation, which is a collection of keyframes and the ability to interpolate between the keyframes. More...
 
class  AudioDecoder
 An audio decoder based on FFMPEG. More...
 
class  Base64
 
class  Battery
 A battery abstraction. More...
 
class  BVHLoader
 Handles loading BVH animation files. More...
 
class  ColladaExporter
 Class used to export Collada mesh files. More...
 
class  ColladaLoader
 Class used to load Collada mesh files. More...
 
class  Connection
 A class that encapsulates a connection. More...
 
class  Console
 Container for loggers, and global logging options (such as verbose vs. quiet output). More...
 
class  DirIter
 A class for iterating over all items in a directory. More...
 
class  Event
 Base class for all events. More...
 
class  EventT
 A class for event processing. More...
 
class  FileLogger
 A logger that outputs messages to a file. More...
 
class  GTSMeshUtils
 Creates GTS utilities for meshes. More...
 
class  HeightmapData
 Encapsulates a generic heightmap data file. More...
 
class  Image
 Encapsulates an image. More...
 
class  ImageHeightmap
 Encapsulates an image that will be interpreted as a heightmap. More...
 
class  KeyEvent
 Generic description of a keyboard event. More...
 
class  KeyFrame
 A key frame in an animation. More...
 
class  Logger
 Terminal logger. More...
 
class  Material
 Encapsulates description of a material. More...
 
class  MaterialDensity
 Encapsulates density types. More...
 
class  Mesh
 A 3D mesh. More...
 
class  MeshCSG
 Creates CSG meshes. More...
 
class  MeshExporter
 Base class for exporting meshes. More...
 
class  MeshLoader
 Base class for loading meshes. More...
 
class  MeshManager
 Maintains and manages all meshes. More...
 
class  MouseEvent
 Generic description of a mouse event. More...
 
class  MovingWindowFilter
 Base class for MovingWindowFilter. More...
 
class  NodeAnimation
 Node animation. More...
 
class  NodeAssignment
 Vertex to node weighted assignement for skeleton animation visualization. More...
 
class  NodeTransform
 A transformation node. More...
 
class  NumericAnimation
 A numeric animation. More...
 
class  NumericKeyFrame
 A keyframe for a NumericAnimation. More...
 
class  OBJLoader
 Class used to load obj mesh files. More...
 
class  Pbr
 This class contains Physically-Based-Rendering (PBR) workflow properties. More...
 
class  Plugin
 
struct  PluginInfo
 Holds info required to construct a plugin. More...
 
class  PluginLoader
 Class for loading plugins. More...
 
class  PoseAnimation
 A pose animation. More...
 
class  PoseKeyFrame
 A keyframe for a PoseAnimation. More...
 
class  Profiler
 Used to perform application-wide performance profiling. More...
 
class  ScopedProfile
 Used to provide C++ RAII-style profiling sample. The sample will start on the construction of the ScopedProfile object and stop when the object leaves scope. More...
 
class  SignalHandler
 Register callbacks that get triggered on SIGINT and SIGTERM. More...
 
class  SingletonT
 Singleton template class. More...
 
class  Skeleton
 A skeleton, usually used for animation purposes. More...
 
class  SkeletonAnimation
 Skeleton animation. More...
 
class  SkeletonNode
 A skeleton node. More...
 
class  SpecializedPlugin
 
class  SpecializedPlugin< SpecInterface >
 This class allows Plugin instances to have high-speed access to interfaces that can be anticipated at compile time. The plugin does not have to actually offer the specialized interface in order to get this performance improvement. This template is variadic, so it can support arbitrarily many interfaces. More...
 
class  STLLoader
 Class used to load STL mesh files. More...
 
class  SubMesh
 A child mesh. More...
 
class  SVGCommand
 SVG command data structure. More...
 
class  SVGLoader
 A loader for SVG files. More...
 
struct  SVGPath
 An SVG path element data structure. More...
 
class  SystemPaths
 Functions to handle getting system paths, keeps track of: More...
 
class  TemplatePluginPtr
 This class manages the lifecycle of a plugin instance. It can receive a plugin instance from the PluginLoader class or by copy-construction or assignment from another PluginPtr instance. More...
 
class  Time
 A Time class, can be used to hold wall- or sim-time. stored as sec and nano-sec. More...
 
class  Timer
 A timer class, used to time things in real world walltime. More...
 
class  TrajectoryInfo
 Information about a trajectory for an animation (e.g., Actor) This contains the keyframe information. More...
 
class  URI
 A complete URI. More...
 
class  URIFragment
 The fragment component of a URI. More...
 
class  URIPath
 The path component of a URI. More...
 
class  URIQuery
 The query component of a URI. More...
 
class  Uuid
 A portable class for representing a Universally Unique Identifier. More...
 
class  Video
 Handle video encoding and decoding using libavcodec. More...
 
class  VideoEncoder
 The VideoEncoder class supports encoding a series of images to a video format, and then writing the video to disk. More...
 
class  WorkerPool
 A pool of worker threads that do stuff in parallel. More...
 

Typedefs

typedef std::shared_ptr< BatteryBatteryPtr
 
using ConnectionPtr = std::shared_ptr< Connection >
 
template<typename To , typename From >
using ConstCompatible = detail::ConstCompatible< To, From >
 Contains a static constexpr field named value which will be true if the type From has a const-quality less than or equal to the type To. More...
 
using ConstPluginPtr = TemplatePluginPtr< const Plugin >
 This produces a PluginPtr whose Plugin wrapper only grants access to const-qualified interfaces of the plugin instance. More...
 
template<typename... SpecInterfaces>
using ConstSpecializedPluginPtr = TemplatePluginPtr< const SpecializedPlugin< SpecInterfaces... > >
 This alias creates a specialized PluginPtr whose interfaces are all const-qualified. More...
 
typedef std::runtime_error exception
 A runtime error. More...
 
using MaterialPtr = std::shared_ptr< Material >
 
using MeshPtr = std::shared_ptr< Mesh >
 
using PluginPtr = TemplatePluginPtr< Plugin >
 Typical usage for TemplatePluginPtr is to just hold a generic Plugin type. More...
 
typedef std::map< unsigned int, SkeletonNode * > SkeletonNodeMap
 
using SkeletonPtr = std::shared_ptr< Skeleton >
 
template<typename... SpecInterfaces>
using SpecializedPluginPtr = TemplatePluginPtr< SpecializedPlugin< SpecInterfaces... > >
 This alias allows PluginPtr instances to have high-speed access to interfaces that can be anticipated at compile time. The plugin does not have to actually offer the specialized interface in order to get this performance improvement. This template is variadic, so it can support arbitrarily many interfaces. More...
 
using SubMeshPtr = std::shared_ptr< SubMesh >
 

Enumerations

enum  FilesystemWarningOp { FSWO_LOG_WARNINGS = 0, FSWO_SUPPRESS_WARNINGS }
 Options for how to handle errors that occur in functions that manipulate the filesystem. More...
 
enum  NodeTransformType { TRANSLATE, ROTATE, SCALE, MATRIX }
 Enumeration of the transform types. More...
 
enum  NormalMapSpace : int { TANGENT = 0, OBJECT = 1 }
 Space the normal map is defined in. More...
 
enum  PbrType : int { NONE = 0, METAL = 1, SPECULAR = 2 }
 Type of PBR workflow. More...
 

Functions

std::string absPath (const std::string &_path)
 Get the absolute path of a provided path. Relative paths are resolved relative to the current working directory. More...
 
void addFindFileURICallback (std::function< std::string(const URI &)> _cb)
 Add a callback to use when findFile() can't find a file that is a valid URI. The callback should return a full local path to the requested file, or and empty string if the file was not found in the callback. Callbacks will be called in the order they were added until a path is found. More...
 
void addSearchPathSuffix (const std::string &_suffix)
 add path suffix to common::SystemPaths More...
 
IGNITION_COMMON_AV_VISIBLE int AVCodecDecode (AVCodecContext *_codecCtx, AVFrame *_frame, int *_gotFrame, AVPacket *_packet)
 Helper function to avoid deprecation warnings from av_codec_decode_video2. More...
 
IGNITION_COMMON_AV_VISIBLE AVFrame * AVFrameAlloc (void)
 Helper function to avoid deprecation warnings. More...
 
IGNITION_COMMON_AV_VISIBLE void AVFrameUnref (AVFrame *_frame)
 Helper function to avoid deprecation warnings. More...
 
IGNITION_COMMON_AV_VISIBLE void AVPacketUnref (AVPacket *_packet)
 Helper function to avoid deprecation warnings. More...
 
std::string basename (const std::string &_path)
 Given a path, get just the basename portion. More...
 
void changeFromUnixPath (std::string &_path)
 Replace forward-slashes '/' with the preferred directory separator of the current operating system. On Windows, this will turn forward-slashes into backslashes. If forward-slash is the preferred separator of the current operating system, this will do nothing. More...
 
void changeToUnixPath (std::string &_path)
 Replace the preferred directory separator of the current operating system with a forward-slash '/'. On Windows, this will turn backslashes into forward-slashes. More...
 
bool chdir (const std::string &_dir)
 Change current working directory to _dir. More...
 
bool copyDirectory (const std::string &_existingDirname, const std::string &_newDirname, const FilesystemWarningOp _warningOp=FSWO_LOG_WARNINGS)
 Copy a directory, overwrite the destination directory if exists. More...
 
bool copyFile (const std::string &_existingFilename, const std::string &_newFilename, const FilesystemWarningOp _warningOp=FSWO_LOG_WARNINGS)
 Copy a file. More...
 
std::string copyFromUnixPath (const std::string &_path)
 Returns a copy of _path which has been passed through changeFromUnixPath. More...
 
std::string copyToUnixPath (const std::string &_path)
 Returns a copy of _path which has been passed through changeToUnixPath. More...
 
bool createDirectories (const std::string &_path)
 Create directories for the given path. More...
 
bool createDirectory (const std::string &_path)
 Create a new directory on the filesystem. Intermediate directories must already exist. More...
 
std::string cwd ()
 Get the current working directory. More...
 
bool EndsWith (const std::string &_s1, const std::string &_s2)
 return true if string ends with another string More...
 
bool env (const std::string &_name, std::string &_value)
 Find the environment variable '_name' and return its value. More...
 
bool env (const std::string &_name, std::string &_value, bool _allowEmpty)
 Find the environment variable '_name' and return its value. More...
 
bool exists (const std::string &_path)
 Determine whether the given path exists on the filesystem. More...
 
std::string findFile (const std::string &_file)
 search for file in common::SystemPaths More...
 
std::string findFile (const std::string &_file, bool _searchLocalPath)
 search for file in common::SystemPaths More...
 
std::string findFilePath (const std::string &_file)
 search for a file in common::SystemPaths More...
 
constexpr uint64_t hash64 (std::string_view _key)
 fnv1a algorithm for 64-bit platforms. More...
 
bool isDirectory (const std::string &_path)
 Determine whether the given path is a directory. More...
 
bool isFile (const std::string &_path)
 Check if the given path is a file. More...
 
std::string Join (const std::vector< std::string > &_orig, const std::string &_delim)
 Join a sequence of strings with a delimiter. More...
 
std::string Join (const std::vector< std::string > &_orig, char _delim)
 Join a sequence of strings with a delimiter. More...
 
std::string joinPaths (const std::string &_path1, const std::string &_path2)
 Join two strings together to form a path. More...
 
std::string joinPaths (const std::string &_path)
 base case for joinPaths(...) below More...
 
template<typename... Args>
std::string joinPaths (const std::string &_path1, const std::string &_path2, Args const &..._args)
 Append one or more additional path elements to the first passed in argument. More...
 
void load ()
 Load external libraries, such as libav. It is safe to call this multiple times. More...
 
std::string logPath ()
 Get the log path. More...
 
std::string lowercase (const std::string &_in)
 Transforms a string to its lowercase equivalent. More...
 
std::string lowercase (const char *_in)
 Transforms a string to its lowercase equivalent. More...
 
void ltrim (std::string &_s)
 In place left trim. More...
 
std::string ltrimmed (std::string _s)
 Copying left trim. More...
 
bool moveFile (const std::string &_existingFilename, const std::string &_newFilename, const FilesystemWarningOp _warningOp=FSWO_LOG_WARNINGS)
 Move a file. More...
 
std::string parentPath (const std::string &_path)
 Given a path, get just its parent path portion, without separator at the end. More...
 
std::string PluralCast (const std::string &_baseWord, const int _n)
 Choose whether to use a singular or plural version of a noun based on the value of an integer quantity. This version will simply add an 's' character to _baseWord in the event that std::abs(_n) != 1, otherwise it returns _baseWord. More...
 
std::string PluralCast (const std::string &_singular, const std::string &_plural, const int _n)
 A version of PluralCast that works for irregular nouns. If std::abs(_n)==1 then _singular is returned; otherwise _plural will be returned. More...
 
bool removeAll (const std::string &_path, const FilesystemWarningOp _warningOp=FSWO_LOG_WARNINGS)
 Remove a file or a directory and all its contents. More...
 
bool removeDirectory (const std::string &_path, const FilesystemWarningOp _warningOp=FSWO_LOG_WARNINGS)
 Remove an empty directory. More...
 
bool removeDirectoryOrFile (const std::string &_path, const FilesystemWarningOp _warningOp=FSWO_LOG_WARNINGS)
 Remove an empty directory or file. More...
 
bool removeFile (const std::string &_existingFilename, const FilesystemWarningOp _warningOp=FSWO_LOG_WARNINGS)
 Remove a file. More...
 
void replaceAll (std::string &_result, const std::string &_orig, const std::string &_key, const std::string &_replacement)
 Replace all occurances of _key with _replacement. More...
 
std::string replaceAll (const std::string &_orig, const std::string &_key, const std::string &_replacement)
 Replace all occurances of _key with _replacement. More...
 
void rtrim (std::string &_s)
 In place right trim. More...
 
std::string rtrimmed (std::string _s)
 Copying right trim. More...
 
std::string const separator (std::string const &_s)
 Append the preferred path separator character for this platform onto the passed-in string. More...
 
bool setenv (const std::string &_name, const std::string &_value)
 Set the environment variable '_name'. More...
 
template<typename T >
std::string sha1 (const T &_buffer)
 Compute the SHA1 hash of an array of bytes. More...
 
std::string sha1 (void const *_buffer, std::size_t _byteCount)
 Compute the SHA1 hash of an array of bytes. Use std::string sha1(const T &_buffer) instead of this function. More...
 
std::vector< std::stringSplit (const std::string &_orig, char _delim)
 split at a one character delimiter to get a vector of something More...
 
std::vector< std::stringsplit (const std::string &_str, const std::string &_delim)
 Splits a string into tokens. More...
 
bool StartsWith (const std::string &_s1, const std::string &_s2)
 return true if string starts with another string More...
 
common::SystemPathssystemPaths ()
 Get a pointer to the global system paths that is used by all the findFile functions. The returned instance has global shared state for a given process. Care should be taken when manipulating global system paths Caller should not assume ownership of the pointer. More...
 
std::string systemTimeISO ()
 Please use systemTimeIso() as this function will be deprecated in Ignition Common 4. Get the wall time as an ISO string: YYYY-MM-DDTHH:MM:SS.NS. More...
 
std::string systemTimeIso ()
 Get the wall time as an ISO string: YYYY-MM-DDTHH:MM:SS.NS. More...
 
std::string timeToIso (const std::chrono::time_point< std::chrono::system_clock > &_time)
 Converts a time point to an ISO string: YYYY-MM-DDTHH:MM:SS.NS. More...
 
void trim (std::string &_s)
 In place trim from both ends. More...
 
std::string trimmed (std::string _s)
 Copying trim from both ends. More...
 
std::string uniqueDirectoryPath (const std::string &_dir)
 Unique directory path to not overwrite existing directory. More...
 
std::string uniqueFilePath (const std::string &_pathAndName, const std::string &_extension)
 Generates a path for a file which doesn't collide with existing files, by appending numbers to it (i.e. (0), (1), ...) More...
 
bool unsetenv (const std::string &_name)
 Unset the environment variable '_name'. More...
 
std::string uuid ()
 Get a UUID. More...
 

Variables

static std::string PixelFormatNames []
 String names for the pixel formats. More...
 
const int PLUGIN_API_VERSION = 1
 sentinel value to check if a plugin was built with the same version of the PluginInfo struct More...
 

Typedef Documentation

◆ BatteryPtr

◆ ConnectionPtr

◆ ConstCompatible

using ConstCompatible = detail::ConstCompatible<To, From>

Contains a static constexpr field named value which will be true if the type From has a const-quality less than or equal to the type To.

The following expressions will return true:

ConstCompatible<T, T>::value
ConstCompatible<const T, T>::value

The following expression will return false:

ConstCompatible<T, const T>::value

◆ ConstPluginPtr

This produces a PluginPtr whose Plugin wrapper only grants access to const-qualified interfaces of the plugin instance.

◆ ConstSpecializedPluginPtr

using ConstSpecializedPluginPtr = TemplatePluginPtr< const SpecializedPlugin<SpecInterfaces...> >

This alias creates a specialized PluginPtr whose interfaces are all const-qualified.

◆ exception

A runtime error.

◆ MaterialPtr

◆ MeshPtr

◆ PluginPtr

Typical usage for TemplatePluginPtr is to just hold a generic Plugin type.

◆ SkeletonNodeMap

typedef std::map<unsigned int, SkeletonNode*> SkeletonNodeMap

◆ SkeletonPtr

◆ SpecializedPluginPtr

This alias allows PluginPtr instances to have high-speed access to interfaces that can be anticipated at compile time. The plugin does not have to actually offer the specialized interface in order to get this performance improvement. This template is variadic, so it can support arbitrarily many interfaces.

Usage example:

Suppose you want to instantiate a plugin that might (or might not) have some combination of four interfaces which are known at compile time: MyInterface1, FooInterface, MyInterface2, and BarInterface. You can use SpecializedPluginPtr as shown here:

using MySpecialPluginPtr = SpecializedPluginPtr<
MyInterface1, FooInterface, MyInterface2, BarInterface>;
MySpecialPluginPtr plugin = loader->Instantiate(pluginName);

Then, calling the function

plugin->QueryInterface<FooInterface>();

will have extremely high speed associated with it. It will provide direct access to the the FooInterface* of plugin. If plugin does not actually offer FooInterface, then it will return a nullptr, still at extremely high speed.

This same rule also applies to MyInterface1, MyInterface2, and BarInterface, because those interfaces were also provided to SpecializedPluginPtr<...> at compile time.

Only interfaces that have been "specialized" can be passed as arguments to the SpecializedPluginPtr template. To specialize an interface, simply put the macro IGN_COMMON_SPECIALIZE_INTERFACE(~) from ignition/common/PluginMacros.hh into a public location of its class definition.

◆ SubMeshPtr

Enumeration Type Documentation

◆ FilesystemWarningOp

Options for how to handle errors that occur in functions that manipulate the filesystem.

Enumerator
FSWO_LOG_WARNINGS 

Errors that occur during filesystem manipulation should be logged as warnings using ignwarn. (Recommended)

FSWO_SUPPRESS_WARNINGS 

Errors that occur during filesystem manipulation should not be logged. The user will be responsible for checking the system's error flags.

◆ NodeTransformType

Enumeration of the transform types.

Enumerator
TRANSLATE 
ROTATE 
SCALE 
MATRIX 

◆ NormalMapSpace

enum NormalMapSpace : int
strong

Space the normal map is defined in.

Enumerator
TANGENT 

Tangent space.

OBJECT 

Object space.

◆ PbrType

enum PbrType : int
strong

Type of PBR workflow.

Enumerator
NONE 

No workflow.

METAL 

Metal/Roughness workflow.

SPECULAR 

Specular/Glossiness workflow.

Function Documentation

◆ absPath()

std::string ignition::common::absPath ( const std::string _path)

Get the absolute path of a provided path. Relative paths are resolved relative to the current working directory.

Parameters
[in]_pathRelative or absolute path.
Returns
Absolute path (with platform-dependent directory separators).

◆ addFindFileURICallback()

void ignition::common::addFindFileURICallback ( std::function< std::string(const URI &)>  _cb)

Add a callback to use when findFile() can't find a file that is a valid URI. The callback should return a full local path to the requested file, or and empty string if the file was not found in the callback. Callbacks will be called in the order they were added until a path is found.

Parameters
[in]_cbThe callback function, which takes a file path or URI and returns the full local path.

◆ addSearchPathSuffix()

void ignition::common::addSearchPathSuffix ( const std::string _suffix)

add path suffix to common::SystemPaths

Parameters
[in]_suffixThe suffix to add.

◆ AVCodecDecode()

IGNITION_COMMON_AV_VISIBLE int ignition::common::AVCodecDecode ( AVCodecContext *  _codecCtx,
AVFrame *  _frame,
int *  _gotFrame,
AVPacket *  _packet 
)

Helper function to avoid deprecation warnings from av_codec_decode_video2.

Parameters
[in]_codecCtxCodec context.
[out]_frameAVFrame in which decoded video frame is stored.
[out]_gotFrameZero if no frame could be decompressed, otherwise nonzero.
[in]_packetAVPacket structure that stores compressed data.
Returns
On error a negative value is returned, otherwise the number of bytes used or zero if no frame could be decompressed.

◆ AVFrameAlloc()

IGNITION_COMMON_AV_VISIBLE AVFrame* ignition::common::AVFrameAlloc ( void  )

Helper function to avoid deprecation warnings.

◆ AVFrameUnref()

IGNITION_COMMON_AV_VISIBLE void ignition::common::AVFrameUnref ( AVFrame *  _frame)

Helper function to avoid deprecation warnings.

◆ AVPacketUnref()

IGNITION_COMMON_AV_VISIBLE void ignition::common::AVPacketUnref ( AVPacket *  _packet)

Helper function to avoid deprecation warnings.

Parameters
[in]_packetAVPacket structure that stores compressed data

◆ basename()

std::string ignition::common::basename ( const std::string _path)

Given a path, get just the basename portion.

Parameters
[in]_pathThe full path.
Returns
A new string with just the basename portion of the path.

Referenced by joinPaths().

◆ changeFromUnixPath()

void ignition::common::changeFromUnixPath ( std::string _path)

Replace forward-slashes '/' with the preferred directory separator of the current operating system. On Windows, this will turn forward-slashes into backslashes. If forward-slash is the preferred separator of the current operating system, this will do nothing.

Note that this will NOT convert backslashes (or any other separator) into forward slashes, even on operating systems that use forward-slashes as separators.

Parameters
[out]_pathThis string will be directly modified by replacing its forward-slashes with the preferred directory separator of the current operating system.

◆ changeToUnixPath()

void ignition::common::changeToUnixPath ( std::string _path)

Replace the preferred directory separator of the current operating system with a forward-slash '/'. On Windows, this will turn backslashes into forward-slashes.

Parameters
[out]_pathThis string will be directly modified to use forward slashes to separate its directory names.

◆ chdir()

bool ignition::common::chdir ( const std::string _dir)

Change current working directory to _dir.

Parameters
[in]_dirThe directory to change to.
Returns
Whether the operation succeeded.

Referenced by joinPaths().

◆ copyDirectory()

bool ignition::common::copyDirectory ( const std::string _existingDirname,
const std::string _newDirname,
const FilesystemWarningOp  _warningOp = FSWO_LOG_WARNINGS 
)

Copy a directory, overwrite the destination directory if exists.

Parameters
[in]_sourcePath to an existing directory to copy from.
[in]_destinationPath to the destination directory.
Returns
True on success.

Referenced by joinPaths().

◆ copyFile()

bool ignition::common::copyFile ( const std::string _existingFilename,
const std::string _newFilename,
const FilesystemWarningOp  _warningOp = FSWO_LOG_WARNINGS 
)

Copy a file.

Parameters
[in]_existingFilenamePath to an existing file.
[in]_newFilenamePath of the new file.
[in]_warningOpLog or suppress warnings that may occur.
Returns
True on success.

Referenced by joinPaths().

◆ copyFromUnixPath()

std::string ignition::common::copyFromUnixPath ( const std::string _path)

Returns a copy of _path which has been passed through changeFromUnixPath.

Parameters
[in]_pathThe path to start with
Returns
A modified path that uses the preferred directory separator of the current operating system.

◆ copyToUnixPath()

std::string ignition::common::copyToUnixPath ( const std::string _path)

Returns a copy of _path which has been passed through changeToUnixPath.

Parameters
[in]_pathThe path to start with
Returns
A modified path that uses forward slashes to separate directory names.

◆ createDirectories()

bool ignition::common::createDirectories ( const std::string _path)

Create directories for the given path.

Parameters
[in]_pathPath to create directories from
Returns
true on success

◆ createDirectory()

bool ignition::common::createDirectory ( const std::string _path)

Create a new directory on the filesystem. Intermediate directories must already exist.

Parameters
[in]_pathThe new directory path to create
Returns
True if directory creation was successful, false otherwise.

◆ cwd()

std::string ignition::common::cwd ( )

Get the current working directory.

Returns
Name of the current directory

Referenced by joinPaths().

◆ EndsWith()

bool ignition::common::EndsWith ( const std::string _s1,
const std::string _s2 
)

return true if string ends with another string

Parameters
[in]_s1the string to check
[in]_s2the possible suffix
Returns
true if _s1 ends with _s2

◆ env() [1/2]

bool ignition::common::env ( const std::string _name,
std::string _value 
)

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

(mjcarroll): Deprecate and remove in tick-tock.

Parameters
[in]_nameName of the environment variable.
[out]_valueValue if the variable was found.
Returns
True if the variable was found or false otherwise.

Referenced by hash64().

◆ env() [2/2]

bool ignition::common::env ( const std::string _name,
std::string _value,
bool  _allowEmpty 
)

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

Parameters
[in]_nameName of the environment variable.
[out]_valueValue if the variable was found.
[in]_allowEmptyAllow set-but-empty variables. (Unsupported on Windows)
Returns
True if the variable was found or false otherwise.

◆ exists()

bool ignition::common::exists ( const std::string _path)

Determine whether the given path exists on the filesystem.

Parameters
[in]_pathThe path to check for existence
Returns
True if the path exists on the filesystem, false otherwise.

◆ findFile() [1/2]

std::string ignition::common::findFile ( const std::string _file)

search for file in common::SystemPaths

Parameters
[in]_fileName of the file to find.
Returns
The path containing the file.

◆ findFile() [2/2]

std::string ignition::common::findFile ( const std::string _file,
bool  _searchLocalPath 
)

search for file in common::SystemPaths

Parameters
[in]_fileName of the file to find.
[in]_searchLocalPathTrue to search in the current working directory.
Returns
The path containing the file.

◆ findFilePath()

std::string ignition::common::findFilePath ( const std::string _file)

search for a file in common::SystemPaths

Parameters
[in]_filethe file name to look for.
Returns
The path containing the file.

◆ hash64()

constexpr uint64_t ignition::common::hash64 ( std::string_view  _key)

fnv1a algorithm for 64-bit platforms.

Parameters
[in]_keyThe input string.
Returns
A 64-bit unsigned hash value. https://notes.underscorediscovery.com/constexpr-fnv1a/

References env(), lowercase(), ltrim(), ltrimmed(), replaceAll(), rtrim(), rtrimmed(), setenv(), split(), trim(), trimmed(), unsetenv(), and uuid().

◆ isDirectory()

bool ignition::common::isDirectory ( const std::string _path)

Determine whether the given path is a directory.

Parameters
[in]_pathThe path to check
Returns
True if given path exists and is a directory, false otherwise.

◆ isFile()

bool ignition::common::isFile ( const std::string _path)

Check if the given path is a file.

Parameters
[in]_pathPath to a file.
Returns
True if _path is a file.

◆ Join() [1/2]

std::string ignition::common::Join ( const std::vector< std::string > &  _orig,
const std::string _delim 
)

Join a sequence of strings with a delimiter.

Note that this will skip any empty entries in the vector, and will also not prepend or append the delimiter to the final output string

Parameters
[in]_origThe input sequence of strings
[in]_delima string delimiter to join the string with
Returns
a single string composed of strings joined with the delimiter

◆ Join() [2/2]

std::string ignition::common::Join ( const std::vector< std::string > &  _orig,
char  _delim 
)

Join a sequence of strings with a delimiter.

Note that this will skip any empty entries in the vector, and will also not prepend or append the delimiter to the final output string

Parameters
[in]_origThe input sequence of strings
[in]_delima character to join the string with
Returns
a single string composed of strings joined with the delimiter

◆ joinPaths() [1/3]

std::string ignition::common::joinPaths ( const std::string _path1,
const std::string _path2 
)

Join two strings together to form a path.

Parameters
[in]_path1the left portion of the path
[in]_path2the right portion of the path
Returns
Joined path. The function can do simplifications such as elimination of ../ (but is not guaranteed to do so).

Referenced by joinPaths().

◆ joinPaths() [2/3]

std::string ignition::common::joinPaths ( const std::string _path)
inline

base case for joinPaths(...) below

◆ joinPaths() [3/3]

std::string ignition::common::joinPaths ( const std::string _path1,
const std::string _path2,
Args const &...  _args 
)
inline

Append one or more additional path elements to the first passed in argument.

Parameters
[in]argsThe paths to append together
Returns
A new string with the paths appended together.

References basename(), chdir(), copyDirectory(), copyFile(), cwd(), FSWO_LOG_WARNINGS, joinPaths(), moveFile(), parentPath(), removeAll(), removeDirectory(), removeDirectoryOrFile(), removeFile(), uniqueDirectoryPath(), and uniqueFilePath().

◆ load()

void ignition::common::load ( )

Load external libraries, such as libav. It is safe to call this multiple times.

◆ logPath()

std::string ignition::common::logPath ( )

Get the log path.

Returns
the log path

◆ lowercase() [1/2]

std::string ignition::common::lowercase ( const std::string _in)

Transforms a string to its lowercase equivalent.

Parameters
[in]_inString to convert to lowercase
Returns
Lowercase equilvalent of _in.

Referenced by hash64().

◆ lowercase() [2/2]

std::string ignition::common::lowercase ( const char *  _in)

Transforms a string to its lowercase equivalent.

Parameters
[in]_inString to convert to lowercase
Returns
Lowercase equilvalent of _in.

◆ ltrim()

void ignition::common::ltrim ( std::string _s)

In place left trim.

Parameters
[in,out]_sString to trim

Referenced by hash64().

◆ ltrimmed()

std::string ignition::common::ltrimmed ( std::string  _s)

Copying left trim.

Parameters
[in]_sString to trim
Returns
Trimmed string

Referenced by hash64().

◆ moveFile()

bool ignition::common::moveFile ( const std::string _existingFilename,
const std::string _newFilename,
const FilesystemWarningOp  _warningOp = FSWO_LOG_WARNINGS 
)

Move a file.

Parameters
[in]_existingFilenameFull path to an existing file.
[in]_newFilenameFull path of the new file.
[in]_warningOpLog or suppress warnings that may occur.
Returns
True on success.

Referenced by joinPaths().

◆ parentPath()

std::string ignition::common::parentPath ( const std::string _path)

Given a path, get just its parent path portion, without separator at the end.

Parameters
[in]_pathPath of which to find parent path
Returns
A new string with just the parent path of the path.

Referenced by joinPaths().

◆ PluralCast() [1/2]

std::string ignition::common::PluralCast ( const std::string _baseWord,
const int  _n 
)

Choose whether to use a singular or plural version of a noun based on the value of an integer quantity. This version will simply add an 's' character to _baseWord in the event that std::abs(_n) != 1, otherwise it returns _baseWord.

Parameters
[in]_baseWordthe singular version of the word to return
[in]_nthe quantity that _baseWord is describing
Returns
_baseWord if std::abs(_n)==1, otherwise return _baseWords

◆ PluralCast() [2/2]

std::string ignition::common::PluralCast ( const std::string _singular,
const std::string _plural,
const int  _n 
)

A version of PluralCast that works for irregular nouns. If std::abs(_n)==1 then _singular is returned; otherwise _plural will be returned.

Parameters
[in]_singularthe return value when std::abs(_n) == 1
[in]_pluralthe return value when std::abs(_n) != 1
Returns
_singular if std::abs(_n)==1, otherwise return _plural

◆ removeAll()

bool ignition::common::removeAll ( const std::string _path,
const FilesystemWarningOp  _warningOp = FSWO_LOG_WARNINGS 
)

Remove a file or a directory and all its contents.

Parameters
[in]_pathPath to a directory or file.
[in]_warningOpLog or suppress warnings that may occur.
Returns
True if _path was removed.

Referenced by joinPaths().

◆ removeDirectory()

bool ignition::common::removeDirectory ( const std::string _path,
const FilesystemWarningOp  _warningOp = FSWO_LOG_WARNINGS 
)

Remove an empty directory.

Remarks
the directory must be empty to be removed
Parameters
[in]_pathPath to a directory.
[in]_warningOpLog or suppress warnings that may occur.
Returns
True if _path is a directory and was removed.

Referenced by joinPaths().

◆ removeDirectoryOrFile()

bool ignition::common::removeDirectoryOrFile ( const std::string _path,
const FilesystemWarningOp  _warningOp = FSWO_LOG_WARNINGS 
)

Remove an empty directory or file.

Parameters
[in]_pathPath to a directory or file.
[in]_warningOpLog or suppress warnings that may occur.
Returns
True if _path was removed.

Referenced by joinPaths().

◆ removeFile()

bool ignition::common::removeFile ( const std::string _existingFilename,
const FilesystemWarningOp  _warningOp = FSWO_LOG_WARNINGS 
)

Remove a file.

Parameters
[in]_existingFilenameFull path to an existing file.
[in]_warningOpLog or suppress warnings that may occur.
Returns
True on success.

Referenced by joinPaths().

◆ replaceAll() [1/2]

void ignition::common::replaceAll ( std::string _result,
const std::string _orig,
const std::string _key,
const std::string _replacement 
)

Replace all occurances of _key with _replacement.

Parameters
[out]_resultThe new string that has had _key replaced with _replacement.
[in]_origOriginal string.
[in]_keyString to replace.
[in]_replacementThe string that replaces _key.
See also
std::string replaceAll(const std::string &_orig, const std::string &_key, const std::string &_replacement)

Referenced by hash64().

◆ replaceAll() [2/2]

std::string ignition::common::replaceAll ( const std::string _orig,
const std::string _key,
const std::string _replacement 
)

Replace all occurances of _key with _replacement.

Parameters
[in]_origOriginal string.
[in]_keyString to replace.
[in]_replacementThe string that replaces _key.
Returns
The new string that has had _key replaced with _replacement.
See also
void common::replaceAll(std::string &_result, const std::string &_orig, const std::string &_key, const std::string &_replacement)

◆ rtrim()

void ignition::common::rtrim ( std::string _s)

In place right trim.

Parameters
[in,out]_sString to trim

Referenced by hash64().

◆ rtrimmed()

std::string ignition::common::rtrimmed ( std::string  _s)

Copying right trim.

Parameters
[in]_sString to trim
Returns
Trimmed string

Referenced by hash64().

◆ separator()

std::string const ignition::common::separator ( std::string const &  _s)

Append the preferred path separator character for this platform onto the passed-in string.

Parameters
[in]_sThe path to start with.
Returns
The original path with the platform path separator appended.

◆ setenv()

bool ignition::common::setenv ( const std::string _name,
const std::string _value 
)

Set the environment variable '_name'.

Note that on Windows setting an empty string (_value=="") is the equivalent of unsetting the variable.

Parameters
[in]_nameName of the environment variable.
[in]_valueValue of the variable to be set.
Returns
True if the variable was set or false otherwise.

Referenced by hash64().

◆ sha1() [1/2]

std::string ignition::common::sha1 ( const T &  _buffer)

Compute the SHA1 hash of an array of bytes.

Parameters
[in]_bufferInput sequence. The permitted data types for this function are std::string and any STL container.
Returns
The string representation (40 character) of the SHA1 hash.

References sha1().

Referenced by sha1().

◆ sha1() [2/2]

std::string ignition::common::sha1 ( void const *  _buffer,
std::size_t  _byteCount 
)

Compute the SHA1 hash of an array of bytes. Use std::string sha1(const T &_buffer) instead of this function.

Parameters
[in]_bufferInput sequence. The permitted data types for this function are std::string and any STL container.
Returns
The string representation (40 character) of the SHA1 hash.
See also
sha1(const T &_buffer)

◆ Split()

std::vector<std::string> ignition::common::Split ( const std::string _orig,
char  _delim 
)

split at a one character delimiter to get a vector of something

Parameters
[in]_origThe string to split
[in]_delima character to split the string at
Returns
vector of split pieces of the string excluding the delimiter

◆ split()

std::vector<std::string> ignition::common::split ( const std::string _str,
const std::string _delim 
)

Splits a string into tokens.

Parameters
[in]_strInput string.
[in]_delimToken delimiter.
Returns
Vector of tokens.

Referenced by hash64().

◆ StartsWith()

bool ignition::common::StartsWith ( const std::string _s1,
const std::string _s2 
)

return true if string starts with another string

Parameters
[in]_s1the string to check
[in]_s2the possible prefix
Returns
true if _s1 starts with _s2

◆ systemPaths()

common::SystemPaths* ignition::common::systemPaths ( )

Get a pointer to the global system paths that is used by all the findFile functions. The returned instance has global shared state for a given process. Care should be taken when manipulating global system paths Caller should not assume ownership of the pointer.

Returns
A mutable reference to the system paths object.

◆ systemTimeISO()

std::string ignition::common::systemTimeISO ( )

Please use systemTimeIso() as this function will be deprecated in Ignition Common 4. Get the wall time as an ISO string: YYYY-MM-DDTHH:MM:SS.NS.

Returns
The current wall time as an ISO string.
See also
systemTimeIso();

◆ systemTimeIso()

std::string ignition::common::systemTimeIso ( )

Get the wall time as an ISO string: YYYY-MM-DDTHH:MM:SS.NS.

Returns
The current wall time as an ISO string.

◆ timeToIso()

std::string ignition::common::timeToIso ( const std::chrono::time_point< std::chrono::system_clock > &  _time)

Converts a time point to an ISO string: YYYY-MM-DDTHH:MM:SS.NS.

Parameters
[in]_timeA time point, such as one created by IGN_SYSTEM_TIME().
Returns
An ISO string that represents the given _time.

◆ trim()

void ignition::common::trim ( std::string _s)

In place trim from both ends.

Parameters
[in,out]_sString to trim

Referenced by hash64().

◆ trimmed()

std::string ignition::common::trimmed ( std::string  _s)

Copying trim from both ends.

Parameters
[in]_sString to trim
Returns
Trimmed string

Referenced by hash64().

◆ uniqueDirectoryPath()

std::string ignition::common::uniqueDirectoryPath ( const std::string _dir)

Unique directory path to not overwrite existing directory.

Parameters
[in]_pathAndNameFull absolute path
Returns
Full path which doesn't collide with existing files

Referenced by joinPaths().

◆ uniqueFilePath()

std::string ignition::common::uniqueFilePath ( const std::string _pathAndName,
const std::string _extension 
)

Generates a path for a file which doesn't collide with existing files, by appending numbers to it (i.e. (0), (1), ...)

Parameters
[in]_pathAndNameFull absolute path and file name up to the file extension.
[in]_extensionFile extension, such as "ddf".
Returns
Full path with name and extension, which doesn't collide with existing files

Referenced by joinPaths().

◆ unsetenv()

bool ignition::common::unsetenv ( const std::string _name)

Unset the environment variable '_name'.

Parameters
[in]_nameName of the environment variable.
Returns
True if the variable was unset or false otherwise.

Referenced by hash64().

◆ uuid()

std::string ignition::common::uuid ( )

Get a UUID.

Returns
A UUID string

Referenced by hash64().

Variable Documentation

◆ PixelFormatNames

std::string PixelFormatNames[]
static
Initial value:
=
{
"UNKNOWN_PIXEL_FORMAT",
"L_INT8",
"L_INT16",
"RGB_INT8",
"RGBA_INT8",
"BGRA_INT8",
"RGB_INT16",
"RGB_INT32",
"BGR_INT8",
"BGR_INT16",
"BGR_INT32",
"R_FLOAT16",
"RGB_FLOAT16",
"R_FLOAT32",
"RGB_FLOAT32",
"BAYER_RGGB8",
"BAYER_RGGR8",
"BAYER_GBRG8",
"BAYER_GRBG8",
"BAYER_BGGR8"
}

String names for the pixel formats.

See also
Image::PixelFormat.

◆ PLUGIN_API_VERSION

const int PLUGIN_API_VERSION = 1

sentinel value to check if a plugin was built with the same version of the PluginInfo struct

This must be incremented when the PluginInfo struct changes