JeVois  1.0
JeVois Smart Embedded Machine Vision Toolkit
ValidValuesSpec.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 // This code is inspired by the Neuromorphic Robotics Toolkit (http://nrtkit.org)
19 
20 #pragma once
21 
22 #include <vector>
23 #include <string>
24 #include <jevois/Types/Range.H>
25 #include <jevois/Types/StepRange.H>
26 #include <boost/regex.hpp>
27 
28 namespace jevois
29 {
30  /*! \defgroup validvalues Specification of sets of valid values, e.g., that some Parameter may take
31 
32  This is used by ParameterDef to specify valid values that a Parameter may take as unrestricted, from a given list,
33  in a range, matching a regex, etc
34 
35  \ingroup parameter */
36 
37  /*! @{ */ // **********************************************************************
38 
39  //! Base class for specifying a set of valid values for a type
40  /*! Note when defining new derived valid values specs: make sure you define operator<<() and also that the copy
41  constructor works as intended (which means that you may have to define it explicitly if your data members are
42  complicated). */
43  template <typename T>
45  {
46  public:
47  //! Construct, for the base class this is a no-op
48  /*! Note that we make the constructor explicit otherwise we get false hits against strings and what not in our
49  operator<< defined on various ValidValueSpec derivatives. */
50  explicit ValidValuesSpecBase();
51 
52  //! Destructor
53  virtual ~ValidValuesSpecBase();
54 
55  //! Check whether a proposed value is valid, return true if it is
56  virtual bool checkValueValidity(T const & val) const = 0;
57 
58  //! Convert the specification of valid values to a readable string
59  /*! Caution, a GUI may wish to parse this string so keep the format tight. Typically,
60  type:[valuesdescription], e.g., see derived classes for None:[], List:[A|B|C], etc. */
61  virtual std::string const str() const = 0;
62  };
63 
64  // ######################################################################
65  //! Open/None valid values spec, anything that T can take is valid
66  template <typename T>
68  {
69  public:
70  //! Construct with no specification, any value that T can take goes
71  explicit ValidValuesSpecNone();
72 
73  //! Destructor
74  virtual ~ValidValuesSpecNone();
75 
76  //! Check whether a proposed value is valid, here always returns true
77  virtual bool checkValueValidity(T const & val) const;
78 
79  //! Convert to a readable string
80  /*! Returns None:[] */
81  virtual std::string const str() const;
82  };
83 
84  // ######################################################################
85  //! Finite list valid values spec, everything listed at construction is valid, anything else is not
86  template <typename T>
88  {
89  public:
90  //! No default constructor, always need to provide a list
91  ValidValuesSpecList() = delete;
92 
93  //! Construct from a given list of valid values in a vector
94  explicit ValidValuesSpecList(std::vector<T> const & valid_list);
95 
96  //! Destructor
97  virtual ~ValidValuesSpecList();
98 
99  //! Check whether a proposed value is valid, returns true iff value is in our list
100  virtual bool checkValueValidity(T const & val) const;
101 
102  //! Convert to a readable string
103  /*! Returns List:[A|B|C] where A, B, C are replaced by the actual elements. */
104  virtual std::string const str() const;
105 
106  protected:
107  std::vector<T> const itsValidList; //!< Our list of valid values
108  };
109 
110  // ######################################################################
111  //! Range-based valid values spec, bounds are included
112  template <typename T>
114  {
115  public:
116  //! No default constructor, always need to provide a range
117  ValidValuesSpecRange() = delete;
118 
119  //! Construct from a Range of valid values (convention: bounds are inclusive)
120  explicit ValidValuesSpecRange(Range<T> const & valid_range);
121 
122  //! Destructor
123  virtual ~ValidValuesSpecRange();
124 
125  //! Check whether a proposed value is valid, returns true iff value is in our range (bounds included)
126  virtual bool checkValueValidity(T const & val) const;
127 
128  //! Convert to a readable string: Range:[MIN-MAX] where MIN and MAX are replaced by the actual range bounds.
129  virtual std::string const str() const;
130 
131  protected:
132  Range<T> const itsValidRange; //!< Our range of valid values
133  };
134 
135  // ######################################################################
136  //! StepRange-based valid values spec, bounds are included
137  template <typename T>
139  {
140  public:
141  //! No default constructor, always need to provide a range
142  ValidValuesSpecStepRange() = delete;
143 
144  //! Construct from a StepRange of valid values (convention: bounds are inclusive)
145  explicit ValidValuesSpecStepRange(StepRange<T> const & valid_range);
146 
147  //! Destructor
148  virtual ~ValidValuesSpecStepRange();
149 
150  //! Check whether a proposed value is valid, returns true iff value is in our range (bounds included)
151  virtual bool checkValueValidity(T const & val) const;
152 
153  //! Convert to a readable string: StepRange:[MIN-STEP-MAX] where MIN, STEP and MAX are replaced by actual values.
154  virtual std::string const str() const;
155 
156  protected:
157  StepRange<T> const itsValidStepRange; //!< Our step-range of valid values
158  };
159 
160  // ######################################################################
161  //! Regex-based valid values spec, everything that is a match to the regex is considered valid
162  /*! Uses boost::regex internally (because std::regex does not alow one to get the original string specification back
163  from the regex, but we need that to display help messages). This allows for highly flexible valid values
164  definitions. For example, say you want an int parameter to be in range [0..59] but it could also have value 72,
165  your regex would be:
166 
167  \verbatim
168  ^(([0-5]?[0-9])|72)$
169  \endverbatim
170 
171  You can find on the web regex examples to match things like a valid filename, a valid URL, a valid credit card
172  number, etc. Just make sure your regex is in the syntax expected by boost::regex since several syntaxes are
173  floating around for regular expressions. */
174  template <typename T>
176  {
177  public:
178  //! No default constructor, always need to provide a regex
179  ValidValuesSpecRegex() = delete;
180 
181  //! Construct from a given regex that specifies valid values
182  explicit ValidValuesSpecRegex(boost::regex const & valid_regex);
183 
184  //! Destructor
185  virtual ~ValidValuesSpecRegex();
186 
187  //! Check whether a proposed value is valid, returns true iff value is a match against our regex
188  virtual bool checkValueValidity(T const & val) const;
189 
190  //! Convert to a readable string
191  /*! Returns Regex:[expression] where expression is replaced by the actual regex. */
192  virtual std::string const str() const;
193 
194  protected:
195  boost::regex const itsValidRegex; //!< Th eregex that defines our valid values
196  };
197 
198  /*! @} */ // **********************************************************************
199 
200 } // namespace jevois
201 
202 // Include inlined implementation details that are of no interest to the end user
204 
205 
ValidValuesSpecRegex()=delete
No default constructor, always need to provide a regex.
virtual std::string const str() const
Convert to a readable string.
ValidValuesSpecRange()=delete
No default constructor, always need to provide a range.
A generic range class with a step.
Definition: StepRange.H:69
Base class for specifying a set of valid values for a type.
virtual bool checkValueValidity(T const &val) const
Check whether a proposed value is valid, returns true iff value is in our range (bounds included) ...
virtual ~ValidValuesSpecRange()
Destructor.
virtual bool checkValueValidity(T const &val) const
Check whether a proposed value is valid, here always returns true.
virtual bool checkValueValidity(T const &val) const
Check whether a proposed value is valid, returns true iff value is in our list.
ValidValuesSpecList()=delete
No default constructor, always need to provide a list.
virtual std::string const str() const
Convert to a readable string: Range:[MIN-MAX] where MIN and MAX are replaced by the actual range boun...
StepRange< T > const itsValidStepRange
Our step-range of valid values.
virtual ~ValidValuesSpecRegex()
Destructor.
Range-based valid values spec, bounds are included.
virtual ~ValidValuesSpecList()
Destructor.
std::vector< T > const itsValidList
Our list of valid values.
boost::regex const itsValidRegex
Th eregex that defines our valid values.
Finite list valid values spec, everything listed at construction is valid, anything else is not...
ValidValuesSpecBase()
Construct, for the base class this is a no-op.
Regex-based valid values spec, everything that is a match to the regex is considered valid...
virtual std::string const str() const
Convert to a readable string.
Open/None valid values spec, anything that T can take is valid.
StepRange-based valid values spec, bounds are included.
virtual std::string const str() const
Convert to a readable string.
Range< T > const itsValidRange
Our range of valid values.
ValidValuesSpecNone()
Construct with no specification, any value that T can take goes.
virtual bool checkValueValidity(T const &val) const
Check whether a proposed value is valid, returns true iff value is in our range (bounds included) ...
A generic range class.
Definition: Range.H:80
ValidValuesSpecStepRange()=delete
No default constructor, always need to provide a range.
virtual bool checkValueValidity(T const &val) const
Check whether a proposed value is valid, returns true iff value is a match against our regex...
virtual std::string const str() const
Convert to a readable string: StepRange:[MIN-STEP-MAX] where MIN, STEP and MAX are replaced by actual...
virtual ~ValidValuesSpecStepRange()
Destructor.
virtual ~ValidValuesSpecNone()
Destructor.
virtual ~ValidValuesSpecBase()
Destructor.
virtual std::string const str() const =0
Convert the specification of valid values to a readable string.
virtual bool checkValueValidity(T const &val) const =0
Check whether a proposed value is valid, return true if it is.