use std::fmt;
pub(crate) fn ascii_string<'a>(
bytes: &'a [u8],
format: crate::Format,
backend: &str,
time: crate::Time,
) -> crate::Result<&'a str> {
if !bytes.is_ascii() {
return Err(crate::Error::NonAsciiString {
format,
backend: backend.into(),
time,
});
}
Ok(std::str::from_utf8(bytes).expect("ASCII is valid UTF-8"))
}
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
pub enum ValueRef<'a> {
Bits(
BitsRef<'a>,
),
Real(
f64,
),
String(
&'a str,
),
Event {
occurrences: u64,
},
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum Value {
Bits(
Bits,
),
Real(
f64,
),
String(
Box<str>,
),
Event {
occurrences: u64,
},
}
impl ValueRef<'_> {
pub(crate) fn same_value(self, other: ValueRef<'_>) -> bool {
match (self, other) {
(Self::Bits(left), ValueRef::Bits(right)) => left == right,
(Self::Real(left), ValueRef::Real(right)) => left.to_bits() == right.to_bits(),
(Self::String(left), ValueRef::String(right)) => left == right,
(Self::Event { occurrences: left }, ValueRef::Event { occurrences: right }) => {
left == right
}
_ => false,
}
}
pub fn to_owned(self) -> Value {
match self {
Self::Bits(bits) => Value::Bits(bits.to_owned()),
Self::Real(real) => Value::Real(real),
Self::String(string) => Value::String(string.into()),
Self::Event { occurrences } => Value::Event { occurrences },
}
}
}
impl Value {
#[cfg(test)]
pub(crate) fn same_value(&self, other: &Self) -> bool {
self.as_ref().same_value(other.as_ref())
}
pub fn as_ref(&self) -> ValueRef<'_> {
match self {
Self::Bits(bits) => ValueRef::Bits(bits.as_ref()),
Self::Real(real) => ValueRef::Real(*real),
Self::String(string) => ValueRef::String(string),
Self::Event { occurrences } => ValueRef::Event {
occurrences: *occurrences,
},
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Logic {
Zero,
One,
X,
Z,
H,
U,
W,
L,
DontCare,
}
impl Logic {
fn from_ascii(byte: u8) -> Option<Self> {
match byte.to_ascii_lowercase() {
b'0' => Some(Self::Zero),
b'1' => Some(Self::One),
b'x' => Some(Self::X),
b'z' => Some(Self::Z),
b'h' => Some(Self::H),
b'u' => Some(Self::U),
b'w' => Some(Self::W),
b'l' => Some(Self::L),
b'-' => Some(Self::DontCare),
_ => None,
}
}
}
#[derive(Debug, Clone, Copy)]
pub struct BitsRef<'a> {
data: &'a [u8],
}
#[derive(Debug, Clone)]
pub struct Bits {
data: Box<[u8]>,
}
impl PartialEq<BitsRef<'_>> for BitsRef<'_> {
fn eq(&self, other: &BitsRef<'_>) -> bool {
self.data.eq_ignore_ascii_case(other.data)
}
}
impl Eq for BitsRef<'_> {}
impl PartialEq for Bits {
fn eq(&self, other: &Self) -> bool {
self.as_ref() == other.as_ref()
}
}
impl Eq for Bits {}
impl PartialEq<BitsRef<'_>> for Bits {
fn eq(&self, other: &BitsRef<'_>) -> bool {
self.as_ref() == *other
}
}
impl PartialEq<Bits> for BitsRef<'_> {
fn eq(&self, other: &Bits) -> bool {
*self == other.as_ref()
}
}
impl<'a> BitsRef<'a> {
pub(crate) fn from_ascii(bytes: &'a [u8]) -> Option<Self> {
u32::try_from(bytes.len()).ok()?;
bytes
.iter()
.all(|&byte| {
matches!(
byte.to_ascii_lowercase(),
b'0' | b'1' | b'x' | b'z' | b'h' | b'u' | b'w' | b'l' | b'-'
)
})
.then_some(Self { data: bytes })
}
pub(crate) fn from_validated_ascii(bytes: &'a [u8]) -> Self {
debug_assert!(Self::from_ascii(bytes).is_some());
Self { data: bytes }
}
pub(crate) fn ascii(self) -> &'a [u8] {
self.data
}
pub(crate) fn slice(self, msb: u32, lsb: u32) -> Self {
let end = self.data.len() - lsb as usize;
let start = self.data.len() - msb as usize - 1;
Self {
data: &self.data[start..end],
}
}
pub fn width(self) -> u32 {
self.data.len() as u32
}
pub fn bit(self, index: u32) -> Option<Logic> {
let offset = self
.data
.len()
.checked_sub(index as usize)?
.checked_sub(1)?;
Logic::from_ascii(self.data[offset])
}
pub fn iter_msb(self) -> impl ExactSizeIterator<Item = Logic> + 'a {
self.data
.iter()
.map(|&byte| Logic::from_ascii(byte).expect("validated logic byte"))
}
pub fn iter_lsb(self) -> impl ExactSizeIterator<Item = Logic> + 'a {
self.data
.iter()
.rev()
.map(|&byte| Logic::from_ascii(byte).expect("validated logic byte"))
}
pub fn to_owned(self) -> Bits {
Bits {
data: self.data.iter().map(u8::to_ascii_lowercase).collect(),
}
}
}
impl fmt::Display for BitsRef<'_> {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
if !self.data.iter().any(u8::is_ascii_uppercase) {
return formatter
.write_str(std::str::from_utf8(self.data).expect("validated logic bytes"));
}
let mut buffer = [0; 256];
for chunk in self.data.chunks(buffer.len()) {
let lowered = &mut buffer[..chunk.len()];
lowered.copy_from_slice(chunk);
lowered.make_ascii_lowercase();
formatter.write_str(std::str::from_utf8(lowered).expect("validated logic bytes"))?;
}
Ok(())
}
}
impl Bits {
pub(crate) fn from_validated_ascii(mut bytes: Vec<u8>) -> Self {
debug_assert!(BitsRef::from_ascii(&bytes).is_some());
bytes.make_ascii_lowercase();
Self {
data: bytes.into_boxed_slice(),
}
}
#[cfg(test)]
pub(crate) fn from_ascii(bytes: &[u8]) -> Option<Self> {
BitsRef::from_ascii(bytes).map(BitsRef::to_owned)
}
pub fn width(&self) -> u32 {
self.as_ref().width()
}
pub fn as_ref(&self) -> BitsRef<'_> {
BitsRef { data: &self.data }
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn sample_strings_preserve_all_ascii_and_reject_other_octets() {
let bytes: Vec<_> = (0..=127).collect();
assert_eq!(
ascii_string(&bytes, crate::Format::Shm, "shm-lib", crate::Time::ZERO)
.unwrap()
.as_bytes(),
bytes
);
for bytes in [
vec![128],
vec![255],
"é".as_bytes().to_vec(),
vec![b'a', 0, 128],
] {
assert!(
matches!(ascii_string(&bytes, crate::Format::Shm, "shm-lib", crate::Time::from_ticks(9)),
Err(crate::Error::NonAsciiString { format: crate::Format::Shm, backend, time })
if backend == "shm-lib" && time.ticks() == 9)
);
}
}
#[test]
fn ascii_states_and_iteration() {
let bits = BitsRef::from_ascii(b"01XZHUWL-").unwrap();
let expected = [
Logic::Zero,
Logic::One,
Logic::X,
Logic::Z,
Logic::H,
Logic::U,
Logic::W,
Logic::L,
Logic::DontCare,
];
assert_eq!(bits.width(), 9);
assert_eq!(bits.to_string(), "01xzhuwl-");
assert_eq!(bits.iter_msb().collect::<Vec<_>>(), expected);
assert_eq!(
bits.iter_lsb().collect::<Vec<_>>(),
expected.into_iter().rev().collect::<Vec<_>>()
);
let mut iter = bits.iter_msb();
assert_eq!(iter.len(), 9);
assert_eq!(iter.next(), Some(Logic::Zero));
assert_eq!(iter.len(), 8);
let mut iter = bits.iter_lsb();
assert_eq!(iter.len(), 9);
assert_eq!(iter.next(), Some(Logic::DontCare));
assert_eq!(iter.len(), 8);
for index in 0..9 {
assert_eq!(bits.bit(index), Some(expected[8 - index as usize]));
}
assert_eq!(bits.bit(9), None);
assert_eq!(bits.bit(u32::MAX), None);
assert!(BitsRef::from_ascii(b"10?").is_none());
assert!(Bits::from_ascii(b"\xff").is_none());
for byte in u8::MIN..=u8::MAX {
assert_eq!(
BitsRef::from_ascii(&[byte]).is_some(),
Logic::from_ascii(byte).is_some(),
"byte {byte}"
);
}
let empty = BitsRef::from_ascii(b"").unwrap();
assert_eq!(empty.width(), 0);
assert_eq!(empty.bit(0), None);
assert_eq!(empty.iter_msb().len(), 0);
assert_eq!(empty.iter_lsb().len(), 0);
assert_eq!(empty.to_string(), "");
}
#[test]
fn slices_and_owned_storage() {
let mut source = b"01XZHUWL-".to_vec();
let owned = {
let bits = BitsRef::from_ascii(&source).unwrap();
assert_eq!(bits.slice(8, 0).to_string(), "01xzhuwl-");
assert_eq!(bits.slice(0, 0).to_string(), "-");
assert_eq!(bits.slice(8, 8).to_string(), "0");
assert_eq!(bits.slice(6, 2).to_string(), "xzhuw");
let nested = bits.slice(6, 2).slice(3, 1);
assert_eq!(nested.width(), 3);
assert_eq!(nested.to_string(), "zhu");
assert_eq!(nested.bit(0), Some(Logic::U));
nested.to_owned()
};
source.fill(b'0');
assert_eq!(owned.width(), 3);
assert_eq!(owned.as_ref().to_string(), "zhu");
assert_eq!(
Bits::from_ascii(b"XzU").unwrap().as_ref().to_string(),
"xzu"
);
}
#[test]
fn owned_validated_bits_keep_all_nine_states() {
let bits = Bits::from_validated_ascii(b"01XZHUWL-".to_vec());
assert_eq!(bits.width(), 9);
assert_eq!(bits.as_ref().to_string(), "01xzhuwl-");
assert_eq!(
bits.as_ref().iter_msb().collect::<Vec<_>>(),
[
Logic::Zero,
Logic::One,
Logic::X,
Logic::Z,
Logic::H,
Logic::U,
Logic::W,
Logic::L,
Logic::DontCare
]
);
assert_eq!(bits, BitsRef::from_ascii(b"01xzhuwl-").unwrap());
}
#[test]
fn values_round_trip_and_compare() {
let bits = ValueRef::Bits(BitsRef::from_ascii(b"01X").unwrap()).to_owned();
assert!(bits.same_value(&Value::Bits(Bits::from_ascii(b"01x").unwrap())));
assert!(ValueRef::Bits(BitsRef::from_ascii(b"01X").unwrap()).same_value(bits.as_ref()));
assert!(!bits.same_value(&Value::Bits(Bits::from_ascii(b"01z").unwrap())));
assert!(!bits.same_value(&Value::Bits(Bits::from_ascii(b"1x").unwrap())));
match bits.as_ref() {
ValueRef::Bits(view) => assert_eq!(view.to_string(), "01x"),
_ => panic!("expected bits"),
}
let text = {
let source = String::from("retained string");
ValueRef::String(&source).to_owned()
};
assert!(matches!(text.as_ref(), ValueRef::String("retained string")));
assert!(text.same_value(&text.as_ref().to_owned()));
assert!(!text.same_value(&Value::String("different".into())));
let real = ValueRef::Real(3.5).to_owned();
assert!(matches!(real.as_ref(), ValueRef::Real(3.5)));
assert!(real.same_value(&real.as_ref().to_owned()));
let event = ValueRef::Event { occurrences: 7 }.to_owned();
assert!(matches!(event.as_ref(), ValueRef::Event { occurrences: 7 }));
assert!(event.same_value(&event.as_ref().to_owned()));
assert!(!event.same_value(&Value::Event { occurrences: 1 }));
assert!(!real.same_value(&text));
assert!(!event.same_value(&real));
}
#[test]
fn real_identity_and_conversion_preserve_bits() {
let patterns = [
0x7ff8_0000_0000_0001, 0x7ff8_0000_0000_0002, 0xfff8_0000_0000_0001, 0x7ff0_0000_0000_0001, 0.0f64.to_bits(),
(-0.0f64).to_bits(),
f64::INFINITY.to_bits(),
f64::NEG_INFINITY.to_bits(),
3.5f64.to_bits(),
];
for left in patterns {
let value = ValueRef::Real(f64::from_bits(left));
let owned = value.to_owned();
let ValueRef::Real(real) = owned.as_ref() else {
panic!("expected real")
};
assert_eq!(real.to_bits(), left);
for right in patterns {
let other = Value::Real(f64::from_bits(right));
assert_eq!(value.same_value(other.as_ref()), left == right);
assert_eq!(owned.same_value(&other), left == right);
}
}
}
#[test]
fn bit_identity_handles_case_width_and_non_word_aligned_slices() {
for width in [0, 1, 7, 9, 63, 65, 4095] {
let upper = b"01XZHUWL-"
.iter()
.copied()
.cycle()
.take(width)
.collect::<Vec<_>>();
let lower = upper.to_ascii_lowercase();
let left = BitsRef::from_ascii(&upper).unwrap();
let right = BitsRef::from_ascii(&lower).unwrap();
check_bit_equality(left, right, true);
assert!(ValueRef::Bits(left).same_value(ValueRef::Bits(right)));
if width > 1 {
check_bit_equality(
left.slice(width as u32 - 2, 0),
right.slice(width as u32 - 2, 0),
true,
);
check_bit_equality(left, right.slice(width as u32 - 2, 0), false);
assert!(
ValueRef::Bits(left.slice(width as u32 - 2, 0))
.same_value(ValueRef::Bits(right.slice(width as u32 - 2, 0)))
);
assert!(
!ValueRef::Bits(left)
.same_value(ValueRef::Bits(right.slice(width as u32 - 2, 0)))
);
}
}
}
#[test]
fn identity_distinguishes_every_logic_state() {
for left in b"01xzhuwl-" {
for right in b"01xzhuwl-" {
let left_value = BitsRef::from_ascii(std::slice::from_ref(left)).unwrap();
let right_value = BitsRef::from_ascii(std::slice::from_ref(right)).unwrap();
check_bit_equality(left_value, right_value, left == right);
assert_eq!(
ValueRef::Bits(left_value).same_value(ValueRef::Bits(right_value)),
left == right
);
}
}
}
fn check_bit_equality(left: BitsRef<'_>, right: BitsRef<'_>, expected: bool) {
fn requires_eq<T: Eq>(_: &T) {}
let left_owned = left.to_owned();
let right_owned = right.to_owned();
requires_eq(&left);
requires_eq(&left_owned);
assert_eq!(left == right, expected);
assert_eq!(right == left, expected);
assert_eq!(left_owned == right_owned, expected);
assert_eq!(right_owned == left_owned, expected);
assert_eq!(left_owned == right, expected);
assert_eq!(right == left_owned, expected);
assert_eq!(left == right_owned, expected);
assert_eq!(right_owned == left, expected);
assert_eq!(PartialEq::eq(&left, &right), expected);
assert_eq!(PartialEq::eq(&left_owned, &right_owned), expected);
}
#[test]
fn wide_bit_display_preserves_logic_states_and_slices() {
let source = b"01XZHUWL-".repeat(129);
let expected = "01xzhuwl-".repeat(129);
let bits = BitsRef::from_ascii(&source).unwrap();
assert_eq!(bits.to_string(), expected);
assert_eq!(bits.to_owned().as_ref().to_string(), expected);
let sliced = bits.slice(1024, 3);
assert_eq!(
sliced.to_string(),
expected[expected.len() - 1025..expected.len() - 3]
);
}
#[test]
fn bit_equality_distinguishes_width_and_leading_zeros() {
for (left, right, expected) in [
("", "", true),
("", "0", false),
("0", "00", false),
("10", "0010", false),
("11", "1111", false),
("0010", "0010", true),
("0010", "0100", false),
("01XZHUWL-", "01xzhuwl-", true),
] {
check_bit_equality(
BitsRef::from_ascii(left.as_bytes()).unwrap(),
BitsRef::from_ascii(right.as_bytes()).unwrap(),
expected,
);
}
let source = BitsRef::from_ascii(b"101XZHUWL-0").unwrap();
let slice = source.slice(9, 1);
let expected = Bits::from_ascii(b"01xzhuwl-").unwrap();
assert_eq!(slice, expected);
let retained = slice.to_owned();
assert_eq!(retained, expected);
}
}