rocstr 0.5.1

An immutable fixed capacity stack based generic copy string
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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

<!-- cargo-sync-rdme title [[ -->
# rocstr
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme badge [[ -->
[![crates.io](https://img.shields.io/crates/v/rocstr.svg?logo=rust&style=for-the-badge)](https://crates.io/crates/rocstr)
[![docs.rs](https://img.shields.io/docsrs/rocstr.svg?logo=docs.rs&style=for-the-badge)](https://docs.rs/rocstr)
[![Rust: ^1.51](https://img.shields.io/badge/rust-^1.51-93450a.svg?logo=rust&style=for-the-badge)](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)
[![Codecov](https://img.shields.io/codecov/c/github/OuiCloud/rocstr.svg?label=codecov&logo=codecov&style=for-the-badge)](https://codecov.io/gh/OuiCloud/rocstr)
[![GitHub Actions: Unit Tests](https://img.shields.io/github/actions/workflow/status/OuiCloud/rocstr/tests.yml.svg?label=Unit+Tests&logo=github&style=for-the-badge)](https://github.com/OuiCloud/rocstr/actions/workflows/tests.yml)
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme rustdoc [[ -->
## RocStr

### Overview

Rust OuiCloud Str

An immutable fixed capacity stack based generic copy string.

The RocStr is a string backed by a fixed size array.

It keeps track of its length, and is parameterized by SIZE for the maximum capacity.

SIZE is of type usize but is range limited to u32::MAX; attempting to create RocStr with larger capacity will panic.

### Usage

#### Basic usage

````bash
cargo install rocstr
````

````rust

pub struct Customer {
    id: u32,
    first_name: RocStr<64>,
    last_name: RocStr<64>,
}

let alice = Customer {id: 1, first_name: "Alice".into(), last_name: "Adams".into()};
let bob = Customer {id: 2, first_name: "Bob".into(), last_name: "Bennett".into()};

let alice_name = alice.first_name + " " + alice.last_name;
let bob_name = bob.first_name + " " + bob.last_name;

assert_eq!(alice_name, "Alice Adams");
assert_eq!(bob_name, "Bob Bennett");
````

### Motivation

Yet another copy string type for Rust.

But, this one is particularly shaped to ease async programming :

* it is owned which means no lifetime management, unlike Rust standard `&str`
* it implements `Copy` trait, unlike Rust standard `String`, which means fast and implicit copy
* it exposed an immutable API, no interior mutability, which means thread safety

More over, it was designed to cover web full stack programming range, from full featured back-end server to WASM front-end.

|Library|owned|impl Copy|immut. API|no std|no unsafe|Note|
|-------|:---:|:-------:|:--------:|:----:|:-------:|----|
|core::str|❌|❌|❌|✅|➖|core immutable string|
|std::String|✅|❌|❌|❌|➖|std string|
|imstr::ImString|✅|❌|❌|❌|❌|use `Arc<String>` under the hood|
|smol_str::SmolStr|✅|❌|❌|✅|❌|rust-analyzer string|
|bytestring::ByteString|✅|❌|❌|✅|❌|actix string|
|flexstr::FlexStr|✅|❌|❌|✅|❌||
|copstr::Str|✅|✅|❌|❌|❌||
|copystr::sXX|✅|✅|❌|❌|✅|old impl before const generic|
|arraystring::ArrayString|✅|✅|❌|✅|❌|old impl before const generic|
|tinystr::TinyAsciiStr|✅|✅|❌|✅|❌|ascii only|
|arrayvec::ArrayString|✅|✅|❌|✅|❌|unfortunately, it uses unsafe|
|rocstr::RocStr|✅|✅|✅|✅|✅|this crate|

### Use cases

The target use case is web full stack programming :

* mapping database strings with bound size (char(SIZE), varchar(SIZE), etc…)
* easing async functional programming (owned, impl Copy, immutability)

### Supported Rust Versions

The RocStr relies on Simple Const Generics introduced in Rust 1.51.

The current MSRV is 1.51.

### Safety

This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in 100% Safe Rust.

### Crate Features

RocStr is built with these features enabled by default:

* std enables functionality dependent on the std lib

Optionally, the following dependencies can be enabled:

* serde enables serde Serialize/Deserialize support
* postgres enables PostgreSql type support

RocStr supports no_std mode (enabled via default-features = false)

### License

RocStr is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT, and COPYRIGHT for details.
<!-- cargo-sync-rdme ]] -->