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
extern crate alloc;
extern crate std;
use Borrow;
/// Chooses the type to borrow when a value is used with a particular context.
///
/// The context is a type your generic code already knows. Each implementation chooses a
/// [`View`](Self::View) for that context. Use [`borrow_for`] or [`Borrow::borrow`] to get a
/// reference to the chosen view.
///
/// `Context` and `View` can be different types. For example, with the `alloc` feature, a string
/// literal in a `String` context has a `str` view. You only need the context's type, so you do
/// not have to create a value of that type.
///
/// Both `Context` and `View` can be unsized, such as `str` or `[T]`. This trait does not require
/// cloning, comparison, or formatting support. Your code adds any bounds it needs to use the
/// borrowed view.
///
/// The crate provides implementations for values, references, and arrays. The `alloc`
/// feature adds strings, C strings, vectors, `Box`, `Rc`, and `Cow`. It also adds `Arc` on targets
/// with pointer-sized atomic operations. The default `std` feature enables `alloc` and adds
/// paths and OS strings. The `serde_json` feature adds strings, numbers, and booleans in JSON value
/// contexts. See the [crate documentation](crate) for the view each implementation chooses.
///
/// # Implementing `BorrowFor`
///
/// First, implement [`Borrow<View>`](Borrow) to return a reference to your view. Then implement
/// `BorrowFor<Context>` to choose that view for the context:
///
/// ```
/// use borrow_for::{BorrowFor, borrow_for};
/// use core::borrow::Borrow;
///
/// struct Text<'a>(&'a str);
///
/// impl Borrow<str> for Text<'_> {
/// fn borrow(&self) -> &str {
/// self.0
/// }
/// }
///
/// impl BorrowFor<String> for Text<'_> {
/// type View = str;
/// }
///
/// let text = Text("hello");
/// assert_eq!(borrow_for::<String, _>(&text), "hello");
/// ```
///
/// [`Borrow`] requires your type and its view to agree on equality, ordering, and hashing
/// whenever they implement those operations. If the borrowed data would behave differently,
/// use [`AsRef`] or an accessor instead.
///
/// # References
///
/// Implementing `BorrowFor<Context>` for `T` does not automatically implement it for `&T` or
/// `&mut T`. Add those implementations explicitly if your API needs them. `BorrowFor` does not
/// strip reference layers to find an implementation.
///
/// A reference can also choose a different view from an owned value. In a `str` context, a
/// `String` is borrowed as `str`, but `&String` and `&mut String` are borrowed as `String`.
/// Pass `.as_str()` if you want a `str` view from a borrowed `String`.
/// Borrows a value using the view chosen for `Context`.
///
/// [`BorrowFor<Context>`](BorrowFor) chooses the view, and this function calls [`Borrow::borrow`]
/// once to get a reference to it. Both the input and the view can be unsized, such as `str` or
/// `[T]`.
///
/// ```
/// use borrow_for::borrow_for;
///
/// let array = [1, 2, 3];
/// let slice: &[i32] = borrow_for::<[i32], _>(&array);
/// assert_eq!(slice, &[1, 2, 3]);
/// assert_eq!(borrow_for::<[i32], _>(slice), slice);
/// ```
Sized, V: + ?Sized>