diff --git a/doc/lexicographic.html b/doc/lexicographic.html new file mode 100644 index 0000000..38522dd --- /dev/null +++ b/doc/lexicographic.html @@ -0,0 +1,234 @@ + + + + Boost.Utility - lexicographic documentation + + + +

+ c++ boost + Utility - Lexicographic +

+ +

+ The class boost::lexicographic provides an easy way + to avoid complex and errorprone if-else cascades to do lexicographic + comparisions on certain different criteria. The class is in the header + boost/utility/lexicographic.hpp and depends on no others headers. + The test code is in + lexicographic_test.hpp. +

+ +

Contents

+ + +

Introduction

+ Often one has to write comparisions which give an ordering between + various kinds of data. When they look in a certain + specified order at one relation between two data items at a time and + result in a lexicographic comparision of all these relations the + programmer often has to write long if-else cascades. These cascades + are often cpomplex and difficult to maintain. The class + boost::lexicographic helps in this scenario. Its constructor + and function call operator takes two data items which need to be + compared as arguments and performs to comparision. The order in which + the function call operators are called determine the lexicographic order + of the relations. Since the result of all further comparisions might not + be needed after a certain step, they are not executed.
+ The logic of the class assumes an ascending order as implied by the + operator <. If a descending order needs to be obtained + one can just switch the order of the arguments. Additionally, both the + constructor and the function call operator provide also a three argument + form which takes a functor for comparisions as a third argument. + +

Examples

+

+ An example usage are special sorting operators, such as the lexicographic + ordering of tuples: +

+
struct position
+{
+    double x, y, z;
+};
+
+bool operator < (position const &p1, position const &p2)
+{
+    return boost::lexicographic (p1.x, p2.x)
+                                (p1.y, p2.y)
+                                (p1.z, p2.z);
+}
+
+ An alternative form of writing this without boost::lexicographic + would be this: +
+
bool operator < (position const &p1, position const &p2)
+{
+    if (p1.x == p2.x)
+        if (p1.y == p2.y)
+            return p1.z < p2.z;
+        else
+            return p1.y < p2.y;
+    else
+        return p1.x < p2.x;
+}
+
+ It is also easy to use different functor such as a case insensitive + comparision function object in the next example. +
+
struct person
+{
+    std::string firstname, lastname;
+};
+
+bool operator < (person const &p1, person const &p2)
+{
+    return boost::lexicographic
+        (p1.lastname, p2.lastname, cmp_case_insensitive)
+        (p1.firstname, p2.firstname, cmp_case_insensitive);
+}
+
+

+ +

Synopsis

+
+
namespace boost
+{
+
+  class lexicographic
+  {
+    public:
+      enum result_type { minus = -1, equivalent, plus };
+
+      template <typename T1, typename T2>
+      lexicographic (T1 const &a, T2 const &b);
+      
+      template <typename T1, typename T2, typename Cmp>
+      lexicographic (T1 const &a, T2 const &b, Cmp cmp);
+
+      template <typename T1, typename T2>
+      lexicographic &operator () (T1 const &a, T2 const &b);
+
+      template <typename T1, typename T2, typename Cmp>
+      lexicographic &operator () (T1 const &a, T2 const &b, Cmp cmp);
+
+      result_type result () const;
+      operator unspecified_bool_type () const;
+  };
+
+  bool operator == (lexicographic l1, lexicographic l2);
+  bool operator != (lexicographic l1, lexicographic l2);
+
+}
+
+ +

Members

+

result_type

+ enum result_type { minus = -1, equivalent, plus }; +

+ Defines the result type of the class. It is kept as internal state + and is returned by result (). + The integer representation of it is equivalent to the one + returned by std::strcmp. +

+

+ +

constructors

+ template <typename T1, typename T2>
+ lexicographic (T1 const &a, T2 const &b); +

+ Constructs new object and does the first comparision + step between a and b. It uses + operator < for comparisions. +

+ + template <typename T1, typename T2, typename Cmp>
+ lexicographic (T1 const &a, T2 const &b, Cmp cmp); +

+ Constructs new object and does the first comparision + step between a and b. It uses + cmp for comparisions. +

+ +

function call operators

+ template <typename T1, typename T2>
+ lexicographic &operator () (T1 const &a, T2 const &b); +

+ Does next comparision step on object between a + and b. It uses operator < for + comparisions. +

+ + template <typename T1, typename T2, typename Cmp>
+ lexicographic &operator () (T1 const &a, T2 const &b, Cmp cmp); +

+ Does next comparision step on object between a + and b. It uses cmp for + comparisions. +

+ +

result

+ result_type result () const; +

+ Gives result of already done comparision steps. +

+ +

conversions

+ operator unspecified_bool_type () const; +

+ This conversion operator allows objects to be used in boolean + contexts, like if (lexicographic (a, b)) {}. The + actual target type is typically a pointer to a member function, + avoiding many of the implicit conversion pitfalls.
+ It evaluates to true if result () == minus, + otherwise to false. +

+ +

Free Functions

+

comparision

+ bool operator == (lexicographic l1, lexicographic l2); +

+ Returns l1.result () == l2.result (). + That means it returns true if both + objects are in the same state. +

+ + bool operator != (lexicographic l1, lexicographic l2); +

+ Returns l1.result () != l2.result (). + That means it returns true if the two + objects are in the a different state. +

+ +

Credits

+

+ The author of boost::lexicographic is Jan Langer (jan@langernetz.de). + Ideas and suggestions from Steve Cleary, David Abrahams and Gennaro Proata + were used. +

+
+

April 17, 2003

+ © Copyright Jan Langer 2003. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

+ + diff --git a/include/boost/utility/lexicographic.hpp b/include/boost/utility/lexicographic.hpp new file mode 100644 index 0000000..763f816 --- /dev/null +++ b/include/boost/utility/lexicographic.hpp @@ -0,0 +1,109 @@ +// (C) 2003, Jan Langer (jan@langernetz.de). +// +// This material is provided "as is", with absolutely no warranty expressed +// or implied. Any use is at your own risk. +// +// Permission to use or copy this software for any purpose is hereby granted +// without fee, provided the above notices are retained on all copies. +// Permission to modify the code and to distribute modified code is granted, +// provided the above notices are retained, and a notice that the code was +// modified is included with the above copyright notice. + +#ifndef BOOST_UTILITY_LEXICOGRAPHIC_HPP +#define BOOST_UTILITY_LEXICOGRAPHIC_HPP + +namespace boost +{ + + class lexicographic + { + public: + enum result_type { minus = -1, equivalent, plus }; + + private: + typedef void (lexicographic::*unspecified_bool_type) (); + void safe_bool_conversion () {} + + template + result_type do_compare (T1 const &a, T2 const &b) const + { + if (a < b) + return minus; + else if (b < a) + return plus; + else + return equivalent; + } + template + result_type do_compare (T1 const &a, T2 const &b, Cmp cmp) const + { + if (cmp (a, b)) + return minus; + else if (cmp (b, a)) + return plus; + else + return equivalent; + } + + public: + lexicographic () : m_value (equivalent) {} + + template + lexicographic (T1 const &a, T2 const &b) + : m_value (do_compare (a, b)) + {} + template + lexicographic (T1 const &a, T2 const &b, Cmp cmp) + : m_value (do_compare (a, b, cmp)) + {} + + template + lexicographic &operator () (T1 const &a, T2 const &b) + { + if (m_value == equivalent) + m_value = do_compare (a, b); + return *this; + } + template + lexicographic &operator () (T1 const &a, T2 const &b, Cmp cmp) + { + if (m_value == equivalent) + m_value = do_compare (a, b, cmp); + return *this; + } + + result_type result () const + { + return m_value; + } + + operator unspecified_bool_type () const + { + return (m_value == minus) + ? &lexicographic::safe_bool_conversion + : 0; + } + + // somehow only needed old compilers + bool operator ! () const + { + return m_value != minus; + } + + private: + result_type m_value; + }; + + bool operator == (lexicographic l1, lexicographic l2) + { + return l1.result () == l2.result (); + } + + bool operator != (lexicographic l1, lexicographic l2) + { + return l1.result () != l2.result (); + } + +} // namespace boost + +#endif // BOOST_UTILITY_LEXICOGRAPHIC_HPP diff --git a/test/lexicographic_test.cpp b/test/lexicographic_test.cpp new file mode 100644 index 0000000..38ce611 --- /dev/null +++ b/test/lexicographic_test.cpp @@ -0,0 +1,70 @@ +// (C) 2003, Jan Langer (jan@langernetz.de). +// +// This material is provided "as is", with absolutely no warranty expressed +// or implied. Any use is at your own risk. +// +// Permission to use or copy this software for any purpose is hereby granted +// without fee, provided the above notices are retained on all copies. +// Permission to modify the code and to distribute modified code is granted, +// provided the above notices are retained, and a notice that the code was +// modified is included with the above copyright notice. + +#include +#include + +#include + +int main () +{ + using boost::lexicographic; + + lexicographic l1; // equivalent + assert (!l1); + + lexicographic l2 (l1); // equivalent + assert (!l2); + + l2 = l1; + assert (!l2); + + l2 (3, 6); // less + assert (l2); + assert (l2.result () == lexicographic::minus); + assert (lexicographic::equivalent != l2.result ()); + + lexicographic l3 (3.0, 1.0); // greater + assert (!l3); + + for (int i = 1; i <= 3; ++i) + for (int j = 1; j <= 3; ++j) + for (int k = 1; k <= 3; ++k) + { + lexicographic l4; + l4 (i, 2) (j, 2) (k, 2); + + if (i < 2) + assert (l4); + else if (i > 2) + assert (!l4); + else if (j < 2) + assert (l4); + else if (j > 2) + assert (!l4); + else if (k < 2) + assert (l4); + else + assert (!l4); + } + + lexicographic l5; + l5 (1, 1, std::greater ()) (2, 3); + assert (l5); + + lexicographic l6; + l6 (1, 1, std::greater ()) (2, 3, std::greater ()); + assert (!l6); + + lexicographic l7; + l7 (1, 1) (2, 3, std::greater ()); + assert (!l7); +}