four_cc/
lib.rs

1//! Newtype wrapper providing a convenient representation of _four-character-code_ values.
2//!
3//! Using this type in a public APIs as an alternative to simply passing the equivalent `u32`
4//! makes the value's expected use explicit.
5//!
6//!
7//! ## Creating a FourCC value
8//!
9//! ```rust
10//! use four_cc::FourCC;
11//!
12//! let uuid = FourCC(*b"uuid");
13//!
14//! // using Into
15//! let code: FourCC = b"uuid".into();
16//! assert_eq!(uuid, code);
17//! ```
18//!
19//! ## From a slice
20//!
21//! ```rust
22//! # use four_cc::FourCC;
23//! let data = b"moofftyp";
24//! let code = FourCC::from(&data[0..4]);  // would panic if fewer than 4 bytes
25//! assert_eq!(FourCC(*b"moof"), code);
26//! ```
27//!
28//! ## From a u32
29//!
30//! ```rust
31//! # use four_cc::FourCC;
32//! let data: u32 = 0x6d6f6f66;
33//! let code = FourCC::from(data);
34//! assert_eq!(FourCC(*b"moof"), code);
35//! // conversion back into a u32
36//! let converted: u32 = code.into();
37//! assert_eq!(data, converted);
38//! ```
39//!
40//! ## Constants
41//!
42//! FourCC values can be used in const expressions
43//!
44//! ```rust
45//! # use four_cc::FourCC;
46//! const UUID: FourCC = FourCC(*b"uuid");
47//! ```
48//!
49//! ## Matching
50//!
51//! You can use FourCC values in match patterns as long as you define constants to match against,
52//!
53//! ```rust
54//! # use four_cc::FourCC;
55//! const UUID: FourCC = FourCC(*b"uuid");
56//! const MOOV: FourCC = FourCC(*b"moov");
57//! # let other_value = UUID;
58//! match other_value {
59//!     MOOV => println!("movie"),
60//!     UUID => println!("unique identifier"),
61//!     // compiler will not accept: FourCC(*b"trun") => println!("track fragment run"),
62//!     _ => println!("Other value; scary stuff")
63//! }
64//! ```
65//!
66//! ## Invalid literal values
67//!
68//! If the literal has other than four bytes, compilation will fail
69//!
70//! ```compile_fail
71//! # use four_cc::FourCC;
72//! let bad_fourcc = FourCC(*b"uuid123");
73//! // -> expected an array with a fixed size of 4 elements, found one with 7 elements
74//! ```
75//! **Note** the FourCC value _may_ contain non-printable byte values, including the byte-value zero.
76//!
77//! ## Debug display
78//!
79//! ```rust
80//! # use four_cc::FourCC;
81//! # use std::fmt::Debug;
82//! let uuid = FourCC(*b"uuid");
83//! # assert_eq!("FourCC(uuid)", format!("{:?}", &uuid));
84//! println!("it's {:?}", uuid);  // produces: it's FourCC{uuid}
85//! ```
86//!
87//! Note that if the FourCC bytes are not able to be converted to UTF8, then a fallback
88//! representation will be used (as it would be surprising for `format!()` to panic).
89//!
90//! ```rust
91//! # use four_cc::FourCC;
92//! # use std::fmt::Debug;
93//! let uuid = FourCC(*b"u\xFFi\0");
94//! # assert_eq!("FourCC(u\\xffi\\x00)", format!("{:?}", &uuid));
95//! println!("it's {:?}", uuid);  // produces: it's FourCC{u\xffi\x00}
96//! ```
97
98#![forbid(unsafe_code)]
99#![deny(rust_2018_idioms, future_incompatible, missing_docs)]
100#![cfg_attr(feature = "nightly", feature(const_trait_impl))]
101#![cfg_attr(not(feature = "std"), no_std)]
102
103use core::fmt;
104use core::fmt::Write;
105use core::result::Result;
106
107/// A _four-character-code_ value.
108///
109/// See the [module level documentation](index.html).
110#[derive(Clone, Copy, PartialEq, Eq, Hash)]
111#[cfg_attr(feature = "zerocopy", derive(zerocopy::FromBytes, zerocopy::AsBytes))]
112#[repr(C, packed)]
113pub struct FourCC(pub [u8; 4]);
114impl FourCC {
115    const fn from_u32(self: Self) -> u32 {
116        ((self.0[0] as u32) << 24 & 0xff000000)
117            | ((self.0[1] as u32) << 16 & 0x00ff0000)
118            | ((self.0[2] as u32) << 8 & 0x0000ff00)
119            | ((self.0[3] as u32) & 0x000000ff)
120    }
121}
122impl<'a> From<&'a [u8; 4]> for FourCC {
123    fn from(buf: &[u8; 4]) -> FourCC {
124        FourCC([buf[0], buf[1], buf[2], buf[3]])
125    }
126}
127impl<'a> From<&'a [u8]> for FourCC {
128    fn from(buf: &[u8]) -> FourCC {
129        FourCC([buf[0], buf[1], buf[2], buf[3]])
130    }
131}
132impl From<u32> for FourCC {
133    fn from(val: u32) -> FourCC {
134        FourCC([
135            (val >> 24 & 0xff) as u8,
136            (val >> 16 & 0xff) as u8,
137            (val >> 8 & 0xff) as u8,
138            (val & 0xff) as u8,
139        ])
140    }
141}
142// The macro is needed, because the `impl const` syntax doesn't exists on `stable`.
143#[cfg(not(feature = "nightly"))]
144macro_rules! from_fourcc_for_u32 {
145    () => {
146        impl From<FourCC> for u32 {
147            fn from(val: FourCC) -> Self {
148                val.from_u32()
149            }
150        }
151    };
152}
153#[cfg(feature = "nightly")]
154macro_rules! from_fourcc_for_u32 {
155    ($($t:tt)*) => {
156        impl const From<FourCC> for u32 {
157            fn from(val: FourCC) -> Self {
158                val.from_u32()
159            }
160        }
161    };
162}
163from_fourcc_for_u32!();
164
165impl fmt::Display for FourCC {
166    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
167        let b = &self.0;
168        let iter = core::ascii::escape_default(b[0])
169            .chain(core::ascii::escape_default(b[1]))
170            .chain(core::ascii::escape_default(b[2]))
171            .chain(core::ascii::escape_default(b[3]));
172        for c in iter {
173            f.write_char(c as char)?;
174        }
175        Ok(())
176    }
177}
178
179impl fmt::Debug for FourCC {
180    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
181        f.debug_tuple("FourCC")
182            .field(&format_args!("{}", self))
183            .finish()
184    }
185}
186
187#[cfg(feature = "schemars")]
188impl schemars::JsonSchema for FourCC {
189    fn schema_name() -> String {
190        "FourCC".to_string()
191    }
192    fn json_schema(gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema {
193        gen.subschema_for::<&str>()
194    }
195    fn is_referenceable() -> bool {
196        false
197    }
198}
199
200#[cfg(feature = "serde")]
201impl serde::ser::Serialize for FourCC {
202    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
203        serializer.collect_str(self)
204    }
205}
206
207#[cfg(feature = "serde")]
208struct FromStrVisitor<T> {
209    expecting: &'static str,
210    ty: core::marker::PhantomData<T>,
211}
212
213#[cfg(feature = "serde")]
214impl<T> FromStrVisitor<T> {
215    fn new(expecting: &'static str) -> Self {
216        FromStrVisitor {
217            expecting: expecting,
218            ty: core::marker::PhantomData,
219        }
220    }
221}
222
223#[cfg(feature = "serde")]
224impl core::str::FromStr for FourCC {
225    type Err = u32;
226    fn from_str(s: &str) -> Result<Self, Self::Err> {
227        Ok(s.as_bytes().into())
228    }
229}
230
231#[cfg(feature = "serde")]
232impl<'de, T> serde::de::Visitor<'de> for FromStrVisitor<T>
233where
234    T: core::str::FromStr,
235    T::Err: fmt::Display,
236{
237    type Value = T;
238
239    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
240        formatter.write_str(self.expecting)
241    }
242
243    fn visit_str<E>(self, s: &str) -> Result<Self::Value, E>
244    where
245        E: serde::de::Error,
246    {
247        s.parse().map_err(serde::de::Error::custom)
248    }
249}
250
251#[cfg(feature = "serde")]
252impl<'de> serde::de::Deserialize<'de> for FourCC {
253    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
254        deserializer.deserialize_str(FromStrVisitor::new("FourCC"))
255    }
256}
257
258#[cfg(test)]
259mod tests {
260    use super::*;
261
262    #[test]
263    fn eq() {
264        assert_eq!(FourCC(*b"uuid"), b"uuid".into());
265        assert_ne!(FourCC(*b"uuid"), b"diuu".into());
266    }
267
268    #[test]
269    fn int_conversions() {
270        let val: u32 = FourCC(*b"ABCD").into();
271        assert_eq!(0x41424344_u32, val);
272        assert_eq!(FourCC(*b"ABCD"), 0x41424344u32.into());
273    }
274
275    #[cfg(feature = "std")]
276    #[test]
277    fn display() {
278        assert_eq!("uuid", format!("{}", FourCC(*b"uuid")));
279        assert_eq!("\\x00uid", format!("{}", FourCC(*b"\x00uid")));
280    }
281
282    #[cfg(feature = "serde")]
283    #[test]
284    fn serialize() {
285        use serde_test::{assert_tokens, Token};
286
287        let code = FourCC(*b"uuid");
288        assert_tokens(&code, &[Token::Str("uuid")]);
289    }
290
291    #[cfg(feature = "serde")]
292    #[test]
293    fn deserialize() {
294        use std::str::FromStr;
295        let data = "uuid";
296        let code = FourCC::from_str(data).unwrap();
297        assert_eq!(code, FourCC(*b"uuid"));
298    }
299
300    #[cfg(feature = "schemars")]
301    #[test]
302    fn schema() {
303        let schema = schemars::schema_for!(FourCC);
304        let expected_type = schemars::schema::InstanceType::String;
305        assert_eq!(
306            schema.schema.instance_type,
307            Some(schemars::schema::SingleOrVec::Single(Box::from(
308                expected_type
309            )))
310        );
311    }
312}
four_cc/lib.rs

four_cc/
lib.rs
