JeVois  1.20
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
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
203 #include <jevois/Component/details/ValidValuesSpecImpl.H>
204 
205 
jevois::ValidValuesSpecNone::ValidValuesSpecNone
ValidValuesSpecNone()
Construct with no specification, any value that T can take goes.
jevois::ValidValuesSpecStepRange::str
virtual const std::string str() const
Convert to a readable string: StepRange:[MIN-STEP-MAX] where MIN, STEP and MAX are replaced by actual...
jevois::Range
A generic range class.
Definition: Range.H:80
jevois::ValidValuesSpecBase::checkValueValidity
virtual bool checkValueValidity(T const &val) const =0
Check whether a proposed value is valid, return true if it is.
jevois::ValidValuesSpecRange::str
virtual const std::string str() const
Convert to a readable string: Range:[MIN-MAX] where MIN and MAX are replaced by the actual range boun...
jevois::ValidValuesSpecNone
Open/None valid values spec, anything that T can take is valid.
Definition: ValidValuesSpec.H:67
jevois::ValidValuesSpecRegex::str
virtual const std::string str() const
Convert to a readable string.
jevois::ValidValuesSpecBase::str
virtual const std::string str() const =0
Convert the specification of valid values to a readable string.
jevois::ValidValuesSpecList::checkValueValidity
virtual bool checkValueValidity(T const &val) const
Check whether a proposed value is valid, returns true iff value is in our list.
jevois::ValidValuesSpecRange
Range-based valid values spec, bounds are included.
Definition: ValidValuesSpec.H:113
jevois::ValidValuesSpecList::itsValidList
const std::vector< T > itsValidList
Our list of valid values.
Definition: ValidValuesSpec.H:107
jevois::ValidValuesSpecList::str
virtual const std::string str() const
Convert to a readable string.
StepRange.H
jevois::StepRange
A generic range class with a step.
Definition: StepRange.H:69
jevois::ValidValuesSpecList::~ValidValuesSpecList
virtual ~ValidValuesSpecList()
Destructor.
jevois::ValidValuesSpecStepRange
StepRange-based valid values spec, bounds are included.
Definition: ValidValuesSpec.H:138
jevois::ValidValuesSpecRegex::itsValidRegex
const boost::regex itsValidRegex
Th eregex that defines our valid values.
Definition: ValidValuesSpec.H:195
jevois::ValidValuesSpecRange::ValidValuesSpecRange
ValidValuesSpecRange()=delete
No default constructor, always need to provide a range.
jevois
Definition: Concepts.dox:1
Range.H
jevois::ValidValuesSpecStepRange::checkValueValidity
virtual bool checkValueValidity(T const &val) const
Check whether a proposed value is valid, returns true iff value is in our range (bounds included)
jevois::ValidValuesSpecStepRange::~ValidValuesSpecStepRange
virtual ~ValidValuesSpecStepRange()
Destructor.
jevois::ValidValuesSpecRegex::checkValueValidity
virtual bool checkValueValidity(T const &val) const
Check whether a proposed value is valid, returns true iff value is a match against our regex.
jevois::ValidValuesSpecStepRange::itsValidStepRange
const StepRange< T > itsValidStepRange
Our step-range of valid values.
Definition: ValidValuesSpec.H:157
jevois::ValidValuesSpecBase
Base class for specifying a set of valid values for a type.
Definition: ValidValuesSpec.H:44
jevois::ValidValuesSpecRegex
Regex-based valid values spec, everything that is a match to the regex is considered valid.
Definition: ValidValuesSpec.H:175
jevois::ValidValuesSpecList
Finite list valid values spec, everything listed at construction is valid, anything else is not.
Definition: ValidValuesSpec.H:87
jevois::ValidValuesSpecStepRange::ValidValuesSpecStepRange
ValidValuesSpecStepRange()=delete
No default constructor, always need to provide a range.
jevois::ValidValuesSpecList::ValidValuesSpecList
ValidValuesSpecList()=delete
No default constructor, always need to provide a list.
jevois::ValidValuesSpecNone::checkValueValidity
virtual bool checkValueValidity(T const &val) const
Check whether a proposed value is valid, here always returns true.
jevois::ValidValuesSpecRange::checkValueValidity
virtual bool checkValueValidity(T const &val) const
Check whether a proposed value is valid, returns true iff value is in our range (bounds included)
jevois::ValidValuesSpecNone::~ValidValuesSpecNone
virtual ~ValidValuesSpecNone()
Destructor.
jevois::ValidValuesSpecRange::~ValidValuesSpecRange
virtual ~ValidValuesSpecRange()
Destructor.
jevois::ValidValuesSpecRegex::~ValidValuesSpecRegex
virtual ~ValidValuesSpecRegex()
Destructor.
jevois::ValidValuesSpecRange::itsValidRange
const Range< T > itsValidRange
Our range of valid values.
Definition: ValidValuesSpec.H:132
jevois::ValidValuesSpecBase::~ValidValuesSpecBase
virtual ~ValidValuesSpecBase()
Destructor.
jevois::ValidValuesSpecNone::str
virtual const std::string str() const
Convert to a readable string.
jevois::ValidValuesSpecBase::ValidValuesSpecBase
ValidValuesSpecBase()
Construct, for the base class this is a no-op.
jevois::ValidValuesSpecRegex::ValidValuesSpecRegex
ValidValuesSpecRegex()=delete
No default constructor, always need to provide a regex.