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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
/// Creates an [`ArrayString`] containing the arguments.
///
/// `array_str!` macro allows creation of an `ArrayString` with given capacity and content.
///
/// Note that the used length type is [`Usize`] and spare memory policy is [`Uninitialized`].
///
/// # Examples
///
/// 1. `array_str![CAPACITY;]` - create an empty `ArrayString` with given capacity:
///
/// ```rust
/// # use cds::array_str;
/// let mut a = array_str![3;];
/// assert_eq!(a.len(), 0);
/// assert_eq!(a.capacity(), 3);
/// ```
///
/// 4. `array_str![CAPACITY; TRY_FROM]` - create an `ArrayString` with given capacity and
/// initializer:
///
/// ```rust
/// # use cds::array_str;
/// let a = array_str![32; "Hello, world!"];
/// assert_eq!(a.capacity(), 32);
/// assert_eq!(a.len(), 13);
/// // assert_eq!(a, "Hello, world!");
/// ```
///
/// 5. `array_str!` panics if the number of elements exceeds the requested capacity:
///
/// ```should_panic
/// # use cds::array_str;
/// array_str![0; "Hello, world!"];
/// ```
///
/// # Panics
///
/// The macro panics if initialization of the array-string fails.
///
/// [`ArrayString`]: crate::arraystring::ArrayString
/// [`Usize`]: crate::len::Usize
/// [`Uninitialized`]: crate::mem::Uninitialized
/// Formats an [`ArrayString`] possibly truncating the result.
///
/// This macro, similar to the standard [`std::format!`], formats a string but with [`ArrayString`]
/// as the resulting type. This allows formatting a string on stack, without memory allocation.
///
/// Note that, as `ArrayString` is a fixed-capacity non-growable string,
/// the result may be truncated (on character boundary) to fit the given capacity.
///
/// This macro is a convenience wrapper of the [`format_lossy`] function.
///
/// # Examples
///
/// Format an `ArrayString` specifying the capacity only. The resulting type uses [`Usize`] as
/// length type and [`Uninitialized`] as spare memory policy.
///
/// ```rust
/// # use cds::lformat;
/// let s = lformat!(16, "Hello, world!");
/// assert_eq!(s, "Hello, world!");
/// assert_eq!(s.capacity(), 16);
/// ```
///
/// Format an `ArrayString` specifying the array-string type.
/// This allows customization of length type and spare memory policy.
///
/// ```rust
/// # use cds::{lformat, len::U8, mem::Pattern, arraystring::ArrayString};
/// type A = ArrayString<16, U8, Pattern<0xCD>>;
/// let s = lformat!(A, "Hello, world!");
/// assert_eq!(s, "Hello, world!");
/// ```
///
/// Note that the result may be truncated if `ArrayString` capacity is not enough to accommodate the
/// whole formatted string. In some use case this may yield wrong results. Thus use only where lossy
/// formatting is appropriate, or when the capacity is ensured to be enough.
///
/// ```rust
/// # use cds::lformat;
/// let s = lformat!(5, "a=2500");
/// assert_eq!(s, "a=250"); // <-- !! the result may be wrong in some use cases
/// ```
///
/// [`ArrayString`]: crate::arraystring::ArrayString
/// [`format_lossy`]: crate::arraystring::format_lossy
/// [`Usize`]: crate::len::Usize
/// [`Uninitialized`]: crate::mem::Uninitialized
/// Formats an [`ArrayString`].
///
/// This macro, similar to the standard [`std::format!`], formats a string yielding
/// `Result<ArrayString>`. This allows formatting a string on stack, without memory allocation.
///
/// Note that, unlike the standard macro, this macro is fallible. `ArrayString` is a fixed-capacity
/// data structure, whose capacity may be not enough for formatting an arbitrary string.
/// See [`lformat!`] for a macro that returns a plain `ArrayString`, while possibly truncating the
/// result.
///
/// This macro is a convenience wrapper of the [`format`] function.
///
/// # Examples
///
/// Format an `ArrayString` specifying the capacity only. The resulting type uses [`Usize`] as
/// length type and [`Uninitialized`] as spare memory policy.
///
/// ```rust
/// # use cds::aformat;
/// # fn foo() -> core::fmt::Result {
/// let s = aformat!(16, "Hello, world!")?;
/// assert_eq!(s, "Hello, world!");
/// assert_eq!(s.capacity(), 16);
/// # Ok(())
/// # }
/// # foo().unwrap()
/// ```
///
/// Format an `ArrayString` specifying the array-string type.
/// This allows customization of length type and spare memory policy.
///
/// ```rust
/// # use cds::{aformat, len::U8, mem::Pattern, arraystring::ArrayString};
/// # fn foo() -> core::fmt::Result {
/// type A = ArrayString<16, U8, Pattern<0xCD>>;
/// let s = aformat!(A, "Hello, world!")?;
/// assert_eq!(s, "Hello, world!");
/// # Ok(())
/// # }
/// # foo().unwrap()
/// ```
///
/// Note that the macro may fail when there is no enough capacity.
///
/// ```rust
/// # use cds::aformat;
/// assert!(aformat!(2, "Hello, world!").is_err());
/// ```
///
/// [`ArrayString`]: crate::arraystring::ArrayString
/// [`format`]: crate::arraystring::format
/// [`Usize`]: crate::len::Usize
/// [`Uninitialized`]: crate::mem::Uninitialized