JeVois  1.0
JeVois Smart Embedded Machine Vision Toolkit
Utils.H
Go to the documentation of this file.
1 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 //
3 // JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4 // California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5 //
6 // This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7 // redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8 // Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9 // without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10 // License for more details. You should have received a copy of the GNU General Public License along with this program;
11 // if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12 //
13 // Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14 // Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16 /*! \file */
17 
18 #pragma once
19 
20 #include <string>
21 #include <vector>
22 #include <type_traits> // for std::is_integral
23 
24 namespace jevois
25 {
26  /*! \defgroup utils Misc utilities
27 
28  Miscellaneous utility and helper functions. */
29 
30  /*! @{ */ // **********************************************************************
31 
32  //! Convert a V4L2 four-cc code (V4L2_PIX_FMT_...) to a 4-char string
33  std::string fccstr(unsigned int fcc);
34 
35  //! Return the number of bytes per pixel for a given V4L2_PIX_FMT_...
36  unsigned int v4l2BytesPerPix(unsigned int fcc);
37 
38  //! Return the image size in bytes for a given V4L2_PIX_FMT_..., width, height
39  unsigned int v4l2ImageSize(unsigned int fcc, unsigned int width, unsigned int height);
40 
41  //! Split string into vector of tokens using a regex to specify what to split on; default regex splits by whitespace
42  std::vector<std::string> split(std::string const & input, std::string const & regex = "\\s+");
43 
44  //! Concatenate a vector of tokens into a string
45  std::string join(std::vector<std::string> const & strings, std::string const & delimiter);
46 
47  //! Return true if str starts with prefix (including if both strings are equal)
48  /*! Note that if str is shorter than prefix, return is false (like in strncmp()). */
49  bool stringStartsWith(std::string const & str, std::string const & prefix);
50 
51  //! Create a string using printf style arguments
52  /*! Example:
53  @code
54  std::string s = nrt::sformat("MyString_%f_%d", 1.0, 2);
55  @endcode
56 
57  One should normally refrain from using sformat(), and instead use streaming operators of C++, one exception is
58  when issuing serial messages that have float numbers in them, the printf-like sytnax of sformat is useful to
59  quickly and easily specify a numerical precision. */
60  std::string sformat(char const * fmt, ...)
61  // NOTE: this __attribute__ tells gcc that it should issue printf-style warnings when compiling calls to sformat(),
62  // treating the 1st argument (fmt) as the format string, and the 2nd and subsequent arguments as the printf-style
63  // parameters
64  __attribute__((format(__printf__, 1, 2)));
65 
66  // Doxygen is not too good with enable_if, it only documents one version of the function. Here is a workaround:
67 #ifdef JEVOIS_DOXYGEN
68  //! Convert from string to a type
69  /*! For integral types, internally uses std::stoll() for that type, which supports prefixes like 0 (for octal) and 0x
70  (hex). Beware of that octal convention and do not pass leading zeros unless you mean it. For non-integral types,
71  internally uses operator>> for that type, so it works with any type that supports it. */
72  template <typename T> T from_string(std::string const & str);
73 #else
74  //! Convert from string to a type, version for non-integral types
75  /*! This internally uses operator>> for that type, so it works with any type that supports it. */
76  template <typename T>
77  typename std::enable_if< ! std::is_integral<T>::value, T>::type from_string(std::string const & str);
78 
79  //! Convert from string to a type, version for integral types
80  /*! This internally uses std::stoll() for that type, which supports prefixes like 0 (for octal) and 0x (hex). */
81  template <typename T>
82  typename std::enable_if<std::is_integral<T>::value, T>::type from_string(std::string const & str);
83 #endif
84 
85  //! Convert from type to string
86  /*! This internally uses operator>> for that type, so it works with any type that supports it. */
87  template <typename T>
88  std::string to_string(T const & val);
89 
90  //! Clamped numerical conversion
91  template <typename dest_type, typename source_type>
92  dest_type clamped_convert(source_type source);
93 
94  //! Flush the caches, may sometimes be useful when running the cemare in turbo mode
95  void flushcache();
96 
97  /*! @} */ // **********************************************************************
98 
99 } // namespace jevois
100 
101 
102 // ####################################################################################################
103 //! Helper macro to execute an ioctl, ignore interruptions, and, if error, issue a fatal message and throw
104 /*! \def XIOCTL(dev, req, mem)
105  \hideinitializer
106 
107  This macro assumes that req is an identifier (\#define) for the corresponding ioctl number.
108  \ingroup utils */
109 
110 // ####################################################################################################
111 //! Helper macro to execute an ioctl, ignore interruptions, and, if error throw quietly
112 /*! \def XIOCTL_QUIET(dev, req, mem)
113  \hideinitializer
114 
115  This is useful, e.g., for V4L2 camera enumeration of formats, where one is supposed to call an ioctl
116  with increasing format number until it fails. When that happens we don't want to display any fatal error
117  message as XIOCTL() does. This macro assumes that req is an identifier for the corresponding ioctl number.
118  \ingroup utils */
119 
120 // Include implementation details
dest_type clamped_convert(source_type source)
Clamped numerical conversion.
Definition: UtilsImpl.H:58
std::vector< std::string > split(std::string const &input, std::string const &regex="\\s+")
Split string into vector of tokens using a regex to specify what to split on; default regex splits by...
Definition: Utils.C:65
void flushcache()
Flush the caches, may sometimes be useful when running the cemare in turbo mode.
Definition: Utils.C:143
std::string sformat(char const *fmt,...) __attribute__((format(__printf__
Create a string using printf style arguments.
Definition: Utils.C:133
unsigned int v4l2BytesPerPix(unsigned int fcc)
Return the number of bytes per pixel for a given V4L2_PIX_FMT_...
Definition: Utils.C:45
std::string join(std::vector< std::string > const &strings, std::string const &delimiter)
Concatenate a vector of tokens into a string.
Definition: Utils.C:75
bool stringStartsWith(std::string const &str, std::string const &prefix)
Return true if str starts with prefix (including if both strings are equal)
Definition: Utils.C:89
std::string fccstr(unsigned int fcc)
Convert a V4L2 four-cc code (V4L2_PIX_FMT_...) to a 4-char string.
Definition: Utils.C:32
unsigned int v4l2ImageSize(unsigned int fcc, unsigned int width, unsigned int height)
Return the image size in bytes for a given V4L2_PIX_FMT_..., width, height.
Definition: Utils.C:61
std::string to_string(T const &val)
Convert from type to string.
Definition: UtilsImpl.H:51
std::string T from_string(std::string const &str)
Convert from string to a type.