hipstr

Yet another string type for Rust 🦀

• no copy borrow via borrowed (a const constructor) or from_static
• no alloc small strings (23 bytes on 64-bit platform)
• no copy owned slices
• a niche: Option<HipStr> and HipStr have the same size
• zero dependency and compatible no_std with alloc

Also byte strings, OS strings, and paths!

⚡ Examples

use hipstr::HipStr;

let simple_greetings = HipStr::from_static("Hello world");
let _clone = simple_greetings.clone(); // no copy

let user = "John";
let greetings = HipStr::from(format!("Hello {}", user));
let user = greetings.slice(6..): // no copy
drop(greetings); // the slice is owned, it exists even if greetings disappear

let chars = user.chars().count(); // "inherits" `&str` methods

✏️ Features

• std (default): provides HipOsStr and HipPath types, and more trait implementations (for comparison and conversions)
• serde: provides serialization/deserialization support with serde
• borsh: provides serialization/deserialization support with borsh
• bstr: provides compatibility with BurntSushi's bstr crate
• unstable: do nothing, used to reveal unstable implementation details

☣️ Safety of hipstr

This crate makes extensive use of unsafe code blocks. 🤷

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 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
• Undefined behavior detection using Miri (the MIR interpreter)

☔ Coverage

This crate has near full line coverage:

cargo llvm-cov --all-features --html
# or
cargo tarpaulin --all-features --out html --engine llvm

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:

cross test --target s390x-unknown-linux-gnu         # 32-bit BE
cross test --target powerpc64-unknown-linux-gnu     # 64-bit BE
cross test --target i686-unknown-linux-gnu          # 32-bit LE
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

🧵 Loom

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

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

🔍 Miri

This crate runs successfully with Miri:

MIRIFLAGS='-Zmiri-symbolic-alignment-check -Zmiri-permissive-provenance' cargo +nightly miri test

for SEED in $(seq 0 10); do
  echo "Trying seed: $SEED"
  MIRIFLAGS="-Zmiri-seed=$SEED -Zmiri-permissive-provenance" cargo +nightly miri test || { echo "Failing seed: $SEED"; break; };
done

To check with different word size and endianness:

# Big endian, 64-bit
cargo +nightly miri test --target mips64-unknown-linux-gnuabi64
# Little endian, 32-bit
cargo +nightly miri test --target i686-unknown-linux-gnu

Note: this crate leverages the "exposed provenance" semantics. MIRIFLAGS=-Zmiri-permissive-provenance silences the warning related to the use of exposed provenance.

📦 Similar crates

#[non_exhaustive]

skipping specialized string types like tinystr (ASCII-only, bounded), or bstr, or bytestring, or...

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

🏎️ Performances

While speed is not the main motivator for hipstr, it seems to be doing OK on that front.

See some actual benchmarks on Rust's String Rosetta.

📖 Author and licenses

For now, just me PoLazarus 👻
Help welcome! 🚨

MIT + Apache