ANKTrivialContiguousBytes and ANKCoreInteger #50

Sources/ANKFoundation/ANKBinaryInteger.swift

@@ -218,7 +218,7 @@ extension ANKBinaryInteger where Self: FixedWidthInteger {
 }
 
 //=----------------------------------------------------------------------------=
-// MARK: Details x Sign & Magnitude
+// MARK: + Details x Sign & Magnitude
 //=----------------------------------------------------------------------------=
 
 extension ANKBinaryInteger where BitPattern == Magnitude.BitPattern {

Sources/ANKFoundation/ANKContiguousBytes.swift

@@ -26,3 +26,80 @@ public protocol ANKContiguousBytes {
     ///
     @inlinable func withUnsafeBytes<T>(_ body: (UnsafeRawBufferPointer) throws -> T) rethrows -> T
 }
+
+//*============================================================================*
+// MARK: * ANK x Contiguous Bytes x Mutable
+//*============================================================================*
+
+/// A type that offers read-write access to its data.
+public protocol ANKMutableContiguousBytes: ANKContiguousBytes {
+
+    //=------------------------------------------------------------------------=
+    // MARK: Utilities
+    //=------------------------------------------------------------------------=
+
+    /// Calls the given closure with read-write access to this value's data.
+    ///
+    /// ```
+    /// var x = UInt256(1).bigEndian; x.withUnsafeMutableBytes({ _ in })
+    /// ```
+    ///
+    @inlinable mutating func withUnsafeMutableBytes<T>(_ body: (UnsafeMutableRawBufferPointer) throws -> T) rethrows -> T
+}
+
+//*============================================================================*
+// MARK: * ANK x Contiguous Bytes x Trivial
+//*============================================================================*
+
+/// A type that offers read-write access to its data, without indirection.
+///
+/// Types conforming to this protocol have access to the following semantic methods:
+///
+/// - `withUnsafeBytes(_:)`
+/// - `withUnsafeMutableBytes(_:)`
+/// - `fromUnsafeMutableBytes(_:)`
+///
+public protocol ANKTrivialContiguousBytes: ANKMutableContiguousBytes { }
+
+//=----------------------------------------------------------------------------=
+// MARK: + Details
+//=----------------------------------------------------------------------------=
+
+extension ANKTrivialContiguousBytes {
+
+    //=------------------------------------------------------------------------=
+    // MARK: Utilities
+    //=------------------------------------------------------------------------=
+
+    /// Calls the given closure with read-only access to this value's data.
+    ///
+    /// ```
+    /// UInt256(1).bigEndian.withUnsafeBytes({ data += $0 })
+    /// ```
+    ///
+    @_transparent public func withUnsafeBytes<T>(_ body: (UnsafeRawBufferPointer) throws -> T) rethrows -> T {
+        try Swift.withUnsafeBytes(of: self, body)
+    }
+
+    /// Calls the given closure with read-write access to this value's data.
+    ///
+    /// ```
+    /// var x = UInt256(1).bigEndian; x.withUnsafeMutableBytes({ _ in })
+    /// ```
+    ///
+    @_transparent public mutating func withUnsafeMutableBytes<T>(_ body: (UnsafeMutableRawBufferPointer) throws -> T) rethrows -> T {
+        try Swift.withUnsafeMutableBytes(of: &self, body)
+    }
+
+    /// Creates a new instance from a temporary allocation.
+    ///
+    /// ```
+    /// UInt256.fromUnsafeMutableBytes({ _ in }).bigEndian
+    /// ```
+    ///
+    @_transparent public static func fromUnsafeMutableBytes(_ body: (UnsafeMutableRawBufferPointer) throws -> Void) rethrows -> Self {
+        try Swift.withUnsafeTemporaryAllocation(byteCount: MemoryLayout<Self>.size, alignment: MemoryLayout<Self>.alignment) { BYTES in
+            try body(BYTES); return BYTES.load(as: Self.self)
+        }
+    }
+}

Sources/ANKFoundation/ANKTrivialFixedWidthInteger.swift → Sources/ANKFoundation/ANKCoreInteger.swift

@@ -8,10 +8,10 @@
 //=----------------------------------------------------------------------------=
 
 //*============================================================================*
-// MARK: * ANK x Fixed Width Integer x Trivial
+// MARK: * ANK x Fixed Width Integer x Core
 //*============================================================================*
 
-/// An awesome, fixed-width, binary integer with trivial implementation.
+/// An awesome, fixed-width, binary integer.
 ///
 /// Only the following types in the standard library may conform to this protocol:
 ///
@@ -26,13 +26,13 @@
 /// - `UInt32`
 /// - `UInt64`
 ///
-public protocol ANKTrivialFixedWidthInteger: ANKBigEndianTextCodable, ANKFixedWidthInteger, ANKUnsafeRawInteger where BitPattern == Magnitude { }
+public protocol ANKCoreInteger: ANKBigEndianTextCodable, ANKFixedWidthInteger, ANKTrivialContiguousBytes where BitPattern == Magnitude { }
 
 //=----------------------------------------------------------------------------=
 // MARK: + Details
 //=----------------------------------------------------------------------------=
 
-extension ANKTrivialFixedWidthInteger {
+extension ANKCoreInteger {
 
     //=------------------------------------------------------------------------=
     // MARK: Initializers
@@ -109,7 +109,7 @@ extension ANKTrivialFixedWidthInteger {
 // MARK: + Details x Bit Pattern
 //=----------------------------------------------------------------------------=
 
-extension ANKTrivialFixedWidthInteger {
+extension ANKCoreInteger {
 
     //=------------------------------------------------------------------------=
     // MARK: Utilities
@@ -128,7 +128,7 @@ extension ANKTrivialFixedWidthInteger {
 // MARK: + Details x Two's Complement
 //=----------------------------------------------------------------------------=
 
-extension ANKTrivialFixedWidthInteger {
+extension ANKCoreInteger {
 
     //=------------------------------------------------------------------------=
     // MARK: Transformations
@@ -147,7 +147,7 @@ extension ANKTrivialFixedWidthInteger {
 // MARK: + Details x Big Endian Text Codable
 //=----------------------------------------------------------------------------=
 
-extension ANKTrivialFixedWidthInteger {
+extension ANKCoreInteger {
 
     //=------------------------------------------------------------------------=
     // MARK: Utilities
@@ -165,10 +165,10 @@ extension ANKTrivialFixedWidthInteger {
 }
 
 //*============================================================================*
-// MARK: * ANK x Fixed Width Integer x Signed x Trivial
+// MARK: * ANK x Fixed Width Integer x Signed x Core
 //*============================================================================*
 
-extension ANKTrivialFixedWidthInteger where Self: ANKSignedFixedWidthInteger {
+extension ANKCoreInteger where Self: ANKSignedFixedWidthInteger {
 
     //=------------------------------------------------------------------------=
     // MARK: Transformations
@@ -185,45 +185,45 @@ extension ANKTrivialFixedWidthInteger where Self: ANKSignedFixedWidthInteger {
 }
 
 //*============================================================================*
-// MARK: * ANK x Fixed Width Integer x Trivial x Swift
+// MARK: * ANK x Fixed Width Integer x Core x Swift
 //*============================================================================*
 
-extension Int: ANKTrivialFixedWidthInteger, ANKSignedFixedWidthInteger {
+extension Int: ANKCoreInteger, ANKSignedFixedWidthInteger {
     public typealias BitPattern = Magnitude
 }
 
-extension Int8: ANKTrivialFixedWidthInteger, ANKSignedFixedWidthInteger {
+extension Int8: ANKCoreInteger, ANKSignedFixedWidthInteger {
     public typealias BitPattern = Magnitude
 }
 
-extension Int16: ANKTrivialFixedWidthInteger, ANKSignedFixedWidthInteger {
+extension Int16: ANKCoreInteger, ANKSignedFixedWidthInteger {
     public typealias BitPattern = Magnitude
 }
 
-extension Int32: ANKTrivialFixedWidthInteger, ANKSignedFixedWidthInteger {
+extension Int32: ANKCoreInteger, ANKSignedFixedWidthInteger {
     public typealias BitPattern = Magnitude
 }
 
-extension Int64: ANKTrivialFixedWidthInteger, ANKSignedFixedWidthInteger {
+extension Int64: ANKCoreInteger, ANKSignedFixedWidthInteger {
     public typealias BitPattern = Magnitude
 }
 
-extension UInt: ANKTrivialFixedWidthInteger, ANKUnsignedFixedWidthInteger {
+extension UInt: ANKCoreInteger, ANKUnsignedFixedWidthInteger {
     public typealias BitPattern = Magnitude
 }
 
-extension UInt8: ANKTrivialFixedWidthInteger, ANKUnsignedFixedWidthInteger {
+extension UInt8: ANKCoreInteger, ANKUnsignedFixedWidthInteger {
     public typealias BitPattern = Magnitude
 }
 
-extension UInt16: ANKTrivialFixedWidthInteger, ANKUnsignedFixedWidthInteger {
+extension UInt16: ANKCoreInteger, ANKUnsignedFixedWidthInteger {
     public typealias BitPattern = Magnitude
 }
 
-extension UInt32: ANKTrivialFixedWidthInteger, ANKUnsignedFixedWidthInteger {
+extension UInt32: ANKCoreInteger, ANKUnsignedFixedWidthInteger {
     public typealias BitPattern = Magnitude
 }
 
-extension UInt64: ANKTrivialFixedWidthInteger, ANKUnsignedFixedWidthInteger {
+extension UInt64: ANKCoreInteger, ANKUnsignedFixedWidthInteger {
     public typealias BitPattern = Magnitude
 }

Sources/ANKFoundation/ANKIntOrUInt.swift

@@ -11,11 +11,11 @@
 // MARK: * ANK x Int Or UInt
 //*============================================================================*
 
-/// A type that is either Int or UInt.
+/// A type that is either `Int` or `UInt`.
 ///
 ///  Only `Int` and `UInt` in the standard library may conform to this protocol.
 ///
-public protocol ANKIntOrUInt: ANKLargeFixedWidthInteger<Self>, ANKTrivialFixedWidthInteger where Magnitude == UInt { }
+public protocol ANKIntOrUInt: ANKCoreInteger, ANKLargeFixedWidthInteger<Self> where Magnitude == UInt { }
 
 //=----------------------------------------------------------------------------=
 // MARK: + Fixes Marked As Unavailable in /Integers.swift

Sources/ANKFullWidthKit/ANKFullWidth.swift

@@ -47,7 +47,7 @@ import ANKFoundation
 /// ```
 ///
 @frozen public struct ANKFullWidth<High, Low>: ANKBigEndianTextCodable,
-ANKLargeFixedWidthInteger, ANKUnsafeRawInteger, ANKWords, CustomStringConvertible,
+ANKLargeFixedWidthInteger, ANKTrivialContiguousBytes, ANKWords, CustomStringConvertible,
 CustomDebugStringConvertible, ExpressibleByStringLiteral, MutableCollection where
 High: ANKLargeFixedWidthInteger, Low: ANKUnsignedLargeFixedWidthInteger<UInt>,
 High.Digit: ANKIntOrUInt, High.Magnitude.Digit == UInt, Low == Low.Magnitude {

Tests/ANKFoundationTests/Types+ANKUnsafeRawInteger.swift → Tests/ANKFoundationTests/Types+ANKCoreInteger.swift

@@ -13,18 +13,18 @@ import ANKFoundation
 import XCTest
 
 //*============================================================================*
-// MARK: * Types x ANKUnsafeRawInteger
+// MARK: * Types x ANKCoreInteger
 //*============================================================================*
 
-final class TypesTestsOnANKUnsafeRawInteger: XCTestCase {
+final class TypesTestsOnANKCoreInteger: XCTestCase {
 
-    typealias T = any ANKUnsafeRawInteger.Type
+    typealias T = any ANKCoreInteger.Type
 
     //=------------------------------------------------------------------------=
     // MARK: State
     //=------------------------------------------------------------------------=
 
-    let types: [T] = Types.ANKUnsafeRawInteger
+    let types: [T] = Types.ANKCoreInteger
 
     //=------------------------------------------------------------------------=
     // MARK: Tests
@@ -35,7 +35,7 @@ final class TypesTestsOnANKUnsafeRawInteger: XCTestCase {
     }
 
     //=------------------------------------------------------------------------=
-    // MARK: Tests
+    // MARK: Tests x Contiguous Bytes
     //=------------------------------------------------------------------------=
 
     func testWithUnsafeBytes() {

Tests/ANKFoundationTests/Types.swift

@@ -56,8 +56,8 @@ enum Types {
     static let ANKUnsignedLargeFixedWidthInteger =
     ANKBinaryInteger.compactMap({ $0 as? any ANKUnsignedLargeFixedWidthInteger.Type })
 
-    static let ANKUnsafeRawInteger =
-    ANKBinaryInteger.compactMap({ $0 as? any ANKUnsafeRawInteger.Type })
+    static let ANKCoreInteger =
+    ANKBinaryInteger.compactMap({ $0 as? any ANKCoreInteger.Type })
 
     //=------------------------------------------------------------------------=
     // MARK: Accessors
@@ -68,4 +68,17 @@ enum Types {
 
     static let ANKIntOrUInt =
     ANKBinaryInteger.compactMap({ $0 as? any ANKIntOrUInt.Type })
+
+    //=------------------------------------------------------------------------=
+    // MARK: Accessors
+    //=------------------------------------------------------------------------=
+
+    static let ANKContiguousBytes =
+    ANKBinaryInteger.compactMap({ $0 as? any (ANKContiguousBytes & ANKBinaryInteger).Type })
+
+    static let ANKMutableContiguousBytes =
+    ANKBinaryInteger.compactMap({ $0 as? any (ANKMutableContiguousBytes & ANKBinaryInteger).Type })
+
+    static let ANKTrivialContiguousBytes =
+    ANKBinaryInteger.compactMap({ $0 as? any (ANKTrivialContiguousBytes & ANKFixedWidthInteger).Type })
 }