Enum CArrayString

Source

pub enum CArrayString<const N: usize> {
    Stack(ArrayString<N>),
    Heap(CString),
}

Variants§

§

Stack(ArrayString<N>)

§

Heap(CString)

Implementations§

Source §

impl<const N: usize> CArrayString<N>

A C-compatible string type that can be stored on the stack or heap.

CArrayString<N> provides a unified abstraction over two storage strategies:

Stack-allocated: Uses ArrayString<N> for small strings that fit into a fixed-size buffer. This avoids heap allocation and is very efficient.
Heap-allocated: Uses CString when the string exceeds the stack buffer, ensuring the string is always valid and null-terminated.

This type guarantees:

[as_ptr] always returns a valid, null-terminated C string pointer for the lifetime of self.
[as_c_str] always returns a valid CStr reference.

§Stack vs Heap Behavior

When creating a CArrayString via [new], the string is first attempted to be stored on the stack. If it does not fit, it falls back to a heap allocation:

┌───────────────┐
│ Stack Buffer  │  (ArrayString<N>)
└───────────────┘
      │ fits
      └─> use stack

      │ does not fit
      └─> allocate heap (CString)

§Performance Considerations

Small strings that fit in the stack buffer avoid heap allocations and are faster.
Large strings trigger heap allocation, which may be slower and use more memory.
Prefer choosing N large enough for your common use case to minimize heap fallbacks.

§Examples

use std::ffi::CStr;
 
use stack_cstr::CArrayString;

// Small string fits on stack
let stack_str = CArrayString::<16>::new(format_args!("hello"));
assert!(matches!(stack_str, CArrayString::Stack(_)));

// Large string falls back to heap
let heap_str = CArrayString::<4>::new(format_args!("this is too long"));
assert!(matches!(heap_str, CArrayString::Heap(_)));

// Accessing as CStr
let cstr: &CStr = heap_str.as_c_str();
assert_eq!(cstr.to_str().unwrap(), "this is too long");

// Raw pointer for FFI
let ptr = stack_str.as_ptr();
unsafe {
    assert_eq!(CStr::from_ptr(ptr).to_str().unwrap(), "hello");
}

Source

pub fn new(fmt: Arguments<'_>) -> CArrayString<N>

Creates a new C-compatible string using format_args!.

Attempts to store the formatted string in a stack buffer of size N. Falls back to a heap allocation if the string does not fit.

§Parameters

fmt: The formatted arguments, typically produced by format_args!.

§Returns

A CArrayString<N> containing the formatted string.

§Notes

If the stack buffer overflows or writing fails, the string is stored on the heap.

§Examples

use stack_cstr::CArrayString;

let s = CArrayString::<8>::new(format_args!("hi {}!", "you"));
assert!(s.as_c_str().to_str().unwrap().starts_with("hi"));

Source

pub fn as_ptr(&self) -> *const c_char

Returns a raw pointer to the null-terminated C string.

The pointer is valid for the lifetime of self. This is useful for passing the string to C APIs via FFI.

§Examples

use std::ffi::CStr;
 
use stack_cstr::CArrayString;

let s = CArrayString::<8>::new(format_args!("hello"));
let ptr = s.as_ptr();
unsafe {
    assert_eq!(CStr::from_ptr(ptr).to_str().unwrap(), "hello");
}

Source

pub fn as_c_str(&self) -> &CStr

Returns a reference to the underlying CStr.

Provides safe access to the string as a &CStr without exposing the underlying storage strategy.

§Examples

use std::ffi::CStr;
 
use stack_cstr::CArrayString;

let s = CArrayString::<8>::new(format_args!("hello"));
let cstr: &CStr = s.as_c_str();
assert_eq!(cstr.to_str().unwrap(), "hello");