[stdlib] add unaligned loads to Unsafe{Mutable}RawBufferPointer

Author: glessard

stdlib/public/core/UnsafeRawBufferPointer.swift.gyb

@@ -381,6 +381,49 @@ extension Unsafe${Mutable}RawBufferPointer {
     return baseAddress!.load(fromByteOffset: offset, as: T.self)
   }
 
+  /// Returns a new instance of the given type, constructed from the raw memory
+  /// at the specified offset.
+  ///
+  /// This function only supports loading trivial types.
+  /// A trivial type does not contain any reference-counted property
+  /// within its in-memory stored representation.
+  /// The memory at `offset` bytes into the buffer must be laid out
+  /// identically to the in-memory representation of `T`.
+  ///
+  /// You can use this method to create new values from the buffer pointer's
+  /// underlying bytes. The following example creates two new `Int32`
+  /// instances from the memory referenced by the buffer pointer `someBytes`.
+  /// The bytes for `a` are copied from the first four bytes of `someBytes`,
+  /// and the bytes for `b` are copied from the next four bytes.
+  ///
+  ///     let a = someBytes.load(as: Int32.self)
+  ///     let b = someBytes.load(fromByteOffset: 4, as: Int32.self)
+  ///
+  /// The memory to read for the new instance must not extend beyond the buffer
+  /// pointer's memory region---that is, `offset + MemoryLayout<T>.size` must
+  /// be less than or equal to the buffer pointer's `count`.
+  ///
+  /// - Parameters:
+  ///   - offset: The offset, in bytes, into the buffer pointer's memory at
+  ///     which to begin reading data for the new instance. The buffer pointer
+  ///     plus `offset` must be properly aligned for accessing an instance of
+  ///     type `T`. The default is zero.
+  ///   - type: The type to use for the newly constructed instance. The memory
+  ///     must be initialized to a value of a type that is layout compatible
+  ///     with `type`.
+  /// - Returns: A new instance of type `T`, copied from the buffer pointer's
+  ///   memory.
+  @_alwaysEmitIntoClient
+  public func loadUnaligned<T>(
+    fromByteOffset offset: Int = 0,
+    as type: T.Type
+  ) -> T {
+    _debugPrecondition(offset >= 0, "${Self}.load with negative offset")
+    _debugPrecondition(offset + MemoryLayout<T>.size <= self.count,
+      "${Self}.load out of bounds")
+    return baseAddress!.loadUnaligned(fromByteOffset: offset, as: T.self)
+  }
+
 %  if mutable:
   /// Stores a value's bytes into the buffer pointer's raw memory at the
   /// specified byte offset.