Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Comment: | Forward-ported all of the differences between MySQL++ 3.2.1 (the point where libtabula originally forked off) and the current trunk version, which includes changes made after the release of MySQL++ 3.2.4. |
---|---|
Timelines: | family | ancestors | trunk |
Files: | files | file ages | folders |
SHA1: |
6c22637ceb7e81f5958288d108060c68 |
User & Date: | tangent 2018-10-28 11:53:13 |
2018-10-28
| ||
11:53 | Forward-ported all of the differences between MySQL++ 3.2.1 (the point where libtabula originally forked off) and the current trunk version, which includes changes made after the release of MySQL++ 3.2.4. Leaf check-in: 6c22637ceb user: tangent tags: trunk | |
11:08 | Dropped throw-specs, that being one of the things we always wanted to do for "MySQL++ 4.0". This obviates the porting of the MAY_THROW() stuff from MySQL++ 3.2.x. check-in: bc21e10c05 user: tangent tags: trunk | |
Changes to doc/userman/Makefile.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 .. 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 .. 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 |
## ------------------------ ## Input files ## ------------------------ HTML_DIR=../html/userman BASENAME=userman DOCFILE=$(BASENAME).dbx PDFFILE=$(BASENAME).pdf FOFILE=$(BASENAME).fo COMMON_SS=common.xsl FO_SS=fo.xsl HTML_SS=html.xsl EX_TXT=cgi_jpeg.txt cpool.txt deadlock.txt fieldinf.txt for_each.txt \ load_jpeg.txt multiquery.txt resetdb.txt simple1.txt \ simple2.txt simple3.txt ssqls1.txt ssqls2.txt ssqls3.txt \ ................................................................................ ## ------------------------ ## Major output rules ## ------------------------ html: $(EX_TXT) $(HTML_DIR)/index.html pdf: $(PDFFILE) ## ------------------------ ## Standard Makefile targets ## ------------------------ # Notice that this is not the first target in the file, as is standard. ................................................................................ # PDF generation takes longer than HTML generation, so to keep the code- # test-debug-rebuild cycle short, we generate only the HTML manual by # default. You can explicitly say "make pdf" or "make all" when you're # sure the DocBook file's contents are correct. all: html pdf clean: @rm -f tags *.fo $(HTML_DIR)/*.html *.log *.out *.pdf $(EX_TXT) ## ------------------------ ## How to make output files ## ------------------------ $(PDFFILE): *.dbx *.in $(FO_SS) $(COMMON_SS) xsltproc --xinclude $(FO_SS) $(DOCFILE) > $(FOFILE) ./fo2pdf $(FOFILE) $(PDFFILE) mkdir -p ../pdf && cp $(PDFFILE) ../pdf $(HTML_DIR)/index.html: *.dbx *.in *.mod *.txt *.xsl @xmllint --xinclude --nonet --postvalid --noent --noout $(DOCFILE) xsltproc --xinclude --nonet -o $(HTML_DIR)/ $(HTML_SS) $(DOCFILE) ## ------------------------ |
| | | > < |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 .. 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 .. 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 |
## ------------------------ ## Input files ## ------------------------ HTML_DIR=../html/userman BASENAME=userman DOCFILE=$(BASENAME).dbx PDFFILE=../pdf/$(BASENAME).pdf FOFILE=$(BASENAME).fo COMMON_SS=common.xsl FO_SS=fo.xsl HTML_SS=html.xsl EX_TXT=cgi_jpeg.txt cpool.txt deadlock.txt fieldinf.txt for_each.txt \ load_jpeg.txt multiquery.txt resetdb.txt simple1.txt \ simple2.txt simple3.txt ssqls1.txt ssqls2.txt ssqls3.txt \ ................................................................................ ## ------------------------ ## Major output rules ## ------------------------ html: $(EX_TXT) $(HTML_DIR)/index.html pdf: $(EX_TXT) $(PDFFILE) ## ------------------------ ## Standard Makefile targets ## ------------------------ # Notice that this is not the first target in the file, as is standard. ................................................................................ # PDF generation takes longer than HTML generation, so to keep the code- # test-debug-rebuild cycle short, we generate only the HTML manual by # default. You can explicitly say "make pdf" or "make all" when you're # sure the DocBook file's contents are correct. all: html pdf clean: @rm -f tags *.fo $(HTML_DIR)/*.html *.log *.out *.pdf $(EX_TXT) $(PDFFILE) ## ------------------------ ## How to make output files ## ------------------------ $(PDFFILE): *.dbx *.in $(FO_SS) $(COMMON_SS) xsltproc --xinclude $(FO_SS) $(DOCFILE) > $(FOFILE) mkdir -p ../pdf ./fo2pdf $(FOFILE) $(PDFFILE) $(HTML_DIR)/index.html: *.dbx *.in *.mod *.txt *.xsl @xmllint --xinclude --nonet --postvalid --noent --noout $(DOCFILE) xsltproc --xinclude --nonet -o $(HTML_DIR)/ $(HTML_SS) $(DOCFILE) ## ------------------------ |
Changes to doc/userman/breakages.dbx.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
..
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
|
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="breakages"> <title>Incompatible Library Changes</title> <para>This chapter documents those library changes since the v4.0.0 fork with MySQL++ that break end-user programs. You can dig this stuff out of the ChangeLog, but the ChangeLog focuses more on explaining and justifying the facets of each change, while this section focuses on how to migrate your code between these library versions.</para> <para>Since pure additions do not break programs, those changes are still documented only in the ChangeLog.</para> <sect2 id="api-changes"> <title>API Changes</title> <para>This section documents files, functions, methods and classes that were removed or changed in an incompatible way. If your ................................................................................ program uses the changed item, you will have to change something in your program to get it to compile after upgrading to each of these versions.</para> <sect3 id="api-4.0.0"> <title>v4.0.0</title> <subtitle>Or, differences between MySQL++ 3.2.1 and libtabula</subtitle> <para>Renamed library files from <filename>*mysqlpp*</filename> to <filename>*tabula*</filename>. On Unixy platforms, this means the actual library file will be called something like <filename>libtabula.*</filename>, which is where the new name comes from. (I didn’t want to call it just |
|
|
|
|
|
|
|
|
|
|
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
..
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
|
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="breakages"> <title>Incompatible Library Changes</title> <para>This chapter documents those library changes since the v4.0.0 fork with MySQL++ that break end-user programs. You can dig this stuff out of the <filename>ChangeLog.md</filename> file, but the change log focuses more on explaining and justifying the facets of each change, while this section focuses on how to migrate your code between these library versions.</para> <para>Since pure additions do not break programs, those changes are still documented only in the change log.</para> <sect2 id="api-changes"> <title>API Changes</title> <para>This section documents files, functions, methods and classes that were removed or changed in an incompatible way. If your ................................................................................ program uses the changed item, you will have to change something in your program to get it to compile after upgrading to each of these versions.</para> <sect3 id="api-4.0.0"> <title>v4.0.0</title> <subtitle>Or, differences between MySQL++ 3.2.4 and libtabula</subtitle> <para>Renamed library files from <filename>*mysqlpp*</filename> to <filename>*tabula*</filename>. On Unixy platforms, this means the actual library file will be called something like <filename>libtabula.*</filename>, which is where the new name comes from. (I didn’t want to call it just |
Changes to doc/userman/configuration.dbx.
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="configuration"> <title>Configuring libtabula</title> <para>The default configuration of libtabula is suitable for most purposes, but there are a few things you can change to make it meet special needs.</para> |
| | |
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="configuration"> <title>Configuring libtabula</title> <para>The default configuration of libtabula is suitable for most purposes, but there are a few things you can change to make it meet special needs.</para> |
Changes to doc/userman/fo2pdf.
1 2 3 4 5 6 7 8 9 10 |
#!/bin/sh
AHCMD=/usr/XSLFormatterV42/run.sh
FOPCMD=`which /usr/local/fop/fop /usr/bin/fop | head -1 2> /dev/null`
XEPCMD=/usr/local/xep/xep
FOFILE=$1
PDFFILE=$2
if [ -n "$FOFILE" -a -r "$FOFILE" -a -n "$PDFFILE" ]
then
if [ -x "$XEPCMD" ]
|
| | |
1 2 3 4 5 6 7 8 9 10 |
#!/bin/bash AHCMD=/usr/XSLFormatterV42/run.sh FOPCMD=$(type -p fop) XEPCMD=/usr/local/xep/xep FOFILE=$1 PDFFILE=$2 if [ -n "$FOFILE" -a -r "$FOFILE" -a -n "$PDFFILE" ] then if [ -x "$XEPCMD" ] |
Changes to doc/userman/incorporating.dbx.
1
2
3
4
5
6
7
8
9
10
...
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="incorporating"> <title>Using libtabula in Your Own Project</title> <para>Up to now, this manual has only discussed libtabula in conjunction with the example programs that come with the library. This chapter covers the steps you need to take to ................................................................................ <filename>Makefiles</filename> you have seen collect both types of flags in a single variable. That can work if the variable is used in the right place in the link command. However, this particular <filename>Makefile</filename> is made with GNU make in mind, and uses its standard rules implicitly. Those rules are designed to use these two variables separately like this. If you were writing your own compilation rules, you could write them in such a way that you didn’t have to do this.</para> <para>Beyond that, we have a pretty vanilla <filename>Makefile</filename>, thanks in large part to the fact that the default <filename>make</filename> rules are fine for such a simple program.</para> </sect2> |
|
|
|
|
1
2
3
4
5
6
7
8
9
10
...
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="incorporating"> <title>Using libtabula in Your Own Project</title> <para>Up to now, this manual has only discussed libtabula in conjunction with the example programs that come with the library. This chapter covers the steps you need to take to ................................................................................ <filename>Makefiles</filename> you have seen collect both types of flags in a single variable. That can work if the variable is used in the right place in the link command. However, this particular <filename>Makefile</filename> is made with GNU make in mind, and uses its standard rules implicitly. Those rules are designed to use these two variables separately like this. If you were writing your own compilation rules, you could write them in such a way that you didn’t have to do this.</para> <para>Beyond that, we have a pretty vanilla <filename>Makefile</filename>, thanks in large part to the fact that the default <filename>make</filename> rules are fine for such a simple program.</para> </sect2> |
Changes to doc/userman/intro.dbx.
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="intro"> <title>Introduction</title> <para>libtabula is a powerful C++ wrapper for multiple C database access libraries. The initial version supports MySQL, MariaDB, and SQLite. Its purpose is to make working with SQL queries as easy as |
| | |
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="intro"> <title>Introduction</title> <para>libtabula is a powerful C++ wrapper for multiple C database access libraries. The initial version supports MySQL, MariaDB, and SQLite. Its purpose is to make working with SQL queries as easy as |
Changes to doc/userman/licenses.dbx.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="licenses"> <title>Licensing</title> <para>The primary copyright holders on libtabula and its documentation are Kevin Atkinson (© 1998), MySQL AB (© 1999 through 2001) and Educational Technology Resources, Inc. (© 2004 through the date of this writing). There are other contributors, who also retain copyrights on their additions; see the ChangeLog file in the distribution tarball for details. Contributions made prior to May 2014 were done to MySQL++, the predecessor to this library.</para> <para>The libtabula library and its Reference Manual are released under the GNU Lesser General Public License (LGPL), reproduced below.</para> <para>The libtabula User Manual — excepting some example code from the library reproduced within it — is offered under a license closely based on the Linux Documentation Project License (LDPL) v2.0, |
| | | | | | | > | | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="licenses"> <title>Licensing</title> <para>The primary copyright holders on libtabula and its documentation are Kevin Atkinson (© 1998), MySQL AB (© 1999 through 2001) and Educational Technology Resources, Inc. (© 2004 through the date of this writing). There are other contributors, who also retain copyrights on their additions; see the <filename>ChangeLog.md</filename> file in the distribution tarball for details. Contributions made prior to May 2014 were done to MySQL++, the predecessor to this library.</para> <para>The libtabula library and its Reference Manual are released under the GNU Lesser General Public License (LGPL), reproduced below.</para> <para>The libtabula User Manual — excepting some example code from the library reproduced within it — is offered under a license closely based on the Linux Documentation Project License (LDPL) v2.0, |
Changes to doc/userman/overview.dbx.
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="overview"> <title>Overview</title> <para>libtabula has a lot of complexity and power to cope with the variety of DBMSes and uses for them, but at bottom it doesn’t work all that differently than other database access APIs. The |
| | |
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="overview"> <title>Overview</title> <para>libtabula has a lot of complexity and power to cope with the variety of DBMSes and uses for them, but at bottom it doesn’t work all that differently than other database access APIs. The |
Changes to doc/userman/section-template.dbx.
1 2 3 4 5 6 7 8 9 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="SOMETHING_UNIQUE"> <title>SECTION TITLE</title> <para>FIRST PARAGRAPH</para> </sect1> |
| | |
1 2 3 4 5 6 7 8 9 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="SOMETHING_UNIQUE"> <title>SECTION TITLE</title> <para>FIRST PARAGRAPH</para> </sect1> |
Changes to doc/userman/ssqls.dbx.
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="ssqls"> <title>Specialized SQL Structures</title> <para>The Specialized SQL Structure (SSQLS) feature lets you easily define C++ structures that match the form of your SQL tables. At the most superficial level, an SSQLS has a member variable corresponding |
| | |
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="ssqls"> <title>Specialized SQL Structures</title> <para>The Specialized SQL Structure (SSQLS) feature lets you easily define C++ structures that match the form of your SQL tables. At the most superficial level, an SSQLS has a member variable corresponding |
Changes to doc/userman/threads.dbx.
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="threads"> <title>Using libtabula in a Multithreaded Program</title> <para>libtabula is not “thread safe” in any meaningful sense. libtabula contains very little code that actively prevents trouble with threads, and all of it is |
| | |
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="threads"> <title>Using libtabula in a Multithreaded Program</title> <para>libtabula is not “thread safe” in any meaningful sense. libtabula contains very little code that actively prevents trouble with threads, and all of it is |
Changes to doc/userman/tquery.dbx.
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="tquery" xreflabel="Template Queries"> <title>Template Queries</title> <para>Another powerful feature of libtabula is being able to set up template queries. These are kind of like C’s <function>printf()</function> facility: you give libtabula a string |
| | |
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="tquery" xreflabel="Template Queries"> <title>Template Queries</title> <para>Another powerful feature of libtabula is being able to set up template queries. These are kind of like C’s <function>printf()</function> facility: you give libtabula a string |
Changes to doc/userman/tutorial.dbx.
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="tutorial" xreflabel="Tutorial"> <title>Tutorial</title> <para>The <link linkend="overview">previous chapter</link> introduced the major top-level mechanisms in libtabula. Now we’ll dig down a little deeper and get into real examples. We start off |
| | |
1 2 3 4 5 6 7 8 9 10 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="tutorial" xreflabel="Tutorial"> <title>Tutorial</title> <para>The <link linkend="overview">previous chapter</link> introduced the major top-level mechanisms in libtabula. Now we’ll dig down a little deeper and get into real examples. We start off |
Changes to doc/userman/unicode.dbx.
1 2 3 4 5 6 7 8 9 10 .. 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 .. 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <sect1 id="unicode" xreflabel="Using Unicode with libtabula"> <title>Using Unicode with libtabula</title> <sect2 id="unicode-history"> <title>A Short History of Unicode</title> <subtitle>...with a focus on relevance to libtabula</subtitle> ................................................................................ common 7-bit ASCII subset. Either people used approximations like a plain “c” instead of the French “ç”, or they invented things like HTML entities (“&ccedil;” in this case) to encode these additional characters using only 7-bit ASCII.</para> <para>Unicode solves this problem. It encodes every character used for writing in the world, using up to 4 bytes per character. The subset covering the most economically valuable cases takes two bytes per character, so many Unicode-aware programs only support this subset, storing characters as 2-byte values, rather than use 4-byte characters so as to cover all possible cases, however rare. This subset of Unicode is called the Basic Multilingual Plane, or BMP.</para> <para>Unfortunately, Unicode was invented about two decades too late for Unix and C. Those decades of legacy created an immense inertia preventing a widespread move away from 8-bit characters. MySQL and C++ come out of these older traditions, and so they share the same practical limitations. libtabula currently doesn’t have any code in it for Unicode conversions; it just passes data along unchanged from the underlying DBMS C API, so you still need to be aware of these underlying issues.</para> <para>During the development of the <ulink url="http://en.wikipedia.org/wiki/Plan_9_from_Bell_Labs">Plan 9</ulink> operating system (a kind of successor to Unix) Ken Thompson <ulink url="http://www.cl.cam.ac.uk/~mgk25/ucs/utf-8-history.txt">invented</ulink> the <ulink url="http://en.wikipedia.org/wiki/UTF-8">UTF-8 encoding</ulink>. UTF-8 is a superset of 7-bit ASCII and is compatible with C strings, since it doesn’t use 0 bytes anywhere as multi-byte Unicode encodings do. As a result, many programs that deal in text will cope with UTF-8 data even though they have no explicit support for UTF-8. (Follow the last link above to see how the design of UTF-8 allows this.) Thus, when explicit support for Unicode was added in MySQL v4.1, they chose to make UTF-8 the native encoding, to preserve backward compatibility with programs that had no Unicode support.</para> </sect2> <sect2 id="unicode-unix"> <title>Unicode on Unixy Systems</title> <para>Linux and Unix have system-wide UTF-8 support these days. If ................................................................................ <function>iconv()</function> should suffice.</para> </sect2> <sect2 id="unicode-windows"> <title>Unicode on Windows</title> <para>Each Windows API function that takes a string actually comes in two versions. One version supports only 1-byte “ANSI” characters<footnote><para>A superset of ASCII</para></footnote> so they end in 'A'. The first Unicode-aware versions of Windows supported a 2-byte subset of Unicode called <ulink url="http://en.wikipedia.org/wiki/UCS-2">UCS-2</ulink>. Since Windows XP, Windows now uses the <ulink url="http://en.wikipedia.org/wiki/UTF-16">UTF-16</ulink> encoding natively instead; it also takes 2 bytes per character for typical Western texts, but unlike UCS-2, it can extend to up to 4 bytes per character to encode the rarer Unicode characters. Regardless of whether you use UTF-16 or UCS-2, these are often generically called “wide” characters, so the other set of Windows API functions end in 'W'. The <function><ulink url="http://msdn.microsoft.com/library/en-us/winui/winui/windowsuserinterface/windowing/dialogboxes/dialogboxreference/dialogboxfunctions/messagebox.asp">MessageBox</ulink>()</function> API, for instance, is actually a macro, not a real function. If you define the <symbol>UNICODE</symbol> macro when building your program, the <function>MessageBox()</function> macro evaluates to <function>MessageBoxW()</function>; otherwise, to <function>MessageBoxA()</function>.</para> <para>Most open source DBMSes these days use the UTF-8 Unicode encoding by preference but Windows uses UTF-16 instead. Because of that, you probably need to convert data when passing text between libtabula and the Windows API. Since there’s no point in trying for portability — no other OS I’m aware of natively uses UTF-16 — you might as well use |
| | | | > > | < < | < | | | | | < | > | | | | | < < > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | | | | | < < < | < < < < < | | | | | | |
1 2 3 4 5 6 7 8 9 10 .. 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 ... 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 |
<?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <sect1 id="unicode" xreflabel="Using Unicode with libtabula"> <title>Using Unicode with libtabula</title> <sect2 id="unicode-history"> <title>A Short History of Unicode</title> <subtitle>...with a focus on relevance to libtabula</subtitle> ................................................................................ common 7-bit ASCII subset. Either people used approximations like a plain “c” instead of the French “ç”, or they invented things like HTML entities (“&ccedil;” in this case) to encode these additional characters using only 7-bit ASCII.</para> <para>Unicode solves this problem. It encodes every character used for writing in the world, using up to 4 bytes per character. Before emoji became popular, the subset covering the most economically valuable cases fit into the lower 65536 code points, so you could encode most texts using only two bytes per character. Many nominally Unicode-aware programs only support this subset, called the Basic Multilingual Plane, or BMP.</para> <para>Unfortunately, Unicode was invented about two decades too late for Unix and C. Those decades of legacy created an immense inertia preventing a widespread move away from 8-bit characters. MySQL and C++ come out of these older traditions, and so they share the same practical limitations. MySQL++ doesn’t have any code in it for Unicode conversions, and it likely never will; it just passes data along unchanged from the underlying MySQL C API, so you still need to be aware of these underlying issues.</para> <para>During the development of the <ulink url="http://en.wikipedia.org/wiki/Plan_9_from_Bell_Labs">Plan 9</ulink> operating system (a kind of successor to Unix) Ken Thompson <ulink url="http://www.cl.cam.ac.uk/~mgk25/ucs/utf-8-history.txt">invented</ulink> the <ulink url="http://en.wikipedia.org/wiki/UTF-8">UTF-8 encoding</ulink>. UTF-8 is a superset of 7-bit ASCII and is compatible with C strings, since it doesn’t use 0 bytes anywhere as multi-byte Unicode encodings do. As a result, many programs that deal in text will cope with UTF-8 data even though they have no explicit support for UTF-8. Follow the last link above to see how the design of UTF-8 allows this.</para> </sect2> <sect2 id="unicode-mysql"> <title>Unicode in MySQL</title> <para>Since MySQL comes out of the Unix world, and it predates the widespread use of UTF-8 in Unix, the early versinos of MySQL had no explicit support for Unicode. From the start, you could store raw UTF-8 strings, but it wouldn’t know how to do things like sort a column of UTF-8 strings.</para> <para>MySQL 4.1 added the first explicit support for Unicode. This version of MySQL supported only the BMP, meaning that if you told it to expect strings to be in UTF-8, it could only use up to 3 bytes per character.</para> <para>MySQL 5.5 was the first release to completely support Unicode. Because the BMP-only Unicode support had been in the wild for about 6 years by that point, and changing to the new character set requires a table rebuild, the new one was called “utf8mb4” rather than change the longstanding meaning of “utf8” in MySQL. This release also added a new alias for the old UTF-8 subset character set, “utf8mb3.”</para> <para>Finally, in MySQL 8.0, “utf8mb4” became the default character set. For backwards compatibility, “utf8” remains an alias for “utf8mb3.”</para> <para>We’ve defined the <varname>LIBTABULA_UTF8_CS</varname> and <varname>LIBTABULA_UTF8_COL</varname> macros which expand to “utf8mb4” and “utf8mb4_general_ci” when you build this library against MySQL 5.5 and newer and to “utf8” and “utf8_general_ci” otherwise. We use these macros in our <filename>resetdb</filename> example; you're welcome to use them in your code as well.</para> </sect2> <sect2 id="unicode-unix"> <title>Unicode on Unixy Systems</title> <para>Linux and Unix have system-wide UTF-8 support these days. If ................................................................................ <function>iconv()</function> should suffice.</para> </sect2> <sect2 id="unicode-windows"> <title>Unicode on Windows</title> <para>Each Windows API function that takes a string actually comes in two versions. One version supports only 1-byte “ANSI” characters (a superset of ASCII), so they end in 'A'. Since Windows XP, there is also a parallel set of APIs ending in 'W' (meaning “wide”) that expect <ulink url="http://en.wikipedia.org/wiki/UTF-16">UTF-16</ulink> encoded strings. The <function><ulink url="http://msdn.microsoft.com/library/en-us/winui/winui/windowsuserinterface/windowing/dialogboxes/dialogboxreference/dialogboxfunctions/messagebox.asp">MessageBox</ulink>()</function> API, for instance, is actually a macro, not a real function. If you define the <symbol>UNICODE</symbol> macro when building your program, the <function>MessageBox()</function> macro evaluates to <function>MessageBoxW()</function>; otherwise, to <function>MessageBoxA()</function>.</para> <para>Most open source DBMSes these days use the UTF-8 Unicode encoding by preference but Windows uses UTF-16 instead. Because of that, you probably need to convert data when passing text between libtabula and the Windows API. Since there’s no point in trying for portability — no other OS I’m aware of natively uses UTF-16 — you might as well use |
Changes to doc/userman/userman.dbx.in.
1
2
3
4
5
6
7
8
9
10
..
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
|
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.docbook.org/xml/4.2/docbookx.dtd" [ <!ENTITY % xinclude SYSTEM "xinclude.mod"> %xinclude; ]> <article> <articleinfo> <title>libtabula v@LIBTABULA_VERSION_MAJOR@.@LIBTABULA_VERSION_MINOR@.@LIBTABULA_VERSION_BUGFIX@ User Manual</title> ................................................................................ <author> <firstname>Warren</firstname> <surname>Young</surname> </author> </authorgroup> <copyright> <year>1998-2001, 2005-2014</year> <holder>Kevin Atkinson (original author)</holder> <holder>MySQL AB</holder> <holder>Educational Technology Resources</holder> </copyright> <pubdate><?dbtimestamp format="B d, Y"?></pubdate> </articleinfo> |
|
|
|
|
1
2
3
4
5
6
7
8
9
10
..
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
|
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.docbook.org/xml/4.4/docbookx.dtd" [ <!ENTITY % xinclude SYSTEM "xinclude.mod"> %xinclude; ]> <article> <articleinfo> <title>libtabula v@LIBTABULA_VERSION_MAJOR@.@LIBTABULA_VERSION_MINOR@.@LIBTABULA_VERSION_BUGFIX@ User Manual</title> ................................................................................ <author> <firstname>Warren</firstname> <surname>Young</surname> </author> </authorgroup> <copyright> <year>1998-2001, 2005-2018</year> <holder>Kevin Atkinson (original author)</holder> <holder>MySQL AB</holder> <holder>Educational Technology Resources</holder> </copyright> <pubdate><?dbtimestamp format="B d, Y"?></pubdate> </articleinfo> |
Changes to examples/resetdb.cpp.
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
...
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
resetdb.cpp - (Re)initializes the libtabula example database. You must run this at least once before running most of the other examples, and it is helpful sometimes to run it again, as some of the examples modify the table in this database. Copyright © 1998 by Kevin Atkinson, © 1999-2001 by MySQL AB, and © 2004-2009 by Educational Technology Resources, Inc. Others may also hold copyrights on code in this file. See the CREDITS file in the top directory of the distribution for details. This file is part of libtabula. libtabula is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published ................................................................................ "CREATE TABLE stock (" << " item CHAR(30) NOT NULL, " << " num BIGINT NOT NULL, " << " weight DOUBLE NOT NULL, " << " price DECIMAL(6,2) NULL, " << // NaN & inf. == NULL " sdate DATE NOT NULL, " << " description MEDIUMTEXT NULL) " << "ENGINE = InnoDB " << "CHARACTER SET utf8 COLLATE utf8_general_ci"; query.execute(); // Set up the template query to insert the data. The parse() // call tells the query object that this is a template and // not a literal query string. query << "insert into %6:table values " << "(%0q, %1q, %2, %3, %4q, %5q:desc)"; |
|
|
|
>
|
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
...
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
resetdb.cpp - (Re)initializes the libtabula example database. You must run this at least once before running most of the other examples, and it is helpful sometimes to run it again, as some of the examples modify the table in this database. Copyright © 1998 by Kevin Atkinson, © 1999-2001 by MySQL AB, and © 2004-2009, 2018 by Educational Technology Resources, Inc. Others may also hold copyrights on code in this file. See the CREDITS file in the top directory of the distribution for details. This file is part of libtabula. libtabula is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published ................................................................................ "CREATE TABLE stock (" << " item CHAR(30) NOT NULL, " << " num BIGINT NOT NULL, " << " weight DOUBLE NOT NULL, " << " price DECIMAL(6,2) NULL, " << // NaN & inf. == NULL " sdate DATE NOT NULL, " << " description MEDIUMTEXT NULL) " << "ENGINE = InnoDB" << " CHARACTER SET "LIBTABULA_UTF8_CS " COLLATE " LIBTABULA_UTF8_COL; query.execute(); // Set up the template query to insert the data. The parse() // call tells the query object that this is a template and // not a literal query string. query << "insert into %6:table values " << "(%0q, %1q, %2, %3, %4q, %5q:desc)"; |
Changes to libtabula.ebuild.
47 48 49 50 51 52 53 54 55 56 57 58 |
emake || die "unable to make"
}
src_install() {
emake DESTDIR="${D}" install || die
# install the docs and HTML pages
dodoc README* CREDITS ChangeLog HACKERS Wishlist
dodoc doc/*
cp -ra doc/html "${D}"/usr/share/doc/${PF}/html
prepalldocs
}
|
| |
47 48 49 50 51 52 53 54 55 56 57 58 |
emake || die "unable to make" } src_install() { emake DESTDIR="${D}" install || die # install the docs and HTML pages dodoc README* CREDITS.md ChangeLog.md HACKERS.md Wishlist.md dodoc doc/* cp -ra doc/html "${D}"/usr/share/doc/${PF}/html prepalldocs } |
Changes to src/common.h.
127
128
129
130
131
132
133
134
135
136
137
138
139
140
...
191
192
193
194
195
196
197
198
199
|
// C++11 added unique_ptr as a replacement for auto_ptr. We don't have
// the ABI problem above with this one, so we switch to it with the
// oldest release possible. As with the above ifdef, this one only
// currently works for g++ and clang++.
#if __cplusplus >= 201103L
# define UNIQUE_PTR(what) std::unique_ptr<what>
# define UNIQUE_PTR(what) std::auto_ptr<what>
#endif
namespace libtabula {
/// \brief Alias for 'true', to make code requesting exceptions more
/// readable.
................................................................................
// while actually working with C++. This is why we disobey the MySQL
// developer docs, which recommend including my_global.h before mysql.h.
#if defined(LIBTABULA_MYSQL_HEADERS_BURIED)
# include <mysql/mysql.h>
#else
# include <mysql.h>
#endif
#endif // !defined(LIBTABULA_COMMON_H)
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
...
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
// C++11 added unique_ptr as a replacement for auto_ptr. We don't have // the ABI problem above with this one, so we switch to it with the // oldest release possible. As with the above ifdef, this one only // currently works for g++ and clang++. #if __cplusplus >= 201103L # define UNIQUE_PTR(what) std::unique_ptr<what> #else # define UNIQUE_PTR(what) std::auto_ptr<what> #endif namespace libtabula { /// \brief Alias for 'true', to make code requesting exceptions more /// readable. ................................................................................ // while actually working with C++. This is why we disobey the MySQL // developer docs, which recommend including my_global.h before mysql.h. #if defined(LIBTABULA_MYSQL_HEADERS_BURIED) # include <mysql/mysql.h> #else # include <mysql.h> #endif // The Unicode chapter of the user manual justifies the following. #if MYSQL_VERSION_ID >= 50500 /// \brief Use this macro in CREATE TABLE strings to get the best /// available UTF-8 character set. /// /// MySQL++ is built against MySQL or MariaDB 5.5 or newer, so these /// macros are defined so that programs using them get the complete /// UTF-8 character set. # define LIBTABULA_UTF8_CS "utf8mb4" /// \brief Use this macro in CREATE TABLE strings to get a matching /// collation to the character set selected by LIBTABULA_UTF8_CS # define LIBTABULA_UTF8_COL "utf8mb4_general_ci" #else /// \brief Use this macro in CREATE TABLE strings to get the best /// available UTF-8 character set and correpsonding collation. /// /// MySQL++ is built against a version of MySQL or MariaDB older than /// 5.5, so we must use the legacy 3-byte-limited subset of UTF-8. # define LIBTABULA_UTF8_CS "utf8" /// \brief Use this macro in CREATE TABLE strings to get a matching /// collation to the character set selected by LIBTABULA_UTF8_CS # define LIBTABULA_UTF8_COL "utf8_general_ci" #endif #endif // !defined(LIBTABULA_COMMON_H) |
Changes to src/dbdriver.cpp.
1 2 3 4 5 6 7 8 9 10 11 12 .. 21 22 23 24 25 26 27 28 29 30 31 32 33 34 .. 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 |
/*********************************************************************** dbdriver.cpp - Implements the DBDriver class. Copyright © 2005-2009, 2014 by Educational Technology Resources, Inc. Others may also hold copyrights on code in this file. See the CREDITS.md file in the top directory of the distribution for details. This file is part of libtabula. libtabula is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or ................................................................................ License along with libtabula; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA ***********************************************************************/ #define LIBTABULA_NOT_HEADER #include "dbdriver.h" using namespace std; namespace libtabula { DBDriver::DBDriver(bool te) : OptionalExceptions(te), ................................................................................ // High-level option setting mechanism, called by Connection::set_option() // and by apply_pending_options(). Lower levels are in the leaf classes. bool DBDriver::set_option(Option* o) { // Ensure o gets destroyed if there is a fatal error or exception std::auto_ptr<Option> cleanup(o); option_error_ = o->set(this); if (option_error_ == Option::err_NONE) { // It was applied successfully, so save it until destruction of // the driver so we know what options have already been applied. applied_options_.push_back(o); cleanup.release(); |
| | > > | |
1 2 3 4 5 6 7 8 9 10 11 12 .. 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 .. 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 |
/*********************************************************************** dbdriver.cpp - Implements the DBDriver class. Copyright © 2005-2009, 2014, 2018 by Educational Technology Resources, Inc. Others may also hold copyrights on code in this file. See the CREDITS.md file in the top directory of the distribution for details. This file is part of libtabula. libtabula is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or ................................................................................ License along with libtabula; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA ***********************************************************************/ #define LIBTABULA_NOT_HEADER #include "dbdriver.h" #include "common.h" using namespace std; namespace libtabula { DBDriver::DBDriver(bool te) : OptionalExceptions(te), ................................................................................ // High-level option setting mechanism, called by Connection::set_option() // and by apply_pending_options(). Lower levels are in the leaf classes. bool DBDriver::set_option(Option* o) { // Ensure o gets destroyed if there is a fatal error or exception UNIQUE_PTR(Option) cleanup(o); option_error_ = o->set(this); if (option_error_ == Option::err_NONE) { // It was applied successfully, so save it until destruction of // the driver so we know what options have already been applied. applied_options_.push_back(o); cleanup.release(); |
Changes to src/mysql/driver.cpp.
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
...
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
|
// the option value, which is as it should be. int n = o; while (n && ((n & 1) == 0)) { n >>= 1; } if ((n == 1) && (o >= CLIENT_LONG_PASSWORD) && #if MYSQL_VERSION_ID > 40000 // highest flag value varies by version (o <= CLIENT_MULTI_RESULTS) #else (o <= CLIENT_TRANSACTIONS) #endif ) { // Option value seems sane, so go ahead and set/clear the flag ................................................................................ #endif } bool MySQLDriver::shutdown() { return mysql_shutdown(&mysql_ SHUTDOWN_ARG); } bool MySQLDriver::thread_aware() { #if defined(LIBTABULA_PLATFORM_WINDOWS) || defined(HAVE_PTHREAD) || defined(HAVE_SYNCH_H) |
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
>
|
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
...
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
|
// the option value, which is as it should be. int n = o; while (n && ((n & 1) == 0)) { n >>= 1; } if ((n == 1) && #ifdef CLIENT_LONG_PASSWORD (o >= CLIENT_LONG_PASSWORD) && #else (o >= CLIENT_MYSQL) && #endif #if MYSQL_VERSION_ID > 40000 // highest flag value varies by version (o <= CLIENT_MULTI_RESULTS) #else (o <= CLIENT_TRANSACTIONS) #endif ) { // Option value seems sane, so go ahead and set/clear the flag ................................................................................ #endif } bool MySQLDriver::shutdown() { #if (MYSQL_VERSION_ID >= 80000) // The C API function we were depending on is removed in 8.0.0. It // was replaced in 8.0.1, but they claim they're going to remove it // again later, so we prefer to behave as if it's gone for good as // of 8.0.0, so we've got a well-tested workaround before then. return connected() ? execute("SHUTDOWN", 8) : false; #elif ((MYSQL_VERSION_ID >= 40103) && (MYSQL_VERSION_ID <= 49999)) || (MYSQL_VERSION_ID >= 50001) // An argument was added to mysql_shutdown() in MySQL 4.1.3 and 5.0.1. return mysql_shutdown(&mysql_, SHUTDOWN_DEFAULT); #else // Prior versions had no argument return mysql_shutdown(&mysql_); #endif } bool MySQLDriver::thread_aware() { #if defined(LIBTABULA_PLATFORM_WINDOWS) || defined(HAVE_PTHREAD) || defined(HAVE_SYNCH_H) |
Changes to src/refcounted.h.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
/// \file refcounted.h /// \brief Declares the RefCountedPointer template /*********************************************************************** Copyright © 2007-2011 by Educational Technology Resources, Inc. and © 2007 by Jonathan Wakely. Others may also hold copyrights on code in this file. See the CREDITS.md file in the top directory of the distribution for details. This file is part of libtabula. libtabula is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. |
| | | | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
/// \file refcounted.h /// \brief Declares the RefCountedPointer template /*********************************************************************** Copyright © 2007-2011, 2018 by Educational Technology Resources, Inc. and © 2007 by Jonathan Wakely. Others may also hold copyrights on code in this file. See the CREDITS.md file in the top directory of the distribution for details. This file is part of libtabula. libtabula is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. |