Skip to content

Commit

Permalink
chore: improve README
Browse files Browse the repository at this point in the history
  • Loading branch information
polazarus committed Nov 10, 2024
1 parent 158b223 commit 2ee9e8e
Showing 1 changed file with 34 additions and 5 deletions.
39 changes: 34 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,19 +34,31 @@ let chars = user.chars().count(); // "inherits" `&str` methods

## ✏️ Features

- `std` (default): uses `std` rather than `core` and `alloc`, and also provides more trait implementations (for comparison, conversions, and errors)
- `std` (default): uses `std` rather than `core` and `alloc`, and also provides more trait implementations (for comparison and conversions)
- `serde`: provides serialization/deserialization support with `serde` crate
- `unstable`: exposes internal `Backend` trait that may change at any moment

## ☣️ Safety of `hipstr`

This crate uses `unsafe` extensively. 🤷
This crate makes extensive use of `unsafe` code blocks. 🤷

It exploits the 2-bit alignment niche in pointers existing on most platforms (I think all Rustc supported platforms) to distinguish the inline representation from the other representations.
It leverages the 2-bit alignment niche present in pointers across most platforms (all platforms currently supported by the Rust compiler?) to discriminate between the three possible representations.

To make things safer, Rust is tested thoroughly on multiple platforms, normally and with [Miri] (the MIR interpreter).

## 🧪 Testing
## 🧪 Testing and Verification Strategy

To ensure safety and reliability, this crate undergoes thorough testing:

- Near 100% test coverage
- Cross-platform validation:
- 32-bit and 64-bit architectures
- little and big endian

In addition, this crate is checked with advanced dynamic verification methods:

- Concurrency testing using the [Tokio's loom crate][loom]
- Undefined behavior detection using [Miri] (the MIR interpreter)

### ☔ Coverage

Expand All @@ -64,6 +76,12 @@ Check out the current coverage on [Codecov]:

### 🖥️ Cross-platform testing

In the Github-provided CI, `hipstr` is tested under:

- Linux
- Windows
- MacOS (ARM 64-bit LE)

You can easily run the test on various platforms with [`cross`]:

```bash
Expand All @@ -75,6 +93,14 @@ cross test --target x86_64-unknown-linux-gnu # 64-bit LE

NB: previously I used MIPS targets for big endian, but due to some LLVM-related issue they are not working anymore… see [Rust issue #113065](https://github.com/rust-lang/rust/issues/113065)

### 🧵 [Loom]

This crates uses the `loom` crate to check the custom "Arc" implementation. To run the tests:

```bash
RUSTFLAGS='--cfg loom' cargo test --release loom
```

### 🔍 [Miri]

This crate runs successfully with Miri:
Expand All @@ -97,6 +123,8 @@ cargo +nightly miri test --target mips64-unknown-linux-gnuabi64
cargo +nightly miri test --target i686-unknown-linux-gnu
```

Note: this crate leverages the "exposed provenance" semantics.

## 📦 Similar crates

`#[non_exhaustive]`
Expand All @@ -121,7 +149,7 @@ skipping specialized string types like [`tinystr`](https://github.com/unicode-or

In short, `HipStr`, one string type to rule them all 😉

[![How standards proliferate](https://imgs.xkcd.com/comics/standards.png)](https://xkcd.com/927/)
[![How standards proliferate](https://imgs.xkcd.com/comics/standards.png)](https://xkcd.com/927/ )

## 🏎️ Performances

Expand All @@ -139,3 +167,4 @@ MIT + Apache
[codecov]: https://app.codecov.io/gh/polazarus/hipstr
[miri]: https://github.com/rust-lang/miri
[`cross`]: https://github.com/cross-rs/cross
[loom]: https://github.com/tokio-rs/loom

0 comments on commit 2ee9e8e

Please sign in to comment.