take_ref 0.2.0

TakeRef, TakeSlice, and TakeString traits enable treating references/slices and values interchangeably. They can be treated as references/slices. And you can take ownership of the value within with a clone performed only as needed.
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

use std::string::String;

/// The `TakeString` trait for Rust enables treating `&str` and `String` instances interchangeably.
/// 
/// # Examples
/// 
/// `take_string` can take in instances of both `String` and `&str`.
/// If it takes in a `&str`, no copying is needed unless `take` is called.
/// ```
/// use take_ref::TakeString;
/// 
/// fn take_string(value: impl TakeString) {
///     assert_eq!(value.as_str(), "Hi!"); // `as_str` references the string in place.
///     assert_eq!(value.as_str(), "Hi!"); // `as_str` can be repeated until `take` is called.
///     assert_eq!(value.take(), "Hi!"); // `take` consumes the value.
/// }
/// 
/// take_string("Hi!");
/// 
/// let s = "Hi!";
/// take_string(s);
/// ```
/// 
/// ## `Disallowed Operations`
/// 
/// `ref_taken` fails to compile since it attempts to reference `value` after `take` has already consumed it.
/// ```compile_fail
/// fn ref_taken(value: impl TakeString) {
///     value.take(); // `take` consumes the value.
///     value.as_str(); // This call is disallowed since the value has already been consumed.
/// }
/// ```
/// 
/// `take_taken` fails to compile since it attempts to `take` `value` after `take` has already consumed it.
/// ```compile_fail
/// fn take_taken(value: impl TakeString) {
///     value.take(); // `take` consumes the value.
///     value.take(); // This call is disallowed since the value has already been consumed.
/// }
/// ```
pub trait TakeString {
    /// Reference the string as a `&str`.
    fn as_str(&self) -> &str;
    /// Take ownership of the String or construct a String and drop `self`.
    fn take(self) -> String;
}

impl TakeString for &str {
    /// Reference the string as a `&str`.
    fn as_str(&self) -> &str {
        self
    }

    /// Construct a String and drop `self`.
    fn take(self) -> String {
        self.into()
    }
}

impl TakeString for String {
    /// Reference the string as a `&str`.
    fn as_str(&self) -> &str {
        self
    }

    /// Take ownership of the String and drop `self`.
    fn take(self) -> String {
        self
    }
}