Ord Instance Documentation (#162)

* Document the ordering used by each Ord instance. Change the Ord instance for PrimArray to use a lexicographic ordering.

* document that Ord instances are subject to change between major versions

Data/Primitive/Array.hs

@@ -380,6 +380,7 @@ arrayLiftCompare elemCompare a1 a2 = loop 0
     = elemCompare x1 x2 `mappend` loop (i+1)
     | otherwise = compare (sizeofArray a1) (sizeofArray a2)
 
+-- | Lexicographic ordering. Subject to change between major versions.
 instance Ord a => Ord (Array a) where
   compare a1 a2 = arrayLiftCompare compare a1 a2
 

Data/Primitive/ByteArray.hs

@@ -458,14 +458,11 @@ instance Eq ByteArray where
       n1 = sizeofByteArray ba1
       n2 = sizeofByteArray ba2
 
--- Note: On GHC 8.4, the primop compareByteArrays# performs a check for pointer
--- equality as a shortcut, so the check here is actually redundant. However, it
--- is included here because it is likely better to check for pointer equality
--- before checking for length equality. Getting the length requires deferencing
--- the pointers, which could cause accesses to memory that is not in the cache.
--- By contrast, a pointer equality check is always extremely cheap.
-
--- | @since 0.6.3.0
+-- | Non-lexicographic ordering. This compares the lengths of
+-- the byte arrays first and uses a lexicographic ordering if
+-- the lengths are equal. Subject to change between major versions.
+-- 
+-- @since 0.6.3.0
 instance Ord ByteArray where
   ba1@(ByteArray ba1#) `compare` ba2@(ByteArray ba2#)
     | sameByteArray ba1# ba2# = EQ
@@ -474,6 +471,12 @@ instance Ord ByteArray where
     where
       n1 = sizeofByteArray ba1
       n2 = sizeofByteArray ba2
+-- Note: On GHC 8.4, the primop compareByteArrays# performs a check for pointer
+-- equality as a shortcut, so the check here is actually redundant. However, it
+-- is included here because it is likely better to check for pointer equality
+-- before checking for length equality. Getting the length requires deferencing
+-- the pointers, which could cause accesses to memory that is not in the cache.
+-- By contrast, a pointer equality check is always extremely cheap.
 
 appendByteArray :: ByteArray -> ByteArray -> ByteArray
 appendByteArray a b = runST $ do

Data/Primitive/PrimArray.hs

@@ -160,22 +160,20 @@ instance (Eq a, Prim a) => Eq (PrimArray a) where
       | i < 0 = True
       | otherwise = indexPrimArray a1 i == indexPrimArray a2 i && loop (i-1)
 
--- | __Note__: For the sake of efficiency, this is not a lexicographic
---   ordering. This library makes no guarantees about the particular
---   ordering used, and it is subject to change between major releases.
---   
+-- | Lexicographic ordering. Subject to change between major versions.
+-- 
 --   @since 0.6.4.0
 instance (Ord a, Prim a) => Ord (PrimArray a) where
   compare a1@(PrimArray ba1#) a2@(PrimArray ba2#)
     | sameByteArray ba1# ba2# = EQ
-    | sz1 /= sz2 = compare sz1 sz2
-    | otherwise = loop (quot sz1 (sizeOf (undefined :: a)) - 1)
+    | otherwise = loop 0
     where
     sz1 = PB.sizeofByteArray (ByteArray ba1#)
     sz2 = PB.sizeofByteArray (ByteArray ba2#)
+    sz = quot (min sz1 sz2) (sizeOf (undefined :: a))
     loop !i
-      | i < 0 = EQ
-      | otherwise = compare (indexPrimArray a1 i) (indexPrimArray a2 i) <> loop (i-1)
+      | i < sz = compare (indexPrimArray a1 i) (indexPrimArray a2 i) <> loop (i+1)
+      | otherwise = compare sz1 sz2
 
 #if MIN_VERSION_base(4,7,0)
 -- | @since 0.6.4.0

Data/Primitive/SmallArray.hs

@@ -575,6 +575,7 @@ instance Ord1 SmallArray where
 #endif
 #endif
 
+-- | Lexicographic ordering. Subject to change between major versions.
 instance Ord a => Ord (SmallArray a) where
   compare sa1 sa2 = smallArrayLiftCompare compare sa1 sa2
 

Data/Primitive/UnliftedArray.hs

@@ -503,7 +503,9 @@ instance (Eq a, PrimUnlifted a) => Eq (UnliftedArray a) where
      | i < 0 = True
      | otherwise = indexUnliftedArray aa1 i == indexUnliftedArray aa2 i && loop (i-1)
 
--- | @since 0.6.4.0
+-- | Lexicographic ordering. Subject to change between major versions.
+--
+--   @since 0.6.4.0
 instance (Ord a, PrimUnlifted a) => Ord (UnliftedArray a) where
   compare a1 a2 = loop 0
     where