Merge pull request #45 from SpringQL/build/0.13.0

feat: 0.13.0

Author: laysakura

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
         rust:
           - nightly
           - stable
-          - 1.56.0  # MSRV
+          - 1.57.0  # MSRV
         make:
           - name: format
             task: format
@@ -48,37 +48,37 @@ jobs:
           - rust: nightly
             make:
               name: format
-          - rust: 1.56.0
+          - rust: 1.57.0
             make:
               name: format
           - rust: nightly
             make:
               name: lint
-          - rust: 1.56.0
+          - rust: 1.57.0
             make:
               name: lint
           - rust: nightly
             make:
               name: doc
-          - rust: 1.56.0
+          - rust: 1.57.0
             make:
               name: doc
           - rust: nightly
             make:
               name: deadlink
-          - rust: 1.56.0
+          - rust: 1.57.0
             make:
               name: deadlink
           - rust: stable
             make:
               name: codecov
-          - rust: 1.56.0
+          - rust: 1.57.0
             make:
               name: codecov
           - rust: nightly
             make:
               name: copyright
-          - rust: 1.56.0
+          - rust: 1.57.0
             make:
               name: copyright
     env:

CHANGELOG.md

@@ -13,6 +13,13 @@ Also check the changes in springql-core: <https://github.com/SpringQL/SpringQL/b
 <!-- markdownlint-disable MD024 -->
 ## [Unreleased]
 
+## [v0.13.0]
+
+### Added
+
+- `spring_column_blob()` and `spring_column_unsigned_int()`. ([#45](https://github.com/SpringQL/SpringQL-client-c/pull/45))
+- `SpringErrno::Time` error number. ([#45](https://github.com/SpringQL/SpringQL-client-c/pull/45))
+
 ## [v0.12.0]
 
 ### For developers
@@ -54,8 +61,9 @@ Depends on springql-core v0.7.1.
 [Semantic Versioning]: https://semver.org/
 
 <!-- Versions -->
-[Unreleased]: https://github.com/SpringQL/SpringQL-client-c/compare/v0.12.0...HEAD
+[Unreleased]: https://github.com/SpringQL/SpringQL-client-c/compare/v0.13.0...HEAD
 [Released]: https://github.com/SpringQL/SpringQL-client-c/releases
+[v0.13.0]: https://github.com/SpringQL/SpringQL-client-c/compare/v0.12.0...v0.13.0
 [v0.12.0]: https://github.com/SpringQL/SpringQL-client-c/compare/v0.11.0...v0.12.0
 [v0.11.0]: https://github.com/SpringQL/SpringQL-client-c/compare/v0.9.0+2...v0.11.0
 [v0.9.0+2]: https://github.com/SpringQL/SpringQL-client-c/compare/v0.9.0...v0.9.0+2

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "springql-client-c"
-version = "0.12.0"
+version = "0.13.0"
 
 authors = ["Sho Nakatani <[email protected]>"]
 license = "MIT OR Apache-2.0"
@@ -15,6 +15,6 @@ name = "springql_client"
 cbindgen = "0.23"
 
 [dependencies]
-springql-core = "0.12.0"
+springql-core = "0.13.0"
 
 log = "0.4"

springql.h

@@ -25,6 +25,7 @@ typedef enum SpringErrno {
   Sql = -10,
   InvalidConfig = -11,
   Null = -12,
+  Time = -13,
   /**
    * Insufficient buffer size
    */
@@ -227,6 +228,27 @@ enum SpringErrno spring_column_int(const SpringRow *row, uint16_t i_col, int *ou
  */
 enum SpringErrno spring_column_long(const SpringRow *row, uint16_t i_col, long *out);
 
+/**
+ * Get a 4-byte unsigned integer column.
+ *
+ * # Parameters
+ *
+ * - `row`: A `SpringRow` pointer to get a column value from.
+ * - `i_col`: The column index to get a value from.
+ * - `out`: A pointer to a buffer to store the column value.
+ *
+ * # Returns
+ *
+ * - `Ok`: On success.
+ * - `Unavailable`:
+ *   - Column pointed by `i_col` is already fetched.
+ *   - `i_col` is out of range.
+ * - `CNull`: Column value is NULL.
+ */
+enum SpringErrno spring_column_unsigned_int(const SpringRow *row,
+                                            uint16_t i_col,
+                                            unsigned int *out);
+
 /**
  * Get a text column.
  *
@@ -247,6 +269,26 @@ enum SpringErrno spring_column_long(const SpringRow *row, uint16_t i_col, long *
  */
 int spring_column_text(const SpringRow *row, uint16_t i_col, char *out, int out_len);
 
+/**
+ * Get a BLOB column.
+ *
+ * # Parameters
+ *
+ * - `row`: A `SpringRow` pointer to get a column value from.
+ * - `i_col`: The column index to get a value from.
+ * - `out`: A pointer to a buffer to store the column value.
+ * - `out_len`: The length of the buffer pointed by `out`.
+ *
+ * # Returns
+ *
+ * - `> 0`: Length of the text.
+ * - `Unavailable`:
+ *   - Column pointed by `i_col` is already fetched.
+ *   - `i_col` is out of range.
+ * - `CNull`: Column value is NULL.
+ */
+int spring_column_blob(const SpringRow *row, uint16_t i_col, void *out, int out_len);
+
 /**
  * Get a bool column.
  *

src/cstr.rs renamed to src/c_mem.rs

@@ -2,7 +2,7 @@
 
 use std::{
     os::raw::{c_char, c_int},
-    ptr, slice,
+    ptr, slice, ffi::c_void,
 };
 
 use log::warn;
@@ -35,3 +35,30 @@ pub(super) fn strcpy(src: &str, dest_buf: *mut c_char, dest_len: c_int) -> c_int
 
     src.len() as c_int
 }
+
+/// # Returns
+///
+/// - `> 0`: the length of `src`.
+/// - `< 0`: SpringErrno
+pub(super) fn memcpy(src: &[u8], dest_buf: *mut c_void, dest_len: c_int) -> c_int {
+    if src.len() >= dest_len as usize {
+        warn!("dest_len is smaller than src.");
+        warn!(
+            "Expected at least {} bytes but got {}",
+            src.len() + 1,
+            dest_len
+        );
+        return SpringErrno::CInsufficient as c_int;
+    }
+
+    let buffer = unsafe { slice::from_raw_parts_mut(dest_buf as *mut u8, dest_len as usize) };
+    unsafe {
+        ptr::copy_nonoverlapping(src.as_ptr(), buffer.as_mut_ptr(), src.len());
+    }
+
+    // Add a trailing null so people using the string as a `char *` don't
+    // accidentally read into garbage.
+    buffer[src.len()] = 0;
+
+    src.len() as c_int
+}

src/lib.rs

@@ -4,22 +4,22 @@
 
 #![allow(clippy::missing_safety_doc)] // C header file does not need `Safety` section
 
-pub(crate) mod cstr;
+pub(crate) mod c_mem;
 mod spring_config;
 pub mod spring_errno;
 pub mod spring_last_err;
 mod spring_pipeline;
 mod spring_row;
 
 use std::{
-    ffi::CStr,
-    os::raw::{c_char, c_float, c_int, c_long, c_short},
+    ffi::{c_void, CStr},
+    os::raw::{c_char, c_float, c_int, c_long, c_short, c_uint},
     panic::{catch_unwind, UnwindSafe},
     ptr,
 };
 
 use crate::{
-    cstr::strcpy,
+    c_mem::{memcpy, strcpy},
     spring_config::SpringConfig,
     spring_errno::SpringErrno,
     spring_last_err::{update_last_error, LastError},
@@ -327,6 +327,39 @@ pub unsafe extern "C" fn spring_column_long(
     }
 }
 
+/// Get a 4-byte unsigned integer column.
+///
+/// # Parameters
+///
+/// - `row`: A `SpringRow` pointer to get a column value from.
+/// - `i_col`: The column index to get a value from.
+/// - `out`: A pointer to a buffer to store the column value.
+///
+/// # Returns
+///
+/// - `Ok`: On success.
+/// - `Unavailable`:
+///   - Column pointed by `i_col` is already fetched.
+///   - `i_col` is out of range.
+/// - `CNull`: Column value is NULL.
+#[no_mangle]
+pub unsafe extern "C" fn spring_column_unsigned_int(
+    row: *const SpringRow,
+    i_col: u16,
+    out: *mut c_uint,
+) -> SpringErrno {
+    let row = (*row).as_row();
+    let i_col = i_col as usize;
+    let result = with_catch(|| row.get_not_null_by_index(i_col as usize));
+    match result {
+        Ok(v) => {
+            *out = v;
+            SpringErrno::Ok
+        }
+        Err(e) => e,
+    }
+}
+
 /// Get a text column.
 ///
 /// # Parameters
@@ -363,6 +396,42 @@ pub unsafe extern "C" fn spring_column_text(
     }
 }
 
+/// Get a BLOB column.
+///
+/// # Parameters
+///
+/// - `row`: A `SpringRow` pointer to get a column value from.
+/// - `i_col`: The column index to get a value from.
+/// - `out`: A pointer to a buffer to store the column value.
+/// - `out_len`: The length of the buffer pointed by `out`.
+///
+/// # Returns
+///
+/// - `> 0`: Length of the text.
+/// - `Unavailable`:
+///   - Column pointed by `i_col` is already fetched.
+///   - `i_col` is out of range.
+/// - `CNull`: Column value is NULL.
+#[no_mangle]
+pub unsafe extern "C" fn spring_column_blob(
+    row: *const SpringRow,
+    i_col: u16,
+    out: *mut c_void,
+    out_len: c_int,
+) -> c_int {
+    let row = (*row).as_row();
+    let i_col = i_col as usize;
+    let result: Result<Vec<u8>, SpringErrno> =
+        with_catch(|| row.get_not_null_by_index(i_col as usize));
+    match result {
+        Ok(v) => {
+            let v_len = memcpy(&v, out, out_len);
+            v_len as c_int
+        }
+        Err(e) => e as c_int,
+    }
+}
+
 /// Get a bool column.
 ///
 /// # Parameters

src/spring_errno.rs

@@ -24,6 +24,7 @@ pub enum SpringErrno {
     Sql = -10,
     InvalidConfig = -11,
     Null = -12,
+    Time = -13,
 
     /// Insufficient buffer size
     CInsufficient = -126,
@@ -45,6 +46,7 @@ impl From<&SpringError> for SpringErrno {
             SpringError::Sql(_) => SpringErrno::Sql,
             SpringError::InvalidConfig { .. } => SpringErrno::InvalidConfig,
             SpringError::Null { .. } => SpringErrno::Null,
+            SpringError::Time(_) => SpringErrno::Time,
         }
     }
 }

src/spring_last_err.rs

@@ -11,7 +11,7 @@ use std::{
 use ::log::{info, warn};
 use ::springql_core::api::error::SpringError;
 
-use crate::{cstr::strcpy, spring_errno::SpringErrno};
+use crate::{c_mem::strcpy, spring_errno::SpringErrno};
 
 thread_local! {
     static LAST_ERROR: RefCell<Option<LastError>> = RefCell::new(None);