Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r59815 - sandbox/tokenmap/libs/tokenmap/doc
From: sl_at_[hidden]
Date: 2010-02-21 12:59:59


Author: sl_
Date: 2010-02-21 12:59:59 EST (Sun, 21 Feb 2010)
New Revision: 59815
URL: http://svn.boost.org/trac/boost/changeset/59815

Log:
initial
Text files modified:
   sandbox/tokenmap/libs/tokenmap/doc/tokenmap.qbk | 158 ++++++++++++++++++++++++++++++++++-----
   1 files changed, 135 insertions(+), 23 deletions(-)

Modified: sandbox/tokenmap/libs/tokenmap/doc/tokenmap.qbk
==============================================================================
--- sandbox/tokenmap/libs/tokenmap/doc/tokenmap.qbk (original)
+++ sandbox/tokenmap/libs/tokenmap/doc/tokenmap.qbk 2010-02-21 12:59:59 EST (Sun, 21 Feb 2010)
@@ -89,7 +89,7 @@
 [def __SGI_FRONT_INSERTION_SEQUENCE__ [@http://www.sgi.com/tech/stl/FrontInsertionSequence.html Front Insertion Sequence]]
 [def __SGI_BACK_INSERTION_SEQUENCE__ [@http://www.sgi.com/tech/stl/BackInsertionSequence.html Back Insertion Sequence]]
 [def __SGI_INPUT_ITERATOR__ [@http://www.sgi.com/tech/stl/InputIterator.html Input Iterator]]
-[def __SGI_FORWARD_ITERATOR__ [@http://www.sgi.com/tech/stl/ForwardIterator.html Forward Iterator]]
+[def __SGI_FORWARD_ITERATOR__ [@http://www.sgi.com/tech/stl/ForwardIterator.o Forward Iterator]]
 [def __SGI_STRICT_WEAK_ORDERING__ [@http://www.sgi.com/tech/stl/StrictWeakOrdering.html Strict Weak Ordering]]
 
 [def __EIFFEL__ [@http://www.eiffel.com/ Eiffel]]
@@ -115,33 +115,145 @@
 
 [heading Description]
 
-__BOOST_TOKENMAP_LOGO__
+In summary, a tokenmap is a data structure that maps auto-generated tokens with
+elements of the collection.
 
-Boost.Tokenmap is a bidirectional maps library for C++. With Boost.Tokenmap you can create associative containers in which both types can be used as key. A `tokenmap<X,Y>`
-can be thought of as a combination of a `std::map<X,Y>` and a `std::map<Y,X>`.
-The learning curve of tokenmap is almost flat if you know how to use standard
-containers. A great deal of effort has been put into mapping the naming scheme of the
-STL in Boost.Tokenmap. The library is designed to match the common STL containers.
+Boost.Tokenmap is a (perfect) hash container library for C++. The library provides
+a tokenmap, a data structure that maps auto-generated tokens with elements of
+the collection. An important distinction between tokenmap and other dictionary-like
+containers (such as std::map or boost::unordered) is that tokenmap generates the
+keys internally (referred to as "tokens") rather than relying on users to provide
+them. Specifically, when a new element is inserted into the tokenmap, an apparently
+random token is returned back to the caller. The returned token can later be used
+for very efficient lookups.
 
 [heading Influences and Related Work]
 
 The design of Boost.Tokenmap interface follows the standard template library.
-It has been strongly influenced by Joaquin Lopez Muñoz's Boost.MultiIndex library
-(the heart of tokenmaps) and codeproject::tokenmap library.
 
 [endsect]
 
-[include introduction.qbk]
-[include quick_tutorial.qbk]
-[include tutorial.qbk]
-[include tokenmap_and_boost.qbk]
-[include reference.qbk]
-[include compiler_specifics.qbk]
-[include performance.qbk]
-[include examples.qbk]
-[include test_suite.qbk]
-[include future_work.qbk]
-[include release_notes.qbk]
-[include rationale.qbk]
-[include history.qbk]
-[include acknowledgements.qbk]
+[section Quick tutorial]
+
+A convenience header is avaiable in the boost directory:
+
+ #include <boost/tokenmap.hpp>
+
+Lets define a token map for strings. The following code creates an empty tokenamp
+container with initial capacity set to 10000, load factor set to 0.7 and current
+time as seed for pseudo-number generator:
+
+typedef tokenmap<std::string, unsigned int> tokenmap_type;
+tokenmap_type names( 10000, 0.7, time(NULL) );
+
+Next, to insert elements into the container we do:
+
+tokenamp_type::value_type rob =
+ names.insert( "Robert DeNiro" );
+tokenamp_type::value_type mart =
+ names.insert( "Martin Scorsese" );
+
+The returned from insert `tokenamp_type::value_type' is a pair, defined as
+std::pair<unsigned int, std::string*>. The first element of the pair is an
+auto-generated token, whereas the second element is a pointer to the stored
+element that maps to it.
+
+With the returned token we can perform efficient lookups within the container,
+example:
+
+tokenamp_type::mapped_type * name = names.find( rob.first );
+
+We can also check if an element exists:
+
+bool found = names.exists( rob.first );
+
+Finally, we can remove the element:
+
+std::auto_ptr<map_type::mapped_type> take_over
+ = names.pop( rob.first );
+
+[endsect]
+
+[section Reference]
+
+[section Headers]
+
+* "boost/tokenmap.hpp" ['(includes "boost/tokenmap/tokenmap.hpp" and imports the tokenmap class to boost namespace)]
+
+[endsect]
+
+[section Header "boost/tokenmap/tokenmap.hpp" synopsis]
+
+ namespace boost {
+ namespace tokenmaps {
+
+ template <typename value__, typename key__ = uint32_t>
+ class tokenmap
+ {
+ public:
+
+ // Metadata
+
+ typedef uint64_t hash_type;
+ typedef key__ key_type;
+ typedef value__ mapped_type;
+ typedef std::pair<key_type, mapped_type*> value_type;
+
+ // Constructor
+
+ tokenmap(size_t capacity, float load_factor, hash_type seed);
+
+ // Destructor
+
+ ~tokenmap();
+
+ // Modifiers
+
+ value_type insert(mapped_type const & value);
+
+ value_type insert(std::auto_ptr<mapped_type> value);
+
+ std::auto_ptr<mapped_type> pop(key_type key);
+
+ // Accessors
+
+ mapped_type * find(key_type key) const;
+
+ bool exists(key_type key) const;
+
+ key_type size() const;
+ };
+
+ } // namespace tokenmap
+ } // namespace boost
+
+[endsect]
+
+[section Class template tokenmap]
+[endsect]
+
+[section Nested types]
+[endsect]
+
+[section Constructors, copy and assignment]
+ tokenmap(size_t capacity, float load_factor, hash_type seed);
+
+* [*Effects:] Constructs an empty `tokenmap`.
+* [*Complexity:] Constant.
+
+[endsect]
+
+[section Performance ]
+[endsect]
+
+[section Examples ]
+[endsect]
+
+[section Rationale ]
+[endsect]
+
+[section Future Work ]
+[endsect]
+
+[section Acknowledgements ]
+[endsect]


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk