https://github.com/rreverser/cow-utils-rs
Copy-on-write string utilities for Rust
https://github.com/rreverser/cow-utils-rs
copy-on-write rust rust-lang rustlang strings strings-manipulation
Last synced: 11 months ago
JSON representation
Copy-on-write string utilities for Rust
- Host: GitHub
- URL: https://github.com/rreverser/cow-utils-rs
- Owner: RReverser
- License: mit
- Created: 2020-02-16T17:02:59.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-04-11T18:34:59.000Z (almost 2 years ago)
- Last Synced: 2024-10-29T22:30:30.202Z (over 1 year ago)
- Topics: copy-on-write, rust, rust-lang, rustlang, strings, strings-manipulation
- Language: Rust
- Homepage: https://docs.rs/cow-utils/latest/cow_utils/trait.CowUtils.html
- Size: 15.6 KB
- Stars: 158
- Watchers: 3
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Copy-on-write string utils for Rust
[](https://docs.rs/cow-utils/latest/cow_utils/trait.CowUtils.html)
[](LICENSE)
Some [`str`](https://doc.rust-lang.org/std/primitive.str.html) methods
perform destructive transformations and so they allocate, copy into and
return a new
[`String`](https://doc.rust-lang.org/std/string/struct.String.html) even
when no modification is necessary.
This crate provides a helper trait `CowUtils` with drop-in variants of
such methods, which behave in the same way, but avoid extra copies and
allocations when no modification is necessary.
For now it's only implemented for `&str` and returns
[`std::borrow::Cow`](https://doc.rust-lang.org/std/borrow/enum.Cow.html),
but in the future might be extended to other types where even more
efficient handling is possible (e.g. in-place modifications on mutable
strings).
## Performance
The primary motivation for this crate was ability to perform zero-alloc replacements when no match is found, so showing results only for `.replace` vs `.cow_replace` for now.
The actual results will vary depending on the inputs, but here is a taster based on `"a".repeat(40)` as an input and various modes (nothing matched, everything matched and replaced, everything matched from the start and deleted):
| params | .replace (ns) | .cow_replace (ns) | difference (%) |
|------------|---------------|-------------------|----------------|
| ("a", "") | 408.59 | 290.27 | -29 |
| ("b", "c") | 98.78 | 54.00 | -45 |
| ("a", "b") | 985.99 | 1,000.70 | +1 |
## Usage
First, you need to import `CowUtils` into the scope:
```rust
use cow_utils::CowUtils;
```
Then you can start invoking following `.cow_`-prefixed methods on
strings instead of the regular ones:
- `.cow_replace` instead of [`str::replace`](https://doc.rust-lang.org/std/primitive.str.html#method.replace)
- `.cow_replacen` instead of [`str::replacen`](https://doc.rust-lang.org/std/primitive.str.html#method.replacen)
- `.cow_to_ascii_lowercase` instead of [`str::to_ascii_lowercase`](https://doc.rust-lang.org/std/primitive.str.html#method.to_ascii_lowercase)
- `.cow_to_ascii_uppercase` instead of [`str::to_ascii_uppercase`](https://doc.rust-lang.org/std/primitive.str.html#method.to_ascii_uppercase)
- `.cow_to_lowercase` instead of [`str::to_lowercase`](https://doc.rust-lang.org/std/primitive.str.html#method.to_lowercase)
- `.cow_to_uppercase` instead of [`str::to_uppercase`](https://doc.rust-lang.org/std/primitive.str.html#method.to_uppercase)
Check out [the docs](https://docs.rs/cow-utils/latest/cow_utils/trait.CowUtils.html) for detailed examples.