str_array 1.1.0

Fixed-size `str` and `CStr` types backed by an array
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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

# str_array

![License: Apache-2.0 OR MIT](https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue) [![str_array on crates.io](https://img.shields.io/crates/v/str_array)](https://crates.io/crates/str_array) [![str_array on docs.rs](https://docs.rs/str_array/badge.svg)](https://docs.rs/str_array) [![Source Code Repository](https://img.shields.io/badge/Code-On%20GitHub-blue?logo=GitHub)](https://github.com/kupiakos/str-array) ![Rust Version: 1.64.0](https://img.shields.io/badge/rustc-1.64.0-orange.svg)

<!-- cargo insert-docs crate-into-readme --link-to-latest -->
<!-- crate documentation start -->
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`](https://doc.rust-lang.org/core/ffi/c_str/struct.CStr.html) 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](https://docs.rs/str_array/latest/str_array/struct.CStrArray.html) support

## Examples

```rust
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.

[`CStrArray<N>`]: https://docs.rs/str_array/latest/str_array/struct.CStrArray.html
[`CStrArray`]: https://docs.rs/str_array/latest/str_array/struct.CStrArray.html
[`StrArray<N>`]: https://docs.rs/str_array/latest/str_array/struct.StrArray.html
[`StrArray`]: https://docs.rs/str_array/latest/str_array/struct.StrArray.html
[`cstr_array!`]: https://docs.rs/str_array/latest/str_array/macro.cstr_array.html
[`str_array!`]: https://docs.rs/str_array/latest/str_array/macro.str_array.html

<!-- crate documentation end -->

## License

Licensed under either of the Apache 2.0 or MIT licenses.