Miscellaneous utility functions. More...

#include <algorithm>
#include <chrono>
#include <iterator>
#include <memory>
#include <ostream>
#include <sstream>
#include <string>
#include <string.h>
#include <sys/time.h>
#include <type_traits>
#include <utility>
#include <vector>
#include <libcamera/base/private.h>

Include dependency graph for utils.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	libcamera::utils::Duration
	Helper class from std::chrono::duration that represents a time duration in nanoseconds with double precision. More...

Namespaces
	libcamera
	Top-level libcamera namespace.

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<typename T >
std::vector< typename T::key_type >	libcamera::utils::map_keys (const T &map)
	Retrieve the keys of a std::map<> 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...

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 , std::enable_if_t< std::is_integral< T >::value > * = nullptr>
_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::toAscii (const std::string &str)
	Remove any non-ASCII characters from a string. 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...

constexpr unsigned int	libcamera::utils::alignDown (unsigned int value, unsigned int alignment)
	Align value down to alignment. More...

constexpr unsigned int	libcamera::utils::alignUp (unsigned int value, unsigned int alignment)
	Align value up to alignment. More...

template<typename T >
details::reverse_adapter< T >	libcamera::utils::reverse (T &&iterable)
	Wrap an iterable to reverse iteration in a range-based loop. More...

template<typename T >
auto	libcamera::utils::enumerate (T &iterable) -> details::enumerate_adapter< decltype(iterable.begin())>
	Wrap an iterable to enumerate index and value in a range-based loop. More...

template<typename T >
decltype(auto)	libcamera::utils::abs_diff (const T &a, const T &b)
	Calculates the absolute value of the difference between two elements. More...

double	libcamera::utils::strtod (const char __restrict nptr, char *__restrict endptr)
	Convert a string to a double independently of the current locale. More...

template<class Enum >
constexpr std::underlying_type_t< Enum >	libcamera::utils::to_underlying (Enum e) noexcept
	Convert an enumeration to its underlygin type. More...

Detailed Description

Miscellaneous utility functions.

Function Documentation

◆ abs_diff()

template<typename T >

libcamera::utils::abs_diff	(	const T &	a,
		const T &	b
	)

Calculates the absolute value of the difference between two elements.

Parameters

[in]	a	The first element
[in]	b	The second element

This function calculates the absolute value of the difference between two elements of the same type, in such a way that a negative value will never occur during the calculation.

This is inspired by the std::abs_diff() candidate proposed in N4318 (http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4318.pdf).

Returns: The absolute value of the difference of the two parameters a and b

◆ alignDown()

libcamera::utils::alignDown	(	unsigned int	value,
		unsigned int	alignment
	)

Align value down to alignment.

Parameters

[in]	value	The value to align
[in]	alignment	The alignment

Returns: The value rounded down to the nearest multiple of alignment

◆ alignUp()

libcamera::utils::alignUp	(	unsigned int	value,
		unsigned int	alignment
	)

Align value up to alignment.

Parameters

[in]	value	The value to align
[in]	alignment	The alignment

Returns: The value rounded up to the nearest multiple of alignment

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

◆ 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

◆ enumerate()

template<typename T >

libcamera::utils::enumerate ( T & iterable ) -> details::enumerate_adapter<decltype(iterable.begin())>

Wrap an iterable to enumerate index and value in a range-based loop.

Parameters

[in] iterable The iterable

Range-based for loops are handy and widely preferred in C++, but are limited in their ability to replace for loops that require access to a loop counter. The enumerate() function solves this problem by wrapping the iterable in an adapter that, when used as a range-expression, will provide iterators whose value_type is a pair of index and value reference.

The iterable must support std::begin() and std::end(). This includes all containers provided by the standard C++ library, as well as C-style arrays.

A typical usage pattern would use structured binding to store the index and value in two separate variables:

std::vector<int> values = ...;
for (auto [index, value] : utils::enumerate(values)) {
    ...
}

Note that the argument to enumerate() has to be an lvalue, as the lifetime of any rvalue would not be extended to the whole for loop. The compiler will complain if an rvalue is passed to the function, in which case it should be stored in a local variable before the loop.

Returns: A value of unspecified type that, when used in a range-based for loop, iterates over an indexed view of the iterable

◆ hex()

template<typename T , std::enable_if_t< std::is_integral< T >::value > * = nullptr>

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

◆ map_keys()

template<typename T >

std::vector< typename T::key_type > libcamera::utils::map_keys ( const T & map )

Retrieve the keys of a std::map<>

Parameters

[in] map The map whose keys to retrieve

Returns: A std::vector<> containing the keys of map

◆ reverse()

template<typename T >

libcamera::utils::reverse ( T && iterable )

Wrap an iterable to reverse iteration in a range-based loop.

Parameters

[in] iterable The iterable

Returns: A value of unspecified type that, when used in a range-based for loop, will cause the loop to iterate over the iterable in reverse order

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

Note: Not all platforms may support the features required to implement the secure execution check, in which case this function behaves as getenv(). A notable example of this is Android.

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

◆ strtod()

double libcamera::utils::strtod	(	const char *__restrict	nptr,
		char **__restrict	endptr
	)

Convert a string to a double independently of the current locale.

Parameters

[in]	nptr	The string to convert
[out]	endptr	Pointer to trailing portion of the string after conversion

This function is a locale-independent version of the std::strtod() function. It behaves as the standard function, but uses the "C" locale instead of the current locale.

Returns: The converted value, if any, or 0.0 if the conversion failed.

◆ 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

◆ to_underlying()

template<class Enum >

libcamera::utils::to_underlying ( Enum e )

noexcept

Convert an enumeration to its underlygin type.

Parameters

[in] e Enumeration value to convert

This function is equivalent to the C++23 std::to_underlying().

Returns: The value of e converted to its underlying type

◆ toAscii()

std::string libcamera::utils::toAscii ( const std::string & str )

Remove any non-ASCII characters from a string.

Parameters

[in] str The string to strip

Remove all non-ASCII characters from a string.

Returns: A string equal to str stripped out of all non-ASCII characters

Classes

Namespaces

Typedefs

Functions

Detailed Description

Function Documentation

◆ abs_diff()

◆ alignDown()

◆ alignUp()

◆ basename()

◆ dirname()

◆ duration_to_timespec()

◆ enumerate()

◆ hex()

◆ join()

◆ libcameraBuildPath()

◆ libcameraSourcePath()

◆ map_keys()

◆ reverse()

◆ secure_getenv()

◆ set_overlap()

◆ split()

◆ strlcpy()

◆ strtod()

◆ time_point_to_string()

◆ to_underlying()

◆ toAscii()