Struct CStringArray 

pub struct CStringArray { /* private fields */ }

Safe wrapper for passing string arrays to C FFI as char**.

This structure provides a safe abstraction over the common C pattern of null-terminated arrays of strings (char**), often used for command-line arguments (argv).

Memory Safety

• Guarantees proper memory layout compatible with C’s char**
• Automatically manages lifetime of all C strings
• Ensures null-termination of the pointer array
• Prevents dangling pointers through RAII
• Zero-copy when constructed from Vec<CString>

Example

use std::ffi::c_char;

use cstring_array::CStringArray;

let args = vec![
    "program".to_string(),
    "--verbose".to_string(),
    "file.txt".to_string(),
];
let array = CStringArray::new(args).unwrap();

// Safe to pass to C FFI
let ptr: *const *const c_char = array.as_ptr();
assert_eq!(array.len(), 3);

Implementations

impl CStringArray

pub fn new(strings: Vec<String>) -> Result<Self, CStringArrayError>

Creates a new CStringArray from a vector of strings.

Arguments

• strings - Vector of strings to convert into C-compatible format

Errors

Returns CStringArrayError::NulError if any string contains an interior null byte. Returns CStringArrayError::EmptyArray if the input vector is empty.

Example

use cstring_array::CStringArray;

let args = vec!["foo".to_string(), "bar".to_string()];
let array = CStringArray::new(args).unwrap();
assert_eq!(array.len(), 2);

pub fn from_cstrings(strings: Vec<CString>) -> Result<Self, CStringArrayError>

Creates a new CStringArray from a vector of CStrings (zero-copy).

This is the most efficient constructor as it takes ownership of already-allocated CString instances without re-allocation.

Arguments

• strings - Vector of CString instances

Errors

Returns CStringArrayError::EmptyArray if the input vector is empty.

Example

use std::ffi::CString;

use cstring_array::CStringArray;

let cstrings = vec![
    CString::new("hello").unwrap(),
    CString::new("world").unwrap(),
];
let array = CStringArray::from_cstrings(cstrings).unwrap();
assert_eq!(array.len(), 2);

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

Returns a pointer suitable for passing to C functions expecting char**.

The returned pointer is valid for the lifetime of this CStringArray. The pointer array is null-terminated as required by C conventions.

Safety

The caller must ensure that:

• The pointer is not used after this CStringArray is dropped
• The pointer is not used to modify the strings (use as_mut_ptr for that)

Example

use std::ffi::c_char;

use cstring_array::CStringArray;

let array = CStringArray::new(vec!["test".to_string()]).unwrap();
let ptr: *const *const c_char = array.as_ptr();

// Safe to pass to C FFI functions like execve, etc.

pub fn as_mut_ptr(&mut self) -> *mut *const c_char

Returns a mutable pointer suitable for C functions expecting char**.

Safety

The caller must ensure that:

• The pointer is not used after this CStringArray is dropped
• C code does not replace pointers in the array (undefined behavior)
• C code only modifies string contents, not pointer values

Example

use std::ffi::c_char;

use cstring_array::CStringArray;

let mut array = CStringArray::new(vec!["test".to_string()]).unwrap();
let ptr: *mut *const c_char = array.as_mut_ptr();

pub fn len(&self) -> usize

Returns the number of strings in the array.

This count does not include the null terminator.

Example

use cstring_array::CStringArray;

let array = CStringArray::new(vec!["a".to_string(), "b".to_string()]).unwrap();
assert_eq!(array.len(), 2);

pub fn is_empty(&self) -> bool

Returns true if the array contains no strings.

Note: Due to the constructor constraints, this will always return false for successfully constructed instances, but is provided for completeness.

Example

use cstring_array::CStringArray;

let array = CStringArray::new(vec!["x".to_string()]).unwrap();
assert!(!array.is_empty());

pub fn get(&self, index: usize) -> Option<&CString>

Returns a reference to the underlying CString at the specified index.

Arguments

• index - The index of the string to retrieve

Returns

Returns Some(&CString) if the index is valid, None otherwise.

Example

use cstring_array::CStringArray;

let array = CStringArray::new(vec!["first".to_string(), "second".to_string()]).unwrap();
assert_eq!(array.get(0).unwrap().to_str().unwrap(), "first");
assert_eq!(array.get(1).unwrap().to_str().unwrap(), "second");
assert!(array.get(2).is_none());

pub fn iter(&self) -> Iter<'_, CString>

Returns an iterator over the CString references.

Example

use cstring_array::CStringArray;

let array = CStringArray::new(vec!["a".to_string(), "b".to_string()]).unwrap();
let strings: Vec<_> = array.iter().collect();
assert_eq!(strings.len(), 2);

pub fn as_slice(&self) -> &[CString]

Returns a slice of the underlying CString array.

Example

use cstring_array::CStringArray;

let array = CStringArray::new(vec!["a".to_string()]).unwrap();
let slice = array.as_slice();
assert_eq!(slice.len(), 1);

pub fn into_strings(self) -> Vec<CString>

Consumes the array and returns the underlying vector of CStrings.

Example

use cstring_array::CStringArray;

let array = CStringArray::new(vec!["test".to_string()]).unwrap();
let strings = array.into_strings();
assert_eq!(strings.len(), 1);

Trait Implementations

impl AsRef<[CString]> for CStringArray

fn as_ref(&self) -> &[CString]

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for CStringArray

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CStringArray

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for CStringArray

fn drop(&mut self)

Executes the destructor for this type.

impl FromIterator<CString> for CStringArray

fn from_iter<I: IntoIterator<Item = CString>>(iter: I) -> Self

Creates a value from an iterator.

impl FromIterator<String> for CStringArray

fn from_iter<I: IntoIterator<Item = String>>(iter: I) -> Self

Creates a value from an iterator.

impl Hash for CStringArray

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Index<usize> for CStringArray

type Output = CString

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<'a> IntoIterator for &'a CStringArray

type Item = &'a CString

The type of the elements being iterated over.

type IntoIter = Iter<'a, CString>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for CStringArray

type Item = CString

The type of the elements being iterated over.

type IntoIter = IntoIter<CString>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for CStringArray

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const N: usize> TryFrom<[&str; N]> for CStringArray

fn try_from(strings: [&str; N]) -> Result<Self, Self::Error>

Converts an array of string slices into a CStringArray.

Errors

Returns an error if any string contains an interior null byte or if the array is empty.

Example

use std::convert::TryFrom;

use cstring_array::CStringArray;

let strings = ["hello", "world"];
let array = CStringArray::try_from(strings).unwrap();
assert_eq!(array.len(), 2);

type Error = CStringArrayError

The type returned in the event of a conversion error.

impl<const N: usize> TryFrom<[String; N]> for CStringArray

fn try_from(strings: [String; N]) -> Result<Self, Self::Error>

Converts an array of Strings into a CStringArray.

Errors

Returns an error if any string contains an interior null byte or if the array is empty.

Example

use std::convert::TryFrom;

use cstring_array::CStringArray;

let strings = ["hello".to_string(), "world".to_string()];
let array = CStringArray::try_from(strings).unwrap();
assert_eq!(array.len(), 2);

type Error = CStringArrayError

The type returned in the event of a conversion error.

impl TryFrom<Vec<&str>> for CStringArray

fn try_from(strings: Vec<&str>) -> Result<Self, Self::Error>

Converts a Vec<&str> into a CStringArray.

Errors

Returns an error if any string contains an interior null byte or if the vector is empty.

Example

use std::convert::TryFrom;

use cstring_array::CStringArray;

let strings = vec!["hello", "world"];
let array = CStringArray::try_from(strings).unwrap();
assert_eq!(array.len(), 2);

type Error = CStringArrayError

The type returned in the event of a conversion error.

impl TryFrom<Vec<CString>> for CStringArray

fn try_from(strings: Vec<CString>) -> Result<Self, Self::Error>

Converts a Vec<CString> into a CStringArray (zero-copy).

Errors

Returns an error if the vector is empty.

Example

use std::{convert::TryFrom, ffi::CString};

use cstring_array::CStringArray;

let cstrings = vec![
    CString::new("hello").unwrap(),
    CString::new("world").unwrap(),
];
let array = CStringArray::try_from(cstrings).unwrap();
assert_eq!(array.len(), 2);

type Error = CStringArrayError

The type returned in the event of a conversion error.

impl TryFrom<Vec<String>> for CStringArray

fn try_from(strings: Vec<String>) -> Result<Self, Self::Error>

Converts a Vec<String> into a CStringArray.

Errors

Returns an error if any string contains an interior null byte or if the vector is empty.

Example

use std::convert::TryFrom;

use cstring_array::CStringArray;

let strings = vec!["hello".to_string(), "world".to_string()];
let array = CStringArray::try_from(strings).unwrap();
assert_eq!(array.len(), 2);

type Error = CStringArrayError

The type returned in the event of a conversion error.

impl Eq for CStringArray

impl Send for CStringArray

impl Sync for CStringArray