--- a/src/misc/RingFinder.h Wed Mar 05 17:12:22 2014 +0200
+++ b/src/misc/RingFinder.h Wed Mar 05 17:29:27 2014 +0200
@@ -20,65 +20,108 @@
#include "../Main.h"
-// =============================================================================
-// RingFinder
-//
-// Provides an algorithm for finding a solution of rings between radii r0 and r1.
-// =============================================================================
+//!
+//! @brief Provides an algorithm for finding solutions of rings between given radii.
+//!
+//! The RingFinder is a class which implements a ring finding algorithm. It is passed
+//! two radii and it tries to find solutions of rings that would fill the given space.
+//!
+//! @note It is not fool-proof and does not always yield a solution, never assume
+//! @note that one is a available as none is guaranteed.
+//!
class RingFinder
{
public:
+ //! A single component in a solution
struct Component
{
int num;
double scale;
};
+ //! A solution whose components would fill the desired ring space.
class Solution
{
public:
- // Components of this solution
+ //! @returns components of this solution
inline const QVector<Component>& getComponents() const
{
return m_components;
}
- // Add a component to this solution
+ //! Add a component to this solution
inline void addComponent (const Component& a)
{
m_components.push_back (a);
}
- // Compare solutions
- bool isBetterThan (const Solution* other) const;
+ //! @brief Compare solutions.
+ //!
+ //! Compares this solution with @c other and determines which
+ //! one is superior.
+ //!
+ //! A solution is considered superior if solution has less
+ //! components than the other one. If both solution have an
+ //! equal amount components, the solution with a lesser maximum
+ //! ring number is found superior, as such solutions should
+ //! yield less new primitives and cleaner definitions.
+ //!
+ //! The solution which is found superior to every other solution
+ //! will be the one returned by @c RingFinder::bestSolution().
+ //!
+ //! @param other the solution to check against
+ //! @returns whether this solution is considered superior
+ //! @returns to @c other.
+ //!
+ bool isSuperiorTo (const Solution* other) const;
private:
QVector<Component> m_components;
};
+ //! Constructs a ring finder.
RingFinder() {}
+
+ //! @brief Tries to find rings between @c r0 and @c r1.
+ //!
+ //! This is the main algorithm of the ring finder. It tries to use math
+ //! to find the one ring between r0 and r1. If it fails (the ring number
+ //! is non-integral), it finds an intermediate radius (ceil of the ring
+ //! number times scale) and splits the radius at this point, calling this
+ //! function again to try find the rings between r0 - r and r - r1.
+ //!
+ //! This does not always yield into usable results. If at some point r ==
+ //! r0 or r == r1, there is no hope of finding the rings, at least with
+ //! this algorithm, as it would fall into an infinite recursion.
+ //!
+ //! @param r0 the lower radius of the ring space
+ //! @param r1 the higher radius of the ring space
+ //! @returns whether it was possible to find a solution for the given
+ //! @returns ring space.
+ //!
bool findRings (double r0, double r1);
+ //! @returns the solution that was considered best. Returns @c null
+ //! @returns if no suitable solution was found.
+ //! @see @c RingFinder::Solution::isSuperiorTo()
inline const Solution* bestSolution()
{
return m_bestSolution;
}
+ //! @returns all found solutions. The list is empty if no solutions
+ //! @returns were found.
inline const QVector<Solution>& allSolutions() const
{
return m_solutions;
}
- inline bool operator() (double r0, double r1)
- {
- return findRings (r0, r1);
- }
-
private:
QVector<Solution> m_solutions;
const Solution* m_bestSolution;
int m_stack;
+ //! Helper function for @c findRings
bool findRingsRecursor (double r0, double r1, Solution& currentSolution);
};
