Add some documentation/concerns around Tuple

Author: vishesh

Sources/FoundationDB/Tuple.swift

@@ -49,6 +49,26 @@ public protocol TupleElement: Sendable, Hashable, Equatable {
 }
 
 // TODO: Make it a TypedTuple so that we don't have to typecast manually.
+/// A tuple represents an ordered collection of elements that can be encoded to and decoded from bytes.
+///
+/// Tuples can be used as keys in FoundationDB, and their encoding preserves lexicographic ordering.
+///
+/// ## Equality and Hashing
+///
+/// Tuple equality is based on the encoded byte representation of each element, which matches
+/// FoundationDB's tuple comparison semantics. This differs from Swift's native equality for
+/// floating-point values in the following ways:
+///
+/// - **Positive and negative zero**: `Tuple(0.0)` and `Tuple(-0.0)` are **not equal** because
+///   they have different bit patterns and encode to different bytes. This differs from Swift,
+///   where `0.0 == -0.0` is `true`.
+///
+/// - **NaN values**: `Tuple(Float.nan)` and `Tuple(Float.nan)` **are equal** if they have the
+///   same bit pattern, because they encode to the same bytes. This differs from Swift, where
+///   `Float.nan == Float.nan` is `false`.
+///
+/// These semantic differences ensure consistency with FoundationDB's tuple ordering and are
+/// important when using tuples as dictionary keys or in sets.
 public struct Tuple: Sendable, Hashable, Equatable {
     private let elements: [any TupleElement]
 
@@ -126,8 +146,14 @@ public struct Tuple: Sendable, Hashable, Equatable {
         guard lhs.count == rhs.count else { return false }
 
         for i in 0..<lhs.count {
-            // Compare encoded bytes since Swift doesn't allow direct comparison of existential types.
-            // This is semantically correct because the tuple encoding is canonical.
+            // Swift's type system doesn't allow comparing `any Protocol` existentials directly,
+            // even though TupleElement requires Equatable conformance. We compare encoded bytes
+            // instead, which is semantically correct since tuple encoding is canonical:
+            // equal values always produce equal encodings.
+            //
+            // Note: This means Float/Double comparison follows bit-pattern equality rather than
+            // IEEE 754 equality (e.g., +0.0 and -0.0 are unequal, NaN values with the same bit
+            // pattern are equal). See the Tuple documentation for details.
             if lhs.elements[i].encodeTuple() != rhs.elements[i].encodeTuple() {
                 return false
             }
@@ -138,8 +164,9 @@ public struct Tuple: Sendable, Hashable, Equatable {
     public func hash(into hasher: inout Hasher) {
         hasher.combine(elements.count)
         for element in elements {
-            // Hash encoded bytes since Swift doesn't allow direct hashing of existential types.
-            // This ensures consistency with equality semantics.
+            // Swift's type system doesn't allow hashing `any Protocol` existentials directly,
+            // even though TupleElement requires Hashable conformance. We hash encoded bytes
+            // instead, which ensures consistency with the equality implementation above.
             hasher.combine(element.encodeTuple())
         }
     }
@@ -155,11 +182,13 @@ struct TupleNil: TupleElement {
     }
 
     static func == (lhs: TupleNil, rhs: TupleNil) -> Bool {
+        // All TupleNil instances are equal (representing null/nil)
         return true
     }
 
     func hash(into hasher: inout Hasher) {
-        hasher.combine(0 as UInt8)
+        // Use a constant value for consistency with the null type code
+        hasher.combine(TupleTypeCode.null.rawValue)
     }
 }
 

Tests/FoundationDBTests/FoundationDBTupleTests.swift

@@ -413,3 +413,109 @@ func tupleHashabilityDictionary() throws {
     #expect(dict[key2] == "Bob", "key2 value should be 'Bob'")
     #expect(dict[key3] == "Charlie", "key3 (same as key1) should retrieve 'Charlie'")
 }
+
+// MARK: - Edge Cases
+
+@Test("Tuple equality - Float positive and negative zero are unequal")
+func tupleFloatZeroInequality() throws {
+    let tuple1 = Tuple(Float(0.0))
+    let tuple2 = Tuple(Float(-0.0))
+
+    // Note: These are unequal because they have different bit patterns
+    // and encode to different bytes. This differs from Swift's Float equality
+    // where 0.0 == -0.0 is true.
+    #expect(tuple1 != tuple2, "Positive and negative zero have different encodings")
+
+    // Verify they hash differently (important for Set/Dictionary correctness)
+    #expect(tuple1.hashValue != tuple2.hashValue, "Different values must have potentially different hashes")
+}
+
+@Test("Tuple equality - Double positive and negative zero are unequal")
+func tupleDoubleZeroInequality() throws {
+    let tuple1 = Tuple(Double(0.0))
+    let tuple2 = Tuple(Double(-0.0))
+
+    #expect(tuple1 != tuple2, "Positive and negative zero have different encodings")
+    #expect(tuple1.hashValue != tuple2.hashValue, "Different values must have potentially different hashes")
+}
+
+@Test("Tuple equality - Float NaN values are equal")
+func tupleFloatNaNEquality() throws {
+    let tuple1 = Tuple(Float.nan)
+    let tuple2 = Tuple(Float.nan)
+
+    // Note: These are equal because they encode to the same bytes
+    // (same bit pattern). This differs from Swift's Float equality
+    // where Float.nan == Float.nan is false.
+    #expect(tuple1 == tuple2, "NaN values with same bit pattern encode to same bytes")
+    #expect(tuple1.hashValue == tuple2.hashValue, "Equal values must have same hash")
+}
+
+@Test("Tuple equality - Double NaN values are equal")
+func tupleDoubleNaNEquality() throws {
+    let tuple1 = Tuple(Double.nan)
+    let tuple2 = Tuple(Double.nan)
+
+    #expect(tuple1 == tuple2, "NaN values with same bit pattern encode to same bytes")
+    #expect(tuple1.hashValue == tuple2.hashValue, "Equal values must have same hash")
+}
+
+@Test("Tuple equality - Float infinity values")
+func tupleFloatInfinity() throws {
+    let tuple1 = Tuple(Float.infinity)
+    let tuple2 = Tuple(Float.infinity)
+    let tuple3 = Tuple(-Float.infinity)
+
+    #expect(tuple1 == tuple2, "Same infinity values should be equal")
+    #expect(tuple1 != tuple3, "Positive and negative infinity should be unequal")
+}
+
+@Test("Tuple equality - Double infinity values")
+func tupleDoubleInfinity() throws {
+    let tuple1 = Tuple(Double.infinity)
+    let tuple2 = Tuple(Double.infinity)
+    let tuple3 = Tuple(-Double.infinity)
+
+    #expect(tuple1 == tuple2, "Same infinity values should be equal")
+    #expect(tuple1 != tuple3, "Positive and negative infinity should be unequal")
+}
+
+@Test("Tuple equality - empty tuples")
+func tupleEmptyEquality() throws {
+    let tuple1 = Tuple()
+    let tuple2 = Tuple([])
+
+    #expect(tuple1 == tuple2, "Empty tuples should be equal")
+    #expect(tuple1.hashValue == tuple2.hashValue, "Empty tuples should have same hash")
+    #expect(tuple1.count == 0, "Empty tuple should have count 0")
+}
+
+@Test("Tuple hashability - empty tuples in Set")
+func tupleEmptySet() throws {
+    let tuple1 = Tuple()
+    let tuple2 = Tuple([])
+
+    var set = Set<Tuple>()
+    set.insert(tuple1)
+    set.insert(tuple2)
+
+    #expect(set.count == 1, "Empty tuples should be deduplicated in Set")
+}
+
+@Test("Tuple with nil values")
+func tupleWithNil() throws {
+    let tuple1 = Tuple(TupleNil(), "hello", TupleNil())
+    let tuple2 = Tuple(TupleNil(), "hello", TupleNil())
+
+    #expect(tuple1 == tuple2, "Tuples with nil values should be equal")
+    #expect(tuple1.hashValue == tuple2.hashValue, "Tuples with nil values should have same hash")
+    #expect(tuple1.count == 3, "Tuple should have 3 elements including nils")
+}
+
+@Test("Tuple equality - nil values in different positions are unequal")
+func tupleNilPositions() throws {
+    let tuple1 = Tuple(TupleNil(), "hello")
+    let tuple2 = Tuple("hello", TupleNil())
+
+    #expect(tuple1 != tuple2, "Tuples with nils in different positions should be unequal")
+}