abistr 0.1.1

C ABI compatible string types
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

//! # 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*`                             | <code>[abistr::CStrPtr]</code>                | `""`
//! | `const char*`                             | <code>[Option]<[abistr::CStrNonNull]></code>  | [`None`]
//! | `const char* __attribute__((nonnull))`    | <code>[abistr::CStrNonNull]</code>            | ❌ undefined behavior ❌
//! | `char struct_member[128];`                | <code>[abistr::CStrBuf]<\[[u8]; 128\]></code> | <span style="opacity: 33%">N/A</span>
//!
//! # Alternatives
//!
//! <code>\*const [std::os::raw::c_char]</code>
//! * 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.
//!
//! <code>[`std::ffi::CStr`]</code>
//! * 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.
//!
//! <code>[std::ffi::CString]</code> - per [`std::ffi::CStr`], but also:
//! * Pro:  Dynamically allocated!
//! * Con:  Dynamically allocated.
//!
//! [DST]:      https://doc.rust-lang.org/nomicon/exotic-sizes.html#dynamically-sized-types-dsts

#![warn(missing_docs)]

#[doc(hidden)] pub extern crate abistr_macros;

#[cfg(doc)] use crate as abistr;
#[cfg(doc)] use std::ptr::*;

#[macro_use] mod macros;

mod as_traits;                          pub use as_traits::*;
mod buffers;                            pub use buffers::*;
mod errors;                             pub use errors::*;
mod fmt;
mod pointers;                           pub use pointers::*;
mod try_into_as_traits;                 pub use try_into_as_traits::*;