feat: add map-key functionality for NamedRef and Arc-backed objects

Author: Dekker1

CHANGELOG.md

@@ -11,6 +11,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add support for parsing `.fzn` files when enabling the `fzn` feature.
   Users can access this functionality via the `FlatZinc::from_fzn` method.
+- Add helper type `ArcKey`, to use in collections that use variables or arrays as keys.
+  `ArcKey` uses pointer identity to determine its order, equality, and hash value.
+  Similarly, `NamedRef` can be used as a key, where the `name` attribute of variables and arrays are used to compare.
 
 ### Changed
 

src/helpers.rs

@@ -0,0 +1,149 @@
+//! Helper structures, methods, and functions to support the serialization and
+//! deserialization of FlatZinc data.
+
+use std::{
+	hash::{Hash, Hasher},
+	ops::Deref,
+	sync::Arc,
+};
+
+#[derive(Debug, Clone)]
+/// A wrapper around an [`Arc`] that can be used as a key for collections, such
+/// as [`BTreeMap`](std::collections::BTreeMap),
+/// [`HashMap`](std::collections::HashMap), and
+/// [`HashSet`](std::collections::HashSet).
+///
+/// This struct uses pointer equality for comparison, so two [`ArcKey`]
+/// instances from [`Arc`] objects that share the same value will be considered
+/// equal. However, two `T` values with the same contents but different memory
+/// addresses will not be considered equal.
+pub struct ArcKey<T> {
+	/// The underlying [`Arc`] value.
+	key: Arc<T>,
+}
+
+impl<T> From<ArcKey<T>> for Arc<T> {
+	fn from(value: ArcKey<T>) -> Self {
+		value.key
+	}
+}
+
+impl<T> ArcKey<T> {
+	/// Creates a new [`ArcKey`] from the given [`Arc`].
+	pub fn new(key: Arc<T>) -> Self {
+		Self { key }
+	}
+}
+
+impl<T> Deref for ArcKey<T> {
+	type Target = T;
+
+	fn deref(&self) -> &Self::Target {
+		self.key.deref()
+	}
+}
+
+impl<T> Eq for ArcKey<T> {}
+
+impl<T> Hash for ArcKey<T> {
+	fn hash<H: Hasher>(&self, state: &mut H) {
+		Arc::as_ptr(&self.key).hash(state);
+	}
+}
+
+impl<T> Ord for ArcKey<T> {
+	fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+		Arc::as_ptr(&self.key).cmp(&Arc::as_ptr(&other.key))
+	}
+}
+
+impl<T> PartialEq for ArcKey<T> {
+	fn eq(&self, other: &Self) -> bool {
+		Arc::ptr_eq(&self.key, &other.key)
+	}
+}
+
+impl<T> PartialOrd for ArcKey<T> {
+	fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+		Some(self.cmp(other))
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use std::{
+		collections::{BTreeMap, HashMap, HashSet},
+		sync::Arc,
+	};
+
+	use crate::helpers::ArcKey;
+
+	#[test]
+	fn arc_key() {
+		let key = Arc::new(42);
+		let arc_key = ArcKey::new(Arc::clone(&key));
+		assert_eq!(*arc_key, 42);
+		assert_eq!(arc_key.key, key);
+	}
+
+	#[test]
+	fn arc_key_uses_pointer_equality() {
+		let key = Arc::new(String::from("value"));
+		let same_ptr = ArcKey::new(Arc::clone(&key));
+		let also_same_ptr = ArcKey::new(Arc::clone(&key));
+		let different_ptr = ArcKey::new(Arc::new(String::from("value")));
+
+		assert_eq!(same_ptr, also_same_ptr);
+		assert_ne!(same_ptr, different_ptr);
+	}
+
+	#[test]
+	fn arc_key_works_in_btree_map() {
+		let first = Arc::new(String::from("shared"));
+		let second = Arc::new(String::from("shared"));
+		let first_key = ArcKey::new(Arc::clone(&first));
+		let second_key = ArcKey::new(Arc::clone(&second));
+
+		let mut map = BTreeMap::new();
+		let _ = map.insert(first_key.clone(), "first");
+		let _ = map.insert(ArcKey::new(first), "updated");
+		let _ = map.insert(second_key.clone(), "second");
+
+		assert_eq!(map.len(), 2);
+		assert_eq!(map.get(&first_key), Some(&"updated"));
+		assert_eq!(map.get(&second_key), Some(&"second"));
+	}
+
+	#[test]
+	fn arc_key_works_in_hash_map() {
+		let key = Arc::new(String::from("entry"));
+		let same_ptr = ArcKey::new(Arc::clone(&key));
+		let different_ptr = ArcKey::new(Arc::new(String::from("entry")));
+		let mut map = HashMap::new();
+
+		let _ = map.insert(same_ptr.clone(), 1);
+		let _ = map.insert(ArcKey::new(Arc::clone(&key)), 2);
+		let _ = map.insert(different_ptr.clone(), 3);
+
+		assert_eq!(map.len(), 2);
+		assert_eq!(map.get(&same_ptr), Some(&2));
+		assert_eq!(map.get(&ArcKey::new(key)), Some(&2));
+		assert_eq!(map.get(&different_ptr), Some(&3));
+	}
+
+	#[test]
+	fn arc_key_works_in_hash_set() {
+		let key = Arc::new(7_u32);
+		let same_ptr = ArcKey::new(Arc::clone(&key));
+		let different_ptr = ArcKey::new(Arc::new(7_u32));
+
+		let mut set = HashSet::new();
+		let _ = set.insert(same_ptr.clone());
+		let _ = set.insert(ArcKey::new(key));
+		let _ = set.insert(different_ptr.clone());
+
+		assert_eq!(set.len(), 2);
+		assert!(set.contains(&same_ptr));
+		assert!(set.contains(&different_ptr));
+	}
+}

src/lib.rs

@@ -116,14 +116,17 @@
 mod error;
 #[cfg(feature = "fzn")]
 mod fzn;
+pub mod helpers;
 #[cfg(any(feature = "fzn", feature = "serde"))]
 mod intermediate;
 #[cfg(feature = "serde")]
 mod serde_impl;
 
 use std::{
+	cmp::Ordering,
 	collections::HashSet,
 	fmt::{Debug, Display},
+	hash::{Hash, Hasher},
 	sync::{Arc, Weak},
 };
 
@@ -132,6 +135,7 @@ pub use rangelist::RangeList;
 use serde::{Deserializer, Serialize};
 
 pub use crate::error::{FznParseError, LinkError};
+use crate::helpers::ArcKey;
 
 /// Additional information provided in a standardized format for declarations,
 /// constraints, or solve objectives
@@ -381,9 +385,15 @@ pub enum Method<Identifier = String> {
 /// It is possible for an [`Array`] to exist without an `name` attribute, if a
 /// reference to such an [`Array`] is used as a [`NamedRef`], serialization can
 /// panic.
-#[derive(Clone, PartialEq, Debug)]
+///
+/// [`NamedRef`] compares, hashes, and orders by the referenced declaration
+/// name. As a consequence, two values that refer to different allocations but
+/// expose the same name are considered equal, and a variable and array with
+/// the same name are also treated as equal for these trait implementations.
+/// Note that this cannot occur in valid FlatZinc models.
+#[derive(Clone, Debug)]
 pub enum NamedRef<Identifier = String> {
-	/// Reference to a variable
+	/// Reference to a variable.
 	Variable(Arc<Variable<Identifier>>),
 	/// Reference to an array.
 	Array(Arc<Array<Identifier>>),
@@ -441,11 +451,6 @@ pub struct Variable<Identifier = String> {
 	pub introduced: bool,
 }
 
-/// Return a unique key for a specific variable or array allocation.
-fn arc_key<T>(arc: &Arc<T>) -> usize {
-	Arc::as_ptr(arc) as usize
-}
-
 impl<Identifier: Display> Display for Annotation<Identifier> {
 	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
 		match self {
@@ -613,6 +618,27 @@ impl<Identifier> Array<Identifier> {
 			.any(|lit| matches!(lit, Literal::Variable(_)));
 		(ty, is_var)
 	}
+
+	/// Converts an array reference into an [`ArcKey`](crate::helpers::ArcKey).
+	///
+	/// This is useful when storing arrays in collections such as
+	/// [`HashMap`](std::collections::HashMap),
+	/// [`HashSet`](std::collections::HashSet), and
+	/// [`BTreeMap`](std::collections::BTreeMap), where the key should identify
+	/// the specific parsed array object rather than its contents or `name`.
+	///
+	/// The resulting key uses the allocation / pointer identity of this
+	/// [`Arc`]. Two arrays with the same name and equal contents will
+	/// therefore compare as different keys if they are stored in different
+	/// allocations.
+	///
+	/// During FlatZinc parsing and deserialization, this crate guarantees that
+	/// identical top-level arrays are allocated only once. In those cases,
+	/// `ArcKey` is a good fit for keying collections by the canonical parsed
+	/// array object.
+	pub fn into_key(self: Arc<Self>) -> ArcKey<Self> {
+		ArcKey::new(self)
+	}
 }
 
 impl<Identifier: Display> Display for Constraint<Identifier> {
@@ -706,12 +732,13 @@ impl<Identifier> Default for FlatZinc<Identifier> {
 
 impl<Identifier: Display> Display for FlatZinc<Identifier> {
 	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-		let output_map: HashSet<_> = self.output.iter().map(|output| output.arc_key()).collect();
+		let output_map: HashSet<_> = self.output.iter().collect();
 
 		for var in &self.variables {
 			write!(f, "var {}", var.ty)?;
 			write!(f, ": {}", var.name)?;
-			if output_map.contains(&arc_key(var)) {
+			let name_ref: NamedRef<_> = Arc::clone(var).into();
+			if output_map.contains(&name_ref) {
 				write!(f, " ::output_var")?;
 			}
 			if var.defined {
@@ -734,7 +761,8 @@ impl<Identifier: Display> Display for FlatZinc<Identifier> {
 				if is_var { "var " } else { "" },
 				arr.name
 			)?;
-			if output_map.contains(&arc_key(arr)) {
+			let name_ref: NamedRef<_> = Arc::clone(arr).into();
+			if output_map.contains(&name_ref) {
 				write!(f, " ::output_array([1..{}])", arr.contents.len())?;
 			}
 			if arr.defined {
@@ -789,14 +817,6 @@ impl<Identifier: Display> Display for Method<Identifier> {
 }
 
 impl<Identifier> NamedRef<Identifier> {
-	/// Return a unique key for the referenced variable or array allocation.
-	fn arc_key(&self) -> usize {
-		match self {
-			NamedRef::Variable(arc) => Arc::as_ptr(arc) as usize,
-			NamedRef::Array(arc) => Arc::as_ptr(arc) as usize,
-		}
-	}
-
 	/// Return the identifier of the referenced output target.
 	pub fn name(&self) -> &str {
 		match self {
@@ -806,6 +826,44 @@ impl<Identifier> NamedRef<Identifier> {
 	}
 }
 
+impl<Identifier> Eq for NamedRef<Identifier> {}
+
+impl<Identifier> From<Arc<Array<Identifier>>> for NamedRef<Identifier> {
+	fn from(arc: Arc<Array<Identifier>>) -> Self {
+		NamedRef::Array(arc)
+	}
+}
+
+impl<Identifier> From<Arc<Variable<Identifier>>> for NamedRef<Identifier> {
+	fn from(arc: Arc<Variable<Identifier>>) -> Self {
+		NamedRef::Variable(arc)
+	}
+}
+
+impl<Identifier> Hash for NamedRef<Identifier> {
+	fn hash<H: Hasher>(&self, state: &mut H) {
+		self.name().hash(state);
+	}
+}
+
+impl<Identifier> Ord for NamedRef<Identifier> {
+	fn cmp(&self, other: &Self) -> Ordering {
+		self.name().cmp(other.name())
+	}
+}
+
+impl<Identifier> PartialEq for NamedRef<Identifier> {
+	fn eq(&self, other: &Self) -> bool {
+		self.name() == other.name()
+	}
+}
+
+impl<Identifier> PartialOrd for NamedRef<Identifier> {
+	fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+		Some(self.cmp(other))
+	}
+}
+
 impl<Identifier> Default for SolveObjective<Identifier> {
 	fn default() -> Self {
 		Self {
@@ -850,3 +908,27 @@ impl Display for Type {
 		}
 	}
 }
+
+impl<Identifier> Variable<Identifier> {
+	/// Converts a variable reference into an
+	/// [`ArcKey`](crate::helpers::ArcKey).
+	///
+	/// This is useful when storing variables in collections such as
+	/// [`HashMap`](std::collections::HashMap),
+	/// [`HashSet`](std::collections::HashSet), and
+	/// [`BTreeMap`](std::collections::BTreeMap), where the key should identify
+	/// the specific parsed variable object rather than its fields or `name`.
+	///
+	/// The resulting key uses the allocation / pointer identity of this
+	/// [`Arc`]. Two variables with the same name and equal fields will
+	/// therefore compare as different keys if they are stored in different
+	/// allocations.
+	///
+	/// During FlatZinc parsing and deserialization, this crate guarantees that
+	/// identical top-level variables are allocated only once. In those cases,
+	/// `ArcKey` is a good fit for keying collections by the canonical parsed
+	/// variable object.
+	pub fn into_key(self: Arc<Self>) -> ArcKey<Self> {
+		ArcKey::new(self)
+	}
+}