[stdlib] Implement difference between pointers

docs/manual/pointers.ipynb

@@ -442,6 +442,35 @@
     "    print(float_ptr[offset], end=\", \")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "When subtracting two pointers of the same type, it gives the number of elements between them:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Second int: 200\nOffset between pointers: 1"
+     ]
+    }
+   ],
+   "source": [
+    "fn main():\n",
+    "    l = List[Int](100, 200) \n",
+    "    p1 = UnsafePointer.address_of(l[0])\n",
+    "    p2 = p1 + 1\n",
+    "    print(\"Second int:\", p2[])\n",
+    "    print(\"Offset between pointers:\", p2 - p1)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

stdlib/src/memory/unsafe_pointer.mojo

@@ -267,6 +267,18 @@ struct UnsafePointer[
         """
         self = self - offset
 
+    @always_inline
+    fn __sub__(self, other: Self) -> Int:
+        """Return the difference between two pointers.
+
+        Args:
+            other: The other pointer.
+
+        Returns:
+            The offset between the two pointers.
+        """
+        return (int(self) - int(other)) // sizeof[type]()
+
     @always_inline("nodebug")
     fn __eq__(self, rhs: Self) -> Bool:
         """Returns True if the two pointers are equal.

stdlib/test/memory/test_unsafepointer.mojo

@@ -282,6 +282,14 @@ def test_load_and_store_simd():
         assert_equal(ptr2[i], i // 4 * 4)
 
 
+def test_difference():
+    var ptr = UnsafePointer[Int].alloc(5)
+    var ptr2 = ptr + 2
+    assert_equal(ptr2 - ptr, 2)
+    assert_equal(ptr - ptr2, -2)
+    ptr.free()
+
+
 def main():
     test_address_of()
 
@@ -297,6 +305,7 @@ def main():
     test_unsafepointer_string()
     test_eq()
     test_comparisons()
+    test_difference()
 
     test_unsafepointer_address_space()
     test_indexing()