diff options
| author | Robert Ryan <robert.ryan@mindspring.com> | 2020-05-09 20:30:31 +0300 |
|---|---|---|
| committer | Robert Ryan <robert.ryan@mindspring.com> | 2020-05-09 20:30:31 +0300 |
| commit | e302faa1af2793568becd399119bdbef4e1df2cf (patch) | |
| tree | cdb0f815e3fe09ac3d42fb553c9e153d59f95303 | |
| parent | 32d925e6fc7f890aa58a54be772a57c1fcdc856d (diff) | |
Replace duplicate/outdated index.html with redirect
| -rw-r--r-- | index.html | 304 |
1 files changed, 6 insertions, 298 deletions
@@ -1,305 +1,13 @@ <!DOCTYPE html> <html> - <head> - <meta charset='utf-8' /> - <meta http-equiv="X-UA-Compatible" content="chrome=1" /> - <meta name="description" content="Fmdb : A Cocoa / Objective-C wrapper around SQLite" /> - - <link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css"> - - <title>Fmdb</title> + <meta http-equiv="Refresh" content="0; url=https://ccgus.github.io/fmdb/html/index.html" /> + <script type="text/javascript"> + window.location.href = "https://ccgus.github.io/fmdb/html/index.html" + </script> + <title>Page Redirection</title> </head> - <body> - - <!-- HEADER --> - <div id="header_wrap" class="outer"> - <header class="inner"> - <a id="forkme_banner" href="https://github.com/ccgus/fmdb">Fork Me on GitHub</a> - - <h1 id="project_title">Fmdb</h1> - <h2 id="project_tagline">A Cocoa / Objective-C wrapper around SQLite</h2> - - <section id="downloads"> - <a class="zip_download_link" href="https://github.com/ccgus/fmdb/zipball/master">Download this project as a .zip file</a> - <a class="tar_download_link" href="https://github.com/ccgus/fmdb/tarball/master">Download this project as a tar.gz file</a> - </section> - </header> - </div> - - <!-- MAIN CONTENT --> - <div id="main_content_wrap" class="outer"> - <section id="main_content" class="inner"> - <h1>FMDB</h1> - -<p>This is an Objective-C wrapper around SQLite: <a href="http://sqlite.org/">http://sqlite.org/</a></p> - -<p>Also refer to the <a href="html/index.html">FMDB Class Reference</a> documentation.</p> - -<h2>The FMDB Mailing List:</h2> - -<p><a href="http://groups.google.com/group/fmdb">http://groups.google.com/group/fmdb</a></p> - -<h2>Read the SQLite FAQ:</h2> - -<p><a href="http://www.sqlite.org/faq.html">http://www.sqlite.org/faq.html</a></p> - -<p>Since FMDB is built on top of SQLite, you're going to want to read this page top to bottom at least once. And while you're there, make sure to bookmark the SQLite Documentation page: <a href="http://www.sqlite.org/docs.html">http://www.sqlite.org/docs.html</a></p> - -<h2>Automatic Reference Counting (ARC) or Manual Memory Management?</h2> - -<p>You can use either style in your Cocoa project. FMDB Will figure out which you are using at compile time and do the right thing.</p> - -<h2>Usage</h2> - -<p>There are three main classes in FMDB:</p> - -<ol> -<li> -<code>FMDatabase</code> - Represents a single SQLite database. Used for executing SQL statements.</li> -<li> -<code>FMResultSet</code> - Represents the results of executing a query on an <code>FMDatabase</code>.</li> -<li> -<code>FMDatabaseQueue</code> - If you're wanting to perform queries and updates on multiple threads, you'll want to use this class. It's described in the "Thread Safety" section below.</li> -</ol><h3>Database Creation</h3> - -<p>An <code>FMDatabase</code> is created with a path to a SQLite database file. This path can be one of these three:</p> - -<ol> -<li>A file system path. The file does not have to exist on disk. If it does not exist, it is created for you.</li> -<li>An empty string (<code>@""</code>). An empty database is created at a temporary location. This database is deleted with the <code>FMDatabase</code> connection is closed.</li> -<li> -<code>NULL</code>. An in-memory database is created. This database will be destroyed with the <code>FMDatabase</code> connection is closed.</li> -</ol><p>(For more information on temporary and in-memory databases, read the sqlite documentation on the subject: <a href="http://www.sqlite.org/inmemorydb.html">http://www.sqlite.org/inmemorydb.html</a>)</p> - -<pre><code>FMDatabase *db = [FMDatabase databaseWithPath:@"/tmp/tmp.db"]; -</code></pre> - -<h3>Opening</h3> - -<p>Before you can interact with the database, it must be opened. Opening fails if there are insufficient resources or permissions to open and/or create the database.</p> - -<pre><code>if (![db open]) { - [db release]; - return; -} -</code></pre> - -<h3>Executing Updates</h3> - -<p>Any sort of SQL statement which is not a <code>SELECT</code> statement qualifies as an update. This includes <code>CREATE</code>, <code>PRAGMA</code>, <code>UPDATE</code>, <code>INSERT</code>, <code>ALTER</code>, <code>COMMIT</code>, <code>BEGIN</code>, <code>DETACH</code>, <code>DELETE</code>, <code>DROP</code>, <code>END</code>, <code>EXPLAIN</code>, <code>VACUUM</code>, and <code>REPLACE</code> statements (plus many more). Basically, if your SQL statement does not begin with <code>SELECT</code>, it is an update statement.</p> - -<p>Executing updates returns a single value, a <code>BOOL</code>. A return value of <code>YES</code> means the update was successfully executed, and a return value of <code>NO</code> means that some error was encountered. If you use the <code>-[FMDatabase executeUpdate:error:withArgumentsInArray:orVAList:]</code> method to execute an update, you may supply an <code>NSError **</code> that will be filled in if execution fails. Otherwise you may invoke the <code>-lastErrorMessage</code> and <code>-lastErrorCode</code> methods to retrieve more information.</p> - -<h3>Executing Queries</h3> - -<p>A <code>SELECT</code> statement is a query and is executed via one of the <code>-executeQuery...</code> methods.</p> - -<p>Executing queries returns an <code>FMResultSet</code> object if successful, and <code>nil</code> upon failure. Like executing updates, there is a variant that accepts an <code>NSError **</code> parameter. Otherwise you should use the <code>-lastErrorMessage</code> and <code>-lastErrorCode</code> methods to determine why a query failed.</p> - -<p>In order to iterate through the results of your query, you use a <code>while()</code> loop. You also need to "step" from one record to the other. With FMDB, the easiest way to do that is like this:</p> - -<pre><code>FMResultSet *s = [db executeQuery:@"SELECT * FROM myTable"]; -while ([s next]) { - //retrieve values for each record -} -</code></pre> - -<p>You must always invoke <code>-[FMResultSet next]</code> before attempting to access the values returned in a query, even if you're only expecting one:</p> - -<pre><code>FMResultSet *s = [db executeQuery:@"SELECT COUNT(*) FROM myTable"]; -if ([s next]) { - int totalCount = [s intForColumnIndex:0]; -} -</code></pre> - -<p><code>FMResultSet</code> has many methods to retrieve data in an appropriate format:</p> - -<ul> -<li><code>intForColumn:</code></li> -<li><code>longForColumn:</code></li> -<li><code>longLongIntForColumn:</code></li> -<li><code>boolForColumn:</code></li> -<li><code>doubleForColumn:</code></li> -<li><code>stringForColumn:</code></li> -<li><code>dateForColumn:</code></li> -<li><code>dataForColumn:</code></li> -<li><code>dataNoCopyForColumn:</code></li> -<li><code>UTF8StringForColumnIndex:</code></li> -<li><code>objectForColumn:</code></li> -</ul><p>Each of these methods also has a <code>{type}ForColumnIndex:</code> variant that is used to retrieve the data based on the position of the column in the results, as opposed to the column's name.</p> - -<p>Typically, there's no need to <code>-close</code> an <code>FMResultSet</code> yourself, since that happens when either the result set is deallocated, or the parent database is closed.</p> - -<h3>Closing</h3> - -<p>When you have finished executing queries and updates on the database, you should <code>-close</code> the <code>FMDatabase</code> connection so that SQLite will relinquish any resources it has acquired during the course of its operation.</p> - -<pre><code>[db close]; -</code></pre> - -<h3>Transactions</h3> - -<p><code>FMDatabase</code> can begin and commit a transaction by invoking one of the appropriate methods or executing a begin/end transaction statement.</p> - -<h3>Data Sanitization</h3> - -<p>When providing a SQL statement to FMDB, you should not attempt to "sanitize" any values before insertion. Instead, you should use the standard SQLite binding syntax:</p> - -<pre><code>INSERT INTO myTable VALUES (?, ?, ?) -</code></pre> - -<p>The <code>?</code> character is recognized by SQLite as a placeholder for a value to be inserted. The execution methods all accept a variable number of arguments (or a representation of those arguments, such as an <code>NSArray</code>, <code>NSDictionary</code>, or a <code>va_list</code>), which are properly escaped for you.</p> - -<p>Alternatively, you may use named parameters syntax:</p> - -<pre><code>INSERT INTO myTable VALUES (:id, :name, :value) -</code></pre> - -<p>The parameters <em>must</em> start with a colon. SQLite itself supports other characters, but internally the Dictionary keys are prefixed with a colon, do <strong>not</strong> include the colon in your dictionary keys.</p> - -<pre><code>NSDictionary *argsDict = [NSDictionary dictionaryWithObjectsAndKeys:@"My Name", @"name", nil]; -[db executeUpdate:@"INSERT INTO myTable (name) VALUES (:name)" withParameterDictionary:argsDict]; -</code></pre> - -<p>Thus, you SHOULD NOT do this (or anything like this):</p> - -<pre><code>[db executeUpdate:[NSString stringWithFormat:@"INSERT INTO myTable VALUES (%@)", @"this has \" lots of ' bizarre \" quotes '"]]; -</code></pre> - -<p>Instead, you SHOULD do:</p> - -<pre><code>[db executeUpdate:@"INSERT INTO myTable VALUES (?)", @"this has \" lots of ' bizarre \" quotes '"]; -</code></pre> - -<p>All arguments provided to the <code>-executeUpdate:</code> method (or any of the variants that accept a <code>va_list</code> as a parameter) must be objects. The following will not work (and will result in a crash):</p> - -<pre><code>[db executeUpdate:@"INSERT INTO myTable VALUES (?)", 42]; -</code></pre> - -<p>The proper way to insert a number is to box it in an <code>NSNumber</code> object:</p> - -<pre><code>[db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:42]]; -</code></pre> - -<p>Alternatively, you can use the <code>-execute*WithFormat:</code> variant to use <code>NSString</code>-style substitution:</p> - -<pre><code>[db executeUpdateWithFormat:@"INSERT INTO myTable VALUES (%d)", 42]; -</code></pre> - -<p>Internally, the <code>-execute*WithFormat:</code> methods are properly boxing things for you. The following percent modifiers are recognized: <code>%@</code>, <code>%c</code>, <code>%s</code>, <code>%d</code>, <code>%D</code>, <code>%i</code>, <code>%u</code>, <code>%U</code>, <code>%hi</code>, <code>%hu</code>, <code>%qi</code>, <code>%qu</code>, <code>%f</code>, <code>%g</code>, <code>%ld</code>, <code>%lu</code>, <code>%lld</code>, and <code>%llu</code>. Using a modifier other than those will have unpredictable results. If, for some reason, you need the <code>%</code> character to appear in your SQL statement, you should use <code>%%</code>.</p> - -<h2>Using FMDatabaseQueue and Thread Safety.</h2> - -<p>Using a single instance of <code>FMDatabase</code> from multiple threads at once is a bad idea. It has always been OK to make a <code>FMDatabase</code> object <em>per thread</em>. Just don't share a single instance across threads, and definitely not across multiple threads at the same time. Bad things will eventually happen and you'll eventually get something to crash, or maybe get an exception, or maybe meteorites will fall out of the sky and hit your Mac Pro. <em>This would suck</em>.</p> - -<p><strong>So don't instantiate a single FMDatabase object and use it across multiple threads.</strong></p> - -<p>Instead, use <code>FMDatabaseQueue</code>. It's your friend and it's here to help. Here's how to use it:</p> - -<p>First, make your queue.</p> - -<pre><code>FMDatabaseQueue *queue = [FMDatabaseQueue databaseQueueWithPath:aPath]; -</code></pre> - -<p>Then use it like so:</p> - -<pre><code>[queue inDatabase:^(FMDatabase *db) { - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]]; - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]]; - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]]; - - FMResultSet *rs = [db executeQuery:@"select * from foo"]; - while ([rs next]) { - … - } -}]; -</code></pre> - -<p>An easy way to wrap things up in a transaction can be done like this:</p> - -<pre><code>[queue inTransaction:^(FMDatabase *db, BOOL *rollback) { - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]]; - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]]; - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]]; - - if (whoopsSomethingWrongHappened) { - *rollback = YES; - return; - } - // etc… - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:4]]; -}]; -</code></pre> - -<p><code>FMDatabaseQueue</code> will make a serialized GCD queue in the background and execute the blocks you pass to the GCD queue. This means if you call your <code>FMDatabaseQueue</code>'s methods from multiple threads at the same time GDC will execute them in the order they are received. This means queries and updates won't step on each other's toes, and every one is happy.</p> - -<h2>Making custom sqlite functions, based on blocks.</h2> -<p>You can do this! For an example, look for <code>makeFunctionNamed:</code> in main.m</p> - -<h2>Swift</h2> -<p> You can use FMDB in Swift projects, too. To do this, you should: </p> - -<ol> -<li>Copy the FMDB .m and .h files into your project. </li> -<li>If prompted to create a "bridging header", you should do so. If not prompted and if you don't already have a bridging header, add one. For more information on bridging headers, see <a href="https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html#//apple_ref/doc/uid/TP40014216-CH10-XID_76">Swift and Objective-C in the Same Project</a>. </li> -<li>In your bridging header, add a line that says: <br /> -<pre><code>#import "FMDB.h" </code></pre></li> -<li>Use the variations of <code>executeQuery</code> and <code>executeUpdate</code> with the sql and values parameters with try pattern, as shown below. -</p></ol> - -<p>These renditions of <code>executeQuery</code> and <code>executeUpdate</code> both throw errors in true Swift 2 fashion. If you do the above, you can then write Swift code that uses <code>FMDatabase</code>. For example: </p> - -<pre><code>let documents = try! NSFileManager.defaultManager().URLForDirectory(.DocumentDirectory, inDomain: .UserDomainMask, appropriateForURL: nil, create: false) -let fileURL = documents.URLByAppendingPathComponent("test.sqlite") -let database = FMDatabase(path: fileURL.path) - -if !database.open() { - print("Unable to open database") - return -} - -do { - try database.executeUpdate("create table test(x text, y text, z text)", values: nil) - try database.executeUpdate("insert into test (x, y, z) values (?, ?, ?)", values: ["a", "b", "c"]) - try database.executeUpdate("insert into test (x, y, z) values (?, ?, ?)", values: ["e", "f", "g"]) - - let rs = try database.executeQuery("select x, y, z from test", values: nil) - while rs.next() { - let x = rs.stringForColumn("x") - let y = rs.stringForColumn("y") - let z = rs.stringForColumn("z") - print("x = \(x); y = \(y); z = \(z)") - } -} catch let error as NSError { - print("failed: \(error.localizedDescription)") -} - -database.close()</code></pre> -<h2>History</h2> - -<p>The history and changes are availbe on its <a href="https://github.com/ccgus/fmdb">GitHub page</a> and are summarized in the "CHANGES_AND_TODO_LIST.txt" file.</p> - -<h2>Contributors</h2> - -<p>The contributors to FMDB are contained in the "Contributors.txt" file.</p> - -<h2>License</h2> - -<p>The license for FMDB is contained in the "License.txt" file.</p> - </section> - </div> - - <!-- FOOTER --> - <div id="footer_wrap" class="outer"> - <footer class="inner"> - <p class="copyright">Fmdb maintained by <a href="https://github.com/ccgus">ccgus</a></p> - <p>Published with <a href="http://pages.github.com">GitHub Pages</a></p> - </footer> - </div> - - - + <p>If not redirected automatically, follow <a href="https://ccgus.github.io/fmdb/html/index.html">this link</a>.</p> </body> </html> |