Skip to content

Commit

Permalink
Minor comment updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@aabewhite
aabewhite committed Dec 11, 2023
1 parent b15dd20 commit 3d558c9
Show file tree
Hide file tree
Showing 3 changed files with 32 additions and 30 deletions.
40 changes: 20 additions & 20 deletions Sources/SkipSQL/SQLContext.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,35 +9,35 @@ import OSLog
import SkipFFI
#endif

internal let logger: Logger = Logger(subsystem: "skip.sql", category: "SQL")
let logger: Logger = Logger(subsystem: "skip.sql", category: "SQL")

/// The default SQLite library to use, which is the library installed with the current host system
/// The default SQLite library to use, which is the library installed with the current host system.
public let SQLiteDefaultLibrary: SQLiteLibrary = SQLitePlatformLibrary()

/// A context for performing operations on a SQLite database.
public final class SQLContext {
/// The SQLite3 library to use
/// The SQLite3 library to use.
fileprivate let SQLite3: SQLiteLibrary

/// The logging level for this context; SQL statements and warnings will be sent to this log
/// The logging level for this context; SQL statements and warnings will be sent to this log.
public var logLevel: OSLogType? = nil

/// The pointer to the SQLite database
/// The pointer to the SQLite database.
private let db: OpaquePointer
private var closed = false
private var updateHook: UpdateHook? = nil

/// The rowid of the most recent successful `INSERT` into a rowid table
/// The rowid of the most recent successful `INSERT` into a rowid table.
public var lastInsertRowID: Int64 {
SQLite3.sqlite3_last_insert_rowid(db)
}

/// The number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement
/// The number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement.
public var changes: Int32 {
SQLite3.sqlite3_changes(db)
}

/// The total number of rows inserted, modified or deleted by all [INSERT], [UPDATE] or [DELETE] statements completed since the database connection was opened, including those executed as part of triggers
/// The total number of rows inserted, modified or deleted by all [INSERT], [UPDATE] or [DELETE] statements completed since the database connection was opened, including those executed as part of triggers.
public var totalChanges: Int32 {
SQLite3.sqlite3_total_changes(db)
}
Expand All @@ -50,7 +50,7 @@ public final class SQLContext {
#endif
}

/// Create an in-memory `SQLContext`
/// Create an in-memory `SQLContext`.
public init(SQLite3: SQLiteLibrary = SQLiteDefaultLibrary) {
// try! because creating an in-memory context should never fail
self.SQLite3 = SQLite3
Expand All @@ -59,8 +59,8 @@ public final class SQLContext {

/// Create a new `SQLContext` with the given options, either in-memory (the default), or on a file path.
/// - Parameters:
/// - path: the path to the local file, or ":memory:" for an in-memory database
/// - flags: the flags to use to open the database
/// - path: The path to the local file, or ":memory:" for an in-memory database.
/// - flags: The flags to use to open the database.
public init(path: String, flags: OpenFlags? = nil, logLevel: OSLogType? = nil, SQLite3: SQLiteLibrary = SQLiteDefaultLibrary) throws {
self.logLevel = logLevel
self.SQLite3 = SQLite3
Expand Down Expand Up @@ -105,7 +105,7 @@ public final class SQLContext {
}


/// Execute the given SQL statement
/// Execute the given SQL statement.
public func exec(sql: String, parameters: [SQLValue] = []) throws {
try checkClosed()
let stmnt = try prepare(sql: sql)
Expand All @@ -127,7 +127,7 @@ public final class SQLContext {
SQLite3.sqlite3_interrupt(db)
}

/// True if the context has been closed
/// True if the context has been closed.
public var isClosed: Bool {
closed
}
Expand Down Expand Up @@ -159,7 +159,7 @@ public final class SQLContext {
return SQLStatement(stmnt: stmntPtr!, SQLite3: self.SQLite3)
}

/// How a transaction is being performed
/// How a transaction is being performed.
public enum TransactionMode: String {
case deferred = "DEFERRED"
case immediate = "IMMEDIATE"
Expand All @@ -180,7 +180,7 @@ public final class SQLContext {
}
}

/// Performs the given operation within the databases mutex lock
/// Performs the given operation within the databases mutex lock.
public func mutex<T>(block: () throws -> T) rethrows -> T {
let lock = SQLite3.sqlite3_db_mutex(db)
SQLite3.sqlite3_mutex_enter(lock)
Expand All @@ -191,7 +191,7 @@ public final class SQLContext {
return try block()
}

/// Performs the given operation in the context of a begin and commit/rollback statement
/// Performs the given operation in the context of a begin and commit/rollback statement.
fileprivate func perform<T>(_ begin: String, _ block: () throws -> T, _ commit: String, or rollback: String) throws -> T {
try exec(sql: begin)
do {
Expand All @@ -210,7 +210,7 @@ public final class SQLContext {
}
}

/// Issues a SQL query with the optional parameters and returns all the values
/// Issues a SQL query with the optional parameters and returns all the values.
public func query(sql: String, parameters: [SQLValue] = []) throws -> [[SQLValue]] {
let stmnt = try prepare(sql: sql)
if !parameters.isEmpty {
Expand Down Expand Up @@ -239,10 +239,10 @@ public final class SQLContext {
return rows
}

/// An action that can be registered to receive updates whenever a ROWID table changes
public typealias UpdateAction = (_ action: SQLAction, _ rowid: Int64, _ dbname: String, _ tblname: String) -> ()
/// An action that can be registered to receive updates whenever a ROWID table changes.
public typealias UpdateAction = (_ action: SQLAction, _ rowid: Int64, _ dbname: String, _ tblname: String) -> Void

/// Registers a function to be invoked whenever a ROWID table is changed
/// Registers a function to be invoked whenever a ROWID table is changed.
///
/// As described at https://www.sqlite.org/c3ref/update_hook.html , a given connection can only have a single update hook at a time, so setting this function will replace any pre-existing update hook.
public func onUpdate(hook: @escaping UpdateAction) {
Expand Down
19 changes: 10 additions & 9 deletions Sources/SkipSQL/SQLStatement.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,12 @@ import OSLog
import SkipFFI
#endif

/// A database prepared statement.
public final class SQLStatement {
/// The SQLite3 library to use
/// The SQLite3 library to use.
fileprivate let SQLite3: SQLiteLibrary

/// The pointer to the SQLite statement
/// The pointer to the SQLite statement.
fileprivate let stmnt: OpaquePointer
fileprivate var closed = false

Expand All @@ -30,7 +31,7 @@ public final class SQLStatement {
self.SQLite3 = SQLite3
}

/// The database pointer that created this statement
/// The database pointer that created this statement.
private var db: OpaquePointer {
SQLite3.sqlite3_db_handle(stmnt)
}
Expand All @@ -55,7 +56,7 @@ public final class SQLStatement {
// strptr(SQLite3.sqlite3_column_database_name(stmnt, $0)) ?? ""
// })

/// Binds the given value at the index
/// Binds the given value at the 1-based index.
public func bind(_ value: SQLValue, at index: Int32) throws {
precondition(index >= 1, "bind index in sqlite starts at 1")
switch value {
Expand Down Expand Up @@ -86,7 +87,7 @@ public final class SQLStatement {
}
}

/// Perform an update with the prepared statemement, resetting it once the update is complete
/// Perform an update with the prepared statemement, resetting it once the update is complete.
/// - Parameter params: the parameters to bind to the SQL statement
public func update(parameters: [SQLValue] = []) throws {
try checkClosed()
Expand Down Expand Up @@ -122,7 +123,7 @@ public final class SQLStatement {
}
}

/// True if the statement has been closed
/// True if the statement has been closed.
public var isClosed: Bool {
closed
}
Expand Down Expand Up @@ -243,17 +244,17 @@ public final class SQLStatement {
}
}

/// The number of named or indexed parameters in this statement
/// The SQL of this statement.
public var sql: String {
strptr(SQLite3.sqlite3_sql(stmnt)) ?? ""
}

/// The number of named or indexed parameters in this statement
/// The number of named or indexed parameters in this statement.
public var parameterCount: Int32 {
SQLite3.sqlite3_bind_parameter_count(stmnt)
}

/// The number of named or indexed parameters in this statement
/// The number of named or indexed parameters in this statement.
public var parameterNames: [String?] {
Array((1...parameterCount).map {
strptr(SQLite3.sqlite3_bind_parameter_name(stmnt, $0))
Expand Down
3 changes: 2 additions & 1 deletion Sources/SkipSQL/SQLite.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import OSLog
import SkipFFI
#endif

/// An action taken on a row
/// An action taken on a row.
public enum SQLAction : Int32 {
case insert = 18 // SQLITE_INSERT
case delete = 9 // SQLITE_DELETE
Expand Down Expand Up @@ -40,6 +40,7 @@ public enum SQLType : Int32, CaseIterable, Hashable {
case null = 5 // SQLITE_NULL
}

/// A database value.
public enum SQLValue : Hashable {
case integer(Int64)
case float(Double)
Expand Down

0 comments on commit 3d558c9

Please sign in to comment.