mediaframe 0.1.3

//! [`TrackOrigin`] — provenance axis for a subtitle track:
//! where the bytes come from relative to the media file.

use derive_more::{Display, IsVariant};

/// Where this subtitle track came from, relative to the media file
/// it accompanies.
///
/// Closed unit-only enum (no `Unknown` / `Other` escape): every
/// subtitle track in practice falls into exactly one of these three
/// buckets, and the wire id is stable / append-only. `Embedded` is
/// the default — the typical case is a subtitle stream multiplexed
/// inside the container.
///
/// `#[non_exhaustive]` is set anyway so a future expansion (e.g. a
/// distinct "broadcast" origin) is non-breaking.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash, Display, IsVariant)]
#[display("{}", self.as_str())]
#[non_exhaustive]
#[cfg_attr(
  feature = "quickcheck",
  derive(::quickcheck_richderive::Arbitrary),
  quickcheck(arbitrary = "crate::quickcheck_helpers::coded::track_origin")
)]
pub enum TrackOrigin {
  /// Stream multiplexed into the container alongside the video /
  /// audio tracks (e.g. an `.mkv` with embedded `.srt`-equivalent
  /// subtitle streams). The default origin.
  #[default]
  Embedded,
  /// Separate subtitle file living next to the media file on disk
  /// — typically an external `.srt` / `.vtt` / `.ass` paired with
  /// the video by filename stem.
  Sidecar,
  /// Externally sourced — downloaded from an online subtitle
  /// database, OCR'd from image-based subtitles, generated by an
  /// automatic-speech-recognition (ASR) pass, or otherwise produced
  /// outside the original media container.
  External,
}

impl TrackOrigin {
  /// Canonical lowercase slug for this origin (`"embedded"` /
  /// `"sidecar"` / `"external"`). Stable; matches what
  /// [`core::fmt::Display`] produces.
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub const fn as_str(&self) -> &'static str {
    match self {
      Self::Embedded => "embedded",
      Self::Sidecar => "sidecar",
      Self::External => "external",
    }
  }

  /// Stable `u32` wire id: `Embedded=0`, `Sidecar=1`, `External=2`.
  /// Append-only — never renumber.
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub const fn to_u32(&self) -> u32 {
    match self {
      Self::Embedded => 0,
      Self::Sidecar => 1,
      Self::External => 2,
    }
  }

  /// Decodes from the stable `u32` wire id produced by
  /// [`Self::to_u32`]. Unknown ids fall back to the default
  /// ([`Self::Embedded`]) — this is a closed enum with no lossless
  /// `Unknown(u32)` escape, so the round-trip is exact only for
  /// the enumerated ids `0`/`1`/`2`.
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub const fn from_u32(v: u32) -> Self {
    match v {
      0 => Self::Embedded,
      1 => Self::Sidecar,
      2 => Self::External,
      _ => Self::Embedded,
    }
  }

  /// Strict counterpart to [`Self::from_u32`]: returns `None` for any code
  /// outside the enumerated set, instead of silently mapping it to the
  /// default. Used by the strict deserialize path so adversarial / corrupt
  /// wire values fail loudly rather than masquerading as `Embedded`.
  #[cfg_attr(not(tarpaulin), inline(always))]
  pub const fn try_from_u32(v: u32) -> Option<Self> {
    match v {
      0 => Some(Self::Embedded),
      1 => Some(Self::Sidecar),
      2 => Some(Self::External),
      _ => None,
    }
  }
}

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

  const ALL: &[TrackOrigin] = &[
    TrackOrigin::Embedded,
    TrackOrigin::Sidecar,
    TrackOrigin::External,
  ];

  #[test]
  fn round_trip_via_u32_for_every_variant() {
    for &o in ALL {
      assert_eq!(TrackOrigin::from_u32(o.to_u32()), o);
    }
  }

  #[test]
  fn from_u32_unknown_falls_back_to_default() {
    assert_eq!(TrackOrigin::from_u32(999), TrackOrigin::Embedded,);
  }

  #[test]
  fn as_str_matches_spec() {
    assert_eq!(TrackOrigin::Embedded.as_str(), "embedded");
    assert_eq!(TrackOrigin::Sidecar.as_str(), "sidecar");
    assert_eq!(TrackOrigin::External.as_str(), "external");
  }

  #[test]
  fn display_matches_as_str() {
    for &o in ALL {
      assert_eq!(o.to_string(), o.as_str());
    }
  }

  #[test]
  fn default_is_embedded() {
    assert_eq!(TrackOrigin::default(), TrackOrigin::Embedded);
  }

  #[test]
  fn is_variant_predicates() {
    assert!(TrackOrigin::Embedded.is_embedded());
    assert!(!TrackOrigin::Embedded.is_sidecar());
    assert!(TrackOrigin::Sidecar.is_sidecar());
    assert!(TrackOrigin::External.is_external());
  }
}