artichoke_backend/extn/core/string/

ffi.rs

use core::char;
use core::convert::TryFrom;
use core::hash::BuildHasher;
use core::num::Wrapping;
use core::ptr;
use core::slice;
use core::str;
use std::collections::TryReserveError;
use std::ffi::{CStr, c_char, c_double, c_int, c_void};
use std::io::Write as _;
use std::ptr::NonNull;

use artichoke_core::convert::Convert;
use artichoke_core::hash::Hash as _;
use bstr::ByteSlice;
use spinoso_exception::ArgumentError;
use spinoso_exception::NoMemoryError;
use spinoso_string::{RawParts, String};

use super::trampoline;
use crate::convert::BoxUnboxVmValue;
use crate::error;
use crate::sys;
use crate::value::Value;

// ```c
// MRB_API mrb_value mrb_str_new_capa(mrb_state *mrb, size_t capa)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_new_capa(mrb: *mut sys::mrb_state, capa: sys::mrb_int) -> sys::mrb_value {
    let capa = if let Ok(capa) = usize::try_from(capa) {
        capa
    } else {
        return sys::mrb_sys_nil_value();
    };
    unwrap_interpreter!(mrb, to => guard);
    let result = String::with_capacity(capa);
    let result = String::alloc_value(result, &mut guard);
    match result {
        Ok(value) => value.inner(),
        Err(exception) => {
            // SAFETY: only Copy objects remain on the stack
            unsafe { error::raise(guard, exception) }
        }
    }
}

// ```c
// MRB_API mrb_value mrb_str_new(mrb_state *mrb, const char *p, size_t len)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_new(
    mrb: *mut sys::mrb_state,
    p: *const c_char,
    len: sys::mrb_int,
) -> sys::mrb_value {
    let len = if let Ok(len) = usize::try_from(len) {
        len
    } else {
        return sys::mrb_sys_nil_value();
    };
    unwrap_interpreter!(mrb, to => guard);
    let s = if p.is_null() {
        String::utf8(vec![0; len])
    } else {
        let bytes = slice::from_raw_parts(p.cast::<u8>(), len);
        let bytes = bytes.to_vec();
        String::utf8(bytes)
    };
    let result = String::alloc_value(s, &mut guard);
    match result {
        Ok(value) => value.inner(),
        Err(exception) => {
            // SAFETY: only Copy objects remain on the stack
            unsafe { error::raise(guard, exception) }
        }
    }
}

// ```c
// MRB_API mrb_value mrb_str_new_cstr(mrb_state *mrb, const char *p)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_new_cstr(mrb: *mut sys::mrb_state, p: *const c_char) -> sys::mrb_value {
    unwrap_interpreter!(mrb, to => guard);
    let cstr = CStr::from_ptr(p);
    let bytes = cstr.to_bytes().to_vec();
    let result = String::utf8(bytes);
    let result = String::alloc_value(result, &mut guard);
    match result {
        Ok(value) => value.inner(),
        Err(exception) => {
            // SAFETY: only Copy objects remain on the stack
            unsafe { error::raise(guard, exception) }
        }
    }
}

// ```c
// MRB_API mrb_value mrb_str_new_static(mrb_state *mrb, const char *p, size_t len)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_new_static(
    mrb: *mut sys::mrb_state,
    p: *const c_char,
    len: sys::mrb_int,
) -> sys::mrb_value {
    // Artichoke doesn't have a static string optimization.
    mrb_str_new(mrb, p, len)
}

// ```c
// MRB_API mrb_int mrb_str_index(mrb_state *mrb, mrb_value str, const char *sptr, mrb_int slen, mrb_int offset)
// ```
#[unsafe(no_mangle)]
#[expect(
    clippy::cast_possible_wrap,
    reason = "mruby stores sizes as int64_t instead of size_t"
)]
unsafe extern "C-unwind" fn mrb_str_index(
    mrb: *mut sys::mrb_state,
    s: sys::mrb_value,
    sptr: *const c_char,
    slen: sys::mrb_int,
    offset: sys::mrb_int,
) -> sys::mrb_int {
    unwrap_interpreter!(mrb, to => guard, or_else = -1);
    let mut value = s.into();
    let Ok(string) = String::unbox_from_value(&mut value, &mut guard) else {
        return -1;
    };

    /*
    len = RSTRING_LEN(str);
    if (offset < 0) {
      offset += len;
      if (offset < 0) return -1;
    }
    if (len - offset < slen) return -1;
    s = RSTRING_PTR(str);
    if (offset) {
      s += offset;
    }
    if (slen == 0) return offset;
    /* need proceed one character at a time */
    len = RSTRING_LEN(str) - offset;
    */
    let mut offset = isize::try_from(offset).unwrap_or(0);
    let length = isize::try_from(string.len()).unwrap_or(0);
    if offset < 0 {
        offset += length;
    }
    let Ok(offset) = usize::try_from(offset) else {
        return -1;
    };
    let Some(haystack) = string.get(offset..) else {
        return -1;
    };
    let needle = slice::from_raw_parts(sptr.cast::<u8>(), usize::try_from(slen).unwrap_or(0));
    if needle.is_empty() {
        return offset as sys::mrb_int;
    }
    haystack.find(needle).map_or(-1, |pos| pos as sys::mrb_int)
}

// ```c
// mrb_value mrb_str_aref(mrb_state *mrb, mrb_value str, mrb_value indx, mrb_value alen)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_aref(
    mrb: *mut sys::mrb_state,
    s: sys::mrb_value,
    indx: sys::mrb_value,
    alen: sys::mrb_value,
) -> sys::mrb_value {
    unwrap_interpreter!(mrb, to => guard);
    let value = Value::from(s);
    let indx = Value::from(indx);
    let alen = Value::from(alen);

    let alen = if alen.is_unreachable() { None } else { Some(alen) };

    let result = trampoline::aref(&mut guard, value, indx, alen);
    match result {
        Ok(value) => value.into(),
        Err(_) => Value::nil().into(),
    }
}

// ```c
// MRB_API mrb_int mrb_str_strlen(mrb_state *mrb, struct RString *s)
// ```
//
// NOTE: Implemented in C in `mruby-sys/src/mruby-sys/ext.c`.

// ```c
// MRB_API void mrb_str_modify_keep_ascii(mrb_state *mrb, struct RString *s)
// MRB_API void mrb_str_modify(mrb_state *mrb, struct RString *s)
// ```
//
// NOTE: Implemented in C in `mruby-sys/src/mruby-sys/ext.c`.

// ```c
// MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_resize(
    mrb: *mut sys::mrb_state,
    s: sys::mrb_value,
    len: sys::mrb_int,
) -> sys::mrb_value {
    fn try_resize(s: &mut String, len: usize) -> Result<(), TryReserveError> {
        match len.checked_sub(s.len()) {
            Some(0) => {}
            Some(additional) => s.try_reserve(additional)?,
            // If the given length is less than the length of the `String`, truncate.
            None => s.truncate(len),
        }
        Ok(())
    }

    unwrap_interpreter!(mrb, to => guard, or_else = s);
    let mut value = s.into();
    let Ok(mut string) = String::unbox_from_value(&mut value, &mut guard) else {
        return s;
    };
    let Ok(len) = usize::try_from(len) else {
        return s;
    };
    // SAFETY: The string is repacked before any intervening uses of `interp`
    // which means no mruby heap allocations can occur.
    let string_mut = string.as_inner_mut();

    let result = try_resize(string_mut, len);

    let inner = string.take();
    let value = String::box_into_value(inner, value, &mut guard).expect("String reboxing should not fail");

    match result {
        Ok(()) => value.inner(),
        // NOTE: Ideally this code would distinguish between a capacity overflow
        // (string too large) vs an out of memory condition (allocation failure).
        // This is not possible on stable Rust since `TryReserveErrorKind` is
        // unstable.
        Err(_) => {
            // NOTE: This code can't use an `Error` unified exception trait object.
            // Since we're in memory error territory, we're not sure if we can
            // allocate the `Box` it requires.
            let err = NoMemoryError::with_message("out of memory");
            error::raise(guard, err);
        }
    }
}

// ```c
// MRB_API char* mrb_str_to_cstr(mrb_state *mrb, mrb_value str0)
// ```
//
// NOTE: Not implemented.

// ```c
// MRB_API void mrb_str_concat(mrb_state *mrb, mrb_value self, mrb_value other)
// ```
//
// NOTE: Implemented in C in `mruby-sys/src/mruby-sys/ext.c`.
//
// ```
// #[unsafe(no_mangle)]
// unsafe extern "C-unwind" mrb_str_concat(mrb: *mut sys::mrb_state, this: sys::mrb_value, other: sys::mrb_value) {
//     unwrap_interpreter!(mrb, to => guard, or_else = ());
// }
// ```

// ```c
// MRB_API mrb_value mrb_str_plus(mrb_state *mrb, mrb_value a, mrb_value b)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_plus(
    mrb: *mut sys::mrb_state,
    a: sys::mrb_value,
    b: sys::mrb_value,
) -> sys::mrb_value {
    unwrap_interpreter!(mrb, to => guard);
    let mut a = Value::from(a);
    let mut b = Value::from(b);

    let Ok(a) = String::unbox_from_value(&mut a, &mut guard) else {
        return Value::nil().into();
    };
    let Ok(b) = String::unbox_from_value(&mut b, &mut guard) else {
        return Value::nil().into();
    };

    let mut s = String::with_capacity_and_encoding(a.len() + b.len(), a.encoding());

    s.extend_from_slice(a.as_slice());
    s.extend_from_slice(b.as_slice());

    let s = String::alloc_value(s, &mut guard).unwrap_or_default();
    s.into()
}

// ```c
// MRB_API int mrb_str_cmp(mrb_state *mrb, mrb_value str1, mrb_value str2)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_cmp(
    mrb: *mut sys::mrb_state,
    str1: sys::mrb_value,
    str2: sys::mrb_value,
) -> c_int {
    unwrap_interpreter!(mrb, to => guard, or_else = -1);
    let mut a = Value::from(str1);
    let mut b = Value::from(str2);

    let Ok(a) = String::unbox_from_value(&mut a, &mut guard) else {
        return -1;
    };
    let Ok(b) = String::unbox_from_value(&mut b, &mut guard) else {
        return -1;
    };

    a.cmp(&*b) as c_int
}

// ```c
// MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_equal(
    mrb: *mut sys::mrb_state,
    str1: sys::mrb_value,
    str2: sys::mrb_value,
) -> sys::mrb_bool {
    unwrap_interpreter!(mrb, to => guard, or_else = false);
    let mut a = Value::from(str1);
    let mut b = Value::from(str2);

    let Ok(a) = String::unbox_from_value(&mut a, &mut guard) else {
        return false;
    };
    let Ok(b) = String::unbox_from_value(&mut b, &mut guard) else {
        return false;
    };

    *a == *b
}

// ```c
// MRB_API const char* mrb_string_value_ptr(mrb_state *mrb, mrb_value str)
// ```
//
// obsolete: use `RSTRING_PTR()`
//
// NOTE: not implemented

// ```c
// MRB_API mrb_int mrb_string_value_len(mrb_state *mrb, mrb_value ptr)
// ```
//
// obsolete: use `RSTRING_LEN()`
//
// NOTE: not implemented

// ```c
// MRB_API mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_dup(mrb: *mut sys::mrb_state, s: sys::mrb_value) -> sys::mrb_value {
    unwrap_interpreter!(mrb, to => guard);
    let mut string = Value::from(s);
    let basic = sys::mrb_sys_basic_ptr(s).cast::<sys::RString>();
    let class = (*basic).c;

    let Ok(string) = String::unbox_from_value(&mut string, &mut guard) else {
        return Value::nil().into();
    };
    let dup = string.clone();
    let Ok(value) = String::alloc_value(dup, &mut guard) else {
        return Value::nil().into();
    };
    let value = value.inner();

    // dup'd strings keep the class of the source `String`.
    let dup_basic = sys::mrb_sys_basic_ptr(value).cast::<sys::RString>();
    (*dup_basic).c = class;

    value
}

// ```c
// MRB_API mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_substr(
    mrb: *mut sys::mrb_state,
    s: sys::mrb_value,
    beg: sys::mrb_int,
    len: sys::mrb_int,
) -> sys::mrb_value {
    if len < 0 {
        return Value::nil().into();
    }
    unwrap_interpreter!(mrb, to => guard);

    let mut string = Value::from(s);
    let Ok(string) = String::unbox_from_value(&mut string, &mut guard) else {
        return Value::nil().into();
    };

    let offset = if let Ok(offset) = usize::try_from(beg) {
        offset
    } else {
        let offset = beg
            .checked_neg()
            .and_then(|offset| usize::try_from(offset).ok())
            .and_then(|offset| offset.checked_sub(string.len()));
        let Some(offset) = offset else {
            return Value::nil().into();
        };
        offset
    };

    // FIXME: mruby treats this as a character offset, not a byte offset.
    let Some(slice) = string.get(offset..) else {
        return Value::nil().into();
    };
    let substr = String::with_bytes_and_encoding(slice.to_vec(), string.encoding());
    String::alloc_value(substr, &mut guard).unwrap_or_default().into()
}

// ```c
// MRB_API mrb_value mrb_ptr_to_str(mrb_state *mrb, void *p)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_ptr_to_str(mrb: *mut sys::mrb_state, p: *mut c_void) -> sys::mrb_value {
    unwrap_interpreter!(mrb, to => guard);
    let mut s = String::with_capacity(16 + 2);
    let _ignore = write!(s, "{p:p}");
    String::alloc_value(s, &mut guard).unwrap_or_default().into()
}

// ```c
// MRB_API mrb_value mrb_cstr_to_inum(mrb_state *mrb, const char *str, mrb_int base, mrb_bool badcheck)
// ```
//
// NOTE: not implemented.

// ```c
// MRB_API const char* mrb_string_value_cstr(mrb_state *mrb, mrb_value *ptr)
// ```
//
// obsolete: use `RSTRING_CSTR()` or `mrb_string_cstr()`
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_string_value_cstr(
    mrb: *mut sys::mrb_state,
    ptr: *mut sys::mrb_value,
) -> *const c_char {
    unwrap_interpreter!(mrb, to => guard, or_else = ptr::null());
    let mut s = Value::from(*ptr);
    let Ok(mut string) = String::unbox_from_value(&mut s, &mut guard) else {
        return ptr::null();
    };
    if let Some(b'\0') = string.last() {
        return string.as_ptr().cast();
    }
    // SAFETY: The string is repacked before any intervening uses of `interp`
    // which means no mruby heap allocations can occur.
    let string_mut = string.as_inner_mut();
    string_mut.push_byte(b'\0');
    // SAFETY: This raw pointer will not be invalidated since we rebox this
    // `String` into the mruby heap where the GC will keep it alive.
    let cstr = string.as_ptr().cast::<c_char>();

    let inner = string.take();
    String::box_into_value(inner, s, &mut guard).expect("String reboxing should not fail");

    cstr
}

// ```c
// MRB_API const char* mrb_string_cstr(mrb_state *mrb, mrb_value str)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_string_cstr(mrb: *mut sys::mrb_state, s: sys::mrb_value) -> *const c_char {
    unwrap_interpreter!(mrb, to => guard, or_else = ptr::null());
    let mut s = Value::from(s);
    let Ok(mut string) = String::unbox_from_value(&mut s, &mut guard) else {
        return ptr::null();
    };
    if let Some(b'\0') = string.last() {
        return string.as_ptr().cast();
    }
    // SAFETY: The string is repacked before any intervening uses of `interp`
    // which means no mruby heap allocations can occur.
    let string_mut = string.as_inner_mut();
    string_mut.push_byte(b'\0');
    // SAFETY: This raw pointer will not be invalidated since we rebox this
    // `String` into the mruby heap where the GC will keep it alive.
    let cstr = string.as_ptr().cast::<c_char>();

    let inner = string.take();
    String::box_into_value(inner, s, &mut guard).expect("String reboxing should not fail");

    cstr
}

// ```c
// MRB_API mrb_value mrb_str_to_integer(mrb_state *mrb, mrb_value str, mrb_int base, mrb_bool badcheck);
// /* obsolete: use mrb_str_to_integer() */
// #define mrb_str_to_inum(mrb, str, base, badcheck) mrb_str_to_integer(mrb, str, base, badcheck)
// ```
//
// This function converts a numeric string to numeric `mrb_value` with the given base.
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_to_integer(
    mrb: *mut sys::mrb_state,
    s: sys::mrb_value,
    base: sys::mrb_int,
    badcheck: sys::mrb_bool,
) -> sys::mrb_value {
    unwrap_interpreter!(mrb, to => guard);
    let mut s = Value::from(s);
    let Ok(s) = String::unbox_from_value(&mut s, &mut guard) else {
        if badcheck {
            let err = ArgumentError::with_message("not a string");
            error::raise(guard, err);
        }
        return guard.convert(0_i64).into();
    };
    let Ok(s) = str::from_utf8(s.as_slice()) else {
        if badcheck {
            let err = ArgumentError::with_message("invalid number");
            error::raise(guard, err);
        }
        return guard.convert(-1_i64).into();
    };
    let Ok(num) = s.parse::<i64>() else {
        if badcheck {
            let err = ArgumentError::with_message("invalid number");
            error::raise(guard, err);
        }
        return guard.convert(0_i64).into();
    };

    let radix = match u32::try_from(base) {
        Ok(base) if (2..=36).contains(&base) => base,
        Ok(_) | Err(_) => {
            let err = ArgumentError::with_message("illegal radix");
            error::raise(guard, err);
        }
    };

    let mut result = vec![];
    let mut x = num;

    loop {
        let m = u32::try_from(x % base).expect("base must be <= 36, which guarantees the result is in range for u32");
        x /= base;

        // will panic if you use a bad radix (< 2 or > 36).
        result.push(char::from_digit(m, radix).unwrap());
        if x == 0 {
            break;
        }
    }
    let int = result.into_iter().rev().collect::<String>();
    String::alloc_value(int, &mut guard).unwrap_or_default().into()
}

// ```c
// MRB_API double mrb_cstr_to_dbl(mrb_state *mrb, const char *s, mrb_bool badcheck)
// ```
//
// NOTE: not implemented

// ```c
// MRB_API double mrb_str_to_dbl(mrb_state *mrb, mrb_value str, mrb_bool badcheck)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_to_dbl(
    mrb: *mut sys::mrb_state,
    s: sys::mrb_value,
    badcheck: sys::mrb_bool,
) -> c_double {
    unwrap_interpreter!(mrb, to => guard, or_else = 0.0);
    let mut s = Value::from(s);
    let Ok(s) = String::unbox_from_value(&mut s, &mut guard) else {
        if badcheck {
            let err = ArgumentError::with_message("not a string");
            error::raise(guard, err);
        }
        return 0.0;
    };
    let Ok(s) = str::from_utf8(s.as_slice()) else {
        if badcheck {
            let err = ArgumentError::with_message("invalid number");
            error::raise(guard, err);
        }
        return 0.0;
    };
    let Ok(num) = s.parse::<c_double>() else {
        if badcheck {
            let err = ArgumentError::with_message("invalid number");
            error::raise(guard, err);
        }
        return 0.0;
    };
    num
}

// ```c
// MRB_API mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, size_t len)
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_cat(
    mrb: *mut sys::mrb_state,
    s: sys::mrb_value,
    ptr: *const c_char,
    len: usize,
) -> sys::mrb_value {
    unwrap_interpreter!(mrb, to => guard, or_else = s);
    let mut s = Value::from(s);
    let Ok(mut string) = String::unbox_from_value(&mut s, &mut guard) else {
        return s.inner();
    };
    let slice = slice::from_raw_parts(ptr.cast::<u8>(), len);

    // SAFETY: The string is repacked before any intervening uses of
    // `interp` which means no mruby heap allocations can occur.
    let string_mut = string.as_inner_mut();
    string_mut.extend_from_slice(slice);
    let inner = string.take();
    let value = String::box_into_value(inner, s, &mut guard).expect("String reboxing should not fail");

    value.inner()
}

// ```c
// MRB_API mrb_value mrb_str_cat_cstr(mrb_state *mrb, mrb_value str, const char *ptr)
// MRB_API mrb_value mrb_str_cat_str(mrb_state *mrb, mrb_value str, mrb_value str2)
// MRB_API mrb_value mrb_str_append(mrb_state *mrb, mrb_value str1, mrb_value str2)
// ```
//
// NOTE: Implemented in C in `mruby-sys/src/mruby-sys/ext.c`.

// ```c
// MRB_API double mrb_float_read(const char *string, char **endPtr)
// ```
//
// NOTE: impl kept in C.

// ```c
// uint32_t mrb_str_hash(mrb_state *mrb, mrb_value str);
// ```
#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_str_hash(mrb: *mut sys::mrb_state, s: sys::mrb_value) -> u32 {
    unwrap_interpreter!(mrb, to => guard, or_else = 0);
    let mut s = Value::from(s);

    let Ok(s) = String::unbox_from_value(&mut s, &mut guard) else {
        return 0;
    };

    // NOTE: it is necessary to retrieve the interpreter `BuildHasher` second to
    // avoid a duplicate borrow error. `Artichoke::global_build_hasher` requires
    // a shared reference which the previous mutable borrow will coerce to, but
    // the other ordering will not compile.
    let Ok(global_build_hasher) = guard.global_build_hasher() else {
        return 0;
    };

    let hash = global_build_hasher.hash_one(s.as_slice());
    // Grab some bytes from the `u64` to construct a `u32` hash.
    let [one, two, three, four, ..] = hash.to_ne_bytes();
    u32::from_ne_bytes([one, two, three, four])
}

// ```c
// #define FNV_32_PRIME ((uint32_t)0x01000193)
// #define FNV1_32_INIT ((uint32_t)0x811c9dc5)
//
// uint32_t mrb_byte_hash(const uint8_t*, mrb_int);
// uint32_t mrb_byte_hash_step(const uint8_t*, mrb_int, uint32_t);
// ```

const FNV_32_PRIME: Wrapping<u32> = Wrapping(0x0100_0193);
const FNV1_32_INIT: Wrapping<u32> = Wrapping(0x811c_9dc5);

#[unsafe(no_mangle)]
unsafe extern "C-unwind" fn mrb_byte_hash(s: *const u8, len: sys::mrb_int) -> u32 {
    mrb_byte_hash_step(s, len, FNV1_32_INIT)
}

#[unsafe(no_mangle)]
#[expect(
    clippy::cast_possible_truncation,
    clippy::cast_sign_loss,
    reason = "mruby stores sizes as int64_t instead of size_t"
)]
unsafe extern "C-unwind" fn mrb_byte_hash_step(s: *const u8, len: sys::mrb_int, mut hval: Wrapping<u32>) -> u32 {
    let slice = slice::from_raw_parts(s, len as usize);
    // FNV-1 hash each octet in the buffer
    for &byte in slice {
        // multiply by the 32 bit FNV magic prime mod `2^32`
        hval *= FNV_32_PRIME;
        // xor the bottom with the current octet
        hval ^= u32::from(byte);
    }
    // return our new hash value
    hval.0
}

#[unsafe(no_mangle)]
#[expect(
    clippy::cast_possible_truncation,
    clippy::cast_sign_loss,
    reason = "mruby stores sizes as int64_t instead of size_t"
)]
unsafe extern "C-unwind" fn mrb_gc_free_str(mrb: *mut sys::mrb_state, string: *mut sys::RString) {
    let _ = mrb;

    let Some(ptr) = NonNull::<c_char>::new((*string).as_.heap.ptr) else {
        // An allocated but uninitialized string has no backing byte buffer, so
        // there is nothing to free.
        return;
    };
    let length = (*string).as_.heap.len as usize;
    let capacity = (*string).as_.heap.aux.capa as usize;

    // we don't need to free the encoding since `Encoding` is `Copy` and we pack
    // it into the `RString` flags as a `u32`.

    let raw_parts = RawParts {
        ptr: ptr.cast::<u8>().as_mut(),
        length,
        capacity,
    };
    drop(String::from_raw_parts(raw_parts));
}