Provide APIs to read file into more data types

Motivation:

As requested in issues [apple#2875](apple#2875) and [apple#2876](apple#2876), it would be convenient to be able to read the contents of a file into more data types such as `Array`, `ArraySlice` & Foundation's `Data`.

Modifications:

- Extend `Array`, `ArraySlice` & `Data` to be initialisable with the contents of a file.

Result:

The contents of a file can be read into more data types.

Sources/NIOFileSystem/Array+FileSystem.swift

@@ -0,0 +1,57 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2024 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS) || os(Linux) || os(Android)
+import NIOCore
+
+@available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
+extension Array where Element == UInt8 {
+    /// Reads the contents of the file at the path.
+    ///
+    /// - Parameters:
+    ///   - path: The path of the file to read.
+    ///   - maximumSizeAllowed: The maximum size of file which can be read, in bytes, as a ``ByteCount``.
+    ///   - fileSystem: The ``FileSystemProtocol`` instance to use to read the file.
+    public init(
+        contentsOf path: FilePath,
+        maximumSizeAllowed: ByteCount,
+        fileSystem: some FileSystemProtocol
+    ) async throws {
+        let byteBuffer = try await fileSystem.withFileHandle(forReadingAt: path) { handle in
+            try await handle.readToEnd(
+                fromAbsoluteOffset: 0,
+                maximumSizeAllowed: maximumSizeAllowed
+            )
+        }
+
+        self = Self(buffer: byteBuffer)
+    }
+
+    /// Reads the contents of the file at the path using ``FileSystem``.
+    ///
+    /// - Parameters:
+    ///   - path: The path of the file to read.
+    ///   - maximumSizeAllowed: The maximum size of file which can be read, as a ``ByteCount``.
+    public init(
+        contentsOf path: FilePath,
+        maximumSizeAllowed: ByteCount
+    ) async throws {
+        self = try await Self(
+            contentsOf: path,
+            maximumSizeAllowed: maximumSizeAllowed,
+            fileSystem: .shared
+        )
+    }
+}
+#endif

Sources/NIOFileSystem/ArraySlice+FileSystem.swift

@@ -0,0 +1,56 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2024 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS) || os(Linux) || os(Android)
+import NIOCore
+
+@available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
+extension ArraySlice where Element == UInt8 {
+    /// Reads the contents of the file at the path.
+    ///
+    /// - Parameters:
+    ///   - path: The path of the file to read.
+    ///   - maximumSizeAllowed: The maximum size of file which can be read, in bytes, as a ``ByteCount``.
+    ///   - fileSystem: The ``FileSystemProtocol`` instance to use to read the file.
+    public init(
+        contentsOf path: FilePath,
+        maximumSizeAllowed: ByteCount,
+        fileSystem: some FileSystemProtocol
+    ) async throws {
+        let bytes = try await Array(
+            contentsOf: path,
+            maximumSizeAllowed: maximumSizeAllowed,
+            fileSystem: fileSystem
+        )
+
+        self = Self(bytes)
+    }
+
+    /// Reads the contents of the file at the path using ``FileSystem``.
+    ///
+    /// - Parameters:
+    ///   - path: The path of the file to read.
+    ///   - maximumSizeAllowed: The maximum size of file which can be read, as a ``ByteCount``.
+    public init(
+        contentsOf path: FilePath,
+        maximumSizeAllowed: ByteCount
+    ) async throws {
+        self = try await Self(
+            contentsOf: path,
+            maximumSizeAllowed: maximumSizeAllowed,
+            fileSystem: .shared
+        )
+    }
+}
+#endif

Sources/NIOFileSystemFoundationCompat/Data+FileSystem.swift

@@ -0,0 +1,59 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2024 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+#if os(macOS) || os(iOS) || os(tvOS) || os(watchOS) || os(Linux) || os(Android)
+import _NIOFileSystem
+import NIOCore
+import struct Foundation.Data
+
+@available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
+extension Data {
+    /// Reads the contents of the file at the path.
+    ///
+    /// - Parameters:
+    ///   - path: The path of the file to read.
+    ///   - maximumSizeAllowed: The maximum size of file which can be read, in bytes, as a ``ByteCount``.
+    ///   - fileSystem: The ``FileSystemProtocol`` instance to use to read the file.
+    public init(
+        contentsOf path: FilePath,
+        maximumSizeAllowed: ByteCount,
+        fileSystem: some FileSystemProtocol
+    ) async throws {
+        let byteBuffer = try await fileSystem.withFileHandle(forReadingAt: path) { handle in
+            try await handle.readToEnd(
+                fromAbsoluteOffset: 0,
+                maximumSizeAllowed: maximumSizeAllowed
+            )
+        }
+
+        self = byteBuffer.withUnsafeReadableBytes { Self($0) }
+    }
+
+    /// Reads the contents of the file at the path using ``FileSystem``.
+    ///
+    /// - Parameters:
+    ///   - path: The path of the file to read.
+    ///   - maximumSizeAllowed: The maximum size of file which can be read, as a ``ByteCount``.
+    public init(
+        contentsOf path: FilePath,
+        maximumSizeAllowed: ByteCount
+    ) async throws {
+        self = try await Self(
+            contentsOf: path,
+            maximumSizeAllowed: maximumSizeAllowed,
+            fileSystem: .shared
+        )
+    }
+}
+#endif

Tests/NIOFileSystemFoundationCompatTests/FileSystemFoundationCompatTests.swift

@@ -33,5 +33,18 @@ final class FileSystemBytesConformanceTests: XCTestCase {
             Date(timeIntervalSince1970: 1.000000001)
         )
     }
+
+    func testReadFileIntoData() async throws {
+        let fs = FileSystem.shared
+        let path = FilePath(#filePath)
+
+        try await fs.withFileHandle(forReadingAndWritingAt: path) { fileHandle in
+            _ = try await fileHandle.write(contentsOf: [0, 1, 2], toAbsoluteOffset: 0)
+        }
+
+        let contents = try await Data(contentsOf: path, maximumSizeAllowed: .bytes(1024))
+
+        XCTAssertEqual(contents, Data([0, 1, 2]))
+    }
 }
 #endif

Tests/NIOFileSystemIntegrationTests/FileSystemTests.swift

@@ -1828,6 +1828,30 @@ extension FileSystemTests {
             )
         }
     }
+
+    func testReadIntoArray() async throws {
+        let path = FilePath(#filePath)
+
+        try await self.fs.withFileHandle(forReadingAndWritingAt: path) { fileHandle in
+            _ = try await fileHandle.write(contentsOf: [0, 1, 2], toAbsoluteOffset: 0)
+        }
+
+        let contents = try await Array(contentsOf: path, maximumSizeAllowed: .bytes(1024))
+
+        XCTAssertEqual(contents, [0, 1, 2])
+    }
+
+    func testReadIntoArraySlice() async throws {
+        let path = FilePath(#filePath)
+
+        try await self.fs.withFileHandle(forReadingAndWritingAt: path) { fileHandle in
+            _ = try await fileHandle.write(contentsOf: [0, 1, 2], toAbsoluteOffset: 0)
+        }
+
+        let contents = try await ArraySlice(contentsOf: path, maximumSizeAllowed: .bytes(1024))
+
+        XCTAssertEqual(contents, [0, 1, 2])
+    }
 }
 
 #if !canImport(Darwin) && swift(<5.9.2)