[Boost-commit] svn:boost r7414

From: hervebronnimann_at_[hidden]
Date: 2007-07-12 09:19:13

Author: hervebronnimann
Date: 2007-07-12 09:19:12 EDT (Thu, 12 Jul 2007)
New Revision: 7414
URL: http://svn.boost.org/trac/boost/changeset/7414

Log:
More example.

Added:
   sandbox/SOC/2007/geometry/libs/hdstl/dev/halfedge_ds/facet_selectors.cpp
   sandbox/SOC/2007/geometry/libs/hdstl/dev/halfedge_ds/facet_selectors.t.cpp
Text files modified: 
   sandbox/SOC/2007/geometry/libs/hdstl/dev/halfedge_ds/facet_selectors.hpp |   270 ++++++++++++++++++++++++++++++++++++++- 
   1 files changed, 260 insertions(+), 10 deletions(-)

Added: sandbox/SOC/2007/geometry/libs/hdstl/dev/halfedge_ds/facet_selectors.cpp
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/geometry/libs/hdstl/dev/halfedge_ds/facet_selectors.cpp	2007-07-12 09:19:12 EDT (Thu, 12 Jul 2007)
@@ -0,0 +1,3 @@
+//facet_selectors.cpp   -*- C++ -*-
+
+#include <boost/hdstl/halfedge_ds/facet_selectors.hpp>

Modified: sandbox/SOC/2007/geometry/libs/hdstl/dev/halfedge_ds/facet_selectors.hpp
==============================================================================
--- sandbox/SOC/2007/geometry/libs/hdstl/dev/halfedge_ds/facet_selectors.hpp	(original)
+++ sandbox/SOC/2007/geometry/libs/hdstl/dev/halfedge_ds/facet_selectors.hpp	2007-07-12 09:19:12 EDT (Thu, 12 Jul 2007)
@@ -3,29 +3,279 @@
 //@PURPOSE: Provide selector classes for 'FacetS'.
 //
 //@CLASSES:
-//  'facetS':  defines configuration options for facet access
+//        'facetS':  defines configuration options for facet storage and access
+//  'stored_facet':  defines the storage for a given facet configuration
+//     'facet_gen':  defines the stored type and accessors for a facet configuration
 //  
 //@SEE_ALSO: {hds_concepts.hpp, halfedge_ds.hpp}
 //
-//@DESCRIPTION: This file provides the 'facetS' selector class for
-//configurations related to facet properties. 
+//@DESCRIPTION: This file provides the 'facetS' selector classes for
+// configurations related to facet properties.  These selector types are
+// suitable to use for the 'FacetS' template parameter to the 'halfedge_ds'
+// class template.  Currently, there are two facet selectors:
+//
+// - 'noFacetS': means that there should be no facets in the corresponding
+//   'hafedge_ds' data structure, and
+//
+// - 'facetS<ContainerS, HasfacetLink>': (where 'ContainerS' can be any of the
+//    types defined by the 'container_selectors' component, such as 'listS',
+//    'vecS', 'setS' or 'hashS') means that there should be facets stored in
+//    that kind of containers within the 'halfedge_ds' data structure, and
+//    whether the facets must have a link to one of the halfedges in their
+//    facet cycles or not.
+//
+// As a consequence, a 'halfedge_ds<..., ..., facetS<...> >' data structure
+// (where the actual selectors used in '...' do not matter) will model the
+// 'FacetListHDS' concept.
+//
+///Usage
+///-----
+// Supposed we want to design a stored facet from a facet selector.  A stored
+// facet needs to know:
+// - whether it stores a facet link or not.
+// - the halfedge descriptor:  in order to store the facet link.  Since it is
+//   not needed when the facet stores no facet link, we make it integer in that
+//   case.
+// - any extra properties that need to get contained by the facet as member. We
+//   make this a parameterized base class.
+//
+// We therefore have the following general implementation.
+//..
+//  template <typename Base,
+//            bool HasVertexLink = false, 
+//            typename HalfedgeDescriptor = int>
+//  struct stored_facet : public Base {
+//      // This 'struct' implements a stored facet, deriving from the
+//      // parameterized 'Base', and adding a facet link if 'HasFacetLink' is
+//      // true.
+//
+//      // DATA
+//      HalfedgeDescriptor m_facetLink;
+//
+//      // CREATORS
+//      stored_facet(Base const& base, HalfedgeDescriptor facetLink)
+//      : Base(base)
+//      , m_facetLink(facetLink) {}
+//  };
+//..
+// Since the facetLink is stored or not, we encapsulate this in a specialization.
+//..
+//  template <typename Base>
+//  struct stored_facet : public Base {
+//      // This specialization implements a stored facet, deriving from the
+//      // parameterized 'Base', but without storing a facet link although its
+//      // constructor accepts a null facet link for uniformity of the
+//      // interface with the general definition.
+//
+//      // CREATORS
+//      stored_facet(Base const& base, HalfedgeDescriptor = 0)
+//      : Base(base) {}
+//  };
+//..
+// Now, we can further define the facet generator: it takes a facet selector
+// and a halfedge descriptor, and uses the 'container_selectors' component to
+// define a suitable base for the 'halfedge_ds_gen' that implements all the
+// functionality of the 'halfedge_ds' related to the facets.
+//..
+//  template <typename HalfedgeDescriptor, typename FacetBase>
+//  struct facet_gen {
+//      // This 'struct' implements a facet generator.  The general definition does
+//      // nothing.
+//  };
+//..
+// The proper facet generator is defined only when 'FacetS' is of the form
+// 'facetS<...>':
+//..
+//  // SPECIALIZATIONS
+//  template <typename FacetS, typename HalfedgeDescriptor = void, typename FacetBase = void>
+//  struct facet_gen<facetS<ContainerS, HasFacetLink>, HalfedgeDescriptor, FacetBase> {
+//      // This specialization of a facet generator for 'facetS' takes a facet selector
+//      // and a halfedge descriptor, and uses the 'container_selectors' component
+//      // to define a suitable base for the 'halfedge_ds_gen' that implements all
+//      // the functionality of the 'halfedge_ds' related to the facets.
+//  
+//      // TYPES
+//      typedef container_gen<ContainerS>           ContainerGen;
+//          // The container generator for this facet generator.
+//
+//      typedef stored_facet<FacetBase, HasfacetLink, HalfedgeDescriptor>
+//                                                  facet_type;
+//          // The stored facet type for this facet generator.
+//  
+//      typedef typename container_gen<ContainerS, facet_type>::type
+//                                                  container_type;
+//          // The facet container type for this facet generator.
+//  
+//      typedef typename container_type::descriptor facet_descriptor;
+//          // The facet descriptor type for this facet generator.
+//
+//      typedef typename container_type::iterator   facet_iterator;
+//          // The facet iterator type for this facet generator.
+//  
+//      // DATA
+//      container_type m_container;
+//          // The actual container for the facets, from which facets can be obtained.
+//  };
+//..
+// and the supporting functions, required by the 'FacetListHDS' concept, are:
+//..
+//  // FREE FUNCTIONS
+//  template <typename FacetS, typename HalfedgeDescriptor, typename FacetBase>
+//  typename facet_gen<FacetS, HalfedgeDescriptor, FacetBase>::iterator
+//  facets_begin(facet_gen<FacetS, HalfedgeDescriptor, FacetBase> const& hds) {
+//      typedef typename facet_gen<FacetS,
+//                                 HalfedgeDescriptor,
+//                                 FacetBase>::container_gen_type ContainerGen;
+//      return ContainerGen::container_begin(hds.m_container);
+//  }
+//  
+//  template <typename FacetS, typename HalfedgeDescriptor, typename FacetBase>
+//  typename facet_gen<FacetS, HalfedgeDescriptor, FacetBase>::iterator
+//  facets_end(facet_gen<FacetS, HalfedgeDescriptor, FacetBase> const& hds) {
+//      typedef typename facet_gen<FacetS,
+//                                 HalfedgeDescriptor,
+//                                 FacetBase>::container_gen_type ContainerGen;
+//      return ContainerGen::container_end(hds.m_container);
+//  }
+//  
+//  template <typename FacetS, typename HalfedgeDescriptor, typename FacetBase>
+//  typename facet_gen<FacetS, HalfedgeDescriptor, FacetBase>::size_type;
+//  facets_end(facet_gen<FacetS, HalfedgeDescriptor, FacetBase> const& hds) {
+//      return hds.m_container.size();
+//  }
+//..
 
 #ifndef BOOST_HDSTL_FACET_SELECTORS_HPP
 #define BOOST_HDSTL_FACET_SELECTORS_HPP 1
 
-namespace boost;
-namespace hdstl;
+namespace boost {
+namespace hdstl {
 
-template<typename Selector>
+                 // ---------------------------
+                 // classes noFacetS and facetS
+                 // ---------------------------
+
+struct noFacetS {
+    // A selector that tells the 'halfedge_ds' that it should not store facets.
+};
+
+template<typename ContainerS, bool HasFacetLink = false>
 struct facetS {
-    typedef false_type is_rand_access;
+    // A selector that tells the 'halfedge_ds' that it should store facets in a
+    // container selected by the specified 'Selector', and that those facets
+    // should have a link to one of the halfedges in their facet cycle or not,
+    // depending on the specified 'HasFacetLink' boolean template parameter.
+
+    // TYPES
+    typedef ContainerS   container_selector;
+        // A selector (see the component 'container_selector') for the type of
+        // container that
+        // will be used to store the halfedge.
+
+    enum { has_facet_links = HasFacetLink };
+        // A boolean enumeration that tells whether the stored halfedge should
+        // contain a link to one of the halfedges in its fact cycle or not.
 };
 
-template<>
-struct facets<vecS> {
-    typedef true_type is_rand_access;
+                 // ------------------
+                 // class stored_facet
+                 // ------------------
+
+template <typename Base,
+          bool HasFacetLink = false, 
+          typename HalfedgeDescriptor = int>
+struct stored_facet : public Base {
+    // This 'struct' implements a stored facet, deriving from the
+    // parameterized 'Base', and adding a facet link if 'HasFacetLink' is
+    // true.
+
+    // DATA
+    HalfedgeDescriptor m_facetLink;
+
+    // CREATORS
+    stored_facet(Base const& base, HalfedgeDescriptor facetLink)
+    : Base(base)
+    , m_facetLink(facetLink) {}
+};
+
+template <typename Base, typename HalfedgeDescriptor>
+struct stored_facet<Base, false, HalfedgeDescriptor> : public Base {
+    // This partial specialization implements a stored facet, deriving from the
+    // parameterized 'Base', but without storing a facet link although its
+    // constructor accepts a null facet link for uniformity of the
+    // interface with the general definition.
+
+    // CREATORS
+    stored_facet(Base const& base, HalfedgeDescriptor = 0)
+    : Base(base) {}
+};
+
+                 // ---------------
+                 // class facet_gen
+                 // ---------------
+
+template <typename HalfedgeDescriptor, typename FacetBase>
+struct facet_gen {
+    // This 'struct' implements a facet generator.  The general definition does
+    // nothing.
+};
+
+// SPECIALIZATIONS
+template <typename FacetS, typename HalfedgeDescriptor = void, typename FacetBase = void>
+struct facet_gen<facetS<ContainerS, HasFacetLink>, HalfedgeDescriptor, FacetBase> {
+    // This specialization of a facet generator for 'facetS' takes a facet selector
+    // and a halfedge descriptor, and uses the 'container_selectors' component
+    // to define a suitable base for the 'halfedge_ds_gen' that implements all
+    // the functionality of the 'halfedge_ds' related to the facets.
+
+    // TYPES
+    typedef container_gen<ContainerS>           ContainerGen;
+        // The container generator for this facet generator.
+
+    typedef stored_facet<FacetBase, HasfacetLink, HalfedgeDescriptor>
+                                                facet_type;
+        // The stored facet type for this facet generator.
+
+    typedef typename container_gen<ContainerS, facet_type>::type
+                                                container_type;
+        // The facet container type for this facet generator.
+
+    typedef typename container_type::descriptor facet_descriptor;
+        // The facet descriptor type for this facet generator.
+
+    typedef typename container_type::iterator   facet_iterator;
+        // The facet iterator type for this facet generator.
+
+    // DATA
+    container_type m_container;
+        // The actual container for the facets, from which facets can be obtained.
 };
 
+// FREE FUNCTIONS
+template <typename FacetS, typename HalfedgeDescriptor, typename FacetBase>
+typename facet_gen<FacetS, HalfedgeDescriptor, FacetBase>::iterator
+facets_begin(facet_gen<FacetS, HalfedgeDescriptor, FacetBase> const& hds) {
+    typedef typename facet_gen<FacetS,
+                               HalfedgeDescriptor,
+                               FacetBase>::container_gen_type ContainerGen;
+    return ContainerGen::container_begin(hds.m_container);
+}
+
+template <typename FacetS, typename HalfedgeDescriptor, typename FacetBase>
+typename facet_gen<FacetS, HalfedgeDescriptor, FacetBase>::iterator
+facets_end(facet_gen<FacetS, HalfedgeDescriptor, FacetBase> const& hds) {
+    typedef typename facet_gen<FacetS,
+                               HalfedgeDescriptor,
+                               FacetBase>::container_gen_type ContainerGen;
+    return ContainerGen::container_end(hds.m_container);
+}
+
+template <typename FacetS, typename HalfedgeDescriptor, typename FacetBase>
+typename facet_gen<FacetS, HalfedgeDescriptor, FacetBase>::size_type;
+facets_end(facet_gen<FacetS, HalfedgeDescriptor, FacetBase> const& hds) {
+    return hds.m_container.size();
+}
+
 } // namespace hdstl
 } // namespace boost
 

Added: sandbox/SOC/2007/geometry/libs/hdstl/dev/halfedge_ds/facet_selectors.t.cpp
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/geometry/libs/hdstl/dev/halfedge_ds/facet_selectors.t.cpp	2007-07-12 09:19:12 EDT (Thu, 12 Jul 2007)
@@ -0,0 +1,216 @@
+//facet_selectors.hpp   -*- C++ -*-
+//
+//@OVERVIEW:  The component under test is a selector class.  We
+// must make sure that all selectors are suitably defined and that the
+// selection is done properly.
+//
+//@TEST_PLAN: First create an instance of all the selectors (to make sure they
+// exist, and verify that there are no more than tested).  Then instantiate the
+// 'container_gen<FacetS,ValueType>' for a given value type and all
+// selectors, and verify that its members have the expected types and
+// signatures.  Finally, verify that the usage example compiles and executes
+// without errors, when assert is replaced by BOOST_CHECK.
+
+#include <boost/hdstl/halfedge_ds/container_selectors.hpp>
+
+#include <boost/test/minimal.hpp>
+
+#include <set>
+#include <string>
+#include <vector>
+
+using namespace boost::hdstl;
+using namespace std;
+
+// ===========================================================================
+//                              SELECTOR CLASSES
+// ===========================================================================
+
+template <typename FacetS>
+bool selector_requirements(FacetS const&) {
+    return false;
+}
+
+bool selector_requirements(noFacetS const&) {
+    return true;
+}
+
+template <typename Base, typename HalfedgeDescriptor>
+bool selector_requirements(facetS<Base, false, HalfedgeDescriptor> const&) {
+    return true;
+}
+
+template <typename Base, typename HalfedgeDescriptor>
+bool selector_requirements(facetS<Base, true, HalfedgeDescriptor> const&) {
+    return true;
+}
+
+// ===========================================================================
+//                              CLASS CONTAINER_GEN
+// ===========================================================================
+
+template <typename FacetS>
+bool selection_requirements(FacetS const&) {
+    return false;
+}
+
+template <typename Base, typename HalfedgeDescriptor>
+bool selector_requirements(facetS<Base, false, HalfedgeDescriptor> const&f) {
+    return true;
+}
+
+template <typename Base, typename HalfedgeDescriptor>
+bool selector_requirements(facetS<Base, true, HalfedgeDescriptor> const&) {
+    return true;
+}
+
+template <class ContainerGen, typename ValueType, typename FacetS>
+bool container_gen_requirements() {
+    ValueType array[] = { 0, 1, 2, 3 };
+    typename ContainerGen::type container(array, array + 4);
+    
+    BOOST_CHECK(( selection_requirements(FacetS(), container) ));
+
+    // Types must exist.
+    typedef typename ContainerGen::descriptor descriptor;
+    typedef typename ContainerGen::iterator   iterator;
+
+    // Value type of iterator must be a descriptor.
+    iterator begin = ContainerGen::container_begin(container);
+    descriptor theBegin = *begin;
+
+    return true;
+}
+
+// ===========================================================================
+//                              USAGE EXAMPLE
+// ===========================================================================
+
+///Usage
+///-----
+// Suppose we want a data structure 'ElementCollection' containing instances of
+// a custom 'Element' type, stored in a container chosen by a selector given as
+// template parameter.  To make this picture more concrete, let us pick an
+// implementation:
+//..
+    struct Element {
+        int           userId;
+        std::string   familyName;
+        int           securityLevel;
+        Element(int uId, std::string name, int level)
+        : userId(uId), familyName(name), securityLevel(level) {}
+    };
+    bool operator<(const Element& lhs, const Element& rhs) {
+        return lhs.userId < rhs.userId;
+    }
+//..
+//  We can implement 'ElementCollection' using the 'container_gen' facility as
+//  follows.  We purposely keep the de
+//..
+    template <typename FacetS>
+    class ElementCollection {
+        // This class stores and gives access to a collection of 'Element'
+        // objects, using the container selected by the specified 'FacetS'
+        // selector.
+  
+      public:
+        // TYPES
+        typedef container_gen<FacetS, Element>       container_generator;
+        typedef typename container_generator::type       container_type;
+        typedef typename container_generator::descriptor descriptor;
+        typedef typename container_generator::iterator   iterator;
+  
+      private:
+        // DATA
+        container_type  m_collection;
+  
+      public:
+        // CREATORS
+        ElementCollection() {}
+            // Create an empty collection of 'Element' objects.
+  
+        template <typename Iterator>
+        ElementCollection(Iterator elementBegin, Iterator elementEnd)
+            // Create a collection of 'Element' objects initially containing
+            // the objects in the specified range '[elementBegin, elementEnd)'.
+        : m_collection(elementBegin, elementEnd) {}
+  
+        // MANIPULATORS
+        iterator begin() { return container_generator::container_begin(m_collection); }
+            // Return an iterator pointing to the beginning of this collection.
+  
+        iterator end() { return container_generator::container_end(m_collection); }
+            // Return an iterator pointing past the end of this collection.
+  
+        container_type& theContainer() { return m_collection; }
+            // Return the modifiable container underlying this collection.
+  
+        // ACCESSORS
+        const container_type& theContainer() const { return m_collection; }
+            // Return the non-modifiable container underlying this collection.
+    };
+//..
+// We can now use the collection as follows.  First let us create the
+// individual elements:
+//..
+    bool usageExample() {
+        Element george(632,  "Harrison",  +78);
+        Element john  (834,  "Lennon",    +255);
+        Element paul  (932,  "McCartney", +126);
+        Element ringo (1432, "Starr",     +123);
+        Element theBeatles[] = { george, john, paul, ringo };
+//..
+// We can use a collection as a searchable set:
+//..
+        ElementCollection<setS> setCollection(theBeatles, theBeatles + 4);
+        Element unknown(843, "Unkown",   +0);
+        BOOST_CHECK(( setCollection.theContainer().find(unknown) == setCollection.end() ));
+        BOOST_CHECK(( setCollection.theContainer().find(john)->familyName == "Lennon" ));
+//..
+// and access the iterators of the collection (here identical to the
+// iterators of the container):
+//..
+        BOOST_CHECK(( setCollection.begin()->familyName == "Harrison" ));
+        BOOST_CHECK(( (--setCollection.end())->familyName == "Starr" ));
+//..
+// or we can use the collection as an indexed array:
+//..
+        ElementCollection<vecS> vectorCollection(theBeatles, theBeatles + 4);
+        BOOST_CHECK(( vectorCollection.theContainer()[1].familyName == "Lennon" ));
+        BOOST_CHECK(( vectorCollection.theContainer()[3].familyName == "Starr" ));
+//..
+// and access the iterators of the collection (whose value type here is the
+// descriptor, not the same as the iterators of the container):
+//..
+        BOOST_CHECK( *vectorCollection.begin() == 0 );
+        BOOST_CHECK( *vectorCollection.end() == 4 );
+
+        return true;
+    }
+//..
+
+// ===========================================================================
+//                              BOOST TEST APPARATUS
+// ===========================================================================
+
+int test_main(int, char **)
+{
+    #if 0
+    BOOST_CHECK(( selector_requirements(hashS()) ));
+    #endif
+    BOOST_CHECK(( selector_requirements(listS()) ));
+    BOOST_CHECK(( selector_requirements(setS()) ));
+    BOOST_CHECK(( selector_requirements(vecS()) ));
+
+    #if 0
+    BOOST_CHECK(( selection_requirements<container_gen<hashS, int>, hashS>() ));
+    #endif
+    BOOST_CHECK(( container_gen_requirements<container_gen<listS, int>, int, listS>() ));
+    BOOST_CHECK(( container_gen_requirements<container_gen<setS, int>, int, setS>() ));
+    BOOST_CHECK(( container_gen_requirements<container_gen<vecS, int>, int, vecS>() ));
+
+    BOOST_CHECK(( usageExample() ));
+    
+    return 0;
+}
+