Skip to content

Commit 96a618a

Browse files
K-balloK-ballo
committed
Extended README.md with basic usage and examples
Signed-off-by: K-ballo <k@fusionfenix.com>
1 parent 4fa09f7 commit 96a618a

File tree

5 files changed

+239
-60
lines changed

5 files changed

+239
-60
lines changed

‎.gitignore

+4-1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@
1212
*.a
1313

1414
# Visual Studio files
15+
*.opensdf
1516
*.sdf
1617
*.suo
17-
*.user
18+
*.user
19+
/libs/sqlite/vs/Debug
20+
/libs/sqlite/vs/ipch

‎LICENSE_1_0.txt

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Boost Software License - Version 1.0 - August 17th, 2003
2+
3+
Permission is hereby granted, free of charge, to any person or organization
4+
obtaining a copy of the software and accompanying documentation covered by
5+
this license (the "Software") to use, reproduce, display, distribute,
6+
execute, and transmit the Software, and to prepare derivative works of the
7+
Software, and to permit third-parties to whom the Software is furnished to
8+
do so, all subject to the following:
9+
10+
The copyright notices in the Software and this entire statement, including
11+
the above license grant, this restriction and the following disclaimer,
12+
must be included in all copies of the Software, in whole or in part, and
13+
all derivative works of the Software, unless such copies or derivative
14+
works are solely in the form of machine-executable object code generated by
15+
a source language processor.
16+
17+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19+
FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
20+
SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
21+
FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
22+
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23+
DEALINGS IN THE SOFTWARE.

‎README.md

+146-5
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,158 @@
22
==============
33

44
`Eggs.SQLite` is a thin wrapper over [`SQLite`][sqlite], written following
5-
_Modern **C++**_ style, and makes extensive use of the _C++ Standard Library_
5+
_Modern **C++**_ style and making extensive use of the _C++ Standard Library_
66
as well as the [_Boost C++ Libraries_][boost].
77

88
The library is in its early development stages, and currently provides no
99
examples, tests nor documentation. Its use in a production environment is not
1010
recommended at the time.
1111

12-
> Copyright Agustín Bergé, Fusion Fenix 2012
12+
[sqlite]: http://sqlite.org/ "SQLite Home Page"
13+
[boost]: http://boost.org/ "Boost C++ Libraries"
14+
15+
# Basic usage #
16+
17+
## Main components ##
18+
19+
The main components in the library are the `database` that handles the
20+
connection to a `SQLite` database, and the `statement`s that handles the
21+
execution of `SQL` statements.
22+
23+
#include <eggs/sqlite/sqlite.hpp>
24+
namespace sqlite = eggs::sqlite;
25+
26+
...
27+
28+
sqlite::database books_db( "books.db" );
29+
sqlite::istatement books_by_author(
30+
books_db
31+
, "SELECT title, year FROM books "
32+
"WHERE author=:author "
33+
"ORDER BY year ASC"
34+
);
35+
36+
Statements are loosely based on standard streams; an `istatement` reads back
37+
the results of a `SELECT` statements, and a `ostatement` writes the fields of
38+
an `INSERT` or `UPDATE` statement.
39+
40+
## Working with data ##
41+
42+
#### core access ####
43+
44+
Input and output statements respectively have a `get` and `put` member
45+
function providing core access to the statement data. The most basic usage
46+
includes stepping through a statement (using the member function `step`) and
47+
retrieving the data using `get`. _Example:_
48+
49+
books_by_author["author"] = "Bjarne Stroustrup";
50+
{
51+
books_by_author.step();
52+
std::cout
53+
<< "title: " << books_by_author.get< std::string >( 0 ) << ", "
54+
<< "year: " << books_by_author.get< int >( 1 )
55+
;
56+
}
57+
books_by_author.reset();
58+
59+
#### row objects ####
60+
61+
Statements only hold valid data for the row they are pointing to. Once a
62+
statement is stepped, previous data becames inaccessible. In particular, for
63+
columns of type _text_ and _blob_ their buffers became invalidated. The `row`
64+
object provides a way to extract all data from a statement, data that will not
65+
be invalidate as the statement is stepped. Otherwise `row`s behave exactly
66+
like `statement`s. _Example:_
67+
68+
books_by_author["author"] = "Bjarne Stroustrup";
69+
{
70+
sqlite::row row_results;
71+
72+
books_by_author >> row_results;
73+
std::cout
74+
<< "title: " << row_results.get< std::string >( 0 ) << ", "
75+
<< "year: " << row_results.get< int >( 1 )
76+
;
77+
}
78+
books_by_author.reset();
79+
80+
81+
#### _Boost.Fusion_ sequences ####
82+
83+
The indended use of the library is for most data to be accessed using _Fusion_
84+
or _Fusion_ adapted sequences. These sequences hold a number of elements of
85+
arbitrary type, and provide reflection capabilities to each element's index and
86+
type which allows the library to operate with them requesting no additional
87+
information. _Example:_
88+
89+
books_by_author["author"] = "Bjarne Stroustrup";
90+
{
91+
std::pair< std::string, int > pair_results;
92+
93+
books_by_author >> pair_results;
94+
std::cout
95+
<< "title: " << pair_results.first << ", "
96+
<< "year: " << pair_results.second
97+
;
98+
99+
std::string title;
100+
int year;
101+
102+
books_by_author >> boost::tie( title, year );
103+
std::cout
104+
<< "title: " << title << ", "
105+
<< "year: " << year
106+
;
107+
}
108+
books_by_author.reset();
109+
110+
## Iterators ##
111+
112+
Iterators over `statement`s are provided in the same fashion as standard
113+
stream objects. These iterators, named `istatement_iterator` and
114+
`ostatement_iterator`, allow the interoperation with standard containers,
115+
algorithms, and even third party code. For instance, combining a `std::vector`
116+
with a `sqlite::row` (or a _Fusion_ sequence) gives what is sometimes referred
117+
to as a _result set_. _Example:_
118+
119+
std::vector< sqlite::row > result_set;
120+
result_set.assign(
121+
sqlite::istatement_iterator< sqlite::row >( books_by_author )
122+
, sqlite::istatement_iterator< sqlite::row >()
123+
);
124+
books_by_author.reset();
125+
126+
// do something with result_set
127+
128+
## Customization points ##
129+
130+
The library provides customization points at three different levels:
131+
132+
#### raw_traits ####
133+
134+
These traits handle _raw_ access to the database. They operate directly with
135+
`SQLite` handles to read or write a single field. Specializations are provided
136+
for all fundamental `SQLite` datatypes; extending these traits should only be
137+
needed when working with `SQLite` extensions that provide a new datatype.
138+
139+
#### conversion_traits ####
140+
141+
These traits handle the conversion between a given type and the _raw_ type that
142+
will be used with `SQLite`. Specializations are provided for all fundamental
143+
integral types (mapped to `int32_t` or `int64_t`), floating point types (mapped to
144+
`double`) and string types (mapped to `char const*`). More specializations of
145+
fundamental and standard types will be added in the future.
146+
147+
#### row extraction/insertion ####
148+
149+
The extraction or insertion of an entire row can be customized by overloading
150+
functions `void extract( istatement& stmt, T& row )` and
151+
`void insert( ostatement& stmt, T const& row )`, which are found via _ADL_.
152+
Both `row` and _Fusion_ sequences access data by providing these overloads.
153+
154+
---
155+
156+
> Copyright _Agustín Bergé_, _Fusion Fenix_ 2012
13157
>
14158
> Distributed under the Boost Software License, Version 1.0. (See accompanying
15159
> file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
16-
17-
[sqlite]: http://sqlite.org/ "SQLite Home Page"
18-
[boost]: http://boost.org/ "Boost C++ Libraries"

‎libs/sqlite/src/main.cpp

+66-54
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,13 @@
1818
#include <boost/exception/diagnostic_information.hpp>
1919

2020
#include <boost/fusion/include/std_pair.hpp>
21-
#include <boost/fusion/include/tuple.hpp>
21+
#include <boost/fusion/include/boost_tuple.hpp>
2222
#include <boost/fusion/include/io.hpp>
2323

2424
#include <boost/range/iterator_range.hpp>
2525

26+
#include <boost/tuple/tuple.hpp>
27+
2628
inline boost::iterator_range< eggs::sqlite::istatement_iterator<> >
2729
query( eggs::sqlite::istatement& statement )
2830
{
@@ -84,76 +86,86 @@ inline std::size_t delete_( eggs::sqlite::ostatement& statement, Row const& row
8486

8587
int main( int argc, char* argv[] )
8688
{
87-
typedef
88-
boost::fusion::tuple< boost::uint32_t, std::string, std::string >
89-
note_type;
90-
9189
namespace sqlite = eggs::sqlite;
9290
try
9391
{
94-
sqlite::database test_db = sqlite::open( "markdown.db" );
95-
96-
//sqlite::statement test_stmt( test_db, "SELECT * FROM \"sqlite_master\" WHERE type='table'" );
97-
sqlite::istatement test_stmt( test_db, "SELECT \"_id\", \"Name\", \"Content\" FROM \"Notes\"" );
98-
sqlite::istatement other_test_stmt( test_db, "SELECT \"_id\", \"Name\", \"Content\" FROM \"Notes\" WHERE \"_id\" = $id" );
99-
sqlite::ostatement insert_stmt( test_db, "INSERT INTO \"Notes\" (\"Name\", \"Content\") VALUES (?, ?)" );
100-
101-
//auto params = sqlite3_bind_parameter_count( insert_stmt.native_handle() );
102-
//auto insert_columns = insert_stmt.columns();
92+
sqlite::database books_db( "books.db" );
93+
sqlite::istatement books_by_author(
94+
books_db
95+
, "SELECT title, year FROM books "
96+
"WHERE author=:author "
97+
"ORDER BY year ASC"
98+
);
10399

104-
sqlite::execute( test_db, "DELETE FROM \"Notes\" WHERE \"_id\" >= 20" );
100+
// Core access
101+
books_by_author["author"] = "Bjarne Stroustrup";
102+
{
103+
books_by_author.step();
104+
std::cout
105+
<< "title: " << books_by_author.get< std::string >( 0 ) << ", "
106+
<< "year: " << books_by_author.get< int >( 1 ) << '\n'
107+
;
108+
}
109+
books_by_author.reset();
105110

111+
// Row object
112+
books_by_author["author"] = "Bjarne Stroustrup";
106113
{
107-
std::map< std::string, std::string > new_notes;
108-
new_notes[ "First test" ] = "Some content...";
109-
new_notes[ "Second test" ] = "Some more content...";
110-
new_notes[ "Last test" ] = "Last content...";
111-
112-
std::copy(
113-
new_notes.cbegin(), new_notes.cend()
114-
, sqlite::ostatement_iterator< std::pair< std::string, std::string > >( insert_stmt )
115-
);
114+
sqlite::row row_results;
115+
116+
books_by_author >> row_results;
117+
std::cout
118+
<< "title: " << row_results.get< std::string >( 0 ) << ", "
119+
<< "year: " << row_results.get< int >( 1 ) << '\n'
120+
;
116121
}
122+
books_by_author.reset();
123+
124+
// Fusion sequences
125+
books_by_author["author"] = "Bjarne Stroustrup";
126+
{
127+
std::pair< std::string, int > pair_results;
117128

118-
//insert_stmt << std::make_pair( "New", "something..." );
119-
//insert_stmt.step();
129+
books_by_author >> pair_results;
130+
std::cout
131+
<< "title: " << pair_results.first << ", "
132+
<< "year: " << pair_results.second << '\n'
133+
;
120134

121-
int version = sqlite::get_pragma< sqlite::pragma::user_version >( test_db );
135+
std::string title;
136+
int year;
122137

123-
auto r = query< note_type >( test_stmt );
124-
std::vector< note_type > v( r.begin(), r.end() );
138+
books_by_author >> boost::tie( title, year );
139+
std::cout
140+
<< "title: " << title << ", "
141+
<< "year: " << year << '\n'
142+
;
143+
}
144+
books_by_author.reset();
125145

126-
for(
127-
sqlite::istatement_iterator< sqlite::istatement >
128-
iter( test_stmt )
129-
, end
130-
; iter != end
131-
; ++iter
132-
)
146+
// Result set
147+
books_by_author["author"] = "Bjarne Stroustrup";
133148
{
134-
std::cout
135-
<< '#' << iter->get< boost::uint32_t >( 0 ) << ' '
136-
<< iter->get< std::string >( 1 ) << ':' << '\n'
137-
<< iter->get< std::string >( 2 ).substr( 0, 30 ) << "..."
138-
<< '\n' << std::endl;
149+
std::vector< sqlite::row > result_set;
150+
result_set.assign(
151+
sqlite::istatement_iterator< sqlite::row >( books_by_author )
152+
, sqlite::istatement_iterator< sqlite::row >()
153+
);
154+
155+
// do something with result_set
139156
}
157+
books_by_author.reset();
140158

141-
other_test_stmt[ "id" ] = 19;
142-
std::copy(
143-
sqlite::istatement_iterator< note_type >( other_test_stmt ), sqlite::istatement_iterator< note_type >()
144-
, std::ostream_iterator< note_type >( std::cout, "\n" )
145-
);
146159

147-
int breakpoint = 3;
148-
} catch( sqlite::sqlite_error const& e ) {
149-
std::cerr
150-
<< "something went wrong :$" "\n"
151-
<< boost::diagnostic_information( e ) << "\n"
152-
<< e.message() << std::endl
153-
;
160+
//} catch( sqlite::sqlite_error const& e ) {
161+
// std::cerr
162+
// << "something went wrong" "\n"
163+
// << boost::diagnostic_information( e ) << "\n"
164+
// << e.message() << std::endl
165+
// ;
154166
} catch( std::exception const& e ) {
155167
std::cerr
156-
<< "something went wrong :$" "\n"
168+
<< "something went wrong" "\n"
157169
<< boost::diagnostic_information( e ) << std::endl
158170
;
159171
} catch( ... ) {

‎libs/sqlite/vs/books.db

3 KB
Binary file not shown.

0 commit comments

Comments
 (0)