🐆 CheetahString

A lightweight, high-performance string type optimized for real-world use cases.

CheetahString is a versatile string type that goes beyond the standard library's String, providing zero-allocation optimizations for common patterns and seamless interoperability with various string representations. It's designed for both std and no_std environments.

✨ Features

• 🚀 Zero-Allocation Optimization

  • Small String Optimization (SSO): Strings ≤ 23 bytes stored inline (no heap allocation)
  • Static string support with 'static lifetime
  • Efficient Arc-based sharing for larger strings

• 🔧 Rich API

  • Query methods: starts_with, ends_with, contains, find, rfind
  • Transformation: to_uppercase, to_lowercase, replace, trim
  • Iteration: split, lines, chars
  • Builder pattern: with_capacity, push_str, reserve
  • String concatenation with + and += operators

• 🌐 Flexible Integration

  • Optional bytes support for zero-copy interop with the bytes crate
  • Optional serde support for serialization/deserialization
  • no_std compatible (requires alloc)

• ⚡ Performance Focused

  • Optimized for common string operations
  • Reduced memory allocations via intelligent internal representation
  • Benchmarked against standard library types

• 🛡️ Safe & Correct

  • UTF-8 validation with safe constructors (try_from_bytes, try_from_vec)
  • Comprehensive test coverage
  • Well-documented API with examples

📦 Installation

Add this to your Cargo.toml:

[dependencies]
cheetah-string = "0.1"

Optional Features

[dependencies]
cheetah-string = { version = "0.1", features = ["bytes", "serde"] }

Available features:

• std (default): Enable standard library support
• bytes: Integration with the bytes crate
• serde: Serialization support via serde

🚀 Quick Start

use cheetah_string::CheetahString;

// Create from various sources
let s1 = CheetahString::from("hello");           // From &str
let s2 = CheetahString::from(String::from("world")); // From String
let s3 = CheetahString::from_static_str("static");   // From 'static str (zero-cost)

// Small strings (≤ 23 bytes) use no heap allocation
let small = CheetahString::from("short");  // Stored inline!

// String operations
let s = CheetahString::from("Hello, World!");
assert!(s.starts_with("Hello"));
assert!(s.contains("World"));
assert_eq!(s.to_lowercase(), "hello, world!");

// Concatenation
let greeting = CheetahString::from("Hello");
let name = CheetahString::from(" Rust");
let message = greeting + name.as_str();  // "Hello Rust"

// Builder pattern for efficient construction
let mut builder = CheetahString::with_capacity(100);
builder.push_str("Hello");
builder.push_str(", ");
builder.push_str("World!");

// Safe UTF-8 validation
let bytes = b"hello";
let s = CheetahString::try_from_bytes(bytes).unwrap();

📊 Performance

CheetahString is designed with performance in mind:

• Small String Optimization (SSO): Strings up to 23 bytes are stored inline without heap allocation
• Efficient Sharing: Large strings use Arc<str> for cheap cloning
• Optimized Operations: Common operations like concatenation have fast-path implementations

Run benchmarks:

cargo bench

🔍 Internal Representation

CheetahString intelligently chooses the most efficient storage:

String Type	Storage	Heap Allocations	Use Case
≤ 23 bytes	Inline (SSO)	0	Short strings, identifiers
Static	&'static str	0	String literals
Dynamic	Arc<str>	1	Long strings, shared data
From Arc	Arc<String>	1	Interop with existing Arc
Bytes	bytes::Bytes	1	Network buffers (with feature)

🔧 API Overview

Construction

• new(), empty(), default() - Create empty strings
• from(s) - From &str, String, &String, char, etc.
• from_static_str(s) - Zero-cost wrapper for 'static str
• from_string(s) - From owned String
• try_from_bytes(b) - Safe construction from bytes with UTF-8 validation
• with_capacity(n) - Pre-allocate capacity

Query Methods

• len(), is_empty(), as_str(), as_bytes()
• starts_with(), ends_with(), contains()
• find(), rfind()

Transformation

• to_uppercase(), to_lowercase()
• replace(), replacen()
• trim(), trim_start(), trim_end()
• substring(), repeat()

Iteration

• chars() - Iterate over characters
• split() - Split by pattern
• lines() - Iterate over lines

Mutation

• push_str() - Append string slice
• reserve() - Reserve additional capacity

Operators

• + - Concatenation
• += - Append in-place (optimized)
• ==, != - Equality comparison with str, String, etc.

🎯 Use Cases

CheetahString is ideal for:

• High-performance servers: Reduce allocations in hot paths
• Memory-constrained environments: Efficient memory usage with SSO
• Network protocols: Integration with bytes crate
• Configuration systems: Fast handling of static and dynamic strings
• No-std applications: Embedded systems and WASM

🏗️ Projects Using CheetahString

• RocketMQ Rust - Apache RocketMQ Rust implementation

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Report Issues: Found a bug? Open an issue
2. Submit PRs: Improvements and bug fixes are appreciated
3. Add Benchmarks: Help us track performance across use cases
4. Improve Documentation: Better docs help everyone

Development Setup

# Clone the repository
git clone https://github.com/mxsm/cheetah-string.git
cd cheetah-string

# Run tests
cargo test

# Run benchmarks
cargo bench

# Run with all features
cargo test --all-features

📝 License

This project is licensed under either of:

• Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🙏 Acknowledgments

CheetahString is inspired by the need for a flexible, high-performance string type in Rust that bridges the gap between String, &str, Arc<str>, and specialized types like bytes::Bytes.