feat: Created the stack-cstr library for efficient C-style string generation.

- Implemented stack-based C string generation with support for configurable stack buffer sizes.
- Provided automatic fallback to heap allocation to handle strings that exceed the stack buffer size.
- Supported `format_args!`-style formatting.
- Provided a simple `cstr!()` macro interface for ease of use.
- Implemented the `CStrLike` trait to simplify FFI usage.
- Added unit tests to ensure correct functionality.

Author: fxdmhtt

Cargo.lock

@@ -0,0 +1,14 @@
+[package]
+name = "stack-cstr"
+version = "0.1.0"
+edition = "2024"
+authors = ["Junkang Yuan <[email protected]>"]
+description = "High-performance stack-to-heap C string creation for Rust with FFI support"
+repository = "https://github.com/fxdmhtt/stack-cstr"
+license = "GPL-2.0"
+readme = "README.md"
+keywords = ["CStr", "CString", "FFI"]
+categories = ["ffi", "formatting", "string"]
+
+[dependencies]
+arrayvec = "0.7.6"

Cargo.toml

@@ -0,0 +1,14 @@
+# stack_cstr
+
+`stack_cstr` is a high-performance Rust library for creating C-style strings (CStr/CString) efficiently.  
+It tries to write the formatted string into a stack buffer first, and if the string is too long, it falls back to heap allocation.  
+The final result is a safe C string that can be passed to FFI functions.
+
+## Features
+
+- Stack buffer attempt with configurable sizes
+- Automatic heap fallback for long strings
+- Supports `format_args!` style formatting
+- Returns `Box<dyn CStrLike>` for easy FFI usage
+- Simple macro interface: `cstr!()`
+- Extensible stack sizes

README.md

@@ -0,0 +1,31 @@
+use std::ffi::{CStr, CString, c_char};
+
+use crate::CStrLike;
+
+pub struct CStrHeap {
+    cstr: CString,
+}
+
+impl CStrHeap {
+    pub fn new(s: CString) -> Self {
+        Self { cstr: s }
+    }
+
+    pub fn as_ptr(&self) -> *const c_char {
+        self.cstr.as_ptr()
+    }
+
+    pub fn as_cstr(&self) -> &CStr {
+        self.cstr.as_c_str()
+    }
+}
+
+impl CStrLike for CStrHeap {
+    fn as_ptr(&self) -> *const c_char {
+        self.as_ptr()
+    }
+
+    fn as_cstr(&self) -> &CStr {
+        self.as_cstr()
+    }
+}

src/cstr_heap.rs

@@ -0,0 +1,6 @@
+use std::ffi::{CStr, c_char};
+
+pub trait CStrLike {
+    fn as_ptr(&self) -> *const c_char;
+    fn as_cstr(&self) -> &CStr;
+}

src/cstr_like.rs

@@ -0,0 +1,49 @@
+use std::ffi::{CStr, c_char};
+
+use arrayvec::ArrayString;
+
+use crate::CStrLike;
+
+pub struct CStrStack<const N: usize> {
+    buf: [u8; N],
+    len: usize,
+}
+
+impl<const N: usize> CStrStack<N> {
+    pub fn new(fmt: std::fmt::Arguments) -> Result<CStrStack<N>, &'static str> {
+        let mut buf: ArrayString<N> = ArrayString::new();
+        std::fmt::write(&mut buf, fmt).map_err(|_| "format failed")?;
+
+        let bytes = buf.as_bytes();
+        if bytes.len() + 1 > N {
+            return Err("stack buffer overflow");
+        }
+
+        let mut c_buf: [u8; N] = [0; N];
+        c_buf[..bytes.len()].copy_from_slice(bytes);
+        c_buf[bytes.len()] = 0;
+
+        Ok(CStrStack {
+            buf: c_buf,
+            len: bytes.len(),
+        })
+    }
+
+    pub fn as_ptr(&self) -> *const c_char {
+        self.buf.as_ptr() as *const c_char
+    }
+
+    pub fn as_cstr(&self) -> &CStr {
+        unsafe { CStr::from_bytes_with_nul_unchecked(&self.buf[..self.len + 1]) }
+    }
+}
+
+impl<const N: usize> CStrLike for CStrStack<N> {
+    fn as_ptr(&self) -> *const c_char {
+        self.as_ptr()
+    }
+
+    fn as_cstr(&self) -> &CStr {
+        self.as_cstr()
+    }
+}

src/cstr_stack.rs

@@ -0,0 +1,8 @@
+pub mod cstr_heap;
+pub mod cstr_like;
+pub mod cstr_stack;
+pub mod macros;
+
+pub use cstr_heap::CStrHeap;
+pub use cstr_like::CStrLike;
+pub use cstr_stack::CStrStack;

src/lib.rs

@@ -0,0 +1,21 @@
+#[macro_export]
+macro_rules! cstr {
+    ([$($size:expr),*], $($args:tt)*) => {{
+        let args = format_args!($($args)*);
+
+        let result: Box<dyn $crate::CStrLike> = if false { unreachable!() }
+        $(
+            else if let Ok(s) = $crate::CStrStack::<$size>::new(args) {
+                Box::new(s)
+            }
+        )*
+        else {
+            Box::new($crate::CStrHeap::new(std::ffi::CString::new(format!($($args)*)).unwrap()))
+        };
+
+        result
+    }};
+    ($($args:tt)*) => {
+        cstr!([32, 128], $($args)*)
+    };
+}

src/macros.rs

@@ -0,0 +1,33 @@
+use std::ffi::CStr;
+
+use stack_cstr::cstr;
+
+#[test]
+fn test_cstr_macro() {
+    let c1 = cstr!("hi");
+
+    let c2 = "x".repeat(100);
+    let c2 = cstr!("{}", c2);
+
+    let c3 = "x".repeat(300);
+    let c3 = cstr!("{}", c3);
+
+    let c4 = cstr!([16, 64, 128], "explicit sizes");
+
+    assert_eq!(
+        unsafe { CStr::from_ptr(c1.as_ptr()).to_str().unwrap() },
+        "hi"
+    );
+    assert_eq!(
+        unsafe { CStr::from_ptr(c2.as_ptr()).to_str().unwrap() },
+        &"x".repeat(100)
+    );
+    assert_eq!(
+        unsafe { CStr::from_ptr(c3.as_ptr()).to_str().unwrap() },
+        &"x".repeat(300)
+    );
+    assert_eq!(
+        unsafe { CStr::from_ptr(c4.as_ptr()).to_str().unwrap() },
+        "explicit sizes"
+    );
+}