Update package with changes from recent ABI stable releases

This brings the contents of this package up to date with versions of the ABI stable `System` module that shipped in recent iOS/macOS releases.

Most changes only touch internal implementation details, but some ABI-related fixes also affect the public API. There are no source-incompatible changes.

- ABI stability fixes (un-deprecate CModeT, don't use PlatformChar in inlinable contexts that need to deploy to iOS 14)
- New utilities: `_RawBuffer`, `Array<String>._withCStringArray`, `_withOptionalUnsafePointerOrNull`, `_withStackBuffer`, `system_memset`
- Prefer using explicit optionals to implicitly-unwrapped ones
- Add support for wildcard matching in mocking tests
- A bunch of new availability annotations. (I expect there will be more of these coming in future PRs.)

Author: lorentey

.gitignore

@@ -1,6 +1,6 @@
 .DS_Store
 /.build
 /Packages
-/*.xcodeproj
+swift-system.xcodeproj
 xcuserdata/
 .*.sw?

Sources/System/CMakeLists.txt

@@ -16,6 +16,7 @@ add_library(SystemPackage
   PlatformString.swift
   SystemString.swift
   Util.swift
+  Util+StringArray.swift
   UtilConsumers.swift)
 set_target_properties(SystemPackage PROPERTIES
   INTERFACE_INCLUDE_DIRECTORIES ${CMAKE_Swift_MODULE_DIRECTORY})
@@ -32,6 +33,7 @@ target_sources(SystemPackage PRIVATE
   Internals/Constants.swift
   Internals/Exports.swift
   Internals/Mocking.swift
+  Internals/RawBuffer.swift
   Internals/Syscalls.swift
   Internals/WindowsSyscallAdapters.swift)
 target_link_libraries(SystemPackage PUBLIC

Sources/System/FileDescriptor.swift

@@ -25,7 +25,8 @@ public struct FileDescriptor: RawRepresentable, Hashable, Codable {
   public init(rawValue: CInt) { self.rawValue = rawValue }
 }
 
-// Standard file descriptors
+// Standard file descriptors.
+/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
 extension FileDescriptor {
   /// The standard input file descriptor, with a numeric value of 0.
   @_alwaysEmitIntoClient

Sources/System/FileOperations.swift

@@ -31,7 +31,7 @@ extension FileDescriptor {
     permissions: FilePermissions? = nil,
     retryOnInterrupt: Bool = true
   ) throws -> FileDescriptor {
-    try path.withPlatformString {
+    try path.withCString {
       try FileDescriptor.open(
         $0, mode, options: options, permissions: permissions, retryOnInterrupt: retryOnInterrupt)
     }
@@ -53,7 +53,7 @@ extension FileDescriptor {
   /// The corresponding C function is `open`.
   @_alwaysEmitIntoClient
   public static func open(
-    _ path: UnsafePointer<CInterop.PlatformChar>,
+    _ path: UnsafePointer<CChar>,
     _ mode: FileDescriptor.AccessMode,
     options: FileDescriptor.OpenOptions = FileDescriptor.OpenOptions(),
     permissions: FilePermissions? = nil,
@@ -66,7 +66,7 @@ extension FileDescriptor {
 
   @usableFromInline
   internal static func _open(
-    _ path: UnsafePointer<CInterop.PlatformChar>,
+    _ path: UnsafePointer<CChar>,
     _ mode: FileDescriptor.AccessMode,
     options: FileDescriptor.OpenOptions,
     permissions: FilePermissions?,
@@ -308,7 +308,10 @@ extension FileDescriptor {
       buffer,
       retryOnInterrupt: retryOnInterrupt)
   }
+}
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
+extension FileDescriptor {
   /// Duplicate this file descriptor and return the newly created copy.
   ///
   /// - Parameters:
@@ -385,7 +388,7 @@ extension FileDescriptor {
   public static func pipe() throws -> (readEnd: FileDescriptor, writeEnd: FileDescriptor) {
     try _pipe().get()
   }
-  
+
   /*System 1.1.0, @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)*/
   @usableFromInline
   internal static func _pipe() -> Result<(readEnd: FileDescriptor, writeEnd: FileDescriptor), Errno> {

Sources/System/FilePath/FilePathComponentView.swift

@@ -40,7 +40,7 @@ extension FilePath {
     }
   }
 
-  #if SYSTEM_PACKAGE
+  #if SYSTEM_PACKAGE // Workaround for a __consuming getter bug in Swift 5.3.3
   /// View the non-root components that make up this path.
   public var components: ComponentView {
     get { ComponentView(self) }
@@ -202,6 +202,7 @@ extension FilePath {
 
 // MARK: - Internals
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.ComponentView: _PathSlice {
   internal var _range: Range<SystemString.Index> {
     _start ..< _path._storage.endIndex
@@ -214,6 +215,7 @@ extension FilePath.ComponentView: _PathSlice {
 
 // MARK: - Invariants
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.ComponentView {
   internal func _invariantCheck() {
     #if DEBUG

Sources/System/FilePath/FilePathComponents.swift

@@ -98,6 +98,7 @@ extension FilePath.Component {
   }
 }
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.Root {
   // TODO: Windows analysis APIs
 }
@@ -183,15 +184,18 @@ extension _PathSlice {
   internal var _storage: SystemString { _path._storage }
 }
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.Component: _PathSlice {
 }
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.Root: _PathSlice {
   internal var _range: Range<SystemString.Index> {
     (..<_rootEnd).relative(to: _path._storage)
   }
 }
+
+/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
 extension FilePath: _PlatformStringable {
-  @usableFromInline
   func _withPlatformString<Result>(_ body: (UnsafePointer<CInterop.PlatformChar>) throws -> Result) rethrows -> Result {
     try _storage.withPlatformString(body)
   }
@@ -202,6 +206,7 @@ extension FilePath: _PlatformStringable {
 
 }
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.Component {
   // The index of the `.` denoting an extension
   internal func _extensionIndex() -> SystemString.Index? {
@@ -230,6 +235,7 @@ internal func _makeExtension(_ ext: String) -> SystemString {
   return result
 }
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.Component {
   internal init?(_ str: SystemString) {
     // FIXME: explicit null root? Or something else?
@@ -242,6 +248,7 @@ extension FilePath.Component {
   }
 }
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.Root {
   internal init?(_ str: SystemString) {
     // FIXME: explicit null root? Or something else?
@@ -256,6 +263,7 @@ extension FilePath.Root {
 
 // MARK: - Invariants
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.Component {
   // TODO: ensure this all gets easily optimized away in release...
   internal func _invariantCheck() {
@@ -267,6 +275,8 @@ extension FilePath.Component {
     #endif // DEBUG
   }
 }
+
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.Root {
   internal func _invariantCheck() {
     #if DEBUG

Sources/System/FilePath/FilePathParsing.swift

@@ -111,6 +111,7 @@ extension SystemString {
   }
 }
 
+/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
 extension FilePath {
   internal mutating func _removeTrailingSeparator() {
     _storage._removeTrailingSeparator()
@@ -191,6 +192,7 @@ extension SystemString {
   }
 }
 
+/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
 extension FilePath {
   internal var _relativeStart: SystemString.Index {
     _storage._relativePathStart
@@ -202,6 +204,7 @@ extension FilePath {
 
 // Parse separators
 
+/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
 extension FilePath {
   internal typealias _Index = SystemString.Index
 
@@ -265,6 +268,7 @@ extension FilePath {
   }
 }
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.ComponentView {
   // TODO: Store this...
   internal var _relativeStart: SystemString.Index {
@@ -289,6 +293,7 @@ extension SystemString {
   }
 }
 
+/*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath.Root {
   // Asserting self is a root, returns whether this is an
   // absolute root.
@@ -313,6 +318,7 @@ extension FilePath.Root {
   }
 }
 
+/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
 extension FilePath {
   internal var _portableDescription: String {
     guard _windowsPaths else { return description }
@@ -331,6 +337,7 @@ internal var _windowsPaths: Bool {
   #endif
 }
 
+/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
 extension FilePath {
   // Whether we should add a separator when doing an append
   internal var _needsSeparatorForAppend: Bool {
@@ -358,6 +365,7 @@ extension FilePath {
 }
 
 // MARK: - Invariants
+/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
 extension FilePath {
   internal func _invariantCheck() {
     #if DEBUG

Sources/System/FilePath/FilePathString.swift

@@ -20,6 +20,7 @@ extension FilePath {
     self.init(_platformString: platformString)
   }
 
+#if !os(Windows) // Availability workaround
   /// Calls the given closure with a pointer to the contents of the file path,
   /// represented as a null-terminated platform string.
   ///
@@ -37,12 +38,28 @@ extension FilePath {
     _ body: (UnsafePointer<CInterop.PlatformChar>) throws -> Result
   ) rethrows -> Result {
     // For backwards deployment, call withCString if available.
-    #if !os(Windows)
     return try withCString(body)
-    #else
+  }
+#else
+  /// Calls the given closure with a pointer to the contents of the file path,
+  /// represented as a null-terminated platform string.
+  ///
+  /// - Parameter body: A closure with a pointer parameter
+  ///   that points to a null-terminated platform string.
+  ///   If `body` has a return value,
+  ///   that value is also used as the return value for this method.
+  /// - Returns: The return value, if any, of the `body` closure parameter.
+  ///
+  /// The pointer passed as an argument to `body` is valid
+  /// only during the execution of this method.
+  /// Don't try to store the pointer for later use.
+  public func withPlatformString<Result>(
+    _ body: (UnsafePointer<CInterop.PlatformChar>) throws -> Result
+  ) rethrows -> Result {
+    // For backwards deployment, call withCString if available.
     return try _withPlatformString(body)
-    #endif
   }
+#endif
 }
 
 /*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/

Sources/System/FilePermissions.swift

@@ -21,14 +21,14 @@
 public struct FilePermissions: OptionSet, Hashable, Codable {
   /// The raw C file permissions.
   @_alwaysEmitIntoClient
-  public let rawValue: CInterop.Mode
+  public let rawValue: CModeT
 
   /// Create a strongly-typed file permission from a raw C value.
   @_alwaysEmitIntoClient
-  public init(rawValue: CInterop.Mode) { self.rawValue = rawValue }
+  public init(rawValue: CModeT) { self.rawValue = rawValue }
 
   @_alwaysEmitIntoClient
-  private init(_ raw: CInterop.Mode) { self.init(rawValue: raw) }
+  private init(_ raw: CModeT) { self.init(rawValue: raw) }
 
   /// Indicates that other users have read-only permission.
   @_alwaysEmitIntoClient

Sources/System/Internals/Backcompat.swift

@@ -0,0 +1,29 @@
+/*
+ This source file is part of the Swift System open source project
+
+ Copyright (c) 2021 Apple Inc. and the Swift System project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+*/
+
+extension String {
+  internal init(
+    _unsafeUninitializedCapacity capacity: Int,
+    initializingUTF8With body: (UnsafeMutableBufferPointer<UInt8>) throws -> Int
+  ) rethrows {
+    if #available(macOS 11, iOS 14.0, watchOS 7.0, tvOS 14.0, *) {
+      self = try String(
+        unsafeUninitializedCapacity: capacity,
+        initializingUTF8With: body)
+      return
+    }
+
+    let array = try Array<UInt8>(
+      unsafeUninitializedCapacity: capacity
+    ) { buffer, count in
+      count = try body(buffer)
+    }
+    self = String(decoding: array, as: UTF8.self)
+  }
+}