Expand description
§C ABI compatible string types
While rust’s stdlib has some good basic options for C-string support, it has some glaring issues when dealing with C functions that accept or return arrays of structures containing C-string pointers or arrays. This crate aims to help fill that niche with safe, fast, ergonomic alternatives.
C type | ABI compatible Rust | null |
---|---|---|
const char* | abistr::CStrPtr | "" |
const char* | Option<abistr::CStrNonNull> | None |
const char* __attribute__((nonnull)) | abistr::CStrNonNull | ❌ undefined behavior ❌ |
char struct_member[128]; | abistr::CStrBuf<[u8; 128]> | N/A |
§Alternatives
*const std::os::raw::c_char
- Pro: Can’t get any simpler for basic interop!
- Con: Requires
unsafe
to so much as shake a stick at. - Con: Easy to create undefined behavior by messing up edge cases involving null.
- Con: Easy to create undefined behavior by creating dangling poniters and other lifetime issues (raw pointers have no lifetimes.)
- Con: Fairly unergonomic to use directly.
- Pro: Relatively safe!
- Con: Immediate
O(n)
length check on construction, even if you never use the string. - Con: Being a DST (at least at the time of writing / rust 1.48.0), this isn’t ABI compatible with
*const c_char
and thus cannot be embedded in zero-conversion structures.
std::ffi::CString
- per std::ffi::CStr
, but also:
- Pro: Dynamically allocated!
- Con: Dynamically allocated.
Macros§
- cstr
- Create a
&CStrNonNull
literal at compile time
Structs§
- Buffer
TooSmall Error - The buffer in question is too small to contain the string in question
- CStrBuf
CStrBuf<[u8; 128]>
is ABI compatible with[c_char; 128]
.- CStr
NonNull Option<CStrNonNull>
is ABI compatible with*const c_char
.- CStrPtr
CStrPtr
is ABI compatible with*const c_char
.null()
is treated as an empty string.- NotNul
Terminated Error - The string in question contains no terminal
\0