inline_flexstr 0.1.5

A simple to use, copy/clone-efficient inline string type for Rust
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

# inline_flexstr

[![Crate](https://img.shields.io/crates/v/inline_flexstr)](https://crates.io/crates/inline_flexstr)
[![Docs](https://docs.rs/inline_flexstr/badge.svg)](https://docs.rs/inline_flexstr)
[![Build](https://github.com/nu11ptr/flexstr/workflows/CI/badge.svg)](https://github.com/nu11ptr/flexstr/actions)
[![codecov](https://codecov.io/gh/nu11ptr/flexstr/branch/master/graph/badge.svg?token=yUZ8v2tKPd)](https://codecov.io/gh/nu11ptr/flexstr)

A simple to use, copy/clone-efficient inline string type for Rust

## Overview

A fast inline string crate. Essentially it never allocates on the heap, but is limited currently to strings that are 2 bytes less than 3 machine words in length (10 bytes on 32-bit, 22 bytes on 64-bit). It is generic over all the Rust string types (`str`, `CStr`, `OsStr`, `Path`, `[u8]`).

## Features

* Implements `Copy`
* O(1) copy/clone
* Mutable
* Same size a a `String` (3 words wide, even inside an `Option`)
* No external dependencies
    * NOTE: `serde`/`sqlx` optional for serialization/deserialization/encode/decode
* Optional `no_std`
* Optional `safe` feature that forbids any `unsafe` usage
    * NOTE: This does induce a performance penalty, as would be expected
    * NOTE 2: `OsStr`/`Path` support on Windows requires at least one unsafe call (`win_min_unsafe` feature).
* Handles all Rust string types (`str`, `CStr`, `OsStr`, `Path`, `[u8]`)

## Cargo Features

* **safe** = Use all safe functions and add `forbid(unsafe_code)` (performance penalty)
* **sqlx** = Enable sqlx encode/decode/type support
* **sqlx_pg_arrays** = Enable sqlx Postgres array support (implies `sqlx` feature)
* **std** = Use `std` (default)
* **serde** = add `serde` dependency and adds serialization/deserialization
* **win_min_unsafe** = enables the minimum necessary unsafe code on Windows to support `OsStr`/`Path`. No other string types or operating systems are impacted (implies `safe` feature).
    * NOTE: The code will refuse to compile if this is not specified when ALL the following conditions are true:
        * The `safe` feature is enabled
        * The `osstr` and/or `path` feature(s) are enabled
        * Compiling for Windows

### String Type Features:
* **str** = Enable `str`-based strings (default)
* **bytes** = Enable byte-based strings (`[u8]`)
* **cstr** = Enable `CStr`-based strings
* **osstr** = Enable `OsStr`-based strings
* **path** = Enable `Path`-based strings (implies `osstr` feature)

## Example

```rust
use inline_flexstr::*;

let hello: InlineStr = "hello".try_into().expect("string too long");
let world: InlineCStr = c"world!".try_into().expect("string too long");

println!("{hello} {world:?}");
```

## Performance

In general, it performs quite well given that it is mostly just a thin wrapper over the stdlib. See the [benchmarks](../benchmarks/README.md) page for more details.

## AI Usage

The code was written by hand with care (although AI tab completion was used). Any contributions should be completely understood by the contributor, whether AI assisted or not.

The tests on the otherhand were 90%+ generated by AI under my instruction. I've done a cursory review for sanity, but they need more work. Volunteers welcome.

## Status

This is currently experimental, however, I will be using this at a startup in production code, so it will become production ready at some point.

## Contributions

Contributions are welcome so long as they align to my vision for this crate. Currently, it does most of what I want it to do (outside of string construction and mutation, but I'm not ready to start on that yet).

## License

This project is licensed optionally under either:

* Apache License, Version 2.0, (LICENSE-APACHE
  or <https://www.apache.org/licenses/LICENSE-2.0>)
* MIT license (LICENSE-MIT or <https://opensource.org/licenses/MIT>)