Merge pull request #262 from gradha/pr_adds_some_documentation_to_db_modules

Documents NULL to "" db_* transformation and return values.

3 files changed, 21 insertions, 13 deletions

diff --git a/lib/impure/db_mysql.nim b/lib/impure/db_mysql.nim
index 5c71fc90d..91cf8a5eb 100755
--- a/lib/impure/db_mysql.nim
+++ b/lib/impure/db_mysql.nim
@@ -14,7 +14,8 @@ import strutils, mysql
 
 type
   TDbConn* = PMySQL    ## encapsulates a database connection
-  TRow* = seq[string]  ## a row of a dataset
+  TRow* = seq[string]  ## a row of a dataset. NULL database values will be
+                       ## transformed always to the empty string.
   EDb* = object of EIO ## exception that is raised if a database error occurs
 
   TSqlQuery* = distinct string ## an SQL query string
@@ -111,7 +112,8 @@ iterator FastRows*(db: TDbConn, query: TSqlQuery,
 
 proc getRow*(db: TDbConn, query: TSqlQuery,
              args: varargs[string, `$`]): TRow {.tags: [FReadDB].} =
-  ## retrieves a single row.
+  ## retrieves a single row. If the query doesn't return any rows, this proc
+  ## will return a TRow with empty strings for each column.
   rawExec(db, query, args)
   var sqlres = mysql.UseResult(db)
   if sqlres != nil:
@@ -150,9 +152,9 @@ iterator Rows*(db: TDbConn, query: TSqlQuery,
 
 proc GetValue*(db: TDbConn, query: TSqlQuery, 
                args: varargs[string, `$`]): string {.tags: [FReadDB].} = 
-  ## executes the query and returns the result dataset's the first column 
-  ## of the first row. Returns "" if the dataset contains no rows. This uses
-  ## `FastRows`, so it inherits its fragile behaviour.
+  ## executes the query and returns the first column of the first row of the
+  ## result dataset. Returns "" if the dataset contains no rows or the database
+  ## value is NULL.
   result = ""
   for row in FastRows(db, query, args): 
     result = row[0]
diff --git a/lib/impure/db_postgres.nim b/lib/impure/db_postgres.nim
index 870960140..2dd55e05f 100755
--- a/lib/impure/db_postgres.nim
+++ b/lib/impure/db_postgres.nim
@@ -14,7 +14,8 @@ import strutils, postgres
 
 type
   TDbConn* = PPGconn   ## encapsulates a database connection
-  TRow* = seq[string]  ## a row of a dataset
+  TRow* = seq[string]  ## a row of a dataset. NULL database values will be
+                       ## transformed always to the empty string.
   EDb* = object of EIO ## exception that is raised if a database error occurs
   
   TSqlQuery* = distinct string ## an SQL query string
@@ -110,7 +111,8 @@ iterator FastRows*(db: TDbConn, query: TSqlQuery,
 
 proc getRow*(db: TDbConn, query: TSqlQuery,
              args: varargs[string, `$`]): TRow {.tags: [FReadDB].} =
-  ## retrieves a single row.
+  ## retrieves a single row. If the query doesn't return any rows, this proc
+  ## will return a TRow with empty strings for each column.
   var res = setupQuery(db, query, args)
   var L = PQnfields(res)
   result = newRow(L)
@@ -131,8 +133,9 @@ iterator Rows*(db: TDbConn, query: TSqlQuery,
 
 proc GetValue*(db: TDbConn, query: TSqlQuery, 
                args: varargs[string, `$`]): string {.tags: [FReadDB].} = 
-  ## executes the query and returns the result dataset's the first column 
-  ## of the first row. Returns "" if the dataset contains no rows.
+  ## executes the query and returns the first column of the first row of the
+  ## result dataset. Returns "" if the dataset contains no rows or the database
+  ## value is NULL.
   var x = PQgetvalue(setupQuery(db, query, args), 0, 0)
   result = if isNil(x): "" else: $x
   
diff --git a/lib/impure/db_sqlite.nim b/lib/impure/db_sqlite.nim
index fbc097784..693077553 100755
--- a/lib/impure/db_sqlite.nim
+++ b/lib/impure/db_sqlite.nim
@@ -14,7 +14,8 @@ import strutils, sqlite3
 
 type
   TDbConn* = PSqlite3  ## encapsulates a database connection
-  TRow* = seq[string]  ## a row of a dataset
+  TRow* = seq[string]  ## a row of a dataset. NULL database values will be
+                       ## transformed always to the empty string.
   EDb* = object of EIO ## exception that is raised if a database error occurs
   
   TSqlQuery* = distinct string ## an SQL query string
@@ -108,7 +109,8 @@ iterator FastRows*(db: TDbConn, query: TSqlQuery,
 
 proc getRow*(db: TDbConn, query: TSqlQuery,
              args: varargs[string, `$`]): TRow {.tags: [FReadDB].} =
-  ## retrieves a single row.
+  ## retrieves a single row. If the query doesn't return any rows, this proc
+  ## will return a TRow with empty strings for each column.
   var stmt = setupQuery(db, query, args)
   var L = (columnCount(stmt))
   result = newRow(L)
@@ -130,8 +132,9 @@ iterator Rows*(db: TDbConn, query: TSqlQuery,
 
 proc GetValue*(db: TDbConn, query: TSqlQuery, 
                args: varargs[string, `$`]): string {.tags: [FReadDB].} = 
-  ## executes the query and returns the result dataset's the first column 
-  ## of the first row. Returns "" if the dataset contains no rows.
+  ## executes the query and returns the first column of the first row of the
+  ## result dataset. Returns "" if the dataset contains no rows or the database
+  ## value is NULL.
   var stmt = setupQuery(db, query, args)
   if step(stmt) == SQLITE_ROW:
     let cb = column_bytes(stmt, 0)