Update of /cvsroot/boost/boost/libs/bimap/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv2441/doc
Modified Files:
bimap.qbk bimap_and_boost.qbk examples.qbk jamfile.v2
quick_tutorial.qbk tutorial.qbk
Log Message:
Xpressive & typeof sections
Index: bimap.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/bimap/doc/bimap.qbk,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- bimap.qbk 31 May 2007 07:07:15 -0000 1.2
+++ bimap.qbk 4 Jun 2007 21:17:25 -0000 1.3
@@ -36,7 +36,8 @@
[def __BIMAP_STRUCTURES__ [$images/bimap/bimap.structures.png]]
[def __TAGGED__ [$images/bimap/tagged.png]]
[def __MORE_BIMAP_STRUCTURES__ [$images/bimap/more.bimap.structures.png]]
-
+[def __RELATION_AND_PAIR__ [$images/bimap/relation.and.pair.png]]
+[def __RELATION_AND_PAIR_WITH_INFO__
[$images/bimap/relation.and.pair.with.info.png]]
[/ People ]
@@ -73,10 +74,10 @@
[def __BOOST_RANGE__ [EMAIL PROTECTED]://www.boost.org/doc/html/range.html
[*Boost.Range]]]
[def __BOOST_FOREACH__ [EMAIL PROTECTED]://www.boost.org/doc/html/foreach.html
[*Boost.Foreach]]]
[def __BOOST_TEST__ [EMAIL PROTECTED]://www.boost.org/libs/test/doc/index.html
[*Boost.Test]]]
+[def __BOOST_TYPEOF__ [EMAIL
PROTECTED]://www.boost.org/libs/typeof/doc/index.html [*Boost.Typeof]]]
+[def __BOOST_XPRESSIVE__ [EMAIL
PROTECTED]://www.boost.org/libs/xpressive/doc/index.html [*Boost.Xpressive]]]
-[/extern links]
-
[/ Extern Links ]
[def __CPP_STANDARD_LIBRARY_TECHNICAL_REPORT__ [EMAIL
PROTECTED]://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1836.pdf C++
Standard Library Technical Report]]
@@ -133,6 +134,8 @@
[heading Description]
+__BOOST_BIMAP_LOGO__
+
Boost.Bimap is a bidirectional maps library for C++. With Boost.Bimap you can
create associative containers in which both types can be used as key. A
`bimap<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 bimap is almost flat if you know how to use standard
Index: bimap_and_boost.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/bimap/doc/bimap_and_boost.qbk,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- bimap_and_boost.qbk 31 May 2007 07:07:15 -0000 1.2
+++ bimap_and_boost.qbk 4 Jun 2007 21:17:25 -0000 1.3
@@ -83,7 +83,7 @@
]
You can also read
-[link boost_bimap.the_tutorial.hooking_information Hooking Information] for
more
+[link boost_bimap.the_tutorial.additional_information Additional Information]
for more
information about the relation of this two libraries.
[endsect]
@@ -126,6 +126,16 @@
[Eric Niebler]
[Iteration]]
+[[ __BOOST_TYPEOF__ ][
+Typeof operator emulation]
+[Arkadiy Vertleyb, Peder Holt]
+[Using BOOST_AUTO while we wait for C++0x]]
+
+[[ __BOOST_XPRESSIVE__ ][
+Regular expressions that can be written as strings or as expression templates]
+[Eric Niebler]
+[Help to fill a bimap from a string]]
+
[[ __BOOST_PROPERTY_MAP__ ][
Concepts defining interfaces which map key objects to value objects]
[Jeremy Siek]
@@ -295,6 +305,51 @@
[endsect]
+[section Boost.Typeof]
+
+[import ../example/bimap_and_boost/typeof.cpp]
+
+Once C++0x is out we are going to be able to write code like:
+
+ auto iter = bm.by<name>().find("john");
+
+instead of the more verbose
+
+ bm_type::map_by<name>::iterator iter = bm.by<name>().find("john");
+
+Boost.Typeof defines a macro BOOST_AUTO that can be used as a library
+solution to the auto keyword while we wait for the next standard.
+
+If we have
+
+[code_bimap_and_boost_typeof_first]
+
+The following code snippet
+
+[code_bimap_and_boost_typeof_not_using_auto]
+
+can be rewrited as
+
+[code_bimap_and_boost_typeof_using_auto]
+
[EMAIL PROTECTED]/../example/bimap_and_boost/typeof.cpp Go to source code]
+
+[endsect]
+
+[section Boost.Xpressive]
+
+[import ../example/bimap_and_boost/xpressive.cpp]
+
+Using Boost.Xpressive we can parse a file and insert the relations in a bimap
+in the same step. It is just amazing the power of four lines of code.
+Here is an example (it is just beatifull)
+
+[code_bimap_and_boost_xpressive]
+
[EMAIL PROTECTED]/../example/bimap_and_boost/xpressive.cpp Go to source code]
+
+[endsect]
+
[section Boost.Property_map]
The Boost Property Map Library consists mainly of interface specifications in
the form of
Index: examples.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/bimap/doc/examples.qbk,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- examples.qbk 31 May 2007 07:07:16 -0000 1.2
+++ examples.qbk 4 Jun 2007 21:17:25 -0000 1.3
@@ -100,6 +100,14 @@
foreach.cpp ]]
[Bimap and Boost.Foreach: Iterating over bimaps ]]
[EMAIL PROTECTED]/../example/bimap_and_boost/typeof.cpp
+ typeof.cpp ]]
+ [Bimap and Boost.Typeof: using BOOST_AUTO while we wait for C++0x ]]
+
[EMAIL PROTECTED]/../example/bimap_and_boost/xpressive.cpp
+ xpressive.cpp ]]
+ [Bimap and Boost.Xpressive: Inserting elements in a bimap ]]
+
[EMAIL PROTECTED]/../example/bimap_and_boost/serialization.cpp
serialization.cpp: ]]
[Bimap and Boost.Serialization: Load and save bimaps and iterators ]]
Index: jamfile.v2
===================================================================
RCS file: /cvsroot/boost/boost/libs/bimap/doc/jamfile.v2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- jamfile.v2 25 May 2007 04:57:21 -0000 1.2
+++ jamfile.v2 4 Jun 2007 21:17:25 -0000 1.3
@@ -21,9 +21,10 @@
:
bimap
:
- <xsl:param>toc.max.depth=4
+ <xsl:param>toc.max.depth=2
<xsl:param>toc.section.depth=4
<xsl:param>chunk.section.depth=2
+ <xsl:param>logo.image.src="'images/bimap/boost.bimap.header.png'"
;
@@ -31,7 +32,6 @@
# -----------------------------------------------------------------------------
# This generate the doxydocs and write "bimap.hdt".
# Delete this file if you want to regenerate the doxydocs again
-
# import directdoxygen ;
# html-doxydocs bimap.hdt : bimap.hdf ;
Index: quick_tutorial.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/bimap/doc/quick_tutorial.qbk,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- quick_tutorial.qbk 25 May 2007 01:07:10 -0000 1.1
+++ quick_tutorial.qbk 4 Jun 2007 21:17:25 -0000 1.2
@@ -38,9 +38,6 @@
You can see how a bimap container offers three views over the same collection
of bidirectional relations.
-The `relation` class represents two related elements. The two values are
-named left and right to express the symmetry of this type.
-
If we have any generic function that work with maps
template< class MapType >
@@ -71,6 +68,14 @@
...
]
+[heading Layout of the relation and the pairs of a bimap]
+
+The `relation` class represents two related elements. The two values are
+named left and right to express the symmetry of this type.
+The bimap pair classes are signature-compatible with `std::pairs`.
+
+__RELATION_AND_PAIR__
+
[heading Step by step]
[import ../example/step_by_step.cpp]
Index: tutorial.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/bimap/doc/tutorial.qbk,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- tutorial.qbk 31 May 2007 07:07:18 -0000 1.2
+++ tutorial.qbk 4 Jun 2007 21:17:25 -0000 1.3
@@ -50,8 +50,8 @@
mapping containers as a particular case. The section
[link boost_bimap.the_tutorial.unconstrained_sets Unconstrained Sets] explains
how they work.
-# The section [link boost_bimap.the_tutorial.hooking_information Hooking
Information]
-explains how to hook additional information to each relation of a bimap.
+# The section [link boost_bimap.the_tutorial.additional_information Additional
information]
+explains how to attach information to each relation of a bimap.
# The final section
([link boost_bimap.the_tutorial.complete_instantiation_scheme Complete
Instantiation Scheme])
@@ -112,9 +112,35 @@
You can view it from one side, obtaining a `std::map` compatible
container, or you can work directly with the whole relation.
+The next diagram shows the layout of the relation and pairs of a bimap. It is
+the one from the ['one minute tutorial]
+
+__RELATION_AND_PAIR__
+
+Bimap pairs are signature-compatible with standard pairs but are different
+from them. As you will see in other sections they can be tagged with user
+defined names and additional information can be attached to them. You can
+convert from `std::pairs` to bimap pairs directly but the reverse conversion
+is not provided. This mean that you can insert elements in a bimap using
+algorithms like `std::copy` from containers `like std::map`, or use
`std::make_pair`
+to add new elements. However it is best to use `bm.left.insert(
bm_type::left_value_type(f,s) )` instead of `bm.insert( std::make_pair(f,s) )`
to avoid an extra call to the
+copy constructor of each type.
+
The following code snippet shows the relation between a bimap and standard
maps.
+[note
+You have to used references to views, and not directly views object.
+Views cannot be constructed as separate objects from the container they
+belong to, so the following:
+``
+// Wrong: we forgot the & after bm_type::left_type
+bm_type::left_map lm = bm.left;
+``
+does not compile, since it is trying to construct the view object `lm`.
+This is a common source of errors in user code.
+]
+
[EMAIL PROTECTED]/../example/standard_map_comparison.cpp Go to source code]
[import ../example/standard_map_comparison.cpp]
@@ -752,8 +778,8 @@
valid C++ type. In a bimap, the types are always tagged. If you do not
specify your own tag, the container uses `member_at::left` and
`member_at::right` to tag the left and right sides respectively. In order
-to specify a custom tag, the collection type specification of each side has to
-be tagged. Tagging a type is very simple:
+to specify a custom tag, the type of each side has to be tagged.
+Tagging a type is very simple:
typedef tagged< int, a_tag > tagged_int;
@@ -770,7 +796,11 @@
struct Left {};
struct Right {};
- typedef bimap< tagged< int, Left >, tagged< int, Right > bm_type;
+ typedef bimap<
+ multiset_of< tagged< int, Left > >,
+ unordered_set_of< tagged< int, Right > >
+ > bm_type;
+
bm_type bm;
//...
@@ -840,7 +870,7 @@
[endsect]
-[section Hooking Information]
+[section Additional information]
[import ../example/tutorial_info_hook.cpp]
@@ -873,12 +903,14 @@
neither.
Boost.Bimap provides support for this kind of situations by means of
-information hooking.
-You can pass an extra parameter to a bimap with the type `info_hook< InfoType
>`
-and an `info` member of type `InfoType` will appear in the relation and bimap
+an embedded information member.
+You can pass an extra parameter to a bimap: `with_info< InfoType >`
+and an `info` member of type `InfoType` will appear in the relation and bimap
pairs.
-Relations and bimap pairs constructors can take an extra argument.
+__RELATION_AND_PAIR_WITH_INFO__
+
+Relations and bimap pairs constructors will take an extra argument.
If only two arguments are used, the information will be initialized with
their default constructor.
@@ -894,6 +926,11 @@
[code_tutorial_info_hook_info_at]
+The info member can be tagged just as the left or the right member. The
following
+is a rewrite of the above example using user defined names:
+
+[code_tutorial_info_hook_tagged_info]
+
[EMAIL PROTECTED]/../example/tutorial_info_hook.cpp Go to source code]
[endsect]
@@ -907,15 +944,15 @@
LeftCollectionType, RightCollectionType
[ , SetTypeOfRelation ] // Default to left_based
- [ , info_hook< Info > ] // Default to no info
+ [ , with_info< Info > ] // Default to no info
[ , Allocator ] // Default to std::allocator<>
> bm;
`{Side}CollectionType` can directly be a type. This defaults to
`set_of<Type>`, or can be a `{CollectionType}_of<Type>` specification.
-Additionally, these two parameters can be tagged to specify other tags
-instead of the usual `member_at::-Side-` tags.
+Additionally, the type of this two parameters can be tagged to specify
+user defined names instead of the usual `member_at::-Side-` tags.
The possibles way to use the first parameter are:
@@ -937,7 +974,7 @@
* Left collection type: `set_of< LeftType >`
* Left tag: `Tag`
- bimap< tagged< `['CollectionType]`_of< Type >, Tag >, R >
+ bimap< `['CollectionType]`_of< tagged< Type, Tag > >, R >
* Left type: `Type`
* Left collection type: ['CollectionType]`_of< LeftType >`
@@ -946,7 +983,8 @@
The same options are available for the second parameter.
The last three parameters are used to specify the collection type of the
relation,
-the information hook and the allocator type.
+the information member and the allocator type.
+
If you want to specify a custom allocator type while relying on the default
value of CollectionTypeOfRelation, you can do so by simply writing
`bimap<LeftKeyType, RightKeyType, Allocator>`. Boost.Bimap's internal
@@ -971,14 +1009,14 @@
* allocator: std::allocator
- bimap< L, R , SetOfRelationType, info_hook<Info> >
+ bimap< L, R , SetOfRelationType, with_info<Info> >
* set_of_relation_type: SetOfRelationType
* info: Info
* allocator: std::allocator
- bimap< L, R , SetOfRelationType, info_hook<Info>, Allocator>
+ bimap< L, R , SetOfRelationType, with_info<Info>, Allocator>
* set_of_relation_type: SetOfRelationType
* info: Info
@@ -992,14 +1030,14 @@
* allocator: Allocator
- bimap< L, R , info_hook<Info> >
+ bimap< L, R , with_info<Info> >
* set_of_relation_type: based on the left key type
* info: Info
* allocator: std::allocator
- bimap< L, R , info_hook<Info>, Allocator>
+ bimap< L, R , with_info<Info>, Allocator>
* set_of_relation_type: based on the left key type
* allocator: Allocator
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/boost-cvs
