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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
use alloc::{string::String, vec::Vec};
use core::num::NonZeroUsize;
use awint_core::{Bits, SerdeError};
use crate::{
string_internals::{
bits_to_string_radix, bits_to_vec_radix, internal_from_bytes_general,
internal_from_bytes_radix, internal_from_str,
},
Awi,
};
/// # non-`const` string representation conversion
impl Awi {
/// Creates a `Vec<u8>` representing `bits` (sign indicators, prefixes, and
/// postfixes not included). This function performs allocation. This is
/// a wrapper around [awint_core::Bits::to_bytes_radix] that truncates
/// leading zeros. An additional `min_chars` specifies the minimum
/// number of characters that should exist. `min_chars` specifies the
/// minimum number of chars in the integer part, inserting leading '0's if
/// there are not enough chars, just like Rust's built in `{:0d}`
/// formatting. Note that an empty vector will be returned if
/// `min_chars == 0 && bits.is_zero()`.
///
/// # Errors
///
/// This can only return an error if `radix` is not in the range 2..=36 or
/// if resource exhaustion occurs.
pub fn bits_to_vec_radix(
bits: &Bits,
signed: bool,
radix: u8,
upper: bool,
min_chars: usize,
) -> Result<Vec<u8>, SerdeError> {
bits_to_vec_radix(bits, signed, radix, upper, min_chars)
}
/// Creates a string representing `bits`. This function performs allocation.
/// This does the same thing as [Awi::bits_to_vec_radix] but with a
/// `String`.
pub fn bits_to_string_radix(
bits: &Bits,
signed: bool,
radix: u8,
upper: bool,
min_chars: usize,
) -> Result<String, SerdeError> {
bits_to_string_radix(bits, signed, radix, upper, min_chars)
}
/// Creates an `Awi` representing the given arguments. This function
/// performs allocation. This is a wrapper around
/// [awint_core::Bits::bytes_radix_] that zero or sign resizes the
/// result to match `bw`.
///
/// # Errors
///
/// See the error conditions of [Bits::bytes_radix_]. Note that `-` is
/// an invalid character even though `to_vec_radix` can return `-`. This
/// is because we need to handle both unsigned and signed integer
/// inputs, specified only by `sign`. If the input is a negative signed
/// integer representation with `-` appended to the front, the subslice
/// `src[1..]` can be taken and `sign` can be set to `Some(true)`.
pub fn from_bytes_radix(
sign: Option<bool>,
src: &[u8],
radix: u8,
bw: NonZeroUsize,
) -> Result<Awi, SerdeError> {
let mut res = Awi::zero(bw);
internal_from_bytes_radix(&mut res, sign, src, radix)?;
Ok(res)
}
/// Creates an `Awi` representing the given arguments. This does the same
/// thing as [Awi::from_bytes_radix] but with an `&str`.
pub fn from_str_radix(
sign: Option<bool>,
str: &str,
radix: u8,
bw: NonZeroUsize,
) -> Result<Awi, SerdeError> {
let mut res = Awi::zero(bw);
internal_from_bytes_radix(&mut res, sign, str.as_bytes(), radix)?;
Ok(res)
}
/// Creates an `Awi` representing the given arguments. This function
/// performs allocation. In addition to the arguments and semantics from
/// [Awi::from_bytes_radix], this function includes the ability to deal
/// with general fixed point integer deserialization. `src` is now split
/// into separate `integer` and `fraction` parts. An exponent `exp` further
/// multiplies the numerical value by `radix^exp`. `fp` is the location
/// of the fixed point in the output representation of the numerical
/// value (e.x. for a plain integer `fp == 0`). `fp` can be negative or
/// greater than the bitwidth.
///
/// This function uses a single rigorous round-to-even that occurs after
/// the exponent and fixed point multiplier are applied and before any
/// numerical information is lost.
///
/// See [crate::FP::to_vec_general] for the inverse of this function.
///
/// # Errors
///
/// See the error conditions of [Awi::from_bytes_radix]. The precision
/// can now be arbitrarily large (any overflow in the low numerical
/// significance direction will be rounded), but overflow can still happen
/// in the more significant direction. Empty strings are interpreted as a
/// zero value.
pub fn from_bytes_general(
sign: Option<bool>,
integer: &[u8],
fraction: &[u8],
exp: isize,
radix: u8,
bw: NonZeroUsize,
fp: isize,
) -> Result<Awi, SerdeError> {
let mut res = Awi::zero(bw);
internal_from_bytes_general(&mut res, sign, integer, fraction, exp, radix, fp)?;
Ok(res)
}
/// Creates an `Awi` representing the given arguments. This does the same
/// thing as [Awi::from_bytes_general] but with `&str`s.
pub fn from_str_general(
sign: Option<bool>,
integer: &str,
fraction: &str,
exp: isize,
radix: u8,
bw: NonZeroUsize,
fp: isize,
) -> Result<Awi, SerdeError> {
let mut res = Awi::zero(bw);
internal_from_bytes_general(
&mut res,
sign,
integer.as_bytes(),
fraction.as_bytes(),
exp,
radix,
fp,
)?;
Ok(res)
}
}
impl core::str::FromStr for Awi {
type Err = SerdeError;
/// Creates an `Awi` described by `s`. There are three modes of operation
/// which invoke [Awi::from_str_radix] or [Awi::from_str_general]
/// differently.
///
/// Note: there is currently a
/// [bug](https://github.com/rust-lang/rust/issues/108385) in Rust that
/// causes certain fixed point literals to fail to parse when attempting
/// to use them in the concatenation macros. In case of getting
/// "literal is not supported" errors, use `Awi::from_str` directly.
///
/// Additionally, note that it is easy to cause resource exhaustion with
/// large bitwidths, exponents, or fixed points that can approach
/// `usize::MAX`. In a future version of `awint` we should have a guarded
/// function for helping with entering literals through things like UIs.
///
/// All valid inputs must begin with '0'-'9' or a '-' followed by '0'-'9'.
///
/// If only ' _ ', '0', and '1' chars are present, this function uses binary
/// mode. It will interpret the input as a binary string, the number of '0's
/// and '1's of which is the bitwidth (including leading '0's and excluding
/// ' _ 's). For example: 42 in binary is 101010. If "101010" is entered
/// into this function, it will return an `ExtAwi` with bitwidth 6 and
/// unsigned value 42. "0000101010" results in bitwidth 10 and unsigned
/// value 42. "1111_1111" results in bitwidth 8 and signed value -128 or
/// equivalently unsigned value 255.
///
/// In integer mode, a decimal bitwidth must be specified after a 'u'
/// (unsigned) or 'i' (signed) suffix. A prefix of "0b" specifies a binary
/// radix, "0o" specifies an octal radix, "0x" specifies hexadecimal,
/// otherwise a decimal radix is used. For example: "42u10" entered into
/// this function creates an `ExtAwi` with bitwidth 10 and unsigned
/// value 42. "-42i10" results in bitwidth 10 and signed value of -42.
/// "0xffff_ffffu32" results in bitwidth 32 and an unsigned value of
/// 0xffffffff (also 4294967295 in decimal and u32::MAX).
/// "0x1_0000_0000u32" results in an error with `SerdeError::Overflow`,
/// because it exceeds the maximum unsigned value for a 32 bit integer.
/// "123" results in `SerdeError::EmptyBitwidth`, because it is not in
/// binary mode and no bitwidth suffix has been supplied.
///
/// If, after the bitwidth, an 'f' char is present, fixed point mode is
/// activated. A decimal fixed point position must be specified after the
/// 'f' that tells where the fixed point will be in the resulting bits (see
/// [crate::FP] for more). If the most significant numerical bit would be
/// cut off, `SerdeError::Overflow` is returned.
///
/// Additionally, an exponent char 'e' (for non-hexadecimal radixes only) or
/// 'p' can be included after the integer or fraction parts but before the
/// bitwidth suffix. The exponent as typed uses the radix of the integer
/// part, and it is raised to the same radix when modifying the numerical
/// value. The exponent can only be negative for fixed point mode. For
/// example: "123e5u32" has numerical value 12300000. "123e-5u32" returns an
/// error since it is trying to use a negative exponent in integer mode.
/// "-0x1234.5678p-3i32f16" has a numerical value of -0x1234.5678 *
/// 0x10^-0x3 and uses [Awi::from_bytes_general] to round-to-even to a 32
/// bit fixed point number with fixed point position 16. You probably want
/// to use underscores to make it clearer where different parts are, e.x.
/// "-0x1234.5678_p-3_i32_f16".
///
/// For all parts including the integer, fraction, exponent, bitwidth, and
/// fixed point parts, if their prefix char exists but there is not at least
/// one '0' for them, some kind of empty error is returned. For example:
/// "0xu8" should be "0x0u8". ".i8f0" should be "0.0i8f0". "1u32f" should be
/// "1u32f0".
fn from_str(s: &str) -> Result<Self, Self::Err> {
internal_from_str(s, Awi::zero)
}
}