Add ptrdiff

Author: CodaFi

Sources/LLVM/BasicBlock.swift

@@ -88,7 +88,7 @@ public struct BasicBlock: IRValue {
 }
 
 extension BasicBlock {
-  /// A `Address` represents a function-relative address of a basic block for 
+  /// An `Address` represents a function-relative address of a basic block for
   /// use with the `indirectbr` instruction.
   public struct Address: IRValue {
     internal let llvm: LLVMValueRef

Sources/LLVM/Function.swift

@@ -90,15 +90,14 @@ public class Function: IRGlobal {
     }
   }
 
-  /// Computes the address of the specified basic block in this function, and 
-  /// always has an `i8*` type. 
+  /// Computes the address of the specified basic block in this function.
   ///
   /// Taking the address of the entry block is illegal.
   ///
   /// This value only has defined behavior when used as an operand to the 
   /// `indirectbr` instruction, or for comparisons against null. Pointer 
-  /// equality tests between labels addresses results in undefined behavior 
-  /// — though, again, comparison against null is ok, and no label is equal to 
+  /// equality tests between labels addresses results in undefined behavior.
+  /// Though, again, comparison against null is ok, and no label is equal to
   /// the null pointer. This may be passed around as an opaque pointer sized 
   /// value as long as the bits are not inspected. This allows `ptrtoint` and 
   /// arithmetic to be performed on these values so long as the original value 

Sources/LLVM/IRBuilder.swift

@@ -911,7 +911,7 @@ public class IRBuilder {
   }
 
   /// Build a return from the current function back to the calling function with
-  /// the given array of values in aggregate.
+  /// the given array of values as members of an aggregate.
   ///
   /// - parameter values: The values to insert as members of the returned aggregate.
   ///
@@ -1253,6 +1253,27 @@ public class IRBuilder {
     return LLVMSizeOf(val.asLLVM())
   }
 
+  /// Builds an expression that returns the difference between two pointer 
+  /// values, dividing out the size of the pointed-to objects.
+  ///
+  /// This is intended to implement C-style pointer subtraction. As such, the 
+  /// pointers must be appropriately aligned for their element types and 
+  /// pointing into the same object.
+  ///
+  /// - parameter lhs: The first pointer (the minuend).
+  /// - parameter rhs: The second pointer (the subtrahend).
+  /// - parameter name: The name for the newly inserted instruction.
+  ///
+  /// - returns: A IRValue representing a 64-bit integer value of the difference
+  ///   of the two pointer values modulo the size of the pointed-to objects.
+  public func buildPointerDifference(_ lhs: IRValue, _ rhs: IRValue, name: String = "") -> IRValue {
+    precondition(
+      lhs.type is PointerType && rhs.type is PointerType,
+      "Cannot take pointer diff of \(lhs.type) and \(rhs.type)."
+    )
+    return LLVMBuildPtrDiff(llvm, lhs.asLLVM(), rhs.asLLVM(), name)
+  }
+
   // MARK: Atomic Instructions
 
   /// Builds a fence instruction that introduces "happens-before" edges between
@@ -1264,6 +1285,7 @@ public class IRBuilder {
   ///   with other atomics in the same thread. (This is useful for interacting
   ///   with signal handlers.) Otherwise this fence is atomic with respect to
   ///   all other code in the system.
+  /// - parameter name: The name for the newly inserted instruction.
   ///
   /// - returns: A value representing `void`.
   public func buildFence(ordering: AtomicOrdering, singleThreaded: Bool = false, name: String = "") -> IRValue {