diff --git a/doc/guidelines.html b/doc/guidelines.html index fbb2147..9ca07eb 100644 --- a/doc/guidelines.html +++ b/doc/guidelines.html @@ -290,6 +290,8 @@ ul.auto-toc {

Boost Pointer Container Library

Usage Guidelines

+
+

Choosing the right container

The recommended usage pattern of the container classes are the same as the for normal standard containers.

ptr_vector, ptr_list and ptr_deque offer the programmer different @@ -306,6 +308,60 @@ one element for each key. Otherwise, it supports equivalent keys. ptr_set and ptr_map support unique keys. ptr_multiset and ptr_multimap support equivalent keys.

+
+
+

Recommended practice for Object-Oriented Programming

+

Idiomtic Object-Oriented Programming in C++ looks a bit different from +the way it is done in other languages. This is partly because C++ +has both value and reference semantics, and partly because C++ is more flexible +than other languages. Below is a list of recommendations that you are +encouraged to follow:

+
+

1. Make base classes abstract and without data

+

The has the following advantages:

+
+
    +
  1. It reduces coupling because you do not have to maintain or update state
    2. +
+ +
    +
  1. It helps you to avoid slicing
    2. +
+ +
    +
  1. It ensures you override the right function
    2. +
+
+

You might also want to read the following articles:

+ + +
+
+

2. Make virtual functions private and provide a non-virtual public forwarding function

+

This has the following advantages:

+
+
    +
  1. It makes sure all calls to the virtual function always goes through one place in your code
    2. +
+ +
    +
  1. It enables you to check preconditions and postconditions inside the forwarding function
    2. +
+
+

You might also want to read Herb Sutter's article Virtuality.

+
+
+

3. Derive your base class from boost::noncopyable

+

Having an abstact base class prevents slicing when the base class is involved, but +it does not prevent it for classes further down the hierarchy. This is where +boost::noncopyable is handy to use.

+
+
+

4. don't allow nulls if you can avoid it, Null Object

Navigate:

  • home
    • @@ -320,5 +376,7 @@ support equivalent keys.

+
+
diff --git a/doc/guidelines.rst b/doc/guidelines.rst index 142dd00..cef8f54 100755 --- a/doc/guidelines.rst +++ b/doc/guidelines.rst @@ -8,6 +8,9 @@ Usage Guidelines ================ +Choosing the right container +---------------------------- + The recommended usage pattern of the container classes are the same as the for normal standard containers. @@ -27,6 +30,71 @@ one element for each key. Otherwise, it supports equivalent keys. ``ptr_multiset`` and ``ptr_multimap`` support equivalent keys. +Recommended practice for Object-Oriented Programming +---------------------------------------------------- + +Idiomtic Object-Oriented Programming in C++ looks a bit different from +the way it is done in other languages. This is partly because C++ +has both value and reference semantics, and partly because C++ is more flexible +than other languages. Below is a list of recommendations that you are +encouraged to follow: + +1. Make base classes abstract and without data +++++++++++++++++++++++++++++++++++++++++++++++ + +The has the following advantages: + + a. It reduces *coupling* because you do not have to maintain or update state + + .. + + b. It helps you to avoid *slicing* + + .. + + c. It ensures you *override* the right function + +You might also want to read the following articles: + +- Kevlin Henney's `Six of the best`__ + +.. __: http://www.two-sdg.demon.co.uk/curbralan/papers/SixOfTheBest.pdf + +- Jack Reeves' `Multiple Inheritance Considered Useful`__ + +.. __: http://www.ddj.com/documents/s=10011/q=1/cuj0602reeves/0602reeves.html + + +2. Make virtual functions private and provide a non-virtual public forwarding function +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +This has the following advantages: + + a. It makes sure all calls to the virtual function always goes through one place in your code + + .. + + b. It enables you to check preconditions and postconditions inside the forwarding function + +You might also want to read Herb Sutter's article `Virtuality`__. + +.. __: http://www.gotw.ca/publications/mill18.htm + +3. Derive your base class from ``boost::noncopyable`` ++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Having an abstact base class prevents slicing when the base class is involved, but +it does not prevent it for classes further down the hierarchy. This is where +`boost::noncopyable`__ is handy to use. + +.. __ : http://www.boost.org/libs/utility/utility.htm#Class_noncopyable + + + +4. don't allow nulls if you can avoid it, Null Object +++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + **Navigate:** - `home `_ diff --git a/doc/reference.html b/doc/reference.html index 9e38297..9ae92cc 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -333,7 +333,6 @@ the Clone

The Clonable concept

Refinement of

@@ -365,22 +364,26 @@ the containers does not even require the stored type to be Clonable.

Valid expressions

---++++ + + +
Expression Type SemanticsPostcondition
new_clone(a); T* Allocate a new object that can be considered equivalent to the a objecttypeid(new_clone(a)) == typeid(a)
delete_clone(ptr); void Deallocate an object previously allocated with allocate_clone(). Must not throw 
diff --git a/doc/reference.rst b/doc/reference.rst index 7a55332..295d0d9 100755 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -52,7 +52,6 @@ The Clonable concept **Refinement of** -- Copy Constructible - Heap Allocable - Heap Deallocable @@ -70,11 +69,11 @@ the containers does not even require the stored type to be Clonable. **Valid expressions** -===================================== =========================== ======================================================================================== - **Expression** **Type** **Semantics** - ``new_clone(a);`` ``T*`` Allocate a new object that can be considered equivalent to the ``a`` object +===================================== =========================== ======================================================================================== =================================== + **Expression** **Type** **Semantics** **Postcondition** + ``new_clone(a);`` ``T*`` Allocate a new object that can be considered equivalent to the ``a`` object ``typeid(new_clone(a)) == typeid(a)`` ``delete_clone(ptr);`` ``void`` Deallocate an object previously allocated with ``allocate_clone()``. Must not throw -===================================== =========================== ======================================================================================== +===================================== =========================== ======================================================================================== =================================== Default implementation