Skip to main content

kernel_api/
naming.rs

1//! Names for the faces and edges of a built solid that survive a rebuild.
2//!
3//! A face is named by how it came to be: the feature that made it and the
4//! sketch element it was swept from, or the feature's start or end. A
5//! face a later feature splits, trims or merges keeps the names of the
6//! faces it came from; an edge is named by the two faces it runs between.
7//! References keep these names beside their points, so a rebuild finds a
8//! face again after dimensions change or features go in earlier, where a
9//! point alone would miss it.
10//!
11//! A name is a 64-bit hash of its parts, the same on every machine and in
12//! every version: it is saved in documents.
13
14/// A face's name; zero is no name.
15pub type TopoName = u64;
16
17const OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
18const PRIME: u64 = 0x0100_0000_01b3;
19
20fn fnv(mut hash: u64, bytes: &[u8]) -> u64 {
21    for byte in bytes {
22        hash ^= u64::from(*byte);
23        hash = hash.wrapping_mul(PRIME);
24    }
25    hash
26}
27
28/// The name of `bytes`: never zero.
29pub fn name_of(bytes: &[u8]) -> TopoName {
30    match fnv(OFFSET, bytes) {
31        0 => 1,
32        name => name,
33    }
34}
35
36/// The name of a thing with a UUID's bytes (a feature, a sketch element).
37pub fn name_of_id(id: &[u8; 16]) -> TopoName {
38    name_of(id)
39}
40
41/// `parent`'s child called `part`: a feature's face swept from one of its
42/// sketch's elements, or its start.
43pub fn child(parent: TopoName, part: &[u8]) -> TopoName {
44    match fnv(fnv(OFFSET, &parent.to_le_bytes()), part) {
45        0 => 1,
46        name => name,
47    }
48}
49
50/// Reads a name written as a number or as a string of its digits: a
51/// script's numbers are doubles, which cannot hold every name, so names
52/// reach scripts as strings and come back as them.
53pub fn name_from_number_or_text<'de, D>(deserializer: D) -> Result<TopoName, D::Error>
54where
55    D: serde::Deserializer<'de>,
56{
57    #[derive(serde::Deserialize)]
58    #[serde(untagged)]
59    enum Written {
60        Number(u64),
61        Text(String),
62    }
63    match <Written as serde::Deserialize>::deserialize(deserializer)? {
64        Written::Number(n) => Ok(n),
65        Written::Text(t) => t.trim().parse().map_err(serde::de::Error::custom),
66    }
67}
68
69/// Reads a pair of names, each written as a number or as a string of its
70/// digits, as [`name_from_number_or_text`] reads one: an edge's two faces.
71pub fn names_from_numbers_or_text<'de, D>(deserializer: D) -> Result<[TopoName; 2], D::Error>
72where
73    D: serde::Deserializer<'de>,
74{
75    #[derive(serde::Deserialize)]
76    struct Name(#[serde(deserialize_with = "name_from_number_or_text")] TopoName);
77    let [a, b] = <[Name; 2] as serde::Deserialize>::deserialize(deserializer)?;
78    Ok([a.0, b.0])
79}
80
81#[cfg(test)]
82mod tests {
83    use super::*;
84
85    #[test]
86    fn names_are_fixed_and_never_zero() {
87        // Saved in documents: the same bytes always make the same name.
88        assert_eq!(name_of(b"pad"), 0x77ca60195676adaa);
89        assert_ne!(name_of(b"pad"), name_of(b"pocket"));
90        assert_ne!(
91            child(name_of(b"pad"), b"start"),
92            child(name_of(b"pad"), b"end")
93        );
94        assert_ne!(name_of(&[]), 0);
95    }
96
97    /// A script hands names back as the strings it was given them as.
98    #[test]
99    fn a_pair_of_names_reads_from_numbers_or_strings() {
100        #[derive(serde::Deserialize)]
101        struct Pick {
102            #[serde(deserialize_with = "names_from_numbers_or_text")]
103            faces: [TopoName; 2],
104        }
105        let read = |text: &str| serde_json::from_str::<Pick>(text).map(|p| p.faces);
106        assert_eq!(
107            read(r#"{"faces": ["18446744073709551615", 7]}"#).unwrap(),
108            [u64::MAX, 7]
109        );
110        assert!(read(r#"{"faces": ["x", 7]}"#).is_err());
111    }
112}