[ISSUE #84]✨Enhance CheetahString with ArcStr support and incremental building methods (#85)

Author: mxsm

README.md

@@ -1,51 +1,208 @@
-# 🐆 Cheetah String
+# 🐆 CheetahString
 
-**A lightweight, high-performance string manipulation library optimized for speed-sensitive applications.**
+[![Crates.io](https://img.shields.io/crates/v/cheetah-string.svg)](https://crates.io/crates/cheetah-string)
+[![Documentation](https://docs.rs/cheetah-string/badge.svg)](https://docs.rs/cheetah-string)
+[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://github.com/mxsm/cheetah-string)
+[![Rust Version](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org)
 
-Cheetah String is designed to provide fast and efficient string operations with minimal resource usage, ideal for performance-critical and memory-constrained environments. It offers a range of easy-to-use, high-speed string handling functions.
+**A lightweight, high-performance string type optimized for real-world use cases.**
 
-## Features
+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.
 
-- **Highly optimized**: Performance-tuned across platforms to support low-latency needs.
-- **Comprehensive API**: Includes common string operations (e.g., split, concatenate, transform, format, etc.).
-- **Easy to integrate**: Simple, intuitive design to minimize the learning curve.
-- **Cross-platform**: Compatible with major operating systems and development environments.
+## ✨ Features
 
-## How to use
+- **🚀 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
 
-To use **`Cheetah-String`**, first add this to your `Cargo.toml`:
+- **🔧 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`:
 
 ```toml
 [dependencies]
-cheetah-string = "0.1.0"
+cheetah-string = "0.1"
 ```
 
-### Bytes support
-
-**Bytes** support is optional and disabled by default. To enable use the feature `bytes`.
+### Optional Features
 
 ```toml
 [dependencies]
-cheetah-string = { version = "1", features = ["bytes"] }
+cheetah-string = { version = "0.1", features = ["bytes", "serde"] }
 ```
 
-### Serde support
+Available features:
+- `std` (default): Enable standard library support
+- `bytes`: Integration with the `bytes` crate
+- `serde`: Serialization support via serde
 
-**serde** support is optional and disabled by default. To enable use the feature `serde`.
+## 🚀 Quick Start
 
-```toml
-[dependencies]
-cheetah-string = { version = "1", features = ["serde"] }
+```rust
+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:
+```bash
+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**](https://github.com/mxsm/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](https://github.com/mxsm/cheetah-string/issues)
+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
+
+```bash
+# 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
 ```
 
-##  Projects used
+## 📝 License
 
-- [**Rocketmq-rust**](https://github.com/mxsm/rocketmq-rust)
+This project is licensed under either of:
 
-## Contributing
+- Apache License, Version 2.0 ([LICENSE](LICENSE) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
-We welcome issues and pull requests to help build a more efficient string manipulation library together!
+at your option.
 
-## License
+## 🙏 Acknowledgments
 
-**cheetah-string** is licensed under the [Apache License 2.0](https://github.com/mxsm/cheetah-string/blob/main/LICENSE) and [MIT license](https://github.com/mxsm/cheetah-string/blob/main/LICENSE-MIT)
+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`.