Adding `str_array` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add str_array

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

str_array = "1.1.0"

The str_array library will be automatically available globally. Read the str_array library documentation.

Back to the crate overview.

Readme

str_array

Provides fixed-size string types StrArray<N> and CStrArray<N>.

StrArray serves as the str equivalent of [u8; N]. It provides a Deref to &str and ensures the UTF-8 invariant is always upheld, but has a size known at compile time.

This is useful in some situations:

Resource-constrained no_std and no-alloc environments.
Defining UTF-8 strings directly in a stack array or static.
Types or parameters that require &str of some fixed length.

The str_array! macro provides a compile-time-checked way to build StrArray values from string literals and constants.

Similarly, CStrArray and cstr_array! can construct a nul-terminated CStr safely on the stack.

Features

no_std support - disable default features to use without std
Optional alloc and std features
Full const support
C string support

Examples

use str_array::{str_array, StrArray};

// Create from a constant using the macro. The length is inferred.
let s1 = str_array!("hello");
assert_eq!(s1.len(), 5);
assert_eq!(s1, "hello");
assert!(matches!(s1.into_bytes(), [b'h', b'e', b'l', b'l', b'o']));

// Or create from a runtime &str with an length check.
let s2: StrArray<12> = StrArray::new(&format!("{s1}, world")).unwrap();
assert_eq!(core::mem::size_of_val(&s2), 12);
assert_eq!(s2, "hello, world");

// Or create from bytes with a UTF-8 check.
let s3 = StrArray::from_utf8(
    b"\xF0\x9F\xA4\x8C\xF0\x9F\x8F\xBC"
).unwrap();
assert_eq!(s3, "🤌🏼");

// Or define an item with an inferred length.
str_array! {
    static S4 = "Georgia";
}
assert_eq!(S4.len(), 7);

Rust feature detection

This crate has a low Minimum Supported Rust Version (MSRV), and it achieves that through cfg values that are enabled in the build.rs based on the presence of existing features. This uses the autocfg library.

The build.rs can be skipped for alternate build systems, but be sure to enable the appropriate cfg values based on your version of rustc. Those are:

cfg(has_core_error) is enabled when core::error::Error is present (stable since Rust 1.81). If it's enabled, then the error types in this crate implement Error with any set of features. If it's disabled, they only implement the Error trait when the std feature is enabled.
cfg(has_const_mut) is enabled when &mut is usable in const (stable since Rust 1.83). It adds const to various fn that use &mut in this crate.

License

Licensed under either of the Apache 2.0 or MIT licenses.

Adding str_array library as a dependency

Adding `str_array` library as a dependency