diff options
author | Gereon Kremer <gereon.kremer@cs.rwth-aachen.de> | 2021-04-22 21:38:57 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-04-22 19:38:57 +0000 |
commit | 69992245e3d2326ca8ecf2295a7e03d395046fc1 (patch) | |
tree | b165e5472cc03856e074eaa54d1a6528dd1c13b2 /src/api | |
parent | 0869a09f1161480de24c412b12954fc84943bab2 (diff) |
Add API documentation for statistics (#6364)
This PR adds documentation for api::Statistics and api::Stat, as well as further explanations in sphinx.
It also adds a custom css to our sphinx theme that slightly changes how inline code blocks look.
Diffstat (limited to 'src/api')
-rw-r--r-- | src/api/cpp/cvc5.cpp | 22 | ||||
-rw-r--r-- | src/api/cpp/cvc5.h | 101 |
2 files changed, 83 insertions, 40 deletions
diff --git a/src/api/cpp/cvc5.cpp b/src/api/cpp/cvc5.cpp index 4dbd06ce8..c5472cdfe 100644 --- a/src/api/cpp/cvc5.cpp +++ b/src/api/cpp/cvc5.cpp @@ -4147,7 +4147,7 @@ bool Stat::isInt() const int64_t Stat::getInt() const { CVC5_API_TRY_CATCH_BEGIN; - CVC5_API_CHECK(isInt()) << "Expected Stat of type int64_t."; + CVC5_API_RECOVERABLE_CHECK(isInt()) << "Expected Stat of type int64_t."; return std::get<int64_t>(d_data->data); CVC5_API_TRY_CATCH_END; } @@ -4158,7 +4158,7 @@ bool Stat::isDouble() const double Stat::getDouble() const { CVC5_API_TRY_CATCH_BEGIN; - CVC5_API_CHECK(isDouble()) << "Expected Stat of type double."; + CVC5_API_RECOVERABLE_CHECK(isDouble()) << "Expected Stat of type double."; return std::get<double>(d_data->data); CVC5_API_TRY_CATCH_END; } @@ -4169,7 +4169,7 @@ bool Stat::isString() const const std::string& Stat::getString() const { CVC5_API_TRY_CATCH_BEGIN; - CVC5_API_CHECK(isString()) << "Expected Stat of type std::string."; + CVC5_API_RECOVERABLE_CHECK(isString()) << "Expected Stat of type std::string."; return std::get<std::string>(d_data->data); CVC5_API_TRY_CATCH_END; } @@ -4180,14 +4180,14 @@ bool Stat::isHistogram() const const Stat::HistogramData& Stat::getHistogram() const { CVC5_API_TRY_CATCH_BEGIN; - CVC5_API_CHECK(isHistogram()) << "Expected Stat of type histogram."; + CVC5_API_RECOVERABLE_CHECK(isHistogram()) << "Expected Stat of type histogram."; return std::get<HistogramData>(d_data->data); CVC5_API_TRY_CATCH_END; } -Stat::Stat(bool expert, bool def, StatData&& sd) +Stat::Stat(bool expert, bool defaulted, StatData&& sd) : d_expert(expert), - d_default(def), + d_default(defaulted), d_data(std::make_unique<StatData>(std::move(sd))) { } @@ -4250,8 +4250,8 @@ bool Statistics::iterator::operator!=(const Statistics::iterator& rhs) const Statistics::iterator::iterator(Statistics::BaseType::const_iterator it, const Statistics::BaseType& base, bool expert, - bool def) - : d_it(it), d_base(&base), d_showExpert(expert), d_showDefault(def) + bool defaulted) + : d_it(it), d_base(&base), d_showExpert(expert), d_showDefault(defaulted) { while (!isVisible()) { @@ -4270,15 +4270,15 @@ const Stat& Statistics::get(const std::string& name) { CVC5_API_TRY_CATCH_BEGIN; auto it = d_stats.find(name); - CVC5_API_CHECK(it != d_stats.end()) + CVC5_API_RECOVERABLE_CHECK(it != d_stats.end()) << "No stat with name \"" << name << "\" exists."; return it->second; CVC5_API_TRY_CATCH_END; } -Statistics::iterator Statistics::begin(bool expert, bool def) const +Statistics::iterator Statistics::begin(bool expert, bool defaulted) const { - return iterator(d_stats.begin(), d_stats, expert, def); + return iterator(d_stats.begin(), d_stats, expert, defaulted); } Statistics::iterator Statistics::end() const { diff --git a/src/api/cpp/cvc5.h b/src/api/cpp/cvc5.h index 96e287f84..b3785c10e 100644 --- a/src/api/cpp/cvc5.h +++ b/src/api/cpp/cvc5.h @@ -2342,10 +2342,12 @@ struct CVC5_EXPORT RoundingModeHashFunction /** * Represents a snapshot of a single statistic value. - * A value can be of type int64_t, double, std::string or a histogram + * A value can be of type `int64_t`, `double`, `std::string` or a histogram * (`std::map<std::string, uint64_t>`). - * The value type can be queried (using `isInt`, `isString`, etc.) and - * the stored value can be accessed (using `getInt`, `getString`, etc.). + * The value type can be queried (using `isInt()`, `isDouble()`, etc.) and + * the stored value can be accessed (using `getInt()`, `getDouble()`, etc.). + * It is possible to query whether this statistic is an expert statistic by + * `isExpert()` and whether its value is the default value by `isDefault()`. */ class CVC5_EXPORT Stat { @@ -2354,33 +2356,67 @@ class CVC5_EXPORT Stat public: friend class Statistics; friend std::ostream& operator<<(std::ostream& os, const Stat& sv); + /** Representation of a histogram: maps names to frequencies. */ using HistogramData = std::map<std::string, uint64_t>; - /** Create from the given value. */ + /** Can only be obtained from a `Statistics` object. */ Stat() = delete; + /** Copy constructor */ Stat(const Stat& s); + /** Destructor */ ~Stat(); + /** Copy assignment */ Stat& operator=(const Stat& s); - /** Is this value intended for experts only? */ + /** + * Is this value intended for experts only? + * @return Whether this is an expert statistic. + */ bool isExpert() const; - /** Does this value hold the default value? */ + /** + * Does this value hold the default value? + * @return Whether this is a defaulted statistic. + */ bool isDefault() const; - /** Is this value an integer? */ + /** + * Is this value an integer? + * @return Whether the value is an integer. + */ bool isInt() const; - /** Return the integer value */ + /** + * Return the integer value. + * @return The integer value. + */ int64_t getInt() const; - /** Is this value a double? */ + /** + * Is this value a double? + * @return Whether the value is a double. + */ bool isDouble() const; - /** Return the double value */ + /** + * Return the double value. + * @return The double value. + */ double getDouble() const; - /** Is this value an string? */ + /** + * Is this value a string? + * @return Whether the value is a string. + */ bool isString() const; - /** Return the string value */ + /** + * Return the string value. + * @return The string value. + */ const std::string& getString() const; - /** Is this value an histogram? */ + /** + * Is this value a histogram? + * @return Whether the value is a histogram. + */ bool isHistogram() const; - /** Return the histogram value */ + /** + * Return the histogram value. + * @return The histogram value. + */ const HistogramData& getHistogram() const; private: @@ -2392,6 +2428,9 @@ class CVC5_EXPORT Stat std::unique_ptr<StatData> d_data; }; +/** + * Print a `Stat` object to an ``std::ostream``. + */ std::ostream& operator<<(std::ostream& os, const Stat& sv) CVC5_EXPORT; /** @@ -2399,25 +2438,23 @@ std::ostream& operator<<(std::ostream& os, const Stat& sv) CVC5_EXPORT; * Once obtained, an instance of this class is independent of the `Solver` * object: it will not change when the solvers internal statistics do, it * will not be invalidated if the solver is destroyed. - * Statistics are generally categorized as public and expert statistics. - * Furthermore, statistics may hold the default values and thus be not of - * interest. * Iterating on this class (via `begin()` and `end()`) shows only public - * statistics that have been set. By passing appropriate flags to `begin()`, - * statistics that are expert, unchanged, or both, can be included as well. - * A single statistic value is represented as `Stat`. + * statistics that have been changed. By passing appropriate flags to + * `begin()`, statistics that are expert, defaulted, or both, can be + * included as well. A single statistic value is represented as `Stat`. */ class CVC5_EXPORT Statistics { public: - friend Solver; + friend class Solver; + /** How the statistics are stored internally. */ using BaseType = std::map<std::string, Stat>; - /** Custom iterator to hide expert statistics from regular iteration */ + /** Custom iterator to hide certain statistics from regular iteration */ class iterator { public: - friend Statistics; + friend class Statistics; BaseType::const_reference operator*() const; BaseType::const_pointer operator->() const; iterator& operator++(); @@ -2431,7 +2468,7 @@ class CVC5_EXPORT Statistics iterator(BaseType::const_iterator it, const BaseType& base, bool expert, - bool def); + bool defaulted); bool isVisible() const; BaseType::const_iterator d_it; const BaseType* d_base; @@ -2439,17 +2476,23 @@ class CVC5_EXPORT Statistics bool d_showDefault = false; }; - /** Retrieve the statistic with the given name. */ + /** + * Retrieve the statistic with the given name. + * Asserts that a statistic with the given name actually exists and throws + * a `CVC4ApiRecoverableException` if it does not. + * @param name Name of the statistic. + * @return The statistic with the given name. + */ const Stat& get(const std::string& name); /** * Begin iteration over the statistics values. * By default, only entries that are public (non-expert) and have been set * are visible while the others are skipped. - * With `expert` set to true, expert statistics are shown as well. - * With `def` set to true, defaulted statistics are shown as well. + * @param expert If set to true, expert statistics are shown as well. + * @param defaulted If set to true, defaulted statistics are shown as well. */ - iterator begin(bool expert = false, bool def = false) const; - /** end iteration */ + iterator begin(bool expert = false, bool defaulted = false) const; + /** End iteration */ iterator end() const; private: |