Add criterion benchmarks for CowStr

Author: KushalMeghani1644

Cargo.toml

@@ -75,6 +75,11 @@ stable_deref_trait = { version = "1", default-features = false }
 [dev-dependencies]
 critical-section = { version = "1.1", features = ["std"] }
 static_assertions = "1.1.0"
+criterion = "0.5"
+
+[[bench]]
+name = "cow_str"
+harness = false
 
 [package.metadata.docs.rs]
 features = [

benches/cow_str.rs

@@ -0,0 +1,288 @@
+//! Criterion benchmarks for `CowStr` enum.
+//!
+//! This benchmark suite measures the performance characteristics of `CowStr`
+//! and compares it against baseline implementations that always copy strings.
+
+use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion};
+use heapless::{cow::CowStr, String};
+
+fn create_test_string<const N: usize>(content: &str) -> String<N> {
+    String::try_from(content).expect("String too long for capacity")
+}
+
+/// Baseline function that always copies into a new String<N>.
+fn baseline_always_copy<const N: usize>(input: &String<N>) -> String<N> {
+    input.clone()
+}
+
+/// Function returning CowStr that only clones on mutation.
+fn cowstr_clone_on_mutation<'a, const N: usize>(
+    input: &'a String<N>,
+    needs_mutation: bool,
+) -> CowStr<'a, N> {
+    if needs_mutation {
+        let mut owned = input.clone();
+        owned.push_str("_mutated").ok();
+        CowStr::Owned(owned)
+    } else {
+        CowStr::Borrowed(input.as_view())
+    }
+}
+
+fn bench_baseline_vs_cowstr(c: &mut Criterion) {
+    let mut group = c.benchmark_group("baseline_vs_cowstr");
+
+    let test_str: String<128> = create_test_string("test string for comparison");
+
+    group.bench_function("baseline_always_copy", |b| {
+        b.iter(|| {
+            let result = baseline_always_copy(black_box(&test_str));
+            black_box(result)
+        });
+    });
+
+    group.bench_function("cowstr_no_mutation", |b| {
+        b.iter(|| {
+            let result = cowstr_clone_on_mutation(black_box(&test_str), false);
+            black_box(result)
+        });
+    });
+
+    group.bench_function("cowstr_with_mutation", |b| {
+        b.iter(|| {
+            let result = cowstr_clone_on_mutation(black_box(&test_str), true);
+            black_box(result)
+        });
+    });
+
+    group.finish();
+}
+
+fn bench_cowstr_creation(c: &mut Criterion) {
+    let mut group = c.benchmark_group("cowstr_creation");
+
+    let short_str: String<16> = create_test_string("hello");
+    let medium_str: String<64> = create_test_string("This is a medium length test string");
+    let long_str: String<256> = create_test_string("This is a much longer test string that contains more characters to properly test the performance characteristics of the CowStr type with different sizes");
+
+    group.bench_function("borrowed_short", |b| {
+        b.iter(|| {
+            let view = black_box(&short_str).as_view();
+            black_box(CowStr::<16>::Borrowed(view))
+        });
+    });
+
+    group.bench_function("borrowed_medium", |b| {
+        b.iter(|| {
+            let view = black_box(&medium_str).as_view();
+            black_box(CowStr::<64>::Borrowed(view))
+        });
+    });
+
+    group.bench_function("borrowed_long", |b| {
+        b.iter(|| {
+            let view = black_box(&long_str).as_view();
+            black_box(CowStr::<256>::Borrowed(view))
+        });
+    });
+
+    group.bench_function("owned_short", |b| {
+        b.iter(|| {
+            let s = black_box(short_str.clone());
+            black_box(CowStr::<16>::Owned(s))
+        });
+    });
+
+    group.bench_function("owned_medium", |b| {
+        b.iter(|| {
+            let s = black_box(medium_str.clone());
+            black_box(CowStr::<64>::Owned(s))
+        });
+    });
+
+    group.bench_function("owned_long", |b| {
+        b.iter(|| {
+            let s = black_box(long_str.clone());
+            black_box(CowStr::<256>::Owned(s))
+        });
+    });
+
+    group.finish();
+}
+
+fn bench_cowstr_as_str(c: &mut Criterion) {
+    let mut group = c.benchmark_group("cowstr_as_str");
+
+    let test_str: String<64> = create_test_string("test string for as_str");
+    let borrowed = CowStr::<64>::Borrowed(test_str.as_view());
+    let owned = CowStr::<64>::Owned(test_str.clone());
+    let static_string: &'static String<64> = Box::leak(Box::new(test_str.clone()));
+    let static_cow = CowStr::<64>::Static(static_string.as_view());
+
+    group.bench_function("borrowed", |b| {
+        b.iter(|| black_box(&borrowed).as_str());
+    });
+
+    group.bench_function("static", |b| {
+        b.iter(|| black_box(&static_cow).as_str());
+    });
+
+    group.bench_function("owned", |b| {
+        b.iter(|| black_box(&owned).as_str());
+    });
+
+    group.finish();
+}
+
+fn bench_cowstr_to_owned(c: &mut Criterion) {
+    let mut group = c.benchmark_group("cowstr_to_owned");
+
+    for size in [16, 64, 256].iter() {
+        let content = match size {
+            16 => "short",
+            64 => "This is a medium length string for testing",
+            256 => "This is a very long string that we use to test the performance of the to_owned method on CowStr with different string sizes and capacities to ensure proper benchmarking",
+            _ => unreachable!(),
+        };
+
+        match size {
+            16 => {
+                let test_str: String<16> = create_test_string(content);
+                let borrowed = CowStr::<16>::Borrowed(test_str.as_view());
+                let owned = CowStr::<16>::Owned(test_str.clone());
+
+                group.bench_with_input(BenchmarkId::new("borrowed", size), size, |b, _| {
+                    b.iter(|| black_box(&borrowed).to_owned());
+                });
+
+                group.bench_with_input(BenchmarkId::new("owned", size), size, |b, _| {
+                    b.iter(|| black_box(&owned).to_owned());
+                });
+            }
+            64 => {
+                let test_str: String<64> = create_test_string(content);
+                let borrowed = CowStr::<64>::Borrowed(test_str.as_view());
+                let owned = CowStr::<64>::Owned(test_str.clone());
+
+                group.bench_with_input(BenchmarkId::new("borrowed", size), size, |b, _| {
+                    b.iter(|| black_box(&borrowed).to_owned());
+                });
+
+                group.bench_with_input(BenchmarkId::new("owned", size), size, |b, _| {
+                    b.iter(|| black_box(&owned).to_owned());
+                });
+            }
+            256 => {
+                let test_str: String<256> = create_test_string(content);
+                let borrowed = CowStr::<256>::Borrowed(test_str.as_view());
+                let owned = CowStr::<256>::Owned(test_str.clone());
+
+                group.bench_with_input(BenchmarkId::new("borrowed", size), size, |b, _| {
+                    b.iter(|| black_box(&borrowed).to_owned());
+                });
+
+                group.bench_with_input(BenchmarkId::new("owned", size), size, |b, _| {
+                    b.iter(|| black_box(&owned).to_owned());
+                });
+            }
+            _ => unreachable!(),
+        }
+    }
+
+    group.finish();
+}
+
+fn bench_cowstr_type_checks(c: &mut Criterion) {
+    let mut group = c.benchmark_group("cowstr_type_checks");
+
+    let test_str: String<64> = create_test_string("test");
+    let borrowed = CowStr::<64>::Borrowed(test_str.as_view());
+    let owned = CowStr::<64>::Owned(test_str.clone());
+    let static_string: &'static String<64> = Box::leak(Box::new(test_str.clone()));
+    let static_cow = CowStr::<64>::Static(static_string.as_view());
+
+    group.bench_function("is_borrowed", |b| {
+        b.iter(|| black_box(&borrowed).is_borrowed());
+    });
+
+    group.bench_function("is_static", |b| {
+        b.iter(|| black_box(&static_cow).is_static());
+    });
+
+    group.bench_function("is_owned", |b| {
+        b.iter(|| black_box(&owned).is_owned());
+    });
+
+    group.finish();
+}
+
+fn bench_cowstr_vs_clone(c: &mut Criterion) {
+    let mut group = c.benchmark_group("cowstr_vs_clone");
+
+    let test_str: String<128> =
+        create_test_string("This is a string that would normally be cloned in every operation");
+
+    group.bench_function("cowstr_borrowed_read_only", |b| {
+        b.iter(|| {
+            let cow = CowStr::<128>::Borrowed(black_box(&test_str).as_view());
+            let _result = black_box(cow.as_str());
+        });
+    });
+
+    group.bench_function("string_clone_read_only", |b| {
+        b.iter(|| {
+            let s = black_box(&test_str).clone();
+            let _result = black_box(s.as_str());
+        });
+    });
+
+    group.bench_function("cowstr_to_owned_when_needed", |b| {
+        b.iter(|| {
+            let cow = CowStr::<128>::Borrowed(black_box(&test_str).as_view());
+            let _owned = black_box(cow.to_owned());
+        });
+    });
+
+    group.bench_function("string_clone_when_needed", |b| {
+        b.iter(|| {
+            let s = black_box(&test_str).clone();
+            let _owned = black_box(s);
+        });
+    });
+
+    group.finish();
+}
+
+fn bench_cowstr_from(c: &mut Criterion) {
+    let mut group = c.benchmark_group("cowstr_from");
+
+    let test_str: String<64> = create_test_string("test string");
+
+    group.bench_function("from_stringview", |b| {
+        b.iter(|| {
+            let view = black_box(&test_str).as_view();
+            black_box(CowStr::<64>::from(view))
+        });
+    });
+
+    group.bench_function("from_string", |b| {
+        b.iter(|| {
+            let s = black_box(&test_str).clone();
+            black_box(CowStr::<64>::from(s))
+        });
+    });
+
+    group.finish();
+}
+
+criterion_group!(
+    benches,
+    bench_baseline_vs_cowstr,
+    bench_cowstr_creation,
+    bench_cowstr_as_str,
+    bench_cowstr_to_owned,
+    bench_cowstr_type_checks,
+    bench_cowstr_vs_clone,
+    bench_cowstr_from
+);
+criterion_main!(benches);

src/cow.rs

@@ -3,6 +3,16 @@
 //! Provides `CowStr`, a heapless clone-on-write string that can be
 //! borrowed, static, or owned. Useful for efficiently handling
 //! temporary string references and owned strings.
+//!
+//! NOTE: Unlike `std::borrow::Cow<'a, str>` this type does NOT provide a
+//! smaller in-memory representation for the borrowed variants. The enum is
+//! at least as large as the owned `String<N, LenT>` because the owned
+//! variant carries the inline buffer. The motivation is purely to avoid
+//! paying an O(len) copy when a string is very often reused unchanged, while
+//! still allowing the API to return an owned form when a (rare) mutation or
+//! normalization is required. If the caller always needs an owned `String`
+//! anyway, `CowStr` offers no benefit and should not be used.
+
 use crate::len_type::LenType;
 use crate::string::StringView;
 use crate::String;