From a007b0a02adf04fdfe84a6169b03596fca490131 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Sun, 28 Aug 2011 14:15:04 +0200 Subject: Document wrapper support for composite values and containers --- NEWS | 22 +++++++++-------- doc/manual.xhtml | 73 +++++++++++++++++++++++++++++++++++++++----------------- 2 files changed, 63 insertions(+), 32 deletions(-) diff --git a/NEWS b/NEWS index 29f3c40..fac6eb6 100644 --- a/NEWS +++ b/NEWS @@ -16,16 +16,18 @@ Version 1.6.0 the ODB manual. * Support for value wrappers. An ODB value wrapper is a class template - that wraps a value type. Common examples of wrappers are smart pointers, - holders, and "optional value" containers such as boost::optional. A - wrapper can be transparent or it can handle the NULL semantics. To - allow the easy conversion of value types that do not support the NULL - semantics into the ones that do, the odb::nullable class template has - been added. ODB also now includes built-in support for std::auto_ptr - and std::tr1::shared_ptr smart pointers as value wrappers as well as - for boost::shared_ptr and QSharedPointer via the Boost and Qt profiles. - For more information, refer to Section 7.3, "NULL Value Semantics" in - the ODB manual. + that wraps a value type or a container. Common examples of wrappers + are smart pointers, holders, and "optional value" containers such as + boost::optional. A wrapper can be transparent or it can handle the + NULL semantics. To allow the easy conversion of value types that do + not support the NULL semantics into the ones that do, the odb::nullable + class template has been added. ODB also now includes built-in support for + std::auto_ptr and std::tr1::shared_ptr smart pointers as value wrappers + as well as for boost::shared_ptr and QSharedPointer via the Boost and Qt + profiles. Currently, the NULL semantics is only supported for simple + values but smart pointers can still be used with composite values and + containers. For more information, refer to Section 7.3, "NULL Value + Semantics" in the ODB manual. * Support for the boost::optional container in the Boost profile. A data member of the boost::optional type is mapped to a column that can have diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 44bfc8b..aac66f0 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -392,7 +392,7 @@ for consistency. - 7.3NULL Value Semantics + 7.3Pointers and NULL Value Semantics @@ -2002,8 +2002,9 @@ class name create dynamically allocated instances of persistent classes and return pointers to these instances. As we will see in later chapters, pointers are also used to establish relationships between objects - (Chapter 6, Relationships) as well as to cache - persistent objects in a session (Chapter 9, Session).

+ (Chapter 6, "Relationships") as well as to cache + persistent objects in a session (Chapter 9, + "Session").

By default, all these mechanisms use raw pointers to return, pass, and cache objects. This is normally sufficient for applications @@ -3747,7 +3748,10 @@ private: behaves like a value type. That is, when an object is made persistent, the elements of the container are stored in the database. Similarly, when a persistent object is loaded from the database, the contents - of the container are automatically loaded as well.

+ of the container are automatically loaded as well. A data member + of a container type can also use a smart pointer, as discussed + in Section 7.3, "Pointers and NULL + Value Semantics".

While an ordinary member is mapped to one or more columns in the object's table, a member of a container type is mapped to a separate @@ -5407,7 +5411,7 @@ CREATE TABLE person_nickname (

Similar to columns, we can make the table prefix empty.

-

7.3 NULL Value Semantics

+

7.3 Pointers and NULL Value Semantics

Relational database systems have a notion of the special NULL value that is used to indicate the absence @@ -5570,6 +5574,31 @@ class person Qt), provide support for smart pointers found in these frameworks and libraries (Part III, "Profiles").

+

Currently, ODB supports the NULL semantics only + for simple values. In future versions this support will be extended + to composite values and containers. With this limitation in mind, + we can still use smart pointers in data members of composite value + and container types. The only restriction is that these pointers + must not be NULL. For example:

+ + 
+#pragma db value
+struct name
+{
+  std::string first_;
+  std::string last_;
+};
+
+#pragma db object
+class person
+{
+  ...
+
+  std::auto_ptr<name> name_;
+  std::auto_ptr<std::vector<name> > aliases_;
+};
+
+ @@ -6710,10 +6739,10 @@ typedef shared_ptr<person> person_ptr;

For a more detailed discussion of the NULL semantics - for values, refer to Section 7.3, "NULL - Value Semantics". For a more detailed discussion of the - NULL semantics for object pointers, refer to - Chapter 6, "Relationships".

+ for values, refer to Section 7.3, "Pointers and + NULL Value Semantics". For a more detailed + discussion of the NULL semantics for object pointers, + refer to Chapter 6, "Relationships".

10.2.4 default

@@ -7262,10 +7291,10 @@ class account not_null specifier), then a warning is issued.

For a more detailed discussion of the NULL semantics - for values, refer to Section 7.3, "NULL - Value Semantics". For a more detailed discussion of the - NULL semantics for object pointers, refer to - Chapter 6, "Relationships".

+ for values, refer to Section 7.3, "Pointers and + NULL Value Semantics". For a more detailed + discussion of the NULL semantics for object pointers, + refer to Chapter 6, "Relationships".

10.3.5 default

@@ -9975,9 +10004,9 @@ odb --profile boost/date-time ... refer to Section 3.2, "Object Pointers" and Chapter 6, "Relationships". For more information on using smart pointers as pointers to values, refer to - Section 7.3, "NULL Value Semantics". - When used as a pointer to a value, only boost::shared_ptr - is supported. For example:

+ Section 7.3, "Pointers and NULL Value + Semantics". When used as a pointer to a value, only + boost::shared_ptr is supported. For example:

 #pragma db object
@@ -10067,8 +10096,8 @@ class person
 
   
In a relational database boost::optional is mapped to
      a column that can have a NULL value. Similar to
-     odb::nullable (Section 7.3,
-     "NULL Value Semantics"), it can be used to add the
+     odb::nullable (Section 7.3, "Pointers and
+     NULL Value Semantics"), it can be used to add the
      NULL semantics to existing C++ types. For example:

 
   
@@ -10515,9 +10544,9 @@ class Person
      refer to Section 3.2, "Object Pointers" and
      Chapter 6, "Relationships". For more information
      on using smart pointers as pointers to values, refer to
-     Section 7.3, "NULL Value Semantics".
-     When used as a pointer to a value, only QSharedPointer
-     is supported. For example:

+     Section 7.3, "Pointers and NULL Value
+     Semantics". When used as a pointer to a value, only
+     QSharedPointer is supported. For example:

 
   
 #pragma db object
@@ -10751,7 +10780,7 @@ class Person
      the INTEGER type represents a clock time as the number of
      seconds since midnight. These mappings have to be explicitly requested
      using the db type pragma
-     (Section 10.3.3,value "type"), as shown
+     (Section 10.3.3, "type"), as shown
      in the following example:

 
 
-- 
cgit v1.1