Author: wyoung
Date: Fri Mar 17 07:32:53 2006
New Revision: 1256
URL: http://svn.gna.org/viewcvs/mysqlpp?rev=1256&view=rev
Log:
Fixed the "0, 0" SSQLS stuff in the user manual, and clarified the
discussion of how these two parameters interact.
Modified:
branches/v2.1-bakefile/Wishlist
branches/v2.1-bakefile/doc/userman/userman.xml
Modified: branches/v2.1-bakefile/Wishlist
URL:
http://svn.gna.org/viewcvs/mysqlpp/branches/v2.1-bakefile/Wishlist?rev=1256&r1=1255&r2=1256&view=diff
==============================================================================
--- branches/v2.1-bakefile/Wishlist (original)
+++ branches/v2.1-bakefile/Wishlist Fri Mar 17 07:32:53 2006
@@ -28,13 +28,6 @@
possible to subclass yourself from the "MySQL++'s developers"
base class.
-
- o The manual recommends using "0, 0" as the second and third
- parameters for creating SSQLSes, but this doesn't actually
- compile. Try to enumerate all the possible function overloading
- problems in the manual, and come up with a solid recommendation
- that will always work. "1, 0" seems to work on a lot of code, but
- we should know _why_ it works.
o Viktor Stark reports that a BLOB of binary data containing 0's
appears to be truncated when stored in an SSQLS with a std::string
Modified: branches/v2.1-bakefile/doc/userman/userman.xml
URL:
http://svn.gna.org/viewcvs/mysqlpp/branches/v2.1-bakefile/doc/userman/userman.xml?rev=1256&r1=1255&r2=1256&view=diff
==============================================================================
--- branches/v2.1-bakefile/doc/userman/userman.xml (original)
+++ branches/v2.1-bakefile/doc/userman/userman.xml Fri Mar 17 07:32:53 2006
@@ -1290,17 +1290,20 @@
<para>This is the most basic sort of SSQLS declaration:</para>
<programlisting>
-sql_create_5(stock, 0, 0,
+sql_create_5(stock, 1, 0,
string, item,
int, num,
double, weight,
double, price,
mysqlpp::Date, date)</programlisting>
- <para>This creates a C++ structure called 'stock'
- containing five member variables, along with some
- constructors and other member functions useful with
- MySQL++.</para>
+ <para>This creates a C++ structure called
+ <classname>stock</classname> containing
+ five member variables (<varname>item</varname>,
+ <varname>num</varname>, <varname>weight</varname>,
+ <varname>price</varname> and <varname>date</varname>),
+ along with some constructors and other member functions
+ useful with MySQL++.</para>
<para>One of the generated constructors takes a reference
to a mysqlpp::Row object, allowing you to easily populate
@@ -1318,163 +1321,115 @@
<para>The general format of this set of macros is:</para>
<programlisting>
-sql_create_#(NAME, KEYS, INITPARMS, TYPE1, ITEM1, ... TYPE#,
ITEM#)</programlisting>
-
- <para>Where # is the number of member variables,
- NAME is the name of the structure you wish to create,
- TYPE<emphasis>x</emphasis> is the type name for a
- member variable, and ITEM<emphasis>x</emphasis> is that
+sql_create_#(NAME, COMPCOUNT, SETCOUNT, TYPE1, ITEM1, ... TYPE#,
ITEM#)</programlisting>
+
+ <para>Where # is the number of member
+ variables, <parameter>NAME</parameter> is
+ the name of the structure you wish to create,
+ <parameter>TYPEx</parameter> is the type of a member
+ variable, and <parameter>ITEMx</parameter> is that
variable's name.</para>
- <para>The KEYS and INITPARMS arguments can always be zero,
- to keep things simple. We will discuss what happens if
- you use different values in the next few sections.</para>
- </sect2>
-
-
- <sect2>
- <title>sql_create with Compare</title>
-
- <para>SSQLS structures can also have member functions that
- allow you to compare one structure to another. You simply
- change the first 0 in the previous example (KEYS) to a
- higher value. If this number is N, then two structures
- are considered equal if the first N members of each
- are equal.</para>
-
- <para>For example:</para>
-
- <programlisting>
-sql_create_5(stock, 1, 0,
+ <para>The <parameter>COMPCOUNT</parameter> and
+ <parameter>SETCOUNT</parameter> arguments are described
+ in the next section.</para>
+ </sect2>
+
+
+ <sect2>
+ <title>SSQLS Comparison and Initialization</title>
+
+ <para><varname>sql_create_</varname><emphasis>x</emphasis>
+ adds member functions and operators to each
+ SSQLS that allow you to compare one SSQLS
+ instance to another. These functions compare
+ the first <parameter>COMPCOUNT</parameter>
+ fields in the structure. In the example above,
+ <parameter>COMPCOUNT</parameter> is 1, so only
+ the <varname>item</varname> field will be checked
+ when comparing two <classname>stock</classname>
+ structures.</para>
+
+ <para>This feature works best when your table's "key"
+ fields are the first ones in the table schema and
+ you set <parameter>COMPCOUNT</parameter> equal to the
+ number of key fields. That way, a check for equality
+ between two SSQLS structures in your C++ code will give
+ the same results as a check for equality in SQL.</para>
+
+ <para><parameter>COMPCOUNT</parameter> must
+ be at least 1. The current implementation of
+ <varname>sql_create_</varname><emphasis>x</emphasis>
+ cannot create an SSQLS without comparison member
+ functions.</para>
+
+ <para>Because our <classname>stock</classname>
+ structure is less-than-comparable, you can use it
+ in STL algorithms and containers that require this,
+ such as STL's associative containers:</para>
+
+ <programlisting>
+std::set<stock> result;
+query.storein(result);
+cout << result.lower_bound(stock("Hamburger"))->item <<
endl;</programlisting>
+
+ <para>This will print the first item in the result
+ set that begins with "Hamburger".</para>
+
+ <para>The third parameter to
+ <varname>sql_create_</varname><emphasis>x</emphasis>
+ is <parameter>SETCOUNT</parameter>. If this is
+ nonzero, it adds an initialization constructor and
+ a <function>set()</function> member function taking
+ the given number of arguments, for setting the first
+ <emphasis>N</emphasis> fields of the structure. For
+ example, you could change the above example like
+ so:</para>
+
+ <programlisting>
+sql_create_5(stock, 1, 2,
string, item,
int, num,
double, weight,
double, price,
- mysqlpp::Date, date)</programlisting>
-
- <para>Here we are saying that the 'item' field is a kind
- of key field: it is always unique between any two 'stock'
- items, so if two stock records have equal item values,
- they are the same stock item.</para>
-
- <para>That change adds the following members to the
- SSQLS:</para>
-
- <programlisting>
-struct stock {
- ...
- stock(const std::string &p1);
- set(const std::string &p1);
- bool operator ==(const stock &other) const;
- bool operator !=(const stock &other) const;
- bool operator >(const stock &other) const;
- bool operator <(const stock &other) const;
- bool operator >=(const stock &other) const;
- bool operator <=(const stock &other) const;
- int cmp(const stock &other) const;
- int compare(const stock &other) const;
-}
-
-int compare(const stock &x, const stock &y);</programlisting>
-
- <para>The global
- <computeroutput>compare()</computeroutput>
- function compares x to y and returns <0 if
- x < y, 0 if x = y, and >0 if x > y.
- <computeroutput>stock::cmp()</computeroutput> and
- <computeroutput>stock::compare()</computeroutput>
- are the same thing as <computeroutput>compare(*this,
- other)</computeroutput>.</para>
-
- <para>The additional constructor initializes the key
- fields of the structure and leaves the other member
- variables undefined. This is useful for creating temporary
- objects to use for comparisons like <computeroutput>x
- <= stock("Hotdog")</computeroutput>.</para>
-
- <para>Because stock is now less-than-comparable you
- can store the query results in an STL associative
- container:</para>
-
- <programlisting>
-std::set<stock> result;
-query.storein(result);</programlisting>
-
- <para>And you can now use it like any other set:</para>
-
- <programlisting>
-cout << result.lower_bound(stock("Hamburger"))->item <<
endl;</programlisting>
-
- <para>This will return the first item that begins with
- "Hamburger".</para>
-
- <para>You can also use it will any STL algorithm that
- require the values to be less-than-comparable.</para>
- </sect2>
-
-
- <sect2>
- <title>sql_create with Additional Initializers</title>
-
- <para>If third parameter for this macro (INITPARMS) is
- nonzero, the SSQLS will have two additional members
- functions that make it easier to initialize the
- structure's data members. For example:</para>
-
- <programlisting>
-sql_create_5(stock, 1, 5,
- string, item,
- int, num,
- double, weight,
- double, price,
- mysqlpp::Date, date)</programlisting>
-
- <para>will add these functions to the structure relative to
- that in the previous example:</para>
-
- <programlisting>
-struct stock {
- ...
- stock(const string&, const int&, const double&,
- const double&, const mysqlpp::Date&);
- void set(const string&, const int&, const double&,
- const double&, const mysqlpp::Date&);
-}</programlisting>
-
- <para>There is one trick with this: because each SSQLS
- has at least one other constructor besides the one
- defined by this feature, not every logical value for
- INITPARMS results in working code. A simple example is
- setting KEYS and INITPARMS to the same value: you get
- two identical constructor definitions, so the compiler
- refuses to compile the code. If you are getting compiler
- errors having to do with duplicate definitions, try
- changing this value to zero.</para>
- </sect2>
-
-
- <sect2>
- <title>An Important Limitation of sql_create</title>
-
- <para>The features described in the two previous sections
- work together nicely most of the time. However, if you try
- to use the same value for the second and third parameters to
- <computeroutput>sql_create_N</computeroutput>, your
- program will fail to compile.</para>
-
- <para>Why is this?</para>
+ mysqlpp::Date, date)
- <para>The second parameter sets up SSQLS comparisons,
- one aspect of which defines a constructor taking just
- the table's key fields. The third parameter sets up
- an initialization constructor, taking as many fields
- as you request. When these two values are equal,
- you get two identical constructor definitions,
- which is illegal in C++.</para>
-
- <para>The solution is to use 0 for the third
- parameter, indicating that you do not need
- a separate full-initialization constructor.
+stock foo("Hotdog", 52);</programlisting>
+
+ <para>In addition to this 2-parameter constructor, this
+ version of the <classname>stock</classname> SSQLS will
+ have a similar 2-parameter <function>set()</function>
+ member function.</para>
+
+ <para>The <parameter>COMPCOUNT</parameter> and
+ <parameter>SETCOUNT</parameter> values cannot
+ be equal. If they are, the macro will generate
+ two initialization constructors with identical
+ parameter lists, which is illegal in C++. Why
+ does this happen? It's often convenient to be
+ able to say something like <computeroutput>x
+ == stock("Hotdog")</computeroutput>. This
+ requires that there be a constructor taking
+ <parameter>COMPCOUNT</parameter> arguments to create
+ the temporary <classname>stock</classname> instance
+ used in the comparison. It is easy to work around this
+ limitation. Using our <classname>stock</classname>
+ example structure, if you wanted comparisons
+ to consider all 5 fields and also be able to
+ initialize all 5 fields at once, you would pass
+ 5 for <parameter>COMPCOUNT</parameter> and 0 for
+ <parameter>SETCOUNT</parameter>. You would still
+ get a 5-parameter initialization constructor and a
+ 5-parameter <function>set()</function> function.</para>
+ </sect2>
+
+
+ <sect2>
+ <title>Retrieving a Table Subset</title>
+
+ <para>It's not necessary to retrieve an entire table
+ row using SSQLS, as long as the fields you want are
+ grouped together at the start of the table schema.
<filename>examples/custom6.cpp</filename> illustrates
this:</para>
@@ -1482,16 +1437,17 @@
parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude"/>
</programlisting>
- <para>This example shows one other thing, which
- is how to retrieve a subset of a table using
- SSQLS. Because we wanted only one column from the
- table, we had to pass 0 for the third parameter to
- <computeroutput>sql_create_N</computeroutput> to get
- the code to compile.</para>
-
<para>(See the simple1 example in the <xref
linkend="tutorial"/> for another way to accomplish
the same thing.)</para>
+
+ <para>Realize that the second and third parameters
+ to <varname>sql_create_1</varname> can't be anything
+ other than 1 and 0, respectively. As discussed above,
+ the second parameter must be at least 1, but since
+ there is only one field in the structure, it cannot
+ be higher than 1. Since the third parameter cannot
+ be equal to the second, only 0 works there.</para>
</sect2>
_______________________________________________
Mysqlpp-commits mailing list
[email protected]
https://mail.gna.org/listinfo/mysqlpp-commits
