[stdlib] add loads and stores for raw buffer slices

Author: glessard

stdlib/public/core/UnsafeBufferPointerSlice.swift

@@ -297,9 +297,9 @@ extension Slice where Base == UnsafeMutableRawBufferPointer {
   }
 
   /// Returns a new instance of the given type, read from the
-  /// buffer pointer slice's raw memory.
+  /// specified offset into the buffer pointer slice's raw memory.
   ///
-  /// The memory at the beginning of this buffer pointer slice
+  /// The memory at `offset` bytes into this buffer pointer slice
   /// must be properly aligned for accessing `T` and initialized to `T` or
   /// another type that is layout compatible with `T`.
   ///
@@ -314,28 +314,31 @@ extension Slice where Base == UnsafeMutableRawBufferPointer {
   ///
   /// The memory to read for the new instance must not extend beyond the
   /// memory region represented by the buffer pointer slice---that is,
-  /// `MemoryLayout<T>.size` must be less than or equal to the slice's `count`.
+  /// `offset + MemoryLayout<T>.size` must be less than or equal
+  /// to the slice's `count`.
   ///
   /// - Parameters:
+  ///   - offset: The offset into the slice's memory, in bytes, at
+  ///     which to begin reading data for the new instance. 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
   ///   slice's memory.
   @inlinable
   @_alwaysEmitIntoClient
-  public func load<T>(as type: T.Type) -> T {
+  public func load<T>(fromByteOffset offset: Int = 0, as type: T.Type) -> T {
     let buffer = Base(rebasing: self)
-    return buffer.load(fromByteOffset: 0, as: T.self)
+    return buffer.load(fromByteOffset: offset, as: T.self)
   }
 
   /// Returns a new instance of the given type, read from the
-  /// buffer pointer slice's raw memory.
+  /// specified offset into the buffer pointer slice's raw memory.
   ///
   /// 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
+  /// The memory at `offset` bytes into the buffer slice 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
@@ -349,32 +352,40 @@ extension Slice where Base == UnsafeMutableRawBufferPointer {
   ///
   /// The memory to read for the new instance must not extend beyond the
   /// memory region represented by the buffer pointer slice---that is,
-  /// `MemoryLayout<T>.size` must be less than or equal to the slice's `count`.
+  /// `offset + MemoryLayout<T>.size` must be less than or equal
+  /// to the slice's `count`.
   ///
   /// - Parameters:
+  ///   - offset: The offset into the slice's memory, in bytes, at
+  ///     which to begin reading data for the new instance. 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.
   @inlinable
   @_alwaysEmitIntoClient
-  public func loadUnaligned<T>(as type: T.Type) -> T {
+  public func loadUnaligned<T>(
+    fromByteOffset offset: Int = 0,
+    as type: T.Type
+  ) -> T {
     let buffer = Base(rebasing: self)
-    return buffer.loadUnaligned(fromByteOffset: 0, as: T.self)
+    return buffer.loadUnaligned(fromByteOffset: offset, as: T.self)
   }
 
-  /// Stores a value's bytes into the buffer pointer slice's raw memory.
+  /// Stores a value's bytes into the buffer pointer slice's raw memory at the
+  /// specified byte offset.
   ///
   /// The type `T` to be stored must be a trivial type. The memory must also be
   /// uninitialized, initialized to `T`, or initialized to another trivial
   /// type that is layout compatible with `T`.
   ///
   /// The memory written to must not extend beyond
   /// the memory region represented by the buffer pointer slice---that is,
-  /// `MemoryLayout<T>.size` must be less than or equal to the slice's `count`.
+  /// `offset + MemoryLayout<T>.size` must be less than or equal
+  /// to the slice's `count`.
   ///
-  /// After calling `storeBytes(of:as:)`, the memory is
+  /// After calling `storeBytes(of:toByteOffset:as:)`, the memory is
   /// initialized to the raw bytes of `value`. If the memory is bound to a
   /// type `U` that is layout compatible with `T`, then it contains a value of
   /// type `U`. Calling `storeBytes(of:toByteOffset:as:)` does not change the
@@ -386,12 +397,14 @@ extension Slice where Base == UnsafeMutableRawBufferPointer {
   ///   forms of indirection are trivial, as are imported C structs and enums.
   ///
   /// If you need to store into memory a copy of a value of a type that isn't
-  /// trivial, you cannot use the `storeBytes(of:as:)` method.
+  /// trivial, you cannot use the `storeBytes(of:toByteOffset:as:)` method.
   /// Instead, you must know either initialize the memory or,
   /// if you know the memory was already bound to `type`, assign to the memory.
   ///
   /// - Parameters:
   ///   - value: The value to store as raw bytes.
+  ///   - offset: The offset in bytes into the buffer pointer slice's memory
+  ///     to begin writing bytes from the value. 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`.
@@ -509,9 +522,9 @@ extension Slice where Base == UnsafeRawBufferPointer {
   }
 
   /// Returns a new instance of the given type, read from the
-  /// buffer pointer slice's raw memory.
+  /// specified offset into the buffer pointer slice's raw memory.
   ///
-  /// The memory at the beginning of this buffer pointer slice
+  /// The memory at `offset` bytes into this buffer pointer slice
   /// must be properly aligned for accessing `T` and initialized to `T` or
   /// another type that is layout compatible with `T`.
   ///
@@ -526,28 +539,31 @@ extension Slice where Base == UnsafeRawBufferPointer {
   ///
   /// The memory to read for the new instance must not extend beyond the
   /// memory region represented by the buffer pointer slice---that is,
-  /// `MemoryLayout<T>.size` must be less than or equal to the slice's `count`.
+  /// `offset + MemoryLayout<T>.size` must be less than or equal
+  /// to the slice's `count`.
   ///
   /// - Parameters:
+  ///   - offset: The offset into the slice's memory, in bytes, at
+  ///     which to begin reading data for the new instance. 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
   ///   slice's memory.
   @inlinable
   @_alwaysEmitIntoClient
-  public func load<T>(as type: T.Type) -> T {
+  public func load<T>(fromByteOffset offset: Int = 0, as type: T.Type) -> T {
     let buffer = Base(rebasing: self)
-    return buffer.load(fromByteOffset: 0, as: T.self)
+    return buffer.load(fromByteOffset: offset, as: T.self)
   }
 
   /// Returns a new instance of the given type, read from the
-  /// buffer pointer slice's raw memory.
+  /// specified offset into the buffer pointer slice's raw memory.
   ///
   /// 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
+  /// The memory at `offset` bytes into the buffer slice 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
@@ -561,19 +577,25 @@ extension Slice where Base == UnsafeRawBufferPointer {
   ///
   /// The memory to read for the new instance must not extend beyond the
   /// memory region represented by the buffer pointer slice---that is,
-  /// `MemoryLayout<T>.size` must be less than or equal to the slice's `count`.
+  /// `offset + MemoryLayout<T>.size` must be less than or equal
+  /// to the slice's `count`.
   ///
   /// - Parameters:
+  ///   - offset: The offset into the slice's memory, in bytes, at
+  ///     which to begin reading data for the new instance. 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.
   @inlinable
   @_alwaysEmitIntoClient
-  public func loadUnaligned<T>(as type: T.Type) -> T {
+  public func loadUnaligned<T>(
+    fromByteOffset offset: Int = 0,
+    as type: T.Type
+  ) -> T {
     let buffer = Base(rebasing: self)
-    return buffer.loadUnaligned(fromByteOffset: 0, as: T.self)
+    return buffer.loadUnaligned(fromByteOffset: offset, as: T.self)
   }
 }