bumpref 0.1.0

Explicit .bump() method for Arc and Rc that signals cheap refcount cloning
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

//! Explicit reference count bumping for `Arc`, `Rc`, and their weak variants.
//!
//! This crate provides the [`Bump`] trait, which adds a `.bump()` method to reference-counted
//! types as an explicit alias for `.clone()`. This makes it clear that cloning is cheap—just
//! incrementing a reference count, not copying data.
//!
//! # Example
//!
//! ```rust
//! use std::sync::Arc;
//! use bumpref::Bump;
//!
//! let arc = Arc::new(42);
//! let arc_bumped = arc.bump(); // equivalent to Arc::clone(&arc)
//! assert_eq!(*arc, *arc_bumped);
//! ```

#![cfg_attr(not(test), no_std)]

extern crate alloc;

use alloc::rc::{Rc, Weak as RcWeak};
use alloc::sync::{Arc, Weak as ArcWeak};

/// A trait that provides a `bump()` method for reference-counted pointers.
///
/// This is an explicit alias for `clone()` that signals the operation is cheap—just
/// incrementing a reference count rather than performing a deep copy.
///
/// # Example
///
/// ```rust
/// use std::sync::Arc;
/// use bumpref::Bump;
///
/// let arc = Arc::new(vec![1, 2, 3]);
/// let bumped = arc.bump();
///
/// // Both point to the same data
/// assert_eq!(Arc::strong_count(&arc), 2);
/// ```
pub trait Bump {
    /// Bumps the reference count and returns a new reference.
    ///
    /// This is equivalent to cloning, but makes the intent more explicit.
    #[must_use]
    fn bump(&self) -> Self;
}

impl<T: ?Sized> Bump for Arc<T> {
    fn bump(&self) -> Self {
        Arc::clone(self)
    }
}

impl<T: ?Sized> Bump for Rc<T> {
    fn bump(&self) -> Self {
        Rc::clone(self)
    }
}

impl<T: ?Sized> Bump for ArcWeak<T> {
    fn bump(&self) -> Self {
        ArcWeak::clone(self)
    }
}

impl<T: ?Sized> Bump for RcWeak<T> {
    fn bump(&self) -> Self {
        RcWeak::clone(self)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_arc_bump() {
        let arc = Arc::new(42);
        let arc_bumped = arc.bump();
        assert_eq!(*arc, *arc_bumped);
        assert_eq!(Arc::strong_count(&arc), 2);
    }

    #[test]
    fn test_rc_bump() {
        let rc = Rc::new(42);
        let rc_bumped = rc.bump();
        assert_eq!(*rc, *rc_bumped);
        assert_eq!(Rc::strong_count(&rc), 2);
    }

    #[test]
    fn test_arc_weak_bump() {
        let arc = Arc::new(42);
        let weak = Arc::downgrade(&arc);
        let weak_bumped = weak.bump();
        assert_eq!(ArcWeak::weak_count(&weak), 2);
        assert_eq!(weak.upgrade().map(|a| *a), Some(42));
        assert_eq!(weak_bumped.upgrade().map(|a| *a), Some(42));
    }

    #[test]
    fn test_rc_weak_bump() {
        let rc = Rc::new(42);
        let weak = Rc::downgrade(&rc);
        let weak_bumped = weak.bump();
        assert_eq!(RcWeak::weak_count(&weak), 2);
        assert_eq!(weak.upgrade().map(|r| *r), Some(42));
        assert_eq!(weak_bumped.upgrade().map(|r| *r), Some(42));
    }
}