Crate hipstr

Yet another string type for Rust 🦀

• no copy and const literal wrapping
• 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, except for optional serde support

Also byte strings, OS strings, paths, too!

Examples

use hipstr::HipStr;

let simple_greetings = HipStr::borrowed("Hello world");
let clone = simple_greetings.clone(); // no copy
std::thread::spawn(move || { println!("{}", clone); });

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

Three Representations

Each type has three distinct representations:

• Borrowed slice
• Inline sequence (up to HipByt::inline_capacity())
• Shared reference (cheaply clonable) and slice (sliceable)

The shared reference can be thread-safe or not, depending on the backend.

Most operations keep string normalized, that is, if the string is not borrowed, the inline representation is preferred when possible.

⚠️ Warning!

The used representation of the empty string is unspecified and may change between patch versions! It may be borrowed or inlined but will never be allocated.

Three Backends

The crate provides three backends:

• Arc (atomic reference counting), formerly ThreadSafe
• Rc (reference counting), formerly Local
• Unique (unique reference)

The last backend, Unique, is mostly an experiment in pushing what constitutes a hipstr backend and has no practical use.

The crate root also provides some convenience type aliases, typically for strings:

• hipstr::HipStr with the Arc backend,
• hipstr::LocalHipStr with the Rc backend.

Platform Support

This crate is only supported on platforms where:

• pointers have the same memory size as usize,
• pointer alignment requirement is strictly greater than 2.

For now, most common architectures are like that. However, hipstr will not work on new and future architectures relying on large tagged pointers (e.g. CHERI 128-bit pointers).

Features

• std (default): uses std rather than core and alloc, and also provides more trait implementations (for comparison, conversions)
• serde: provides serialization/deserialization support with serde
• borsh: provides serialization/deserialization support with borsh
• bstr: provides compatibility with BurntSushi’s bstr crate make HipByt deref to &bstr::BStr rather than &[u8]
• unstable: do nothing, used to reveal unstable implementation details

Modules

bytes

Bytes.

os_stringstd

OS string.

pathstd

Cross-platform path.

string

String.

Structs

Arctarget_has_atomic="ptr"

Atomic (thread-safe) reference counter.

Rc

Local (thread-unsafe) reference counter.

Unique

Unique reference marker.

Traits

Backend

Sealed marker trait for allocated backend.

Type Aliases

HipByt

Thread-safe shared byte sequence.

HipOsStrstd

Thread-safe shared string.

HipPathstd

Thread-safe shared path.

HipStr

Thread-safe shared string.

LocalDeprecated

LocalHipByt

Thread-local shared byte sequence.

LocalHipOsStrstd

Thread-local shared byte sequence.

LocalHipPathstd

Thread-local shared path.

LocalHipStr

Thread-local shared string.

ThreadSafeDeprecated