dvb-si 13.0.0

//! VBI Data Descriptor — ETSI EN 300 468 §6.2.47 (tag 0x45).
//!
//! Table 106 (PDF p. 110). Carried in PMT ES_info for an elementary stream
//! carrying VBI data (per ETSI EN 301 775). Body is a loop of entries, each a
//! `data_service_id` byte + an 8-bit `data_service_descriptor_length` + that
//! many service-descriptor bytes.
//!
//! The first loop level (data_service_id + length-delimited service block) is
//! typed. For `data_service_id` values `0x01`–`0x02`, `0x04`–`0x07` (Table 106/107), each
//! service-descriptor byte encodes `reserved(2)|field_parity(1)|line_offset(5)`;
//! other values are kept as raw reserved bytes.

use super::descriptor_body;
use crate::error::{Error, Result};
use alloc::vec::Vec;
use broadcast_common::len::need_out;
use broadcast_common::{Parse, Serialize};

/// Descriptor tag for VBI_data_descriptor.
pub const TAG: u8 = 0x45;
const HEADER_LEN: usize = 2;
const ENTRY_HEADER_LEN: usize = 2;
const MAX_BODY_LEN: usize = u8::MAX as usize;
const MAX_SERVICE_LEN: usize = u8::MAX as usize;
const LINE_RESERVED_SHIFT: u8 = 6;
const LINE_RESERVED_MASK: u8 = 0xC0;
const LINE_PARITY_MASK: u8 = 0x20;
const LINE_OFFSET_MASK: u8 = 0x1F;
/// Spec default of the per-line `reserved_future_use`(2) (`reserved` before
/// V1.17.1): all ones (EN 300 468 V1.4.1-V1.20.1 Table 106; audit
/// `private/specs-verified/dvb/dvb-si/reserved-bits-edition-audit.md` §6.1, class B: renamed only).
pub const LINE_RESERVED_FUTURE_USE_DEFAULT: u8 = 0b11;

/// Per-service-descriptor content, keyed by `data_service_id`.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "yoke", derive(yoke::Yokeable))]
#[non_exhaustive]
pub enum VbiService<'a> {
    /// `data_service_id` 0x01–0x02, 0x04–0x07: each byte is
    /// `reserved_future_use(2)|field_parity(1)|line_offset(5)` (Table 106).
    Lines(Vec<VbiLine>),
    /// `data_service_id` 0x00, 0x03, or 0x08+: raw reserved bytes.
    Reserved(&'a [u8]),
}

/// One VBI line entry (Table 106 per-byte layout for ids 0x01–0x07).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
pub struct VbiLine {
    /// `reserved_future_use`(2) at the top of the line byte (2 bits,
    /// right-aligned). Captured on parse, re-emitted verbatim;
    /// [`VbiLine::new`] defaults to [`LINE_RESERVED_FUTURE_USE_DEFAULT`].
    pub reserved_future_use: u8,
    /// `field_parity` (1 bit) — `[5]` of the service-descriptor byte.
    pub field_parity: bool,
    /// `line_offset` (5 bits) — `[4:0]` of the service-descriptor byte.
    pub line_offset: u8,
}

impl VbiLine {
    /// Build a line entry with the spec-default reserved bits (all ones).
    #[must_use]
    pub const fn new(field_parity: bool, line_offset: u8) -> Self {
        Self {
            reserved_future_use: LINE_RESERVED_FUTURE_USE_DEFAULT,
            field_parity,
            line_offset,
        }
    }
}

/// One VBI data service entry.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "yoke", derive(yoke::Yokeable))]
pub struct VbiDataEntry<'a> {
    /// data_service_id (EN 300 468 Table 107): 0x01 = EBU teletext,
    /// 0x02 = inverted teletext, 0x04 = VPS, 0x05 = WSS, 0x06 = closed
    /// captioning, 0x07 = monochrome 4:2:2 samples; others reserved/user.
    pub data_service_id: u8,
    /// Per-service content, typed for ids 0x01–0x02, 0x04–0x07.
    pub service_descriptor: VbiService<'a>,
}

/// VBI Data Descriptor.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "yoke", derive(yoke::Yokeable))]
pub struct VbiDataDescriptor<'a> {
    /// Service entries in wire order.
    pub entries: Vec<VbiDataEntry<'a>>,
}

impl<'a> Parse<'a> for VbiDataDescriptor<'a> {
    type Error = crate::error::Error;
    fn parse(bytes: &'a [u8]) -> Result<Self> {
        let body = descriptor_body(
            bytes,
            TAG,
            "VbiDataDescriptor",
            "unexpected tag for VBI_data_descriptor",
        )?;
        let mut entries = Vec::new();
        let mut pos = 0;
        while pos < body.len() {
            if pos + ENTRY_HEADER_LEN > body.len() {
                return Err(Error::InvalidDescriptor {
                    tag: TAG,
                    reason: "truncated VBI data entry header",
                });
            }
            let data_service_id = body[pos];
            let svc_len = body[pos + 1] as usize;
            pos += ENTRY_HEADER_LEN;
            if pos + svc_len > body.len() {
                return Err(Error::InvalidDescriptor {
                    tag: TAG,
                    reason: "data_service_descriptor_length exceeds descriptor body",
                });
            }
            let svc_bytes = &body[pos..pos + svc_len];
            pos += svc_len;
            let service_descriptor = if matches!(data_service_id, 0x01 | 0x02 | 0x04..=0x07) {
                let lines = svc_bytes
                    .iter()
                    .map(|&b| VbiLine {
                        reserved_future_use: (b & LINE_RESERVED_MASK) >> LINE_RESERVED_SHIFT,
                        field_parity: (b & LINE_PARITY_MASK) != 0,
                        line_offset: b & LINE_OFFSET_MASK,
                    })
                    .collect();
                VbiService::Lines(lines)
            } else {
                VbiService::Reserved(svc_bytes)
            };
            entries.push(VbiDataEntry {
                data_service_id,
                service_descriptor,
            });
        }
        Ok(Self { entries })
    }
}

impl Serialize for VbiDataDescriptor<'_> {
    type Error = crate::error::Error;
    fn serialized_len(&self) -> usize {
        HEADER_LEN
            + self
                .entries
                .iter()
                .map(|e| {
                    ENTRY_HEADER_LEN
                        + match &e.service_descriptor {
                            VbiService::Lines(lines) => lines.len(),
                            VbiService::Reserved(b) => b.len(),
                        }
                })
                .sum::<usize>()
    }

    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
        let len = self.serialized_len();
        need_out(buf, len)?;
        let body_len = len - HEADER_LEN;
        if body_len > MAX_BODY_LEN {
            return Err(Error::InvalidDescriptor {
                tag: TAG,
                reason: "VBI_data_descriptor body exceeds 255 bytes",
            });
        }
        crate::descriptors::write_descriptor_header(buf, TAG, body_len)?;
        let mut pos = HEADER_LEN;
        for e in &self.entries {
            let svc_len = match &e.service_descriptor {
                VbiService::Lines(lines) => lines.len(),
                VbiService::Reserved(b) => b.len(),
            };
            if svc_len > MAX_SERVICE_LEN {
                return Err(Error::InvalidDescriptor {
                    tag: TAG,
                    reason: "service_descriptor exceeds 255 bytes (8-bit length field)",
                });
            }
            buf[pos] = e.data_service_id;
            buf[pos + 1] = svc_len as u8;
            pos += ENTRY_HEADER_LEN;
            match &e.service_descriptor {
                VbiService::Lines(lines) => {
                    for line in lines {
                        buf[pos] = (broadcast_common::len::fit_mask(
                            line.reserved_future_use,
                            LINE_RESERVED_MASK >> LINE_RESERVED_SHIFT,
                            "reserved_future_use",
                        )? << LINE_RESERVED_SHIFT)
                            | (u8::from(line.field_parity) << 5)
                            | broadcast_common::len::fit_mask(
                                line.line_offset,
                                LINE_OFFSET_MASK,
                                "line_offset",
                            )?;
                        pos += 1;
                    }
                }
                VbiService::Reserved(b) => {
                    buf[pos..pos + b.len()].copy_from_slice(b);
                    pos += b.len();
                }
            }
        }
        Ok(len)
    }
}
impl<'a> crate::traits::DescriptorDef<'a> for VbiDataDescriptor<'a> {
    const TAG: u8 = TAG;
    const NAME: &'static str = "VBI_DATA";
}

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

    #[test]
    fn parse_single_entry() {
        // data_service_id=0x01 (EBU teletext), 2 line bytes: 0xC1, 0xC2
        // 0xC1 = reserved(2)=11 | field_parity=0 | line_offset=00001 → fp=false, lo=1
        // 0xC2 = reserved(2)=11 | field_parity=0 | line_offset=00010 → fp=false, lo=2
        let bytes = [TAG, 4, 0x01, 0x02, 0xC1, 0xC2];
        let d = VbiDataDescriptor::parse(&bytes).unwrap();
        assert_eq!(d.entries.len(), 1);
        assert_eq!(d.entries[0].data_service_id, 0x01);
        match &d.entries[0].service_descriptor {
            VbiService::Lines(lines) => {
                assert_eq!(lines.len(), 2);
                assert!(!lines[0].field_parity);
                assert_eq!(lines[0].line_offset, 0x01);
                assert!(!lines[1].field_parity);
                assert_eq!(lines[1].line_offset, 0x02);
            }
            other => panic!("expected Lines, got {other:?}"),
        }
    }

    #[test]
    fn parse_multiple_entries() {
        // 0xAA = 10_1_01010 → fp=true, lo=0x0A=10
        // 0xBB = 10_1_11011 → fp=true, lo=0x1B=27
        // 0xCC = 11_0_01100 → fp=false, lo=0x0C=12
        let bytes = [TAG, 7, 0x04, 0x01, 0xAA, 0x05, 0x02, 0xBB, 0xCC];
        let d = VbiDataDescriptor::parse(&bytes).unwrap();
        assert_eq!(d.entries.len(), 2);
        assert_eq!(d.entries[0].data_service_id, 0x04);
        match &d.entries[0].service_descriptor {
            VbiService::Lines(lines) => {
                assert_eq!(lines.len(), 1);
                assert!(lines[0].field_parity);
                assert_eq!(lines[0].line_offset, 0x0A);
            }
            other => panic!("expected Lines, got {other:?}"),
        }
        assert_eq!(d.entries[1].data_service_id, 0x05);
        match &d.entries[1].service_descriptor {
            VbiService::Lines(lines) => {
                assert_eq!(lines.len(), 2);
                assert!(lines[0].field_parity);
                assert_eq!(lines[0].line_offset, 0x1B);
                assert!(!lines[1].field_parity);
                assert_eq!(lines[1].line_offset, 0x0C);
            }
            other => panic!("expected Lines, got {other:?}"),
        }
    }

    #[test]
    fn parse_entry_with_empty_service_block() {
        let bytes = [TAG, 2, 0x06, 0x00];
        let d = VbiDataDescriptor::parse(&bytes).unwrap();
        assert_eq!(d.entries.len(), 1);
        match &d.entries[0].service_descriptor {
            VbiService::Lines(lines) => assert!(lines.is_empty()),
            other => panic!("expected Lines, got {other:?}"),
        }
    }

    #[test]
    fn parse_reserved_data_service_id() {
        let bytes = [TAG, 4, 0x00, 0x02, 0xDE, 0xAD];
        let d = VbiDataDescriptor::parse(&bytes).unwrap();
        assert_eq!(d.entries.len(), 1);
        assert_eq!(d.entries[0].data_service_id, 0x00);
        match &d.entries[0].service_descriptor {
            VbiService::Reserved(b) => assert_eq!(*b, &[0xDE, 0xAD]),
            other => panic!("expected Reserved, got {other:?}"),
        }
    }

    #[test]
    fn parse_rejects_wrong_tag() {
        assert!(matches!(
            VbiDataDescriptor::parse(&[0x46, 0]).unwrap_err(),
            Error::InvalidDescriptor { tag: 0x46, .. }
        ));
    }

    #[test]
    fn parse_rejects_short_buffer() {
        // declares 4 body bytes, only 2 present
        let bytes = [TAG, 4, 0x01, 0x02];
        assert!(matches!(
            VbiDataDescriptor::parse(&bytes).unwrap_err(),
            Error::BufferTooShort(..)
        ));
    }

    #[test]
    fn parse_rejects_inner_length_overrun() {
        // entry declares 5 service bytes but only 1 remains in body
        let bytes = [TAG, 3, 0x01, 0x05, 0xAA];
        assert!(matches!(
            VbiDataDescriptor::parse(&bytes).unwrap_err(),
            Error::InvalidDescriptor { tag: TAG, .. }
        ));
    }

    #[test]
    fn empty_descriptor_valid() {
        let d = VbiDataDescriptor::parse(&[TAG, 0]).unwrap();
        assert!(d.entries.is_empty());
    }

    #[test]
    fn serialize_round_trip() {
        let d = VbiDataDescriptor {
            entries: vec![
                VbiDataEntry {
                    data_service_id: 0x01,
                    service_descriptor: VbiService::Lines(vec![
                        VbiLine::new(false, 0x01),
                        VbiLine::new(false, 0x02),
                        VbiLine::new(false, 0x03),
                    ]),
                },
                VbiDataEntry {
                    data_service_id: 0x04,
                    service_descriptor: VbiService::Lines(vec![]),
                },
            ],
        };
        let mut buf = vec![0u8; d.serialized_len()];
        d.serialize_into(&mut buf).unwrap();
        assert_eq!(VbiDataDescriptor::parse(&buf).unwrap(), d);
    }

    #[test]
    fn serialize_round_trip_reserved() {
        let d = VbiDataDescriptor {
            entries: vec![VbiDataEntry {
                data_service_id: 0x80,
                service_descriptor: VbiService::Reserved(&[0xDE, 0xAD]),
            }],
        };
        let mut buf = vec![0u8; d.serialized_len()];
        d.serialize_into(&mut buf).unwrap();
        assert_eq!(VbiDataDescriptor::parse(&buf).unwrap(), d);
    }

    #[test]
    fn byte_identity_with_reserved_bits() {
        let bytes = [TAG, 4, 0x01, 0x02, 0xC1, 0xC2];
        let d = VbiDataDescriptor::parse(&bytes).unwrap();
        let mut buf = vec![0u8; d.serialized_len()];
        d.serialize_into(&mut buf).unwrap();
        assert_eq!(buf, bytes);
    }

    /// Every line byte (all 256 values, so every reserved(2) value) round-trips.
    #[test]
    fn reserved_preserved_for_every_byte() {
        for b in 0..=0xFFu8 {
            let bytes = [TAG, 3, 0x01, 0x01, b];
            let d = VbiDataDescriptor::parse(&bytes).unwrap();
            match &d.entries[0].service_descriptor {
                VbiService::Lines(l) => assert_eq!(l[0].reserved_future_use, b >> 6),
                other => panic!("expected Lines, got {other:?}"),
            }
            let mut buf = vec![0u8; d.serialized_len()];
            d.serialize_into(&mut buf).unwrap();
            assert_eq!(buf, bytes);
        }
    }

    #[test]
    fn default_is_spec_value() {
        let d = VbiDataDescriptor {
            entries: vec![VbiDataEntry {
                data_service_id: 0x01,
                service_descriptor: VbiService::Lines(vec![VbiLine::new(true, 0x0A)]),
            }],
        };
        let mut buf = vec![0u8; d.serialized_len()];
        d.serialize_into(&mut buf).unwrap();
        assert_eq!(buf, [TAG, 3, 0x01, 0x01, 0xEA]);
    }

    #[test]
    fn data_service_id_0x03_is_reserved() {
        let bytes = [TAG, 3, 0x03, 0x01, 0xAA];
        let d = VbiDataDescriptor::parse(&bytes).unwrap();
        assert_eq!(d.entries[0].data_service_id, 0x03);
        match &d.entries[0].service_descriptor {
            VbiService::Reserved(b) => assert_eq!(*b, &[0xAA]),
            other => panic!("expected Reserved for id 0x03, got {other:?}"),
        }
    }

    #[test]
    fn serialize_rejects_small_buffer() {
        let d = VbiDataDescriptor {
            entries: vec![VbiDataEntry {
                data_service_id: 0x01,
                service_descriptor: VbiService::Lines(vec![VbiLine::new(false, 0x0A)]),
            }],
        };
        let mut tiny = [0u8; 3];
        assert!(matches!(
            d.serialize_into(&mut tiny).unwrap_err(),
            Error::OutputBufferTooSmall(..)
        ));
    }

    #[cfg(feature = "serde")]
    #[test]
    fn serde_serialize_stable() {
        // Borrowed-byte fields cannot deserialize from a JSON array (serde_json
        // requires a borrowed-str for &[u8]); assert the Serialize half is
        // stable, matching the other borrowed descriptors (e.g.
        // content_identifier) in this crate.
        let make = || VbiDataDescriptor {
            entries: vec![VbiDataEntry {
                data_service_id: 0x01,
                service_descriptor: VbiService::Lines(vec![
                    VbiLine::new(false, 0x01),
                    VbiLine::new(false, 0x02),
                ]),
            }],
        };
        let json = serde_json::to_string(&make()).unwrap();
        assert!(json.contains("data_service_id"));
        assert_eq!(json, serde_json::to_string(&make()).unwrap());
    }
}