smart-package-tracker 0.4.0

//! Code 128 encoding and decoding.
//!
//! Wraps the [`code128`](https://docs.rs/code128) crate, which implements
//! ISO/IEC 15417 including automatic character-set selection — digit runs are
//! compressed into Set C without the caller having to ask, which matters for
//! the long numeric payloads carriers use.
//!
//! The upstream crate reports bar coordinates with its own 10-module quiet
//! zone already applied. This module strips that offset so a [`Symbol`] holds
//! the symbol and nothing else, leaving quiet zones to
//! [`RenderOptions`](crate::RenderOptions).

use alloc::string::{String, ToString};
use alloc::vec;
use alloc::vec::Vec;

use super::{BitMatrix, Decoder, Symbol, Symbology, SymbologyKind};
use crate::error::{Error, Result};

/// Quiet zone baked into `code128`'s coordinate space, in modules per side.
const UPSTREAM_QUIET_ZONE: u32 = 10;

/// The Code 128 symbology.
///
/// # Examples
///
/// ```
/// use smart_package_tracker::symbology::{Code128, Symbology};
///
/// let symbol = Code128.encode("PKG-9ED9285C")?;
/// assert!(symbol.is_linear());
/// assert_eq!(symbol.modules().height(), 1);
/// # Ok::<(), smart_package_tracker::Error>(())
/// ```
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
pub struct Code128;

impl Symbology for Code128 {
    fn kind(&self) -> SymbologyKind {
        SymbologyKind::Code128
    }

    fn encode(&self, data: &str) -> Result<Symbol> {
        if data.is_empty() {
            return Err(Error::EmptyPayload);
        }

        let code = ::code128::Code128::encode_str(data).ok_or_else(|| Error::Unencodable {
            symbology: SymbologyKind::Code128.name(),
            reason: "payload contains characters outside ISO/IEC 8859-1 (Latin-1)".to_string(),
        })?;

        // `len()` counts the quiet zone on both sides; the symbol itself is
        // what remains.
        let total = code.len() as u32;
        let width = total
            .checked_sub(2 * UPSTREAM_QUIET_ZONE)
            .filter(|w| *w > 0)
            .ok_or_else(|| Error::Unencodable {
                symbology: SymbologyKind::Code128.name(),
                reason: "encoder produced a degenerate symbol".to_string(),
            })?;

        let mut row = vec![false; width as usize];
        for bar in code.bar_coordinates() {
            let start = bar.x.saturating_sub(UPSTREAM_QUIET_ZONE) as usize;
            // Clamp both ends, not just the far one: a bar reported at or past
            // the trailing quiet zone would otherwise slice backwards and
            // panic. Upstream does not emit one today; this keeps a version
            // bump from turning that into a crash.
            if start >= row.len() {
                continue;
            }
            let end = (start + bar.width as usize).min(row.len());
            row[start..end].fill(true);
        }

        Ok(Symbol::new(
            SymbologyKind::Code128,
            BitMatrix::from_row(row),
            data.to_string(),
        ))
    }
}

impl Decoder for Code128 {
    fn kind(&self) -> SymbologyKind {
        SymbologyKind::Code128
    }

    fn decode(&self, modules: &BitMatrix) -> Result<String> {
        if modules.height() != 1 {
            return Err(Error::Decode(
                "expected a single-row linear symbol".to_string(),
            ));
        }

        let bars = to_bars(modules.row(0));
        if bars.is_empty() {
            return Err(Error::Decode("symbol contains no bars".to_string()));
        }

        let bytes = ::code128::decode(&bars).map_err(|e| Error::Decode(alloc::format!("{e:?}")))?;

        // The decoder returns Latin-1 bytes; widening each byte to a `char` is
        // the exact inverse of the encoder's Latin-1 narrowing.
        Ok(bytes.into_iter().map(|b| b as char).collect())
    }
}

/// Decode a Code 128 [`Symbol`] back into its payload.
///
/// This reconstructs bar/space runs from the module grid and hands them to the
/// upstream decoder, so it exercises the same conversion the renderers rely
/// on. That makes it a genuine round-trip check rather than a trivial identity
/// on the stored payload.
///
/// # Errors
///
/// Returns [`Error::Decode`] if the symbol is not a linear Code 128 symbol, or
/// if the module pattern is not a valid Code 128 sequence.
pub fn decode(symbol: &Symbol) -> Result<String> {
    if symbol.kind() != SymbologyKind::Code128 {
        return Err(Error::Decode(alloc::format!(
            "expected a Code 128 symbol, found {}",
            symbol.kind()
        )));
    }

    Code128.decode(symbol.modules())
}

/// Convert a module row into the bar/space runs the upstream decoder expects.
fn to_bars(row: &[bool]) -> Vec<::code128::Bar> {
    let mut bars = Vec::new();
    let mut i = 0;

    while i < row.len() {
        if !row[i] {
            i += 1;
            continue;
        }
        let bar_start = i;
        while i < row.len() && row[i] {
            i += 1;
        }
        let width = (i - bar_start) as u8;

        let space_start = i;
        while i < row.len() && !row[i] {
            i += 1;
        }
        let space = (i - space_start) as u8;

        bars.push(::code128::Bar { width, space });
    }

    bars
}

#[cfg(test)]
mod tests {
    use super::*;
    use alloc::format;

    /// Published Code 128 start patterns (11 modules each).
    const START_A: &str = "11010000100";
    const START_B: &str = "11010010000";
    const START_C: &str = "11010011100";
    /// Published Code 128 stop pattern (13 modules, including the two extra
    /// termination bars).
    const STOP: &str = "1100011101011";

    fn as_bits(symbol: &Symbol) -> String {
        symbol
            .modules()
            .row(0)
            .iter()
            .map(|d| if *d { '1' } else { '0' })
            .collect()
    }

    #[test]
    fn starts_with_a_valid_start_pattern() {
        let bits = as_bits(&Code128.encode("PKG-9ED9285C").unwrap());
        let start = &bits[..11];
        assert!(
            start == START_A || start == START_B || start == START_C,
            "unexpected start pattern {start}"
        );
    }

    #[test]
    fn numeric_payloads_use_the_set_c_start_pattern() {
        // A pure digit run should be encoded two digits per symbol.
        let bits = as_bits(&Code128.encode("1234567890").unwrap());
        assert_eq!(&bits[..11], START_C, "digit runs should start in Set C");
    }

    #[test]
    fn ends_with_the_stop_pattern() {
        let bits = as_bits(&Code128.encode("PKG-9ED9285C").unwrap());
        assert!(bits.ends_with(STOP), "missing or malformed stop pattern");
    }

    #[test]
    fn width_is_a_whole_number_of_symbols_plus_the_stop_bars() {
        // Every Code 128 character occupies 11 modules; the stop pattern adds
        // two more.
        let bits = as_bits(&Code128.encode("PKG-9ED9285C").unwrap());
        assert_eq!(
            (bits.len() - 2) % 11,
            0,
            "symbol width {} is not 11n + 2",
            bits.len()
        );
    }

    #[test]
    fn set_c_halves_the_width_of_long_digit_runs() {
        let digits = "12345678901234567890"; // 20 digits
        let letters = "ABCDEFGHIJKLMNOPQRST"; // 20 letters
        let numeric = Code128.encode(digits).unwrap().modules().width();
        let alpha = Code128.encode(letters).unwrap().modules().width();
        assert!(
            numeric < alpha,
            "Set C compression not applied: {numeric} modules vs {alpha}"
        );
    }

    #[test]
    fn round_trips_through_the_module_grid() {
        for payload in [
            "PKG-9ED9285C",
            "1234567890123456789012",
            "A",
            "Mixed 123 Case!",
            "~$%^&*()_+",
        ] {
            let symbol = Code128.encode(payload).unwrap();
            let decoded = decode(&symbol).unwrap_or_else(|e| panic!("{payload}: {e}"));
            assert_eq!(decoded, payload);
        }
    }

    #[test]
    fn rejects_an_empty_payload() {
        assert!(matches!(Code128.encode(""), Err(Error::EmptyPayload)));
    }

    #[test]
    fn rejects_characters_outside_latin1() {
        let err = Code128.encode("PKG-\u{4e2d}\u{6587}").unwrap_err();
        assert!(matches!(err, Error::Unencodable { .. }), "got {err:?}");
    }

    #[test]
    fn quiet_zone_is_not_part_of_the_symbol() {
        let symbol = Code128.encode("A").unwrap();
        let row = symbol.modules().row(0);
        assert!(row[0], "symbol must begin with a bar, not a quiet zone");
        assert!(
            *row.last().unwrap(),
            "symbol must end with a bar, not a quiet zone"
        );
    }

    #[test]
    fn payload_is_preserved_on_the_symbol() {
        let symbol = Code128.encode("PKG-9ED9285C").unwrap();
        assert_eq!(symbol.payload(), "PKG-9ED9285C");
        assert_eq!(format!("{}", symbol.kind()), "Code 128");
    }
}