/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef C2UTILS_INTERFACE_UTILS_H_
#define C2UTILS_INTERFACE_UTILS_H_
#include <C2Param.h>
#include <C2Work.h>
#include <cmath>
#include <iterator>
#include <limits>
#include <type_traits>
/**
* Helper class to map underlying types to C2Value types as well as to print field values. This is
* generally the same as simply the underlying type except for characters (STRING) and bytes (BLOB).
*/
template<typename T>
struct C2_HIDE _C2FieldValueHelper {
typedef T ValueType;
inline static std::ostream& put(std::ostream &os, const C2Value::Primitive &p) {
return os << p.ref<T>();
}
};
template<>
struct C2_HIDE _C2FieldValueHelper<uint8_t> {
typedef uint32_t ValueType;
static std::ostream& put(std::ostream &os, const C2Value::Primitive &p);
};
template<>
struct C2_HIDE _C2FieldValueHelper<char> {
typedef int32_t ValueType;
static std::ostream& put(std::ostream &os, const C2Value::Primitive &p);
};
/**
* Supported value range utility for a field of a given type.
*
* This mimics C2FieldSupportedValue for RANGE type.
*/
template<typename T>
class C2SupportedRange {
typedef typename _C2FieldValueHelper<T>::ValueType ValueType;
//private:
constexpr static T MIN_VALUE = std::numeric_limits<T>::min();
constexpr static T MAX_VALUE = std::numeric_limits<T>::max();
constexpr static T MIN_STEP = std::is_floating_point<T>::value ? 0 : 1;
public:
/**
* Constructs an empty range with no supported values.
*
* \note This is a specializated supported range representation that is only used for
* this object - it is equivalent to the EMPTY type in C2FieldSupportedValues.
*/
inline static constexpr C2SupportedRange<T> None() {
return C2SupportedRange(MAX_VALUE, MIN_VALUE);
}
/**
* Constructs a range with all values supported.
*/
inline static constexpr C2SupportedRange<T> Any() {
return C2SupportedRange(MIN_VALUE, MAX_VALUE);
}
/**
* Constructs a range with a single supported value.
*
* \param value the sole supported value
*/
inline static constexpr C2SupportedRange<T> EqualTo(T value) {
return C2SupportedRange(value, value);
}
/**
* Constructs a range with supported values greater than a given value.
*
* \param value the given value
*/
inline static C2SupportedRange<T> GreaterThan(T value) {
return (value == MAX_VALUE ? None() :
std::is_floating_point<T>::value ?
C2SupportedRange(std::nextafter(value, MAX_VALUE), MAX_VALUE) :
C2SupportedRange(value + MIN_STEP, MAX_VALUE));
}
/**
* Constructs a range with supported values greater than or equal to a given value.
*
* \param value the given value
*/
inline static constexpr C2SupportedRange<T> GreaterThanOrEqualTo(T value) {
return C2SupportedRange(value, MAX_VALUE);
}
/**
* Constructs a range with supported values greater than or equal to (aka not less than) a given
* value.
*
* \param value the given value
*/
inline static constexpr C2SupportedRange<T> NotLessThan(T value) {
return GreaterThanOrEqualTo(value);
}
/**
* Constructs a range with supported values less than or equal to a given value.
*
* \param value the given value
*/
inline static constexpr C2SupportedRange<T> LessThanOrEqualTo(T value) {
return C2SupportedRange(MIN_VALUE, value);
}
/**
* Constructs a range with supported values less than or equal to (aka not greater than) a given
* value.
*
* \param value the given value
*/
inline static constexpr C2SupportedRange<T> NotGreaterThan(T value) {
return LessThanOrEqualTo(value);
}
/**
* Constructs a range with supported values less than a given value.
*
* \param value the given value
*/
inline static C2SupportedRange<T> LessThan(T value) {
return (value == MIN_VALUE ? None() :
std::is_floating_point<T>::value ?
C2SupportedRange(MIN_VALUE, std::nextafter(value, MIN_VALUE)) :
C2SupportedRange(MIN_VALUE, value - MIN_STEP));
}
/**
* Constructs a continuous or arithmetic range between two values.
*
* \param min the lower value
* \param max the higher value (if this is lower than |min| the range will be empty)
* \param step the step of the arithmetic range. (If this is 0 for floating point types or 1 for
* integer types, the constructed range is continuous)
*/
inline static constexpr
C2SupportedRange<T> InRange(T min, T max, T step = MIN_STEP) {
return C2SupportedRange(min, max, step);
}
/**
* Constructs a range over a geometric series between two values.
*
* \param min the lower bound of the range. This value is always part of the constructed range
* as long as it is not greater than |max|.
* \param max the upper bound of the range. This value is only part of the constructed
* range if it is part of the geometric series.
* \param num the numerator of the geometric series.
* \param denom the denominator of the geometric series.
*/
inline static constexpr
C2SupportedRange<T> InSeries(T min, T max, T num, T denom) {
return C2SupportedRange(min, max, 0, num, denom);
}
/**
* Constructs a range over a multiply-accumulate series between two values.
*
* \param min the lower bound of the range. This value is always part of the constructed range
* as long as it is not greater than |max|.
* \param max the upper bound of the range. This value is only part of the constructed
* range if it is part of the series.
* \param step the accumulator of the multiply-accumulate series
* \param num the numerator of the multiply-accumulate series.
* \param denom the denominator of the multiply-accumulate series.
*/
inline static constexpr
C2SupportedRange<T> InMacSeries(T min, T max, T step, T num, T denom) {
return C2SupportedRange(min, max, step, num, denom);
}
/**
* Constructs a range from a generic C2FieldSupportedValues object. This will be an empty
* range if the supported values are not of RANGE type.
*
* \param values the supported values object
*/
C2SupportedRange(const C2FieldSupportedValues &values);
/**
* Returns whether this range is empty.
*/
inline constexpr bool isEmpty() const {
return _mMin > _mMax;
}
/**
* Returns whether this range is valid.
*
* Ranges are valid if they are continuous or monotonic.
*/
inline constexpr bool isValid() const {
// TODO: handle overflow or negative series
return _mDenom > 0 && _mNum >= _mDenom && _mMin * (_mDenom - _mNum) < _mStep * _mDenom;
}
/**
* Returns whether a value is part of this range.
*
* \param value the value to check.
*/
bool contains(T value) const;
/**
* Returns a new range that is the intersection of this range and another, if it is
* representable as a range object.
*
* \param limit the other range
*/
C2SupportedRange<T> limitedTo(const C2SupportedRange<T> &limit) const;
/**
* Converts this object to a C2FieldSupportedValues object.
*/
inline operator C2FieldSupportedValues() const {
return C2FieldSupportedValues(_mMin, _mMax, _mStep, _mNum, _mDenom);
}
/**
* Returns the lower bound and starting point of this range.
*/
inline C2_HIDE constexpr T min() const { return _mMin; }
/**
* Returns the upper bound of this range.
*/
inline C2_HIDE constexpr T max() const { return _mMax; }
/**
* Returns the step of this range.
*/
inline C2_HIDE constexpr T step() const { return _mStep; }
/**
* Returns the numerator of this range.
*/
inline C2_HIDE constexpr T num() const { return _mNum; }
/**
* Returns the denominator of this range.
*/
inline C2_HIDE constexpr T denom() const { return _mDenom; }
private:
/**
* Returns whether x[i...] is all values between _mMin and _mMax.
*/
inline C2_HIDE constexpr bool isSimpleRange() const {
return _mStep == MIN_STEP && _mNum == 1 && _mDenom == 1;
}
/**
* Returns whether x[i...] is defined as such:
* x[i + 1] = x[i] + _mStep, where _mStep > 0 and _mMin <= x[i] <= _mMax
*/
inline C2_HIDE constexpr bool isArithmeticSeries() const {
return _mStep > MIN_STEP && _mNum == 1 && _mDenom == 1;
}
/**
* Returns whether x[i...] is defined as such:
* x[i] = x[0] * (_mNum / _mDenom) ^ i (with rounding), where _mNum > _mDenom > 0 and x[0] > 0
*/
inline C2_HIDE constexpr bool isGeometricSeries() const {
return _mMin > 0 && _mStep == 0 && _mNum > _mDenom && _mDenom > 0;
}
/**
* Returns whether x[i...] is defined as such:
* x[i + 1] = x[i] * _mNum / _mDenom + _mStep (with rounding), while x[i + 1] > x[i], where
* _mStep != 0, _mDenom > 0 and _mNum > 0
*/
inline C2_HIDE constexpr bool isMacSeries() const {
return _mStep != 0 && _mNum > 0 && _mDenom > 0;
}
/**
* Constructs an arithmetic or continuous range.
*
* \param min the lower value
* \param max the higher value (if this is lower than |min| the range will be empty)
* \param step the step of the arithmetic range. (If this is 0 for floating point types or 1 for
* integer types, the constructed range is continuous)
*/
constexpr C2_HIDE C2SupportedRange(T min, T max, T step = T(std::is_floating_point<T>::value ? 0 : 1))
: _mMin(min), _mMax(max), _mStep(step), _mNum(1), _mDenom(1) { }
/**
* Constructs a range over a geomertic sor multiply-accumulate series.
*
* \param min the lower bound of the range. This value is always part of the constructed range
* as long as it is not greater than |max|.
* \param max the upper bound of the range. This value is only part of the constructed
* range if it is part of the geometric series.
* \param step the accumulator of the multiply-accumulate series. This is 0 for a pure geometric
* series
* \param num the numerator of the geometric series.
* \param denom the denominator of the geometric series.
*/
constexpr C2_HIDE C2SupportedRange(T min, T max, T step, T num, T den)
: _mMin(min), _mMax(max), _mStep(step), _mNum(num), _mDenom(den) { }
T _mMin; ///< lower bound and starting point
T _mMax; ///< upper bound
T _mStep; ///< step of an arithmetic series (0 if continuous floating point range)
T _mNum; ///< numerator of a geometric series
T _mDenom; ///< denominator of a geometric series
};
/**
* Ordered supported flag set for a field of a given type.
*/
template<typename T>
class C2SupportedFlags {
typedef typename _C2FieldValueHelper<T>::ValueType ValueType;
public:
/**
* Constructs an empty flag set.
*
* \note This is a specializated supported flags representation that is only used for
* this object - it is equivalent to the EMPTY type in C2FieldSupportedValues.
*/
static inline C2SupportedFlags<T> None() {
return C2SupportedFlags(std::initializer_list<C2Value::Primitive>());
}
/**
* Constructs a flags set of given flags.
*
* \param flags the ordered set of flags as an initializer list.
* \param min minimum set of flags to be set.
*/
static inline C2SupportedFlags<T> Flags(const std::initializer_list<T> flags, T min = T(0)) {
return C2SupportedFlags(min, flags);
}
/**
* Constructs a flags set of given flags.
*
* \param flags the ordered set of flags.
* \param min minimum set of flags to be set.
*/
static inline C2SupportedFlags<T> Flags(const std::vector<T> &flags, T min = T(0)) {
return C2SupportedFlags(min, flags);
}
/**
* Constructs a flag set from a generic C2FieldSupportedValues object. This will be an empty
* set if the supported values are not of FLAGS type.
*
* \param values the supported values object
*/
C2SupportedFlags<T>(const C2FieldSupportedValues &values) {
if (values.type == C2FieldSupportedValues::FLAGS) {
_mValues.insert(_mValues.end(), values.values.begin(), values.values.end());
}
}
/**
* Returns whether this set is empty.
*/
constexpr bool isEmpty() const {
return _mValues.empty();
}
/**
* Returns whether a value is part of this set.
*
* \param value the value to check.
*/
bool contains(T value) const;
/**
* Returns a new flag set that is the intersection of this set and another.
*
* \param limit the other value set
*/
C2SupportedFlags<T> limitedTo(const C2SupportedFlags<T> &limit) const;
/**
* Converts this object to a C2FieldSupportedValues object.
*/
operator C2FieldSupportedValues() const {
return C2FieldSupportedValues(!isEmpty() /* flags */, _mValues);
}
/**
* Returns the ordered set of flags of this object.
*/
const std::vector<T> flags() const;
/**
* Returns the minimum set of flags for this object.
*/
T min() const;
/**
* Clears this supported value set.
*/
inline void clear() {
_mValues.clear();
}
private:
/**
* Constructs a flag set directly from an internal representation.
*
* \param values a vector containing the minimum flag set followed by the set of flags
*/
C2SupportedFlags(std::vector<C2Value::Primitive> &&values)
: _mValues(values) {
}
/**
* Constructs a flag set from a set of flags and a minimum flag set.
*
* \param flags the set
*/
C2SupportedFlags(T min, const std::vector<T> &flags) {
_mValues.emplace_back(min);
for (T elem : flags) {
_mValues.emplace_back(elem);
}
}
/**
* Constructs a flag set from a set of initializer list values and a minimum flag set
*
* \param flags the set
*/
C2SupportedFlags(T min, const std::initializer_list<T> flags) {
_mValues.emplace_back(min);
for (T elem : flags) {
_mValues.emplace_back(elem);
}
}
std::vector<C2Value::Primitive> _mValues; ///< the minimum flag set followed by the set of flags
};
/**
* Ordered supported value set for a field of a given type.
*/
template<typename T>
class C2SupportedValueSet {
typedef typename _C2FieldValueHelper<T>::ValueType ValueType;
public:
/**
* Constructs an empty value set.
*
* \note This is a specializated supported range representation that is only used for
* this object - it is equivalent to the EMPTY type in C2FieldSupportedValues.
*/
static inline C2SupportedValueSet<T> None() {
return C2SupportedValueSet({ });
}
/**
* Constructs a value set of given values.
*
* \param values the ordered set of values as an initializer list.
*/
static inline C2SupportedValueSet<T> OneOf(const std::initializer_list<T> values) {
return C2SupportedValueSet(values);
}
/**
* Constructs a value set of given values.
*
* \param values the ordered set of values.
*/
static inline C2SupportedValueSet<T> OneOf(const std::vector<T> &values) {
return C2SupportedValueSet(values);
}
/**
* Constructs a value set from a generic C2FieldSupportedValues object. This will be an empty
* set if the supported values are not of VALUES type.
*
* \param values the supported values object
*/
C2SupportedValueSet<T>(const C2FieldSupportedValues &values) {
if (values.type == C2FieldSupportedValues::VALUES) {
_mValues.insert(_mValues.end(), values.values.begin(), values.values.end());
}
}
/**
* Returns whether this range is empty.
*/
constexpr bool isEmpty() const {
return _mValues.empty();
}
/**
* Returns whether a value is part of this set.
*
* \param value the value to check.
*/
bool contains(T value) const;
/**
* Returns a new value set that is the intersection of this set and another.
*
* \param limit the other value set
*/
C2SupportedValueSet<T> limitedTo(const C2SupportedValueSet<T> &limit) const;
/**
* Returns a new value set that is the intersection of this set and a value range.
*
* \param limit the other range
*/
C2SupportedValueSet<T> limitedTo(const C2SupportedRange<T> &limit) const;
/**
* Returns a new value set that is the intersection of this set and a flag set.
*
* \param limit the other flag set
*/
C2SupportedValueSet<T> limitedTo(const C2SupportedFlags<T> &limit) const;
/**
* Converts this object to a C2FieldSupportedValues object.
*/
operator C2FieldSupportedValues() const {
return C2FieldSupportedValues(false /* flags */, _mValues);
}
/**
* Returns the ordered set of values of this object.
*/
const std::vector<T> values() const;
/**
* Clears this supported value set.
*/
inline void clear() {
_mValues.clear();
}
private:
/**
* Constructs a value set from a set of C2Value::Primitive values.
*
* \param values the set
*/
C2SupportedValueSet(std::vector<C2Value::Primitive> &&values)
: _mValues(values) {
}
/**
* Constructs a value set from a set of values.
*
* \param values the set
*/
C2SupportedValueSet(const std::vector<T> &values) {
for (T elem : values) {
_mValues.emplace_back(elem);
}
}
/**
* Constructs a value set from a set of initializer list values
*
* \param values the set
*/
C2SupportedValueSet(const std::initializer_list<T> values) {
for (T elem : values) {
_mValues.emplace_back(elem);
}
}
std::vector<C2Value::Primitive> _mValues; ///< the supported set of values
};
/**
* Helper class to handle C2FieldSupporteValues object for fields of various types.
*/
template<typename T>
class C2FieldSupportedValuesHelper;
// templated operator must be predeclared for friend declaration
template<typename T>
std::ostream& operator<<(std::ostream& os, const C2FieldSupportedValuesHelper<T> &i);
template<typename T>
class C2FieldSupportedValuesHelper {
public:
/**
* Creates a helper for a specific type from a generic C2FieldSupportedValues struct.
*/
C2FieldSupportedValuesHelper(const C2FieldSupportedValues &values);
// TRICKY: needed for std::unique_ptr<Impl> declaration
~C2FieldSupportedValuesHelper();
// support copy constructor/operator
C2FieldSupportedValuesHelper(const C2FieldSupportedValuesHelper &);
C2FieldSupportedValuesHelper& operator=(const C2FieldSupportedValuesHelper &);
bool supports(T value) const;
private:
// use pimpl as implementation may change in the future
struct Impl;
std::unique_ptr<Impl> _mImpl;
friend std::ostream& operator<< <T>(std::ostream& os, const C2FieldSupportedValuesHelper<T> &i);
//friend std::ostream& operator<<(std::ostream& os, const C2FieldSupportedValuesHelper &i);
};
/**
* Builder for supported values for a field of a given type.
*
* This builder can be used to successively restrict the supported values for a field. Upon
* creation, there are no supported values specified - which for this builder means that all
* values are supported.
*/
template<typename T>
class C2ParamFieldValuesBuilder {
public:
/**
* Creates a builder with no defined values - but implicitly any value allowed.
*/
C2ParamFieldValuesBuilder(const C2ParamField &field);
/**
* Get C2ParamFieldValues from this builder.
*/
operator C2ParamFieldValues() const;
/**
* Define the supported values as the currently supported values of this builder.
*/
C2ParamFieldValuesBuilder<T> &any();
/**
* Restrict (and thus define) the supported values to none.
*
* \note This really should not be used from the builder as all params must have supported
* values, but is here in case this is really the case.
*/
C2ParamFieldValuesBuilder<T> &none();
/**
* Restrict (and thus define) the supported values to |value| alone.
*/
C2ParamFieldValuesBuilder<T> &equalTo(T value);
/**
* Restrict (and thus define) the supported values to values greater than |value|.
*/
inline C2ParamFieldValuesBuilder<T> &greaterThan(T value) {
return limitTo(C2SupportedRange<T>::GreaterThan(value));
}
/**
* Restrict (and thus define) the supported values to values greater than or equal to |value|.
*/
C2ParamFieldValuesBuilder<T> &greaterThanOrEqualTo(T value) {
return limitTo(C2SupportedRange<T>::GreaterThanOrEqualTo(value));
}
/**
* Restrict (and thus define) the supported values to values greater than or equal to |value|.
*/
C2ParamFieldValuesBuilder<T> ¬LessThan(T value) {
return limitTo(C2SupportedRange<T>::NotLessThan(value));
}
/**
* Restrict (and thus define) the supported values to values less than or equal to |value|.
*/
C2ParamFieldValuesBuilder<T> &lessThanOrEqualTo(T value) {
return limitTo(C2SupportedRange<T>::LessThanOrEqualTo(value));
}
/**
* Restrict (and thus define) the supported values to values less than or equal to |value|.
*/
C2ParamFieldValuesBuilder<T> ¬GreaterThan(T value) {
return limitTo(C2SupportedRange<T>::NotGreaterThan(value));
}
/**
* Restrict (and thus define) the supported values to values less than |value|.
*/
C2ParamFieldValuesBuilder<T> &lessThan(T value) {
return limitTo(C2SupportedRange<T>::LessThan(value));
}
/**
* Restrict (and thus define) the supported values to values in the range of [ |min|, |max| ]
* with optional |step|.
*/
C2ParamFieldValuesBuilder<T> &inRange(
T min, T max, T step = std::is_floating_point<T>::value ? T(0) : T(1)) {
return limitTo(C2SupportedRange<T>::InRange(min, max, step));
}
/**
* Restrict (and thus define) the supported values to values in the geometric series starting
* from |min| with factor |num| / |denom|, not greater than |max|.
*/
C2ParamFieldValuesBuilder<T> &inSeries(T min, T max, T num, T denom) {
return limitTo(C2SupportedRange<T>::InSeries(min, max, num, denom));
}
/**
* Restrict (and thus define) the supported values to values in the multiply-accumulate series
* starting from |min| with factor |num| / |denom| and |step|, not greater than |max|.
*/
C2ParamFieldValuesBuilder<T> &inMacSeries(T min, T max, T step, T num, T denom) {
return limitTo(C2SupportedRange<T>::InMacSeries(min, max, step, num, denom));
}
/**
* Restrict (and thus define) the supported values to values in |values|.
*/
C2ParamFieldValuesBuilder<T> &oneOf(const std::initializer_list<T> values) {
return limitTo(C2SupportedValueSet<T>::OneOf(values));
}
/**
* Restrict (and thus define) the supported values to values in |values|.
*/
C2ParamFieldValuesBuilder<T> &oneOf(const std::vector<T> &values) {
return limitTo(C2SupportedValueSet<T>::OneOf(values));
}
/**
* Restrict (and thus define) the supported values to flags in |flags| with at least |min|
* set.
*/
C2ParamFieldValuesBuilder<T> &flags(const std::vector<T> &flags, T min = T(0)) {
return limitTo(C2SupportedFlags<T>::Flags(flags, min));
}
/**
* Restrict (and thus define) the supported values to flags in |values| with at least |min|
* set.
*/
C2ParamFieldValuesBuilder<T> &flags(const std::initializer_list<T> flags, T min = T(0)) {
return limitTo(C2SupportedFlags<T>::Flags(flags, min));
}
virtual ~C2ParamFieldValuesBuilder();
// support copy constructor/operator
C2ParamFieldValuesBuilder(const C2ParamFieldValuesBuilder &);
C2ParamFieldValuesBuilder& operator=(const C2ParamFieldValuesBuilder &);
private:
/**
* Restrict (and thus define) the supported values to a value set.
*/
C2ParamFieldValuesBuilder<T> &limitTo(const C2SupportedValueSet<T> &limit);
/**
* Restrict (and thus define) the supported values to a value set.
*/
C2ParamFieldValuesBuilder<T> &limitTo(const C2SupportedFlags<T> &limit);
/**
* Restrict (and thus define) the supported values to a range.
*/
C2ParamFieldValuesBuilder<T> &limitTo(const C2SupportedRange<T> &limit);
struct Impl;
std::unique_ptr<Impl> _mImpl;
};
/**
* Builder for a list of setting conflicts.
*/
class C2SettingConflictsBuilder {
public:
/**
* Creates an empty list of setting conflicts.
*/
C2SettingConflictsBuilder();
/**
* Creates a list containing a single setting conflict.
*/
C2SettingConflictsBuilder(C2ParamFieldValues &&conflict);
/**
* Adds a conflict to the current list of conflicts and returns this
*/
C2SettingConflictsBuilder& with(C2ParamFieldValues &&conflict);
/**
* Gets the current list of conflicts (and moves them out of this builder.)
* (this is why it is not const)
*/
std::vector<C2ParamFieldValues> retrieveConflicts();
/**
* Returns whether the current list is empty.
*/
inline bool empty() const { return _mConflicts.empty(); }
inline operator bool() const { return empty(); }
private:
std::vector<C2ParamFieldValues> _mConflicts;
};
/**
* Setting result builder for a parameter.
*/
struct C2SettingResultBuilder {
/**
* Creates a read-only setting result failure.
*
* This does not take FSV as only the current value of the field is supported.
*/
static C2SettingResult ReadOnly(const C2ParamField ¶m);
/**
* Creates a bad-value or infoinformational bad-value setting result failure.
*
* This does not take FSV as the value is outside of the possible values. As such, there are no
* conflicts for this case either.
*/
static C2SettingResult BadValue(const C2ParamField ¶mField, bool isInfo = false);
/**
* Creates a conflict (or informational conflict) setting result failure.
*
* This takes FSV so use paramFieldValues and optional conflicts.
*/
static C2SettingResult Conflict(
C2ParamFieldValues &¶mFieldValues, C2SettingConflictsBuilder &conflicts,
bool isInfo = false);
// TODO: retrieve results
private:
C2ParamField _mParamField;
C2SettingResult _mResult;
C2SettingResultBuilder(const C2SettingResultBuilder &) = delete;
};
/**
* Setting results (PLURAL) builder.
*
* Setting results contain a failure status along with a list of failing fields or params.
*/
struct C2SettingResultsBuilder {
C2SettingResultsBuilder(const C2SettingResultsBuilder&) = delete;
C2SettingResultsBuilder(C2SettingResultsBuilder&&) = default;
C2SettingResultsBuilder &operator=(C2SettingResultsBuilder&&) = default;
/** \returns (default) successful result with no details. */
inline static C2SettingResultsBuilder Ok() {
return C2SettingResultsBuilder(C2_OK);
}
/** \returns Interface is in bad state, with no further details. */
inline static C2SettingResultsBuilder BadState() {
return C2SettingResultsBuilder(C2_BAD_STATE);
}
/** \returns Interface connection timed out, with no further details. */
inline static C2SettingResultsBuilder TimedOut() {
return C2SettingResultsBuilder(C2_TIMED_OUT);
}
/** \returns Interface connection is corrupted, with no further details. */
inline static C2SettingResultsBuilder Corrupted() {
return C2SettingResultsBuilder(C2_CORRUPTED);
}
inline static C2SettingResultsBuilder NoMemory(C2Param::Index index_ __unused) {
// TODO: try to add failure result
return C2SettingResultsBuilder(C2_NO_MEMORY);
}
// TODO: this should not be a constructor
/** Creates a builder with a single bad value setting result. */
C2SettingResultsBuilder(C2SettingResult &&result);
/** Combines this results with other results. */
C2SettingResultsBuilder plus(C2SettingResultsBuilder&& results);
/** Retrieve (get and move out) failures and return the failure status. */
c2_status_t retrieveFailures(std::vector<std::unique_ptr<C2SettingResult>>* const failures);
private:
/** Setting results based on a single status. This is used when actual setting could not be
* attempted to get a single C2SettingResult, or when a setting succeeded without
* 'complaints'. */
C2SettingResultsBuilder(c2_status_t status);
// status must be one of OK, BAD_STATE, TIMED_OUT, CORRUPTED or NO_MEMORY
// mainly: BLOCKING, BAD_INDEX, BAD_VALUE and NO_MEMORY requires a setting attempt, but
// NO_MEMORY may not allow us to create a results structure.
/**
* One of OK, BAD_INDEX, BAD_VALUE, BAD_STATE, NO_MEMORY, TIMED_OUT, BLOCKING or CORRUPTED.
*/
c2_status_t _mStatus __unused;
/**
* Vector of individual setting result details.
*/
std::vector<std::unique_ptr<C2SettingResult>> _mResults;
};
/**
* Utility class to enumerate fields of parameters.
*/
struct C2FieldUtils {
struct _Inspector;
/**
* An extended field descriptor object with structural information (lineage back to the root of
* the param).
*/
struct Info {
typedef C2FieldDescriptor::type_t type_t; ///< field type
typedef C2FieldDescriptor::NamedValuesType NamedValuesType; ///< named values list type
/// returns the name of the field
C2String name() const;
/// returns the type of this field
type_t type() const;
/**
* Returns the defined name-value pairings for this field. The returned reference is
* only valid during the validity of this object
*/
const NamedValuesType &namedValues() const;
/**
* The index of this field. E.g. param.field or param.field[0] has an index of 0, and
* param.struct[2].field[3] has an index of 3.
*/
size_t index() const;
/// returns the length of the field in case it is an array. Returns 0 for
/// T[] arrays if this info comes from a C2Param::Index object, and the currently used
/// extent if it comes from a C2Param object. Returns 1 for T[1] arrays as well as if the
/// field is not an array.
size_t extent() const;
/**
* The (structural) depth of this field. E.g. param.field or param.field[0] has a depth of
* 0, and param.struct.field or param.struct[0].field[0] has a depth of 1.
*/
size_t depth() const;
/**
* Returns the offset of this field in the parameter in bytes.
*/
size_t offset() const;
/**
* Returns the size of this field in bytes.
*/
size_t size() const;
/**
* The offset of this field's array. E.g. for param.struct[2].field[3] this is the offset
* of its smallest sibling: param.struct[2].field[0].
*/
size_t arrayOffset() const;
/**
* Returns the size of this field's array. This is equivalent to extent() * size()
*/
size_t arraySize() const;
/**
* The offset of the base field. The base field is a cousin of the current field where
* all indices are 0. E.g. the the base field for param.struct[2].field[3] is
* param.struct[0].field[0]. Base fields are used to specify supported values for
* all cousin fields.
*/
size_t baseFieldOffset() const;
/**
* Returns whether this field is an arithmetic (integral, counter or float) field.
*/
bool isArithmetic() const;
/**
* Returns whether this field can have a flexible extent. extent() returns the current
* extent.
*/
bool isFlexible() const;
/// returns whether this info is valid
inline bool isValid() const { return _mImpl != nullptr; }
/// returns the info for the parent of this field, or an invalid Info object if it has no
/// parents
Info parent() const;
/// returns whether this info is valid
inline operator bool() const { return isValid(); }
struct Impl;
Info(std::shared_ptr<Impl>);
private:
std::shared_ptr<Impl> _mImpl;
friend struct _Inspector;
};
/**
* An (input) iterator object over fields using Info objects.
*/
struct Iterator {
typedef Info const value_type;
typedef ptrdiff_t difference_type;
typedef Info const * pointer;
typedef Info const reference;
typedef std::input_iterator_tag iterator_category;
/// return Info at current position
virtual reference operator*() const;
/// move to the next field
virtual Iterator& operator++();
virtual bool operator==(const Iterator &) const;
inline bool operator!=(const Iterator &other) const { return !operator==(other); }
virtual ~Iterator() = default;
struct Impl;
Iterator(std::shared_ptr<Impl>);
protected:
std::shared_ptr<Impl> mImpl;
};
/**
* An (input) iterable object representing a list of fields.
*/
struct List {
/// returns an iterator to the beginning of the list
virtual Iterator begin() const;
/// returns an iterator to the end of the list
virtual Iterator end() const;
virtual ~List() = default;
struct Impl;
List(std::shared_ptr<Impl>);
protected:
std::shared_ptr<Impl> mImpl;
};
/**
* Enumerates all (base) fields at index 0 of the parameter. The order of iteration is the
* following:
* Fields of a structure are enumerated in field order. However, sub-fields of a structure
* are enumerated directly after the structure field, and prior to sibling fields.
*
* In essence the order of enumeration is first by increasing offset, then by decreasing size.
*
* \param param parameter to enumerate its fields
* \param reflector parameter reflector used for enumeration
*
* \return an iterable object
*/
static List enumerateFields(
const C2Param ¶m,
const std::shared_ptr<C2ParamReflector> &reflector);
/**
* Enumerates all cousin fields up to depth - level for a field. If level is 0, it enumerates
* only the field. For level 1, it enumerates all fields in its current array (which may be
* itself if extent is 1). The order of iteration is by increasing field offset.
*/
static List enumerateCousins(
const Info &field,
uint32_t level = ~0);
/**
* Locates the field in a parameter and returns a list of 2 elements - the most-specific field
* array of the parameter that contains the entire field. If the field is not a valid field
* specifier for this parameter (e.g. it is outside the bounds of the parameter), it returns
* an empty list.
*/
static std::vector<Info> locateField(
const C2Param ¶m, const _C2FieldId &field,
const std::shared_ptr<C2ParamReflector> &reflector);
static std::vector<Info> locateField(
const C2ParamField &pf, const std::shared_ptr<C2ParamReflector> &reflector);
};
#include <util/C2Debug-interface.h>
#endif // C2UTILS_INTERFACE_UTILS_H_