FFI & C Interop

#include <stddef.h>

/* Weighted ISBN-13 checksum of the first n ASCII digits; -1 on a non-digit. */
int isbn_checksum(const char *digits, size_t n);

/* Calls cb(user_data, title) for each title in a fixed list. */
typedef void (*title_cb)(void *user_data, const char *title);
void for_each_title(title_cb cb, void *user_data);

mod sys {
    use std::ffi::{c_char, c_int, c_void};

    pub type TitleCb = Option<unsafe extern "C" fn(user_data: *mut c_void, title: *const c_char)>;

    // Edition 2024: extern blocks are `unsafe extern`, and items can be marked `safe`.
    unsafe extern "C" {
        pub fn isbn_checksum(digits: *const c_char, n: usize) -> c_int;
        pub fn for_each_title(cb: TitleCb, user_data: *mut c_void);
        pub safe fn abs(x: c_int) -> c_int; // from libc: no preconditions, so callable without `unsafe`
    }
}

/// Safe wrapper: validates an ISBN-13 using the C checksum.
pub fn isbn_is_valid(isbn: &str) -> bool {
    let digits: String = isbn.chars().filter(|c| *c != '-').collect();
    if digits.len() != 13 {
        return false;
    }
    // SAFETY: `digits` is a live UTF-8 buffer of exactly `digits.len()` bytes; the C function
    // reads n bytes and does not keep the pointer.
    let sum = unsafe { sys::isbn_checksum(digits.as_ptr().cast::<c_char>(), digits.len()) };
    sum >= 0 && sum % 10 == 0
}

/// Safe wrapper around a C callback API: collects the titles into a Vec.
pub fn all_titles() -> Vec<String> {
    unsafe extern "C" fn push(user_data: *mut c_void, title: *const c_char) {
        // SAFETY: `user_data` is the &mut Vec passed below; `title` is a NUL-terminated string
        // that stays valid for the duration of the callback.
        let titles = unsafe { &mut *user_data.cast::<Vec<String>>() };
        let title = unsafe { CStr::from_ptr(title) };
        titles.push(title.to_string_lossy().into_owned());
    }
    let mut titles: Vec<String> = Vec::new();
    // SAFETY: `push` matches the callback signature and `titles` outlives the call.
    unsafe { sys::for_each_title(Some(push), (&raw mut titles).cast::<c_void>()) };
    titles
}

pub fn magnitude(x: i32) -> i32 {
    sys::abs(x) // a `safe` foreign item: no unsafe block needed
}

[package]
name = "ffitest"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["cdylib", "rlib"]   # cdylib: a C-loadable .so/.dylib/.dll; rlib: usable from Rust too

[build-dependencies]
cc = "1.6"
bindgen = "0.73"

// build.rs: compile the C library and generate Rust declarations for its header.
use std::env;
use std::path::PathBuf;

fn main() {
    println!("cargo::rerun-if-changed=c/isbn.c");
    println!("cargo::rerun-if-changed=c/isbn.h");

    cc::Build::new().file("c/isbn.c").compile("isbn"); // builds libisbn.a and links it

    let bindings = bindgen::Builder::default()
        .header("c/isbn.h")
        .allowlist_function("isbn_checksum|for_each_title")
        .wrap_unsafe_ops(true)
        .generate()
        .expect("generate bindings");
    let out = PathBuf::from(env::var("OUT_DIR").expect("set by cargo"));
    bindings.write_to_file(out.join("isbn_bindings.rs")).expect("write bindings");
}

// in src/lib.rs: use the generated declarations
#[allow(non_camel_case_types, dead_code)]
mod generated {
    include!(concat!(env!("OUT_DIR"), "/isbn_bindings.rs"));
}

pub fn checksum_via_bindgen(digits: &str) -> i32 {
    // SAFETY: as in `isbn_is_valid`.
    unsafe { generated::isbn_checksum(digits.as_ptr().cast(), digits.len()) }
}

/// Returns 1 if `isbn` is a valid ISBN-13, 0 otherwise.
///
/// # Safety
///
/// `isbn` must be a valid pointer to a NUL-terminated string that stays alive for the call.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn shelf_isbn_valid(isbn: *const c_char) -> c_int {
    if isbn.is_null() {
        return 0;
    }
    // SAFETY: guaranteed by the caller (see # Safety).
    let isbn = unsafe { CStr::from_ptr(isbn) };
    c_int::from(isbn.to_str().is_ok_and(isbn_is_valid))
}

/// Parses a year; returns -1 for invalid input and -2 if Rust code panicked.
/// Panics must not unwind into C: catch them at the boundary, or use the "C-unwind" ABI.
///
/// # Safety
///
/// `year` must be NULL or a valid pointer to a NUL-terminated string.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn shelf_parse_year(year: *const c_char) -> c_int {
    std::panic::catch_unwind(|| {
        if year.is_null() {
            return -1;
        }
        // SAFETY: guaranteed by the caller (see # Safety).
        let text = unsafe { CStr::from_ptr(year) }.to_string_lossy();
        text.trim().parse().unwrap_or(-1)
    })
    .unwrap_or(-2)
}