utils.h File Reference

Miscellaneous utility functions. More...

`#include <algorithm>`
`#include <chrono>`
`#include <memory>`
`#include <ostream>`
`#include <sstream>`
`#include <string>`
`#include <string.h>`
`#include <sys/time.h>`

Go to the source code of this file.

## Macros

#define | ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
| Determine the number of elements in the static array.

## Typedefs

using | libcamera::utils::clock = std::chrono::steady_clock
| The libcamera clock (monotonic)
using | libcamera::utils::duration = std::chrono::steady_clock::duration
| The libcamera duration related to libcamera::utils::clock.
using | libcamera::utils::time_point = std::chrono::steady_clock::time_point
| The libcamera time point related to libcamera::utils::clock.

## Functions

const char * | libcamera::utils::basename (const char *path)
| Strip the directory prefix from the path. More...
char * | libcamera::utils::secure_getenv (const char *name)
| Get an environment variable. More...
std::string | libcamera::utils::dirname (const std::string &path)
| Identify the dirname portion of a path. More...
template<class InputIt1 , class InputIt2 >
unsigned int | libcamera::utils::set_overlap (InputIt1 first1, InputIt1 last1, InputIt2 first2, InputIt2 last2)
| Count the number of elements in the intersection of two ranges. More...
template<typename T >
const T & | libcamera::utils::clamp (const T &v, const T &lo, const T &hi)
struct timespec | libcamera::utils::duration_to_timespec (const duration &value)
| Convert a duration to a timespec. More...
std::string | libcamera::utils::time_point_to_string (const time_point &time)
| Convert a time point to a string representation. More...
template<typename T >
_hex | libcamera::utils::hex (T value, unsigned int width=0)
| Write an hexadecimal value to an output string. More...
size_t | libcamera::utils::strlcpy (char *dst, const char *src, size_t size)
| Copy a string with a size limit. More...
template<typename Container , typename UnaryOp >
std::string | libcamera::utils::join (const Container &items, const std::string &sep, UnaryOp op=nullptr)
| Join elements of a container in a string with a separator. More...
details::StringSplitter | libcamera::utils::split (const std::string &str, const std::string &delim)
| Split a string based on a delimiter. More...
std::string | libcamera::utils::libcameraBuildPath ()
| Retrieve the path to the build directory. More...
std::string | libcamera::utils::libcameraSourcePath ()
| Retrieve the path to the source directory. More...

## Detailed Description

Miscellaneous utility functions.

## Function Documentation

## basename()

const char * libcamera::utils::basename | ( | const char * | path | ) |

Strip the directory prefix from the path.

Parameters

  [in] | path | The path to process

basename is implemented differently across different C libraries. This implementation matches the one provided by the GNU libc, and does not modify its input parameter.

Returns
  A pointer within the given path without any leading directory components.

## clamp()

template<typename T >

libcamera::utils::clamp | ( | const T & | v,
|  | const T & | lo,
|  | const T & | hi
| ) |  |

Parameters

  [in] | v | The value to clamp
  [in] | lo | The lower boundary to clamp v to
  [in] | hi | The higher boundary to clamp v to

Returns
  lo if v is less than lo, hi if v is greater than hi, otherwise v

## dirname()

std::string libcamera::utils::dirname | ( | const std::string & | path | ) |

Identify the dirname portion of a path.

Parameters

  [in] | path | The full path to parse

This function conforms with the behaviour of the dirname() function as defined by POSIX.

Returns
  A string of the directory component of the path

## duration_to_timespec()

struct timespec libcamera::utils::duration_to_timespec | ( | const duration & | value | ) |

Convert a duration to a timespec.

Parameters

  [in] | value | The duration

Returns
  A timespec expressing the duration

## hex()

template<typename T >

libcamera::utils::hex | ( | T | value,
|  | unsigned int | width = `0`
| ) |  |

Write an hexadecimal value to an output string.

Parameters

  value | The value
  width | The width

Return an object of unspecified type such that, if os is the name of an output stream of type std::ostream, and T is an integer type, then the expression

os << utils::hex(value)

will output the value to the stream in hexadecimal form with the base prefix and the filling character set to '0'. The field width is set to width if specified to a non-zero value, or to the native width of type T otherwise. The os stream configuration is not modified.

## join()

template<typename Container , typename UnaryOp >

template< typename Container, typename UnaryOp > std::string libcamera::utils::join | ( | const Container & | items,
|  | const std::string & | sep,
|  | UnaryOp | op = `nullptr`
| ) |  |

Join elements of a container in a string with a separator.

Parameters

  [in] | items | The container
  [in] | sep | The separator to add between elements
  [in] | op | A function that converts individual elements to strings

This function joins all elements in the items container into a string and returns it. The sep separator is added between elements. If the container elements are not implicitly convertible to std::string, the op function shall be provided to perform conversion of elements to std::string.

Returns
  A string that concatenates all elements in the container

## libcameraBuildPath()

std::string libcamera::utils::libcameraBuildPath | ( |  | ) |

Retrieve the path to the build directory.

During development, it is useful to run libcamera binaries directly from the build directory without installing them. This function helps components that need to locate resources in the build tree, such as IPA modules or IPA proxy workers, by providing them with the path to the root of the build directory. Callers can then use it to complement or override searches in system-wide directories.

If libcamera has been installed, the build directory path is not available and this function returns an empty string.

Returns
  The path to the build directory if running from a build, or an empty string otherwise

## libcameraSourcePath()

std::string libcamera::utils::libcameraSourcePath | ( |  | ) |

Retrieve the path to the source directory.

During development, it is useful to run libcamera binaries directly from the build directory without installing them. This function helps components that need to locate resources in the source tree, such as IPA configuration files, by providing them with the path to the root of the source directory. Callers can then use it to complement or override searches in system-wide directories.

If libcamera has been installed, the source directory path is not available and this function returns an empty string.

Returns
  The path to the source directory if running from a build directory, or an empty string otherwise

## secure_getenv()

char * libcamera::utils::secure_getenv | ( | const char * | name | ) |

Get an environment variable.

Parameters

  [in] | name | The name of the variable to return

The environment list is searched to find the variable 'name', and the corresponding string is returned.

If 'secure execution' is required then this function always returns NULL to avoid vulnerabilities that could occur if set-user-ID or set-group-ID programs accidentally trust the environment.

Returns
  A pointer to the value in the environment or NULL if the requested environment variable doesn't exist or if secure execution is required.

## set_overlap()

template<class InputIt1 , class InputIt2 >

libcamera::utils::set_overlap | ( | InputIt1 | first1,
|  | InputIt1 | last1,
|  | InputIt2 | first2,
|  | InputIt2 | last2
| ) |  |

Count the number of elements in the intersection of two ranges.

Count the number of elements in the intersection of the sorted ranges [first1, last1) and [first1, last2). Elements are compared using operator< and the ranges must be sorted with respect to the same.

Returns
  The number of elements in the intersection of the two ranges

## split()

details::StringSplitter libcamera::utils::split | ( | const std::string & | str,
|  | const std::string & | delim
| ) |  |

Split a string based on a delimiter.

Parameters

  [in] | str | The string to split
  [in] | delim | The delimiter string

This function splits the string str into substrings based on the delimiter delim. It returns an object of unspecified type that can be used in a range-based for loop and yields the substrings in sequence.

Returns
  An object that can be used in a range-based for loop to iterate over the substrings

Todo:
  Try to avoid copies of str and delim

Todo:
  Try to avoid copies of str and delim

## strlcpy()

size_t libcamera::utils::strlcpy | ( | char * | dst,
|  | const char * | src,
|  | size_t | size
| ) |  |

Copy a string with a size limit.

Parameters

  [in] | dst | The destination string
  [in] | src | The source string
  [in] | size | The size of the destination string

This function copies the null-terminated string src to dst with a limit of size - 1 characters, and null-terminates the result if size is larger than 0. If src is larger than size - 1, dst is truncated.

Returns
  The size of src

## time_point_to_string()

std::string libcamera::utils::time_point_to_string | ( | const time_point & | time | ) |

Convert a time point to a string representation.

Parameters

  [in] | time | The time point

Returns
  A string representing the time point in hh:mm:ss.nanoseconds format