-
Notifications
You must be signed in to change notification settings - Fork 571
Foundation macOS xcode27.0 b1
Alex Soto edited this page Jun 9, 2026
·
1 revision
#Foundation.framework
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/FoundationErrors.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/FoundationErrors.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/FoundationErrors.h 2026-04-18 20:58:56
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/FoundationErrors.h 2026-05-27 00:45:54
@@ -10,116 +10,225 @@
*/
NS_ERROR_ENUM(NSCocoaErrorDomain) {
// File system and file I/O related errors, with NSFilePathErrorKey or NSURLErrorKey containing path or URL
- NSFileNoSuchFileError = 4, // Attempt to do a file system operation on a non-existent file
- NSFileLockingError = 255, // Couldn't get a lock on file
- NSFileReadUnknownError = 256, // Read error (reason unknown)
- NSFileReadNoPermissionError = 257, // Read error (permission problem)
- NSFileReadInvalidFileNameError = 258, // Read error (invalid file name)
- NSFileReadCorruptFileError = 259, // Read error (file corrupt, bad format, etc)
- NSFileReadNoSuchFileError = 260, // Read error (no such file)
- NSFileReadInapplicableStringEncodingError = 261, // Read error (string encoding not applicable) also NSStringEncodingErrorKey
- NSFileReadUnsupportedSchemeError = 262, // Read error (unsupported URL scheme)
- NSFileReadTooLargeError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 263, // Read error (file too large)
- NSFileReadUnknownStringEncodingError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 264, // Read error (string encoding of file contents could not be determined)
- NSFileWriteUnknownError = 512, // Write error (reason unknown)
- NSFileWriteNoPermissionError = 513, // Write error (permission problem)
- NSFileWriteInvalidFileNameError = 514, // Write error (invalid file name)
- NSFileWriteFileExistsError API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) = 516, // Write error (file exists)
- NSFileWriteInapplicableStringEncodingError = 517, // Write error (string encoding not applicable) also NSStringEncodingErrorKey
- NSFileWriteUnsupportedSchemeError = 518, // Write error (unsupported URL scheme)
- NSFileWriteOutOfSpaceError = 640, // Write error (out of disk space)
- NSFileWriteVolumeReadOnlyError API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 642, // Write error (readonly volume)
+ /// A filesystem operation was attempted on a non-existent file.
+ NSFileNoSuchFileError = 4,
+ /// The file could not be locked.
+ NSFileLockingError = 255,
+ /// Read error, for unknown reasons.
+ NSFileReadUnknownError = 256,
+ /// Could not read because of a permission problem.
+ NSFileReadNoPermissionError = 257,
+ /// Could not read because of an invalid file name.
+ NSFileReadInvalidFileNameError = 258,
+ /// Could not read because of a corrupted file, bad format, or similar reason.
+ NSFileReadCorruptFileError = 259,
+ /// Could not read because no such file was found.
+ NSFileReadNoSuchFileError = 260,
+ /// Could not read because the string encoding was not applicable.
+ ///
+ /// Access the bad encoding from the `userInfo` dictionary using the ``NSStringEncodingErrorKey`` key.
+ NSFileReadInapplicableStringEncodingError = 261,
+ /// Could not read because the specified URL scheme is unsupported.
+ NSFileReadUnsupportedSchemeError = 262,
+ /// Could not read because the specified file was too large.
+ NSFileReadTooLargeError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 263,
+ /// Could not read because the string encoding of the file contents could not be determined.
+ NSFileReadUnknownStringEncodingError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 264,
+ /// Write error, for unknown reasons.
+ NSFileWriteUnknownError = 512,
+ /// Could not write because of a permission problem.
+ NSFileWriteNoPermissionError = 513,
+ /// Could not write because of an invalid file name.
+ NSFileWriteInvalidFileNameError = 514,
+ /// Could not perform an operation because the destination file already exists.
+ ///
+ /// This error can be produced by the ``NSFileManager`` class's copy, move, and link methods.
+ NSFileWriteFileExistsError API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) = 516,
+ /// Could not write because the string encoding was not applicable.
+ ///
+ /// Access the bad encoding from the `userInfo` dictionary using the ``NSStringEncodingErrorKey`` key.
+ NSFileWriteInapplicableStringEncodingError = 517,
+ /// Could not write because the specified URL scheme is unsupported.
+ NSFileWriteUnsupportedSchemeError = 518,
+ /// Could not write because of a lack of disk space.
+ NSFileWriteOutOfSpaceError = 640,
+ /// Could not write because the volume is read-only.
+ NSFileWriteVolumeReadOnlyError API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 642,
// NSFileManager unmount errors
- NSFileManagerUnmountUnknownError API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos) = 768, // The volume could not be unmounted (reason unknown)
- NSFileManagerUnmountBusyError API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos) = 769, // The volume could not be unmounted because it is in use
+ /// The volume could not be unmounted (reason unknown).
+ NSFileManagerUnmountUnknownError API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos) = 768,
+ /// The volume could not be unmounted because it is in use.
+ NSFileManagerUnmountBusyError API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos) = 769,
// Other errors
- NSKeyValueValidationError = 1024, // KVC validation error
- NSFormattingError = 2048, // Formatting error
- NSUserCancelledError = 3072, // User cancelled operation (this one often doesn't deserve a panel and might be a good one to special case)
- NSFeatureUnsupportedError API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) = 3328, // Feature unsupported error
-
+ /// A key-value coding validation error.
+ NSKeyValueValidationError = 1024,
+ /// A formatter could not generate a string for an object, or parse a string into an object.
+ NSFormattingError = 2048,
+ /// The user canceled the operation (for example, by pressing Command-period).
+ ///
+ /// This code is for errors that do not require a dialog displayed and might be candidates for special-casing.
+ NSUserCancelledError = 3072,
+ /// The feature is not supported, because the file system lacks the feature, or required libraries are missing, or other similar reasons.
+ ///
+ /// For example, some volumes may not support a Trash folder, so these methods will report failure by returning `false` or `nil` and an ``NSError`` with ``NSFeatureUnsupportedError``.
+ NSFeatureUnsupportedError API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) = 3328,
+
// Executable loading errors
- NSExecutableNotLoadableError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3584, // Executable is of a type that is not loadable in the current process
- NSExecutableArchitectureMismatchError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3585, // Executable does not provide an architecture compatible with the current process
- NSExecutableRuntimeMismatchError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3586, // Executable has Objective C runtime information incompatible with the current process
- NSExecutableLoadError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3587, // Executable cannot be loaded for some other reason, such as a problem with a library it depends on
- NSExecutableLinkError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3588, // Executable fails due to linking issues
-
+ /// The executable type is not loadable in the current process.
+ NSExecutableNotLoadableError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3584,
+ /// The executable does not provide an architecture compatible with the current process.
+ NSExecutableArchitectureMismatchError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3585,
+ /// The executable has Objective-C runtime information incompatible with the current process.
+ NSExecutableRuntimeMismatchError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3586,
+ /// The executable cannot be loaded for an otherwise-unspecified reason.
+ ///
+ /// This error covers situations such as an error caused by a library the executable depends on.
+ NSExecutableLoadError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3587,
+ /// The executable failed due to linking issues.
+ NSExecutableLinkError API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3588,
+
// Inclusive error range definitions, for checking future error codes
+ /// The start of the range of error codes reserved for file errors.
NSFileErrorMinimum = 0,
+ /// The end of the range of error codes reserved for file errors.
NSFileErrorMaximum = 1023,
-
+
+ /// The start of the range of error codes reserved for validation errors.
NSValidationErrorMinimum = 1024,
+ /// The end of the range of error codes reserved for validation errors.
NSValidationErrorMaximum = 2047,
+ /// The beginning of the range of error codes reserved for errors related to executable files.
NSExecutableErrorMinimum API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3584,
+ /// The end of the range of error codes reserved for errors related to executable files.
NSExecutableErrorMaximum API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = 3839,
+ /// The start of the range of error codes reserved for formatting errors.
NSFormattingErrorMinimum = 2048,
+ /// The end of the range of error codes reserved for formatting errors.
NSFormattingErrorMaximum = 2559,
-
- NSPropertyListReadCorruptError API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 3840, // Error parsing a property list
- NSPropertyListReadUnknownVersionError API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 3841, // The version number in the property list is unknown
- NSPropertyListReadStreamError API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 3842, // Stream error reading a property list
- NSPropertyListWriteStreamError API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 3851, // Stream error writing a property list
- NSPropertyListWriteInvalidError API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 3852, // Invalid property list object or invalid property list type specified when writing
+ /// Parsing of the property list failed.
+ NSPropertyListReadCorruptError API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 3840,
+ /// The version number of the property list could not be determined.
+ NSPropertyListReadUnknownVersionError API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 3841,
+ /// Reading of the property list failed.
+ NSPropertyListReadStreamError API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 3842,
+ /// Writing to the property list failed.
+ NSPropertyListWriteStreamError API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 3851,
+ /// Writing failed because of an invalid property list object, or an invalid property list type was specified.
+ NSPropertyListWriteInvalidError API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 3852,
+
+ /// The start of the range of error codes reserved for property list errors.
NSPropertyListErrorMinimum API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 3840,
+ /// The end of the range of error codes reserved for property list errors.
NSPropertyListErrorMaximum API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 4095,
+ /// The XPC connection was interrupted.
NSXPCConnectionInterrupted API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) = 4097,
+ /// The XPC connection was invalid.
NSXPCConnectionInvalid API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) = 4099,
+ /// The XPC connection reply was invalid.
NSXPCConnectionReplyInvalid API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) = 4101,
+ /// A code-signing requirement check failed.
+ ///
+ /// This error represents a failure to meet the requirement set by a call to ``NSXPCConnection``'s ``NSXPCConnection/setCodeSigningRequirement:`` method, or ``NSXPCListener``'s ``NSXPCListener/setConnectionCodeSigningRequirement:`` method.
NSXPCConnectionCodeSigningRequirementFailure API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), watchos(9.0)) = 4102,
-
+
+ /// The lower bounds of XPC connection error code values.
+ ///
+ /// All XPC error codes have values between ``NSXPCConnectionErrorMinimum`` and ``NSXPCConnectionErrorMaximum``, exclusive. This constant does not correspond to any particular error.
NSXPCConnectionErrorMinimum API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) = 4096,
+ /// The upper bounds of XPC connection error code values.
+ ///
+ /// All XPC error codes have values between ``NSXPCConnectionErrorMinimum`` and ``NSXPCConnectionErrorMaximum``, exclusive. This constant does not correspond to any particular error.
NSXPCConnectionErrorMaximum API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) = 4224,
- NSUbiquitousFileUnavailableError API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = 4353, // NSURLUbiquitousItemDownloadingErrorKey contains an error with this code when the item has not been uploaded to iCloud by the other devices yet
- NSUbiquitousFileNotUploadedDueToQuotaError API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = 4354, // NSURLUbiquitousItemUploadingErrorKey contains an error with this code when the item has not been uploaded to iCloud because it would make the account go over-quota
- NSUbiquitousFileUbiquityServerNotAvailable API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = 4355, // NSURLUbiquitousItemDownloadingErrorKey and NSURLUbiquitousItemUploadingErrorKey contain an error with this code when connecting to the iCloud servers failed
+ /// The item has not been uploaded to iCloud by another device yet.
+ ///
+ /// When this error occurs, you do not need to ask the system to start downloading the item. The system will download the item as soon as it can. If you want to know when the item becomes available, use an ``NSMetadataQuery`` object to monitor changes to the file's URL.
+ NSUbiquitousFileUnavailableError API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = 4353,
+ /// The item could not be uploaded to iCloud because it would make the account go over its quota.
+ NSUbiquitousFileNotUploadedDueToQuotaError API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = 4354,
+ /// Connecting to the iCloud servers failed.
+ NSUbiquitousFileUbiquityServerNotAvailable API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = 4355,
+ /// The minimum error code value that represents an iCloud error.
NSUbiquitousFileErrorMinimum API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = 4352,
+ /// The maximum error code value that represents an iCloud error.
NSUbiquitousFileErrorMaximum API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = 4607,
- NSUserActivityHandoffFailedError API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 4608, // The data for the user activity was not available (e.g. if the remote device became unavailable.)
- NSUserActivityConnectionUnavailableError API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 4609, // The user activity could not be continued because a required connection was not available
- NSUserActivityRemoteApplicationTimedOutError API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 4610, // The remote application failed to send data in time
- NSUserActivityHandoffUserInfoTooLargeError API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 4611, // The NSUserActivity userInfo dictionary was too large to receive
+ /// The data for the user activity wasn't available.
+ ///
+ /// This error can occur if the remote device became unavailable.
+ NSUserActivityHandoffFailedError API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 4608,
+ /// The user activity could not be continued because a required connection was not available.
+ NSUserActivityConnectionUnavailableError API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 4609,
+ /// The remote application failed to send data within the specified time.
+ NSUserActivityRemoteApplicationTimedOutError API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 4610,
+ /// The user activity's `userInfo` dictionary was too large to receive.
+ NSUserActivityHandoffUserInfoTooLargeError API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 4611,
+ /// The start of the range of error codes reserved for user activity errors.
NSUserActivityErrorMinimum API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 4608,
+ /// The end of the range of error codes reserved for user activity errors.
NSUserActivityErrorMaximum API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = 4863,
-
- NSCoderReadCorruptError API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4864, // Error parsing data during decode
- NSCoderValueNotFoundError API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4865, // Data requested was not found
- NSCoderInvalidValueError API_AVAILABLE(macos(10.13), ios(11.0), watchos(4.0), tvos(11.0)) = 4866, // Data was not valid to encode
+
+ /// Decoding failed due to corrupt data.
+ NSCoderReadCorruptError API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4864,
+ /// The requested data was not found.
+ NSCoderValueNotFoundError API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4865,
+ /// Data was not valid to encode.
+ NSCoderInvalidValueError API_AVAILABLE(macos(10.13), ios(11.0), watchos(4.0), tvos(11.0)) = 4866,
+ /// The start of the range of error codes reserved for coder errors.
NSCoderErrorMinimum API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4864,
+ /// The end of the range of error codes reserved for coder errors.
NSCoderErrorMaximum API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4991,
-
+
+ /// The start of the range of error codes reserved for bundle errors.
NSBundleErrorMinimum API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4992,
+ /// The end of the range of error codes reserved for bundle errors.
NSBundleErrorMaximum API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 5119,
-
- NSBundleOnDemandResourceOutOfSpaceError API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4992, // There was not enough space available to download the requested On Demand Resources.
- NSBundleOnDemandResourceExceededMaximumSizeError API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4993, // The application exceeded the amount of On Demand Resources content in use at one time
- NSBundleOnDemandResourceInvalidTagError API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4994, // The application specified a tag which the system could not find in the application tag manifest
-
- NSCloudSharingNetworkFailureError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5120, // Sharing failed due to a network failure.
- NSCloudSharingQuotaExceededError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5121, // The user doesn't have enough storage space available to share the requested items.
- NSCloudSharingTooManyParticipantsError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5122, // Additional participants could not be added to the share, because the limit was reached.
- NSCloudSharingConflictError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5123, // A conflict occurred while trying to save changes to the CKShare and/or root CKRecord. Respond to this error by first fetching the server's changes to the records, then either handle the conflict manually or present it, which will instruct the user to try the operation again.
- NSCloudSharingNoPermissionError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5124, // The current user doesn't have permission to perform the requested actions.
- NSCloudSharingOtherError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5375, // These errors may require application-specific responses. For CloudKit sharing, use the NSUnderlyingErrorKey, which is a CKErrorDomain error, to discover the specific error and refer to the CloudKit documentation for the proper response to these errors.
-
+
+ /// Insufficient space available to download the requested On Demand Resources.
+ NSBundleOnDemandResourceOutOfSpaceError API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4992,
+ /// The application exceeded the amount of On Demand Resources content in use at one time.
+ NSBundleOnDemandResourceExceededMaximumSizeError API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4993,
+ /// The application specified a tag that the system could not find in the application tag manifest.
+ NSBundleOnDemandResourceInvalidTagError API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = 4994,
+
+ /// Sharing failed due to a network failure.
+ NSCloudSharingNetworkFailureError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5120,
+ /// The user doesn't have enough storage space available to share the requested items.
+ NSCloudSharingQuotaExceededError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5121,
+ /// Additional participants could not be added to the share because the limit was reached.
+ NSCloudSharingTooManyParticipantsError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5122,
+ /// A conflict occurred during an attempt to save changes.
+ ///
+ /// This error occurs when a conflict is detected while trying to save changes to the `CKShare` or root `CKRecord`. Respond to this error by first fetching the server's changes to the records, then either handle the conflict manually or present it, which will instruct the user to try the operation again.
+ NSCloudSharingConflictError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5123,
+ /// The current user doesn't have permission to perform the requested actions.
+ NSCloudSharingNoPermissionError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5124,
+ /// An otherwise unspecified cloud-sharing error occurred.
+ ///
+ /// For CloudKit sharing, use the ``NSUnderlyingErrorKey``, whose value is a `CKErrorDomain` error, to discover the specific error. Refer to the CloudKit documentation for the proper response to these errors.
+ NSCloudSharingOtherError API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5375,
+
+ /// The start of the range of error codes reserved for cloud sharing errors.
NSCloudSharingErrorMinimum API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5120,
+ /// The end of the range of error codes reserved for cloud sharing errors.
NSCloudSharingErrorMaximum API_AVAILABLE(macosx(10.12), ios(10.0)) API_UNAVAILABLE(watchos, tvos) = 5375,
-
+
+ /// An error code value that indicates a failure to compress data using the provided algorithm.
NSCompressionFailedError API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0)) = 5376,
+ /// An error code value that indicates a failure to decompress data using the provided algorithm.
NSDecompressionFailedError API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0)) = 5377,
-
+
+ /// The start of the range of error codes reserved for compression errors.
NSCompressionErrorMinimum API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0)) = 5376,
+ /// The end of the range of error codes reserved for compression errors.
NSCompressionErrorMaximum API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0)) = 5503,
-
};
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAffineTransform.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAffineTransform.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAffineTransform.h 2026-04-18 22:35:12
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAffineTransform.h 2026-05-22 05:23:53
@@ -14,43 +14,132 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
+/// A structure that defines the three-by-three matrix that performs an affine transform between two coordinate systems.
typedef struct NS_SWIFT_SENDABLE {
- CGFloat m11, m12, m21, m22;
- CGFloat tX, tY;
+ /// An element of the transform matrix that contributes scaling, rotation, and shear.
+ CGFloat m11,
+ /// An element of the transform matrix that contributes scaling, rotation, and shear.
+ m12,
+ /// An element of the transform matrix that contributes scaling, rotation, and shear.
+ m21,
+ /// An element of the transform matrix that contributes scaling, rotation, and shear.
+ m22;
+ /// An element of the transform matrix that contributes translation along the x axis.
+ CGFloat tX,
+ /// An element of the transform matrix that contributes translation along the y axis.
+ tY;
} NSAffineTransformStruct;
+/// A graphics coordinate transformation.
+///
+/// In Swift, this object bridges to ``AffineTransform``; use ``NSAffineTransform`` when you need reference semantics or other Foundation-specific behavior.
+///
+/// A transformation specifies how points in one coordinate system are transformed to points in another coordinate system. An affine transformation is a special type of transformation that preserves parallel lines in a path but does not necessarily preserve lengths or angles. Scaling, rotation, and translation are the most commonly used manipulations supported by affine transforms, but shearing is also possible.
+///
+/// > Note:
+/// > In OS X 10.3 and earlier the ``NSAffineTransform`` class was declared and implemented entirely in the Application Kit framework. As of macOS 10.4 the ``NSAffineTransform`` class has been split across the Foundation and Application Kit frameworks.
+///
+/// Methods for applying affine transformations to the current graphics context and a method for applying an affine transformation to an <doc://com.apple.documentation/documentation/appkit/nsbezierpath> object are described in NSAffineTransform Additions Reference in the Application Kit.
+///
+/// > Important:
+/// > The Swift overlay to the Foundation framework provides the ``AffineTransform`` structure, which bridges to the ``NSAffineTransform`` class. For more information about value types, see <doc://com.apple.documentation/documentation/swift/working-with-foundation-types>.
@interface NSAffineTransform : NSObject <NSCopying, NSSecureCoding>
// Creation
+/// Creates a new affine transform initialized to the identity matrix.
+///
+/// - Returns: A new identity transform object. This matrix transforms any point to the same point.
+ (NSAffineTransform *)transform;
// Initialization
+/// Initializes the receiver's matrix using another transform object.
+///
+/// - Parameter transform: The transform object whose matrix values should be copied to this object.
+/// - Returns: A new transform object initialized with the matrix values of `transform`.
- (instancetype)initWithTransform:(NSAffineTransform *)transform;
+/// Initializes an affine transform matrix to the identity matrix.
- (instancetype)init NS_DESIGNATED_INITIALIZER;
// Translating
+/// Applies the specified translation factors to the receiver's transformation matrix.
+///
+/// Subsequent transformations cause coordinates to be shifted by `deltaX` units along the x axis and by `deltaY` units along the y axis. Translation factors do not affect `NSSize` values, which specify a differential between points.
+///
+/// - Parameter deltaX: The number of units to move along the x axis.
+/// - Parameter deltaY: The number of units to move along the y axis.
- (void)translateXBy:(CGFloat)deltaX yBy:(CGFloat)deltaY;
// Rotating
+/// Applies a rotation factor (measured in degrees) to the receiver's transformation matrix.
+///
+/// After invoking this method, applying the receiver's matrix turns the axes counterclockwise about the current origin by `angle` degrees, in addition to performing all previous transformations.
+///
+/// - Parameter angle: The rotation angle, measured in degrees.
- (void)rotateByDegrees:(CGFloat)angle;
+/// Applies a rotation factor (measured in radians) to the receiver's transformation matrix.
+///
+/// After invoking this method, applying the receiver's matrix turns the axes counterclockwise about the current origin by `angle` radians, in addition to performing all previous transformations.
+///
+/// - Parameter angle: The rotation angle, measured in radians.
- (void)rotateByRadians:(CGFloat)angle;
// Scaling
+/// Applies the specified scaling factor along both x and y axes to the receiver's transformation matrix.
+///
+/// After invoking this method, applying the receiver's matrix modifies the unit lengths along the current x and y axes by a factor of `scale`, in addition to performing all previous transformations.
+///
+/// - Parameter scale: The scaling factor to apply to both axes. Specifying a negative value has the effect of inverting the direction of the axes in addition to scaling them. A scaling factor of 1.0 scales the content to exactly the same size.
- (void)scaleBy:(CGFloat)scale;
+/// Applies scaling factors to each axis of the receiver's transformation matrix.
+///
+/// After invoking this method, applying the receiver's matrix modifies the unit length on the x axis by a factor of `scaleX` and the y axis by a factor of `scaleY`, in addition to performing all previous transformations. A value of 1.0 for either axis scales the content on that axis to the same size.
+///
+/// - Parameter scaleX: The scaling factor to apply to the x axis.
+/// - Parameter scaleY: The scaling factor to apply to the y axis.
- (void)scaleXBy:(CGFloat)scaleX yBy:(CGFloat)scaleY;
// Inverting
+/// Replaces the receiver's matrix with its inverse matrix.
+///
+/// Inverse matrices are useful for undoing the effects of a matrix. If a previous point (x,y) was transformed to (x',y'), inverting the matrix and applying it to point (x',y') yields the point (x,y).
+///
+/// You can also use inverse matrices in conjunction with the `concat()` method to remove the effects of concatenating the matrix to the current transformation matrix of the current graphic context.
- (void)invert;
// Transforming with transform
+/// Appends the specified matrix to the receiver's matrix.
+///
+/// This method multiplies the receiver's matrix by the matrix in `transform` and replaces the receiver's matrix with the results. This type of operation is the same as applying the transformations in the receiver followed by the transformations in `transform`.
+///
+/// - Parameter transform: The matrix to append to the receiver.
- (void)appendTransform:(NSAffineTransform *)transform;
+/// Prepends the specified matrix to the receiver's matrix.
+///
+/// This method multiplies the matrix in `transform` by the receiver's matrix and replaces the receiver's matrix with the result. This type of operation is the same as applying the transformations in `transform` followed by the transformations in the receiver.
+///
+/// - Parameter transform: The matrix to prepend to the receiver.
- (void)prependTransform:(NSAffineTransform *)transform;
// Transforming points and sizes
+/// Applies the receiver's transform to the specified point and returns the result.
+///
+/// - Parameter aPoint: The point in the current coordinate system to which you want to apply the matrix.
+/// - Returns: The resulting point after applying the receiver's transformations.
- (NSPoint)transformPoint:(NSPoint)aPoint;
+/// Applies the receiver's transform to the specified size and returns the results.
+///
+/// This method applies the current rotation and scaling factors to `aSize`; it does not apply translation factors. You can think of this method as transforming a vector whose origin is (0, 0) and whose end point is specified by the value in `aSize`. After the rotation and scaling factors are applied, this method effectively returns the end point of the new vector.
+///
+/// This method is useful for transforming delta or distance values when you need to take scaling and rotation factors into account.
+///
+/// - Parameter aSize: The size data to which you want to apply the matrix.
+/// - Returns: The resulting size after applying the receiver's transformations.
- (NSSize)transformSize:(NSSize)aSize;
// Transform Struct
+/// The matrix coefficients stored as the transformation matrix.
+///
+/// The ``NSAffineTransformStruct`` structure is an alternate representation of a transformation matrix that can be used to specify matrix values directly. The six-element structure is of the form `{m11, m12, m21, m22, tX, tY}`.
@property NSAffineTransformStruct transformStruct;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleEventDescriptor.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleEventDescriptor.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleEventDescriptor.h 2026-04-18 22:35:17
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleEventDescriptor.h 2026-05-22 05:23:50
@@ -12,20 +12,53 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
typedef NS_OPTIONS(NSUInteger, NSAppleEventSendOptions) {
- NSAppleEventSendNoReply = kAENoReply, /* sender doesn't want a reply to event */
- NSAppleEventSendQueueReply = kAEQueueReply, /* sender wants a reply but won't wait */
- NSAppleEventSendWaitForReply = kAEWaitReply, /* sender wants a reply and will wait */
- NSAppleEventSendNeverInteract = kAENeverInteract, /* server should not interact with user */
- NSAppleEventSendCanInteract = kAECanInteract, /* server may try to interact with user */
- NSAppleEventSendAlwaysInteract = kAEAlwaysInteract, /* server should always interact with user where appropriate */
- NSAppleEventSendCanSwitchLayer = kAECanSwitchLayer, /* interaction may switch layer */
- NSAppleEventSendDontRecord = kAEDontRecord, /* don't record this event */
- NSAppleEventSendDontExecute = kAEDontExecute, /* don't execute this event; used for recording */
- NSAppleEventSendDontAnnotate = kAEDoNotAutomaticallyAddAnnotationsToEvent, /* don't automatically add any sandbox or other annotations to the event */
+ /// Sender doesn't want a reply to event.
+ NSAppleEventSendNoReply = kAENoReply,
+ /// Sender wants a reply but won't wait.
+ NSAppleEventSendQueueReply = kAEQueueReply,
+ /// Sender wants a reply and will wait.
+ NSAppleEventSendWaitForReply = kAEWaitReply,
+ /// Server should not interact with user.
+ NSAppleEventSendNeverInteract = kAENeverInteract,
+ /// Server may try to interact with user.
+ NSAppleEventSendCanInteract = kAECanInteract,
+ /// Server should always interact with user where appropriate.
+ NSAppleEventSendAlwaysInteract = kAEAlwaysInteract,
+ /// Interaction may switch layer.
+ NSAppleEventSendCanSwitchLayer = kAECanSwitchLayer,
+ /// Don't record this event.
+ NSAppleEventSendDontRecord = kAEDontRecord,
+ /// Don't execute this event; used for recording.
+ NSAppleEventSendDontExecute = kAEDontExecute,
+ /// Don't automatically add any sandbox or other annotations to the event.
+ NSAppleEventSendDontAnnotate = kAEDoNotAutomaticallyAddAnnotationsToEvent,
+ /// The default options: wait for reply and allow interaction.
NSAppleEventSendDefaultOptions = NSAppleEventSendWaitForReply | NSAppleEventSendCanInteract
} API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
+/// A wrapper for the Apple event descriptor data type.
+///
+/// An instance of ``NSAppleEventDescriptor`` represents a descriptor—the basic building block for Apple events. This class is a wrapper for the underlying Apple event descriptor data type, <doc://com.apple.documentation/documentation/coreservices/aedesc>. Scriptable Cocoa applications frequently work with instances of ``NSAppleEventDescriptor``, but should rarely need to work directly with the <doc://com.apple.documentation/documentation/coreservices/aedesc> data structure.
+///
+/// A _descriptor_ is a data structure that stores data and an accompanying four-character code. A descriptor can store a value, or it can store a list of other descriptors (which may also be lists). All the information in an Apple event is stored in descriptors and lists of descriptors, and every Apple event is itself a descriptor list that matches certain criteria.
+///
+/// > Important:
+/// > An instance of `NSAppleEventDescriptor` can represent any kind of descriptor, from a simple value descriptor, to a descriptor list, to a full-fledged Apple event.
+///
+/// Descriptors can be used to build arbitrarily complex containers, so that one Apple event can represent a script statement such as `tell application "TextEdit" to get word 3 of paragraph 6 of document 3`.
+///
+/// In working with Apple event descriptors, it can be useful to understand some of the underlying data types. You'll find terms such as descriptor, descriptor list, Apple event record, and Apple event defined in Building an Apple Event in Apple Events Programming Guide. You'll also find information on the four-character codes used to identify information within a descriptor. Apple event data types are defined in <doc://com.apple.documentation/documentation/applicationservices/apple_event_manager>. The values of many four-character codes used by Apple (and in some cases reused by developers) can be found in [AppleScript Terminology and Apple Event Codes](http://developer.apple.com/releasenotes/AppleScript/ASTerminology_AppleEventCodes/TermsAndCodes.html).
+///
+/// The most common reason to construct an Apple event with an instance of `NSAppleEventDescriptor` is to supply information in a return Apple event. The most common situation where you might need to extract information from an Apple event (as an instance of `NSAppleEventDescriptor`) is when an Apple event handler installed by your application is invoked, as described in "Installing an Apple Event Handler" in [How Cocoa Applications Handle Apple Events](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_handle_AEs/SAppsHandleAEs.html#//apple_ref/doc/uid/20001239). In addition, if you execute an AppleScript script using the `NSAppleScript` class, you get an instance of `NSAppleEventDescriptor` as the return value, from which you can extract any required information.
+///
+/// When you work with an instance of `NSAppleEventDescriptor`, you can access the underlying descriptor directly, if necessary, with the ``aeDesc`` method. Other methods, including ``descriptorWithDescriptorType:bytes:length:`` make it possible to create and initialize instances of `NSAppleEventDescriptor` without creating temporary instances of `NSData`.
+///
+/// The designated initializer for `NSAppleEventDescriptor` is ``init(aeDescNoCopy:)``. However, it is unlikely that you will need to create a subclass of `NSAppleEventDescriptor`.
+///
+/// Cocoa doesn't currently provide a mechanism for applications to directly send raw Apple events (though compiling and executing an AppleScript script with `NSAppleScript` may result in Apple events being sent). However, Cocoa applications have full access to the Apple Event Manager C APIs for working with Apple events. So, for example, you might use an instance of `NSAppleEventDescriptor` to assemble an Apple event and call the Apple Event Manager function `AESend(_:_:_:_:_:_:_:)` to send it.
+///
+/// If you need to send Apple events, or if you need more information on some of the Apple event concepts described here, see Apple Events Programming Guide and <doc://com.apple.documentation/documentation/applicationservices/apple_event_manager>.
@interface NSAppleEventDescriptor : NSObject<NSCopying, NSSecureCoding> {
@private
AEDesc _desc;
@@ -33,103 +66,351 @@
char _padding[3];
}
-// Create an autoreleased NSAppleEventDescriptor whose AEDesc type is typeNull.
+/// Creates and initializes a descriptor with no parameter or attribute values set.
+///
+/// You don't typically call this method, as most `NSAppleEventDescriptor` instance methods can't be safely called on the returned empty descriptor.
+ (NSAppleEventDescriptor *)nullDescriptor;
-// Given some data, and a four-character type code, create and return an autoreleased NSAppleEventDescriptor that contains that data, with that type.
+/// Creates a descriptor initialized with the specified event type that stores the specified data (from a series of bytes).
+///
+/// - Parameters:
+/// - descriptorType: The descriptor type to be set in the returned descriptor.
+/// - bytes: The data, as a sequence of bytes, to be set in the returned descriptor.
+/// - byteCount: The length, in bytes, of the data to be set in the returned descriptor.
+/// - Returns: A descriptor with the specified type and data, or `nil` if an error occurs.
+ (nullable NSAppleEventDescriptor *)descriptorWithDescriptorType:(DescType)descriptorType bytes:(nullable const void *)bytes length:(NSUInteger)byteCount;
+
+/// Creates a descriptor initialized with the specified event type that stores the specified data (from an instance of `NSData`).
+///
+/// - Parameters:
+/// - descriptorType: The descriptor type to be set in the returned descriptor.
+/// - data: The data, as an instance of `NSData`, to be set in the returned descriptor.
+/// - Returns: A descriptor with the specified type and data, or `nil` if an error occurs.
+///
+/// You can use this method to create a descriptor that you can build into a complete Apple event by calling methods
+/// such as `-setAttributeDescriptor:forKeyword:`, `-setDescriptor:forKeyword:`, and `-setParamDescriptor:forKeyword:`.
+ (nullable NSAppleEventDescriptor *)descriptorWithDescriptorType:(DescType)descriptorType data:(nullable NSData *)data;
-// Given a value, create and return an autoreleased NSAppleEventDescriptor that contains that value, with an appropriate type (typeBoolean, typeEnumerated, typeSInt32, typeIEEE64BitFloatingPoint, or typeType, respectively).
+/// Creates a descriptor initialized with type `typeBoolean` that stores the specified Boolean value.
+///
+/// - Parameter boolean: The Boolean value to be set in the returned descriptor.
+/// - Returns: A descriptor with the specified Boolean value, or `nil` if an error occurs.
+ (NSAppleEventDescriptor *)descriptorWithBoolean:(Boolean)boolean;
+
+/// Creates a descriptor initialized with type `typeEnumerated` that stores the specified enumerator data type value.
+///
+/// - Parameter enumerator: A type code that identifies the type of enumerated data to be stored in the returned descriptor.
+/// - Returns: A descriptor with the specified enumerator data type value, or `nil` if an error occurs.
+ (NSAppleEventDescriptor *)descriptorWithEnumCode:(OSType)enumerator;
+
+/// Creates a descriptor initialized with Apple event type `typeSInt32` that stores the specified integer value.
+///
+/// - Parameter signedInt: The integer value to be stored in the returned descriptor.
+/// - Returns: A descriptor containing the specified integer value, or `nil` if an error occurs.
+ (NSAppleEventDescriptor *)descriptorWithInt32:(SInt32)signedInt;
+
+/// Creates a descriptor initialized with Apple event type `typeIEEE64BitFloatingPoint` that stores the specified double value.
+ (NSAppleEventDescriptor *)descriptorWithDouble:(double)doubleValue API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
+
+/// Creates a descriptor initialized with type `typeType` that stores the specified type value.
+///
+/// - Parameter typeCode: The type value to be set in the returned descriptor.
+/// - Returns: A descriptor with the specified type, or `nil` if an error occurs.
+ (NSAppleEventDescriptor *)descriptorWithTypeCode:(OSType)typeCode;
-// Given a string, date, or file URL object, respectively, create and return an autoreleased NSAppleEventDescriptor that contains that value.
+/// Creates a descriptor initialized with type `typeUnicodeText` that stores the text from the specified string.
+///
+/// - Parameter string: A string that specifies the text to be stored in the returned descriptor.
+/// - Returns: A descriptor that contains the text from the specified string, or `nil` if an error occurs.
+ (NSAppleEventDescriptor *)descriptorWithString:(NSString *)string;
+
+/// Creates a descriptor that stores the specified date value.
+ (NSAppleEventDescriptor *)descriptorWithDate:(NSDate *)date API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
+
+/// Creates a descriptor that stores the specified file URL.
+ (NSAppleEventDescriptor *)descriptorWithFileURL:(NSURL *)fileURL API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
-// Create and return an autoreleased event, list, or record NSAppleEventDescriptor, respectively.
+/// Creates a descriptor that represents an Apple event, initialized according to the specified information.
+///
+/// - Parameters:
+/// - eventClass: The event class to be set in the returned descriptor.
+/// - eventID: The event ID to be set in the returned descriptor.
+/// - targetDescriptor: A pointer to a descriptor that identifies the target application for the Apple event. Passing `nil` results in an Apple event descriptor that has no `keyAddressAttr` attribute (it is valid for an Apple event to have no target address attribute).
+/// - returnID: The return ID to be set in the returned descriptor. If you pass a value of `kAutoGenerateReturnID`, the Apple Event Manager assigns the created Apple event a return ID that is unique to the current session. If you pass any other value, the Apple Event Manager assigns that value for the ID.
+/// - transactionID: The transaction ID to be set in the returned descriptor. A transaction is a sequence of Apple events that are sent back and forth between client and server applications, beginning with the client's initial request for a service. All Apple events that are part of a transaction must have the same transaction ID. You can specify `kAnyTransactionID` if the Apple event is not one of a series of interdependent Apple events.
+/// - Returns: A descriptor for an Apple event, initialized according to the specified parameter values, or `nil` if an error occurs.
+///
+/// Constants such as `kAutoGenerateReturnID` and `kAnyTransactionID` are defined in `AE.framework`, a subframework of `ApplicationServices.framework`.
+ (NSAppleEventDescriptor *)appleEventWithEventClass:(AEEventClass)eventClass eventID:(AEEventID)eventID targetDescriptor:(nullable NSAppleEventDescriptor *)targetDescriptor returnID:(AEReturnID)returnID transactionID:(AETransactionID)transactionID;
+
+/// Creates and initializes an empty list descriptor.
+///
+/// A list descriptor is a descriptor whose data consists of one or more descriptors. You can add items to the list
+/// by calling `-insertDescriptor:atIndex:` or remove them with `-removeDescriptorAtIndex:`.
+///
+/// Invoking this method is equivalent to allocating an instance of `NSAppleEventDescriptor` and invoking `-initListDescriptor`.
+ (NSAppleEventDescriptor *)listDescriptor;
+
+/// Creates and initializes a descriptor for an Apple event record whose data has yet to be set.
+///
+/// An Apple event record is a descriptor whose data is a set of descriptors keyed by four-character codes.
+/// You can add information to the descriptor with methods such as `-setAttributeDescriptor:forKeyword:`,
+/// `-setDescriptor:forKeyword:`, and `-setParamDescriptor:forKeyword:`.
+///
+/// Invoking this method is equivalent to allocating an instance of `NSAppleEventDescriptor` and invoking `-initRecordDescriptor`.
+ (NSAppleEventDescriptor *)recordDescriptor;
-// Create and return an autoreleased application address descriptor using the current process, a pid, a url referring to an application, or an application bundle identifier, respectively. The result is suitable for use as the "targetDescriptor" parameter of +appleEventWithEventClass:/initWithEventClass:.
+/// Creates and returns an application address descriptor using the current process.
+///
+/// The result is suitable for use as the `targetDescriptor` parameter of `+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:`.
+ (NSAppleEventDescriptor *)currentProcessDescriptor API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
+
+/// Creates and returns an application address descriptor using the specified process identifier.
+///
+/// The result is suitable for use as the `targetDescriptor` parameter of `+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:`.
+ (NSAppleEventDescriptor *)descriptorWithProcessIdentifier:(pid_t)processIdentifier API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
+
+/// Creates and returns an application address descriptor using the specified bundle identifier.
+///
+/// The result is suitable for use as the `targetDescriptor` parameter of `+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:`.
+ (NSAppleEventDescriptor *)descriptorWithBundleIdentifier:(NSString *)bundleIdentifier API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
+
+/// Creates and returns an application address descriptor using the specified application URL.
+///
+/// The result is suitable for use as the `targetDescriptor` parameter of `+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:`.
+ (NSAppleEventDescriptor *)descriptorWithApplicationURL:(NSURL *)applicationURL API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
-// The designated initializer. The initialized object takes ownership of the passed-in AEDesc, and will call AEDisposeDesc() on it at deallocation time.
+/// Initializes a newly allocated instance as a descriptor for the specified Carbon `AEDesc` structure.
+///
+/// The initialized object takes responsibility for calling the `AEDisposeDesc` function on the `AEDesc` at object deallocation time.
+/// This is the designated initializer for this class.
+///
+/// - Parameter aeDesc: A pointer to the `AEDesc` structure to associate with the descriptor.
+/// - Returns: An instance of `NSAppleEventDescriptor` that is associated with the structure pointed to by `aeDesc`, or `nil` if an error occurs.
- (instancetype)initWithAEDescNoCopy:(const AEDesc *)aeDesc NS_DESIGNATED_INITIALIZER;
-// Other initializers.
+/// Initializes a newly allocated instance as a descriptor with the specified descriptor type and data (from an arbitrary sequence of bytes and a length count).
+///
+/// - Parameters:
+/// - descriptorType: The descriptor type to be set in the returned descriptor.
+/// - bytes: The data, as a sequence of bytes, to be set in the returned descriptor.
+/// - byteCount: The length, in bytes, of the data to be set in the returned descriptor.
+/// - Returns: An instance of `NSAppleEventDescriptor` with the specified type and data. Returns `nil` if an error occurs.
- (nullable instancetype)initWithDescriptorType:(DescType)descriptorType bytes:(nullable const void *)bytes length:(NSUInteger)byteCount;
+
+/// Initializes a newly allocated instance as a descriptor with the specified descriptor type and data (from an instance of `NSData`).
+///
+/// - Parameters:
+/// - descriptorType: The descriptor type to be set in the initialized descriptor.
+/// - data: The data to be set in the initialized descriptor.
+/// - Returns: An instance of `NSAppleEventDescriptor` with the specified type and data. Returns `nil` if an error occurs.
- (nullable instancetype)initWithDescriptorType:(DescType)descriptorType data:(nullable NSData *)data;
+
+/// Initializes a newly allocated instance as a descriptor for an Apple event, initialized with the specified values.
+///
+/// - Parameters:
+/// - eventClass: The event class to be set in the returned descriptor.
+/// - eventID: The event ID to be set in the returned descriptor.
+/// - targetDescriptor: A pointer to a descriptor that identifies the target application for the Apple event. Passing `nil` results in an Apple event descriptor that has no `keyAddressAttr` attribute.
+/// - returnID: The return ID to be set in the returned descriptor. Pass `kAutoGenerateReturnID` to have the Apple Event Manager assign a unique return ID.
+/// - transactionID: The transaction ID to be set in the returned descriptor. You can specify `kAnyTransactionID` if the Apple event is not one of a series of interdependent Apple events.
+/// - Returns: The initialized Apple event (an instance of `NSAppleEventDescriptor`), or `nil` if an error occurs.
- (instancetype)initWithEventClass:(AEEventClass)eventClass eventID:(AEEventID)eventID targetDescriptor:(nullable NSAppleEventDescriptor *)targetDescriptor returnID:(AEReturnID)returnID transactionID:(AETransactionID)transactionID;
+
+/// Initializes a newly allocated instance as an empty list descriptor.
+///
+/// You can add items to the empty list descriptor with `-insertDescriptor:atIndex:`. The list indices are one-based.
- (instancetype)initListDescriptor;
+
+/// Initializes a newly allocated instance as a descriptor that is an Apple event record.
+///
+/// An Apple event record is a descriptor whose data is a set of descriptors keyed by four-character codes.
+/// You can add information to the descriptor with methods such as `-setAttributeDescriptor:forKeyword:`,
+/// `-setDescriptor:forKeyword:`, and `-setParamDescriptor:forKeyword:`.
- (instancetype)initRecordDescriptor;
-// Return a pointer to the AEDesc that is encapsulated by the object.
+/// The `AEDesc` structure encapsulated by the receiver, if it has one.
+///
+/// If the receiver has a valid `AEDesc` structure, returns a pointer to it; otherwise returns `nil`.
@property (nullable, readonly) const AEDesc *aeDesc NS_RETURNS_INNER_POINTER;
-// Get the four-character type code or the data from a fully-initialized descriptor.
+/// The descriptor type of the receiver.
@property (readonly) DescType descriptorType;
+
+/// The receiver's data.
+///
+/// An instance of `NSData` containing the receiver's data, or `nil` if an error occurs.
@property (readonly, copy) NSData *data;
-// Return the contents of a descriptor, after coercing the descriptor's contents to typeBoolean, typeEnumerated, typeSInt32, typeIEEE64BitFloatingPoint, or typeType, respectively.
+/// The contents of the receiver as a Boolean value, coercing (to `typeBoolean`) if necessary.
+///
+/// The contents of the descriptor, as a Boolean value, or `false` if an error occurs.
@property (readonly) Boolean booleanValue;
+
+/// The contents of the receiver as an enumeration type, coercing to `typeEnumerated` if necessary.
+///
+/// The contents of the descriptor, as an enumeration type, or 0 if an error occurs.
@property (readonly) OSType enumCodeValue;
+
+/// The contents of the receiver as an integer, coercing (to `typeSInt32`) if necessary.
+///
+/// The contents of the descriptor, as an integer value, or 0 if an error occurs.
@property (readonly) SInt32 int32Value;
+
+/// The contents of the receiver as a double value, coercing (to `typeIEEE64BitFloatingPoint`) if necessary.
@property (readonly) double doubleValue API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
+
+/// The contents of the receiver as a type, coercing to `typeType` if necessary.
+///
+/// The contents of the descriptor, as a type, or 0 if an error occurs.
@property (readonly) OSType typeCodeValue;
-// Return the contents of a descriptor, after coercing the descriptor's contents to a string, date, or file URL, respectively.
+/// The contents of the receiver as a Unicode text string, coercing to `typeUnicodeText` if necessary.
+///
+/// The contents of the descriptor, as a string, or `nil` if an error occurs.
@property (nullable, readonly, copy) NSString *stringValue;
+
+/// The contents of the receiver as a date, coercing if necessary.
@property (nullable, readonly, copy) NSDate *dateValue API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
+
+/// The contents of the receiver as a file URL, coercing if necessary.
@property (nullable, readonly, copy) NSURL *fileURLValue API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
-// Accessors for an event descriptor.
+/// The event class for the receiver.
+///
+/// The event class (a four-character code) for the receiver, or 0 if an error occurs.
+/// The receiver must be an Apple event. An Apple event is identified by its event class and event ID,
+/// a pair of four-character codes stored as 32-bit integers.
@property (readonly) AEEventClass eventClass;
+
+/// The event ID for the receiver.
+///
+/// The event ID (a four-character code) for the receiver, or 0 if an error occurs.
+/// The receiver must be an Apple event.
@property (readonly) AEEventID eventID;
+
+/// The receiver's return ID (the ID for a reply Apple event).
+///
+/// The receiver's return ID (an integer value), or 0 if an error occurs. The receiver must be an Apple event.
@property (readonly) AEReturnID returnID;
+
+/// The receiver's transaction ID, if any.
+///
+/// The receiver's transaction ID (an integer value), or 0 if an error occurs. The receiver must be an Apple event.
@property (readonly) AETransactionID transactionID;
-// Set, retrieve, or remove parameter descriptors inside an event descriptor.
+/// Adds a descriptor to the receiver as an Apple event parameter identified by the specified keyword.
+///
+/// - Parameters:
+/// - descriptor: The parameter descriptor to add to the receiver.
+/// - keyword: A keyword (a four-character code) that identifies the parameter descriptor to add. If a descriptor with that keyword already exists in the receiver, it is replaced.
+///
+/// The receiver must be an Apple event or Apple event record, both of which can contain parameters.
- (void)setParamDescriptor:(NSAppleEventDescriptor *)descriptor forKeyword:(AEKeyword)keyword;
+
+/// Returns a descriptor for the receiver's Apple event parameter identified by the specified keyword.
+///
+/// - Parameter keyword: A keyword (a four-character code) that identifies the parameter descriptor to obtain.
+/// - Returns: A descriptor for the specified keyword, or `nil` if an error occurs.
+///
+/// The receiver must be an Apple event.
- (nullable NSAppleEventDescriptor *)paramDescriptorForKeyword:(AEKeyword)keyword;
+
+/// Removes the receiver's parameter descriptor identified by the specified keyword.
+///
+/// - Parameter keyword: A keyword (a four-character code) that identifies the parameter descriptor to remove.
+///
+/// The receiver must be an Apple event or Apple event record, both of which can contain parameters.
+/// Currently provides no indication if an error occurs.
- (void)removeParamDescriptorWithKeyword:(AEKeyword)keyword;
-// Set or retrieve attribute descriptors inside an event descriptor.
+/// Adds a descriptor to the receiver as an attribute identified by the specified keyword.
+///
+/// - Parameters:
+/// - descriptor: The attribute descriptor to add to the receiver.
+/// - keyword: A keyword (a four-character code) that identifies the attribute descriptor to add. If a descriptor with that keyword already exists in the receiver, it is replaced.
+///
+/// The receiver must be an Apple event. Currently provides no indication if an error occurs.
- (void)setAttributeDescriptor:(NSAppleEventDescriptor *)descriptor forKeyword:(AEKeyword)keyword;
+
+/// Returns a descriptor for the receiver's Apple event attribute identified by the specified keyword.
+///
+/// - Parameter keyword: A keyword (a four-character code) that identifies the descriptor to obtain.
+/// - Returns: The attribute descriptor for the specified keyword, or `nil` if an error occurs.
+///
+/// The receiver must be an Apple event.
- (nullable NSAppleEventDescriptor *)attributeDescriptorForKeyword:(AEKeyword)keyword;
-// Send an Apple event.
+/// Sends an Apple event.
- (nullable NSAppleEventDescriptor *)sendEventWithOptions:(NSAppleEventSendOptions)sendOptions timeout:(NSTimeInterval)timeoutInSeconds error:(NSError **)error API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
-// Return whether or not a descriptor is a record-like descriptor. Record-like descriptors function as records, but may have a descriptorType other than typeAERecord, such as typeObjectSpecifier.
+/// Returns whether or not the receiver is a record-like descriptor.
+///
+/// Record-like descriptors function as records, but may have a `descriptorType` other than `typeAERecord`,
+/// such as `typeObjectSpecifier`.
@property (readonly) BOOL isRecordDescriptor API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
-// Return the number of items inside a list or record descriptor.
+/// The number of descriptors in the receiver's descriptor list.
+///
+/// The number of descriptors in the receiver's descriptor list (possibly 0); returns 0 if an error occurs.
@property (readonly) NSInteger numberOfItems;
-// Set, retrieve, or remove indexed descriptors inside a list or record descriptor.
+/// Inserts a descriptor at the specified (one-based) position in the receiving descriptor list, replacing the existing descriptor, if any, at that position.
+///
+/// - Parameters:
+/// - descriptor: The descriptor to insert in the receiver. Specifying an index of 0 or count + 1 causes appending to the end of the list.
+/// - index: The one-based descriptor list position at which to insert the descriptor.
+///
+/// Because it actually replaces the descriptor, if any, at the specified position, this method might better be called
+/// `replaceDescriptor:atIndex:`. The receiver must be a list descriptor. The indices are one-based.
+/// Currently provides no indication if an error occurs.
- (void)insertDescriptor:(NSAppleEventDescriptor *)descriptor atIndex:(NSInteger)index;
+
+/// Returns the descriptor at the specified (one-based) position in the receiving descriptor list.
+///
+/// - Parameter index: The one-based descriptor list position of the descriptor to return.
+/// - Returns: The descriptor from the specified position (one-based) in the descriptor list, or `nil` if the specified descriptor cannot be obtained.
- (nullable NSAppleEventDescriptor *)descriptorAtIndex:(NSInteger)index;
+
+/// Removes the descriptor at the specified (one-based) position in the receiving descriptor list.
+///
+/// - Parameter index: The one-based position of the descriptor to remove.
+///
+/// The receiver must be a list descriptor. The indices are one-based. Currently provides no indication if an error occurs.
- (void)removeDescriptorAtIndex:(NSInteger)index;
-// Set, retrieve, or remove keyed descriptors inside a record descriptor.
+/// Adds a descriptor, identified by a keyword, to the receiver.
+///
+/// - Parameters:
+/// - descriptor: The descriptor to add to the receiver.
+/// - keyword: A keyword (a four-character code) that identifies the descriptor to add. If a descriptor with that keyword already exists in the receiver, it is replaced.
+///
+/// The receiver must be an Apple event or Apple event record. Currently provides no indication if an error occurs.
- (void)setDescriptor:(NSAppleEventDescriptor *)descriptor forKeyword:(AEKeyword)keyword;
+
+/// Returns the receiver's descriptor for the specified keyword.
+///
+/// - Parameter keyword: A keyword (a four-character code) that identifies the descriptor to obtain.
+/// - Returns: A descriptor for the specified keyword, or `nil` if an error occurs.
- (nullable NSAppleEventDescriptor *)descriptorForKeyword:(AEKeyword)keyword;
+
+/// Removes the receiver's descriptor identified by the specified keyword.
+///
+/// - Parameter keyword: A keyword (a four-character code) that identifies the descriptor to remove.
+///
+/// The receiver must be an Apple event or Apple event record. Currently provides no indication if an error occurs.
- (void)removeDescriptorWithKeyword:(AEKeyword)keyword;
-// Return the keyword associated with an indexed descriptor inside a record descriptor.
+/// Returns the keyword for the descriptor at the specified (one-based) position in the receiver.
+///
+/// - Parameter index: The one-based descriptor list position of the descriptor to get the keyword for.
+/// - Returns: The keyword (a four-character code) for the descriptor at the one-based location specified by `index`, or 0 if an error occurs.
- (AEKeyword)keywordForDescriptorAtIndex:(NSInteger)index;
-// Create and return a descriptor of the requested type, doing a coercion if that's appropriate and possible.
+/// Returns a descriptor obtained by coercing the receiver to the specified type.
+///
+/// - Parameter descriptorType: The descriptor type to coerce the receiver to.
+/// - Returns: A descriptor of the specified type, or `nil` if an error occurs.
- (nullable NSAppleEventDescriptor *)coerceToDescriptorType:(DescType)descriptorType;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleEventManager.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleEventManager.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleEventManager.h 2026-04-18 22:35:10
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleEventManager.h 2026-05-22 05:23:42
@@ -11,51 +11,91 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
+/// Identifies an Apple event whose handling has been suspended. Can be used to resume handling of the Apple event.
typedef const struct __NSAppleEventManagerSuspension* NSAppleEventManagerSuspensionID;
+/// A timeout constant indicating that the default timeout should be used.
extern const double NSAppleEventTimeOutDefault;
+/// A timeout constant indicating that there is no timeout.
extern const double NSAppleEventTimeOutNone;
+/// Posted by `NSAppleEventManager` before it first dispatches an Apple event.
extern NSNotificationName const NSAppleEventManagerWillProcessFirstEventNotification;
+/// A mechanism for registering handler routines for specific types of Apple events and dispatching events to those handlers.
+///
+/// Cocoa provides built-in scriptability support that uses scriptability information supplied by an application to automatically convert Apple events into script command objects that perform the desired operation. However, some applications may want to perform more basic Apple event handling, in which an application registers handlers for the Apple events it can process, then calls on the Apple Event Manager to dispatch received Apple events to the appropriate handler. `NSAppleEventManager` supports these mechanisms by providing methods to register and remove handlers and to dispatch Apple events to the appropriate handler, if one exists. For related information, see [How Cocoa Applications Handle Apple Events](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_handle_AEs/SAppsHandleAEs.html#//apple_ref/doc/uid/20001239)
+///
+/// Each application has at most one instance of `NSAppleEventManager`. To obtain a reference to it, you call the class method ``shared()``, which creates the instance if it doesn't already exist.
+///
+/// For information about the Apple Event Manager, see <doc://com.apple.documentation/documentation/applicationservices/apple_event_manager> and Apple Events Programming Guide.
@interface NSAppleEventManager : NSObject {
@private
BOOL _isPreparedForDispatch;
char _padding[3];
}
-// Get the pointer to the program's single NSAppleEventManager.
+/// Returns the single instance of `NSAppleEventManager`, creating it first if it doesn't exist.
+ (NSAppleEventManager *)sharedAppleEventManager;
-// Set or remove a handler for a specific kind of Apple Event. The handler method should have the same signature as:
-// - (void)handleAppleEvent:(NSAppleEventDescriptor *)event withReplyEvent:(NSAppleEventDescriptor *)replyEvent;
-// When it is invoked, the value of the first parameter will be the event to be handled. The value of the second parameter will be the reply event to fill in. A reply event object will always be passed in (replyEvent will never be nil), but it should not be touched if the event sender has not requested a reply, which is indicated by [replyEvent descriptorType]==typeNull.
+/// Registers the Apple event handler specified by `handler` for the event specified by `eventClass` and `eventID`.
+///
+/// If an event handler is already registered for the specified event class and event ID, removes it. The signature for `handler` should match the following:
+///
+/// ```objc
+/// - (void)handleAppleEvent:(NSAppleEventDescriptor *)event withReplyEvent:(NSAppleEventDescriptor *)replyEvent;
+/// ```
+///
+/// When it is invoked, the value of the first parameter will be the event to be handled. The value of the second parameter will be the reply event to fill in. A reply event object will always be passed in (replyEvent will never be nil), but it should not be touched if the event sender has not requested a reply, which is indicated by `[replyEvent descriptorType]==typeNull`.
- (void)setEventHandler:(id)handler andSelector:(SEL)handleEventSelector forEventClass:(AEEventClass)eventClass andEventID:(AEEventID)eventID;
+
+/// If an Apple event handler has been registered for the event specified by `eventClass` and `eventID`, removes it.
+///
+/// Otherwise does nothing.
- (void)removeEventHandlerForEventClass:(AEEventClass)eventClass andEventID:(AEEventID)eventID;
-// Given an event, reply event, and refCon of the sort passed into Apple event handler functions that can be registered with AEInstallEventHandler(), dispatch the event to a handler that has been registered with -setEventHandler:andSelector:forEventClass:andEventID:.
-// This method is primarily meant for Cocoa's internal use. It does not send events to other applications!
+/// Causes the Apple event specified by `theAppleEvent` to be dispatched to the appropriate Apple event handler, if one has been registered by calling `-setEventHandler:andSelector:forEventClass:andEventID:`.
+///
+/// The `theReply` parameter always specifies a reply Apple event, never `nil`. However, the handler should not fill out the reply if the descriptor type for the reply event is `typeNull`, indicating the sender does not want a reply.
+///
+/// The `handlerRefcon` parameter provides 4 bytes of data to the handler; a common use for this parameter is to pass a pointer to additional data.
+///
+/// This method is primarily intended for Cocoa's internal use. Note that _dispatching_ an event means routing an event to an appropriate handler in the current application. You cannot use this method to _send_ events to other applications.
- (OSErr)dispatchRawAppleEvent:(const AppleEvent *)theAppleEvent withRawReply:(AppleEvent *)theReply handlerRefCon:(SRefCon)handlerRefCon;
-// If an Apple event is being handled on the current thread (i.e., a handler that was registered with -setEventHandler:andSelector:forEventClass:andEventID: is being messaged at this instant or -setCurrentAppleEventAndReplyEventWithSuspensionID: has just been invoked), return the descriptor for the event. Return nil otherwise. The effects of mutating or retaining the returned descriptor are undefined, though it may be copied.
+/// Returns the descriptor for `currentAppleEvent` if an Apple event is being handled on the current thread.
+///
+/// An Apple event is being handled on the current thread if a handler that was registered with `-setEventHandler:andSelector:forEventClass:andEventID:` is being messaged at this instant or `-setCurrentAppleEventAndReplyEventWithSuspensionID:` has just been invoked. Returns `nil` otherwise. The effects of mutating or retaining the returned descriptor are undefined, although it may be copied.
@property (nullable, readonly, retain) NSAppleEventDescriptor *currentAppleEvent;
-// If an Apple event is being handled on the current thread (i.e., -currentAppleEvent would not return nil), return the corresponding reply event descriptor. Return nil otherwise. This descriptor, including any mutatations, will be returned to the sender of the current event when all handling of the event has been completed, if the sender has requested a reply. The effects of retaining the descriptor are undefined; it may be copied, but mutations of the copy will not be returned to the sender of the current event.
+/// Returns the corresponding reply event descriptor if an Apple event is being handled on the current thread.
+///
+/// An Apple event is being handled on the current thread if `currentAppleEvent` does not return `nil`. Returns `nil` otherwise. This descriptor, including any mutations, will be returned to the sender of the current event when all handling of the event has been completed, if the sender has requested a reply. The effects of retaining the descriptor are undefined; it may be copied, but mutations of the copy are not returned to the sender of the current event.
@property (nullable, readonly, retain) NSAppleEventDescriptor *currentReplyAppleEvent;
-// If an Apple event is being handled on the current thread (i.e., -currentAppleEvent would not return nil), suspend the handling of the event, returning an ID that must be used to resume the handling of the event. Return zero otherwise. The suspended event will no longer be the current event after this method has returned.
+/// Suspends the handling of the current event and returns an ID that must be used to resume the handling of the event if an Apple event is being handled on the current thread.
+///
+/// An Apple event is being handled on the current thread if `currentAppleEvent` does not return `nil`. Returns zero otherwise. The suspended event is no longer the current event after this method returns.
- (nullable NSAppleEventManagerSuspensionID)suspendCurrentAppleEvent NS_RETURNS_INNER_POINTER;
-// Given a nonzero suspension ID returned by an invocation of -suspendCurrentAppleEvent, return the descriptor for the event whose handling was suspended. The effects of mutating or retaining the returned descriptor are undefined, though it may be copied. This method may be invoked in any thread, not just the one in which the corresponding invocation of -suspendCurrentAppleEvent occurred.
+/// Given a nonzero suspension ID returned by an invocation of `-suspendCurrentAppleEvent`, returns the descriptor for the event whose handling was suspended.
+///
+/// The effects of mutating or retaining the returned descriptor are undefined, although it may be copied. This method may be invoked in any thread, not just the one in which the corresponding invocation of `-suspendCurrentAppleEvent` occurred.
- (NSAppleEventDescriptor *)appleEventForSuspensionID:(NSAppleEventManagerSuspensionID)suspensionID;
-// Given a nonzero suspension ID returned by an invocation of -suspendCurrentAppleEvent, return the corresponding reply event descriptor. This descriptor, including any mutatations, will be returned to the sender of the suspended event when handling of the event is resumed, if the sender has requested a reply. The effects of retaining the descriptor are undefined; it may be copied, but mutations of the copy will not be returned to the sender of the suspended event. This method may be invoked in any thread, not just the one in which the corresponding invocation of -suspendCurrentAppleEvent occurred.
+/// Given a nonzero suspension ID returned by an invocation of `-suspendCurrentAppleEvent`, returns the corresponding reply event descriptor.
+///
+/// This descriptor, including any mutations, will be returned to the sender of the suspended event when handling of the event is resumed, if the sender has requested a reply. The effects of retaining the descriptor are undefined; it may be copied, but mutations of the copy will not be returned to the sender of the suspended event. This method may be invoked in any thread, not just the one in which the corresponding invocation of `-suspendCurrentAppleEvent` occurred.
- (NSAppleEventDescriptor *)replyAppleEventForSuspensionID:(NSAppleEventManagerSuspensionID)suspensionID;
-// Given a nonzero suspension ID returned by an invocation of -suspendCurrentAppleEvent, set the values that will be returned by subsequent invocations of -currentAppleEvent and -currentReplyAppleEvent to be the event whose handling was suspended and its corresponding reply event, respectively. Redundant invocations of this method will be ignored.
+/// Given a nonzero suspension ID returned by an invocation of `-suspendCurrentAppleEvent`, sets the values that will be returned by subsequent invocations of `currentAppleEvent` and `currentReplyAppleEvent` to be the event whose handling was suspended and its corresponding reply event, respectively.
+///
+/// Redundant invocations of this method will be ignored.
- (void)setCurrentAppleEventAndReplyEventWithSuspensionID:(NSAppleEventManagerSuspensionID)suspensionID;
-// Given a nonzero suspension ID returned by an invocation of -suspendCurrentAppleEvent, signal that handling of the suspended event may now continue. This may result in the immediate sending of the reply event to the sender of the suspended event, if the sender has requested a reply. If the suspension ID has been used in a previous invocation of -setCurrentAppleEventAndReplyEventWithSuspensionID: the effects of that invocation will be completely undone. Subsequent invocations of other NSAppleEventManager methods using the same suspension ID are invalid. This method may be invoked in any thread, not just the one in which the corresponding invocation of -suspendCurrentAppleEvent occurred.
+/// Given a nonzero suspension ID returned by an invocation of `-suspendCurrentAppleEvent`, signal that handling of the suspended event may now continue.
+///
+/// This may result in the immediate sending of the reply event to the sender of the suspended event, if the sender has requested a reply. If the suspension ID has been used in a previous invocation of `-setCurrentAppleEventAndReplyEventWithSuspensionID:` the effects of that invocation will be completely undone. Subsequent invocations of other `NSAppleEventManager` methods using the same suspension ID are invalid. This method may be invoked in any thread, not just the one in which the corresponding invocation of `-suspendCurrentAppleEvent` occurred.
- (void)resumeWithSuspensionID:(NSAppleEventManagerSuspensionID)suspensionID;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleScript.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleScript.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleScript.h 2026-04-18 22:35:16
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAppleScript.h 2026-05-22 05:23:48
@@ -11,12 +11,38 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
// If the result of -initWithContentsOfURL:error:, -compileAndReturnError:, -executeAndReturnError:, or -executeAppleEvent:error:, signals failure (nil, NO, nil, or nil, respectively), a pointer to an autoreleased dictionary is put at the location pointed to by the error parameter. The error info dictionary may contain entries that use any combination of the following keys, including no entries at all.
+
+/// An `NSString` that supplies a detailed description of the error condition.
FOUNDATION_EXPORT NSString *const NSAppleScriptErrorMessage API_AVAILABLE(macos(10.2)) API_UNAVAILABLE(ios, watchos, tvos); // NSString
+
+/// An `NSNumber` that specifies the error number.
FOUNDATION_EXPORT NSString *const NSAppleScriptErrorNumber API_AVAILABLE(macos(10.2)) API_UNAVAILABLE(ios, watchos, tvos); // NSNumber
+
+/// An `NSString` that specifies the name of the application that generated the error.
FOUNDATION_EXPORT NSString *const NSAppleScriptErrorAppName API_AVAILABLE(macos(10.2)) API_UNAVAILABLE(ios, watchos, tvos); // NSString
+
+/// An `NSString` that provides a brief description of the error.
FOUNDATION_EXPORT NSString *const NSAppleScriptErrorBriefMessage API_AVAILABLE(macos(10.2)) API_UNAVAILABLE(ios, watchos, tvos); // NSString
+
+/// An `NSValue` that specifies a range.
FOUNDATION_EXPORT NSString *const NSAppleScriptErrorRange API_AVAILABLE(macos(10.2)) API_UNAVAILABLE(ios, watchos, tvos); // NSValue containing an NSRange
+/// An object that provides the ability to load, compile, and execute scripts.
+///
+/// This class provides applications with the ability to
+///
+/// - load a script from a URL or from a text string
+/// - compile or execute a script or an individual Apple event
+/// - obtain an `NSAppleEventDescriptor` containing the reply from an executed script or event
+/// - obtain an attributed string for a compiled script, suitable for display in a script editor
+/// - obtain various kinds of information about any errors that may occur
+///
+/// > Important:
+/// > `NSAppleScript` provides the ``executeAppleEvent(_:error:)`` method so that you can send an Apple event to invoke a handler in a script. (In an AppleScript script, a handler is the equivalent of a function.) However, you cannot use this method to send Apple events to other applications.
+///
+/// When you create an instance of `NSAppleScript` object, you can use a URL to specify a script that can be in either text or compiled form, or you can supply the script as a string. Should an error occur when compiling or executing the script, several of the methods return a dictionary containing error information. The keys for obtaining error information, such as ``errorMessage``, are described in the Constants section.
+///
+/// See also NSAppleScript Additions Reference in the Application Kit framework, which defines a method that returns the syntax-highlighted source code for a script.
@interface NSAppleScript : NSObject<NSCopying> {
@private
NSString *_source;
@@ -25,25 +51,56 @@
void *_reserved2;
}
-// Given a URL that locates a script, in either text or compiled form, initialize. Return nil and a pointer to an error information dictionary if an error occurs. This is a designated initializer for this class.
+/// Initializes a newly allocated script instance from the source identified by the passed URL.
+///
+/// - Parameters:
+/// - url: A URL that locates a script, in either text or compiled form.
+/// - errorInfo: On return, if an error occurs, a pointer to an error information dictionary.
+/// - Returns: The initialized script object, `nil` if an error occurs.
+///
+/// This method is a designated initializer for `NSAppleScript`.
- (nullable instancetype)initWithContentsOfURL:(NSURL *)url error:(NSDictionary<NSString *, id> * _Nullable * _Nullable)errorInfo NS_DESIGNATED_INITIALIZER;
-// Given a string containing the AppleScript source code of a script, initialize. Return nil if an error occurs. This is also a designated initializer for this class.
+/// Initializes a newly allocated script instance from the passed source.
+///
+/// - Parameter source: A string containing the source code of a script.
+/// - Returns: The initialized script object, `nil` if an error occurs.
+///
+/// This method is a designated initializer for `NSAppleScript`.
- (nullable instancetype)initWithSource:(NSString *)source NS_DESIGNATED_INITIALIZER;
-// Return the source code of the script if it is available, nil otherwise. It is possible for an NSAppleScript that has been instantiated with -initWithContentsOfURL:error: to be a script for which the source code is not available, but is nonetheless executable.
+/// The script source for the receiver.
+///
+/// It is possible for an `NSAppleScript` that has been instantiated with `-initWithContentsOfURL:error:` to be a script for which the source code is not available but is nonetheless executable.
@property (nullable, readonly, copy) NSString *source;
-// Return yes if the script is already compiled, no otherwise.
+/// A Boolean value that indicates whether the receiver's script has been compiled.
@property (readonly, getter=isCompiled) BOOL compiled;
-// Compile the script, if it is not already compiled. Return yes for success or if the script was already compiled, no and a pointer to an error information dictionary otherwise.
+/// Compiles the receiver, if it is not already compiled.
+///
+/// - Parameter errorInfo: On return, if an error occurs, a pointer to an error information dictionary.
+/// - Returns: `YES` for success or if the script was already compiled, `NO` otherwise.
- (BOOL)compileAndReturnError:(NSDictionary<NSString *, id> * _Nullable * _Nullable)errorInfo;
-// Execute the script, compiling it first if it is not already compiled. Return the result of executing the script, or nil and a pointer to an error information dictionary for failure.
+/// Executes the receiver, compiling it first if it is not already compiled.
+///
+/// - Parameter errorInfo: On return, if an error occurs, a pointer to an error information dictionary.
+/// - Returns: The result of executing the event, or `nil` if an error occurs.
+///
+/// Any changes to property values caused by executing the script do not persist.
- (NSAppleEventDescriptor *)executeAndReturnError:(NSDictionary<NSString *, id> * _Nullable * _Nullable)errorInfo;
-// Execute an Apple event in the context of the script, compiling the script first if it is not already compiled. Return the result of executing the event, or nil and a pointer to an error information dictionary for failure.
+/// Executes an Apple event in the context of the receiver, as a means of allowing the application to invoke a handler in the script.
+///
+/// - Parameters:
+/// - event: The Apple event to execute.
+/// - errorInfo: On return, if an error occurs, a pointer to an error information dictionary.
+/// - Returns: The result of executing the event, or `nil` if an error occurs.
+///
+/// Compiles the receiver before executing it if it is not already compiled.
+///
+/// > Important: You cannot use this method to send Apple events to other applications.
- (NSAppleEventDescriptor *)executeAppleEvent:(NSAppleEventDescriptor *)event error:(NSDictionary<NSString *, id> * _Nullable * _Nullable)errorInfo;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSArchiver.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSArchiver.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSArchiver.h 2026-04-18 22:35:16
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSArchiver.h 2026-05-22 05:23:49
@@ -9,8 +9,19 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
-/************ Archiving: Writing ****************/
+/* *********** Archiving: Writing ****************/
+/// A coder that stores an object's data to an archive.
+///
+/// ``NSArchiver``, a concrete subclass of ``NSCoder``, provides a way to encode objects into an architecture-independent format that can be stored in a file. When you archive a graph of objects, the class information and instance variables for each object are written to the archive. The companion class ``NSUnarchiver`` decodes the data in an archive and creates a graph of objects equivalent to the original set.
+///
+/// ``NSArchiver`` stores the archive data in a mutable data object (``NSMutableData``). After encoding the objects, you can have the ``NSArchiver`` object write this mutable data object immediately to a file, or you can retrieve the mutable data object for some other use.
+///
+/// In macOS 10.2 and later, ``NSArchiver`` and ``NSUnarchiver`` have been replaced by ``NSKeyedArchiver`` and ``NSKeyedUnarchiver`` respectively—see [Archives and Serializations Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Archiving.html#//apple_ref/doc/uid/10000047i).
+///
+/// @DeprecationSummary {
+/// Use ``NSKeyedArchiver`` instead.
+/// }
API_DEPRECATED("Use NSKeyedArchiver instead", macos(10.0,10.13), ios(2.0,11.0), watchos(2.0,4.0), tvos(9.0,11.0))
@interface NSArchiver : NSCoder {
@private
@@ -23,26 +34,94 @@
void *reserved;
}
+/// Returns an archiver, initialized to encode stream and version information into a given mutable data object.
+///
+/// - Parameters:
+/// - mdata: The mutable data object into which to write the archive. This value must not be `nil`.
+/// - Returns: An archiver object, initialized to encode stream and version information into `mdata`.
+///
+/// Raises an `NSInvalidArgumentException` if `mdata` is `nil`.
- (instancetype)initForWritingWithMutableData:(NSMutableData *)mdata NS_DESIGNATED_INITIALIZER;
-
+
+/// The receiver's archive data.
+///
+/// The returned data object is the same one specified as the argument to ``NSArchiver/init(forWritingWith:)``. It contains whatever data has been encoded thus far by invocations of the various encoding methods. It is safest not to invoke this method until after ``NSArchiver/encodeRootObject(_:)`` has returned. In other words, although it is possible for a class to invoke this method from within its ``NSCoding/encode(with:)`` method, that method must not alter the data.
@property (readonly, retain) NSMutableData *archiverData;
+/// Encodes a given root object, along with all of the objects it's connected to.
+///
+/// If any object is encountered more than once while traversing the graph, it is encoded only once, but the multiple references to it are stored.
+///
+/// This message must not be sent more than once to a given `NSArchiver` object; an `NSInvalidArgumentException` is raised if a root object has already been encoded. If you need to encode multiple object graphs, don't attempt to reuse an `NSArchiver` instance; instead, create a new one for each graph.
+///
+/// - Parameter rootObject: The root object of the object graph to archive.
- (void)encodeRootObject:(id)rootObject;
+
+/// Encodes an object only if it is referenced by another object in the archive.
+///
+/// This method overrides the superclass implementation to allow `object` to be encoded only if it is also encoded unconditionally by another object in the object graph. Conditional encoding lets you encode one part of a graph detached from the rest.
+///
+/// This method should be invoked only from within an ``NSCoding/encode(with:)`` method. If `object` is `nil`, the `NSArchiver` object encodes it unconditionally as `nil`. This method raises an `NSInvalidArgumentException` if no root object has been encoded.
+///
+/// - Parameter object: The object to archive.
- (void)encodeConditionalObject:(nullable id)object;
+/// Returns a data object that contains the encoded form of the object graph formed by the given root object.
+///
+/// This method invokes ``NSArchiver/initForWritingWithMutableData:`` and ``NSArchiver/encodeRootObject:`` to create a temporary archiver that encodes the object graph.
+///
+/// - Parameter rootObject: The root object of the object graph to archive.
+/// - Returns: A data object containing the encoded form of the object graph whose root object is `rootObject`.
+ (NSData *)archivedDataWithRootObject:(id)rootObject;
+/// Archives an object graph rooted at a given object by encoding it into a data object then atomically writing the resulting data object to a file at a given path.
+///
+/// This convenience method invokes ``NSArchiver/archivedDataWithRootObject:`` to get the encoded data, and then sends that data object the message ``NSData/writeToFile:atomically:``, using `path` for the first argument and `YES` for the second.
+///
+/// The archived data should be retrieved from the archive by an ``NSUnarchiver`` object.
+///
+/// - Parameters:
+/// - rootObject: The root object of the object graph to archive.
+/// - path: The location of the file into which to write the archive.
+/// - Returns: `YES` if the archive was written successfully, otherwise `NO`.
+ (BOOL)archiveRootObject:(id)rootObject toFile:(NSString *)path;
+/// Encodes a given class under a given name.
+///
+/// Any subsequently encountered objects of class `trueName` are archived as instances of class `inArchiveName`. It is safest not to invoke this method during the archiving process (that is, within an ``NSCoding/encode(with:)`` method). Instead, invoke it before ``encodeRootObject:``.
+///
+/// - Parameters:
+/// - trueName: The real name of a class in the object graph being archived.
+/// - inArchiveName: The name of the class to use in the archive in place of `trueName`.
- (void)encodeClassName:(NSString *)trueName intoClassName:(NSString *)inArchiveName;
+/// Returns the name under which a given class was encoded.
+///
+/// - Parameter trueName: The real name of an encoded class.
+/// - Returns: The name of the class used to archive instances of the class `trueName`.
- (nullable NSString *)classNameEncodedForTrueClassName:(NSString *)trueName;
+/// Replaces one object with another during encoding.
+///
+/// Causes the receiver to treat subsequent requests to encode `object` as though they were requests to encode `newObject` instead. Both `object` and `newObject` must be valid objects.
+///
+/// - Parameters:
+/// - object: An object in the object graph being archived.
+/// - newObject: The object with which to replace `object` in the archive.
- (void)replaceObject:(id)object withObject:(id)newObject;
@end
-/************ Archiving: Reading ****************/
+/* *********** Archiving: Reading ****************/
+/// A decoder that restores data from an archive.
+///
+/// ``NSUnarchiver``, a concrete subclass of ``NSCoder``, defines methods for decoding a set of Objective-C objects from an archive. Such archives are produced by objects of the ``NSArchiver`` class.
+///
+/// In macOS 10.2 and later, ``NSArchiver`` and ``NSUnarchiver`` have been replaced by ``NSKeyedArchiver`` and ``NSKeyedUnarchiver`` respectively—see [Archives and Serializations Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Archiving.html#//apple_ref/doc/uid/10000047i).
+///
+/// @DeprecationSummary {
+/// Use ``NSKeyedUnarchiver`` instead.
+/// }
API_DEPRECATED("Use NSKeyedUnarchiver instead", macos(10.0,10.13), ios(2.0,11.0), watchos(2.0,4.0), tvos(9.0,11.0))
@interface NSUnarchiver : NSCoder {
@private
@@ -63,30 +142,97 @@
id reserved;
}
+/// Returns an `NSUnarchiver` object initialized to read an archive from a given data object.
+///
+/// The method decodes the system version number that was archived in `data` and prepares the `NSUnarchiver` object for a subsequent invocation of ``NSCoder/decodeObject()``.
+///
+/// Raises an `NSInvalidArgumentException` if `data` is `nil`.
+///
+/// - Parameter data: The archive data.
+/// - Returns: An `NSUnarchiver` object initialized to read an archive from `data`. Returns `nil` if `data` is not a valid archive.
- (nullable instancetype)initForReadingWithData:(NSData *)data NS_DESIGNATED_INITIALIZER;
+/// Sets the zone in which decoded objects are allocated.
- (void)setObjectZone:(nullable NSZone *)zone NS_AUTOMATED_REFCOUNT_UNAVAILABLE;
+/// Returns the zone in which decoded objects are allocated.
- (nullable NSZone *)objectZone NS_AUTOMATED_REFCOUNT_UNAVAILABLE;
+/// A Boolean value that indicates whether the receiver has reached the end of the encoded data while decoding.
+///
+/// You can invoke this after invoking `decodeObject` to discover whether the archive contains extra data following the encoded object graph. If it does, you can either ignore this anomaly or consider it an error.
@property (getter=isAtEnd, readonly) BOOL atEnd;
+/// The system version number in effect when the archive was created.
+///
+/// This information is available as soon as the receiver has been initialized.
@property (readonly) unsigned int systemVersion;
+/// Decodes and returns the previously-archived object graph in the given data.
+///
+/// This method invokes ``NSUnarchiver/initForReadingWithData:`` and ``NSCoder/decodeObject`` to create a temporary `NSUnarchiver` object that decodes the object. If the archived object is the root of a graph of objects, the entire graph is unarchived.
+///
+/// - Parameter data: An `NSData` object that contains an archive created using `NSArchiver`.
+/// - Returns: The object, or object graph, that was archived in `data`. Returns `nil` if `data` cannot be unarchived.
+ (nullable id)unarchiveObjectWithData:(NSData *)data;
+/// Decodes and returns the previously-archived object graph from the file at the given path.
+///
+/// This convenience method reads the file by invoking the `NSData` method ``NSData/dataWithContentsOfFile:`` and then invokes ``NSUnarchiver/unarchiveObjectWithData:``.
+///
+/// - Parameter path: The path to a file that contains an archive created using ``NSArchiver``.
+/// - Returns: The object, or object graph, that was archived in the file at `path`. Returns `nil` if the file at `path` cannot be unarchived.
+ (nullable id)unarchiveObjectWithFile:(NSString *)path;
+/// Sets a class-wide substitution mapping, translating a given class name from the archive to a given replacement class name during decoding.
+///
+/// This method enables easy conversion of unarchived data when the name of a class has changed since the archive was created.
+///
+/// Note that there is also an instance method of the same name. An instance of `NSUnarchiver` can maintain its own mapping of class names. However, if both the class method and the instance method have been invoked using an identical value for `inArchiveName`, the class method takes precedence.
+///
+/// - Parameters:
+/// - inArchiveName: The ostensible name of a class in an archive.
+/// - trueName: The name of the class to use when instantiating objects whose ostensible class, according to the archived data, is `inArchiveName`.
+ (void)decodeClassName:(NSString *)inArchiveName asClassName:(NSString *)trueName;
+/// Sets a per-instance substitution mapping, translating a given class name from the archive to a given replacement class name during decoding.
+///
+/// This method enables easy conversion of unarchived data when the name of a class has changed since the archive was created.
+///
+/// Note that there's also a class method of the same name. The class method has precedence in case of conflicts.
+///
+/// - Parameters:
+/// - inArchiveName: The ostensible name of a class in an archive.
+/// - trueName: The name of the class to use when instantiating objects whose ostensible class, according to the archived data, is `inArchiveName`.
- (void)decodeClassName:(NSString *)inArchiveName asClassName:(NSString *)trueName;
+/// Returns the class name that the unarchiver class substitutes for a given archived class name.
+///
+/// Returns `inArchiveName` if no substitute name has been specified using the class method ``NSUnarchiver/decodeClassName:asClassName:``.
+///
+/// Note that each individual instance of `NSUnarchiver` can be given its own class name mappings by invoking the instance method ``NSUnarchiver/decodeClassName:asClassName:``. The `NSUnarchiver` class has no information about these instance-specific mappings, however, so they don't affect the return value of this method.
+///
+/// - Parameter inArchiveName: The name of a class.
+/// - Returns: The name of the class used when instantiating objects whose ostensible class, according to the archived data, is `inArchiveName`.
+ (NSString *)classNameDecodedForArchiveClassName:(NSString *)inArchiveName;
+/// Returns the class name that this unarchiver substitutes for a given archived class name.
+///
+/// Returns `inArchiveName` unless a substitute name has been specified using the instance method ``decodeClassName:asClassName:``.
+///
+/// - Parameter inArchiveName: The name of a class.
+/// - Returns: The name of the class used when instantiating objects whose ostensible class, according to the archived data, is `inArchiveName`.
- (NSString *)classNameDecodedForArchiveClassName:(NSString *)inArchiveName;
+/// Replaces one object with another during decoding.
+///
+/// Causes the receiver to substitute `newObject` for `object` whenever `object` is extracted from the archive. `newObject` can be of a different class from `object`, and the class mappings set by ``decodeClassName:asClassName:`` are ignored.
+///
+/// - Parameters:
+/// - object: The archived object to replace.
+/// - newObject: The object with which to replace `object`.
- (void)replaceObject:(id)object withObject:(id)newObject;
@end
-/************ Object call back ****************/
+/* *********** Object call back ****************/
@interface NSObject (NSArchiverCallback)
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSArray.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSArray.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSArray.h 2026-04-18 19:13:13
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSArray.h 2026-05-27 00:45:57
@@ -10,91 +10,797 @@
@class NSData, NSIndexSet, NSString, NSURL;
-/**************** Immutable Array ****************/
+/* *************** Immutable Array ****************/
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
+/// A static ordered collection of objects.
+///
+/// You can use this type in Swift instead of an `Array` constant in cases that require reference semantics.
+///
+/// `NSArray` and its subclass `NSMutableArray` manage ordered collections of objects called **arrays**. `NSArray`
+/// creates static arrays, and `NSMutableArray` creates dynamic arrays. You can use arrays when you need an ordered
+/// collection of objects.
+///
+/// `NSArray` is "toll-free bridged" with its Core Foundation counterpart, `CFArray`. See
+/// [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html#//apple_ref/doc/uid/TP40010810-CH2)
+/// for more information on toll-free bridging.
+///
+/// ### Creating NSArray Objects Using Array Literals
+///
+/// In addition to the provided initializers, such as `initWithObjects:`, you can create an `NSArray` object using an
+/// _array literal_.
+///
+/// In Objective-C:
+///
+/// NSArray *array = @[someObject, @"Hello, World!", @42];
+///
+/// In Objective-C, the compiler generates code that makes an underlying call to the `initWithObjects:count:` method.
+///
+/// id objects[] = { someObject, @"Hello, World!", @42 };
+/// NSUInteger count = sizeof(objects) / sizeof(id);
+/// NSArray *array = [NSArray arrayWithObjects:objects
+/// count:count];
+///
+/// You should not terminate the list of objects with `nil` when using this literal syntax, and in fact `nil` is an
+/// invalid value. For more information about object literals in Objective-C, see
+/// [Working with Objects](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/WorkingwithObjects/WorkingwithObjects.html#//apple_ref/doc/uid/TP40011210-CH4)
+/// in
+/// [Programming with Objective-C](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html#//apple_ref/doc/uid/TP40011210).
+///
+/// ### Accessing Values Using Subscripting
+///
+/// In addition to the provided instance methods, such as `objectAtIndex:`, you can access `NSArray` values by their
+/// indexes using _subscripting_.
+///
+/// id value = array[3];
+///
+/// ### Subclassing Notes
+///
+/// There is typically little reason to subclass `NSArray`. The class does well what it is designed to do -- maintain an
+/// ordered collection of objects. But there are situations where a custom `NSArray` object might come in handy. Here
+/// are a few possibilities:
+///
+/// - Changing how `NSArray` stores the elements of its collection. You might do this for performance reasons or for
+/// better compatibility with legacy code.
+/// - Acquiring more information about what is happening to the collection (for example, statistics gathering).
+///
+/// #### Methods to Override
+///
+/// Any subclass of `NSArray` _must_ override the primitive instance methods `count` and `objectAtIndex:`. These methods
+/// must operate on the backing store that you provide for the elements of the collection. For this backing store you
+/// can use a static array, a standard `NSArray` object, or some other data type or mechanism. You may also choose to
+/// override, partially or fully, any other `NSArray` method for which you want to provide an alternative
+/// implementation.
+///
+/// You might want to implement an initializer for your subclass that is suited to the backing store that the subclass
+/// is managing. If you do, your initializer must invoke one of the designated initializers of the `NSArray` class,
+/// either `init` or `initWithObjects:count:`. The `NSArray` class adopts the `NSCopying`, `NSMutableCopying`, and
+/// `NSCoding` protocols; custom subclasses of `NSArray` should override the methods in these protocols as necessary.
+///
+/// Remember that `NSArray` is the public interface for a class cluster and what this entails for your subclass. You
+/// must provide the storage for your subclass and implement the primitive methods that directly act on that storage.
+///
+/// #### Alternatives to Subclassing
+///
+/// Before making a custom subclass of `NSArray`, investigate `NSPointerArray` and the corresponding Core Foundation
+/// type, `CFArray`. Because `NSArray` and `CFArray` are "toll-free bridged," you can substitute a `CFArray` object for
+/// a `NSArray` object in your code (with appropriate casting). Although they are corresponding types, `CFArray` and
+/// `NSArray` do not have identical interfaces or implementations, and you can sometimes do things with `CFArray` that
+/// you cannot easily do with `NSArray`. For example, `CFArray` provides a set of callbacks, some of which are for
+/// implementing custom retain-release behavior. If you specify `NULL` implementations for these callbacks, you can
+/// easily get a non-retaining array.
+///
+/// If the behavior you want to add supplements that of the existing class, you could write a category on `NSArray`.
+/// Keep in mind, however, that this category will be in effect for all instances of `NSArray` that you use, and this
+/// might have unintended consequences. Alternatively, you could use composition to achieve the desired behavior.
@interface NSArray<__covariant ObjectType> : NSObject <NSCopying, NSMutableCopying, NSSecureCoding, NSFastEnumeration>
+/// The number of objects in the array.
@property (readonly) NSUInteger count;
+/// Returns the object located at the specified index.
+///
+/// If `index` is beyond the end of the array (that is, if `index` is greater than or equal to the value returned by
+/// `count`), an `NSRangeException` is raised.
+///
+/// - Parameter index: An index within the bounds of the array.
+/// - Returns: The object located at `index`.
- (ObjectType)objectAtIndex:(NSUInteger)index;
+/// Initializes a newly allocated array.
+///
+/// After an immutable array has been initialized in this way, it cannot be modified.
+///
+/// This method is a designated initializer.
+///
+/// - Returns: An array.
- (instancetype)init NS_DESIGNATED_INITIALIZER;
+/// Initializes a newly allocated array to include a given number of objects from a given C array.
+///
+/// Elements are added to the new array in the same order they appear in `objects`, up to but not including index
+/// `count`.
+///
+/// After an immutable array has been initialized in this way, it can't be modified.
+///
+/// This method is a designated initializer.
+///
+/// - Parameters:
+/// - objects: A C array of objects.
+/// - cnt: The number of values from the `objects` C array to include in the new array. This number will be the count
+/// of the new array -- it must not be negative or greater than the number of elements in `objects`.
+/// - Returns: A newly allocated array including the first `count` objects from `objects`. The returned object might be
+/// different than the original receiver.
- (instancetype)initWithObjects:(const ObjectType _Nonnull [_Nullable])objects count:(NSUInteger)cnt NS_DESIGNATED_INITIALIZER;
+/// - Parameter coder: The coder.
- (nullable instancetype)initWithCoder:(NSCoder *)coder NS_DESIGNATED_INITIALIZER;
@end
@interface NSArray<ObjectType> (NSExtendedArray)
+/// Returns a new array that is a copy of the receiving array with a given object added to the end.
+///
+/// If `anObject` is `nil`, an `NSInvalidArgumentException` is raised.
+///
+/// - Parameter anObject: An object.
+/// - Returns: A new array that is a copy of the receiving array with `anObject` added to the end.
- (NSArray<ObjectType> *)arrayByAddingObject:(ObjectType)anObject;
+/// Returns a new array that is a copy of the receiving array with the objects contained in another array added to the
+/// end.
+///
+/// - Parameter otherArray: An array.
+/// - Returns: A new array that is a copy of the receiving array with the objects contained in `otherArray` added to
+/// the end.
- (NSArray<ObjectType> *)arrayByAddingObjectsFromArray:(NSArray<ObjectType> *)otherArray;
+/// Constructs and returns an `NSString` object that is the result of interposing a given separator between the
+/// elements of the array.
+///
+/// For example, this code excerpt writes "`here be dragons`" to the console:
+///
+/// NSArray *pathArray = [NSArray arrayWithObjects:@"here", @"be", @"dragons", nil];
+/// NSLog(@"%@",[pathArray componentsJoinedByString:@" "]);
+///
+/// ### Special Considerations
+///
+/// Each element in the array must handle `description`.
+///
+/// - Parameter separator: The string to interpose between the elements of the array.
+/// - Returns: An `NSString` object that is the result of interposing `separator` between the elements of the array. If
+/// the array has no elements, returns an `NSString` object representing an empty string.
- (NSString *)componentsJoinedByString:(NSString *)separator;
+/// Returns a Boolean value that indicates whether a given object is present in the array.
+///
+/// Starting at index `0`, each element of the array is checked for equality with `anObject` until a match is found or
+/// the end of the array is reached. Objects are considered equal if `isEqual:` returns `YES`.
+///
+/// To determine if the array contains a particular instance of an object, you can test for identity rather than
+/// equality by calling the `indexOfObjectIdenticalTo:` method and comparing the return value to `NSNotFound`.
+///
+/// - Parameter anObject: An object to look for in the array.
+/// - Returns: `YES` if `anObject` is present in the array, otherwise `NO`.
- (BOOL)containsObject:(ObjectType)anObject;
+/// A string that represents the contents of the array, formatted as a property list.
@property (readonly, copy) NSString *description;
+/// Returns a string that represents the contents of the array, formatted as a property list.
+///
+/// For a description of how `locale` is applied to each element in the receiving array, see
+/// `descriptionWithLocale:indent:`.
+///
+/// - Parameter locale: An `NSLocale` object or an `NSDictionary` object that specifies options used for formatting
+/// each of the array's elements (where recognized). Specify `nil` if you don't want the elements formatted.
+/// - Returns: A string that represents the contents of the array, formatted as a property list.
- (NSString *)descriptionWithLocale:(nullable id)locale;
+/// Returns a string that represents the contents of the array, formatted as a property list.
+///
+/// The returned `NSString` object contains the string representations of each of the array's elements, in order, from
+/// first to last. To obtain the string representation of a given element, `descriptionWithLocale:indent:` proceeds as
+/// follows:
+///
+/// - If the element is an `NSString` object, it is used as is.
+/// - If the element responds to `descriptionWithLocale:indent:`, that method is invoked to obtain the element's string
+/// representation.
+/// - If the element responds to `descriptionWithLocale:`, that method is invoked to obtain the element's string
+/// representation.
+/// - If none of the above conditions is met, the element's string representation is obtained by invoking its
+/// `description` method.
+///
+/// - Parameters:
+/// - locale: An `NSLocale` object or an `NSDictionary` object that specifies options used for formatting each of the
+/// array's elements (where recognized). Specify `nil` if you don't want the elements formatted.
+/// - level: A level of indent, to make the output more readable: set `level` to `0` to use four spaces to indent, or
+/// `1` to indent the output with a tab character.
+/// - Returns: A string that represents the contents of the array, formatted as a property list.
- (NSString *)descriptionWithLocale:(nullable id)locale indent:(NSUInteger)level;
+/// Returns the first object contained in the receiving array that's equal to an object in another given array.
+///
+/// This method uses `isEqual:` to check for object equality.
+///
+/// - Parameter otherArray: An array.
+/// - Returns: Returns the first object contained in the receiving array that's equal to an object in `otherArray`. If
+/// no such object is found, returns `nil`.
- (nullable ObjectType)firstObjectCommonWithArray:(NSArray<ObjectType> *)otherArray;
+/// Copies references to objects contained in the array that fall within the specified range to `aBuffer`.
+///
+/// The method copies into `aBuffer` references to objects in the array in the range specified by `aRange`; the size of
+/// the buffer must therefore be at least the length of the range multiplied by the size of an object reference, as
+/// shown in the following example (this is solely for illustration -- you should typically not create a buffer simply
+/// to iterate over the contents of an array):
+///
+/// NSArray *mArray = // an array with at least six elements...;
+/// id *objects;
+///
+/// NSRange range = NSMakeRange(2, 4);
+/// objects = malloc(sizeof(id) * range.length);
+///
+/// [mArray getObjects:objects range:range];
+///
+/// for (i = 0; i < range.length; i++) {
+/// NSLog(@"objects: %@", objects[i]);
+/// }
+/// free(objects);
+///
+/// - Parameters:
+/// - objects: A C array of objects of size at least the length of the range specified by `aRange`.
+/// - range: A range within the bounds of the array. If the location plus the length of the range is greater than the
+/// count of the array, this method raises an `NSRangeException`.
- (void)getObjects:(ObjectType _Nonnull __unsafe_unretained [_Nonnull])objects range:(NSRange)range NS_SWIFT_UNAVAILABLE("Use 'subarrayWithRange()' instead");
+/// Returns the lowest index whose corresponding array value is equal to a given object.
+///
+/// Starting at index `0`, each element of the array is passed as an argument to an `isEqual:` message sent to
+/// `anObject` until a match is found or the end of the array is reached. Objects are considered equal if `isEqual:`
+/// (declared in the `NSObject` protocol) returns `YES`.
+///
+/// - Parameter anObject: An object.
+/// - Returns: The lowest index whose corresponding array value is equal to `anObject`. If none of the objects in the
+/// array is equal to `anObject`, returns `NSNotFound`.
- (NSUInteger)indexOfObject:(ObjectType)anObject;
+/// Returns the lowest index within a specified range whose corresponding array value is equal to a given object.
+///
+/// Starting at `range.location`, each element of the array is passed as an argument to an `isEqual:` message sent to
+/// `anObject` until a match is found or the end of the `range` is reached. Objects are considered equal if `isEqual:`
+/// returns `YES`.
+///
+/// This method raises an `NSRangeException` exception if the `range` parameter represents a range that doesn't exist
+/// in the array.
+///
+/// - Parameters:
+/// - anObject: An object.
+/// - range: The range of indexes in the array within which to search for `anObject`.
+/// - Returns: The lowest index within `range` whose corresponding array value is equal to `anObject`. If none of the
+/// objects within `range` is equal to `anObject`, returns `NSNotFound`.
- (NSUInteger)indexOfObject:(ObjectType)anObject inRange:(NSRange)range;
+/// Returns the lowest index whose corresponding array value is identical to a given object.
+///
+/// Objects are considered identical if their object addresses are the same.
+///
+/// - Parameter anObject: An object.
+/// - Returns: The lowest index whose corresponding array value is identical to `anObject`. If none of the objects in
+/// the array is identical to `anObject`, returns `NSNotFound`.
- (NSUInteger)indexOfObjectIdenticalTo:(ObjectType)anObject;
+/// Returns the lowest index within a specified range whose corresponding array value is equal to a given object.
+///
+/// Objects are considered identical if their object addresses are the same.
+///
+/// - Parameters:
+/// - anObject: An object.
+/// - range: The range of indexes in the array within which to search for `anObject`.
+/// - Returns: The lowest index within `range` whose corresponding array value is identical to `anObject`. If none of
+/// the objects within `range` is identical to `anObject`, returns `NSNotFound`.
- (NSUInteger)indexOfObjectIdenticalTo:(ObjectType)anObject inRange:(NSRange)range;
+/// Compares the receiving array to another array.
+///
+/// Two arrays have equal contents if they each hold the same number of objects and objects at a given index in each
+/// array satisfy the `isEqual:` test.
+///
+/// - Parameter otherArray: An array.
+/// - Returns: `YES` if the contents of `otherArray` are equal to the contents of the receiving array, otherwise `NO`.
- (BOOL)isEqualToArray:(NSArray<ObjectType> *)otherArray;
+/// The first object in the array.
+///
+/// If the array is empty, returns `nil`.
@property (nullable, nonatomic, readonly) ObjectType firstObject API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// The last object in the array.
+///
+/// If the array is empty, returns `nil`.
@property (nullable, nonatomic, readonly) ObjectType lastObject;
+/// Returns an enumerator object that lets you access each object in the array.
+///
+/// Returns an enumerator object that lets you access each object in the array, in order, starting with the element at
+/// index 0, as in:
+///
+/// NSEnumerator *enumerator = [myArray objectEnumerator];
+/// id anObject;
+///
+/// while (anObject = [enumerator nextObject]) {
+/// /* code to act on each element as it is returned */
+/// }
+///
+/// ### Special Considerations
+///
+/// When you use this method with mutable subclasses of `NSArray`, you must not modify the array during enumeration.
+///
+/// It is more efficient to use the fast enumeration protocol (see `NSFastEnumeration`). Fast enumeration is available
+/// in macOS 10.5 and later and iOS 2.0 and later.
+///
+/// - Returns: An enumerator object that lets you access each object in the array, in order, from the element at the
+/// lowest index upwards.
- (NSEnumerator<ObjectType> *)objectEnumerator;
+/// Returns an enumerator object that lets you access each object in the array, in reverse order.
+///
+/// When you use this method with mutable subclasses of `NSArray`, you must not modify the array during enumeration.
+///
+/// It is more efficient to use the fast enumeration protocol (see `NSFastEnumeration`). Fast enumeration is available
+/// in macOS 10.5 and later and iOS 2.0 and later.
+///
+/// - Returns: An enumerator object that lets you access each object in the array, in order, from the element at the
+/// highest index down to the element at index `0`.
- (NSEnumerator<ObjectType> *)reverseObjectEnumerator;
+/// Analyzes the array and returns a "hint" that speeds the sorting of the array when the hint is supplied to
+/// `sortedArrayUsingFunction:context:hint:`.
@property (readonly, copy) NSData *sortedArrayHint;
+/// Returns a new array that lists the receiving array's elements in ascending order as defined by the comparison
+/// function `comparator`.
+///
+/// The new array contains references to the receiving array's elements, not copies of them.
+///
+/// The comparison function is used to compare two elements at a time and should return `NSOrderedAscending` if the
+/// first element is smaller than the second, `NSOrderedDescending` if the first element is larger than the second, and
+/// `NSOrderedSame` if the elements are equal. Each time the comparison function is called, it's passed `context` as
+/// its third argument. This allows the comparison to be based on some outside parameter, such as whether character
+/// sorting is case-sensitive or case-insensitive.
+///
+/// Given `anArray` (an array of `NSNumber` objects) and a comparison function of this type:
+///
+/// NSInteger intSort(id num1, id num2, void *context)
+/// {
+/// int v1 = [num1 intValue];
+/// int v2 = [num2 intValue];
+/// if (v1 < v2)
+/// return NSOrderedAscending;
+/// else if (v1 > v2)
+/// return NSOrderedDescending;
+/// else
+/// return NSOrderedSame;
+/// }
+///
+/// A sorted version of `anArray` is created in this way:
+///
+/// NSArray *sortedArray; sortedArray = [anArray sortedArrayUsingFunction:intSort context:NULL];
- (NSArray<ObjectType> *)sortedArrayUsingFunction:(NSInteger (NS_NOESCAPE *)(ObjectType, ObjectType, void * _Nullable))comparator context:(nullable void *)context;
+/// Returns a new array that lists the receiving array's elements in ascending order as defined by the comparison
+/// function `comparator`.
+///
+/// The new array contains references to the receiving array's elements, not copies of them.
+///
+/// This method is similar to `sortedArrayUsingFunction:context:`, except that it uses the supplied hint to speed the
+/// sorting process. When you know the array is nearly sorted, this method is faster than
+/// `sortedArrayUsingFunction:context:`. If you sorted a large array (`N` entries) once, and you don't change it much
+/// (`P` additions and deletions, where `P` is much smaller than `N`), then you can reuse the work you did in the
+/// original sort by conceptually doing a merge sort between the `N` "old" items and the `P` "new" items.
+///
+/// To obtain an appropriate hint, use `sortedArrayHint`. You should obtain this hint when the original array has been
+/// sorted, and keep hold of it until you need it, after the array has been modified. The hint is computed by
+/// `sortedArrayHint` in `O(N)` (where `N` is the number of items). This assumes that items in the array implement a
+/// `-hash` method. Given a suitable hint, and assuming that the hash function is a "good" hash function,
+/// `sortedArrayUsingFunction:context:hint:` sorts the array in `O(P*LOG(P)+N)` where `P` is the number of adds or
+/// deletes. This is an improvement over the un-hinted sort, `O(N*LOG(N))`, when `P` is small.
+///
+/// The hint is simply an array of size `N` containing the `N` hashes. To re-sort you need internally to create a map
+/// table mapping a hash to the index. Using this map table on the new array, you can get a first guess for the
+/// indexes, and then sort that. For example, a sorted array \{A, B, D, E, F\} with corresponding hash values
+/// \{25, 96, 78, 32, 17\}, may be subject to small changes that result in contents \{E, A, C, B, F\}. The mapping
+/// table maps the hashes \{25, 96, 78, 32, 17\} to the indexes \{#0, #1, #2, #3, #4\}. If the hashes for
+/// \{E, A, C, B, F\} are \{32, 25, 99, 96, 17\}, then by using the mapping table you can get a first order sort
+/// \{#3, #0, ?, #1, #4\}, so therefore create an initial semi-sorted array \{A, B, E, F\}, and then perform a cheap
+/// merge sort with \{C\} that yields \{A, B, C, E, F\}.
- (NSArray<ObjectType> *)sortedArrayUsingFunction:(NSInteger (NS_NOESCAPE *)(ObjectType, ObjectType, void * _Nullable))comparator context:(nullable void *)context hint:(nullable NSData *)hint;
+/// Returns an array that lists the receiving array's elements in ascending order, as determined by the comparison
+/// method specified by a given selector.
+///
+/// The new array contains references to the receiving array's elements, not copies of them.
+///
+/// The `comparator` message is sent to each object in the array and has as its single argument another object in the
+/// array.
+///
+/// For example, an array of `NSString` objects can be sorted by using the `caseInsensitiveCompare:` method declared in
+/// the `NSString` class. Assuming `anArray` exists, a sorted version of the array can be created in this way:
+///
+/// NSArray *sortedArray =
+/// [anArray sortedArrayUsingSelector:@selector(caseInsensitiveCompare:)];
+///
+/// - Parameter comparator: A selector that identifies the method to use to compare two elements at a time. The method
+/// should return `NSOrderedAscending` if the receiving array is smaller than the argument,
+/// `NSOrderedDescending` if the receiving array is larger than the argument, and `NSOrderedSame` if they are equal.
+/// - Returns: An array that lists the receiving array's elements in ascending order, as determined by the comparison
+/// method specified by the selector `comparator`.
- (NSArray<ObjectType> *)sortedArrayUsingSelector:(SEL)comparator;
+/// Returns a new array containing the receiving array's elements that fall within the limits specified by a given
+/// range.
+///
+/// If `range` isn't within the receiving array's range of elements, an `NSRangeException` is raised.
+///
+/// For example, the following code example creates an array containing the elements found in the first half of
+/// `wholeArray` (assuming `wholeArray` exists).
+///
+/// NSArray *halfArray;
+/// NSRange theRange;
+///
+/// theRange.location = 0;
+/// theRange.length = [wholeArray count] / 2;
+///
+/// halfArray = [wholeArray subarrayWithRange:theRange];
+///
+/// - Parameter range: A range within the receiving array's range of elements.
+/// - Returns: A new array containing the receiving array's elements that fall within the limits specified by `range`.
- (NSArray<ObjectType> *)subarrayWithRange:(NSRange)range;
/* Serializes this instance to the specified URL in the NSPropertyList format (using NSPropertyListXMLFormat_v1_0). For other formats use NSPropertyListSerialization directly. */
- (BOOL)writeToURL:(NSURL *)url error:(NSError **)error API_AVAILABLE(macos(10.13), ios(11.0), watchos(4.0), tvos(11.0));
+/// Sends to each object in the array the message identified by a given selector, starting with the first object and
+/// continuing through the array to the last object.
+///
+/// This method raises an `NSInvalidArgumentException` if `aSelector` is `NULL`.
+///
+/// - Parameter aSelector: A selector that identifies the message to send to the objects in the array. The method must
+/// not take any arguments, and must not have the side effect of modifying the receiving array.
- (void)makeObjectsPerformSelector:(SEL)aSelector NS_SWIFT_UNAVAILABLE("Use enumerateObjectsUsingBlock: or a for loop instead");
+/// Sends the `aSelector` message to each object in the array, starting with the first object and continuing through
+/// the array to the last object.
+///
+/// This method raises an `NSInvalidArgumentException` if `aSelector` is `NULL`.
+///
+/// - Parameters:
+/// - aSelector: A selector that identifies the message to send to the objects in the array. The method must take a
+/// single argument of type id, and must not have the side effect of modifying the receiving array.
+/// - argument: The object to send as the argument to each invocation of the `aSelector` method.
- (void)makeObjectsPerformSelector:(SEL)aSelector withObject:(nullable id)argument NS_SWIFT_UNAVAILABLE("Use enumerateObjectsUsingBlock: or a for loop instead");
+/// Returns an array containing the objects in the array at the indexes specified by a given index set.
+///
+/// The returned objects are in the ascending order of their indexes in `indexes`, so that object in returned array with
+/// higher index in indexes will follow the object with smaller index in `indexes`.
+///
+/// Raises an `NSRangeException` if any location in `indexes` exceeds the bounds of the array, `indexes` is `nil`.
+///
+/// - Returns: An array containing the objects in the array at the indexes specified by `indexes`.
- (NSArray<ObjectType> *)objectsAtIndexes:(NSIndexSet *)indexes;
+/// Returns the object at the specified index.
+///
+/// This method has the same behavior as the `objectAtIndex:` method.
+///
+/// If `idx` is beyond the end of the array (that is, if `idx` is greater than or equal to the value returned by
+/// `count`), an `NSRangeException` is raised.
+///
+/// You shouldn't need to call this method directly. Instead, this method is called when accessing an object by index
+/// using subscripting.
+///
+/// id value = array[3]; // equivalent to [array objectAtIndex:3]
+///
+/// - Parameter idx: An index within the bounds of the array.
+/// - Returns: The object located at `idx`.
- (ObjectType)objectAtIndexedSubscript:(NSUInteger)idx API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0));
+/// Executes a given closure or block using each object in the array, starting with the first object and continuing
+/// through the array to the last object.
+///
+/// This method executes synchronously. Values allocated within the block are deallocated after the block is executed.
+///
+/// - Parameter block: A closure or block to execute for each object in the array, taking three arguments: the object,
+/// the index of the object in the array, and a reference to a Boolean value which the closure can set to `YES` in
+/// order to stop further enumeration of the array. If a closure stops further enumeration, that closure continues to
+/// run until it's finished.
- (void)enumerateObjectsUsingBlock:(void (NS_NOESCAPE ^)(ObjectType obj, NSUInteger idx, BOOL *stop))block API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Executes a given closure or block using each object in the array with the specified options.
+///
+/// This method executes synchronously. By default, the enumeration starts with the first object and continues serially
+/// through the array to the last object. You can specify `NSEnumerationConcurrent` and/or `NSEnumerationReverse` as
+/// enumeration options to modify this behavior.
+///
+/// - Parameters:
+/// - opts: The options for the enumeration. For possible values, see `NSEnumerationOptions`.
+/// - block: A closure or block to execute for each object in the array, taking three arguments: the object, the
+/// index of the object in the array, and a reference to a Boolean value which the closure can set to `YES` in order
+/// to stop further enumeration of the array. If a closure stops further enumeration, that closure continues to run
+/// until it's finished. When the `NSEnumerationConcurrent` enumeration option is specified, enumeration stops after
+/// all of the currently running closures finish.
- (void)enumerateObjectsWithOptions:(NSEnumerationOptions)opts usingBlock:(void (NS_NOESCAPE ^)(ObjectType obj, NSUInteger idx, BOOL *stop))block API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Executes a given block using the objects in the array at the specified indexes.
+///
+/// By default, the enumeration starts with the first object and continues serially through the array to the last
+/// element specified by `indexSet`. You can specify `NSEnumerationConcurrent` and/or `NSEnumerationReverse` as
+/// enumeration options to modify this behavior.
+///
+/// This method executes synchronously.
+///
+/// > Important: If the block parameter or the `indexSet` is `nil` this method will raise an exception.
+///
+/// - Parameters:
+/// - s: The indexes of the objects over which to enumerate.
+/// - opts: A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and
+/// whether it should be performed in reverse order).
+/// - block: The block to apply to elements in the array. The block takes three arguments: the element in the array,
+/// the index of the element in the array, and a reference to a Boolean value. The block can set the value to `YES`
+/// to stop further enumeration of the array. If a block stops further enumeration, that block continues to run
+/// until it's finished. When the `NSEnumerationConcurrent` enumeration option is specified, enumeration stops after
+/// all of the currently running blocks finish. The `stop` argument is an out-only argument. You should only ever
+/// set this Boolean to `YES` within the block.
- (void)enumerateObjectsAtIndexes:(NSIndexSet *)s options:(NSEnumerationOptions)opts usingBlock:(void (NS_NOESCAPE ^)(ObjectType obj, NSUInteger idx, BOOL *stop))block API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns the index of the first object in the array that passes a test in a given block.
+///
+/// If the block parameter is `nil` this method will raise an exception.
+///
+/// - Parameter predicate: The block to apply to elements in the array. The block takes three arguments: the element in
+/// the array, the index of the element in the array, and a reference to a Boolean value. The block can set the value
+/// to `YES` to stop further enumeration of the array. If a block stops further enumeration, that block continues to
+/// run until it's finished. The `stop` argument is an out-only argument. You should only ever set this Boolean to
+/// `YES` within the block. The block returns a Boolean value that indicates whether `obj` passed the test. Returning
+/// `YES` will stop further processing of the array.
+/// - Returns: The lowest index whose corresponding value in the array passes the test specified by `predicate`. If no
+/// objects in the array pass the test, returns `NSNotFound`.
- (NSUInteger)indexOfObjectPassingTest:(BOOL (NS_NOESCAPE ^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns the index of an object in the array that passes a test in a given block for a given set of enumeration
+/// options.
+///
+/// By default, the enumeration starts with the first object and continues serially through the array to the last
+/// object. You can specify `NSEnumerationConcurrent` and/or `NSEnumerationReverse` as enumeration options to modify
+/// this behavior.
+///
+/// > Important: If the block parameter is `nil` this method will raise an exception.
+///
+/// - Parameters:
+/// - opts: A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and
+/// whether it should be performed in reverse order).
+/// - predicate: The block to apply to elements in the array. The block takes three arguments: the element in the
+/// array, the index of the element in the array, and a reference to a Boolean value. The block can set the value to
+/// `YES` to stop further enumeration of the array. If a block stops further enumeration, that block continues to
+/// run until it's finished. When the `NSEnumerationConcurrent` enumeration option is specified, enumeration stops
+/// after all of the currently running blocks finish. The `stop` argument is an out-only argument. You should only
+/// ever set this Boolean to `YES` within the block. The block returns a Boolean value that indicates whether `obj`
+/// passed the test.
+/// - Returns: The index whose corresponding value in the array passes the test specified by `predicate` and `opts`. If
+/// the `opts` bit mask specifies reverse order, then the last item that matches is returned. Otherwise, the index of
+/// the first matching object is returned. If no objects in the array pass the test, returns `NSNotFound`.
- (NSUInteger)indexOfObjectWithOptions:(NSEnumerationOptions)opts passingTest:(BOOL (NS_NOESCAPE ^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns the index, from a given set of indexes, of the first object in the array that passes a test in a given
+/// block for a given set of enumeration options.
+///
+/// By default, the enumeration starts with the first object and continues serially through the array to the last
+/// element specified by `indexSet`. You can specify `NSEnumerationConcurrent` and/or `NSEnumerationReverse` as
+/// enumeration options to modify this behavior.
+///
+/// > Important: If the block parameter or `indexSet` is `nil` this method will raise an exception.
+///
+/// - Parameters:
+/// - s: The indexes of the objects over which to enumerate.
+/// - opts: A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and
+/// whether it should be performed in reverse order).
+/// - predicate: The block to apply to elements in the array. The block takes three arguments: the element in the
+/// array, the index of the element in the array, and a reference to a Boolean value. The block can set the value to
+/// `YES` to stop further enumeration of the array. If a block stops further enumeration, that block continues to
+/// run until it's finished. When the `NSEnumerationConcurrent` enumeration option is specified, enumeration stops
+/// after all of the currently running blocks finish. The `stop` argument is an out-only argument. You should only
+/// ever set this Boolean to `YES` within the block. The block returns a Boolean value that indicates whether `obj`
+/// passed the test.
+/// - Returns: The lowest index whose corresponding value in the array passes the test specified by `predicate`. If no
+/// objects in the array pass the test, returns `NSNotFound`.
- (NSUInteger)indexOfObjectAtIndexes:(NSIndexSet *)s options:(NSEnumerationOptions)opts passingTest:(BOOL (NS_NOESCAPE^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns the indexes of objects in the array that pass a test in a given block.
+///
+/// - Parameter predicate: The block to apply to elements in the array. The block takes three arguments: the element in
+/// the array, the index of the element in the array, and a reference to a Boolean value. The block can set the value
+/// to `YES` to stop further enumeration of the array. If a block stops further enumeration, that block continues to
+/// run until it's finished. The `stop` argument is an out-only argument. You should only ever set this Boolean to
+/// `YES` within the block. The block returns a Boolean value that indicates whether `obj` passed the test.
+/// - Returns: The indexes whose corresponding values in the array pass the test specified by `predicate`. If no
+/// objects in the array pass the test, returns an empty index set.
- (NSIndexSet *)indexesOfObjectsPassingTest:(BOOL (NS_NOESCAPE ^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns the indexes of objects in the array that pass a test in a given block for a given set of enumeration
+/// options.
+///
+/// By default, the enumeration starts with the first object and continues serially through the array to the last
+/// object. You can specify `NSEnumerationConcurrent` and/or `NSEnumerationReverse` as enumeration options to modify
+/// this behavior.
+///
+/// > Important: If the block parameter is `nil` this method will raise an exception.
+///
+/// - Parameters:
+/// - opts: A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and
+/// whether it should be performed in reverse order).
+/// - predicate: The block to apply to elements in the array. The block takes three arguments: the element in the
+/// array, the index of the element in the array, and a reference to a Boolean value. The block can set the value to
+/// `YES` to stop further enumeration of the array. If a block stops further enumeration, that block continues to
+/// run until it's finished. When the `NSEnumerationConcurrent` enumeration option is specified, enumeration stops
+/// after all of the currently running blocks finish. The `stop` argument is an out-only argument. You should only
+/// ever set this Boolean to `YES` within the block. The block returns a Boolean value that indicates whether `obj`
+/// passed the test.
+/// - Returns: The indexes whose corresponding values in the array pass the test specified by `predicate`. If no
+/// objects in the array pass the test, returns an empty index set.
- (NSIndexSet *)indexesOfObjectsWithOptions:(NSEnumerationOptions)opts passingTest:(BOOL (NS_NOESCAPE ^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns the indexes, from a given set of indexes, of objects in the array that pass a test in a given block for a
+/// given set of enumeration options.
+///
+/// By default, the enumeration starts with the first object and continues serially through the array to the last
+/// element specified by `indexSet`. You can specify `NSEnumerationConcurrent` and/or `NSEnumerationReverse` as
+/// enumeration options to modify this behavior.
+///
+/// > Important: If the block parameter or the `indexSet` is `nil` this method will raise an exception.
+///
+/// - Parameters:
+/// - s: The indexes of the objects over which to enumerate.
+/// - opts: A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and
+/// whether it should be performed in reverse order).
+/// - predicate: The block to apply to elements in the array. The block takes three arguments: the element in the
+/// array, the index of the element in the array, and a reference to a Boolean value. The block can set the value to
+/// `YES` to stop further enumeration of the array. If a block stops further enumeration, that block continues to
+/// run until it's finished. When the `NSEnumerationConcurrent` enumeration option is specified, enumeration stops
+/// after all of the currently running blocks finish. The `stop` argument is an out-only argument. You should only
+/// ever set this Boolean to `YES` within the block. The block returns a Boolean value that indicates whether `obj`
+/// passed the test.
+/// - Returns: The indexes whose corresponding values in the array pass the test specified by `predicate`. If no
+/// objects in the array pass the test, returns an empty index set.
- (NSIndexSet *)indexesOfObjectsAtIndexes:(NSIndexSet *)s options:(NSEnumerationOptions)opts passingTest:(BOOL (NS_NOESCAPE ^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns an array that lists the receiving array's elements in ascending order, as determined by the comparison
+/// method specified by a given `NSComparator` block.
+///
+/// - Parameter cmptr: A comparator block.
+/// - Returns: An array that lists the receiving array's elements in ascending order, as determined by the comparison
+/// method specified `cmptr`.
- (NSArray<ObjectType> *)sortedArrayUsingComparator:(NSComparator NS_NOESCAPE)cmptr API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns an array that lists the receiving array's elements in ascending order, as determined by the comparison
+/// method specified by a given `NSComparator` block.
+///
+/// - Parameters:
+/// - opts: A bit mask that specifies the options for the sort (whether it should be performed concurrently and
+/// whether it should be performed stably).
+/// - cmptr: A comparator block.
+/// - Returns: An array that lists the receiving array's elements in ascending order, as determined by the comparison
+/// method specified `cmptr`.
- (NSArray<ObjectType> *)sortedArrayWithOptions:(NSSortOptions)opts usingComparator:(NSComparator NS_NOESCAPE)cmptr API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Options for searches and insertions using ``NSArray/index(of:inSortedRange:options:usingComparator:)``.
typedef NS_OPTIONS(NSUInteger, NSBinarySearchingOptions) {
+ /// Specifies that the search should find the first object equal to the given object.
NSBinarySearchingFirstEqual = (1UL << 8),
+ /// Specifies that the search should find the last object equal to the given object.
NSBinarySearchingLastEqual = (1UL << 9),
+ /// Specifies that the search should return the insertion index for the given object.
NSBinarySearchingInsertionIndex = (1UL << 10),
};
-- (NSUInteger)indexOfObject:(ObjectType)obj inSortedRange:(NSRange)r options:(NSBinarySearchingOptions)opts usingComparator:(NSComparator NS_NOESCAPE)cmp API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)); // binary search
+/// Returns the index, within a specified range, of an object compared with elements in the array using a given
+/// `NSComparator` block.
+///
+/// The elements in the array must have already been sorted using the comparator `cmp`. If the array is not sorted, the
+/// result is undefined.
+///
+/// - Parameters:
+/// - obj: An object for which to search in the array. If this value is `nil`, throws an
+/// `NSInvalidArgumentException`.
+/// - r: The range within the array to search for `obj`. If `r` exceeds the bounds of the array (if the location plus
+/// length of the range is greater than the count of the array), throws an `NSRangeException`.
+/// - opts: Options for the search. For possible values, see `NSBinarySearchingOptions`. If you specify both
+/// `NSBinarySearchingFirstEqual` and `NSBinarySearchingLastEqual`, throws an `NSInvalidArgumentException`.
+/// - cmp: A comparator block used to compare the object `obj` with elements in the array. If this value is `NULL`,
+/// throws an `NSInvalidArgumentException`.
+/// - Returns: If the `NSBinarySearchingInsertionIndex` option is not specified: if the `obj` is found and neither
+/// `NSBinarySearchingFirstEqual` nor `NSBinarySearchingLastEqual` is specified, returns an arbitrary matching
+/// object's index. If the `NSBinarySearchingFirstEqual` option is also specified, returns the lowest index of equal
+/// objects. If the `NSBinarySearchingLastEqual` option is also specified, returns the highest index of equal objects.
+/// If the object is not found, returns `NSNotFound`.
+///
+/// If the `NSBinarySearchingInsertionIndex` option is specified, returns the index at which you should insert `obj`
+/// in order to maintain a sorted array: if the `obj` is found and neither `NSBinarySearchingFirstEqual` nor
+/// `NSBinarySearchingLastEqual` is specified, returns any equal or one larger index than any matching object's index.
+/// If the `NSBinarySearchingFirstEqual` option is also specified, returns the lowest index of equal objects. If the
+/// `NSBinarySearchingLastEqual` option is also specified, returns the highest index of equal objects. If the object
+/// is not found, returns the index of the least greater object, or the index at the end of the array if the object
+/// is larger than all other elements.
+- (NSUInteger)indexOfObject:(ObjectType)obj inSortedRange:(NSRange)r options:(NSBinarySearchingOptions)opts usingComparator:(NSComparator NS_NOESCAPE)cmp API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
@end
@interface NSArray<ObjectType> (NSArrayCreation)
+/// Creates and returns an empty array.
+///
+/// This method is used by mutable subclasses of `NSArray`.
+///
+/// - Returns: An empty array.
+ (instancetype)array;
+/// Creates and returns an array containing a given object.
+///
+/// Alternatively, you can use array literal syntax in Objective-C to create an array containing a given object:
+///
+/// NSArray *array = @[@"Hello, world!"];
+///
+/// - Parameter anObject: An object.
+/// - Returns: An array containing the single element `anObject`.
+ (instancetype)arrayWithObject:(ObjectType)anObject;
+/// Creates and returns an array that includes a given number of objects from a given C array.
+///
+/// Elements are added to the new array in the same order they appear in `objects`, up to but not including index
+/// `count`. For example:
+///
+/// NSString *strings[3];
+/// strings[0] = @"First";
+/// strings[1] = @"Second";
+/// strings[2] = @"Third";
+///
+/// NSArray *stringsArray = [NSArray arrayWithObjects:strings count:2];
+/// // strings array contains { @"First", @"Second" }
+///
+/// - Parameters:
+/// - objects: A C array of objects.
+/// - cnt: The number of values from the `objects` C array to include in the new array. This number will be the count
+/// of the new array -- it must not be negative or greater than the number of elements in `objects`.
+/// - Returns: A new array including the first `count` objects from `objects`.
+ (instancetype)arrayWithObjects:(const ObjectType _Nonnull [_Nonnull])objects count:(NSUInteger)cnt;
+/// Creates and returns an array containing the objects in the argument list.
+///
+/// Pass comma-separated list of trailing variadic arguments as additional objects, ending with `nil`.
+///
+/// The following code example creates an array containing three different types of element:
+///
+/// NSDate *aDate = [NSDate distantFuture];
+/// NSValue *aValue = @(5);
+/// NSString *aString = @"hello";
+///
+/// NSArray *array = [NSArray arrayWithObjects:aDate, aValue, aString, nil];
+///
+/// Alternatively, you can use array literal syntax in Objective-C or Swift to create an array containing given objects:
+///
+/// NSArray *array = @[@"alpha", @"bravo", @"charlie"];
+///
+/// - Parameter firstObj: The first object for the array.
+/// - Returns: An array containing the objects in the argument list.
+ (instancetype)arrayWithObjects:(ObjectType)firstObj, ... NS_REQUIRES_NIL_TERMINATION;
+/// Creates and returns an array containing the objects in another given array.
+///
+/// - Parameter array: An array.
+/// - Returns: An array containing the objects in `anArray`.
+ (instancetype)arrayWithArray:(NSArray<ObjectType> *)array;
+/// Initializes a newly allocated array by placing in it the objects in the argument list.
+///
+/// Pass comma-separated list of trailing variadic arguments as additional objects, ending with `nil`.
+///
+/// After an immutable array has been initialized in this way, it can't be modified.
+///
+/// This method is a designated initializer.
+///
+/// - Parameter firstObj: The first object for the array.
+/// - Returns: An array initialized to include the objects in the argument list. The returned object might be different
+/// than the original receiver.
- (instancetype)initWithObjects:(ObjectType)firstObj, ... NS_REQUIRES_NIL_TERMINATION;
+/// Initializes a newly allocated array by placing in it the objects contained in a given array.
+///
+/// After an immutable array has been initialized in this way, it cannot be modified.
+///
+/// - Parameter array: An array.
+/// - Returns: An array initialized to contain the objects in `anArray`. The returned object might be different than the
+/// original receiver.
- (instancetype)initWithArray:(NSArray<ObjectType> *)array;
+/// Initializes a newly allocated array using `anArray` as the source of data objects for the array.
+///
+/// After an immutable array has been initialized in this way, it cannot be modified.
+///
+/// The `copyWithZone:` method performs a shallow copy. If you have a collection of arbitrary depth, passing `YES` for
+/// the `flag` parameter will perform an immutable copy of the first level below the surface. If you pass `NO` the
+/// mutability of the first level is unaffected. In either case, the mutability of all deeper levels is unaffected.
+///
+/// - Parameters:
+/// - array: An array containing the objects with which to initialize the new array.
+/// - flag: If `YES`, each object in `array` receives a `copyWithZone:` message to create a copy of the object --
+/// objects must conform to the `NSCopying` protocol. In a managed memory environment, this is instead of the
+/// `retain` message the object would otherwise receive. The object copy is then added to the returned array. If
+/// `NO`, then in a managed memory environment each object in `array` simply receives a `retain` message when it is
+/// added to the returned array.
+/// - Returns: An array initialized to contain the objects -- or if `flag` is `YES`, copies of the objects -- in
+/// `array`. The returned object might be different than the original receiver.
- (instancetype)initWithArray:(NSArray<ObjectType> *)array copyItems:(BOOL)flag;
/* Reads array stored in NSPropertyList format from the specified url. */
@@ -108,85 +814,636 @@
NS_SWIFT_UNAVAILABLE("NSArray diffing methods are not available in Swift, use Collection.difference(from:) instead")
@interface NSArray<ObjectType> (NSArrayDiffing)
+/// Compares two arrays, using the provided block and with options, to create a difference object that represents the
+/// changes between them.
+///
+/// The options allow you to choose to omit insertion or removal references to the change objects within the difference
+/// object's changes. Don't use the option `NSOrderedCollectionDifferenceCalculationInferMoves` when providing a block
+/// for the equivalence test. The changes returned in the difference object don't include valid values for
+/// `associatedIndex`.
- (NSOrderedCollectionDifference<ObjectType> *)differenceFromArray:(NSArray<ObjectType> *)other withOptions:(NSOrderedCollectionDifferenceCalculationOptions)options usingEquivalenceTest:(BOOL (NS_NOESCAPE ^)(ObjectType obj1, ObjectType obj2))block;
+/// Compares two arrays, with options, to create a difference object that represents the changes between them.
+///
+/// The difference method creates the difference object by comparing objects within the arrays with the `isEqual:`
+/// method.
+///
+/// The options allow you to choose to omit insertion or removal references to the change objects within the difference
+/// object. You can also choose to infer moves when computing the difference, which provides an `associatedIndex`
+/// within the change objects that indicates the index in the array where the object moved from.
+///
+/// The following example computes the difference between two arrays, inferring moves between them:
+///
+/// NSArray *original = @[@"Red", @"Green", @"Blue"];
+/// NSArray *modified = @[@"Red", @"Blue", @"Green"];
+///
+/// NSOrderedCollectionDifference *diff = [original
+/// differenceFromArray:modified
+/// withOptions:NSOrderedCollectionDifferenceCalculationInferMoves];
+///
+/// // diff.hasChanges == TRUE
+/// // diff.insertions.count == 1
+/// // diff.removals.count == 1
+///
+/// // Inferring the moves adds an associatedIndex into the change.
+/// NSOrderedCollectionChange* insertion = diff.insertions[0];
+/// // insertion.index == 2
+/// // insertion.associatedIndex == 1
+///
+/// NSOrderedCollectionChange* deletion = diff.removals[0];
+/// // deletion.index == 1
+/// // deletion.associatedIndex == 2
- (NSOrderedCollectionDifference<ObjectType> *)differenceFromArray:(NSArray<ObjectType> *)other withOptions:(NSOrderedCollectionDifferenceCalculationOptions)options;
+/// Compares two arrays to create a difference object that represents the changes between them.
+///
+/// The difference method creates the difference object by comparing objects within the arrays with the `isEqual:`
+/// method.
+///
+/// The following example computes the difference between two arrays:
+///
+/// NSArray *original = @[@"1", @"2"];
+/// NSArray *modified = @[@"1", @"2", @"3"];
+///
+/// NSOrderedCollectionDifference *diff = [modified differenceFromArray:original];
+/// // diff.hasChanges == TRUE
+/// // diff.insertions.count == 1
+/// // diff.removals.count == 0
// Uses isEqual: to determine the difference between the parameter and the receiver
- (NSOrderedCollectionDifference<ObjectType> *)differenceFromArray:(NSArray<ObjectType> *)other;
+/// Creates a new array by applying a difference object to an existing array.
+///
+/// The following example computes the difference between two arrays, then applies the difference to create an array
+/// that duplicates the original:
+///
+/// NSArray *original = @[@"1", @"2"];
+/// NSArray *modified = @[@"1", @"2", @"3"];
+///
+/// NSOrderedCollectionDifference *diff = [modified differenceFromArray:original];
+/// // diff.hasChanges == true
+/// // diff.insertions.count == 1
+/// // diff.removals.count == 0
+///
+/// NSArray *updated = [original arrayByApplyingDifference:diff];
+/// // updated == [@"1", @"2", @"3"]
- (nullable NSArray<ObjectType> *)arrayByApplyingDifference:(NSOrderedCollectionDifference<ObjectType> *)difference;
@end
@interface NSArray<ObjectType> (NSDeprecated)
-/* This method is unsafe because it could potentially cause buffer overruns. You should use -getObjects:range: instead.
- */
-
+/// Copies all the objects contained in the array to `aBuffer`.
+///
+/// The method copies into `aBuffer` all the objects in the array; the size of the buffer must therefore be at least the
+/// count of the array multiplied by the size of an object reference, as shown in the following example (note that this
+/// is just an example, you should typically not create a buffer simply to iterate over the contents of an array):
+///
+/// NSArray *mArray = // ...;
+/// id *objects;
+///
+/// NSUInteger count = [mArray count];
+/// objects = malloc(sizeof(id) * count);
+///
+/// [mArray getObjects:objects];
+///
+/// for (i = 0; i < count; i++) {
+/// NSLog(@"object at index %d: %@", i, objects[i]);
+/// }
+/// free(objects);
+///
+/// ### Special Considerations
+///
+/// This deprecated method is unsafe because it could potentially cause buffer overruns.
+///
+/// - Parameter objects: A C array of objects of size at least the count of the array.
- (void)getObjects:(ObjectType _Nonnull __unsafe_unretained [_Nonnull])objects NS_SWIFT_UNAVAILABLE("Use 'as [AnyObject]' instead") API_DEPRECATED("Use -getObjects:range: instead", macos(10.0, 10.13), ios(2.0, 11.0), watchos(2.0, 4.0), tvos(9.0, 11.0));
/* These methods are deprecated, and will be marked with API_DEPRECATED in a subsequent release. Use the variants that use errors instead. */
+/// Creates and returns an array containing the contents of the file specified by a given path.
+///
+/// The array representation in the file identified by `aPath` must contain only property list objects (`NSString`,
+/// `NSData`, `NSDate`, `NSNumber`, `NSArray`, or `NSDictionary` objects). For more details, see
+/// [Property List Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/Introduction/Introduction.html#//apple_ref/doc/uid/10000048i).
+/// The objects contained by this array are immutable, even if the array is mutable.
+///
+/// - Parameter path: The path to a file containing a string representation of an array produced by the
+/// `writeToFile:atomically:` method.
+/// - Returns: An array containing the contents of the file specified by `aPath`. Returns `nil` if the file can't be
+/// opened or if the contents of the file can't be parsed into an array.
+ (nullable NSArray<ObjectType> *)arrayWithContentsOfFile:(NSString *)path API_DEPRECATED_WITH_REPLACEMENT("arrayWithContentsOfURL:error:", macos(10.0, API_TO_BE_DEPRECATED), ios(2.0, API_TO_BE_DEPRECATED), watchos(2.0, API_TO_BE_DEPRECATED), tvos(9.0, API_TO_BE_DEPRECATED));
+/// Creates and returns an array containing the contents specified by a given URL.
+///
+/// The array representation at the location identified by `aURL` must contain only property list objects (`NSString`,
+/// `NSData`, `NSArray`, or `NSDictionary` objects). The objects contained by this array are immutable, even if the
+/// array is mutable.
+///
+/// - Parameter url: The location of a file containing a string representation of an array produced by the
+/// `writeToURL:atomically:` method.
+/// - Returns: An array containing the contents specified by `aURL`. Returns `nil` if the location can't be opened or
+/// if the contents of the location can't be parsed into an array.
+ (nullable NSArray<ObjectType> *)arrayWithContentsOfURL:(NSURL *)url API_DEPRECATED_WITH_REPLACEMENT("arrayWithContentsOfURL:error:", macos(10.0, API_TO_BE_DEPRECATED), ios(2.0, API_TO_BE_DEPRECATED), watchos(2.0, API_TO_BE_DEPRECATED), tvos(9.0, API_TO_BE_DEPRECATED));
+/// Initializes a newly allocated array with the contents of the file specified by a given path.
+///
+/// The array representation in the file identified by `aPath` must contain only property list objects (`NSString`,
+/// `NSData`, `NSArray`, or `NSDictionary` objects). The objects contained by this array are immutable, even if the
+/// array is mutable.
+///
+/// - Parameter path: The path to a file containing a representation of an array produced by the
+/// `writeToFile:atomically:` method.
+/// - Returns: An array initialized to contain the contents of the file specified by `aPath` or `nil` if the file
+/// can't be opened or the contents of the file can't be parsed into an array. The returned object might be different
+/// than the original receiver.
- (nullable NSArray<ObjectType> *)initWithContentsOfFile:(NSString *)path API_DEPRECATED_WITH_REPLACEMENT("initWithContentsOfURL:error:", macos(10.0, API_TO_BE_DEPRECATED), ios(2.0, API_TO_BE_DEPRECATED), watchos(2.0, API_TO_BE_DEPRECATED), tvos(9.0, API_TO_BE_DEPRECATED));
+/// Initializes a newly allocated array with the contents of the location specified by a given URL.
+///
+/// The array representation at the location identified by `aURL` must contain only property list objects (`NSString`,
+/// `NSData`, `NSArray`, or `NSDictionary` objects). The objects contained by this array are immutable, even if the
+/// array is mutable.
+///
+/// - Parameter url: The location of a file containing a string representation of an array produced by the
+/// `writeToURL:atomically:` method.
+/// - Returns: An array initialized to contain the contents specified by `aURL`. Returns `nil` if the location can't
+/// be opened or if the contents of the location can't be parsed into an array. The returned object might be
+/// different than the original receiver.
- (nullable NSArray<ObjectType> *)initWithContentsOfURL:(NSURL *)url API_DEPRECATED_WITH_REPLACEMENT("initWithContentsOfURL:error:", macos(10.0, API_TO_BE_DEPRECATED), ios(2.0, API_TO_BE_DEPRECATED), watchos(2.0, API_TO_BE_DEPRECATED), tvos(9.0, API_TO_BE_DEPRECATED));
+/// Writes the contents of the array to a file at a given path.
+///
+/// If the array's contents are all property list objects (`NSString`, `NSData`, `NSArray`, or `NSDictionary` objects),
+/// the file written by this method can be used to initialize a new array with the class method
+/// `arrayWithContentsOfFile:` or the instance method `initWithContentsOfFile:`. This method recursively validates that
+/// all the contained objects are property list objects before writing out the file, and returns `NO` if all the objects
+/// are not property list objects, since the resultant file would not be a valid property list.
+///
+/// - Parameters:
+/// - path: The path at which to write the contents of the array. If `path` contains a tilde (~) character, you must
+/// expand it with `stringByExpandingTildeInPath` before invoking this method.
+/// - useAuxiliaryFile: If `YES`, the array is written to an auxiliary file, and then the auxiliary file is renamed to
+/// `path`. If `NO`, the array is written directly to `path`. The `YES` option guarantees that `path`, if it exists
+/// at all, won't be corrupted even if the system should crash during writing.
+/// - Returns: `YES` if the file is written successfully, otherwise `NO`.
- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile API_DEPRECATED_WITH_REPLACEMENT("writeToURL:error:", macos(10.0, API_TO_BE_DEPRECATED), ios(2.0, API_TO_BE_DEPRECATED), watchos(2.0, API_TO_BE_DEPRECATED), tvos(9.0, API_TO_BE_DEPRECATED));
+/// Writes the contents of the array to the location specified by a given URL.
+///
+/// If the array's contents are all property list objects (`NSString`, `NSData`, `NSArray`, or `NSDictionary` objects),
+/// the location written by this method can be used to initialize a new array with the class method
+/// `arrayWithContentsOfURL:` or the instance method `initWithContentsOfURL:`.
+///
+/// - Parameters:
+/// - url: The location at which to write the array.
+/// - atomically: If `YES`, the array is written to an auxiliary location, and then the auxiliary location is renamed
+/// to `aURL`. If `NO`, the array is written directly to `aURL`. The `YES` option guarantees that `aURL`, if it
+/// exists at all, won't be corrupted even if the system should crash during writing.
+/// - Returns: `YES` if the location is written successfully, otherwise `NO`.
- (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)atomically API_DEPRECATED_WITH_REPLACEMENT("writeToURL:error:", macos(10.0, API_TO_BE_DEPRECATED), ios(2.0, API_TO_BE_DEPRECATED), watchos(2.0, API_TO_BE_DEPRECATED), tvos(9.0, API_TO_BE_DEPRECATED));
@end
-/**************** Mutable Array ****************/
+/* *************** Mutable Array ****************/
+/// A dynamic ordered collection of objects.
+///
+/// You can use this type in Swift instead of an `Array` variable in cases that require reference semantics.
+///
+/// The `NSMutableArray` class declares the programmatic interface to objects that manage a modifiable array of objects.
+/// This class adds insertion and deletion operations to the basic array-handling behavior inherited from `NSArray`.
+///
+/// `NSMutableArray` is "toll-free bridged" with its Core Foundation counterpart, `CFMutableArray`. See
+/// [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html#//apple_ref/doc/uid/TP40010810-CH2)
+/// for more information.
+///
+/// ### Accessing Values Using Subscripting
+///
+/// In addition to the provided instance methods, such as `replaceObjectAtIndex:withObject:`, you can access
+/// `NSArray` values by their indexes using _subscripting_.
+///
+/// In Swift:
+///
+/// mutableArray[3] = "someValue"
+///
+/// In Objective-C:
+///
+/// mutableArray[3] = @"someValue";
+///
+/// ### Subclassing Notes
+///
+/// There is typically little reason to subclass `NSMutableArray`. The class does well what it is designed to do ---
+/// maintain a mutable, ordered collection of objects. But there are situations where a custom `NSArray` object might
+/// come in handy. Here are a few possibilities:
+///
+/// - Changing how `NSMutableArray` stores the elements of its collection. You might do this for performance reasons or
+/// for better compatibility with legacy code.
+/// - Acquiring more information about what is happening to the collection (for example, statistics gathering).
+///
+/// #### Methods to Override
+///
+/// `NSMutableArray` defines five primitive methods:
+///
+/// - `insertObject:atIndex:`
+/// - `removeObjectAtIndex:`
+/// - `addObject:`
+/// - `removeLastObject`
+/// - `replaceObjectAtIndex:withObject:`
+///
+/// In a subclass, you must override all these methods. You must also override the primitive methods of the `NSArray`
+/// class.
@interface NSMutableArray<ObjectType> : NSArray<ObjectType>
+/// Inserts a given object at the end of the array.
+///
+/// - Parameter anObject: The object to add to the end of the array's content. This value must not be `nil`.
+///
+/// > Important: Raises an `NSInvalidArgumentException` if `anObject` is `nil`.
- (void)addObject:(ObjectType)anObject;
+/// Inserts a given object into the array's contents at a given index.
+///
+/// If `index` is already occupied, the objects at `index` and beyond are shifted by adding `1` to their indices to make
+/// room.
+///
+/// Note that `NSArray` objects are not like C arrays. That is, even though you specify a size when you create an array,
+/// the specified size is regarded as a "hint"; the actual size of the array is still 0. This means that you cannot
+/// insert an object at an index greater than the current count of an array. For example, if an array contains two
+/// objects, its size is 2, so you can add objects at indices 0, 1, or 2. Index 3 is illegal and out of bounds; if you
+/// try to add an object at index 3 (when the size of the array is 2), `NSMutableArray` raises an exception.
+///
+/// - Parameters:
+/// - anObject: The object to add to the array's content. This value must not be `nil`.
+///
+/// > Important: Raises an `NSInvalidArgumentException` if `anObject` is `nil`.
+///
+/// - index: The index in the array at which to insert `anObject`. This value must not be greater than the count of
+/// elements in the array.
+///
+/// > Important: Raises an `NSRangeException` if `index` is greater than the number of elements in the array.
- (void)insertObject:(ObjectType)anObject atIndex:(NSUInteger)index;
+/// Removes the object with the highest-valued index in the array.
- (void)removeLastObject;
+/// Removes the object at `index`.
+///
+/// To fill the gap, all elements beyond `index` are moved by subtracting 1 from their index.
+///
+/// - Parameter index: The index from which to remove the object in the array. The value must not exceed the bounds of
+/// the array.
+///
+/// > Important: Raises an exception `NSRangeException` if `index` is beyond the end of the array.
- (void)removeObjectAtIndex:(NSUInteger)index;
+/// Replaces the object at `index` with `anObject`.
+///
+/// - Parameters:
+/// - index: The index of the object to be replaced. This value must not exceed the bounds of the array.
+///
+/// > Important: Raises an `NSRangeException` if `index` is beyond the end of the array.
+///
+/// - anObject: The object with which to replace the object at index `index` in the array. This value must not be
+/// `nil`.
+///
+/// > Important: Raises an `NSInvalidArgumentException` if `anObject` is `nil`.
- (void)replaceObjectAtIndex:(NSUInteger)index withObject:(ObjectType)anObject;
+/// Initializes a newly allocated array.
+///
+/// This method is a designated initializer.
+///
+/// - Returns: An array.
- (instancetype)init NS_DESIGNATED_INITIALIZER;
+/// Returns an array, initialized with enough memory to initially hold a given number of objects.
+///
+/// Mutable arrays expand as needed; `numItems` simply establishes the object's initial capacity.
+///
+/// This method is a designated initializer.
+///
+/// - Parameter numItems: The initial capacity of the new array.
+/// - Returns: An array initialized with enough memory to hold `numItems` objects. The returned object might be
+/// different than the original receiver.
- (instancetype)initWithCapacity:(NSUInteger)numItems NS_DESIGNATED_INITIALIZER;
- (nullable instancetype)initWithCoder:(NSCoder *)coder NS_DESIGNATED_INITIALIZER;
@end
@interface NSMutableArray<ObjectType> (NSExtendedMutableArray)
-
+
+/// Adds the objects contained in another given array to the end of the receiving array's content.
+///
+/// - Parameter otherArray: An array of objects to add to the end of the receiving array's content.
- (void)addObjectsFromArray:(NSArray<ObjectType> *)otherArray;
+/// Exchanges the objects in the array at given indexes.
+///
+/// - Parameters:
+/// - idx1: The index of the object with which to replace the object at index `idx2`.
+/// - idx2: The index of the object with which to replace the object at index `idx1`.
- (void)exchangeObjectAtIndex:(NSUInteger)idx1 withObjectAtIndex:(NSUInteger)idx2;
+/// Empties the array of all its elements.
- (void)removeAllObjects;
+/// Removes all occurrences within a specified range in the array of a given object.
+///
+/// Matches are determined by comparing `anObject` to the objects in the receiver using the `isEqual:` method. If the
+/// array does not contain `anObject` within `aRange`, the method has no effect (although it does incur the overhead of
+/// searching the contents).
+///
+/// - Parameters:
+/// - anObject: The object to be removed from the array's content.
+/// - range: The range from which to remove `anObject`.
+///
+/// > Important: Raises an exception `NSRangeException` if `aRange` exceeds the bounds of the array.
- (void)removeObject:(ObjectType)anObject inRange:(NSRange)range;
+/// Removes all occurrences in the array of a given object.
+///
+/// This method determines a match by comparing `anObject` to the objects in the receiver using the `isEqual:` method.
+/// If the array does not contain `anObject`, the method has no effect (although it does incur the overhead of searching
+/// the contents).
+///
+/// - Parameter anObject: The object to remove from the array.
- (void)removeObject:(ObjectType)anObject;
+/// Removes all occurrences of `anObject` within the specified range in the array.
+///
+/// This method determines a match by comparing the address of `anObject` to the addresses of objects in the receiver.
+/// If the array does not contain `anObject` within `aRange`, the method has no effect (although it does incur the
+/// overhead of searching the contents).
+///
+/// - Parameters:
+/// - anObject: The object to remove from the array within `aRange`.
+/// - range: The range in the array from which to remove `anObject`.
+///
+/// > Important: Raises an exception `NSRangeException` if `aRange` exceeds the bounds of the array.
- (void)removeObjectIdenticalTo:(ObjectType)anObject inRange:(NSRange)range;
+/// Removes all occurrences of a given object in the array.
+///
+/// This method determines a match by comparing the address of `anObject` to the addresses of objects in the receiver.
+/// If the array does not contain `anObject`, the method has no effect (although it does incur the overhead of searching
+/// the contents).
+///
+/// - Parameter anObject: The object to remove from the array.
- (void)removeObjectIdenticalTo:(ObjectType)anObject;
+/// Removes the specified number of objects from the array, beginning at the specified index.
+///
+/// This method is similar to `removeObjectAtIndex:`, but it allows you to efficiently remove multiple objects with a
+/// single operation. If you sort the list of indexes in ascending order, you will improve the speed of this operation.
+///
+/// This method cannot be sent to a remote object with distributed objects.
+///
+/// > Note: This deprecated method uses a C array of indices. The `removeObjectsAtIndexes:` method uses an `NSIndexSet`
+/// > which provides a more efficient way of indexing into an array.
+///
+/// - Parameters:
+/// - indices: A C array of the indices of the objects to remove from the receiving array.
+/// - cnt: The number of objects to remove from the receiving array.
- (void)removeObjectsFromIndices:(NSUInteger *)indices numIndices:(NSUInteger)cnt API_DEPRECATED("Not supported", macos(10.0,10.6), ios(2.0,4.0), watchos(2.0,2.0), tvos(9.0,9.0));
+/// Removes from the receiving array the objects in another given array.
+///
+/// This method is similar to `removeObject:`, but it allows you to efficiently remove large sets of objects with a
+/// single operation. If the receiving array does not contain objects in `otherArray`, the method has no effect (although
+/// it does incur the overhead of searching the contents).
+///
+/// This method assumes that all elements in `otherArray` respond to `hash` and `isEqual:`.
+///
+/// - Parameter otherArray: An array containing the objects to be removed from the receiving array.
- (void)removeObjectsInArray:(NSArray<ObjectType> *)otherArray;
+/// Removes from the array each of the objects within a given range.
+///
+/// The objects are removed using `removeObjectAtIndex:`.
+///
+/// - Parameter range: The range of the objects to be removed from the array.
- (void)removeObjectsInRange:(NSRange)range;
+/// Replaces the objects in the receiving array specified by one given range with the objects in another array specified
+/// by another range.
+///
+/// The lengths of `aRange` and `otherRange` don't have to be equal: If `aRange` is longer than `otherRange`, the extra
+/// objects in the receiving array are removed; if `otherRange` is longer than `aRange`, the extra objects from
+/// `otherArray` are inserted into the receiving array.
+///
+/// - Parameters:
+/// - range: The range of objects to be replaced in (or removed from) the receiving array.
+/// - otherArray: The array of objects from which to select replacements for the objects in `aRange`.
+/// - otherRange: The range of objects be selected from `otherArray` as replacements for the objects in `aRange`.
- (void)replaceObjectsInRange:(NSRange)range withObjectsFromArray:(NSArray<ObjectType> *)otherArray range:(NSRange)otherRange;
+/// Replaces the objects in the receiving array specified by a given range with all of the objects from a given array.
+///
+/// If `otherArray` has fewer objects than are specified by `aRange`, the extra objects in the receiving array are
+/// removed. If `otherArray` has more objects than are specified by `aRange`, the extra objects from `otherArray` are
+/// inserted into the receiving array.
+///
+/// - Parameters:
+/// - range: The range of objects to be replaced in (or removed from) the receiving array.
+/// - otherArray: The array of objects from which to select replacements for the objects in `aRange`.
- (void)replaceObjectsInRange:(NSRange)range withObjectsFromArray:(NSArray<ObjectType> *)otherArray;
+/// Sets the receiving array's elements to those in another given array.
+///
+/// - Parameter otherArray: The array of objects with which to replace the receiving array's content.
- (void)setArray:(NSArray<ObjectType> *)otherArray;
+/// Sorts the receiver in ascending order as defined by the comparison function `compare`.
+///
+/// This approach allows the comparison to be based on some outside parameter, such as whether character sorting is case
+/// sensitive or case insensitive.
+///
+/// - Parameters:
+/// - compare: The comparison function to use to compare two elements at a time. The function's parameters are two
+/// objects to compare and the context parameter, `context`. The function should return `NSOrderedAscending` if the
+/// first element is smaller than the second, `NSOrderedDescending` if the first element is larger than the second,
+/// and `NSOrderedSame` if the elements are equal.
+/// - context: The context argument to be passed to the compare function.
- (void)sortUsingFunction:(NSInteger (NS_NOESCAPE *)(ObjectType, ObjectType, void * _Nullable))compare context:(nullable void *)context;
+/// Sorts the receiver in ascending order, as determined by the comparison method specified by a given selector.
+///
+/// - Parameter comparator: A selector that specifies the comparison method to use to compare elements in the array. The
+/// `comparator` message is sent to each object in the array and has as its single argument another object in the
+/// array. The `comparator` method should return `NSOrderedAscending` if the array is smaller than the argument,
+/// `NSOrderedDescending` if the array is larger than the argument, and `NSOrderedSame` if they are equal.
- (void)sortUsingSelector:(SEL)comparator;
+/// Inserts the objects in the provided array into the receiving array at the specified indexes.
+///
+/// Each object in `objects` is inserted into the receiving array in turn at the corresponding location specified in
+/// `indexes` after earlier insertions have been made. The implementation is conceptually similar to that illustrated in
+/// the following example:
+///
+/// - void insertObjects:(NSArray *)additions atIndexes:(NSIndexSet *)indexes
+/// {
+/// NSUInteger currentIndex = [indexes firstIndex];
+/// NSUInteger i, count = [indexes count];
+///
+/// for (i = 0; i < count; i++)
+/// {
+/// [self insertObject:[additions objectAtIndex:i] atIndex:currentIndex];
+/// currentIndex = [indexes indexGreaterThanIndex:currentIndex];
+/// }
+/// }
+///
+/// The resulting behavior is illustrated by the following example:
+///
+/// NSMutableArray *array = [NSMutableArray arrayWithObjects: @"one", @"two", @"three", @"four", nil];
+/// NSArray *newAdditions = [NSArray arrayWithObjects: @"a", @"b", nil];
+/// NSMutableIndexSet *indexes = [NSMutableIndexSet indexSetWithIndex:1];
+/// [indexes addIndex:3];
+/// [array insertObjects:newAdditions atIndexes:indexes];
+/// NSLog(@"array: %@", array);
+///
+/// // Output: array: (one, a, two, b, three, four)
+///
+/// The locations specified by `indexes` may therefore only exceed the bounds of the receiving array if one location
+/// specifies the count of the array or the count of the array after preceding insertions, and other locations exceeding
+/// the bounds do so in a contiguous fashion from that location, as illustrated in the following examples.
+///
+/// In this example, both new objects are appended to the end of the array.
+///
+/// NSMutableArray *array = [NSMutableArray arrayWithObjects: @"one", @"two", @"three", @"four", nil];
+/// NSArray *newAdditions = [NSArray arrayWithObjects: @"a", @"b", nil];
+/// NSMutableIndexSet *indexes = [NSMutableIndexSet indexSetWithIndex:5];
+/// [indexes addIndex:4];
+/// [array insertObjects:newAdditions atIndexes:indexes];
+/// NSLog(@"array: %@", array);
+///
+/// // Output: array: (one, two, three, four, a, b)
+///
+/// If you replace `[indexes addIndex:4]` with `[indexes addIndex:6]` (so that the indexes are 5 and 6), then the
+/// application will fail with an out of bounds exception.
+///
+/// In this example, two objects are added into the middle of the array, and another at the current end of the array
+/// (index 4) which means that it is third from the end of the modified array.
+///
+/// NSMutableArray *array = [NSMutableArray arrayWithObjects: @"one", @"two", @"three", @"four", nil];
+/// NSArray *newAdditions = [NSArray arrayWithObjects: @"a", @"b", @"c", nil];
+/// NSMutableIndexSet *indexes = [NSMutableIndexSet indexSetWithIndex:1];
+/// [indexes addIndex:2];
+/// [indexes addIndex:4];
+/// [array insertObjects:newAdditions atIndexes:indexes];
+/// NSLog(@"array: %@", array);
+///
+/// // Output: array: (one, a, b, two, c, three, four)
+///
+/// If you replace `[indexes addIndex:4]` with `[indexes addIndex:6]` (so that the indexes are 1, 2, and 6), then the
+/// output is `(one, a, b, two, three, four, c)`.
+///
+/// If `objects` or `indexes` is `nil`, this method will raises an exception.
+///
+/// - Parameters:
+/// - objects: An array of objects to insert into the receiving array.
+/// - indexes: The indexes at which the objects in `objects` should be inserted. The count of locations in `indexes`
+/// must equal the count of `objects`. For more details, see the Discussion.
- (void)insertObjects:(NSArray<ObjectType> *)objects atIndexes:(NSIndexSet *)indexes;
+/// Removes the objects at the specified indexes from the array.
+///
+/// This method is similar to `removeObjectAtIndex:`, but allows you to efficiently remove multiple objects with a
+/// single operation. `indexes` specifies the locations of objects to be removed given the state of the array when the
+/// method is invoked, as illustrated in the following example:
+///
+/// NSMutableArray *array = [NSMutableArray arrayWithObjects: @"one", @"a", @"two", @"b", @"three", @"four", nil];
+/// NSMutableIndexSet *indexes = [NSMutableIndexSet indexSetWithIndex:1];
+/// [indexes addIndex:3];
+/// [array removeObjectsAtIndexes:indexes];
+/// NSLog(@"array: %@", array);
+///
+/// // Output: array: (one, two, three, four)
+///
+/// If `indexes` is `nil`, this method raises an exception.
+///
+/// - Parameter indexes: The indexes of the objects to remove from the array. The locations specified by `indexes` must
+/// lie within the bounds of the array.
- (void)removeObjectsAtIndexes:(NSIndexSet *)indexes;
+/// Replaces the objects in the receiving array at locations specified with the objects from a given array.
+///
+/// The indexes in `indexes` are used in the same order as the objects in `objects`.
+///
+/// If `objects` or `indexes` is `nil`, this method raises an exception.
+///
+/// - Parameters:
+/// - indexes: The indexes of the objects to be replaced.
+/// - objects: The objects with which to replace the objects in the receiving array at the indexes specified by
+/// `indexes`. The count of locations in `indexes` must equal the count of `objects`.
- (void)replaceObjectsAtIndexes:(NSIndexSet *)indexes withObjects:(NSArray<ObjectType> *)objects;
+/// Replaces the object at the index with the new object, possibly adding the object.
+///
+/// This method has the same behavior as the `replaceObjectAtIndex:withObject:` method.
+///
+/// If `idx` is beyond the end of the array (that is, if `idx` is greater than the value returned by `count`), an
+/// `NSRangeException` is raised.
+///
+/// You shouldn't need to call this method directly. Instead, this method is called when setting an object by index
+/// using subscripting.
+///
+/// mutableArray[3] = @"someValue"; // equivalent to [mutableArray replaceObjectAtIndex:3 withObject:@"someValue"]
+///
+/// - Parameters:
+/// - obj: The object with which to replace the object at index `idx` in the array. This value must not be `nil`.
+///
+/// > Important: Raises an `NSInvalidArgumentException` if `anObject` is `nil`.
+///
+/// - idx: The index of the object to be replaced. This value must not exceed the bounds of the array.
+///
+/// > Important: Raises an `NSRangeException` if `idx` is beyond the end of the array.
- (void)setObject:(ObjectType)obj atIndexedSubscript:(NSUInteger)idx API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0));
+/// Sorts the receiver in ascending order using the comparison method specified by a given `NSComparator` block.
+///
+/// - Parameter cmptr: A comparator block.
- (void)sortUsingComparator:(NSComparator NS_NOESCAPE)cmptr API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Sorts the receiver in ascending order using the specified options and the comparison method specified by a given
+/// `NSComparator` block.
+///
+/// - Parameters:
+/// - opts: A bitmask that specifies the options for the sort (whether it should be performed concurrently and whether
+/// it should be performed stably).
+/// - cmptr: A comparator block.
- (void)sortWithOptions:(NSSortOptions)opts usingComparator:(NSComparator NS_NOESCAPE)cmptr API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
@end
@interface NSMutableArray<ObjectType> (NSMutableArrayCreation)
+/// Creates and returns an `NSMutableArray` object with enough allocated memory to initially hold a given number of
+/// objects.
+///
+/// Mutable arrays expand as needed; `numItems` simply establishes the object's initial capacity.
+///
+/// - Parameter numItems: The initial capacity of the new array.
+/// - Returns: A new `NSMutableArray` object with enough allocated memory to hold `numItems` objects.
+ (instancetype)arrayWithCapacity:(NSUInteger)numItems;
+/// Creates and returns a mutable array containing the contents of the file specified by the given path.
+///
+/// The mutable array representation in the file identified by `aPath` must contain only property list objects
+/// (`NSString`, `NSData`, `NSDate`, `NSNumber`, `NSArray`, or `NSDictionary` objects). For more details, see
+/// [Property List Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/Introduction/Introduction.html#//apple_ref/doc/uid/10000048i).
+/// The objects contained by this array are immutable even if the array is mutable.
+///
+/// - Parameter path: The path to a file containing a string representation of a mutable array produced by the
+/// `writeToFile:atomically:` method.
+/// - Returns: A mutable array containing the contents of the file specified `aPath`. Returns `nil` if the file can't be
+/// opened or if the contents of the file can't be parsed into a mutable array.
+ (nullable NSMutableArray<ObjectType> *)arrayWithContentsOfFile:(NSString *)path;
+/// Creates and returns a mutable array containing the contents specified by a given URL.
+///
+/// The array representation at the location identified by `aURL` must contain only property list objects (`NSString`,
+/// `NSData`, `NSDate`, `NSNumber`, `NSArray`, or `NSDictionary` objects). The objects contained by this array are
+/// immutable even if the array is mutable.
+///
+/// - Parameter url: The location of the file containing a string representation of a mutable array produced by the
+/// `writeToURL:atomically:` method.
+/// - Returns: A mutable array containing the contents specified by `aURL`. Returns `nil` if the location can't be
+/// opened or if the contents of the location can't be parsed into a mutable array.
+ (nullable NSMutableArray<ObjectType> *)arrayWithContentsOfURL:(NSURL *)url;
+/// Initializes a newly allocated mutable array with the contents of the file specified by a given path.
+///
+/// The mutable array representation in the file identified by `aPath` must contain only property list objects
+/// (`NSString`, `NSData`, `NSDate`, `NSNumber`, `NSArray`, or `NSDictionary` objects). The objects contained by this
+/// array are immutable even if the array is mutable.
+///
+/// - Parameter path: The path to a file containing a representation of a mutable array produced by
+/// `writeToFile:atomically:` method.
+/// - Returns: A mutable array initialized to contain the contents of the file specified by `aPath` or `nil` if the file
+/// can't be opened or the contents of the file can't be parsed into a mutable array. The returned object must be
+/// different than the original receiver.
- (nullable NSMutableArray<ObjectType> *)initWithContentsOfFile:(NSString *)path;
+/// Initialized a newly allocated mutable array with the contents of the location specified by a given URL.
+///
+/// The array representation at the location identified by `aURL` must contain only property list objects (`NSString`,
+/// `NSData`,`NSDate`, `NSNumber`, `NSArray`, or `NSDictionary` objects). The objects contained by this array are
+/// immutable, even if the array is mutable.
+///
+/// - Parameter url: The location of a file containing a string representation of a mutable array produced by
+/// `writeToURL:atomically:` method.
+/// - Returns: A mutable array initialized to contain the contents specified by `aURL`. Returns `nil` if the location
+/// can't be opened or if the contents of the location can't be parsed into a mutable array. The returned objects must
+/// be different than the original receiver.
- (nullable NSMutableArray<ObjectType> *)initWithContentsOfURL:(NSURL *)url;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAttributedString.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAttributedString.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAttributedString.h 2026-04-18 21:33:46
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAttributedString.h 2026-05-27 01:10:04
@@ -19,70 +19,307 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
+/// The attributes you apply to ranges of characters in an attributed string.
+///
+/// Some attributes provide information about how to render, lay out, or interpret the text, while other attributes provide transient or collaborative information.
typedef NSString * NSAttributedStringKey NS_TYPED_EXTENSIBLE_ENUM;
+
+/// A type that represents a key in the formatting context dictionary.
typedef NSString * NSAttributedStringFormattingContextKey NS_TYPED_EXTENSIBLE_ENUM;
+/// A key for the inflection concepts in the formatting context dictionary.
FOUNDATION_EXPORT NSAttributedStringFormattingContextKey const NSInflectionConceptsKey
API_AVAILABLE(macos(14.0), ios(17.0), tvos(17.0), watchos(10.0));
+/// A string of text that manages data, layout, and stylistic information for ranges of characters to support rendering.
+///
+/// ``NSAttributedString`` is a type you use to manage strings of stylized Unicode text. In addition to text, an attributed string contains key-value pairs known as _attributes_ that specify additional information to apply to ranges of characters within the string. Attributed strings support many different kinds of attributes, including:
+///
+/// - Rendering attributes that specify font, color, kern, ligature, and other details
+/// - Attributes for attachments and adaptive image glyphs
+/// - Semantic attributes such as link URLs or tool-tip information
+/// - Language attributes to support automatic gender agreement and text layout
+/// - Accessibility attributes that provide information for assistive technologies
+/// - Attributes that summarize details of the Markdown import process
+/// - Custom attributes you define for your app
+///
+/// Use attributed strings anywhere you need styled text, or when you need to associate additional information with your text. Because ``NSAttributedString`` is an immutable type, you specify all of the text and attributes for it at creation time and can't change them later. You can create attributed strings directly from a string of characters and a dictionary of attributes. You can also create attributed strings from the contents of a file, including files that contain RTF, RTFD, HTML, Markdown, or other file formats. If you need to modify the contents of an attributed string later, use the ``NSMutableAttributedString`` type instead.
+///
+/// If you create an ``NSAttributedString`` without any font information, the string's default font is Helvetica 12-point, which might differ from the default system font for the platform. To change the font, specify a font attribute at creation time.
+///
+/// ### Persistence
+///
+/// Be aware of how you persist attributed strings to and from the disk. RTF and RTFD are the preferred format for attributed strings because they offer the best fidelity for reading and writing attribute data. The RTF formats support a large number of standard attributes, and Apple extends the formats to support many Apple-specific attributes. If you define custom attributes for ranges of characters, store them separately alongside the RTF file for your text.
+///
+/// If you work extensively with HTML content, validate the results and performance of import and export operations during testing. WebKit handles the conversion between HTML markup and attributed strings. If an HTML file contains tags or constructs that attributed strings don't support, the import process ignores them and imports what it can.
+///
+/// When you create an attributed string from Markdown, the system adds presentation intent attributes with information about the original Markdown content. The system doesn't add style attributes to match the Markdown elements, but the system applies default style information when it renders a string with intent attributes. To change the rendering behavior of your Markdown content, remove the intent attributes and add the style attributes you prefer.
+///
+/// > Important:
+/// > When reading or writing attributed strings, choose methods that return or throw an error, and check any errors you receive. Handling errors is the best way to detect issues with the import or export process and take corrective action.
+///
+/// The methods for reading and writing common file formats also support document attributes. Document attributes aren't part of the attributed string itself, but accompany the text when you save it to a file. When you read a file, the system returns any document attributes that it finds. Similarly, when you write an attributed string to a file, you can specify the attributes to include. For more information about document attributes, see ``DocumentAttributeKey`` and ``DocumentReadingOptionKey``.
+///
+/// ### System framework interoperability
+///
+/// <doc://com.apple.documentation/documentation/uikit/textkit> and <doc://com.apple.documentation/documentation/coretext> use attributed strings extensively during the layout and rendering processes. These technologies use the string's text and rendering-related attributes to calculate the text metrics needed during layout. Similarly, these technologies apply those same attributes during rendering to give the text its styled appearance. The technologies use only attributes that directly affect the appearance of the text, and ignore most other attributes. For some attributes, the text system adds attributes during rendering as needed. For example, the text system provides default style attributes for text with the ``Key/link`` attribute.
+///
+/// <doc://com.apple.documentation/documentation/appkit> and <doc://com.apple.documentation/documentation/uikit> also support attributed strings in several ways. Some views and controls in these frameworks have APIs that accept attributed strings, and render the string with its style information. The frameworks also add methods to the ``NSAttributedString`` class that let you draw a styled string directly in one of your custom views. Because these methods use TextKit to draw the string, they recognize the same rendering-related attributes as that technology.
+///
+/// The ``NSAttributedString`` class and its Core Foundation counterpart, <doc://com.apple.documentation/documentation/corefoundation/cfattributedstring>, are toll-free bridged, which means you can use the two types interchangeably in your code without losing any text or attribute information.
API_AVAILABLE(macos(10.0), ios(3.2), watchos(2.0), tvos(9.0))
@interface NSAttributedString : NSObject <NSCopying, NSMutableCopying, NSSecureCoding>
// Override these two APIs when subclassing NSAttributedString
+
+/// The character contents of the receiver as a string.
@property (readonly, copy) NSString *string;
+
+/// Returns the attributes for the character at the specified index.
+///
+/// Raises an `NSRangeException` if `location` lies beyond the end of the receiver's characters.
+///
+/// - Parameters:
+/// - location: The index for which to return attributes. This value must lie within the bounds of the receiver.
+/// - range: Upon return, the range over which the attributes and values are the same as those at `location`. This range isn't necessarily the maximum range covered, and its extent is implementation-dependent. If you need the maximum range, use `attributesAtIndex:longestEffectiveRange:inRange:`. If you don't need this value, pass `NULL`.
+/// - Returns: The attributes for the character at `location`.
- (NSDictionary<NSAttributedStringKey, id> *)attributesAtIndex:(NSUInteger)location effectiveRange:(nullable NSRangePointer)range;
@end
@interface NSAttributedString (NSExtendedAttributedString)
+/// The length of the attributed string.
@property (readonly) NSUInteger length;
+
+/// Returns the value for an attribute with the specified name of the character at the specified index and, by reference, the range where the attribute applies.
+///
+/// Raises an `NSRangeException` if `location` lies beyond the end of the receiver's characters.
+///
+/// - Parameters:
+/// - attrName: The name of an attribute.
+/// - location: The index for which to return attributes. This value must not exceed the bounds of the receiver.
+/// - range: If non-`NULL`, upon return contains a range over which the named attribute's value applies, or a range over which the attribute does not exist. The range isn't necessarily the maximum range covered by `attrName`, and its extent is implementation-dependent. If you need the maximum range, use `attribute:atIndex:longestEffectiveRange:inRange:`. If you don't need this value, pass `NULL`.
+/// - Returns: The value for the attribute named `attrName` of the character at `location`, or `nil` if there is no such attribute.
- (nullable id)attribute:(NSAttributedStringKey)attrName atIndex:(NSUInteger)location effectiveRange:(nullable NSRangePointer)range;
+
+/// Returns an attributed string consisting of the characters and attributes within the specified range in the attributed string.
+///
+/// Raises an `NSRangeException` if any part of `range` lies beyond the end of the receiver's characters. This method treats the length of the string as a valid range value that returns an empty string.
+///
+/// - Parameter range: The range from which to create a new attributed string. `range` must lie within the bounds of the receiver.
+/// - Returns: An `NSAttributedString` object consisting of the characters and attributes within `range` in the receiver.
- (NSAttributedString *)attributedSubstringFromRange:(NSRange)range;
+/// Returns the attributes for the character at the specified index and, by reference, the range where the attributes apply.
+///
+/// Raises an `NSRangeException` if `location` or any part of `rangeLimit` lies beyond the end of the receiver's characters.
+///
+/// If you don't need the range information, it's far more efficient to use `attributesAtIndex:effectiveRange:` to retrieve the attribute value.
+///
+/// - Parameters:
+/// - location: The index for which to return attributes. This value must not exceed the bounds of the receiver.
+/// - range: If non-`NULL`, upon return contains the maximum range over which the attributes and values are the same as those at `location`, clipped to `rangeLimit`.
+/// - rangeLimit: The range over which to search for continuous presence of the attributes at `location`. This value must not exceed the bounds of the receiver.
- (NSDictionary<NSAttributedStringKey, id> *)attributesAtIndex:(NSUInteger)location longestEffectiveRange:(nullable NSRangePointer)range inRange:(NSRange)rangeLimit;
+
+/// Returns the value for the attribute with the specified name of the character at the specified index and, by reference, the range where the attribute applies.
+///
+/// Raises an `NSRangeException` if `location` or any part of `rangeLimit` lies beyond the end of the receiver's characters.
+///
+/// If you don't need the longest effective range, it's far more efficient to use `attribute:atIndex:effectiveRange:` to retrieve the attribute value.
+///
+/// - Parameters:
+/// - attrName: The name of an attribute.
+/// - location: The index at which to test for `attrName`.
+/// - range: If non-`NULL`, upon return contains the full range over which the value of the named attribute is the same as that at `location`, clipped to `rangeLimit`, or the full range over which the attribute does not exist. If you don't need this value, pass `NULL`.
+/// - rangeLimit: The range over which to search for continuous presence of `attrName`. This value must not exceed the bounds of the receiver.
+/// - Returns: The value for the attribute named `attrName` of the character at `location`, or `nil` if there is no such attribute.
- (nullable id)attribute:(NSAttributedStringKey)attrName atIndex:(NSUInteger)location longestEffectiveRange:(nullable NSRangePointer)range inRange:(NSRange)rangeLimit;
+/// Returns a Boolean value that indicates whether the attributed string is equal to the specified string.
+///
+/// This method performs a character-by-character comparison of the string and its attributes. The character and its attributes must be the same in both strings for the method to return `YES`.
+///
+/// - Parameter other: The attributed string with which to compare the receiver.
+/// - Returns: `YES` if the text and attributes in the current string and `other` are the same, otherwise `NO`.
- (BOOL)isEqualToAttributedString:(NSAttributedString *)other;
+/// Creates an attributed string with the specified text and no attribute information.
+///
+/// - Parameter str: The text for the new attributed string.
+/// - Returns: An `NSAttributedString` object initialized with the characters of `str` and no attribute information.
- (instancetype)initWithString:(NSString *)str;
+
+/// Creates an attributed string with the specified text and attributes.
+///
+/// Returns an `NSAttributedString` object initialized with the characters of `str` and the attributes of `attrs`.
+///
+/// - Parameters:
+/// - str: The text for the new attributed string.
+/// - attrs: The attributes for the new attributed string. This method applies the attributes to the entire string.
- (instancetype)initWithString:(NSString *)str attributes:(nullable NSDictionary<NSAttributedStringKey, id> *)attrs;
+
+/// Creates a new attributed string from the contents of another attributed string.
+///
+/// - Parameter attrStr: An attributed string.
+/// - Returns: An `NSAttributedString` object initialized with the characters and attributes of `attrStr`.
- (instancetype)initWithAttributedString:(NSAttributedString *)attrStr;
+/// Options for enumerating attributes of an attributed string.
typedef NS_OPTIONS(NSUInteger, NSAttributedStringEnumerationOptions) {
+ /// Causes the enumeration to occur in reverse.
NSAttributedStringEnumerationReverse = (1UL << 1),
+ /// If this option is supplied, the longest effective range computation is not performed; the blocks may be invoked with consecutive attribute runs that have the same value.
NSAttributedStringEnumerationLongestEffectiveRangeNotRequired = (1UL << 20)
};
+/// Executes the specified block for each range of attributes in the attributed string.
+///
+/// If this method is called by an instance of `NSMutableAttributedString`, mutation (deletion, addition, or change) is allowed only if the mutation is within the range provided to the block. After a mutation, the enumeration continues with the range immediately following the processed range, adjusting for any change in length caused by the mutation.
+///
+/// - Parameters:
+/// - enumerationRange: The range over which the attributes are enumerated.
+/// - opts: The options used by the enumeration.
+/// - block: The block to apply to ranges of attributes in the attributed string.
- (void)enumerateAttributesInRange:(NSRange)enumerationRange options:(NSAttributedStringEnumerationOptions)opts usingBlock:(void (NS_NOESCAPE ^)(NSDictionary<NSAttributedStringKey, id> *attrs, NSRange range, BOOL *stop))block API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// Executes the specified block for each range of a particular attribute in the attributed string.
+///
+/// If this method is called by an instance of `NSMutableAttributedString`, mutation (deletion, addition, or change) is allowed only if the mutation is within the range provided to the block. After a mutation, the enumeration continues with the range immediately following the processed range, adjusting for any change in length caused by the mutation.
+///
+/// - Parameters:
+/// - attrName: The name of the attribute to enumerate.
+/// - enumerationRange: The range over which the attribute values are enumerated.
+/// - opts: The options used by the enumeration.
+/// - block: A block to apply to ranges of the specified attribute in the attributed string.
- (void)enumerateAttribute:(NSAttributedStringKey)attrName inRange:(NSRange)enumerationRange options:(NSAttributedStringEnumerationOptions)opts usingBlock:(void (NS_NOESCAPE ^)(id _Nullable value, NSRange range, BOOL *stop))block API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
@end
+/// A mutable string with associated attributes (such as visual style, hyperlinks, or accessibility data) for portions of its text.
+///
+/// The `NSMutableAttributedString` class declares additional methods for mutating the content of an attributed string. You can add and remove characters (raw strings) and attributes separately or together as attributed strings. See the class description for ``NSAttributedString`` for more information about attributed strings.
+///
+/// `NSMutableAttributedString` adds two primitive methods to those of `NSAttributedString`. These primitive methods provide the basis for all the other methods in its class. The primitive ``replaceCharacters(in:with:)-6oq9r`` method replaces a range of characters with those from a string, leaving all attribute information outside that range intact. The primitive ``setAttributes(_:range:)`` method sets attributes and values for a given range of characters, replacing any previous attributes and values for that range.
+///
+/// In macOS, AppKit also uses <doc://com.apple.documentation/documentation/appkit/nsparagraphstyle> and its subclass <doc://com.apple.documentation/documentation/appkit/nsmutableparagraphstyle> to encapsulate the paragraph or ruler attributes used by the `NSAttributedString` classes.
+///
+/// Note that the default font for `NSAttributedString` objects is Helvetica 12-point, which may differ from the macOS system font, so you may wish to create the string with non-default attributes suitable for your application using, for example, ``NSAttributedString/init(string:attributes:)``.
+///
+/// > iOS Note:
+/// > In iOS, this class is used primarily in conjunction with the Core Text framework.
+///
+/// `NSMutableAttributedString` is "toll-free bridged" with its Core Foundation counterpart, <doc://com.apple.documentation/documentation/corefoundation/cfmutableattributedstring>. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html#//apple_ref/doc/uid/TP40010810-CH2) for more information.
API_AVAILABLE(macos(10.0), ios(3.2), watchos(2.0), tvos(9.0))
@interface NSMutableAttributedString : NSAttributedString
// Override these two APIs (in addition to the two for NSAttributedString) when subclassing NSMutableAttributedString
+
+/// Replaces the characters in the given range with the characters of the given string.
+///
+/// The new characters inherit the attributes of the first replaced character from `range`. Where the length of `range` is 0, the new characters inherit the attributes of the character preceding `range` if it has any, otherwise of the character following `range`.
+///
+/// Raises an `NSRangeException` if any part of `range` lies beyond the end of the receiver's characters.
+///
+/// - Parameters:
+/// - range: A range specifying the characters to replace.
+/// - str: A string specifying the characters to replace those in `range`.
- (void)replaceCharactersInRange:(NSRange)range withString:(NSString *)str;
+
+/// Sets the attributes for the characters in the specified range to the specified attributes.
+///
+/// These new attributes replace any attributes previously associated with the characters in `range`. Raises an `NSRangeException` if any part of `range` lies beyond the end of the receiver's characters.
+///
+/// - Parameters:
+/// - attrs: A dictionary containing the attributes to set.
+/// - range: The range of characters whose attributes are set.
- (void)setAttributes:(nullable NSDictionary<NSAttributedStringKey, id> *)attrs range:(NSRange)range;
@end
@interface NSMutableAttributedString (NSExtendedMutableAttributedString)
+/// The character contents of the receiver as a mutable string object.
+///
+/// The receiver tracks changes to this string and keeps its attribute mappings up to date.
@property (readonly, retain) NSMutableString *mutableString;
+/// Adds an attribute with the given name and value to the characters in the specified range.
+///
+/// You may assign any `name`/`value` pair you wish to a range of characters. Raises an `NSInvalidArgumentException` if `name` or `value` is `nil` and an `NSRangeException` if any part of `range` lies beyond the end of the receiver's characters.
+///
+/// - Parameters:
+/// - name: A string specifying the attribute name.
+/// - value: The attribute value associated with `name`.
+/// - range: The range of characters to which the specified attribute/value pair applies.
- (void)addAttribute:(NSAttributedStringKey)name value:(id)value range:(NSRange)range;
+
+/// Adds the given collection of attributes to the characters in the specified range.
+///
+/// You may assign any name/value pair you wish to a range of characters. Raises an `NSInvalidArgumentException` if `attrs` is `nil` and an `NSRangeException` if any part of `range` lies beyond the end of the receiver's characters.
+///
+/// - Parameters:
+/// - attrs: A dictionary containing the attributes to add.
+/// - range: The range of characters to which the specified attributes apply.
- (void)addAttributes:(NSDictionary<NSAttributedStringKey, id> *)attrs range:(NSRange)range;
+
+/// Removes the named attribute from the characters in the specified range.
+///
+/// Raises an `NSRangeException` if any part of `range` lies beyond the end of the receiver's characters.
+///
+/// - Parameters:
+/// - name: A string specifying the attribute name to remove.
+/// - range: The range of characters from which the specified attribute is removed.
- (void)removeAttribute:(NSAttributedStringKey)name range:(NSRange)range;
+/// Replaces the characters and attributes in a given range with the characters and attributes of the given attributed string.
+///
+/// Raises an `NSRangeException` if any part of `range` lies beyond the end of the receiver's characters.
+///
+/// - Parameters:
+/// - range: The range of characters and attributes replaced.
+/// - attrString: The attributed string whose characters and attributes replace those in the specified range.
- (void)replaceCharactersInRange:(NSRange)range withAttributedString:(NSAttributedString *)attrString;
+
+/// Inserts the characters and attributes of the given attributed string into the receiver at the given index.
+///
+/// The new characters and attributes begin at the given index and the existing characters and attributes from the index to the end of the receiver are shifted by the length of the attributed string. Raises an `NSRangeException` if `loc` lies beyond the end of the receiver's characters.
+///
+/// - Parameters:
+/// - attrString: The string whose characters and attributes are inserted.
+/// - loc: The index at which the characters and attributes are inserted.
- (void)insertAttributedString:(NSAttributedString *)attrString atIndex:(NSUInteger)loc;
+
+/// Adds the characters and attributes of a given attributed string to the end of the receiver.
+///
+/// - Parameter attrString: The string whose characters and attributes are added.
- (void)appendAttributedString:(NSAttributedString *)attrString;
+
+/// Deletes the characters in the given range along with their associated attributes.
+///
+/// Raises an `NSRangeException` if any part of `range` lies beyond the end of the receiver's characters.
+///
+/// - Parameter range: A range specifying the characters to delete.
- (void)deleteCharactersInRange:(NSRange)range;
+
+/// Replaces the receiver's entire contents with the characters and attributes of the given attributed string.
+///
+/// - Parameter attrString: The attributed string whose characters and attributes replace those in the receiver.
- (void)setAttributedString:(NSAttributedString *)attrString;
+/// Begins the buffering of changes to the string's characters and attributes.
+///
+/// Override this method in a subclass to buffer or optimize a series of changes to the string's characters or attributes. The string continues to buffer text until you call `endEditing`, at which time it consolidates the changes and notifies observers.
+///
+/// You can nest pairs of `beginEditing` and `endEditing` messages.
- (void)beginEditing;
+
+/// Ends the buffering of changes to the string's characters and attributes.
+///
+/// Override this method in a subclass to consolidate changes made since a previous call to `beginEditing`. When you call this method, the string notifies observers of the changes.
+///
+/// The default implementation of this method does nothing.
- (void)endEditing;
@end
@@ -92,97 +329,128 @@
// Presentation intents correspond to the Markdown constructs applied to a certain range.
// The system may supply a default presentation for these intents in certain contexts.
-// Inline presentation intents.
-// For use with NSInlinePresentationAttributeName.
+/// A type that defines presentation intent for runs of characters for traits like emphasis, strikethrough, and code voice.
+///
+/// Inline presentation intents.
+/// For use with `NSInlinePresentationAttributeName`.
typedef NS_OPTIONS(NSUInteger, NSInlinePresentationIntent) {
+ /// An intent that represents an emphasized presentation.
NSInlinePresentationIntentEmphasized = 1 << 0,
+ /// An intent that represents a strongly emphasized presentation.
NSInlinePresentationIntentStronglyEmphasized = 1 << 1,
+ /// An intent that represents a code voice presentation.
NSInlinePresentationIntentCode = 1 << 2,
+ /// An intent that represents a strikethrough presentation.
NSInlinePresentationIntentStrikethrough = 1 << 5,
+ /// An intent that represents a soft line break.
NSInlinePresentationIntentSoftBreak = 1 << 6,
+ /// An intent that represents a line break.
NSInlinePresentationIntentLineBreak = 1 << 7,
+ /// An intent that represents an inline HTML presentation.
NSInlinePresentationIntentInlineHTML = 1 << 8,
+ /// An intent that represents a block HTML presentation.
NSInlinePresentationIntentBlockHTML = 1 << 9
} API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) NS_SWIFT_NAME(InlinePresentationIntent);
-// a NSNumber wrapping a value of type NSInlinePresentationIntent
+/// An attribute key whose value is an `NSNumber` wrapping a value of type `NSInlinePresentationIntent`.
FOUNDATION_EXTERN const NSAttributedStringKey NSInlinePresentationIntentAttributeName
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) NS_SWIFT_NAME(inlinePresentationIntent);
-// a NSString
+/// An attribute key whose value is an `NSString` providing an alternate description.
FOUNDATION_EXTERN const NSAttributedStringKey NSAlternateDescriptionAttributeName
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) NS_SWIFT_NAME(alternateDescription);
-// a NSURL
+/// An attribute key whose value is an `NSURL` for an image.
FOUNDATION_EXTERN const NSAttributedStringKey NSImageURLAttributeName
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) NS_SWIFT_NAME(imageURL);
-// a NSString
+/// An attribute key whose value is an `NSString` containing a BCP-47 language identifier.
FOUNDATION_EXTERN const NSAttributedStringKey NSLanguageIdentifierAttributeName
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) NS_SWIFT_NAME(languageIdentifier);
-// a NSAttributedStringMarkdownSourcePosition
+/// An attribute key whose value is an `NSAttributedStringMarkdownSourcePosition` indicating the position in the original Markdown source.
FOUNDATION_EXPORT const NSAttributedStringKey NSMarkdownSourcePositionAttributeName
API_AVAILABLE(macos(13.0), ios(16.0), watchos(9.0), tvos(16.0)) NS_SWIFT_NAME(markdownSourcePosition);
+/// A type that represents policies for handling parsing failures.
typedef NS_ENUM(NSInteger, NSAttributedStringMarkdownParsingFailurePolicy) {
- // If parsing fails, return an error from the appropriate constructor.
+ /// A policy to return an error from the initializer if parsing fails.
NSAttributedStringMarkdownParsingFailureReturnError = 0,
- // If parsing fails, and if possible, return a partial string. It may contain unparsed markup.
- // Note that if it isn't possible, an error may be returned anyway.
+ /// A policy to return a partially parsed string, if possible. The returned string may include unparsed markup. If returning a partially parsed string isn't possible, the parser may return an error anyway.
NSAttributedStringMarkdownParsingFailureReturnPartiallyParsedIfPossible = 1,
} API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) NS_REFINED_FOR_SWIFT;
+/// A type that represents the syntax for intepreting a Markdown string.
typedef NS_ENUM(NSInteger, NSAttributedStringMarkdownInterpretedSyntax) {
- // Interpret the full Markdown syntax and produce all relevant attributes
+ /// A syntax value that interprets the full Markdown syntax and produces all relevant attributes.
NSAttributedStringMarkdownInterpretedSyntaxFull = 0,
-
- // Parse all Markdown text, but interpret only attributes that apply to inline spans. Attributes that differentiate blocks (e.g. NSPresentationIntentAttributeName) will not be applied. (Extended attributes apply to inline spans, if allowed, and will also be interpreted.)
+
+ /// A syntax value that parses all Markdown text, but interprets only attributes that apply to inline spans. Attributes that differentiate blocks (e.g. `NSPresentationIntentAttributeName`) will not be applied. (Extended attributes apply to inline spans, if allowed, and will also be interpreted.)
NSAttributedStringMarkdownInterpretedSyntaxInlineOnly = 1,
-
- // Like …InlineOnly, but do not interpret multiple consecutive instances of whitespace as a single separator space. All whitespace characters will appear in the result as they are specified in the source.
+
+ /// A syntax value that behaves like `NSAttributedStringMarkdownInterpretedSyntaxInlineOnly`, but does not interpret multiple consecutive instances of whitespace as a single separator space. All whitespace characters will appear in the result as they are specified in the source.
NSAttributedStringMarkdownInterpretedSyntaxInlineOnlyPreservingWhitespace = 2
} API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) NS_REFINED_FOR_SWIFT;
+/// The position of attributed string text in its original Markdown source string.
NS_REFINED_FOR_SWIFT
API_AVAILABLE(macos(13.0), ios(16.0), watchos(9.0), tvos(16.0))
@interface NSAttributedStringMarkdownSourcePosition : NSObject <NSCopying, NSSecureCoding>
+/// The line where the text begins in the Markdown source. Uses 1-based counting.
@property (readonly) NSInteger startLine;
+/// The column where the text begins in the Markdown source. Uses 1-based counting. Columns represent UTF-8 indices; for multi-byte characters, the column indicates the first byte.
@property (readonly) NSInteger startColumn;
+/// The line where the text ends in the Markdown source. Uses 1-based counting.
@property (readonly) NSInteger endLine;
+/// The column where the text ends in the Markdown source. Uses 1-based counting. Columns represent UTF-8 indices; for multi-byte characters, the column indicates the first byte.
@property (readonly) NSInteger endColumn;
+/// Creates a Markdown source position instance from its start and end line and column.
+///
+/// - Parameters:
+/// - startLine: The line number where text begins in the Markdown source. Specify a 1-based number.
+/// - startColumn: The column number where text begins in the Markdown source. Specify a 1-based number. Columns represent UTF-8 indices; for multi-byte characters, the column indicates the first byte.
+/// - endLine: The line number where the Markdown source ends. Specify a 1-based number.
+/// - endColumn: The column number where the Markdown source ends. Specify a 1-based number.
- (instancetype)initWithStartLine:(NSInteger)startLine startColumn:(NSInteger)startColumn endLine:(NSInteger)endLine endColumn:(NSInteger)endColumn;
+/// Returns a range indicating the source portion within a Markdown string.
+///
+/// Use this method to access the marked-up region of `string` with an `NSRange`, rather than making manual calculations based on row and column values.
+///
+/// - Parameter string: The Markdown source string that this source position object refers to.
+/// - Returns: A range that represents the source portion within a source Markdown string.
- (NSRange)rangeInString:(NSString *)string;
@end
+/// Options that affect the parsing of Markdown content into an attributed string.
NS_REFINED_FOR_SWIFT
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0))
@interface NSAttributedStringMarkdownParsingOptions : NSObject <NSCopying>
+/// Creates a Markdown parsing options instance.
- (instancetype)init;
-// Whether to allow parsing extensions to Markdown that specify extended attributes. Defaults to NO (only parse CommonMark syntax).
+/// A Boolean value that indicates whether parsing allows extensions to Markdown that specify extended attributes. Defaults to `NO` (only parse CommonMark syntax).
@property BOOL allowsExtendedAttributes;
-// What subset of Markdown syntax will be interpreted to produce relevant attributes in the final result.
-// Excluded syntax will still be parsed, and the text will be included in the final result. However, it will not have attributes applied to it.
+/// The syntax for interpreting a Markdown string.
+///
+/// If your Markdown data uses syntax that this setting excludes, the parser still parses it and includes its text in the final result. However, the relevant text won't have attributes.
@property NSAttributedStringMarkdownInterpretedSyntax interpretedSyntax;
-// The policy to apply if the Markdown source triggers a parsing error.
-// The default is NSAttributedStringMarkdownParsingFailureReturnError.
+/// The policy for handling a parsing failure. The default is `NSAttributedStringMarkdownParsingFailureReturnError`.
@property NSAttributedStringMarkdownParsingFailurePolicy failurePolicy;
-// The BCP-47 language code for this document. If not nil, the NSLanguageAttributeName attribute will be applied to any range in the returned string that doesn't otherwise specify a language attribute.
-// The default is nil, which applies no attributes.
+/// The BCP-47 language code for this document. If not `nil`, the `NSLanguageIdentifierAttributeName` attribute will be applied to any range in the returned string that doesn't otherwise specify a language attribute. The default is `nil`, which applies no attributes.
@property (nullable, copy) NSString *languageCode;
+/// A Boolean value that indicates whether parsing applies attributes that indicate the position of attributed text in the original Markdown string.
@property BOOL appliesSourcePositionAttributes API_AVAILABLE(macos(13.0), ios(16.0), watchos(9.0), tvos(16.0));
@end
@@ -193,6 +461,14 @@
// These constructors have a 'baseURL' parameter. If specified, links in the document will be relative to this URL, and images in the document will be looked for relative to this URL (if the other options allow image loading).
// Defaults to nil. If set to nil, paths will not be resolved.
+/// Creates an attributed string from the contents of a specified URL that contains Markdown-formatted data using the provided options.
+///
+/// - Parameters:
+/// - markdownFile: The URL to load Markdown-formatted data from.
+/// - options: Options that affect how the initializer interprets formatting in the Markdown string. This parameter defaults to no options.
+/// - baseURL: The base URL to use when resolving Markdown URLs. The initializer treats URLs as being relative to this URL. If this value is `nil`, the initializer doesn't resolve URLs. The default is `nil`.
+/// - error: On return, if an error occurs, this pointer contains an actual error object with the error information. You may specify `nil` for this parameter if you don't want the error information.
+/// - Returns: An attributed string with the parsed Markdown text and styling, or `nil` if parsing the data fails.
- (nullable instancetype)initWithContentsOfMarkdownFileAtURL:(NSURL *)markdownFile
options:(nullable NSAttributedStringMarkdownParsingOptions *)options
baseURL:(nullable NSURL *)baseURL
@@ -200,6 +476,14 @@
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0))
NS_REFINED_FOR_SWIFT;
+/// Creates an attributed string from Markdown-formatted data using the provided options.
+///
+/// - Parameters:
+/// - markdown: The `NSData` instance that contains the Markdown formatting.
+/// - options: Options that affect how the initializer interprets formatting in the Markdown string. This parameter defaults to no options.
+/// - baseURL: The base URL to use when resolving Markdown URLs. The initializer treats URLs as being relative to this URL. If this value is `nil`, the initializer doesn't resolve URLs. The default is `nil`.
+/// - error: On return, if an error occurs, this pointer contains an actual error object with the error information. You may specify `nil` for this parameter if you don't want the error information.
+/// - Returns: An attributed string with the parsed Markdown text and styling, or `nil` if parsing the data fails.
- (nullable instancetype)initWithMarkdown:(NSData *)markdown
options:(nullable NSAttributedStringMarkdownParsingOptions *)options
baseURL:(nullable NSURL *)baseURL
@@ -207,6 +491,14 @@
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0))
NS_REFINED_FOR_SWIFT;
+/// Creates an attributed string from a Markdown-formatted string using the provided options.
+///
+/// - Parameters:
+/// - markdownString: The string that contains the Markdown formatting.
+/// - options: Options that affect how the initializer interprets formatting in the Markdown string. This parameter defaults to no options.
+/// - baseURL: The base URL to use when resolving Markdown URLs. The initializer treats URLs as being relative to this URL. If this value is `nil`, the initializer doesn't resolve URLs. The default is `nil`.
+/// - error: On return, if an error occurs, this pointer contains an actual error object with the error information. You may specify `nil` for this parameter if you don't want the error information.
+/// - Returns: An attributed string with the parsed Markdown text and styling, or `nil` if parsing the data fails.
- (nullable instancetype)initWithMarkdownString:(NSString *)markdownString
options:(nullable NSAttributedStringMarkdownParsingOptions *)options
baseURL:(nullable NSURL *)baseURL
@@ -219,9 +511,12 @@
// Formatting API:
+/// Options to use when creating an attributed string from a format string and variable list of arguments.
typedef NS_OPTIONS(NSUInteger, NSAttributedStringFormattingOptions) {
+ /// An option to replace the attributes in a substituted string with those of the provided attributed string.
NSAttributedStringFormattingInsertArgumentAttributesWithoutMerging
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) = 1 << 0,
+ /// An option to apply the replacement index attribute to the replaced portions of text in a format string.
NSAttributedStringFormattingApplyReplacementIndexAttribute
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) = 1 << 1,
} NS_REFINED_FOR_SWIFT;
@@ -296,6 +591,7 @@
@end
+/// An attribute key whose value is an `NSNumber` indicating the replacement's position in a format string.
FOUNDATION_EXPORT NSAttributedStringKey const NSReplacementIndexAttributeName
NS_SWIFT_NAME(replacementIndex)
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0));
@@ -313,115 +609,257 @@
@end
+/// An attribute key whose value is an `NSMorphology` object that specifies the morphology for the attributed string.
FOUNDATION_EXPORT NSAttributedStringKey const NSMorphologyAttributeName
NS_SWIFT_NAME(morphology)
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0));
+/// An attribute key whose value is an `NSInflectionRule` object that specifies the inflection rule to apply to the attributed string.
FOUNDATION_EXPORT NSAttributedStringKey const NSInflectionRuleAttributeName
NS_SWIFT_NAME(inflectionRule)
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0));
+/// An attribute key whose value indicates inflection agreement with a specific argument.
FOUNDATION_EXPORT NSAttributedStringKey const NSInflectionAgreementArgumentAttributeName
NS_SWIFT_NAME(agreeWithArgument)
API_AVAILABLE(macos(14.0), ios(17.0), tvos(17.0), watchos(10.0));
+/// An attribute key whose value indicates inflection agreement with a specific concept.
FOUNDATION_EXPORT NSAttributedStringKey const NSInflectionAgreementConceptAttributeName
NS_SWIFT_NAME(agreeWithConcept)
API_AVAILABLE(macos(14.0), ios(17.0), tvos(17.0), watchos(10.0));
+/// An attribute key whose value indicates the referent concept for inflection.
FOUNDATION_EXPORT NSAttributedStringKey const NSInflectionReferentConceptAttributeName
NS_SWIFT_NAME(referentConcept)
API_AVAILABLE(macos(14.0), ios(17.0), tvos(17.0), watchos(10.0));
+/// An attribute key whose value provides an alternative inflection for the attributed string.
FOUNDATION_EXPORT NSAttributedStringKey const NSInflectionAlternativeAttributeName
NS_SWIFT_NAME(inflectionAlternative)
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0));
+/// An attribute key whose value specifies a localized number format.
FOUNDATION_EXPORT NSAttributedStringKey const NSLocalizedNumberFormatAttributeName
NS_SWIFT_NAME(localizedNumberFormat)
API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
-// an NSString representing the delimiter used when declaring the current list item
+/// An attribute key whose value is an `NSString` representing the delimiter used when declaring the current list item.
FOUNDATION_EXTERN const NSAttributedStringKey NSListItemDelimiterAttributeName
NS_SWIFT_NAME(listItemDelimiter)
API_AVAILABLE(macos(26.0), ios(26.0), watchos(26.0), tvos(26.0), visionos(26.0));
+/// An attribute key whose value is an `NSPresentationIntent` object representing the presentation intent for a block-level element.
FOUNDATION_EXTERN
const NSAttributedStringKey NSPresentationIntentAttributeName API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0));
+/// An enumeration of intended display styles for blocks of text like paragraphs, lists, and code blocks.
typedef NS_ENUM(NSInteger, NSPresentationIntentKind) {
+ /// A presentation style for a paragraph of text.
NSPresentationIntentKindParagraph,
+ /// A presentation style for a section header.
NSPresentationIntentKindHeader,
+ /// A presentation style for an ordered list of items.
NSPresentationIntentKindOrderedList,
+ /// A presentation style for an unordered list of items.
NSPresentationIntentKindUnorderedList,
+ /// A presentation style for a list of items.
NSPresentationIntentKindListItem,
+ /// A presentation style for a block of code.
NSPresentationIntentKindCodeBlock,
+ /// A presentation style for a block quote.
NSPresentationIntentKindBlockQuote,
+ /// A presentation style for a horizontal rule.
NSPresentationIntentKindThematicBreak,
+ /// A presentation style for a table.
NSPresentationIntentKindTable,
+ /// A presentation style for the header row of a table.
NSPresentationIntentKindTableHeaderRow,
+ /// A presentation style for a row of a table.
NSPresentationIntentKindTableRow,
+ /// A presentation style for a single cell of a table.
NSPresentationIntentKindTableCell,
} API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) NS_REFINED_FOR_SWIFT;
+/// An enumeration of values for aligning the contents of table columns.
typedef NS_ENUM(NSInteger, NSPresentationIntentTableColumnAlignment) {
+ /// A presentation style for columns with left-aligned text.
NSPresentationIntentTableColumnAlignmentLeft,
+ /// A presentation style for columns with center-aligned text.
NSPresentationIntentTableColumnAlignmentCenter,
+ /// A presentation style for columns with right-aligned text.
NSPresentationIntentTableColumnAlignmentRight,
} API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0)) NS_REFINED_FOR_SWIFT;
+/// A type that contains the Markdown formatting for blocks of text, like paragraphs, lists, code blocks, and parts of tables.
+///
+/// An ``NSPresentationIntent`` object stores the Markdown semantics for a range of characters in an attributed string. When parsing Markdown into an attributed string, the system sets the value of the ``NSAttributedString/Key/presentationIntentAttributeName`` attribute to an instance of this class. When displaying your string in system views, the system applies a default visual style to match the corresponding information in this type. To replace the system's default formatting, remove these attributes from your attributed string and apply the formatting you want.
NS_REFINED_FOR_SWIFT
API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0))
@interface NSPresentationIntent: NSObject <NSCopying, NSSecureCoding>
+/// The type of the intent.
@property (readonly) NSPresentationIntentKind intentKind;
- (instancetype)init NS_UNAVAILABLE;
+/// The parent of the current intent.
@property (readonly, nullable, strong) NSPresentationIntent *parentIntent;
+/// Creates a paragraph intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - parent: The parent intent of the paragraph.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindParagraph`.
+ (NSPresentationIntent *)paragraphIntentWithIdentity:(NSInteger)identity nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates a header intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - level: The level for the header section. Specify `1` or greater for this parameter. Don't specify `0`.
+/// - parent: The parent intent of the header.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindHeader`.
+ (NSPresentationIntent *)headerIntentWithIdentity:(NSInteger)identity level:(NSInteger)level nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates a code-block intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - languageHint: The programming language for the code listing.
+/// - parent: The parent intent of the code block.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindCodeBlock`.
+ (NSPresentationIntent *)codeBlockIntentWithIdentity:(NSInteger)identity languageHint:(nullable NSString *)languageHint nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates a thematic break intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - parent: The parent intent of the thematic break.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindThematicBreak`.
+ (NSPresentationIntent *)thematicBreakIntentWithIdentity:(NSInteger)identity nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates an ordered list intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - parent: The parent intent of the ordered list.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindOrderedList`.
+ (NSPresentationIntent *)orderedListIntentWithIdentity:(NSInteger)identity nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates an unordered list intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - parent: The parent intent of the unordered list.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindUnorderedList`.
+ (NSPresentationIntent *)unorderedListIntentWithIdentity:(NSInteger)identity nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates a list item intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - ordinal: The ordinal number of the list item.
+/// - parent: The parent intent of the list item.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindListItem`.
+ (NSPresentationIntent *)listItemIntentWithIdentity:(NSInteger)identity ordinal:(NSInteger)ordinal nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates a block quote intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - parent: The parent intent of the block quote.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindBlockQuote`.
+ (NSPresentationIntent *)blockQuoteIntentWithIdentity:(NSInteger)identity nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates a table intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - columnCount: The number of columns in the table.
+/// - alignments: An array of `NSNumber` values indicating the alignment of each column.
+/// - parent: The parent intent of the table.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindTable`.
+ (NSPresentationIntent *)tableIntentWithIdentity:(NSInteger)identity columnCount:(NSInteger)columnCount alignments:(NSArray<NSNumber *> *)alignments nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates a table header row intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - parent: The parent intent of the table header row.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindTableHeaderRow`.
+ (NSPresentationIntent *)tableHeaderRowIntentWithIdentity:(NSInteger)identity nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates a table row intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - row: The row number (0-based).
+/// - parent: The parent intent of the table row.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindTableRow`.
+ (NSPresentationIntent *)tableRowIntentWithIdentity:(NSInteger)identity row:(NSInteger)row nestedInsideIntent:(nullable NSPresentationIntent *)parent;
+
+/// Creates a table cell intent with the provided information.
+///
+/// - Parameters:
+/// - identity: The unique identifier for the intent.
+/// - column: The column number (0-based).
+/// - parent: The parent intent of the table cell.
+/// - Returns: A new intent with the kind set to `NSPresentationIntentKindTableCell`.
+ (NSPresentationIntent *)tableCellIntentWithIdentity:(NSInteger)identity column:(NSInteger)column nestedInsideIntent:(nullable NSPresentationIntent *)parent;
-/// An integer value which uniquely identifies this intent in the document. Identity disambiguates attributes which apply to contiguous text -- for example, two headers in a row with the same level. It can also be used to track the location in an attributed string of a particular part of a document, even after mutation.
+/// A unique identifier for the intent in the document.
+///
+/// Use the value in this property to disambiguate attributes that apply to contiguous text. For example, you might use it to differentiate between two headers in a row with the same level.
@property (readonly) NSInteger identity;
-/// If the intent is not a list, this value is 0.
+/// The number for an item in an ordered list.
+///
+/// If the intent is not a list, the value of this property is `0`.
@property (readonly) NSInteger ordinal;
-/// If the intent is not a table, this value is `nil`.
+/// The alignments for the columns in a table.
+///
+/// If the intent is not a table, the value of this property is `nil`.
@property (nullable, readonly) NSArray<NSNumber *> *columnAlignments;
-/// If the intent is not a table, this value is 0.
+/// The number of columns in a table.
+///
+/// If the intent is not a table, the value of this property is `0`.
@property (readonly) NSInteger columnCount;
-/// If the intent is not a header, this value is 0.
+/// The level of a header section.
+///
+/// This value corresponds to the number of hash marks (`#`) associated with the header. If the intent is not a header, the value of this property is `0`.
@property (readonly) NSInteger headerLevel;
-/// If the intent is not a code block, this value is `nil`.
+/// The language associated with the code listing.
+///
+/// If the intent is not a code block, the value of this property is `nil`.
@property (readonly, nullable, copy) NSString *languageHint;
-/// The column to which this cell belongs (0-based). If the intent is not a cell, this value is 0.
+/// The column number to which the cell belongs.
+///
+/// The value of this property is `0`-based, with the first column at `0`, the second column at `1`, and so on. If the intent is not a cell, this value is `0`.
@property (readonly) NSInteger column;
-/// The row to which this cell belongs (0-based). If the intent is not a row, this value is 0. Header rows are always row 0. If the table has more rows, those start at row 1.
+/// The row number to which this cell belongs.
+///
+/// The value of this property is `0`-based, with the first row at `0`, the second row at `1`, and so on. If the intent is not a cell, this value is `0`.
@property (readonly) NSInteger row;
-/// The indentation level of this intent. Each nested list increases the indentation level by one; all elements within the same list (and not then nested into a child list intent) have the same indentation level.
-/// Text outside list intents has an indentation level of 0.
+/// The indentation level of the intent.
+///
+/// The initial list has an indentation level of `0`. Each time you nest a new list, the indentation level increases by `1`. All elements within the same list have the same indentation level. Text outside list intents has an indentation level of `0`.
@property (readonly) NSInteger indentationLevel;
-/// Returns `YES` if this intent is equivalent to the other presentation intent. Equivalence is the same as equality except that identity is not taken into account.
+/// Returns a Boolean value that indicates whether the current intent is equivalent to the specified intent.
+///
+/// Two intents are equivalent if their attributes match. This method doesn't consider the `identity` property of the intents when determining their equivalence.
+///
+/// - Parameter other: The other intent to use in the comparison.
+/// - Returns: `YES` if the current intent is equivalent to the specified intent, or `NO` if it isn't.
- (BOOL)isEquivalentToPresentationIntent:(NSPresentationIntent *)other;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAutoreleasePool.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAutoreleasePool.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAutoreleasePool.h 2026-04-18 22:35:11
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAutoreleasePool.h 2026-05-27 00:11:54
@@ -6,6 +6,51 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
+/// An object that supports Cocoa's reference-counted memory management system.
+///
+/// An autorelease pool stores objects that are sent a `release` message when the pool itself is drained.
+///
+/// > Important:
+/// > If you use Automatic Reference Counting (ARC), you cannot use autorelease pools directly. Instead, you use `@autoreleasepool` blocks. For example, in place of:
+/// >
+/// > ```objc
+/// > NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
+/// > // Code benefitting from a local autorelease pool.
+/// > [pool release];
+/// > ```
+/// >
+/// > you would write:
+/// >
+/// > ```objc
+/// > @autoreleasepool {
+/// > // Code benefitting from a local autorelease pool.
+/// > }
+/// > ```
+/// >
+/// > `@autoreleasepool` blocks are more efficient than using an instance of ``NSAutoreleasePool`` directly; you can also use them even if you do not use ARC.
+///
+/// In a reference-counted environment (as opposed to one which uses garbage collection), an ``NSAutoreleasePool`` object contains objects that have received an <doc://com.apple.documentation/documentation/objectivec/nsobject-c.protocol/autorelease> message and when drained it sends a <doc://com.apple.documentation/documentation/objectivec/nsobject-c.protocol/release> message to each of those objects. Thus, sending <doc://com.apple.documentation/documentation/objectivec/nsobject-c.protocol/autorelease> instead of <doc://com.apple.documentation/documentation/objectivec/nsobject-c.protocol/release> to an object extends the lifetime of that object at least until the pool itself is drained (it may be longer if the object is subsequently retained). An object can be put into the same pool several times, in which case it receives a <doc://com.apple.documentation/documentation/objectivec/nsobject-c.protocol/release> message for each time it was put into the pool.
+///
+/// In a reference counted environment, Cocoa expects there to be an autorelease pool always available. If a pool is not available, autoreleased objects do not get released and you leak memory. In this situation, your program will typically log suitable warning messages.
+///
+/// The Application Kit creates an autorelease pool on the main thread at the beginning of every cycle of the event loop, and drains it at the end, thereby releasing any autoreleased objects generated while processing an event. If you use the Application Kit, you therefore typically don't have to create your own pools. If your application creates a lot of temporary autoreleased objects within the event loop, however, it may be beneficial to create "local" autorelease pools to help to minimize the peak memory footprint.
+///
+/// You create an ``NSAutoreleasePool`` object with the usual `alloc` and `init` messages and dispose of it with ``drain`` (or `release`—to understand the difference, see <doc:#Garbage-Collection>). Since you cannot retain an autorelease pool (or autorelease it—see `retain` and `autorelease`), draining a pool ultimately has the effect of deallocating it. You should always drain an autorelease pool in the same context (invocation of a method or function, or body of a loop) that it was created. See [Using Autorelease Pool Blocks](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmAutoreleasePools.html#//apple_ref/doc/uid/20000047) for more details.
+///
+/// Each thread (including the main thread) maintains its own stack of ``NSAutoreleasePool`` objects (see <doc:#Threads>). As new pools are created, they get added to the top of the stack. When pools are deallocated, they are removed from the stack. Autoreleased objects are placed into the top autorelease pool for the current thread. When a thread terminates, it automatically drains all of the autorelease pools associated with itself.
+///
+/// ### Threads
+///
+/// If you are making Cocoa calls outside of the Application Kit's main thread—for example if you create a Foundation-only application or if you detach a thread—you need to create your own autorelease pool.
+///
+/// If your application or thread is long-lived and potentially generates a lot of autoreleased objects, you should periodically drain and create autorelease pools (like the Application Kit does on the main thread); otherwise, autoreleased objects accumulate and your memory footprint grows. If, however, your detached thread does not make Cocoa calls, you do not need to create an autorelease pool.
+///
+/// > Note:
+/// > If you are creating secondary threads using the POSIX thread APIs instead of `NSThread` objects, you cannot use Cocoa, including `NSAutoreleasePool`, unless Cocoa is in multithreading mode. Cocoa enters multithreading mode only after detaching its first `NSThread` object. To use Cocoa on secondary POSIX threads, your application must first detach at least one `NSThread` object, which can immediately exit. You can test whether Cocoa is in multithreading mode with the `NSThread` class method ``Thread/isMultiThreaded()``.
+///
+/// ### Garbage Collection
+///
+/// In a garbage-collected environment, there is no need for autorelease pools. You may, however, write a framework that is designed to work in both a garbage-collected and reference-counted environment. In this case, you can use autorelease pools to hint to the collector that collection may be appropriate. In a garbage-collected environment, sending a ``drain`` message to a pool triggers garbage collection if necessary; `release`, however, is a no-op. In a reference-counted environment, ``drain`` has the same effect as `release`. Typically, therefore, you should use ``drain`` instead of `release`.
NS_AUTOMATED_REFCOUNT_UNAVAILABLE
@interface NSAutoreleasePool : NSObject {
@private
@@ -15,10 +60,15 @@
void *_reserved;
}
+/// Adds a given object to the active autorelease pool in the current thread.
+ (void)addObject:(id)anObject;
+/// Adds a given object to the receiver.
- (void)addObject:(id)anObject;
+/// Releases and pops the receiver.
+///
+/// In a reference-counted environment, this method behaves the same as calling `-release`. In a garbage-collected environment, this triggers garbage collection if the memory allocated since the last collection is greater than the current threshold.
- (void)drain;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBackgroundActivityScheduler.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBackgroundActivityScheduler.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBackgroundActivityScheduler.h 2026-04-18 22:35:16
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBackgroundActivityScheduler.h 2026-05-22 05:23:48
@@ -8,12 +8,12 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
-/* These values are arguments to the completion handler block for the scheduler. */
+/// These constants indicate whether background activity has been completed successfully or whether additional processing should be deferred until a more optimal time.
typedef NS_ENUM(NSInteger, NSBackgroundActivityResult) {
- // Indicate that the work for this activity has finished and the next invocation can be scheduled.
+ /// The activity has finished executing. If the activity repeats, the next invocation is scheduled by the system.
NSBackgroundActivityResultFinished = 1,
-
- // Indicate that the system should defer the remainder of this work for now and reschedule the completion soon. This should be used in response to checking the value of -shouldDefer.
+
+ /// System conditions have changed since the time the activity began executing, and deferral of additional work is recommended.
NSBackgroundActivityResultDeferred = 2,
} API_AVAILABLE(macos(10.10)) API_UNAVAILABLE(ios, watchos, tvos);
@@ -25,59 +25,246 @@
It is used to schedule maintenance or background kinds of tasks. These activities are run by the OS at a time that best accommodates system-wide factors like energy, thermal conditions, and CPU usage. If you have activities that run at an interval measured in 10s of minutes or more, then use this class to schedule those activities.
*/
+
+/// A task scheduler suitable for low priority operations that can run in the background.
+///
+/// Use an ``NSBackgroundActivityScheduler`` object to schedule an arbitrary maintenance or background task. It's similar to an ``Timer`` object, in that it lets you schedule a repeating or non-repeating task. However, ``NSBackgroundActivityScheduler`` gives the system flexibility to determine the most efficient time to execute based on energy usage, thermal conditions, and CPU use.
+///
+/// For example, use an ``NSBackgroundActivityScheduler`` object to schedule:
+///
+/// - Automatic saves
+/// - Backups
+/// - Data maintenance
+/// - Periodic content fetches
+/// - Installation of updates
+/// - Activities occurring in intervals of 10 minutes or more
+/// - Any other deferrable task
+///
+/// For information about performing non-deferrable tasks efficiently, see [Specify Nondeferrable Background Activities](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/SchedulingBackgroundActivity.html#//apple_ref/doc/uid/TP40013929-CH32-SW10) in [Energy Efficiency Guide for Mac Apps](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/index.html#//apple_ref/doc/uid/TP40013929).
+///
+/// > Note:
+/// > The ``NSBackgroundActivityScheduler`` class interfaces with the XPC Activity API. However, your app doesn't need to be an XPC service in order to use ``NSBackgroundActivityScheduler``.
+///
+/// ### Create a Scheduler
+///
+/// To initialize a scheduler, call ``init(identifier:)`` for `NSBackgroundActivityScheduler`, and pass it a unique identifier string in reverse DNS notation (`nil` and zero-length strings are not allowed) that remains constant across launches of your application.
+///
+/// @TabNavigator {
+/// @Tab("Swift") {
+/// ```swift
+/// let activity = NSBackgroundActivityScheduler(identifier: "com.example.MyApp.updatecheck")
+/// ```
+/// }
+/// @Tab("Objective-C") {
+/// ```objc
+/// NSBackgroundActivityScheduler *activity = [[NSBackgroundActivityScheduler alloc] initWithIdentifier:@"com.example.MyApp.updatecheck"];
+/// ```
+/// }
+/// }
+///
+///
+/// > Note:
+/// > The system uses this unique identifier to track the number of times the activity has run and to improve the heuristics for deciding when to run it again in the future.
+///
+/// ### Configure Scheduler Properties
+///
+/// Configure the scheduler with any of the following scheduling properties:
+///
+/// - ``repeats``—If set to <doc://com.apple.documentation/documentation/swift/true>, the activity is rescheduled at the specified interval after finishing.
+/// - ``interval``—For repeating schedulers, the average interval between invocations of the activity. For nonrepeating schedulers, `interval` is the suggested interval of time between scheduling the activity and the invocation of the activity.
+/// - ``tolerance``—The amount of time before or after the nominal fire date when the activity should be invoked. The nominal fire date is calculated by using the interval combined with the previous fire date or the time when the activity is started. These two properties create a window in time, during which the activity may be scheduled. The system will more aggressively schedule the activity as it nears the end of the grace period after the nominal fire date. The default value is half the interval.
+/// - ``qualityOfService``—The default value is `NSQualityOfServiceBackground`. If you upgrade the quality of service above this level, the system schedules the activity more aggressively. The default value is the recommended value for most activities. For information on quality of service, see [Prioritize Work at the Task Level](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/PrioritizeWorkAtTheTaskLevel.html#//apple_ref/doc/uid/TP40013929-CH35) in [Energy Efficiency Guide for Mac Apps](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/index.html#//apple_ref/doc/uid/TP40013929).
+///
+/// The next three code examples demonstrate different scheduling scenarios.
+///
+/// Scheduling an activity to fire in the next 10 minutes
+///
+/// @TabNavigator {
+/// @Tab("Swift") {
+/// ```swift
+/// activity.tolerance = 10 * 60
+/// ```
+/// }
+/// @Tab("Objective-C") {
+/// ```objc
+/// activity.tolerance = 10 * 60;
+/// ```
+/// }
+/// }
+///
+///
+/// Scheduling an activity to fire between 15 and 45 minutes from now
+///
+/// @TabNavigator {
+/// @Tab("Swift") {
+/// ```swift
+/// activity.interval = 30 * 60
+/// activity.tolerance = 15 * 60
+/// ```
+/// }
+/// @Tab("Objective-C") {
+/// ```objc
+/// activity.interval = 30 * 60;
+/// activity.tolerance = 15 * 60;
+/// ```
+/// }
+/// }
+///
+///
+/// Scheduling an activity to fire once each hour
+///
+/// @TabNavigator {
+/// @Tab("Swift") {
+/// ```swift
+/// activity.repeats = true
+/// activity.interval = 60 * 60
+/// ```
+/// }
+/// @Tab("Objective-C") {
+/// ```objc
+/// activity.repeats = YES;
+/// activity.interval = 60 * 60;
+/// ```
+/// }
+/// }
+///
+///
+/// ### Schedule Activity with scheduleWithBlock:
+///
+/// When you're ready to schedule the activity, call `scheduleWithBlock:` and provide a block of code to execute when the scheduler runs, as shown in the following example. The block will be called on a serial background queue appropriate for the level of quality of service specified. The system automatically uses the ``ProcessInfo/beginActivity(options:reason:)`` method (of ``ProcessInfo``) while invoking the block, choosing appropriate options based on the specified quality of service.
+///
+/// When your block is called, it's passed a completion handler as an argument. Configure the block to invoke this handler, passing it a result of type ``Result`` to indicate whether the activity finished (``Result/finished``) or should be deferred (``Result/deferred``) and rescheduled for a later time. Failure to invoke the completion handler results in the activity not being rescheduled. For work that will be deferred and rescheduled, the block may optionally adjust scheduler properties, such as ``interval`` or ``tolerance``, before calling the completion handler.
+///
+/// Scheduling background activity
+///
+/// @TabNavigator {
+/// @Tab("Swift") {
+/// ```swift
+/// activity.scheduleWithBlock() { (completion: NSBackgroundActivityCompletionHandler) in
+/// // Perform the activity
+/// self.completion(NSBackgroundActivityResult.Finished)
+/// }
+/// ```
+/// }
+/// @Tab("Objective-C") {
+/// ```objc
+/// [activity
+/// scheduleWithBlock:^(NSBackgroundActivityCompletionHandler completion) {
+/// // Perform the activity
+/// self.completion(NSBackgroundActivityResultFinished);
+/// }];
+/// ```
+/// }
+/// }
+///
+///
+/// ### Detect Whether to Defer Activity
+///
+/// It's conceivable that while a lengthy activity is running, conditions may change, resulting in the activity now requiring deferral. For example, perhaps the user has unplugged the Mac and it's now running on battery power. Your activity can call ``shouldDefer`` to determine whether this has occurred. A value of <doc://com.apple.documentation/documentation/swift/true> indicates that the block should finish what it's currently doing and invoke its completion handler with a value of ``Result/deferred``. See the following example.
+///
+/// Detecting deferred background activity
+///
+/// @TabNavigator {
+/// @Tab("Swift") {
+/// ```swift
+/// if activity.shouldDefer {
+/// // Wrap up processing and prepare to defer activity
+/// self.completion(NSBackgroundActivityResult.Deferred)
+/// } else {
+/// // Continue processing
+/// self.completion(NSBackgroundActivityResult.Finished)
+/// }
+/// ```
+/// }
+/// @Tab("Objective-C") {
+/// ```objc
+/// if ([activity shouldDefer]) {
+/// // Wrap up processing and prepare to defer activity
+/// self.completion(NSBackgroundActivityResultDeferred);
+/// } else {
+/// // Continue processing
+/// self.completion(NSBackgroundActivityResultFinished);
+/// };
+/// ```
+/// }
+/// }
+///
+///
+/// ### Stop Activity
+///
+/// Call ``invalidate()`` to stop scheduling an activity, as shown in the following example.
+///
+/// Stopping background activity
+///
+/// @TabNavigator {
+/// @Tab("Swift") {
+/// ```swift
+/// activity.invalidate()
+/// ```
+/// }
+/// @Tab("Objective-C") {
+/// ```objc
+/// [activity invalidate];
+/// ```
+/// }
+/// }
+///
+///
+/// > Note:
+/// > When an activity is stopped, a block that's currently executing will still finish executing.
API_AVAILABLE(macos(10.10)) API_UNAVAILABLE(ios, watchos, tvos)
@interface NSBackgroundActivityScheduler : NSObject
-/* Initialize a new instance of the class. The identifier argument should be a string that remains constant across launches of your application. The system uses the value to keep track of the number of times this activity has run and improve the heuristics for deciding when to run the activity in the future.
-
- The string should be a reverse DNS style string, such as "com.mycompany.myapplication.myactivity". nil and zero-length strings are not allowed.
-*/
+/// Initializes a background activity scheduler object with a specified unique identifier.
+///
+/// - Parameters:
+/// - identifier: A unique string, in reverse DNS notation, that identifies the activity. For example, `com.example.MyApp.updatecheck`. `nil` and zero-length strings are not allowed.
+/// - Returns: A new background activity scheduler object.
+///
+/// The string passed to the `identifier` parameter should remain constant for an activity across launches of your app because the system uses this unique identifier to track the number of times the activity has run and to improve the heuristics for deciding when to run it again in the future.
- (instancetype)initWithIdentifier:(NSString *)identifier NS_DESIGNATED_INITIALIZER;
-/* The identifier this object was initialized with.
- */
+/// A unique reverse DNS notation string, such as `com.example.MyApp.updatecheck`, that identifies the activity.
+///
+/// This string should remain constant for an activity across launches of your app because the system uses this unique identifier to track the number of times the activity has run and to improve the heuristics for deciding when to run it again in the future. `nil` and zero-length strings are not allowed.
@property (readonly, copy) NSString *identifier;
-/* Default value is NSQualityOfServiceBackground. If you upgrade the quality of service above this level, the system will more aggressively schedule this activity. The default value is the recommended value for most activities.
- */
+/// A value of type `NSQualityOfService`, which controls how aggressively the system schedules the activity.
+///
+/// The default value is `NSQualityOfServiceBackground`. If you upgrade the quality of service above this level, the system schedules the activity more aggressively. The default value is the recommended value for most activities.
@property NSQualityOfService qualityOfService;
-/* The default value is NO.
- If set to YES, then the activity will be rescheduled after finishing at the specified interval.
- */
+/// A Boolean value indicating whether the activity should be rescheduled after it completes.
+///
+/// The default value for this property is `NO`.
@property BOOL repeats;
-/* If this activity is repeating, then this property describes the average interval of seconds between invocations of this activity.
- If the activity is not repeating, then this property is the suggested interval of time between scheduling the activity and the invocation of the activity.
-*/
+/// An integer providing a suggested interval between scheduling and invoking the activity.
+///
+/// For repeating activities, the value of this property is also the suggested interval between invocations.
@property NSTimeInterval interval;
-/* Specifies the number of seconds before or after the nominal fire date when the activity should be invoked. The nominal fire date is calculated by using the interval combined with the previous fire date or the time when the activity is started. These two properties create a window in time during which the activity may be scheduled.
-
- The system will more aggresively schedule the activity as it nears the end of the grace period after the nominal fire date.
-
- The default value is 1/2 the interval.
- */
+/// A value of type `NSTimeInterval`, which specifies a range of time during which the background activity may occur.
+///
+/// A nominal fire date for scheduled background activity is calculated based on a combination of the `interval` property value and the time the activity began or the last execution date. The `tolerance` property specifies a grace period -- a range of time before and after the nominal fire date, during which the activity may be invoked. As the activity nears the end of its grace period, the system schedules the activity more aggressively. The default tolerance period is half the value of the `interval` property.
@property NSTimeInterval tolerance;
-/* Begin scheduling the activity. All properties should be setup by this point.
-
- The block will be called on a serial background queue appropriate for the level of quality of service specified. The system will automatically use NSProcessInfo's -beginActivityWithOptions:reason: API while invoking the block, choosing options appropriate for the desired quality of service.
-
- When you are done with the work, be sure to invoke the completionHandler block given to you as an argument to your block. You can pass in a kind of NSBackgroundActivityResult to indicate if the work has been finished or if you are deferring the rest of the work (see -shouldDefer). If you fail to invoke the completionHandler then your activity will never be rescheduled.
-
- When invoking the completionHandler, the system will set the schedule the next invocation. If you want to adjust the properties of your scheduler (e.g., the interval or tolerance), do this before invoking the completion block.
- */
+/// Begins scheduling the background activity.
+///
+/// - Parameters:
+/// - block: A block of code to execute when the scheduler runs. This block will be called on a serial background queue appropriate for the level of quality of service specified. See `qualityOfService`.
+///
+/// When your block is called, it's passed a completion handler as an argument. Configure the block to invoke this handler, passing it a result of type `NSBackgroundActivityResult` to indicate whether the activity finished (`NSBackgroundActivityResultFinished`) or should be deferred (`NSBackgroundActivityResultDeferred`) and rescheduled for a later time. Failure to invoke the completion handler results in the activity not being rescheduled. For work that will be deferred and rescheduled, the block may optionally adjust scheduler properties, such as `interval` or `tolerance`, before calling the completion handler.
- (void)scheduleWithBlock:(void (NS_SWIFT_SENDABLE ^)(NSBackgroundActivityCompletionHandler completionHandler))block NS_SWIFT_DISABLE_ASYNC;
-/* Stop scheduling the activity. Any currently executing block will still complete.
- */
+/// Prevents the background activity from being scheduled again.
+///
+/// When `invalidate` is used to stop an activity that is currently executing, the activity will still finish executing.
- (void)invalidate;
-/* You can call this method occasionally during execution of your activity to determine if system conditions have changed such that it is no longer a good time to run this activity.
-
- If the result of this method is YES, then you should wrap up current state. Once you are done saving your state, invoke the completionHandler block (the argument to your scheduled block) with the NSBackgroundActivityResultDeferred constant. The system will invoke your activity block again at a later, more appropriate time. At that point you can read your state and continue the work.
- */
+/// A Boolean value indicating whether your app should stop performing background activity and resume at a more optimal time.
+///
+/// Your app can check the `shouldDefer` property while executing scheduled background activity. If this property contains a value of `YES`, system conditions have changed since the time the activity started and deferral is recommended. For example, perhaps the user unplugged the Mac and it's now running on battery power. In this case, your app should finish what it's currently doing, save its state, and invoke its completion handler with a value of `NSBackgroundActivityResultDeferred`. The system will invoke your activity again at a more optimal time, and your app can restore its previous state and resume where it left off.
@property (readonly) BOOL shouldDefer;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBundle.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBundle.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBundle.h 2026-04-18 19:13:12
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBundle.h 2026-05-27 00:01:42
@@ -16,82 +16,411 @@
/* Because NSBundle caches allocated instances, subclasses should be prepared
to receive an already initialized object back from [super initWithPath:] */
+
+/// A representation of the code and resources stored in a bundle directory on disk.
+///
+/// Apple uses bundles to represent apps, frameworks, plug-ins, and many other specific types of content. Bundles organize their contained resources into well-defined subdirectories, and bundle structures vary depending on the platform and the type of the bundle. By using a bundle object, you can access a bundle's resources without knowing the structure of the bundle. The bundle object provides a single interface for locating items, taking into account the bundle structure, user preferences, available localizations, and other relevant factors.
+///
+/// Any executable can use a bundle object to locate resources, either inside an app's bundle or in a known bundle located elsewhere. You don't use a bundle object to locate files in a container directory or in other parts of the file system.
+///
+/// The general pattern for using a bundle object is as follows:
+///
+/// 1. Create a bundle object for the intended bundle directory.
+/// 2. Use the methods of the bundle object to locate or load the needed resource.
+/// 3. Use other system APIs to interact with the resource.
+///
+///
+/// Some types of frequently used resources can be located and opened without a bundle. For example, when loading images, you store images in asset catalogs and load them using the <doc://com.apple.documentation/documentation/uikit/uiimage/init(named:)> methods of <doc://com.apple.documentation/documentation/uikit/uiimage> or <doc://com.apple.documentation/documentation/appkit/nsimage>. Similarly, for string resources, you use ``NSLocalizedString`` to load individual strings instead of loading the entire `.strings` file yourself.
+///
+/// > Note: Unlike some other Foundation classes with corresponding Core Foundation names (such as ``NSString`` and <doc://com.apple.documentation/documentation/corefoundation/cfstring>), ``Bundle`` objects cannot be cast to <doc://com.apple.documentation/documentation/corefoundation/cfbundle> references. If you need functionality provided by <doc://com.apple.documentation/documentation/corefoundation/cfbundle>, you can still create a <doc://com.apple.documentation/documentation/corefoundation/cfbundle> and use the <doc://com.apple.documentation/documentation/corefoundation/cfbundle> API. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html#//apple_ref/doc/uid/TP40010810-CH2) for more information.
+///
+/// ### Finding and Opening a Bundle
+///
+/// Before you can locate a resource, you must first specify which bundle contains it. The ``Bundle`` class has many constructors, but the one you use most often is ``main``. The main bundle represents the bundle directory that contains the currently executing code. So for an app, the main bundle object gives you access to the resources that shipped with your app.
+///
+/// If your app interacts directly with plug-ins, frameworks, or other bundled content, you can use other methods of this class to create appropriate bundle objects. You can always create bundle objects from a known URL or path, but other methods make it easier to access bundles your app is already using. For example, if you link to a framework, you can use the ``init(for:)`` method to locate the framework bundle based on a class defined in that framework.
+///
+/// @TabNavigator {
+/// @Tab("Swift") {
+/// ```swift
+/// // Get the app's main bundle
+/// let mainBundle = Bundle.main
+///
+/// // Get the bundle containing the specified private class.
+/// let myBundle = Bundle(for: NSClassFromString("MyPrivateClass")!)
+/// ```
+/// }
+/// @Tab("Objective-C") {
+/// ```objc
+/// // Get the app's main bundle
+/// NSBundle *main = [NSBundle mainBundle];
+///
+/// // Get the bundle containing the specified private class.
+/// NSBundle *myBundle = [NSBundle bundleForClass:[MyPrivateClass class]];
+/// ```
+/// }
+/// }
+///
+/// In Swift, use the ``bundle()`` macro to insert a bundle instance appropriate to the current execution context, whether an app, app extension, framework, or Swift package.
+///
+/// ### Locating Resources in a Bundle
+///
+/// You use ``Bundle`` objects to obtain the location of specific resources inside the bundle. When looking for resources, you provide the name of the resource and its type at a minimum. For resources in a specific subdirectory, you can also specify that directory. After locating the resource, the bundle routines return a path string or URL that you can use to open the file.
+///
+/// Locating a single resource in a bundle
+///
+/// ```objc
+/// NSBundle *main = [NSBundle mainBundle];
+/// NSString *resourcePath = [main pathForResource:@"Seagull" ofType:@"jpg"];
+/// ```
+///
+///
+///
+///
+/// Bundle objects follow a specific search pattern when looking for resources on disk. Global resources—that is, resources not in a language-specific `.lproj` directory—are returned first, followed by region- and language-specific resources. This search pattern means that the bundle looks for resources in the following order:
+///
+/// 1. Global (nonlocalized) resources
+/// 2. Region-specific localized resources (based on the user's region preferences)
+/// 3. Language-specific localized resources (based on the user's language preferences)
+/// 4. Development language resources (as specified by the [CFBundleDevelopmentRegion](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-130430) key in the bundle's Info.plist file)
+///
+///
+/// Because global resources take precedence over language-specific resources, you should never include both a global and localized version of a given resource in your app. When a global version of a resource exists, language-specific versions are never returned. The reason for this precedence is performance. If localized resources were searched first, the bundle object might waste time searching for a nonexistent localized resource before returning the global resource.
+///
+/// > Important:
+/// > Bundle objects always consider case when searching for resource files, even on file systems that support case-insensitive filenames. Always make sure that you specify filenames with case sensitivity in mind.
+///
+/// When locating resource files, the bundle object automatically considers many standard filename modifiers when determining which file to return. Resources may be tagged for a specific device (`~iphone`, `~ipad`) or for a specific screen resolution (`@2x`, `@3x`). Do not include these modifiers when specifying the name of the resource you want. The bundle object selects the file that is most appropriate for the underlying device. For more information, see [App Icons on iPhone, iPad and Apple Watch](https://developer.apple.com/library/archive/qa/qa1686/_index.html#//apple_ref/doc/uid/DTS40009882).
+///
+/// ### Understanding Bundle Structures
+///
+/// Bundle structures vary depending on the target platform and the type of bundle you are building. The ``Bundle`` class hides this underlying structure in most (but not all) cases. Many of the methods you use to load resources from a bundle automatically locate the appropriate starting directory and look for resources in known places. You can also use the methods and properties of this class to get the location of known bundle directories and to retrieve resources specifically from those directories.
+///
+/// For information about the bundle structure of iOS and macOS apps, see [Bundle Programming Guide](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/Introduction/Introduction.html#//apple_ref/doc/uid/10000123i). For information about the structure of framework bundles, see [Framework Programming Guide](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Frameworks.html#//apple_ref/doc/uid/10000183i). For information about the structure of macOS plug-ins, see [Code Loading Programming Topics](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/LoadingCode/LoadingCode.html#//apple_ref/doc/uid/10000052i).
NS_SWIFT_SENDABLE
@interface NSBundle : NSObject
/* Methods for creating or retrieving bundle instances. */
+
+/// Returns the bundle object that contains the current executable.
+///
+/// The main bundle lets you access the resources in the same directory as the currently running executable. For a running app or code running in a framework, the main bundle offers access to the app's bundle directory.
+///
+/// This method may return a valid bundle object even for unbundled apps. It may also return `nil` if the bundle object could not be created, so always check the return value.
@property (class, readonly, strong) NSBundle *mainBundle;
+/// Creates and returns an `NSBundle` object that corresponds to the specified directory.
+///
+/// @param path The path to a directory. This must be a full pathname for a directory; if it contains any symbolic links, they must be resolvable.
+/// @return An `NSBundle` object that corresponds to @c path. Returns @c nil if @c path does not exist or the user doesn't have access to it.
+ (nullable instancetype)bundleWithPath:(NSString *)path;
+
+/// Returns an `NSBundle` object initialized to correspond to the specified directory.
+///
+/// This method initializes and returns a new instance only if there is no existing bundle associated with @c fullPath,
+/// otherwise it deallocates @c self and returns the existing object.
+///
+/// @param path The path to a directory. This must be a full pathname for a directory; if it contains any symbolic links, they must be resolvable.
+/// @return An `NSBundle` object initialized to correspond to @c fullPath, or @c nil if @c fullPath doesn't exist or the user doesn't have access to it.
- (nullable instancetype)initWithPath:(NSString *)path NS_DESIGNATED_INITIALIZER;
+/// Creates and returns an `NSBundle` object that corresponds to the specified file URL.
+///
+/// @param url The file URL to a directory. This must be a full URL for a directory; if it contains any symbolic links, they must be resolvable.
+/// @return An `NSBundle` object that corresponds to @c url. Returns @c nil if @c url does not exist or the user doesn't have access to it.
+ (nullable instancetype)bundleWithURL:(NSURL *)url API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// Returns an `NSBundle` object initialized to correspond to the specified file URL.
+///
+/// This method initializes and returns a new instance only if there is no existing bundle associated with @c url,
+/// otherwise it deallocates @c self and returns the existing object.
+///
+/// @param url The file URL to a directory. This must be a full URL for a directory; if it contains any symbolic links, they must be resolvable.
+/// @return An `NSBundle` object initialized to correspond to @c url, or @c nil if @c url doesn't exist or the user doesn't have access to it.
- (nullable instancetype)initWithURL:(NSURL *)url API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns the `NSBundle` object with which the specified class is associated.
+///
+/// @param aClass A class.
+/// @return The `NSBundle` object that dynamically loaded @c aClass (a loadable bundle), the `NSBundle` object for the framework in which @c aClass is defined, or the main bundle object if @c aClass was not dynamically loaded or is not defined in a framework.
+ (NSBundle *)bundleForClass:(Class)aClass;
+
+/// Returns the `NSBundle` instance that has the specified bundle identifier.
+///
+/// This method is typically used by frameworks and plug-ins to locate their own bundle at runtime. It may be somewhat more
+/// efficient than trying to locate the bundle using @c bundleForClass:. However, if the initial lookup fails, this method
+/// uses potentially time-consuming heuristics to attempt to locate the bundle.
+///
+/// @param identifier The identifier for an existing `NSBundle` instance.
+/// @return The previously allocated `NSBundle` object with the bundle identifier @c identifier, or @c nil if the requested bundle is not found.
+ (nullable NSBundle *)bundleWithIdentifier:(NSString *)identifier;
+/// An array of all the application's non-framework bundles.
+///
+/// The returned array includes the main bundle and all bundles that have been dynamically created but doesn't contain any bundles that represent frameworks.
@property (class, readonly, copy) NSArray<NSBundle *> *allBundles;
+
+/// An array of all of the application's bundles that represent frameworks.
+///
+/// The returned array includes frameworks that are linked into an application when the application is built and bundles for frameworks that have been dynamically created. Only frameworks with one or more Objective-C classes in them are included.
@property (class, readonly, copy) NSArray<NSBundle *> *allFrameworks;
/* Methods for loading and unloading bundles. */
+
+/// Dynamically loads the bundle's executable code into a running program, if the code has not already been loaded.
+///
+/// You can use this method to load the code associated with a dynamically loaded bundle, such as a plug-in or framework.
+/// You don't need to load a bundle's executable code to search the bundle's resources.
+/// @return @c YES if the method successfully loads the bundle's code or if the code has already been loaded, otherwise @c NO.
- (BOOL)load;
+
+/// The load status of a bundle.
+///
+/// @c YES if the bundle's code is currently loaded, otherwise @c NO.
@property (readonly, getter=isLoaded) BOOL loaded;
+
+/// Unloads the code associated with the receiver.
+///
+/// This method attempts to unload a bundle's executable code using the underlying dynamic loader (typically @c dyld).
+/// You may use this method to unload plug-in and framework bundles when you no longer need the code they contain.
+/// It is the responsibility of the caller to ensure that no in-memory objects or data structures refer to the code being unloaded.
+/// @return @c YES if the bundle was successfully unloaded or was not already loaded; otherwise, @c NO if the bundle could not be unloaded.
- (BOOL)unload;
+/// Returns a Boolean value indicating whether the bundle's executable code could be loaded successfully.
+///
+/// This method does not actually load the bundle's executable code. Instead, it performs several checks to see if the code
+/// could be loaded and with one exception returns the same errors that would occur during an actual load operation.
+/// @param error On output, this variable may contain an error object indicating why the bundle's executable could not be loaded.
+/// @return @c YES if the bundle's executable code could be loaded successfully or is already loaded; otherwise, @c NO.
- (BOOL)preflightAndReturnError:(NSError **)error API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0));
+
+/// Loads the bundle's executable code and returns any errors.
+///
+/// If this method returns @c NO and you pass a value for the @c error parameter, a suitable error object is returned.
+/// Potential errors include @c NSFileNoSuchFileError, @c NSExecutableNotLoadableError,
+/// @c NSExecutableArchitectureMismatchError, @c NSExecutableRuntimeMismatchError,
+/// @c NSExecutableLoadError, and @c NSExecutableLinkError.
+/// @param error On output, this variable may contain an error object indicating why the bundle's executable could not be loaded.
+/// @return @c YES if the bundle's executable code was loaded successfully or was already loaded; otherwise, @c NO.
- (BOOL)loadAndReturnError:(NSError **)error API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0));
/* Methods for locating various components of a bundle. */
+
+/// The full URL of the receiver's bundle directory.
@property (readonly, copy) NSURL *bundleURL API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// The file URL of the bundle's subdirectory containing resource files.
+///
+/// This property contains the appropriate path for modern application and framework bundles. This property may not contain a path for non-standard bundle formats or for some older bundle formats.
@property (nullable, readonly, copy) NSURL *resourceURL API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// The file URL of the receiver's executable file.
@property (nullable, readonly, copy) NSURL *executableURL API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// Returns the file URL of the executable with the specified name in the receiver's bundle.
+///
+/// This method returns the appropriate path for modern application and framework bundles.
+/// This method may not return a URL for non-standard bundle formats or for some older bundle formats.
+/// @param executableName The name of an executable file.
+/// @return The file URL of the executable in the receiver's bundle.
- (nullable NSURL *)URLForAuxiliaryExecutable:(NSString *)executableName API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// The file URL of the bundle's subdirectory containing private frameworks.
+///
+/// This property contains the appropriate path for modern application and framework bundles. This property may not be a URL for non-standard bundle formats or for some older bundle formats.
@property (nullable, readonly, copy) NSURL *privateFrameworksURL API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// The file URL of the receiver's subdirectory containing shared frameworks.
+///
+/// This property contains the appropriate path for modern application and framework bundles. This property may not contain a URL for non-standard bundle formats or for some older bundle formats.
@property (nullable, readonly, copy) NSURL *sharedFrameworksURL API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// The file URL of the bundle's subdirectory containing shared support files.
+///
+/// This property contains the appropriate path for modern application and framework bundles. This property may not contain a path for non-standard bundle formats or for some older bundle formats.
@property (nullable, readonly, copy) NSURL *sharedSupportURL API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// The file URL of the receiver's subdirectory containing plug-ins.
+///
+/// This is the appropriate path for modern application and framework bundles. This may not be a URL for non-standard bundle formats or for some older bundle formats.
@property (nullable, readonly, copy) NSURL *builtInPlugInsURL API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
#if defined(__swift__) // Deprecated for Swift only
+/// The file URL for the bundle's App Store receipt.
+///
+/// Use this app bundle property to locate the app receipt if it's present; this property is @c nil if the receipt isn't present.
+/// In the rare case a receipt is invalid or missing in an app that a user downloads from the App Store,
+/// use @c SKReceiptRefreshRequest to request a new receipt.
@property (nullable, readonly, copy) NSURL *appStoreReceiptURL API_DEPRECATED("Use AppTransaction.shared and Transaction.all from StoreKit.framework instead", macosx(10.7,15.0), ios(7.0,18.0), watchos(2.0,11.0), tvos(9.0,18.0));
#else
+/// The file URL for the bundle's App Store receipt.
+///
+/// Use this app bundle property to locate the app receipt if it's present; this property is @c nil if the receipt isn't present.
+/// In the rare case a receipt is invalid or missing in an app that a user downloads from the App Store,
+/// use @c SKReceiptRefreshRequest to request a new receipt.
@property (nullable, readonly, copy) NSURL *appStoreReceiptURL API_AVAILABLE(macos(10.7), ios(7.0), watchos(2.0), tvos(9.0));
#endif
+/// The full pathname of the receiver's bundle directory.
@property (readonly, copy) NSString *bundlePath;
+
+/// The full pathname of the bundle's subdirectory containing resources.
@property (nullable, readonly, copy) NSString *resourcePath;
+
+/// The full pathname of the receiver's executable file.
@property (nullable, readonly, copy) NSString *executablePath;
+
+/// Returns the full pathname of the executable with the specified name in the receiver's bundle.
+///
+/// This method returns the appropriate path for modern application and framework bundles.
+/// This method may not return a path for non-standard bundle formats or for some older bundle formats.
+/// @param executableName The name of an executable file.
+/// @return The full pathname of the executable in the receiver's bundle.
- (nullable NSString *)pathForAuxiliaryExecutable:(NSString *)executableName;
+/// The full pathname of the bundle's subdirectory containing private frameworks.
+///
+/// This property contains the appropriate path for modern application and framework bundles. This property may not contain a path for non-standard bundle formats or for some older bundle formats.
@property (nullable, readonly, copy) NSString *privateFrameworksPath;
+
+/// The full pathname of the bundle's subdirectory containing shared frameworks.
+///
+/// This property contains the appropriate path for modern application and framework bundles. This property may not contain a path for non-standard bundle formats or for some older bundle formats.
@property (nullable, readonly, copy) NSString *sharedFrameworksPath;
+
+/// The full pathname of the bundle's subdirectory containing shared support files.
+///
+/// This property contains the appropriate path for modern application and framework bundles. This property may not contain a path for non-standard bundle formats or for some older bundle formats.
@property (nullable, readonly, copy) NSString *sharedSupportPath;
+
+/// The full pathname of the receiver's subdirectory containing plug-ins.
+///
+/// This is the appropriate path for modern application and framework bundles. This may not be a path for non-standard bundle formats or for some older bundle formats.
@property (nullable, readonly, copy) NSString *builtInPlugInsPath;
/* Methods for locating bundle resources. Instance methods locate resources in the bundle indicated by the receiver; class methods take an argument pointing to a bundle on disk. In the class methods, bundleURL is a URL pointing to the location of a bundle on disk, and may not be nil; bundlePath is the path equivalent of bundleURL, an absolute path pointing to the location of a bundle on disk. By contrast, subpath is a relative path to a subdirectory inside the relevant global or localized resource directory, and should be nil if the resource file in question is not in a subdirectory. Where appropriate, localizationName is the name of a .lproj directory in the bundle, minus the .lproj extension; passing nil for localizationName retrieves only global resources, whereas using a method without this argument retrieves both global and localized resources (using the standard localization search algorithm). */
+/// Creates and returns a file URL for the resource with the specified name and extension in the specified bundle.
+///
+/// @param name The name of the resource file. If @c nil, the method returns the first resource file it finds that matches the remaining criteria.
+/// @param ext The filename extension of the file to locate. If an empty string or @c nil, the extension is assumed not to exist.
+/// @param subpath The name of the bundle subdirectory to search.
+/// @param bundleURL The file URL of the bundle to search.
+/// @return The file URL for the resource file or @c nil if the file could not be located.
+ (nullable NSURL *)URLForResource:(nullable NSString *)name withExtension:(nullable NSString *)ext subdirectory:(nullable NSString *)subpath inBundleWithURL:(NSURL *)bundleURL API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// Returns an array containing the file URLs for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, within the specified bundle.
+///
+/// @param ext The filename extension of the files to locate. If an empty string or @c nil, all files in @c subpath are returned.
+/// @param subpath The name of the bundle subdirectory to search.
+/// @param bundleURL The file URL of the bundle to search.
+/// @return An array of file URLs for the resource files matching the criteria or an empty array if no files could be located.
+ (nullable NSArray<NSURL *> *)URLsForResourcesWithExtension:(nullable NSString *)ext subdirectory:(nullable NSString *)subpath inBundleWithURL:(NSURL *)bundleURL API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns the file URL for the resource identified by the specified name and file extension.
+///
+/// @param name The name of the resource file. If @c nil, the method returns the first resource file it finds with the specified extension.
+/// @param ext The extension of the resource file. If an empty string or @c nil, the extension is assumed not to exist.
+/// @return The file URL for the resource file or @c nil if the file could not be located.
- (nullable NSURL *)URLForResource:(nullable NSString *)name withExtension:(nullable NSString *)ext API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// Returns the file URL for the resource file identified by the specified name and extension and residing in a given bundle directory.
+///
+/// @param name The name of a resource file. If @c nil, the method returns the first resource file it finds with the specified extension.
+/// @param ext The filename extension of the file to locate. If an empty string or @c nil, the extension is assumed not to exist.
+/// @param subpath The name of the bundle subdirectory to search.
+/// @return The file URL for the resource file or @c nil if the file could not be located.
- (nullable NSURL *)URLForResource:(nullable NSString *)name withExtension:(nullable NSString *)ext subdirectory:(nullable NSString *)subpath API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// Returns the file URL for the resource identified by the specified name and file extension, located in the specified bundle subdirectory, and limited to global resources and those associated with the specified localization.
+///
+/// @param name The name of the resource file. If @c nil, the method returns the first resource file it finds that matches the remaining criteria.
+/// @param ext The filename extension of the file to locate. If an empty string or @c nil, the extension is assumed not to exist.
+/// @param subpath The name of the bundle subdirectory to search.
+/// @param localizationName The language ID for the localization. This parameter should correspond to the name of one of the bundle's language-specific resource directories without the @c .lproj extension.
+/// @return The file URL for the resource file or @c nil if the file could not be located.
- (nullable NSURL *)URLForResource:(nullable NSString *)name withExtension:(nullable NSString *)ext subdirectory:(nullable NSString *)subpath localization:(nullable NSString *)localizationName API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns an array of file URLs for all resources identified by the specified file extension and located in the specified bundle subdirectory.
+///
+/// @param ext The filename extension of the files to locate. If an empty string or @c nil, all files in @c subpath are returned.
+/// @param subpath The name of the bundle subdirectory.
+/// @return An array of file URLs for the resource files or @c nil if no files could be located.
- (nullable NSArray<NSURL *> *)URLsForResourcesWithExtension:(nullable NSString *)ext subdirectory:(nullable NSString *)subpath API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+
+/// Returns an array containing the file URLs for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, and limited to global resources and those associated with the specified localization.
+///
+/// @param ext The filename extension of the files to locate. If an empty string or @c nil, all files in @c subpath are returned.
+/// @param subpath The name of the bundle subdirectory to search.
+/// @param localizationName The language ID for the localization. This parameter should correspond to the name of one of the bundle's language-specific resource directories without the @c .lproj extension.
+/// @return An array containing the file URLs for all bundle resources matching the specified criteria. Returns an empty array if no matching resource files are found.
- (nullable NSArray<NSURL *> *)URLsForResourcesWithExtension:(nullable NSString *)ext subdirectory:(nullable NSString *)subpath localization:(nullable NSString *)localizationName API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Returns the full pathname for the resource file identified by the specified name and extension and residing in a given bundle directory.
+///
+/// @param name The name of a resource file contained in the directory specified by @c bundlePath. If @c nil, the method returns the first resource file it finds with the specified extension.
+/// @param ext The filename extension of the file to locate. If an empty string or @c nil, the extension is assumed not to exist.
+/// @param bundlePath The path of a top-level bundle directory. This must be a valid path.
+/// @return The full pathname for the resource file or @c nil if the file could not be located.
+ (nullable NSString *)pathForResource:(nullable NSString *)name ofType:(nullable NSString *)ext inDirectory:(NSString *)bundlePath;
+
+/// Returns an array containing the pathnames for all bundle resources having the specified extension and residing in the bundle directory at the specified path.
+///
+/// @param ext The filename extension of the files to locate. If an empty string or @c nil, all files in @c bundlePath are returned.
+/// @param bundlePath The top-level directory of a bundle. This must represent a valid path.
+/// @return An array containing the full pathnames for all bundle resources with the specified extension. Returns an empty array if no matching resource files are found.
+ (NSArray<NSString *> *)pathsForResourcesOfType:(nullable NSString *)ext inDirectory:(NSString *)bundlePath;
+/// Returns the full pathname for the resource identified by the specified name and file extension.
+///
+/// The method first looks for a matching resource file in the non-localized resource directory of the specified bundle.
+/// If a matching resource file is not found, it then looks in the top level of an available language-specific @c .lproj folder.
+/// @param name The name of the resource file. If @c nil, the method returns the first resource file it finds with the specified extension.
+/// @param ext The filename extension of the file to locate. If an empty string or @c nil, the extension is assumed not to exist.
+/// @return The full pathname for the resource file, or @c nil if the file could not be located.
- (nullable NSString *)pathForResource:(nullable NSString *)name ofType:(nullable NSString *)ext;
+
+/// Returns the full pathname for the resource identified by the specified name and file extension and located in the specified bundle subdirectory.
+///
+/// @param name The name of the resource file. If @c nil, the method returns the first resource file it finds that matches the remaining criteria.
+/// @param ext The filename extension of the files to locate. If an empty string or @c nil, all files in @c subpath and its subdirectories are returned.
+/// @param subpath The name of the bundle subdirectory.
+/// @return The full pathname for the resource file, or @c nil if the file could not be located.
- (nullable NSString *)pathForResource:(nullable NSString *)name ofType:(nullable NSString *)ext inDirectory:(nullable NSString *)subpath;
+
+/// Returns the full pathname for the resource identified by the specified name and file extension, located in the specified bundle subdirectory, and limited to global resources and those associated with the specified localization.
+///
+/// @param name The name of the resource file. If @c nil, the method returns the first resource file it finds that matches the remaining criteria.
+/// @param ext The filename extension of the files to locate. If an empty string or @c nil, the extension is assumed not to exist.
+/// @param subpath The name of the bundle subdirectory to search.
+/// @param localizationName The language ID for the localization. This parameter should correspond to the name of one of the bundle's language-specific resource directories without the @c .lproj extension.
+/// @return The full pathname for the resource file or @c nil if the file could not be located.
- (nullable NSString *)pathForResource:(nullable NSString *)name ofType:(nullable NSString *)ext inDirectory:(nullable NSString *)subpath forLocalization:(nullable NSString *)localizationName;
+/// Returns an array containing the pathnames for all bundle resources having the specified filename extension and residing in the resource subdirectory.
+///
+/// @param ext The filename extension of the files to locate. If an empty string or @c nil, all files in @c subpath are returned.
+/// @param subpath The name of the bundle subdirectory to search.
+/// @return An array containing the full pathnames for all bundle resources matching the specified criteria. Returns an empty array if no matching resource files are found.
- (NSArray<NSString *> *)pathsForResourcesOfType:(nullable NSString *)ext inDirectory:(nullable NSString *)subpath;
+
+/// Returns an array containing the file for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, and limited to global resources and those associated with the specified localization.
+///
+/// @param ext The filename extension of the files to locate. If an empty string or @c nil, all files in @c subpath are returned.
+/// @param subpath The name of the bundle subdirectory to search.
+/// @param localizationName The language ID for the localization. This parameter should correspond to the name of one of the bundle's language-specific resource directories without the @c .lproj extension.
+/// @return An array containing the full pathnames for all bundle resources matching the specified criteria. Returns an empty array if no matching resource files are found.
- (NSArray<NSString *> *)pathsForResourcesOfType:(nullable NSString *)ext inDirectory:(nullable NSString *)subpath forLocalization:(nullable NSString *)localizationName;
/* Methods for retrieving localized strings. */
+
+/// Returns a localized version of the string designated by the specified key and residing in the specified table.
+///
+/// @param key The key for a string in the table identified by @c tableName.
+/// @param value The value to return if @c key is @c nil or if a localized string for @c key can't be found in the table.
+/// @param tableName The receiver's string table to search. If @c nil or an empty string, the method attempts to use the table in @c Localizable.strings.
+/// @return A localized version of the string designated by @c key in table @c tableName.
- (NSString *)localizedStringForKey:(NSString *)key value:(nullable NSString *)value table:(nullable NSString *)tableName NS_FORMAT_ARGUMENT(1);
#if !0
- (NSAttributedString *)localizedAttributedStringForKey:(NSString *)key value:(nullable NSString *)value table:(nullable NSString *)tableName NS_FORMAT_ARGUMENT(1) NS_REFINED_FOR_SWIFT API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0));
@@ -107,41 +436,218 @@
- (NSString *)localizedStringForKey:(NSString *)key value:(nullable NSString *)value table:(nullable NSString *)tableName localizations:(NSArray<NSString *>*)localizations NS_FORMAT_ARGUMENT(1) API_AVAILABLE(macos(15.4), ios(18.4), watchos(11.4), tvos(18.4), visionos(2.4)) NS_REFINED_FOR_SWIFT;
/* Methods for obtaining various information about a bundle. */
+
+/// The receiver's bundle identifier.
+///
+/// The bundle identifier is defined by the @c CFBundleIdentifier key in the bundle's information property list.
@property (nullable, readonly, copy) NSString *bundleIdentifier;
+
+/// A dictionary, constructed from the bundle's @c Info.plist file, that contains information about the receiver.
+///
+/// If the bundle does not contain an @c Info.plist file, this dictionary contains only private keys that are used internally by the @c NSBundle class.
+/// Common keys for accessing the values of the dictionary are @c CFBundleIdentifier, @c NSMainNibFile, and @c NSPrincipalClass.
@property (nullable, readonly, copy) NSDictionary<NSString *, id> *infoDictionary;
+
+/// A dictionary with the keys from the bundle's localized property list.
+///
+/// This property uses the preferred localization for the current user when determining which resources to include.
+/// If the preferred localization is not available, this property chooses the most appropriate localization found in the bundle.
@property (nullable, readonly, copy) NSDictionary<NSString *, id> *localizedInfoDictionary;
+
+/// Returns the value associated with the specified key in the receiver's information property list.
+///
+/// Use of this method is preferred over other access methods because it returns the localized value of a key when one is available.
+/// @param key A key in the receiver's property list.
+/// @return The value associated with @c key in the receiver's property list (@c Info.plist). The localized value of a key is returned when one is available.
- (nullable id)objectForInfoDictionaryKey:(NSString *)key;
+
+/// Returns the @c Class object for the specified name.
+///
+/// If the bundle's executable code is not yet loaded, this method dynamically loads it into memory.
+/// @param className The name of a class.
+/// @return The @c Class object for @c className. Returns @c nil if @c className is not one of the classes associated with the receiver or if there is an error loading the executable code.
- (nullable Class)classNamed:(NSString *)className;
+
+/// The bundle's principal class.
+///
+/// This property is set after ensuring that the code containing the definition of the class is dynamically loaded.
+/// If the bundle encounters errors in loading or if it can't find the executable code file in the bundle directory, this property is @c nil.
+/// The bundle obtains the principal class from the information dictionary using the key @c NSPrincipalClass. For non-loadable bundles
+/// (applications and frameworks), if the principal class is not specified in the property list, this property is @c nil.
@property (nullable, readonly) Class principalClass;
/* Methods for dealing with localizations. */
+
+/// An ordered list of preferred localizations contained in the bundle.
+///
+/// An array of @c NSString objects containing language IDs for localizations in the bundle.
+/// The strings are ordered according to the user's language preferences and available localizations.
@property (readonly, copy) NSArray<NSString *> *preferredLocalizations; // a subset of this bundle's localizations, re-ordered into the preferred order for this process's current execution environment; the main bundle's preferred localizations indicate the language (of text) the user is most likely seeing in the UI
+/// A list of all the localizations contained in the bundle.
+///
+/// An array of @c NSString objects containing language IDs for all the localizations contained in the bundle.
@property (readonly, copy) NSArray<NSString *> *localizations; // list of language names this bundle appears to be localized to
+
+/// The localization for the development language.
+///
+/// This property corresponds to the value in the @c CFBundleDevelopmentRegion key of the bundle's property list (@c Info.plist).
@property (nullable, readonly, copy) NSString *developmentLocalization;
+/// Returns one or more localizations from the specified list that a bundle object would use to locate resources for the current user.
+///
+/// This method does not return all localizations in preference order but only those from which @c NSBundle would get
+/// localized content, typically either a single non-region-specific localization or a region-specific localization
+/// followed by a corresponding non-region-specific localization as a fallback.
+/// @param localizationsArray An array of @c NSString objects, each of which specifies the language ID for a localization that the bundle supports.
+/// @return An array of @c NSString objects containing the preferred localizations, ordered according to the user's language preferences.
+ (NSArray<NSString *> *)preferredLocalizationsFromArray:(NSArray<NSString *> *)localizationsArray;
+
+/// Returns locale identifiers for which a bundle would provide localized content, given a specified list of candidates for a user's language preferences.
+///
+/// @param localizationsArray An array of identifiers, each corresponding to a localization that a bundle can support.
+/// @param preferencesArray An array of BCP 47 language codes corresponding to a user's preferred languages. If @c nil, the method uses the current user's language preferences.
+/// @return An array of locale identifiers, ordered according to user preference. If none of the user-preferred localizations are available, this method returns one of the values in @c localizationsArray.
+ (NSArray<NSString *> *)preferredLocalizationsFromArray:(NSArray<NSString *> *)localizationsArray forPreferences:(nullable NSArray<NSString *> *)preferencesArray;
/* Method for determining executable architectures. */
enum {
+ /// The 32-bit Intel architecture.
NSBundleExecutableArchitectureI386 = 0x00000007,
+ /// The 32-bit PowerPC architecture.
NSBundleExecutableArchitecturePPC = 0x00000012,
+ /// The 64-bit Intel architecture.
NSBundleExecutableArchitectureX86_64 = 0x01000007,
+ /// The 64-bit PowerPC architecture.
NSBundleExecutableArchitecturePPC64 = 0x01000012,
+ /// The 64-bit ARM architecture.
NSBundleExecutableArchitectureARM64 API_AVAILABLE(macos(11.0), ios(14.0), watchos(7.0), tvos(14.0)) = 0x0100000c
};
+/// An array of numbers indicating the architecture types supported by the bundle's executable.
+///
+/// An array of @c NSNumber objects, each of which contains an integer value corresponding to a supported processor
+/// architecture. If the bundle does not contain a Mach-O executable, this is @c nil.
@property (nullable, readonly, copy) NSArray<NSNumber *> *executableArchitectures API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0));
@end
+/// Returns a localized version of a string from the default table, which Xcode autogenerates when exporting localizations.
+///
+/// Use this macro to automatically generate the default `Localizable.strings` file from your code
+/// when exporting localizations from Xcode or the `genstrings` utility. You can specify Unicode
+/// characters in `key` using `\\Uxxxx`---see the `-u` option for the `genstrings` utility.
+///
+/// The initial value for `key` in the strings file is `key`. To avoid collisions between words or
+/// phrases with multiple meanings, use a unique `key` for each use of the same phrase. Use the
+/// ``NSLocalizedStringWithDefaultValue`` macro to specify another value for `key`.
+///
+/// As of OS X 10.11 and iOS 9, `NSBundle` is thread-safe. As such, you can safely call
+/// `NSLocalizedString` from any execution context.
+///
+/// > Important: The values for `key` and `comment` must be string literal values. Xcode can read
+/// > these values from source code to automatically create localization tables when exporting
+/// > localizations, but it doesn't resolve string variables. If you want to use string variables,
+/// > manually create a strings file and use ``NSBundle/localizedStringForKey:value:table:`` instead.
+///
+/// - Parameters:
+/// - key: The key for a string in the default table.
+/// - comment: The comment to place above the key-value pair in the strings file. This parameter
+/// provides the translator with some context about the localized string's presentation to the user.
+/// - Returns: The result of sending ``NSBundle/localizedStringForKey:value:table:`` to the main bundle,
+/// passing the specified `key`.
#define NSLocalizedString(key, comment) \
[NSBundle.mainBundle localizedStringForKey:(key) value:@"" table:nil]
+/// Returns a localized version of a string from the table that you specify, which Xcode autogenerates when exporting localizations.
+///
+/// Use this macro to automatically generate a strings file named `[tableName].strings` from your
+/// code when exporting localizations from Xcode or the `genstrings` utility. You can specify
+/// Unicode characters in `key` using `\\Uxxxx`---see the `-u` option for the `genstrings` utility.
+///
+/// The initial value for `key` in the strings file is `key`. To avoid collisions between words or
+/// phrases with multiple meanings, use a unique `key` for each use of the same phrase. Use the
+/// ``NSLocalizedStringWithDefaultValue`` macro to specify another value for `key`.
+///
+/// As of OS X 10.11 and iOS 9, `NSBundle` is thread-safe. As such, you can safely call
+/// `NSLocalizedStringFromTable` from any execution context.
+///
+/// > Important: The values for `key`, `tbl`, and `comment` must be string literal values. Xcode
+/// > can read these values from source code to automatically create localization tables when
+/// > exporting localizations, but it doesn't resolve string variables. If you want to use string
+/// > variables, manually create a strings file and use ``NSBundle/localizedStringForKey:value:table:``
+/// > instead.
+///
+/// - Parameters:
+/// - key: The key for a string in the specified table.
+/// - tbl: The name of the table containing the key-value pairs. Also, the suffix for the strings
+/// file (a file with the `.strings` extension) to store the localized string. The default table
+/// in `Localizable.strings` is used when `tbl` is `nil` or an empty string.
+/// - comment: The comment to place above the key-value pair in the strings file. This parameter
+/// provides the translator with some context about the localized string's presentation to the user.
+/// - Returns: The result of invoking ``NSBundle/localizedStringForKey:value:table:`` on the main bundle,
+/// passing the specified `key` and `tbl`.
#define NSLocalizedStringFromTable(key, tbl, comment) \
[NSBundle.mainBundle localizedStringForKey:(key) value:@"" table:(tbl)]
+/// Returns a localized version of a string from the table and bundle that you specify, which Xcode autogenerates when exporting localizations.
+///
+/// Use this macro to automatically generate a strings file named `[tableName].strings` located in
+/// `bundle` from your code when exporting localizations from Xcode or the `genstrings` utility.
+/// You can specify Unicode characters in `key` using `\\Uxxxx`---see the `-u` option for the
+/// `genstrings` utility.
+///
+/// The initial value for `key` in the strings file is `key`. To avoid collisions between words or
+/// phrases with multiple meanings, use a unique `key` for each use of the same phrase. Use the
+/// ``NSLocalizedStringWithDefaultValue`` macro to specify another value for `key`.
+///
+/// As of OS X 10.11 and iOS 9, `NSBundle` is thread-safe. As such, you can safely call
+/// `NSLocalizedStringFromTableInBundle` from any execution context.
+///
+/// > Important: The values for `key`, `tbl`, and `comment` must be string literal values. Xcode
+/// > can read these values from source code to automatically create localization tables when
+/// > exporting localizations, but it doesn't resolve string variables. If you want to use string
+/// > variables, manually create a strings file and use ``NSBundle/localizedStringForKey:value:table:``
+/// > instead.
+///
+/// - Parameters:
+/// - key: The key for a string in the specified table.
+/// - tbl: The name of the table containing the key-value pairs. Also, the suffix for the strings
+/// file (a file with the `.strings` extension) to store the localized string. The default table
+/// in `Localizable.strings` is used when `tbl` is `nil` or an empty string.
+/// - bundle: The bundle containing the table's strings file.
+/// - comment: The comment to place above the key-value pair in the strings file. This parameter
+/// provides the translator with some context about the localized string's presentation to the user.
+/// - Returns: The result of sending ``NSBundle/localizedStringForKey:value:table:`` to `bundle`,
+/// passing the specified `key` and `tbl`.
#define NSLocalizedStringFromTableInBundle(key, tbl, bundle, comment) \
[bundle localizedStringForKey:(key) value:@"" table:(tbl)]
+/// Returns a localized version of a string identified by a key in the table that you specify, which Xcode autogenerates when exporting localizations.
+///
+/// Use this macro to automatically generate a strings file named `[tableName].strings` located in
+/// `bundle` from your code when exporting localizations from Xcode or the `genstrings` utility.
+/// The initial value for `key` in the strings file is `val`. You can specify Unicode characters in
+/// `key` using `\\Uxxxx`---see the `-u` option for the `genstrings` utility.
+///
+/// As of OS X 10.11 and iOS 9, `NSBundle` is thread-safe. As such, you can safely call
+/// `NSLocalizedStringWithDefaultValue` from any execution context.
+///
+/// > Important: The values for `key`, `tbl`, `val`, and `comment` must be string literal values.
+/// > Xcode can read these values from source code to automatically create localization tables when
+/// > exporting localizations, but it doesn't resolve string variables. If you want to use string
+/// > variables, manually create a strings file and use ``NSBundle/localizedStringForKey:value:table:``
+/// > instead.
+///
+/// - Parameters:
+/// - key: The key for a string in the specified table.
+/// - tbl: The name of the table containing the key-value pairs. Also, the suffix for the strings
+/// file (a file with the `.strings` extension) to store the localized string. The default table
+/// in `Localizable.strings` is used when `tbl` is `nil` or an empty string.
+/// - bundle: The bundle containing the table's strings file.
+/// - val: The localized string for the development locale. For other locales, return this value
+/// if `key` is `nil` or if a localized string for `key` isn't found in the table.
+/// - comment: The comment to place above the key-value pair in the strings file. This parameter
+/// provides the translator with some context about the localized string's presentation to the user.
+/// - Returns: The result of sending ``NSBundle/localizedStringForKey:value:table:`` to `bundle`,
+/// passing the specified `key`, `val`, and `tbl`.
#define NSLocalizedStringWithDefaultValue(key, tbl, bundle, val, comment) \
[bundle localizedStringForKey:(key) value:(val) table:(tbl)]
@@ -156,13 +662,32 @@
@interface NSString (NSBundleExtensionMethods)
-/* For strings with length variations, such as from a stringsdict file, this method returns the variant at the given width. If there is no variant at the given width, the one for the next smaller width is returned. And if there are none smaller, the smallest available is returned. For strings without variations, this method returns self. The unit that width is expressed in is decided by the application or framework. But it is intended to be some measurement indicative of the context a string would fit best to avoid truncation and wasted space.
-*/
+/// Returns a string variation suitable for the specified presentation width.
+///
+/// You can use this method to provide adaptive strings for the user's device -- that is, text that avoids truncation and maximizes available space. For example, an app running on an iPad Pro in Landscape orientation might welcome a user with the message "Greetings and Salutations!", whereas the same app running on an iPhone SE in Portrait orientation might instead show an abbreviated welcome message, like "Hello!".
+///
+/// > Note: Don't call this method when setting user-visible text for standard UIKit controls, such as `UILabel`. UIKit provides built-in support for adaptive strings, and automatically selects the string width variant appropriate for the current screen size.
+///
+/// Call this method on a string with one or more width variations. You define width variations for a localized string in a Stringsdict file using the `NSStringVariableWidthRuleType` key, and then retrieve a string with variations using `NSLocalizedString`.
+///
+/// This method selects a variation for a specified width according to the following behavior:
+///
+/// - If no variations exist for the string, the original string is returned.
+/// - If a variation exists for the specified width, that string is returned.
+/// - If no variation is found with a width less than the specified value, the variation with the smallest width is returned.
+/// - Otherwise, the variation with the next smallest width value is returned.
+///
+/// - Parameter width: The desired width of the string variation.
+/// - Returns: A string variation, or the original string if no variations exist for the specified width.
- (NSString *)variantFittingPresentationWidth:(NSInteger)width API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0));
@end
+/// A notification that lets observers know when classes are dynamically loaded.
+///
+/// The notification object is the @c NSBundle instance that dynamically loads classes. The @c userInfo dictionary contains an @c NSLoadedClasses key.
FOUNDATION_EXPORT NSNotificationName const NSBundleDidLoadNotification;
+/// Generates a log of the class names loaded by the runtime.
FOUNDATION_EXPORT NSString * const NSLoadedClasses; // notification key
@@ -178,66 +703,60 @@
The request object itself is lightweight. You may create as many as you need, for example to request the same set of tags in different components of your application.
*/
-API_AVAILABLE(ios(9.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos)
+/// A resource manager you use to download content hosted on the App Store at the time your app needs it.
+///
+/// You identify on-demand resources during development by creating string identifiers known as tags and assigning one or more tags to each resource. An ``NSBundleResourceRequest`` object manages the resources marked by one or more tags.
+///
+/// You use the resource request to inform the system when the managed tags are needed and when you have finished accessing them. The resource request manages the downloading of any resources marked with the managed tags that are not already on the device and informs your app when the resources are ready for use.
+///
+/// > Note:
+/// > This class ignores calls from Mac apps built with Mac Catalyst.
+///
+/// The system will not attempt to purge the resources marked with a tag from on-device storage as long as at least one ``NSBundleResourceRequest`` object is managing the tag. Apps can access resources after the completion handler of either ``beginAccessingResources(completionHandler:)`` or ``conditionallyBeginAccessingResources(completionHandler:)`` is called successfully. Management ends after a call to ``endAccessingResources()`` or after the resource request object is deallocated.
+///
+/// Other properties and methods let you track the progress of a download, change the priority of a download, and check whether the resources marked by a set of tags are already on the device. Methods in ``Bundle`` indicate to the system the relative importance of preserving a tag in memory after it is no longer in use. For more information, see ``Bundle/setPreservationPriority(_:forTags:)`` and ``Bundle/preservationPriority(forTag:)``.
+///
+/// > Important:
+/// > An ``NSBundleResourceRequest`` object can only be used for one successful resource request.
+API_DEPRECATED("Use Background Assets instead.", ios(9.0, 27.0), watchos(2.0, 27.0), tvos(9.0, 27.0)) API_UNAVAILABLE(macos)
@interface NSBundleResourceRequest : NSObject <NSProgressReporting>
- (instancetype)init NS_UNAVAILABLE;
-/*
- A tag and bundle are required arguments to the init methods. The tag argument is required and it must exist in the manifest of the specified bundle. The bundle argument describes an existing bundle which was built with on demand resources support. Any resources downloaded can be found using the standard NSBundle resource lookup API once the request is completed. If no bundle is specified then the main bundle is used.
- */
+/// Creates a resource request with the specified tags.
+///
+/// Resources are looked up in the main bundle.
- (instancetype)initWithTags:(NSSet<NSString *> *)tags;
+/// Creates a resource request with the specified tags and bundle.
- (instancetype)initWithTags:(NSSet<NSString *> *)tags bundle:(NSBundle *)bundle NS_DESIGNATED_INITIALIZER;
-/*
- Provides a hint to the resource loading system as to the loading priority of this request. Values are limited to between 0 and 1, with 1 being the highest priority. The default priority is 0.5.
-
- The exact meaning of the value is up to your application. The system will prefer to act on requests that have a higher priority (from the same application). You may change the priority at any time, even after a request has started. The system will make a best attempt to take the new priority into account.
- */
+/// A hint to the system about the relative priority of the resource request.
+///
+/// Values are limited to between `0` and `1`, with `1` being the highest priority. The default priority is `0.5`.
@property double loadingPriority;
-/*
- The tags this request will load.
- */
+/// The tags managed by this request.
@property (readonly, copy) NSSet<NSString *> *tags;
-/*
- The bundle object that will hold the requested resources. After the -beginAccessingResourcesWithCompletionHandler: callback is invoked, you may use the standard bundle lookup APIs on this bundle object to find your resources.
- */
+/// The bundle object that will hold the requested resources.
@property (readonly, strong) NSBundle *bundle;
-/*
- Ask the system to fetch the resources that were part of the tag set in this request. Resources will not be purged while in use by the application (as indicated by the application using this begin API paired with a call to -endAccessingResources). If an application has too many fetched resources and the system is unable to reserve enough space for newly requested tags, the request may return an error.
-
- When you are finished with the resources and they may be purged off the disk, invoke -endAccessingResources. If the request object is deallocated, it will also inform the system that the resources are no longer in use.
-
- The completion block will be invoked on a non-main serial queue when the resources are available or an error has occurred. An example of a possible error that may be reported is the lack of a network connection or a problem connecting to the on-demand servers.
-
- Fetch requests are reference counted across the application. So if you have two requests outstanding with the same set of tags, each may be used independently without having to know about any global state. However, each NSBundleResourceRequest object may only be used once.
-
- If you cancel an outstanding request (via the cancel method on the NSProgress object, or cancelling a parent progress object you have created) the completion handler argument to this method will be called back with an NSUserCancelledError in the NSCocoaErrorDomain.
-
- Be sure to always invoke the -endAccessingResources method to balance a call to the begin method, even in the case of an error in the completion handler.
-
- If you want to access the resources again, create a new NSBundleResourceRequest object.
- */
+/// Requests access to the resources and initiates download of content if necessary.
+///
+/// Resources will not be purged while in use. When you are finished with the resources, invoke `-endAccessingResources`. The completion block will be invoked on a non-main serial queue when the resources are available or an error has occurred.
- (void)beginAccessingResourcesWithCompletionHandler:(void (NS_SWIFT_SENDABLE ^)(NSError * _Nullable error))completionHandler;
-/*
- Inform the system that you wish to begin accessing the resources that are part of this request, but do not attempt to download any content over the network. The completion handler will be invoked with a YES argument if the resources are available.
-
- If the resources were available, then you must invoke the -endAccessingResources method once you are done accessing them. If the resources were not available, then you may invoke the -beginAccessingResourcesWithCompletionHandler: method to initiate a download of the resources.
-*/
+/// Checks whether the resources are already available on disk without initiating a download.
+///
+/// The completion handler will be invoked with `YES` if the resources are available. If so, you must invoke `-endAccessingResources` when done. Otherwise, use `-beginAccessingResourcesWithCompletionHandler:` to initiate a download.
- (void)conditionallyBeginAccessingResourcesWithCompletionHandler:(void (NS_SWIFT_SENDABLE ^)(BOOL resourcesAvailable))completionHandler;
-/*
- Informs the system that you are finished with the resources that were part of the tag set in this request. Call this after you no longer need the resources to be available on disk. It is important to invoke this method to make room for newly requested resources. This method may only be invoked if you have received a callback from -beginAccessingResourcesWithCompletionHandler:. To cancel an in-progress request, invoke cancel on the -progress property.
- */
+/// Informs the system that you are finished with the resources that were part of the tag set in this request.
- (void)endAccessingResources;
-/*
- Progress for the request. The progress object will be valid at initialization and begin updating after the -beginAccessingResourcesWithCompletionHandler: method is called.
-*/
+/// Progress for the request.
+///
+/// The progress object will be valid at initialization and begin updating after `-beginAccessingResourcesWithCompletionHandler:` is called.
@property (readonly, strong) NSProgress *progress;
@end
@@ -250,23 +769,31 @@
This method will throw an exception if the receiver bundle has no on demand resource tag information.
*/
-- (void)setPreservationPriority:(double)priority forTags:(NSSet<NSString *> *)tags API_AVAILABLE(ios(9.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos);
-- (double)preservationPriorityForTag:(NSString *)tag API_AVAILABLE(ios(9.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos);
+/// A hint to the system of the relative order for purging tagged sets of resources in the bundle.
+///
+/// @param priority A number specifying the relative priority of preserving the resources. Possible values are between @c 0.0 and @c 1.0. The default is @c 0.0.
+/// @param tags A set of tag names specifying resources stored in the bundle. Must not be @c nil.
+- (void)setPreservationPriority:(double)priority forTags:(NSSet<NSString *> *)tags API_DEPRECATED("Use Background Assets instead.", ios(9.0, 27.0), watchos(2.0, 27.0), tvos(9.0, 27.0)) API_UNAVAILABLE(macos);
+/// Returns the current preservation priority for the specified tag.
+///
+/// @param tag A string specifying the identifier for a group of related resources.
+/// @return The preservation priority for the specified @c tag. Possible values are between @c 0.0 and @c 1.0.
+- (double)preservationPriorityForTag:(NSString *)tag API_DEPRECATED("Use Background Assets instead.", ios(9.0, 27.0), watchos(2.0, 27.0), tvos(9.0, 27.0)) API_UNAVAILABLE(macos);
+
@end
-/*
- This notification is posted to the default notification center when the resource request system detects a low disk space condition.
-
- If the application is in the background, the system needs more space, and the application does not free up enough in response to the notification then the application may be killed. The application can free up space by calling -endAccessingResources on any outstanding requests. This will inform the system that you are done with those resources and it may purge the content to make room for a new request.
-
- Note that this notification may not be the same as low disk space on the system, as applications can have a smaller quota.
- */
-FOUNDATION_EXPORT NSNotificationName const NSBundleResourceRequestLowDiskSpaceNotification API_AVAILABLE(ios(9.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos);
+/// Posted after the system detects that the amount of available disk space is getting low. The notification is posted to the default notification center.
+///
+/// After receiving this notification, the app should release any on-demand resources that are not required. Call `endAccessingResources()` to release the managed resources. If the app is in the background and the app does not free up enough space, it may be terminated.
+///
+/// > Note: This notification may not be the same as low disk space on the system, as applications can have a smaller quota.
+FOUNDATION_EXPORT NSNotificationName const NSBundleResourceRequestLowDiskSpaceNotification API_DEPRECATED("Use Background Assets instead.", ios(9.0, 27.0), watchos(2.0, 27.0), tvos(9.0, 27.0)) API_UNAVAILABLE(macos);
/* Use this value for the loadingPriority property if the user is doing nothing but waiting on the result of this request. The system will dedicate the maximum amount of resources available to finishing this request as soon as possible.
*/
-FOUNDATION_EXPORT double const NSBundleResourceRequestLoadingPriorityUrgent API_AVAILABLE(ios(9.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos);
+/// A priority that causes a resource request to load as soon as possible.
+FOUNDATION_EXPORT double const NSBundleResourceRequestLoadingPriorityUrgent API_DEPRECATED("Use Background Assets instead.", ios(9.0, 27.0), watchos(2.0, 27.0), tvos(9.0, 27.0)) API_UNAVAILABLE(macos);
#endif
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteCountFormatter.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteCountFormatter.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteCountFormatter.h 2026-04-18 21:51:11
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteCountFormatter.h 2026-05-27 00:45:54
@@ -7,96 +7,152 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
+/// Specifies the units appropriate for the formatter to display. Specifying any units explicitly causes just those units to be used in showing the number.
typedef NS_OPTIONS(NSUInteger, NSByteCountFormatterUnits) {
- // This causes default units appropriate for the platform to be used. Specifying any units explicitly causes just those units to be used in showing the number.
- NSByteCountFormatterUseDefault = 0,
- // Specifying any of the following causes the specified units to be used in showing the number.
- NSByteCountFormatterUseBytes = 1UL << 0,
+ /// This causes default units appropriate for the platform to be used. This is the default.
+ NSByteCountFormatterUseDefault = 0,
+ /// Displays bytes in the formatter content.
+ NSByteCountFormatterUseBytes = 1UL << 0,
+ /// Displays kilobytes in the formatter content.
NSByteCountFormatterUseKB = 1UL << 1,
+ /// Displays megabytes in the formatter content.
NSByteCountFormatterUseMB = 1UL << 2,
- NSByteCountFormatterUseGB = 1UL << 3,
- NSByteCountFormatterUseTB = 1UL << 4,
- NSByteCountFormatterUsePB = 1UL << 5,
- NSByteCountFormatterUseEB = 1UL << 6,
- NSByteCountFormatterUseZB = 1UL << 7,
- NSByteCountFormatterUseYBOrHigher = 0x0FFUL << 8,
- // Can use any unit in showing the number.
- NSByteCountFormatterUseAll = 0x0FFFFUL
+ /// Displays gigabytes in the formatter content.
+ NSByteCountFormatterUseGB = 1UL << 3,
+ /// Displays terabytes in the formatter content.
+ NSByteCountFormatterUseTB = 1UL << 4,
+ /// Displays petabytes in the formatter content.
+ NSByteCountFormatterUsePB = 1UL << 5,
+ /// Displays exabytes in the formatter content.
+ NSByteCountFormatterUseEB = 1UL << 6,
+ /// Displays zettabytes in the formatter content.
+ NSByteCountFormatterUseZB = 1UL << 7,
+ /// Displays yottabytes in the formatter content.
+ NSByteCountFormatterUseYBOrHigher = 0x0FFUL << 8,
+ /// Can use any unit in the formatter content.
+ NSByteCountFormatterUseAll = 0x0FFFFUL
};
+/// Specifies display of file or storage byte counts. The display style is platform specific.
typedef NS_ENUM(NSInteger, NSByteCountFormatterCountStyle) {
- // Specifies display of file or storage byte counts. The actual behavior for this is platform-specific; on OS X 10.8, this uses the decimal style, but that may change over time.
- NSByteCountFormatterCountStyleFile = 0,
- // Specifies display of memory byte counts. The actual behavior for this is platform-specific; on OS X 10.8, this uses the binary style, but that may change over time.
+ /// Specifies display of file byte counts. The actual behavior for this is platform-specific; in macOS 10.8, this uses the decimal style, but that may change over time.
+ NSByteCountFormatterCountStyleFile = 0,
+ /// Specifies display of memory byte counts. The actual behavior for this is platform-specific; in macOS 10.8, this uses the binary style, but that may change over time.
NSByteCountFormatterCountStyleMemory = 1,
- // The following two allow specifying the number of bytes for KB explicitly. It's better to use one of the above values in most cases.
- NSByteCountFormatterCountStyleDecimal = 2, // 1000 bytes are shown as 1 KB
- NSByteCountFormatterCountStyleBinary = 3 // 1024 bytes are shown as 1 KB
+ /// Causes 1000 bytes to be shown as 1 KB. It is better to use `NSByteCountFormatterCountStyleFile` or `NSByteCountFormatterCountStyleMemory` in most cases.
+ NSByteCountFormatterCountStyleDecimal = 2,
+ /// Causes 1024 bytes to be shown as 1 KB. It is better to use `NSByteCountFormatterCountStyleFile` or `NSByteCountFormatterCountStyleMemory` in most cases.
+ NSByteCountFormatterCountStyleBinary = 3
};
+/// A formatter that converts a byte count value into a localized description that is formatted with the appropriate byte modifier (KB, MB, GB and so on).
+///
+/// > Tip:
+/// > In Swift, you can use ``ByteCountFormatStyle`` or ``Measurement/FormatStyle/ByteCount`` rather than ``ByteCountFormatter``. The ``FormatStyle`` API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ``FormatStyle`` instances, so you don't need to pass them around your app, or risk wasting memory with duplicate formatters.
API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0))
@interface NSByteCountFormatter : NSFormatter
-/* Shortcut for converting a byte count into a string without creating an NSByteCountFormatter and an NSNumber. If you need to specify options other than countStyle, create an instance of NSByteCountFormatter first.
- */
+/// Converts a byte count into the specified string format without creating an `NSNumber` object.
+///
+/// If you need to specify options other than `countStyle`, create an instance of `NSByteCountFormatter` first.
+///
+/// @param byteCount The byte count.
+/// @param countStyle The formatter style. See `NSByteCountFormatterCountStyle` for possible values.
+/// @return A string containing the formatted `byteCount` value.
+ (NSString *)stringFromByteCount:(long long)byteCount countStyle:(NSByteCountFormatterCountStyle)countStyle;
-/* Convenience method on stringForObjectValue:. Convert a byte count into a string without creating an NSNumber.
- */
+/// Converts a byte count into a string without creating an `NSNumber` object.
+///
+/// This is a convenience method on `stringForObjectValue:`.
+///
+/// @param byteCount The byte count.
+/// @return A string containing the formatted `byteCount` value.
- (NSString *)stringFromByteCount:(long long)byteCount;
-/* Formats the value of the given measurement using the given `countStyle`.
-
- Throws an exception if the given measurement's unit does not belong to the `NSUnitInformationStorage` dimension.
- */
+/// Formats the value of the given measurement using the given `countStyle`.
+///
+/// Throws an exception if the given measurement's unit does not belong to the `NSUnitInformationStorage` dimension.
+ (NSString *)stringFromMeasurement:(NSMeasurement<NSUnitInformationStorage *> *)measurement countStyle:(NSByteCountFormatterCountStyle)countStyle API_AVAILABLE(macos(10.15), ios(13.0), tvos(13.0), watchos(6.0));
-/* Formats the value of the given measurement using the receiver's `countStyle`.
- Converts the measurement to the units allowed by the receiver's `allowedUnits` before formatting; depending on the value of the measurement, this may result in a string which implies an approximate value (e.g. if the measurement is too large to represent in `allowedUnits`, like `1e20 YB` expressed in `NSByteCountFormatterUseBytes`).
-
- Throws an exception if the given measurement's unit does not belong to the `NSUnitInformationStorage` dimension.
- */
+/// Formats the value of the given measurement using the receiver's `countStyle`.
+///
+/// Converts the measurement to the units allowed by the receiver's `allowedUnits` before formatting; depending on the value of the measurement, this may result in a string which implies an approximate value (e.g. if the measurement is too large to represent in `allowedUnits`, like `1e20 YB` expressed in `NSByteCountFormatterUseBytes`).
+///
+/// Throws an exception if the given measurement's unit does not belong to the `NSUnitInformationStorage` dimension.
- (NSString *)stringFromMeasurement:(NSMeasurement<NSUnitInformationStorage *> *)measurement API_AVAILABLE(macos(10.15), ios(13.0), tvos(13.0), watchos(6.0));
-/* Formats `obj` as a byte count (if `obj` is an `NSNumber`) or specific byte measurement (if `obj` is an `NSMeasurement`) using the receiver's settings.
-
- Returns `nil` if `obj` is not of the correct class (`NSNumber` or `NSMeasurement`).
- Throws an exception if `obj` is an `NSMeasurement` whose unit does not belong to the `NSUnitInformationStorage` dimension.
- */
+/// Formats `obj` as a byte count (if `obj` is an `NSNumber`) or specific byte measurement (if `obj` is an `NSMeasurement`) using the receiver's settings.
+///
+/// Returns `nil` if `obj` is not of the correct class (`NSNumber` or `NSMeasurement`).
+/// Throws an exception if `obj` is an `NSMeasurement` whose unit does not belong to the `NSUnitInformationStorage` dimension.
- (nullable NSString *)stringForObjectValue:(nullable id)obj;
-
-/* Specify the units that can be used in the output. If NSByteCountFormatterUseDefault, uses platform-appropriate settings; otherwise will only use the specified units. This is the default value. Note that ZB and YB cannot be covered by the range of possible values, but you can still choose to use these units to get fractional display ("0.0035 ZB" for instance).
- */
+
+/// Specify the units that can be used in the output.
+///
+/// If the value is `NSByteCountFormatterUseDefault`, the formatter uses platform-appropriate settings; otherwise only the specified units are used.
+///
+/// > Note: ZB and YB cannot be covered by the range of possible values, but you can still choose to use these units to get fractional display ("0.0035 ZB" for instance).
@property NSByteCountFormatterUnits allowedUnits;
-/* Specify how the count is displayed by indicating the number of bytes to be used for kilobyte. The default setting is NSByteCountFormatterFileCount, which is the system specific value for file and storage sizes.
- */
+/// Specify the number of bytes to be used for kilobytes.
+///
+/// The default setting is `NSByteCountFormatterCountStyleFile`, which is the system specific value for file and storage sizes.
@property NSByteCountFormatterCountStyle countStyle;
-/* Choose whether to allow more natural display of some values, such as zero, where it may be displayed as "Zero KB," ignoring all other flags or options (with the exception of NSByteCountFormatterUseBytes, which would generate "Zero bytes"). The result is appropriate for standalone output. Default value is YES. Special handling of certain values such as zero is especially important in some languages, so it's highly recommended that this property be left in its default state.
- */
+/// Determines whether to allow more natural display of some values.
+///
+/// Displays a more natural display of some values, such as zero, where it may be displayed as "Zero KB", ignoring all other flags or options (with the exception of `NSByteCountFormatterUseBytes`, which would generate "Zero bytes"). The result is appropriate for standalone output.
+///
+/// Special handling of certain values such as zero is especially important in some languages, so it's highly recommended that this property be left in its default state.
+///
+/// Default value is `YES`.
@property BOOL allowsNonnumericFormatting;
-/* Choose whether to include the number or the units in the resulting formatted string. (For example, instead of 723 KB, returns "723" or "KB".) You can call the API twice to get both parts, separately. But note that putting them together yourself via string concatenation may be wrong for some locales; so use this functionality with care. Both of these values are YES by default. Setting both to NO will unsurprisingly result in an empty string.
- */
+/// Determines whether to include the units in the resulting formatted string.
+///
+/// If set to `YES` and `includesCount` is set to `NO`, no count is displayed. For example, a value of 723 KB is formatted as "KB".
+///
+/// You can set this property and `includesCount` individually to get both parts, separately. Note that putting them together yourself via string concatenation may be incorrect for some locales.
+///
+/// The default value is `YES`.
@property BOOL includesUnit;
+
+/// Determines whether to include the count in the resulting formatted string.
+///
+/// If set to `YES` and `includesUnit` is set to `NO`, no unit is displayed. For example, a value of 723 KB is formatted as "723".
+///
+/// You can set this property and `includesUnit` individually to get both parts, separately. Note that putting them together yourself via string concatenation may be incorrect for some locales.
+///
+/// The default value is `YES`.
@property BOOL includesCount;
-/* Choose whether to parenthetically (localized as appropriate) display the actual number of bytes as well, for instance "723 KB (722,842 bytes)". This will happen only if needed, that is, the first part is already not showing the exact byte count. If includesUnit or includesCount are NO, then this setting has no effect. Default value is NO.
-*/
+/// Determines whether to include the number of bytes after the formatted string.
+///
+/// Setting this value to `YES` causes the byte count to be displayed parenthetically (localized as appropriate), for instance "723 KB (722,842 bytes)". This will happen only if needed, that is, the first part is already not showing the exact byte count.
+///
+/// If `includesUnit` or `includesCount` are `NO`, then this setting has no effect.
+///
+/// Default value is `NO`.
@property BOOL includesActualByteCount;
-/* Choose the display style. The "adaptive" algorithm is platform specific and uses a different number of fraction digits based on the magnitude (in 10.8: 0 fraction digits for bytes and KB; 1 fraction digits for MB; 2 for GB and above). Otherwise the result always tries to show at least three significant digits, introducing fraction digits as necessary. Default is YES.
- */
+/// Determines the display style of the size representation.
+///
+/// The "adaptive" algorithm is platform specific and uses a different number of fraction digits based on the magnitude (in OS X v10.8: 0 fraction digits for bytes and KB; 1 fraction digits for MB; 2 for GB and above). Otherwise the result always tries to show at least three significant digits, introducing fraction digits as necessary.
+///
+/// Default is `YES`.
@property (getter=isAdaptive) BOOL adaptive;
-/* Choose whether to zero pad fraction digits so a consistent number of fraction digits are displayed, causing updating displays to remain more stable. For instance, if the adaptive algorithm is used, this option formats 1.19 and 1.2 GB as "1.19 GB" and "1.20 GB" respectively, while without the option the latter would be displayed as "1.2 GB". Default value is NO.
-*/
+/// Determines whether to zero pad fraction digits so a consistent number of characters is displayed in a representation.
+///
+/// Displaying values using zero pad fraction digits causes a consistent number of fraction digits to be displayed, causing updating displays to remain more stable. For instance, if the adaptive algorithm is used, this option formats 1.19 and 1.2 GB as "1.19 GB" and "1.20 GB", respectively, while without the option the latter would be displayed as "1.2 GB".
+///
+/// Default value is `NO`.
@property BOOL zeroPadsFractionDigits;
-/* Specify the formatting context for the formatted string. Default is NSFormattingContextUnknown.
-*/
+/// Specify the formatting context for the formatted string.
+///
+/// The default value is `NSFormattingContextUnknown`.
@property NSFormattingContext formattingContext API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteOrder.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteOrder.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteOrder.h 2026-04-18 21:57:37
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteOrder.h 2026-05-27 01:09:58
@@ -7,24 +7,55 @@
NS_HEADER_AUDIT_BEGIN(sendability)
+/// Constants that indicate the byte order of the current architecture.
enum {
+ /// The byte order is unknown.
NS_UnknownByteOrder = CFByteOrderUnknown,
+ /// The byte order is little-endian.
NS_LittleEndian = CFByteOrderLittleEndian,
+ /// The byte order is big-endian.
NS_BigEndian = CFByteOrderBigEndian
};
+/// Returns the endian format.
+///
+/// - Returns: The endian format, either `NS_LittleEndian` or `NS_BigEndian`.
NS_INLINE long NSHostByteOrder(void) {
return CFByteOrderGetCurrent();
}
+/// Swaps the bytes of a number.
+///
+/// Swaps the low-order and high-order bytes of `inv` and returns the resulting value.
+///
+/// - Parameter inv: The value whose bytes you want to swap.
+/// - Returns: The byte-swapped value.
NS_INLINE unsigned short NSSwapShort(unsigned short inv) {
return CFSwapInt16(inv);
}
+/// Swaps the bytes of a number.
+///
+/// Swaps the bytes of `inv` and returns the resulting value. Bytes are swapped from each
+/// low-order position to the corresponding high-order position and vice versa. For example,
+/// if the bytes of `inv` are numbered from 1 to 4, this function swaps bytes 1 and 4, and
+/// bytes 2 and 3.
+///
+/// - Parameter inv: The value whose bytes you want to swap.
+/// - Returns: The byte-swapped value.
NS_INLINE unsigned int NSSwapInt(unsigned int inv) {
return CFSwapInt32(inv);
}
+/// Swaps the bytes of a number.
+///
+/// Swaps the bytes of `inv` and returns the resulting value. Bytes are swapped from each
+/// low-order position to the corresponding high-order position and vice versa. For example,
+/// if the bytes of `inv` are numbered from 1 to 4, this function swaps bytes 1 and 4, and
+/// bytes 2 and 3.
+///
+/// - Parameter inv: The value whose bytes you want to swap.
+/// - Returns: The byte-swapped value.
NS_INLINE unsigned long NSSwapLong(unsigned long inv) {
#if __LP64__
return CFSwapInt64(inv);
@@ -33,18 +64,51 @@
#endif
}
+/// Swaps the bytes of a number.
+///
+/// Swaps the bytes of `inv` and returns the resulting value. Bytes are swapped from each
+/// low-order position to the corresponding high-order position and vice versa. For example,
+/// if the bytes of `inv` are numbered from 1 to 8, this function swaps bytes 1 and 8, bytes
+/// 2 and 7, bytes 3 and 6, and bytes 4 and 5.
+///
+/// - Parameter inv: The value whose bytes you want to swap.
+/// - Returns: The byte-swapped value.
NS_INLINE unsigned long long NSSwapLongLong(unsigned long long inv) {
return CFSwapInt64(inv);
}
+/// Converts a big-endian `unsigned short` to the host's native byte order.
+///
+/// Converts the big-endian value in `x` to the current endian format and returns the
+/// resulting value. If it is necessary to swap the bytes of `x`, this function calls
+/// ``NSSwapShort(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned short NSSwapBigShortToHost(unsigned short x) {
return CFSwapInt16BigToHost(x);
}
+/// Converts a big-endian `unsigned int` to the host's native byte order.
+///
+/// Converts the big-endian value in `x` to the current endian format and returns the
+/// resulting value. If it is necessary to swap the bytes of `x`, this function calls
+/// ``NSSwapInt(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned int NSSwapBigIntToHost(unsigned int x) {
return CFSwapInt32BigToHost(x);
}
+/// Converts a big-endian `unsigned long` to the host's native byte order.
+///
+/// Converts the big-endian value in `x` to the current endian format and returns the
+/// resulting value. If it is necessary to swap the bytes of `x`, this function calls
+/// ``NSSwapLong(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned long NSSwapBigLongToHost(unsigned long x) {
#if __LP64__
return CFSwapInt64BigToHost(x);
@@ -53,18 +117,50 @@
#endif
}
+/// Converts a big-endian `unsigned long long` to the host's native byte order.
+///
+/// Converts the big-endian value in `x` to the current endian format and returns the
+/// resulting value. If it is necessary to swap the bytes of `x`, this function calls
+/// ``NSSwapLongLong(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned long long NSSwapBigLongLongToHost(unsigned long long x) {
return CFSwapInt64BigToHost(x);
}
+/// Converts an `unsigned short` from the host's native byte order to big-endian.
+///
+/// Converts the value in `x`, specified in the current endian format, to big-endian format
+/// and returns the resulting value. If it is necessary to swap the bytes, this function calls
+/// ``NSSwapShort(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned short NSSwapHostShortToBig(unsigned short x) {
return CFSwapInt16HostToBig(x);
}
+/// Converts an `unsigned int` from the host's native byte order to big-endian.
+///
+/// Converts the value in `x`, specified in the current endian format, to big-endian format
+/// and returns the resulting value. If it is necessary to swap the bytes, this function calls
+/// ``NSSwapInt(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned int NSSwapHostIntToBig(unsigned int x) {
return CFSwapInt32HostToBig(x);
}
+/// Converts an `unsigned long` from the host's native byte order to big-endian.
+///
+/// Converts the value in `x`, specified in the current endian format, to big-endian format
+/// and returns the resulting value. If it is necessary to swap the bytes, this function calls
+/// ``NSSwapLong(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned long NSSwapHostLongToBig(unsigned long x) {
#if __LP64__
return CFSwapInt64HostToBig(x);
@@ -73,18 +169,50 @@
#endif
}
+/// Converts an `unsigned long long` from the host's native byte order to big-endian.
+///
+/// Converts the value in `x`, specified in the current endian format, to big-endian format
+/// and returns the resulting value. If it is necessary to swap the bytes, this function calls
+/// ``NSSwapLongLong(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned long long NSSwapHostLongLongToBig(unsigned long long x) {
return CFSwapInt64HostToBig(x);
}
+/// Converts a little-endian `unsigned short` to the host's native byte order.
+///
+/// Converts the little-endian formatted value in `x` to the current endian format and
+/// returns the resulting value. If it is necessary to swap the bytes of `x`, this function
+/// calls ``NSSwapShort(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned short NSSwapLittleShortToHost(unsigned short x) {
return CFSwapInt16LittleToHost(x);
}
+/// Converts a little-endian `unsigned int` to the host's native byte order.
+///
+/// Converts the little-endian formatted value in `x` to the current endian format and
+/// returns the resulting value. If it is necessary to swap the bytes, this function calls
+/// ``NSSwapInt(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned int NSSwapLittleIntToHost(unsigned int x) {
return CFSwapInt32LittleToHost(x);
}
+/// Converts a little-endian `unsigned long` to the host's native byte order.
+///
+/// Converts the little-endian formatted value in `x` to the current endian format and
+/// returns the resulting value. If it is necessary to swap the bytes of `x`, this function
+/// calls ``NSSwapLong(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned long NSSwapLittleLongToHost(unsigned long x) {
#if __LP64__
return CFSwapInt64LittleToHost(x);
@@ -93,18 +221,50 @@
#endif
}
+/// Converts a little-endian `unsigned long long` to the host's native byte order.
+///
+/// Converts the little-endian formatted value in `x` to the current endian format and
+/// returns the resulting value. If it is necessary to swap the bytes, this function calls
+/// ``NSSwapLongLong(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned long long NSSwapLittleLongLongToHost(unsigned long long x) {
return CFSwapInt64LittleToHost(x);
}
+/// Converts an `unsigned short` from the host's native byte order to little-endian.
+///
+/// Converts the value in `x`, specified in the current endian format, to little-endian
+/// format and returns the resulting value. If it is necessary to swap the bytes, this
+/// function calls ``NSSwapShort(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned short NSSwapHostShortToLittle(unsigned short x) {
return CFSwapInt16HostToLittle(x);
}
+/// Converts an `unsigned int` from the host's native byte order to little-endian.
+///
+/// Converts the value in `x`, specified in the current endian format, to little-endian
+/// format and returns the resulting value. If it is necessary to swap the bytes, this
+/// function calls ``NSSwapInt(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned int NSSwapHostIntToLittle(unsigned int x) {
return CFSwapInt32HostToLittle(x);
}
+/// Converts an `unsigned long` from the host's native byte order to little-endian.
+///
+/// Converts the value in `x`, specified in the current endian format, to little-endian
+/// format and returns the resulting value. If it is necessary to swap the bytes, this
+/// function calls ``NSSwapLong(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned long NSSwapHostLongToLittle(unsigned long x) {
#if __LP64__
return CFSwapInt64HostToLittle(x);
@@ -113,14 +273,32 @@
#endif
}
+/// Converts an `unsigned long long` from the host's native byte order to little-endian.
+///
+/// Converts the value in `x`, specified in the current endian format, to little-endian
+/// format and returns the resulting value. If it is necessary to swap the bytes, this
+/// function calls ``NSSwapLongLong(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE unsigned long long NSSwapHostLongLongToLittle(unsigned long long x) {
return CFSwapInt64HostToLittle(x);
}
+/// A structure holding a swapped `float` value.
typedef struct NS_SWIFT_SENDABLE {unsigned int v;} NSSwappedFloat;
+/// A structure holding a swapped `double` value.
typedef struct NS_SWIFT_SENDABLE {unsigned long long v;} NSSwappedDouble;
+/// Performs a type conversion.
+///
+/// Converts the float value in `x` to a value whose bytes can be swapped. This function
+/// does not actually swap the bytes of `x`. You should not need to call this function
+/// directly.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE NSSwappedFloat NSConvertHostFloatToSwapped(float x) {
union fconv {
float number;
@@ -129,6 +307,13 @@
return ((union fconv *)&x)->sf;
}
+/// Performs a type conversion.
+///
+/// Converts the value in `x` to a float value. This function does not actually swap the
+/// bytes of `x`. You should not need to call this function directly.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE float NSConvertSwappedFloatToHost(NSSwappedFloat x) {
union fconv {
float number;
@@ -137,6 +322,14 @@
return ((union fconv *)&x)->number;
}
+/// Performs a type conversion.
+///
+/// Converts the double value in `x` to a value whose bytes can be swapped. This function
+/// does not actually swap the bytes of `x`. You should not need to call this function
+/// directly.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE NSSwappedDouble NSConvertHostDoubleToSwapped(double x) {
union dconv {
double number;
@@ -145,6 +338,13 @@
return ((union dconv *)&x)->sd;
}
+/// Performs a type conversion.
+///
+/// Converts the value in `x` to a double value. This function does not actually swap the
+/// bytes of `x`. You should not need to call this function directly.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE double NSConvertSwappedDoubleToHost(NSSwappedDouble x) {
union dconv {
double number;
@@ -153,11 +353,29 @@
return ((union dconv *)&x)->number;
}
+/// Swaps the bytes of a number.
+///
+/// Swaps the bytes of `x` and returns the resulting value. Bytes are swapped from each
+/// low-order position to the corresponding high-order position and vice versa. For example,
+/// if the bytes of `x` are numbered from 1 to 4, this function swaps bytes 1 and 4, and
+/// bytes 2 and 3.
+///
+/// - Parameter x: The value whose bytes you want to swap.
+/// - Returns: The byte-swapped value.
NS_INLINE NSSwappedFloat NSSwapFloat(NSSwappedFloat x) {
x.v = NSSwapInt(x.v);
return x;
}
+/// Swaps the bytes of a number.
+///
+/// Swaps the bytes of `x` and returns the resulting value. Bytes are swapped from each
+/// low-order position to the corresponding high-order position and vice versa. For example,
+/// if the bytes of `x` are numbered from 1 to 8, this function swaps bytes 1 and 8, bytes
+/// 2 and 7, bytes 3 and 6, and bytes 4 and 5.
+///
+/// - Parameter x: The value whose bytes you want to swap.
+/// - Returns: The byte-swapped value.
NS_INLINE NSSwappedDouble NSSwapDouble(NSSwappedDouble x) {
x.v = NSSwapLongLong(x.v);
return x;
@@ -165,68 +383,196 @@
#if defined(__BIG_ENDIAN__)
+/// Swaps the bytes of a number.
+///
+/// Converts the big-endian value in `x` to the current endian format and returns the
+/// resulting value. If it is necessary to swap the bytes of `x`, this function calls
+/// ``NSSwapDouble(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE double NSSwapBigDoubleToHost(NSSwappedDouble x) {
return NSConvertSwappedDoubleToHost(x);
}
+/// Swaps the bytes of a number.
+///
+/// Converts the big-endian value in `x` to the current endian format and returns the
+/// resulting value. If it is necessary to swap the bytes of `x`, this function calls
+/// ``NSSwapFloat(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE float NSSwapBigFloatToHost(NSSwappedFloat x) {
return NSConvertSwappedFloatToHost(x);
}
+/// Swaps the bytes of a number.
+///
+/// Converts the value in `x`, specified in the current endian format, to big-endian format
+/// and returns the resulting value. If it is necessary to swap the bytes, this function calls
+/// ``NSSwapDouble(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE NSSwappedDouble NSSwapHostDoubleToBig(double x) {
return NSConvertHostDoubleToSwapped(x);
}
+/// Swaps the bytes of a number.
+///
+/// Converts the value in `x`, specified in the current endian format, to big-endian format
+/// and returns the resulting value. If it is necessary to swap the bytes, this function calls
+/// ``NSSwapFloat(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE NSSwappedFloat NSSwapHostFloatToBig(float x) {
return NSConvertHostFloatToSwapped(x);
}
+/// Swaps the bytes of a number.
+///
+/// Converts the little-endian formatted value in `x` to the current endian format and
+/// returns the resulting value. If it is necessary to swap the bytes of `x`, this function
+/// calls ``NSSwapDouble(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE double NSSwapLittleDoubleToHost(NSSwappedDouble x) {
return NSConvertSwappedDoubleToHost(NSSwapDouble(x));
}
+/// Swaps the bytes of a number.
+///
+/// Converts the little-endian formatted value in `x` to the current endian format and
+/// returns the resulting value. If it is necessary to swap the bytes of `x`, this function
+/// calls ``NSSwapFloat(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE float NSSwapLittleFloatToHost(NSSwappedFloat x) {
return NSConvertSwappedFloatToHost(NSSwapFloat(x));
}
+/// Swaps the bytes of a number.
+///
+/// Converts the value in `x`, specified in the current endian format, to little-endian
+/// format and returns the resulting value. If it is necessary to swap the bytes, this
+/// function calls ``NSSwapDouble(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE NSSwappedDouble NSSwapHostDoubleToLittle(double x) {
return NSSwapDouble(NSConvertHostDoubleToSwapped(x));
}
+/// Swaps the bytes of a number.
+///
+/// Converts the value in `x`, specified in the current endian format, to little-endian
+/// format and returns the resulting value. If it is necessary to swap the bytes, this
+/// function calls ``NSSwapFloat(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE NSSwappedFloat NSSwapHostFloatToLittle(float x) {
return NSSwapFloat(NSConvertHostFloatToSwapped(x));
}
#elif defined(__LITTLE_ENDIAN__)
+/// Swaps the bytes of a number.
+///
+/// Converts the big-endian value in `x` to the current endian format and returns the
+/// resulting value. If it is necessary to swap the bytes of `x`, this function calls
+/// ``NSSwapDouble(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE double NSSwapBigDoubleToHost(NSSwappedDouble x) {
return NSConvertSwappedDoubleToHost(NSSwapDouble(x));
}
+/// Swaps the bytes of a number.
+///
+/// Converts the big-endian value in `x` to the current endian format and returns the
+/// resulting value. If it is necessary to swap the bytes of `x`, this function calls
+/// ``NSSwapFloat(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE float NSSwapBigFloatToHost(NSSwappedFloat x) {
return NSConvertSwappedFloatToHost(NSSwapFloat(x));
}
+/// Swaps the bytes of a number.
+///
+/// Converts the value in `x`, specified in the current endian format, to big-endian format
+/// and returns the resulting value. If it is necessary to swap the bytes, this function calls
+/// ``NSSwapDouble(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE NSSwappedDouble NSSwapHostDoubleToBig(double x) {
return NSSwapDouble(NSConvertHostDoubleToSwapped(x));
}
+/// Swaps the bytes of a number.
+///
+/// Converts the value in `x`, specified in the current endian format, to big-endian format
+/// and returns the resulting value. If it is necessary to swap the bytes, this function calls
+/// ``NSSwapFloat(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE NSSwappedFloat NSSwapHostFloatToBig(float x) {
return NSSwapFloat(NSConvertHostFloatToSwapped(x));
}
+/// Swaps the bytes of a number.
+///
+/// Converts the little-endian formatted value in `x` to the current endian format and
+/// returns the resulting value. If it is necessary to swap the bytes of `x`, this function
+/// calls ``NSSwapDouble(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE double NSSwapLittleDoubleToHost(NSSwappedDouble x) {
return NSConvertSwappedDoubleToHost(x);
}
+/// Swaps the bytes of a number.
+///
+/// Converts the little-endian formatted value in `x` to the current endian format and
+/// returns the resulting value. If it is necessary to swap the bytes of `x`, this function
+/// calls ``NSSwapFloat(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE float NSSwapLittleFloatToHost(NSSwappedFloat x) {
return NSConvertSwappedFloatToHost(x);
}
+/// Swaps the bytes of a number.
+///
+/// Converts the value in `x`, specified in the current endian format, to little-endian
+/// format and returns the resulting value. If it is necessary to swap the bytes, this
+/// function calls ``NSSwapDouble(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE NSSwappedDouble NSSwapHostDoubleToLittle(double x) {
return NSConvertHostDoubleToSwapped(x);
}
+/// Swaps the bytes of a number.
+///
+/// Converts the value in `x`, specified in the current endian format, to little-endian
+/// format and returns the resulting value. If it is necessary to swap the bytes, this
+/// function calls ``NSSwapFloat(_:)`` to perform the swap.
+///
+/// - Parameter x: The value you want to convert.
+/// - Returns: The converted value.
NS_INLINE NSSwappedFloat NSSwapHostFloatToLittle(float x) {
return NSConvertHostFloatToSwapped(x);
}
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCache.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCache.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCache.h 2026-04-18 22:35:15
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCache.h 2026-05-27 00:45:16
@@ -9,28 +9,88 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
+/// A mutable collection you use to temporarily store transient key-value pairs that are subject to eviction when resources are low.
+///
+/// Cache objects differ from other mutable collections in a few ways:
+///
+/// - The ``NSCache`` class incorporates various auto-eviction policies, which ensure that a cache doesn't use too much of the system's memory. If memory is needed by other applications, these policies remove some items from the cache, minimizing its memory footprint.
+/// - You can add, remove, and query items in the cache from different threads without having to lock the cache yourself.
+/// - Unlike an ``NSMutableDictionary`` object, a cache does not copy the key objects that are put into it.
+///
+/// You typically use ``NSCache`` objects to temporarily store objects with transient data that are expensive to create. Reusing these objects can provide performance benefits, because their values do not have to be recalculated. However, the objects are not critical to the application and can be discarded if memory is tight. If discarded, their values will have to be recomputed again when needed.
+///
+/// Objects that have subcomponents that can be discarded when not being used can adopt the ``NSDiscardableContent`` protocol to improve cache eviction behavior. By default, ``NSDiscardableContent`` objects in a cache are automatically removed if their content is discarded, although this automatic removal policy can be changed. If an ``NSDiscardableContent`` object is put into the cache, the cache calls ``NSDiscardableContent/discardContentIfPossible()`` on it upon its removal.
API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0))
@interface NSCache <KeyType, ObjectType> : NSObject
+/// The name of the cache.
+///
+/// The default value is an empty string ("").
@property (copy) NSString *name;
+/// The cache's delegate.
+///
+/// The delegate must adopt the `NSCacheDelegate` protocol.
@property (nullable, assign) id<NSCacheDelegate> delegate;
+/// Returns the value associated with a given key.
+///
+/// - Parameter key: An object identifying the value.
+/// - Returns: The value associated with `key`, or `nil` if no value is associated with `key`.
- (nullable ObjectType)objectForKey:(KeyType)key;
+/// Sets the value of the specified key in the cache.
+///
+/// Unlike an `NSMutableDictionary` object, a cache does not copy the key objects that are put into it.
+///
+/// - Parameter obj: The object to be stored in the cache.
+/// - Parameter key: The key with which to associate the value.
- (void)setObject:(ObjectType)obj forKey:(KeyType)key; // 0 cost
+/// Sets the value of the specified key in the cache, and associates the key-value pair with the specified cost.
+///
+/// The `cost` value is used to compute a sum encompassing the costs of all the objects in the cache. When memory is limited or when the total cost of the cache eclipses the maximum allowed total cost, the cache could begin an eviction process to remove some of its elements.
+///
+/// Unlike an `NSMutableDictionary` object, a cache does not copy the key objects that are put into it.
+///
+/// - Parameter obj: The object to store in the cache.
+/// - Parameter key: The key with which to associate the value.
+/// - Parameter g: The cost with which to associate the key-value pair.
- (void)setObject:(ObjectType)obj forKey:(KeyType)key cost:(NSUInteger)g;
+/// Removes the value of the specified key in the cache.
+///
+/// - Parameter key: The key identifying the value to be removed.
- (void)removeObjectForKey:(KeyType)key;
+/// Empties the cache.
- (void)removeAllObjects;
+/// The maximum total cost that the cache can hold before it starts evicting objects.
+///
+/// If `0`, there is no total cost limit. The default value is `0`.
+///
+/// This is not a strict limit, and if the cache goes over the limit, an object in the cache could be evicted instantly, at a later point in time, or possibly never, all depending on the implementation details of the cache.
@property NSUInteger totalCostLimit; // limits are imprecise/not strict
+/// The maximum number of objects the cache should hold.
+///
+/// If `0`, there is no count limit. The default value is `0`.
+///
+/// This is not a strict limit -- if the cache goes over the limit, an object in the cache could be evicted instantly, later, or possibly never, depending on the implementation details of the cache.
@property NSUInteger countLimit; // limits are imprecise/not strict
+/// Whether the cache will automatically evict discardable-content objects whose content has been discarded.
+///
+/// If `YES`, the cache will evict a discardable-content object after its content is discarded. If `NO`, it will not. The default value is `YES`.
@property BOOL evictsObjectsWithDiscardedContent;
@end
+/// The delegate of an ``NSCache`` object implements this protocol to perform specialized actions when an object is about to be evicted or removed from the cache.
@protocol NSCacheDelegate <NSObject>
@optional
+/// Called when an object is about to be evicted or removed from the cache.
+///
+/// It is not possible to modify `cache` from within the implementation of this delegate method.
+///
+/// - Parameter cache: The cache with which the object of interest is associated.
+/// - Parameter obj: The object of interest in the cache.
- (void)cache:(NSCache *)cache willEvictObject:(id)obj;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendar.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendar.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendar.h 2026-04-18 19:13:09
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendar.h 2026-05-27 00:02:55
@@ -24,25 +24,46 @@
#endif
#endif
+/// The supported calendar types.
+///
+/// Use these identifiers to specify the kind of calendar. The Gregorian calendar is the calendar typically used in Europe, the Western Hemisphere, and elsewhere.
typedef NSString * NSCalendarIdentifier NS_TYPED_EXTENSIBLE_ENUM;
+/// Identifier for the Gregorian calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierGregorian API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)); // the common calendar in Europe, the Western Hemisphere, and elsewhere
+/// Identifier for the Buddhist calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierBuddhist API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Chinese calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierChinese API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Coptic calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierCoptic API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Ethiopic Amete Mihret calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierEthiopicAmeteMihret API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Ethiopic Amete Alem calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierEthiopicAmeteAlem API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Hebrew calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierHebrew API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the ISO 8601 calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierISO8601 API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Indian calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierIndian API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Islamic calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierIslamic API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Islamic civil calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierIslamicCivil API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Japanese calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierJapanese API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Persian calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierPersian API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// Identifier for the Republic of China (Minguo) calendar.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierRepublicOfChina API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
-// A simple tabular Islamic calendar using the astronomical/Thursday epoch of CE 622 July 15
+/// Identifier for the Islamic tabular calendar.
+///
+/// A simple tabular Islamic calendar using the astronomical/Thursday epoch of CE 622 July 15.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierIslamicTabular API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));
-// The Islamic Umm al-Qura calendar used in Saudi Arabia. This is based on astronomical calculation, instead of tabular behavior.
+/// Identifier for the Islamic Umm al-Qura calendar.
+///
+/// The Islamic Umm al-Qura calendar used in Saudi Arabia. This is based on astronomical calculation, instead of tabular behavior.
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierIslamicUmmAlQura API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierBangla API_AVAILABLE(macos(26.0), ios(26.0), watchos(26.0), tvos(26.0), visionos(26.0));
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierGujarati API_AVAILABLE(macos(26.0), ios(26.0), watchos(26.0), tvos(26.0), visionos(26.0));
@@ -56,158 +77,361 @@
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierDangi API_AVAILABLE(macos(26.0), ios(26.0), watchos(26.0), tvos(26.0), visionos(26.0));
FOUNDATION_EXPORT NSCalendarIdentifier const NSCalendarIdentifierVietnamese API_AVAILABLE(macos(26.0), ios(26.0), watchos(26.0), tvos(26.0), visionos(26.0));
+/// Calendrical units such as year, month, day and hour.
typedef NS_OPTIONS(NSUInteger, NSCalendarUnit) {
+ /// Identifier for the era unit.
+ ///
+ /// The corresponding value is an `NSInteger`.
NSCalendarUnitEra = kCFCalendarUnitEra,
+ /// Identifier for the year unit.
+ ///
+ /// The corresponding value is an `NSInteger`.
NSCalendarUnitYear = kCFCalendarUnitYear,
+ /// Identifier for the month unit.
+ ///
+ /// The corresponding value is an `NSInteger`.
NSCalendarUnitMonth = kCFCalendarUnitMonth,
+ /// Identifier for the day unit.
+ ///
+ /// The corresponding value is an `NSInteger`.
NSCalendarUnitDay = kCFCalendarUnitDay,
+ /// Identifier for the hour unit.
+ ///
+ /// The corresponding value is an `NSInteger`.
NSCalendarUnitHour = kCFCalendarUnitHour,
+ /// Identifier for the minute unit.
+ ///
+ /// The corresponding value is an `NSInteger`.
NSCalendarUnitMinute = kCFCalendarUnitMinute,
+ /// Identifier for the second unit.
+ ///
+ /// The corresponding value is a `double`.
NSCalendarUnitSecond = kCFCalendarUnitSecond,
+ /// Identifier for the weekday unit.
+ ///
+ /// The corresponding value is an `NSInteger`. The weekday units are the numbers `1` through `N` (where for the Gregorian calendar `N`=`7` and `1` is Sunday).
NSCalendarUnitWeekday = kCFCalendarUnitWeekday,
+ /// Identifier for the ordinal weekday unit.
+ ///
+ /// The corresponding value is an `NSInteger`. The weekday ordinal unit describes ordinal position within the month unit of the corresponding weekday unit. For example, in the Gregorian calendar a weekday ordinal unit of `2` for a weekday unit `3` indicates "the second Tuesday in the month".
NSCalendarUnitWeekdayOrdinal = kCFCalendarUnitWeekdayOrdinal,
+ /// Identifier for the quarter of the calendar.
+ ///
+ /// The corresponding value is an `NSInteger`.
+ ///
+ /// > Important: The `NSCalendarUnitQuarter` unit is largely unimplemented, and is not recommended for use.
NSCalendarUnitQuarter API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = kCFCalendarUnitQuarter,
+ /// Identifier for the week of the month calendar unit.
NSCalendarUnitWeekOfMonth API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) = kCFCalendarUnitWeekOfMonth,
+ /// Identifier for the week of the year calendar unit.
NSCalendarUnitWeekOfYear API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) = kCFCalendarUnitWeekOfYear,
+ /// Identifier for the week-counting year unit.
NSCalendarUnitYearForWeekOfYear API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) = kCFCalendarUnitYearForWeekOfYear,
+ /// Identifier for the nanosecond unit.
NSCalendarUnitNanosecond API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) = (1 << 15),
NSCalendarUnitDayOfYear API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0)) = kCFCalendarUnitDayOfYear,
+ /// Identifier for the calendar of a date components object.
+ ///
+ /// The corresponding value is an `NSCalendar`.
NSCalendarUnitCalendar API_AVAILABLE(macos(10.7), ios(4.0), watchos(2.0), tvos(9.0)) = (1 << 20),
+ /// Identifier for the time zone of a date components object.
+ ///
+ /// The corresponding value is an `NSTimeZone`.
NSCalendarUnitTimeZone API_AVAILABLE(macos(10.7), ios(4.0), watchos(2.0), tvos(9.0)) = (1 << 21),
NSCalendarUnitIsLeapMonth API_AVAILABLE(macos(26.0), ios(26.0), watchos(26.0), tvos(26.0), visionos(26.0)) = (1 << 30),
NSCalendarUnitIsRepeatedDay API_AVAILABLE(macos(26.0), ios(26.0), watchos(26.0), tvos(26.0), visionos(26.0)) = (1UL << 31),
#if !0
+ /// Specifies the era unit.
+ /// @deprecated Use `NSCalendarUnitEra` instead.
NSEraCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitEra", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitEra,
+ /// Specifies the year unit.
+ /// @deprecated Use `NSCalendarUnitYear` instead.
NSYearCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitYear", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitYear,
+ /// Specifies the month unit.
+ /// @deprecated Use `NSCalendarUnitMonth` instead.
NSMonthCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitMonth", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitMonth,
+ /// Specifies the day unit.
+ /// @deprecated Use `NSCalendarUnitDay` instead.
NSDayCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitDay", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitDay,
+ /// Specifies the hour unit.
+ /// @deprecated Use `NSCalendarUnitHour` instead.
NSHourCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitHour", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitHour,
+ /// Specifies the minute unit.
+ /// @deprecated Use `NSCalendarUnitMinute` instead.
NSMinuteCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitMinute", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitMinute,
+ /// Specifies the second unit.
+ /// @deprecated Use `NSCalendarUnitSecond` instead.
NSSecondCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitSecond", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitSecond,
+ /// Specifies the week unit.
+ ///
+ /// Equal to `kCFCalendarUnitWeek`.
+ /// @deprecated Use `NSCalendarUnitWeekOfMonth` or `NSCalendarUnitWeekOfYear` instead.
NSWeekCalendarUnit API_DEPRECATED("NSCalendarUnitWeekOfMonth or NSCalendarUnitWeekOfYear, depending on which you mean", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = kCFCalendarUnitWeek,
+ /// Specifies the weekday unit.
+ /// @deprecated Use `NSCalendarUnitWeekday` instead.
NSWeekdayCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitWeekday", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitWeekday,
+ /// Specifies the ordinal weekday unit.
+ ///
+ /// The weekday ordinal unit describes the ordinal position within the month of the corresponding weekday unit. For example, in the Gregorian calendar a weekday ordinal of 2 for a weekday of 3 indicates "the second Tuesday in the month". Equal to `kCFCalendarUnitWeekdayOrdinal`.
+ /// @deprecated Use `NSCalendarUnitWeekdayOrdinal` instead.
NSWeekdayOrdinalCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitWeekdayOrdinal", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitWeekdayOrdinal,
+ /// Specifies the quarter unit.
+ /// @deprecated Use `NSCalendarUnitQuarter` instead.
NSQuarterCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitQuarter", macos(10.6, 10.10), ios(4.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitQuarter,
+ /// Specifies the week of the month calendar unit.
+ /// @deprecated Use `NSCalendarUnitWeekOfMonth` instead.
NSWeekOfMonthCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitWeekOfMonth", macos(10.7, 10.10), ios(5.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitWeekOfMonth,
+ /// Specifies the week of the year calendar unit.
+ /// @deprecated Use `NSCalendarUnitWeekOfYear` instead.
NSWeekOfYearCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitWeekOfYear", macos(10.7, 10.10), ios(5.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitWeekOfYear,
+ /// Specifies the year when the calendar is being interpreted as a week-based calendar.
+ /// @deprecated Use `NSCalendarUnitYearForWeekOfYear` instead.
NSYearForWeekOfYearCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitYearForWeekOfYear", macos(10.7, 10.10), ios(5.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitYearForWeekOfYear,
+ /// Specifies the calendar of the calendar.
+ /// @deprecated Use `NSCalendarUnitCalendar` instead.
NSCalendarCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitCalendar", macos(10.7, 10.10), ios(4.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitCalendar,
+ /// Specifies the time zone of the calendar as an `NSTimeZone`.
+ /// @deprecated Use `NSCalendarUnitTimeZone` instead.
NSTimeZoneCalendarUnit API_DEPRECATED_WITH_REPLACEMENT("NSCalendarUnitTimeZone", macos(10.7, 10.10), ios(4.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarUnitTimeZone,
#endif
};
+/// The options for arithmetic operations involving calendars.
typedef NS_OPTIONS(NSUInteger, NSCalendarOptions) {
- NSCalendarWrapComponents = (1UL << 0), // option for arithmetic operations that do calendar addition
+ /// Specifies that the components specified for an `NSDateComponents` object should be incremented and wrap around to zero/one on overflow, but should not cause higher units to be incremented.
+ NSCalendarWrapComponents = (1UL << 0),
+ /// Specifies that the operation should travel as far forward or backward as necessary looking for a match.
NSCalendarMatchStrictly API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = (1ULL << 1),
+ /// Specifies that the operation should travel backwards to find the previous match before the given date.
NSCalendarSearchBackwards API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = (1ULL << 2),
-
+
+ /// Specifies that, when there is no matching time before the end of the next instance of the next highest unit specified in the given `NSDateComponents` object, this method uses the previous existing value of the missing unit and preserves the lower units' values.
NSCalendarMatchPreviousTimePreservingSmallerUnits API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = (1ULL << 8),
+ /// Specifies that, when there is no matching time before the end of the next instance of the next highest unit specified in the given `NSDateComponents` object, this method uses the next existing value of the missing unit and preserves the lower units' values.
NSCalendarMatchNextTimePreservingSmallerUnits API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = (1ULL << 9),
+ /// Specifies that, when there is no matching time before the end of the next instance of the next highest unit specified in the given `NSDateComponents` object, this method uses the next existing value of the missing unit and does not preserve the lower units' values.
NSCalendarMatchNextTime API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = (1ULL << 10),
-
+
+ /// Specifies that, if there are two or more matching times, the operation should return the first occurrence.
NSCalendarMatchFirst API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = (1ULL << 12),
+ /// Specifies that, if there are two or more matching times, the operation should return the last occurrence.
NSCalendarMatchLast API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0)) = (1ULL << 13)
};
enum {
+ /// Specifies that the components specified for an `NSDateComponents` object should be incremented and wrap around to zero/one on overflow, but should not cause higher units to be incremented.
+ ///
+ /// @deprecated Use `NSCalendarWrapComponents` instead.
NSWrapCalendarComponents API_DEPRECATED_WITH_REPLACEMENT("NSCalendarWrapComponents", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSCalendarWrapComponents,
};
+/// A definition of the relationships between calendar units and absolute points in time, providing features for calculation and comparison of dates.
+///
+/// In Swift, this object bridges to ``Calendar``; use ``NSCalendar`` when you need reference semantics or other Foundation-specific behavior.
+///
+/// ``NSCalendar`` objects encapsulate information about systems of reckoning time in which the beginning, length, and divisions of a year are defined. They provide information about the calendar and support for calendrical computations such as determining the range of a given calendrical unit and adding units to a given absolute time.
+///
+/// ``NSCalendar`` is _toll-free bridged_ with its Core Foundation counterpart, <doc://com.apple.documentation/documentation/corefoundation/cfcalendar>. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging.
+///
+/// > Important:
+/// > The Swift overlay to the Foundation framework provides the ``Calendar`` structure, which bridges to the ``NSCalendar`` class. For more information about value types, see <doc://com.apple.documentation/documentation/swift/working-with-foundation-types>.
+///
+/// ### Locales and Calendars
+///
+/// Most locales use the most widely used civil calendar, called the _Gregorian calendar_ (``Identifier/gregorian``), but there remain exceptions to this trend. For example:
+///
+/// - In Saudi Arabia, some locales use primarily the Islamic Umm al-Qura calendar (``Identifier/islamicUmmAlQura``).
+/// - In Ethiopia, some locales use primarily the Ethiopian calendar (``Identifier/ethiopicAmeteMihret`` or ``Identifier/ethiopicAmeteAlem``).
+/// - In Iran and Afghanistan, some locales use primarily the Persian calendar (``Identifier/persian``).
+/// - In Thailand, some locales use primarily the Buddhist calendar (``Identifier/buddhist``).
+///
+/// Other locales use another calendar alongside the Gregorian calendar. For example:
+///
+/// - India also uses the Indian national calendar (``Identifier/indian``).
+/// - Israel also uses the Hebrew calendar (``Identifier/hebrew``).
+/// - China mainland and other regions also use the Chinese calendar (``Identifier/chinese``), primarily to calculate astronomical date and Chinese traditional holidays.
+/// - Japan also uses the Japanese calendar (``Identifier/japanese``), primarily to add year names.
+///
+/// Independent of any particular locale, certain calendars are used primarily to calculate dates for religious observances. Among these are the Buddhist (``Identifier/buddhist``), Coptic (``Identifier/coptic``), Hebrew (``Identifier/hebrew``), and Islamic (``Identifier/islamic``) calendars.
+///
+/// ### How NSCalendar Models the Gregorian Calendar
+///
+/// The Gregorian calendar was first introduced in 1582, as a replacement for the Julian Calendar. According to the Julian calendar, a leap day is added to February for any year with a number divisible by 4, which results in an annual disparity of 11 minutes, or 1 day every 128 years. The Gregorian calendar revised the rules for leap day calculation, by skipping the leap day for any year with a number divisible by 100, unless that year number is also divisible by 400, resulting in an annual disparity of only 26 seconds, or 1 day every 3323 years.
+///
+/// To transition from the Julian calendar to the Gregorian calendar, 10 days were dropped from the Gregorian calendar (October 5–14).
+///
+/// After the Gregorian calendar was introduced, many regions continued to use the Julian calendar, with Turkey being the last country or region to adopt the Gregorian calendar, in 1926. As a result of the staggered adoption, the transition period for regions at the time of adoption have different start dates and a different number of skipped days to account for the additional disparity from leap day calculations.
+///
+/// ``NSCalendar`` models the behavior of a _proleptic_ Gregorian calendar (_as defined by ISO 8601:2004_), which extends the Gregorian calendar backward in time from the date of its introduction. This behavior should be taken into account when working with dates created before the transition period of the affected locales.
+///
+/// ### Calendar Arithmetic
+///
+/// To do calendar arithmetic, you use ``NSDate`` objects in conjunction with a calendar. For example, to convert between a decomposed date in one calendar and another calendar, you must first convert the decomposed elements into a date using the first calendar, then decompose it using the second. ``NSDate`` provides the absolute scale and epoch (reference point) for dates and times, which can then be rendered into a particular calendar, for calendrical computations or user display.
+///
+/// Two ``NSCalendar`` methods that return a date object, ``date(from:)``, ``date(byAdding:to:options:)``, take as a parameter an ``NSDateComponents`` object that describes the calendrical components required for the computation. You can provide as many components as you need (or choose to). When there is incomplete information to compute an absolute time, default values similar to `0` and `1` are usually chosen by a calendar, but this is a calendar-specific choice. If you provide inconsistent information, calendar-specific disambiguation is performed (which may involve ignoring one or more of the parameters). Related methods (``components(_:from:)`` and ``components(_:from:to:options:)-84y5w``) take a bit mask parameter that specifies which components to calculate when returning an ``NSDateComponents`` object. The bit mask is composed of ``Unit`` constants (see `Constants`).
+///
+/// In a calendar, day, week, weekday, month, and year numbers are generally 1-based, but there may be calendar-specific exceptions. Ordinal numbers, where they occur, are 1-based. Some calendars represented by this API may have to map their basic unit concepts into year/month/week/day/… nomenclature. For example, a calendar composed of 4 quarters in a year instead of 12 months uses the month unit to represent quarters. The particular values of the unit are defined by each calendar, and are not necessarily consistent with values for that unit in another calendar.
@interface NSCalendar : NSObject <NSCopying, NSSecureCoding>
-@property (class, readonly, copy) NSCalendar *currentCalendar; // user's preferred calendar
-@property (class, readonly, strong) NSCalendar *autoupdatingCurrentCalendar API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)); // tracks changes to user's preferred calendar identifier
+/// The user's current calendar.
+///
+/// The returned calendar is formed from the settings for the current user's chosen system locale overlaid with any custom settings the user has specified in System Preferences. Settings you get from this calendar do not change as System Preferences are changed.
+@property (class, readonly, copy) NSCalendar *currentCalendar;
-/*
- This method returns a new autoreleased calendar object of the given type, specified by a calendar identifier constant.
- The calendar defaults to having the current locale and default time zone, for those properties.
-*/
+/// A calendar that tracks changes to user's preferred calendar.
+///
+/// Settings you get from this calendar do change as the user's settings change. Note that if you cache values based on the calendar or related information those caches will of course not be automatically updated by the updating of the calendar object.
+@property (class, readonly, strong) NSCalendar *autoupdatingCurrentCalendar API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0));
+
+/// Creates a new calendar specified by a given identifier.
+///
+/// - Parameters:
+/// - calendarIdentifierConstant: The identifier for the new calendar. For valid identifiers, see `Calendar Identifiers`.
+/// - Returns: The initialized calendar, or `nil` if the identifier is unknown (if, for example, it is either an unrecognized string or the calendar is not supported by the current version of the operating system).
+///
+/// The returned calendar defaults to the current locale and default time zone.
+ (nullable NSCalendar *)calendarWithIdentifier:(NSCalendarIdentifier)calendarIdentifierConstant API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
- (instancetype)init NS_UNAVAILABLE;
+/// Initializes a calendar according to a given identifier.
+///
+/// - Parameters:
+/// - ident: The identifier for the new calendar. For valid identifiers, see `Calendar Identifiers`.
+/// - Returns: The initialized calendar, or `nil` if the identifier is unknown (if, for example, it is either an unrecognized string or the calendar is not supported by the current version of the operating system).
- (nullable id)initWithCalendarIdentifier:(NSCalendarIdentifier)ident NS_DESIGNATED_INITIALIZER;
+/// An identifier for the calendar.
@property (readonly, copy) NSCalendarIdentifier calendarIdentifier;
+
+/// The locale for the calendar.
@property (nullable, copy) NSLocale *locale;
+
+/// The time zone for the calendar.
@property (copy) NSTimeZone *timeZone;
+
+/// The index of the first weekday for the calendar.
@property NSUInteger firstWeekday;
+
+/// The minimum number of days in the first week of the calendar.
@property NSUInteger minimumDaysInFirstWeek;
// Methods to return component name strings localized to the calendar's locale
+/// A list of era symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *eraSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The long era symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *longEraSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of month symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *monthSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of short month symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *shortMonthSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of very short month symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *veryShortMonthSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of standalone month symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *standaloneMonthSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of short standalone month symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *shortStandaloneMonthSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of very short standalone month symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *veryShortStandaloneMonthSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of weekday symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *weekdaySymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of short weekday symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *shortWeekdaySymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of very short weekday symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *veryShortWeekdaySymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of standalone weekday symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *standaloneWeekdaySymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of short standalone weekday symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *shortStandaloneWeekdaySymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of very short standalone weekday symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *veryShortStandaloneWeekdaySymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of quarter symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *quarterSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of short quarter symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *shortQuarterSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of standalone quarter symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *standaloneQuarterSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The list of short standalone quarter symbols for this calendar.
@property (readonly, copy) NSArray<NSString *> *shortStandaloneQuarterSymbols API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The AM symbol for this calendar.
@property (readonly, copy) NSString *AMSymbol API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The PM symbol for this calendar.
@property (readonly, copy) NSString *PMSymbol API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
// Calendrical calculations
+/// The minimum range limits of the values that a given unit can take on.
- (NSRange)minimumRangeOfUnit:(NSCalendarUnit)unit;
+
+/// The maximum range limits of the values that a given unit can take on.
- (NSRange)maximumRangeOfUnit:(NSCalendarUnit)unit;
+/// The range of absolute time values that a smaller calendar unit can take on in a larger calendar unit for a specified absolute time.
- (NSRange)rangeOfUnit:(NSCalendarUnit)smaller inUnit:(NSCalendarUnit)larger forDate:(NSDate *)date;
+
+/// The ordinal number of a smaller calendar unit within a specified larger calendar unit for a specified absolute time.
- (NSUInteger)ordinalityOfUnit:(NSCalendarUnit)smaller inUnit:(NSCalendarUnit)larger forDate:(NSDate *)date;
+/// The starting time and duration of a given calendar unit that contains a given date.
- (BOOL)rangeOfUnit:(NSCalendarUnit)unit startDate:(NSDate * _Nullable * _Nullable)datep interval:(nullable NSTimeInterval *)tip forDate:(NSDate *)date API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0));
+/// A date created from the specified components.
- (nullable NSDate *)dateFromComponents:(NSDateComponents *)comps;
+
+/// The date components representing a given date.
- (NSDateComponents *)components:(NSCalendarUnit)unitFlags fromDate:(NSDate *)date;
+/// A date representing the absolute time calculated by adding given components to a given date.
- (nullable NSDate *)dateByAddingComponents:(NSDateComponents *)comps toDate:(NSDate *)date options:(NSCalendarOptions)opts;
+/// Returns the difference between two supplied dates as date components.
+///
+/// The result is lossy if there is not a small enough unit requested to hold the full precision of the difference. Some operations can be ambiguous, and the behavior of the computation is calendar-specific, but generally larger components will be computed before smaller components; for example, in the Gregorian calendar a result might be 1 month and 5 days instead of, for example, 0 months and 35 days. The resulting component values may be negative if `resultDate` is before `startDate`.
+///
+/// Note that some computations can take a relatively long time.
+///
+/// - Parameters:
+/// - unitFlags: Specifies the components for the returned `NSDateComponents` object.
+/// - startingDate: The start date for the calculation.
+/// - resultDate: The end date for the calculation.
+/// - opts: Options for the calculation. If you specify ``NSCalendar/Options/wrapComponents``, the specified components are incremented and wrap around to zero/one on overflow, but do not cause higher units to be incremented.
+/// - Returns: An `NSDateComponents` object whose components are specified by `unitFlags` and calculated from the difference between the `resultDate` and `startDate`. Returns `nil` if either date falls outside the defined range of the receiver or if the computation cannot be performed.
- (NSDateComponents *)components:(NSCalendarUnit)unitFlags fromDate:(NSDate *)startingDate toDate:(NSDate *)resultDate options:(NSCalendarOptions)opts;
-/*
- This API is a convenience for getting era, year, month, and day of a given date.
- Pass NULL for a NSInteger pointer parameter if you don't care about that value.
-*/
+/// Returns the era, year, month, and day of a given date.
+///
+/// Pass `NULL` for a `NSInteger` pointer parameter if you don't care about that value.
- (void)getEra:(out nullable NSInteger *)eraValuePointer year:(out nullable NSInteger *)yearValuePointer month:(out nullable NSInteger *)monthValuePointer day:(out nullable NSInteger *)dayValuePointer fromDate:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
-/*
- This API is a convenience for getting era, year for week-of-year calculations, week of year, and weekday of a given date.
- Pass NULL for a NSInteger pointer parameter if you don't care about that value.
-*/
+/// Returns the era, year for week-of-year calculations, week of year, and weekday of a given date.
+///
+/// Pass `NULL` for a `NSInteger` pointer parameter if you don't care about that value.
- (void)getEra:(out nullable NSInteger *)eraValuePointer yearForWeekOfYear:(out nullable NSInteger *)yearValuePointer weekOfYear:(out nullable NSInteger *)weekValuePointer weekday:(out nullable NSInteger *)weekdayValuePointer fromDate:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
-/*
- This API is a convenience for getting hour, minute, second, and nanoseconds of a given date.
- Pass NULL for a NSInteger pointer parameter if you don't care about that value.
-*/
+/// Returns the hour, minute, second, and nanoseconds of a given date.
+///
+/// Pass `NULL` for a `NSInteger` pointer parameter if you don't care about that value.
- (void)getHour:(out nullable NSInteger *)hourValuePointer minute:(out nullable NSInteger *)minuteValuePointer second:(out nullable NSInteger *)secondValuePointer nanosecond:(out nullable NSInteger *)nanosecondValuePointer fromDate:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns the value for one component of a date.
/*
Get just one component's value.
*/
- (NSInteger)component:(NSCalendarUnit)unit fromDate:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Creates a date with given components. Current era is assumed.
/*
Create a date with given components.
Current era is assumed.
@@ -215,6 +439,7 @@
- (nullable NSDate *)dateWithEra:(NSInteger)eraValue year:(NSInteger)yearValue month:(NSInteger)monthValue day:(NSInteger)dayValue hour:(NSInteger)hourValue minute:(NSInteger)minuteValue second:(NSInteger)secondValue nanosecond:(NSInteger)nanosecondValue API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Creates a date with given week-of-year-based components. Current era is assumed.
/*
Create a date with given components.
Current era is assumed.
@@ -222,6 +447,10 @@
- (nullable NSDate *)dateWithEra:(NSInteger)eraValue yearForWeekOfYear:(NSInteger)yearValue weekOfYear:(NSInteger)weekValue weekday:(NSInteger)weekdayValue hour:(NSInteger)hourValue minute:(NSInteger)minuteValue second:(NSInteger)secondValue nanosecond:(NSInteger)nanosecondValue API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns the first moment date of a given date.
+///
+/// Pass in `[NSDate date]`, for example, if you want the start of "today".
+/// If there were two midnights, it returns the first. If there was none, it returns the first moment that did exist.
/*
This API returns the first moment date of a given date.
Pass in [NSDate date], for example, if you want the start of "today".
@@ -230,6 +459,9 @@
- (NSDate *)startOfDayForDate:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns all the date components of a date, as if in a given time zone (instead of the receiving calendar's time zone).
+///
+/// The time zone overrides the time zone of the `NSCalendar` for the purposes of this calculation.
/*
This API returns all the date components of a date, as if in a given time zone (instead of the receiving calendar's time zone).
The time zone overrides the time zone of the NSCalendar for the purposes of this calculation.
@@ -238,82 +470,104 @@
- (NSDateComponents *)componentsInTimeZone:(NSTimeZone *)timezone fromDate:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Compares the given dates down to the given unit, reporting them equal if they are the same in the given unit and all larger units, otherwise either less than or greater than.
/*
This API compares the given dates down to the given unit, reporting them equal if they are the same in the given unit and all larger units, otherwise either less than or greater than.
*/
- (NSComparisonResult)compareDate:(NSDate *)date1 toDate:(NSDate *)date2 toUnitGranularity:(NSCalendarUnit)unit API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns whether the given dates are equal down to the given unit, reporting them equal if they are the same in the given unit and all larger units.
/*
This API compares the given dates down to the given unit, reporting them equal if they are the same in the given unit and all larger units.
*/
- (BOOL)isDate:(NSDate *)date1 equalToDate:(NSDate *)date2 toUnitGranularity:(NSCalendarUnit)unit API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns whether the given dates are in the same day.
/*
This API compares the Days of the given dates, reporting them equal if they are in the same Day.
*/
- (BOOL)isDate:(NSDate *)date1 inSameDayAsDate:(NSDate *)date2 API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns whether the given date is within "today".
/*
This API reports if the date is within "today".
*/
- (BOOL)isDateInToday:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns whether the given date is within "yesterday".
/*
This API reports if the date is within "yesterday".
*/
- (BOOL)isDateInYesterday:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns whether the given date is within "tomorrow".
/*
This API reports if the date is within "tomorrow".
*/
- (BOOL)isDateInTomorrow:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns whether the given date is within a weekend period, as defined by the calendar and calendar's locale.
/*
This API reports if the date is within a weekend period, as defined by the calendar and calendar's locale.
*/
- (BOOL)isDateInWeekend:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
-/*
- Find the range of the weekend around the given date, returned via two by-reference parameters.
- Returns NO if the given date is not in a weekend.
- Note that a given entire Day within a calendar is not necessarily all in a weekend or not; weekends can start in the middle of a Day in some calendars and locales.
-*/
+/// Returns whether a given date falls within a weekend period, and if so, returns by reference the start date and time interval of the weekend range.
+///
+/// Note that a particular calendar day may not necessarily fall entirely within a weekend period, as weekends can start in the middle of a day in some calendars and locales.
+///
+/// - Parameters:
+/// - datep: Upon return, contains the starting date of the weekend period.
+/// - tip: Upon return, contains the time interval of the weekend period.
+/// - date: The date to use to perform the calculation.
+/// - Returns: `YES` if the given date falls within a weekend period, otherwise `NO`.
- (BOOL)rangeOfWeekendStartDate:(out NSDate * _Nullable * _Nullable)datep interval:(out nullable NSTimeInterval *)tip containingDate:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
-/*
- Returns the range of the next weekend, via two by-reference parameters, which starts strictly after the given date.
- The NSCalendarSearchBackwards option can be used to find the previous weekend range strictly before the date.
- Returns NO if there are no such things as weekend in the calendar and its locale.
- Note that a given entire Day within a calendar is not necessarily all in a weekend or not; weekends can start in the middle of a Day in some calendars and locales.
-*/
+/// Returns by reference the starting date and time interval range of the next weekend period after a given date.
+///
+/// Note that a particular calendar day may not necessarily fall entirely within a weekend period, as weekends can start in the middle of a day in some calendars and locales.
+///
+/// The `NSCalendarSearchBackwards` option can be used to find the previous weekend range strictly before the date. Returns `NO` if there are no such things as weekends in the calendar and its locale.
+///
+/// - Parameters:
+/// - datep: Upon return, contains the starting date of the next weekend period.
+/// - tip: Upon return, contains the time interval of the next weekend period.
+/// - options: Options for the calculation. If you specify ``NSCalendar/Options/searchBackwards``, the starting date and time interval range of the preceding weekend period will be returned by reference instead.
+/// - date: The date for which to perform the calculation.
+/// - Returns: `NO` if the calendar and locale do not have the concept of a weekend, otherwise `YES`.
- (BOOL)nextWeekendStartDate:(out NSDate * _Nullable * _Nullable)datep interval:(out nullable NSTimeInterval *)tip options:(NSCalendarOptions)options afterDate:(NSDate *)date API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
-/*
- This API returns the difference between two dates specified as date components.
- For units which are not specified in each NSDateComponents, but required to specify an absolute date, the base value of the unit is assumed. For example, for an NSDateComponents with just a Year and a Month specified, a Day of 1, and an Hour, Minute, Second, and Nanosecond of 0 are assumed.
- Calendrical calculations with unspecified Year or Year value prior to the start of a calendar are not advised.
- For each date components object, if its time zone property is set, that time zone is used for it; if the calendar property is set, that is used rather than the receiving calendar, and if both the calendar and time zone are set, the time zone property value overrides the time zone of the calendar property.
- No options are currently defined; pass 0.
-*/
+/// Returns the difference between start and end dates given as date components.
+///
+/// If an `NSDateComponents` object does not specify a value for a calendar unit required to determine an absolute date, the base value of that unit is assumed. For example, given an `NSDateComponents` object with only a `year` and a `month` specified, the resulting `NSDate` object would be constructed using a `day` value of `1` and `hour`, `minute`, `second` and `nanosecond` values of `0`. Passing an `NSDateComponents` argument with an unspecified `era` or `year` value is not advised.
+///
+/// If an `NSDateComponents` object's `timeZone` property is set, the time zone property value will be used in the calculation. If an `NSDateComponents` object's `calendar` property is set, the calendar property value will be used instead of the receiving calendar. If both an `NSDateComponents` object's `timeZone` and `calendar` properties are set, the time zone property value overrides the time zone of the calendar property value.
+///
+/// - Parameters:
+/// - unitFlags: Specifies the components for the returned `NSDateComponents` object.
+/// - startingDateComp: The start date for the calculation as an `NSDateComponents` object.
+/// - resultDateComp: The end date for the calculation as an `NSDateComponents` object.
+/// - options: The options parameter is currently unused.
+/// - Returns: An `NSDateComponents` object whose components are specified by `unitFlags` and calculated from the difference between the `startingDateComp` and `resultDateComp`. Returns `nil` if either date falls outside the defined range of the receiver or if the computation cannot be performed.
- (NSDateComponents *)components:(NSCalendarUnit)unitFlags fromDateComponents:(NSDateComponents *)startingDateComp toDateComponents:(NSDateComponents *)resultDateComp options:(NSCalendarOptions)options API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns a new date representing the date calculated by adding an amount of a specific component to a given date.
/*
This API returns a new NSDate object representing the date calculated by adding an amount of a specific component to a given date.
The NSCalendarWrapComponents option specifies if the component should be incremented and wrap around to zero/one on overflow, and should not cause higher units to be incremented.
*/
- (nullable NSDate *)dateByAddingUnit:(NSCalendarUnit)unit value:(NSInteger)value toDate:(NSDate *)date options:(NSCalendarOptions)options API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
-
/*
This method computes the dates which match (or most closely match) a given set of components, and calls the block once for each of them, until the enumeration is stopped.
There will be at least one intervening date which does not match all the components (or the given date itself must not match) between the given date and any result.
@@ -336,8 +590,20 @@
Result dates have an integer number of seconds (as if 0 was specified for the nanoseconds property of the NSDateComponents matching parameter), unless a value was set in the nanoseconds property, in which case the result date will have that number of nanoseconds (or as close as possible with floating point numbers).
The enumeration is stopped by setting *stop = YES in the block and return. It is not necessary to set *stop to NO to keep the enumeration going.
*/
+/// Computes the dates that match (or most closely match) a given set of components, and calls the block once for each of them, until the enumeration is stopped.
+///
+/// If you specify a strict matching option (``NSCalendar/Options/matchStrictly``), this method searches as far as necessary looking for a match, up to an implementation-defined limit. If an exact match is not possible, `nil` is passed to the `date` argument of the block, and the enumeration is stopped. Otherwise, this method searches as far as the next instance of the next highest calendar unit in the given `NSDateComponents` object.
+///
+/// If you do not specify a strict matching option, you must specify one of ``NSCalendar/Options/matchPreviousTimePreservingSmallerUnits``, ``NSCalendar/Options/matchNextTimePreservingSmallerUnits``, or ``NSCalendar/Options/matchNextTime``, or an illegal argument exception will be thrown.
+///
+/// - Parameters:
+/// - start: The date for which to perform the calculation.
+/// - comps: The date components to match. If no components are specified, the enumeration will not be executed.
+/// - opts: Options for the enumeration. For possible values, see ``NSCalendar/Options``.
+/// - block: The block to apply to each enumerated date. The block takes three arguments: the enumerated date, whether the date exactly matches the specified date components, and a reference to a Boolean value that the block can set to `YES` to stop the enumeration.
- (void)enumerateDatesStartingAfterDate:(NSDate *)start matchingComponents:(NSDateComponents *)comps options:(NSCalendarOptions)opts usingBlock:(void (NS_NOESCAPE ^)(NSDate * _Nullable date, BOOL exactMatch, BOOL *stop))block API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Computes the next date which matches (or most closely matches) a given set of components.
/*
This method computes the next date which matches (or most closely matches) a given set of components.
The general semantics follow those of the -enumerateDatesStartingAfterDate:... method above.
@@ -346,6 +612,7 @@
- (nullable NSDate *)nextDateAfterDate:(NSDate *)date matchingComponents:(NSDateComponents *)comps options:(NSCalendarOptions)options API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns a new date representing the date found which matches a specific component value.
/*
This API returns a new NSDate object representing the date found which matches a specific component value.
The general semantics follow those of the -enumerateDatesStartingAfterDate:... method above.
@@ -354,6 +621,7 @@
- (nullable NSDate *)nextDateAfterDate:(NSDate *)date matchingUnit:(NSCalendarUnit)unit value:(NSInteger)value options:(NSCalendarOptions)options API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns a new date representing the date found which matches the given hour, minute, and second values.
/*
This API returns a new NSDate object representing the date found which matches the given hour, minute, and second values.
The general semantics follow those of the -enumerateDatesStartingAfterDate:... method above.
@@ -361,16 +629,28 @@
*/
- (nullable NSDate *)nextDateAfterDate:(NSDate *)date matchingHour:(NSInteger)hourValue minute:(NSInteger)minuteValue second:(NSInteger)secondValue options:(NSCalendarOptions)options API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
-
/*
This API returns a new NSDate object representing the date calculated by setting a specific component to a given time, and trying to keep lower components the same. If the unit already has that value, this may result in a date which is the same as the given date.
Changing a component's value often will require higher or coupled components to change as well. For example, setting the Weekday to Thursday usually will require the Day component to change its value, and possibly the Month and Year as well.
If no such time exists, the next available time is returned (which could, for example, be in a different day, week, month, ... than the nominal target date). Setting a component to something which would be inconsistent forces other units to change; for example, setting the Weekday to Thursday probably shifts the Day and possibly Month and Year.
The specific behaviors here are as yet unspecified; for example, if I change the weekday to Thursday, does that move forward to the next, backward to the previous, or to the nearest Thursday? A likely rule is that the algorithm will try to produce a result which is in the next-larger unit to the one given (there's a table of this mapping at the top of this document). So for the "set to Thursday" example, find the Thursday in the Week in which the given date resides (which could be a forwards or backwards move, and not necessarily the nearest Thursday). For forwards or backwards behavior, one can use the -nextDateAfterDate:matchingUnit:value:options: method above.
*/
+/// Returns a new date representing the date calculated by setting a specific component of a given date to a given value, while trying to keep lower components the same.
+///
+/// Changing a component's value often requires higher or coupled components to change as well. For example, setting the `weekday` to "Thursday" will require the `day` component to change its value, and possibly the `month` and `year` as well. If no such time exists, the next available date is returned, which may be on a different calendar day.
+///
+/// - Parameters:
+/// - unit: The unit to set with the given value. For possible values, see ``NSCalendar/Unit``.
+/// - v: The value to set for the given calendar unit.
+/// - date: The date to use to perform the calculation.
+/// - opts: Options for the calculation. For possible values, see ``NSCalendar/Options``.
+/// - Returns: A new `NSDate` instance representing the date calculated by setting a specific component of a given date to a given value. If the unit already has that value, this may result in a date which is the same as the given date.
- (nullable NSDate *)dateBySettingUnit:(NSCalendarUnit)unit value:(NSInteger)v ofDate:(NSDate *)date options:(NSCalendarOptions)opts API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns a new date representing the date calculated by setting hour, minute, and second to a given time.
+///
+/// If no such time exists, the next available time is returned (which could be in a different day than the nominal target date). The intent is to return a date on the same day as the original date argument.
/*
This API returns a new NSDate object representing the date calculated by setting hour, minute, and second to a given time.
If no such time exists, the next available time is returned (which could, for example, be in a different day than the nominal target date).
@@ -379,6 +659,7 @@
- (nullable NSDate *)dateBySettingHour:(NSInteger)h minute:(NSInteger)m second:(NSInteger)s ofDate:(NSDate *)date options:(NSCalendarOptions)opts API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns `YES` if the date has all the matched components. Otherwise, it returns `NO`.
/*
This API returns YES if the date has all the matched components. Otherwise, it returns NO.
It is useful to test the return value of the -nextDateAfterDate:matchingUnit:value:options:, to find out if the components were obeyed or if the method had to fudge the result value due to missing time.
@@ -398,6 +679,9 @@
// notification is received by observers in a "timely" manner, same as
// with distributed notifications.
+/// A notification posted whenever the calendar day of the system changes, as determined by the system calendar, locale, and time zone.
+///
+/// If the device is asleep when the day changes, this notification will be posted on wakeup. Only one notification will be posted on wakeup if the device has been asleep for multiple days. There are no guarantees about the timeliness of when this notification will be received by observers.
FOUNDATION_EXPORT NSNotificationName const NSCalendarDayChangedNotification API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
@@ -420,39 +704,114 @@
// or quantities of the units.
// When you create a new one of these, all values begin Undefined.
+/// Constants that denote that the value of a date component is undefined.
NS_ENUM(NSInteger) {
+ /// Specifies a date component without a value.
NSDateComponentUndefined = NSIntegerMax,
+ /// Specifies a date component without a value.
+ ///
+ /// @deprecated Use `NSDateComponentUndefined` instead.
NSUndefinedDateComponent API_DEPRECATED_WITH_REPLACEMENT("NSDateComponentUndefined", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0)) = NSDateComponentUndefined
};
+/// An object that specifies a date or time in terms of units (such as year, month, day, hour, and minute) to be evaluated in a calendar system and time zone.
+///
+/// In Swift, this object bridges to ``DateComponents``; use ``NSDateComponents`` when you need reference semantics or other Foundation-specific behavior.
+///
+/// ``NSDateComponents`` encapsulates the components of a date in an extendable, object-oriented manner. It's used to specify a date by providing the temporal components that make up a date and time: hour, minutes, seconds, day, month, year, and so on. You can also use it to specify a duration of time, for example, 5 hours and 16 minutes. An ``NSDateComponents`` object is not required to define all the component fields. When a new instance of ``NSDateComponents`` is created, the date components are set to ``NSDateComponentUndefined``.
+///
+/// > Important:
+/// > An ``NSDateComponents`` object is meaningless in itself; you need to know what calendar it is interpreted against, and you need to know whether the values are absolute values of the units, or quantities of the units.
+///
+/// An instance of ``NSDateComponents`` is not responsible for answering questions about a date beyond the information with which it was initialized. For example, if you initialize one with May 4, 2017, its weekday is ``NSDateComponentUndefined``, not Thursday. To get the correct day of the week, you must create a suitable instance of ``NSCalendar``, create an ``NSDate`` object using ``NSCalendar/date(from:)`` and then use ``NSCalendar/components(_:from:)`` to retrieve the weekday—as illustrated in the following example.
+///
+/// @TabNavigator {
+/// @Tab("Swift") {
+/// ```swift
+/// let dateComponents = NSDateComponents()
+/// dateComponents.day = 4
+/// dateComponents.month = 5
+/// dateComponents.year = 2017
+///
+/// if let gregorianCalendar = NSCalendar(calendarIdentifier: .gregorian),
+/// let date = gregorianCalendar.date(from: dateComponents as DateComponents) {
+/// let weekday = gregorianCalendar.component(.weekday, from: date)
+/// print(weekday) // 5, which corresponds to Thursday in the Gregorian Calendar
+/// }
+///
+/// ```
+/// }
+/// @Tab("Objective-C") {
+/// ```objc
+/// NSDateComponents *dateComponents = [[NSDateComponents alloc] init];
+/// dateComponents.day = 4;
+/// dateComponents.month = 5;
+/// dateComponents.year = 2017;
+///
+/// NSCalendar *gregorianCalendar = [[NSCalendar alloc] initWithCalendarIdentifier:NSCalendarIdentifierGregorian];
+/// NSDate *date = [gregorianCalendar dateFromComponents:dateComponents];
+///
+/// NSInteger weekday = [gregorianCalendar component:NSCalendarUnitWeekday fromDate:date];
+/// NSLog(@"%d", weekday); // 5, which corresponds to Thursday in the Gregorian Calendar
+/// ```
+/// }
+/// }
+///
+///
+/// For more details, see [Calendars, Date Components, and Calendar Units](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DatesAndTimes/Articles/dtCalendars.html#//apple_ref/doc/uid/TP40003470) in [Date and Time Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DatesAndTimes/DatesAndTimes.html#//apple_ref/doc/uid/10000039i).
+///
+/// > Important:
+/// > The Swift overlay to the Foundation framework provides the ``DateComponents`` structure, which bridges to the ``NSDateComponents`` class. For more information about value types, see <doc://com.apple.documentation/documentation/swift/working-with-foundation-types>.
@interface NSDateComponents : NSObject <NSCopying, NSSecureCoding>
+/// The calendar used to interpret the date components.
@property (nullable, copy) NSCalendar *calendar API_AVAILABLE(macos(10.7), ios(4.0), watchos(2.0), tvos(9.0));
+/// The time zone used to interpret the date components.
@property (nullable, copy) NSTimeZone *timeZone API_AVAILABLE(macos(10.7), ios(4.0), watchos(2.0), tvos(9.0));
+/// The number of eras.
@property NSInteger era;
+/// The number of years.
@property NSInteger year;
+/// The number of months.
@property NSInteger month;
+/// The number of days.
@property NSInteger day;
+/// The number of hour units for the receiver.
@property NSInteger hour;
+/// The number of minute units for the receiver.
@property NSInteger minute;
+/// The number of second units for the receiver.
@property NSInteger second;
+/// The number of nanosecond units for the receiver.
@property NSInteger nanosecond API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The number of the weekdays.
@property NSInteger weekday;
+/// The ordinal number of weekdays.
@property NSInteger weekdayOrdinal;
+/// The number of quarters.
@property NSInteger quarter API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// The week number of the months.
@property NSInteger weekOfMonth API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The ISO 8601 week date of the year.
@property NSInteger weekOfYear API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The ISO 8601 week-numbering year.
@property NSInteger yearForWeekOfYear API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
+/// The day of the year value of the date components.
@property NSInteger dayOfYear API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
+/// A Boolean value that indicates whether the month is a leap month.
@property (getter=isLeapMonth) BOOL leapMonth API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0));
@property (getter=isRepeatedDay) BOOL repeatedDay API_AVAILABLE(macos(26.0), ios(26.0), watchos(26.0), tvos(26.0), visionos(26.0));
+/// The date calculated from the current components using the stored calendar.
@property (nullable, readonly, copy) NSDate *date API_AVAILABLE(macos(10.7), ios(4.0), watchos(2.0), tvos(9.0));
- (NSInteger)week API_DEPRECATED("Use -weekOfMonth or -weekOfYear, depending on which you mean", macos(10.4, 10.9), ios(2.0, 7.0), watchos(2.0, 2.0), tvos(9.0, 9.0));
- (void)setWeek:(NSInteger)v API_DEPRECATED("Use -setWeekOfMonth: or -setWeekOfYear:, depending on which you mean", macos(10.4, 10.9), ios(2.0, 7.0), watchos(2.0, 2.0), tvos(9.0, 9.0));
+/// Sets a value for a given calendar unit.
+///
+/// The calendar and timeZone and isLeapMonth properties cannot be set by this method.
/*
This API allows one to set a specific component of NSDateComponents, by enum constant value rather than property name.
The calendar and timeZone and isLeapMonth properties cannot be set by this method.
@@ -460,6 +819,9 @@
- (void)setValue:(NSInteger)value forComponent:(NSCalendarUnit)unit API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns the value for a given calendar unit.
+///
+/// The calendar and timeZone and isLeapMonth property values cannot be retrieved by this method.
/*
This API allows one to get the value of a specific component of NSDateComponents, by enum constant value rather than property name.
The calendar and timeZone and isLeapMonth property values cannot be retrieved by this method.
@@ -467,6 +829,9 @@
- (NSInteger)valueForComponent:(NSCalendarUnit)unit API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// A Boolean value that indicates whether the current combination of properties represents a date which exists in the current calendar.
+///
+/// This method is not appropriate for use on `NSDateComponents` objects which are specifying relative quantities of calendar components. The calendar property must be set, or `NO` is returned.
/*
Reports whether or not the combination of properties which have been set in the receiver is a date which exists in the calendar.
This method is not appropriate for use on NSDateComponents objects which are specifying relative quantities of calendar components.
@@ -477,6 +842,9 @@
@property (getter=isValidDate, readonly) BOOL validDate API_AVAILABLE(macos(10.9), ios(8.0), watchos(2.0), tvos(9.0));
+/// Returns a Boolean value that indicates whether the current combination of properties represents a date which exists in the specified calendar.
+///
+/// This method is not appropriate for use on `NSDateComponents` objects which are specifying relative quantities of calendar components.
/*
Reports whether or not the combination of properties which have been set in the receiver is a date which exists in the calendar.
This method is not appropriate for use on NSDateComponents objects which are specifying relative quantities of calendar components.
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendarDate.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendarDate.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendarDate.h 2026-04-18 22:35:15
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendarDate.h 2026-05-22 05:23:48
@@ -20,6 +20,11 @@
#endif
#endif
+/// A specialized date object with embedded calendar information.
+///
+/// @DeprecationSummary {
+/// Use ``NSDate`` and ``NSCalendar`` instead.
+/// }
API_DEPRECATED("Use NSCalendar and NSDateComponents and NSDateFormatter instead", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0))
NS_SWIFT_UNAVAILABLE("Use NSCalendar and NSDateComponents and NSDateFormatter instead")
@interface NSCalendarDate : NSDate {
@@ -72,11 +77,63 @@
* Use NSCalendar for calendrical calculations.
* Use NSDateFormatter for date<->string conversions.
*/
+/// Creates and returns a date object set to the date and time specified by a given string.
+///
+/// This method supports only a limited set of colloquial phrases, primarily in English. It may give unexpected results, and its use is strongly discouraged. To create a date object from a string, you should use a date formatter object instead (see ``DateFormatter`` and [Data Formatting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DataFormatting/DataFormatting.html#//apple_ref/doc/uid/10000029i)).
+///
+/// The keys and values that represent the locale data from `locale` are used when parsing the string. In addition to the locale keys listed in the class description, these keys are used when parsing natural language strings:
+///
+/// - NSDateTimeOrdering
+/// - NSEarlierTimeDesignations
+/// - NSHourNameDesignations
+/// - NSLaterTimeDesignations
+/// - NSNextDayDesignations
+/// - NSNextNextDayDesignations
+/// - NSPriorDayDesignations
+/// - NSThisDayDesignations
+/// - NSYearMonthWeekDesignations
+///
+/// - Parameters:
+/// - string: A string that contains a colloquial specification of a date, such as "last Tuesday at dinner," "3pm December 31, 2001," "12/31/01," or "31/12/01."
+/// - locale: An `NSDictionary` object containing locale data. To use the user's preferences, you can use `[[NSUserDefaults standardUserDefaults] dictionaryRepresentation]`. If you pass `nil` or an instance of `NSLocale`, `NSDate` uses the system default locale---this is not the same as the current user's locale.
+/// - Returns: A new `NSDate` object set to the date and time specified by `string` as interpreted according to `locale`.
+ (nullable id)dateWithNaturalLanguageString:(NSString *)string locale:(nullable id)locale API_DEPRECATED("Create an NSDateFormatter with `init` and set the dateFormat property instead.", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0));
+/// Creates and returns a date object set to the date and time specified by a given string.
+///
+/// This method supports only a limited set of colloquial phrases, primarily in English. It may give unexpected results, and its use is strongly discouraged. To create a date object from a string, you should use a date formatter object instead (see ``DateFormatter`` and [Data Formatting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DataFormatting/DataFormatting.html#//apple_ref/doc/uid/10000029i)).
+///
+/// In parsing the string, this method uses the date and time preferences stored in the user's defaults database. (See ``NSDate/date(withNaturalLanguageString:locale:)`` for a list of the specific items used.)
+///
+/// - Parameter string: A string that contains a colloquial specification of a date, such as "last Tuesday at dinner," "3pm December 31, 2001," "12/31/01," or "31/12/01."
+/// - Returns: A new `NSDate` object set to the current date and time specified by `string`.
+ (nullable id)dateWithNaturalLanguageString:(NSString *)string API_DEPRECATED("Create an NSDateFormatter with `init` and set the dateFormat property instead.", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0));
+/// Creates and returns a date object with a date and time value specified by a given string in the international string representation format (`YYYY-MM-DD HH:MM:SS ±HHMM`).
+///
+/// To create a date object from a string, you should typically use a date formatter object instead (see ``DateFormatter`` and [Data Formatting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DataFormatting/DataFormatting.html#//apple_ref/doc/uid/10000029i)).
+///
+/// - Parameter aString: A string that specifies a date and time value in the international string representation format---`YYYY-MM-DD HH:MM:SS ±HHMM`, where `±HHMM` is a time zone offset in hours and minutes from UTC (for example, "`2001-03-24 10:45:32 +0600`"). You must specify all fields of the format string, including the time zone offset, which must have a plus or minus sign prefix.
+/// - Returns: An `NSDate` object with a date and time value specified by `aString`.
+ (id)dateWithString:(NSString *)aString API_DEPRECATED("Use NSDateFormatter instead", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0));
+/// Converts the receiver to a calendar date with a given format string and time zone.
+///
+/// @DeprecationSummary {
+/// Use `NSDate` methods to set the individual date values.
+/// }
+///
+/// - Parameters:
+/// - format: The format for the returned string. Pass `nil` to use the default format string, `"%Y-%m-%d %H:%M:%S %z"`.
+/// - aTimeZone: The time zone for the new calendar date. Pass `nil` to use the default time zone.
+/// - Returns: A new `NSCalendarDate` object bound to `format` and the time zone `aTimeZone`.
- (NSCalendarDate *)dateWithCalendarFormat:(nullable NSString *)format timeZone:(nullable NSTimeZone *)aTimeZone API_DEPRECATED("", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0));
+/// Returns a string representation of the date formatted as specified by given conversion specifiers.
- (nullable NSString *)descriptionWithCalendarFormat:(nullable NSString *)format timeZone:(nullable NSTimeZone *)aTimeZone locale:(nullable id)locale API_DEPRECATED("", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0));
+/// Returns a date object initialized with a date and time value specified by a given string in the international string representation format.
+///
+/// - Parameters:
+/// - description: A string that specifies a date and time value in the international string representation format---`YYYY-MM-DD HH:MM:SS ±HHMM`,
+/// where `±HHMM` is a time zone offset in hours and minutes from UTC (for example, "`2001-03-24 10:45:32 +0600`").
+/// You must specify all fields of the format string, including the time zone offset, which must have a plus or minus sign prefix.
+/// - Returns: An `NSDate` object initialized with a date and time value specified by `description`.
- (nullable id)initWithString:(NSString *)description API_DEPRECATED("Use NSDateFormatter instead", macos(10.4, 10.10), ios(2.0, 8.0), watchos(2.0, 2.0), tvos(9.0, 9.0));
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCharacterSet.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCharacterSet.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCharacterSet.h 2026-04-18 22:35:15
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCharacterSet.h 2026-05-27 00:11:56
@@ -11,75 +11,309 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
+/// Specifies the lower bound for a Unicode character range reserved for Apple's corporate use (the range is `0xF400`–`0xF8FF`).
enum {
NSOpenStepUnicodeReservedBase = 0xF400
};
+/// An object representing a fixed set of Unicode character values for use in search operations.
+///
+/// In Swift, this bridges to a ``CharacterSet``; use ``NSCharacterSet`` when you need reference semantics or other Foundation-specific behavior.
+///
+/// An `NSCharacterSet` object represents a set of Unicode-compliant characters. `NSString` and `NSScanner` objects use `NSCharacterSet` objects to group characters together for searching operations, so that they can find any of a particular set of characters during a search. The cluster's two public classes, `NSCharacterSet` and ``NSMutableCharacterSet``, declare the programmatic interface for static and dynamic character sets, respectively.
+///
+/// The objects you create using these classes are referred to as character set objects (and when no confusion will result, merely as character sets). Because of the nature of class clusters, character set objects aren't actual instances of the `NSCharacterSet` or `NSMutableCharacterSet` classes but of one of their private subclasses. Although a character set object's class is private, its interface is public, as declared by these abstract superclasses, `NSCharacterSet` and `NSMutableCharacterSet`. The character set classes adopt the `NSCopying` and `NSMutableCopying` protocols, making it convenient to convert a character set of one type to the other.
+///
+/// The `NSCharacterSet` class declares the programmatic interface for an object that manages a set of Unicode characters (see the ``NSString`` class cluster specification for information on Unicode). `NSCharacterSet`'s principal primitive method, ``characterIsMember(_:)``, provides the basis for all other instance methods in its interface. A subclass of `NSCharacterSet` needs only to implement this method, plus ``NSMutableCopying/mutableCopy(with:)``, for proper behavior. For optimal performance, a subclass should also override ``bitmapRepresentation``, which otherwise works by invoking ``characterIsMember(_:)`` for every possible Unicode value.
+///
+/// `NSCharacterSet` is "toll-free bridged" with its Core Foundation counterpart, <doc://com.apple.documentation/documentation/corefoundation/cfcharacterset>. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging.
+///
+/// > Important:
+/// > The Swift overlay to the Foundation framework provides the ``CharacterSet`` structure, which bridges to the ``NSCharacterSet`` class and its mutable subclass, ``NSMutableCharacterSet``. For more information about value types, see <doc://com.apple.documentation/documentation/swift/working-with-foundation-types>.
@interface NSCharacterSet : NSObject <NSCopying, NSMutableCopying, NSSecureCoding>
+/// A character set containing the characters in Unicode General Category Cc and Cf.
+///
+/// These characters include, for example, the soft hyphen (`U+00AD`), control characters to support bi-directional text, and IETF language tag characters.
@property (readonly, class, copy) NSCharacterSet *controlCharacterSet;
+
+/// A character set containing the characters in Unicode General Category Zs and `CHARACTER TABULATION` (`U+0009`).
+///
+/// This set doesn't contain the newline or carriage return characters.
@property (readonly, class, copy) NSCharacterSet *whitespaceCharacterSet;
+
+/// A character set containing characters in Unicode General Category Z\*, `U+000A` ~ `U+000D`, and `U+0085`.
@property (readonly, class, copy) NSCharacterSet *whitespaceAndNewlineCharacterSet;
+
+/// A character set containing the characters in the category of Decimal Numbers.
+///
+/// Informally, this set is the set of all characters used to represent the decimal values `0` through `9`. These characters include, for example, the decimal digits of the Indic scripts and Arabic.
@property (readonly, class, copy) NSCharacterSet *decimalDigitCharacterSet;
+
+/// A character set containing the characters in Unicode General Category L\* & M\*.
+///
+/// Informally, this set is the set of all characters used as letters of alphabets and ideographs.
@property (readonly, class, copy) NSCharacterSet *letterCharacterSet;
+
+/// A character set containing the characters in Unicode General Category Ll.
+///
+/// Informally, this set is the set of all characters used as lowercase letters in alphabets that make case distinctions.
@property (readonly, class, copy) NSCharacterSet *lowercaseLetterCharacterSet;
+
+/// A character set containing the characters in Unicode General Category Lu and Lt.
+///
+/// Informally, this set is the set of all characters used as uppercase letters in alphabets that make case distinctions.
@property (readonly, class, copy) NSCharacterSet *uppercaseLetterCharacterSet;
+
+/// A character set containing the characters in Unicode General Category M\*.
+///
+/// This set is also defined as all legal Unicode characters with a non-spacing priority greater than `0`. Informally, this set is the set of all characters used as modifiers of base characters.
@property (readonly, class, copy) NSCharacterSet *nonBaseCharacterSet;
+
+/// A character set containing the characters in Unicode General Categories L\*, M\*, and N\*.
+///
+/// Informally, this set is the set of all characters used as basic units of alphabets, syllabaries, ideographs, and digits.
@property (readonly, class, copy) NSCharacterSet *alphanumericCharacterSet;
+
+/// A character set containing individual Unicode characters that can also be represented as composed character sequences (such as for letters with accents), by the definition of "standard decomposition" in version 3.2 of the Unicode character encoding standard.
+///
+/// These characters include compatibility characters as well as pre-composed characters.
+///
+/// > Note: This character set doesn't currently include the Hangul characters defined in version 2.0 of the Unicode standard.
@property (readonly, class, copy) NSCharacterSet *decomposableCharacterSet;
+
+/// A character set containing values in the category of Non-Characters or that have not yet been defined in version 3.2 of the Unicode standard.
@property (readonly, class, copy) NSCharacterSet *illegalCharacterSet;
+
+/// A character set containing the characters in Unicode General Category P\*.
+///
+/// Informally, this set is the set of all non-whitespace characters used to separate linguistic units in scripts, such as periods, dashes, parentheses, and so on.
@property (readonly, class, copy) NSCharacterSet *punctuationCharacterSet;
+
+/// A character set containing the characters in Unicode General Category Lt.
@property (readonly, class, copy) NSCharacterSet *capitalizedLetterCharacterSet;
+
+/// A character set containing the characters in Unicode General Category S\*.
+///
+/// These characters include, for example, the dollar sign (`$`) and the plus (`+`) sign.
@property (readonly, class, copy) NSCharacterSet *symbolCharacterSet;
+
+/// A character set containing the newline characters (`U+000A` ~ `U+000D`, `U+0085`, `U+2028`, and `U+2029`).
@property (readonly, class, copy) NSCharacterSet *newlineCharacterSet API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0));
+/// Returns a character set containing characters with Unicode values in a given range.
+///
+/// This code excerpt creates a character set object containing the lowercase English alphabetic characters:
+///
+/// ```objc
+/// NSRange lcEnglishRange;
+/// NSCharacterSet *lcEnglishLetters;
+///
+/// lcEnglishRange.location = (unsigned int)'a';
+/// lcEnglishRange.length = 26;
+/// lcEnglishLetters = [NSCharacterSet characterSetWithRange:lcEnglishRange];
+/// ```
+///
+/// - Parameter aRange: A range of Unicode values. `aRange.location` is the value of the first character to return; `aRange.location + aRange.length - 1` is the value of the last.
+/// - Returns: A character set containing characters whose Unicode values are given by `aRange`. If `aRange.length` is `0`, returns an empty character set.
+ (NSCharacterSet *)characterSetWithRange:(NSRange)aRange;
+
+/// Returns a character set containing the characters in a given string.
+///
+/// - Parameter aString: A string containing characters for the new character set.
+/// - Returns: A character set containing the characters in `aString`. Returns an empty character set if `aString` is empty.
+ (NSCharacterSet *)characterSetWithCharactersInString:(NSString *)aString;
+
+/// Returns a character set containing characters determined by a given bitmap representation.
+///
+/// This method is useful for creating a character set object with data from a file or other external data source.
+///
+/// A raw bitmap representation of a character set is a byte array with the first 2^16 bits (that is, 8192 bytes) representing the code point range of the Basic Multilingual Plane (BMP), such that the value of the bit at position n represents the presence in the character set of the character with decimal Unicode value n. A bitmap representation may contain zero to sixteen additional 8192 byte segments for each additional Unicode plane containing a character in a character set, with each 8192 byte segment prepended with a single plane index byte.
+///
+/// To add a character in the Basic Multilingual Plane (BMP) with decimal Unicode value n to a raw bitmap representation, you might do the following:
+///
+/// ```objc
+/// unsigned char bitmapRep[8192];
+/// bitmapRep[n >> 3] |= (((unsigned int)1) << (n & 7));
+/// ```
+///
+/// To remove that character:
+///
+/// ```objc
+/// bitmapRep[n >> 3] &= ~(((unsigned int)1) << (n & 7));
+/// ```
+///
+/// - Parameter data: A bitmap representation of a character set.
+/// - Returns: A character set containing characters determined by `data`.
+ (NSCharacterSet *)characterSetWithBitmapRepresentation:(NSData *)data;
+
+/// Returns a character set read from the bitmap representation stored in the file at a given path.
+///
+/// This method doesn't use filenames to check for the uniqueness of the character sets it creates. To prevent duplication of character sets in memory, cache them and make them available through an API that checks whether the requested set has already been loaded.
+///
+/// To read a bitmap representation from any file, use the `NSData` method `dataWithContentsOfFile:options:error:` and pass the result to ``characterSetWithBitmapRepresentation:``.
+///
+/// - Parameter fName: A path to a file containing a bitmap representation of a character set. The path name must end with the extension `.bitmap`.
+/// - Returns: A character set read from the bitmap representation stored in the file at `fName`.
+ (nullable NSCharacterSet *)characterSetWithContentsOfFile:(NSString *)fName;
- (instancetype) initWithCoder:(NSCoder *)coder NS_DESIGNATED_INITIALIZER;
+/// Returns a Boolean value that indicates whether a given character is in the receiver.
+///
+/// - Parameter aCharacter: The character to test for membership of the receiver.
+/// - Returns: `YES` if `aCharacter` is in the receiving character set, otherwise `NO`.
- (BOOL)characterIsMember:(unichar)aCharacter;
+
+/// An `NSData` object encoding the receiver in binary format.
+///
+/// This format is suitable for saving to a file or otherwise transmitting or archiving.
+///
+/// A raw bitmap representation of a character set is a byte array with the first 2^16 bits (that is, 8192 bytes) representing the code point range of the Basic Multilingual Plane (BMP), such that the value of the bit at position n represents the presence in the character set of the character with decimal Unicode value n. A bitmap representation may contain zero to sixteen additional 8192 byte segments for each additional Unicode plane containing a character in a character set, with each 8192 byte segment prepended with a single plane index byte.
+///
+/// For example, a character set containing only Basic Latin (ASCII) characters, which are contained by the Basic Multilingual Plane (BMP, plane 0), has a bitmap representation with a size of 8192 bytes, whereas a character set containing both Basic Latin (ASCII) characters and emoji characters, which are contained by the Supplementary Multilingual Plane (SMP, plane 1), has a bitmap representation with a size of 16385 bytes (8192 bytes for BMP, followed by the byte `0x01` for the plane index of SMP, followed by 8192 bytes for SMP).
+///
+/// To test for the presence of a character in the Basic Multilingual Plane (BMP) with decimal Unicode value n in a raw bitmap representation, you might do the following:
+///
+/// ```objc
+/// unsigned char bitmapRep[8192];
+/// if (bitmapRep[n >> 3] & (((unsigned int)1) << (n & 7))) {
+/// /* Character is present. */
+/// }
+/// ```
@property (readonly, copy) NSData *bitmapRepresentation;
+
+/// A character set containing only characters that don't exist in the receiver.
+///
+/// Using the inverse of an immutable character set is much more efficient than inverting a mutable character set.
@property (readonly, copy) NSCharacterSet *invertedSet;
+/// Returns a Boolean value that indicates whether a given long character is a member of the receiver.
+///
+/// This method supports the specification of 32-bit characters.
+///
+/// - Parameter theLongChar: A UTF32 character.
+/// - Returns: `YES` if `theLongChar` is in the receiver, otherwise `NO`.
- (BOOL)longCharacterIsMember:(UTF32Char)theLongChar;
+/// Returns a Boolean value that indicates whether the receiver is a superset of another given character set.
+///
+/// - Parameter theOtherSet: A character set.
+/// - Returns: `YES` if the receiver is a superset of `theOtherSet`, otherwise `NO`.
- (BOOL)isSupersetOfSet:(NSCharacterSet *)theOtherSet;
+
+/// Returns a Boolean value that indicates whether the receiver has at least one member in a given character plane.
+///
+/// This method makes it easier to find the plane containing the members of the current character set. The Basic Multilingual Plane (BMP) is plane `0`.
+///
+/// - Parameter thePlane: A character plane.
+/// - Returns: `YES` if the receiver has at least one member in `thePlane`, otherwise `NO`.
- (BOOL)hasMemberInPlane:(uint8_t)thePlane;
@end
+/// An object representing a mutable set of Unicode character values for use in search operations.
+///
+/// In Swift, this object bridges to ``CharacterSet``; use ``NSMutableCharacterSet`` when you need reference semantics or other Foundation-specific behavior.
+///
+/// The `NSMutableCharacterSet` class declares the programmatic interface to objects that manage a modifiable set of Unicode characters. You can add or remove characters from a mutable character set as numeric values in `NSRange` structures or as character values in strings, combine character sets by union or intersection, and invert a character set.
+///
+/// Mutable character sets are less efficient to use than immutable character sets. If you don't need to change a character set after creating it, create an immutable copy with `copy` and use that.
+///
+/// `NSMutableCharacterSet` defines no primitive methods. Subclasses must implement all methods declared by this class in addition to the primitives of ``NSCharacterSet``. They must also implement ``NSMutableCopying/mutableCopy(with:)``.
+///
+/// `NSMutableCharacterSet` is "toll-free bridged" with its Core Foundation counterpart, <doc://com.apple.documentation/documentation/corefoundation/cfmutablecharacterset>. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html#//apple_ref/doc/uid/TP40010810-CH2) for more information.
+///
+/// > Important:
+/// > The Swift overlay to the Foundation framework provides the ``CharacterSet`` structure, which bridges to the ``NSMutableCharacterSet`` class and its immutable superclass, ``NSCharacterSet``. For more information about value types, see <doc://com.apple.documentation/documentation/swift/working-with-foundation-types>.
@interface NSMutableCharacterSet : NSCharacterSet <NSCopying, NSMutableCopying, NSSecureCoding>
+/// Adds to the receiver the characters whose Unicode values are in a given range.
+///
+/// This code excerpt adds to a character set the lowercase English alphabetic characters:
+///
+/// ```objc
+/// NSMutableCharacterSet *aCharacterSet = [[NSMutableCharacterSet alloc] init];
+/// NSRange lcEnglishRange;
+///
+/// lcEnglishRange.location = (unsigned int)'a';
+/// lcEnglishRange.length = 26;
+/// [aCharacterSet addCharactersInRange:lcEnglishRange];
+/// ```
+///
+/// - Parameter aRange: The range of characters to add. `aRange.location` is the value of the first character to add; `aRange.location + aRange.length - 1` is the value of the last. If `aRange.length` is `0`, this method has no effect.
- (void)addCharactersInRange:(NSRange)aRange;
+
+/// Removes from the receiver the characters whose Unicode values are in a given range.
+///
+/// - Parameter aRange: The range of characters to remove. `aRange.location` is the value of the first character to remove; `aRange.location + aRange.length - 1` is the value of the last. If `aRange.length` is `0`, this method has no effect.
- (void)removeCharactersInRange:(NSRange)aRange;
+
+/// Adds to the receiver the characters in a given string.
+///
+/// This method has no effect if `aString` is empty.
+///
+/// - Parameter aString: The characters to add to the receiver.
- (void)addCharactersInString:(NSString *)aString;
+
+/// Removes from the receiver the characters in a given string.
+///
+/// This method has no effect if `aString` is empty.
+///
+/// - Parameter aString: The characters to remove from the receiver.
- (void)removeCharactersInString:(NSString *)aString;
+
+/// Modifies the receiver so it contains all characters that exist in either the receiver or another set.
- (void)formUnionWithCharacterSet:(NSCharacterSet *)otherSet;
+
+/// Modifies the receiver so it contains only characters that exist in both the receiver and another set.
+///
+/// - Parameter otherSet: The character set with which to perform the intersection.
- (void)formIntersectionWithCharacterSet:(NSCharacterSet *)otherSet;
+
+/// Replaces all the characters in the receiver with all the characters it didn't previously contain.
+///
+/// Inverting a mutable character set, whether by `invert` or by `invertedSet`, is much less efficient than inverting an immutable character set with `invertedSet`.
- (void)invert;
+/// Returns a mutable character set containing the characters in Unicode General Category Cc and Cf.
+ (NSMutableCharacterSet *)controlCharacterSet;
+/// Returns a mutable character set containing the characters in Unicode General Category Zs and `CHARACTER TABULATION` (`U+0009`).
+ (NSMutableCharacterSet *)whitespaceCharacterSet;
+/// Returns a mutable character set containing characters in Unicode General Category Z\*, `U+000A` ~ `U+000D`, and `U+0085`.
+ (NSMutableCharacterSet *)whitespaceAndNewlineCharacterSet;
+/// Returns a mutable character set containing the characters in the category of decimal numbers.
+ (NSMutableCharacterSet *)decimalDigitCharacterSet;
+/// Returns a mutable character set containing the characters in Unicode General Category L\* & M\*.
+ (NSMutableCharacterSet *)letterCharacterSet;
+/// Returns a mutable character set containing the characters in Unicode General Category Ll.
+ (NSMutableCharacterSet *)lowercaseLetterCharacterSet;
+/// Returns a mutable character set containing the characters in Unicode General Category Lu and Lt.
+ (NSMutableCharacterSet *)uppercaseLetterCharacterSet;
+/// Returns a mutable character set containing the characters in Unicode General Category M\*.
+ (NSMutableCharacterSet *)nonBaseCharacterSet;
+/// Returns a mutable character set containing the characters in Unicode General Categories L\*, M\*, and N\*.
+ (NSMutableCharacterSet *)alphanumericCharacterSet;
+/// Returns a mutable character set containing individual Unicode characters that can also be represented as composed character sequences (such as for letters with accents), by the definition of "standard decomposition" in version 3.2 of the Unicode character encoding standard.
+ (NSMutableCharacterSet *)decomposableCharacterSet;
+/// Returns a mutable character set containing values in the category of Non-Characters or that have not yet been defined in version 3.2 of the Unicode standard.
+ (NSMutableCharacterSet *)illegalCharacterSet;
+/// Returns a mutable character set containing the characters in Unicode General Category P\*.
+ (NSMutableCharacterSet *)punctuationCharacterSet;
+/// Returns a mutable character set containing the characters in Unicode General Category Lt.
+ (NSMutableCharacterSet *)capitalizedLetterCharacterSet;
+/// Returns a mutable character set containing the characters in Unicode General Category S\*.
+ (NSMutableCharacterSet *)symbolCharacterSet;
+/// Returns a mutable character set containing the newline characters (`U+000A` ~ `U+000D`, `U+0085`, `U+2028`, and `U+2029`).
+ (NSMutableCharacterSet *)newlineCharacterSet API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0));
+/// Returns a mutable character set containing characters with Unicode values in a given range.
+ (NSMutableCharacterSet *)characterSetWithRange:(NSRange)aRange;
+/// Returns a mutable character set containing the characters in a given string.
+ (NSMutableCharacterSet *)characterSetWithCharactersInString:(NSString *)aString;
+/// Returns a mutable character set containing characters determined by a given bitmap representation.
+ (NSMutableCharacterSet *)characterSetWithBitmapRepresentation:(NSData *)data;
+/// Returns a mutable character set read from the bitmap representation stored in the file at a given path.
+ (nullable NSMutableCharacterSet *)characterSetWithContentsOfFile:(NSString *)fName;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSClassDescription.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSClassDescription.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSClassDescription.h 2026-04-18 22:35:10
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSClassDescription.h 2026-05-22 05:23:42
@@ -10,15 +10,28 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
+/// An abstract class that provides the interface for querying the relationships and properties of a class.
@interface NSClassDescription : NSObject
+/// Registers an ``NSClassDescription`` object for a given class in the ``NSClassDescription`` cache.
+ (void)registerClassDescription:(NSClassDescription *)description forClass:(Class)aClass;
+
+/// Removes all ``NSClassDescription`` objects from the cache.
+ (void)invalidateClassDescriptionCache;
+
+/// Returns the class description for a given class.
+ (nullable NSClassDescription *)classDescriptionForClass:(Class)aClass;
+/// An array of ``NSString`` objects representing the receiver's attribute keys.
@property (readonly, copy) NSArray<NSString *> *attributeKeys;
+
+/// An array of ``NSString`` objects representing the keys for the receiver's to-one relationships.
@property (readonly, copy) NSArray<NSString *> *toOneRelationshipKeys;
+
+/// An array of ``NSString`` objects representing the keys for the receiver's to-many relationships.
@property (readonly, copy) NSArray<NSString *> *toManyRelationshipKeys;
+
+/// Returns the name of the inverse relationship from a relationship specified by a given key.
- (nullable NSString *)inverseForRelationshipKey:(NSString *)relationshipKey;
@end
@@ -33,6 +46,7 @@
@end
+/// Posted when an ``NSClassDescription`` is needed for a class but one has not yet been registered.
FOUNDATION_EXPORT NSNotificationName const NSClassDescriptionNeededForClassNotification;
NS_HEADER_AUDIT_END(nullability, sendability)
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCoder.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCoder.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCoder.h 2026-04-18 20:58:57
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCoder.h 2026-05-27 00:45:18
@@ -8,73 +8,262 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
-/*!
- Describes the action an NSCoder should take when it encounters decode failures (e.g. corrupt data) for non-TopLevel decodes.
- */
+/// Policies describing the action the coder should take when encountering decode failures.
typedef NS_ENUM(NSInteger, NSDecodingFailurePolicy) {
- // On decode failure, the NSCoder will raise an exception internally to propagate failure messages (and unwind the stack). This exception can be transformed into an NSError via any of the TopLevel decode APIs.
+ /// A failure policy that directs the coder to raise an exception.
+ ///
+ /// With this policy, the `NSCoder` raises an exception internally to propagate failure messages (and unwind the stack). This exception can be transformed into an `NSError` via any of the TopLevel decode APIs.
NSDecodingFailurePolicyRaiseException,
- // On decode failure, the NSCoder will capture the failure as an NSError, and prevent further decodes (by returning 0 / nil equivalent as appropriate). Clients should consider using this policy if they know that all encoded objects behave correctly in the presence of decode failures (e.g. they use -failWithError: to communicate decode failures and don't raise exceptions for error propagation)
+ /// A failure policy that directs the coder to capture the failure as an error object.
+ ///
+ /// On decode failure, the `NSCoder` will capture the failure as an `NSError`, and prevent further decodes (by returning `0` / `nil` equivalent as appropriate). Use this policy if you know that all encoded objects use `failWithError:` to communicate decode failures and don't raise exceptions for error propagation.
NSDecodingFailurePolicySetErrorAndReturn,
} API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0));
+/// An abstract class that serves as the basis for objects that enable archiving and distribution of other objects.
+///
+/// ``NSCoder`` declares the interface used by concrete subclasses to transfer objects and other values between memory and some other format. This capability provides the basis for archiving (storing objects and data on disk) and distribution (copying objects and data items between different processes or threads). The concrete subclasses provided by Foundation for these purposes are ``NSArchiver``, ``NSUnarchiver``, ``NSKeyedArchiver``, ``NSKeyedUnarchiver``, and ``NSPortCoder``. Concrete subclasses of ``NSCoder`` are "coder classes", and instances of these classes are "coder objects" (or simply "coders"). A coder that can only encode values is an "encoder", and one that can only decode values is a "decoder".
+///
+/// ``NSCoder`` operates on objects, scalars, C arrays, structures, strings, and on pointers to these types. It doesn't handle types whose implementation varies across platforms, such as `union`, `void *`, function pointers, and long chains of pointers. A coder stores object type information along with the data, so an object decoded from a stream of bytes is normally of the same class as the object that was originally encoded into the stream. An object can change its class when encoded, however; this is described in [Archives and Serializations Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Archiving.html#//apple_ref/doc/uid/10000047i).
+///
+/// The AVFoundation framework adds methods to the ``NSCoder`` class to make it easier to create archives including Core Media time structures, and extract Core Media time structure from archives.
+///
+/// ### Subclassing Notes
+///
+/// For details of how to create a subclass of `NSCoder`, see [Subclassing NSCoder](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Articles/subclassing.html#//apple_ref/doc/uid/20000951) in [Archives and Serializations Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Archiving/Archiving.html#//apple_ref/doc/uid/10000047i).
@interface NSCoder : NSObject
+
+/// Encodes a value of the given type at the given address.
+///
+/// Subclasses must override this method, and match it with a subsequent ``decodeValueOfObjCType:at:size:`` message.
+/// When calling this method, `type` must contain exactly one type code.
+/// You should not use this method to encode Objective-C objects.
- (void)encodeValueOfObjCType:(const char *)type at:(const void *)addr;
+
+/// Encodes a given data object.
+///
+/// Subclasses must override this method. This method must be matched by a subsequent ``decodeDataObject`` message.
- (void)encodeDataObject:(NSData *)data;
+
+/// Decodes and returns an `NSData` object that was previously encoded with ``encodeDataObject:``.
+///
+/// Subclasses must override this method.
- (nullable NSData *)decodeDataObject;
+
+/// Decodes a single value of a known type from the specified data buffer.
+///
+/// The `type` parameter must contain exactly one type code, and the buffer specified by `data` must be large enough to hold the value corresponding to that type code.
+/// Subclasses must override this method and provide an implementation to decode the value.
+/// This method matches an ``encodeValueOfObjCType:at:`` message used during encoding.
- (void)decodeValueOfObjCType:(const char *)type at:(void *)data size:(NSUInteger)size API_AVAILABLE(macos(10.13), ios(11.0), watchos(4.0), tvos(11.0));
+
+/// This method is present for historical reasons and is not used with keyed archivers.
+///
+/// - Returns: The version in effect for the class named `className` or `NSNotFound` if no class named `className` exists.
- (NSInteger)versionForClassName:(NSString *)className;
@end
@interface NSCoder (NSExtendedCoder)
-
+
+/// Encodes an object.
+///
+/// `NSCoder`'s implementation simply invokes ``encodeValueOfObjCType:at:`` to encode `object`. Subclasses can override this method to encode a reference to `object` instead of `object` itself.
+/// This method must be matched by a subsequent ``decodeObject`` message.
- (void)encodeObject:(nullable id)object;
+
+/// An encoding method for subclasses to override to encode an interconnected group of objects, starting with the provided root object.
+///
+/// `NSCoder`'s implementation simply invokes ``encodeObject:``. This method must be matched by a subsequent ``decodeObject`` message.
- (void)encodeRootObject:(id)rootObject;
+
+/// An encoding method for subclasses to override such that it creates a copy, rather than a proxy, when decoded.
+///
+/// `NSCoder`'s implementation simply invokes ``encodeObject:``. This method must be matched by a corresponding ``decodeObject`` message.
- (void)encodeBycopyObject:(nullable id)anObject;
+
+/// An encoding method for subclasses to override such that it creates a proxy, rather than a copy, when decoded.
+///
+/// `NSCoder`'s implementation simply invokes ``encodeObject:``. This method must be matched by a corresponding ``decodeObject`` message.
- (void)encodeByrefObject:(nullable id)anObject;
+
+/// An encoding method for subclasses to override to conditionally encode an object, preserving common references to it.
+///
+/// In the overriding method, `object` should be encoded only if it's unconditionally encoded elsewhere (with any other `encode...Object:` method).
+/// `NSCoder`'s implementation simply invokes ``encodeObject:``.
+/// This method must be matched by a subsequent ``decodeObject`` message.
- (void)encodeConditionalObject:(nullable id)object;
+
+/// Encodes a series of values of potentially differing Objective-C types.
+///
+/// `types` is a C string containing any number of type codes. The variable arguments consist of one or more pointer arguments, each of which specifies a buffer containing the value to be encoded.
+/// This method must be matched by a subsequent ``decodeValuesOfObjCTypes:`` message.
+/// You should not use this method to encode Objective-C objects.
- (void)encodeValuesOfObjCTypes:(const char *)types, ...;
+
+/// Encodes an array of the given Objective-C type, provided the number of items and a pointer.
+///
+/// The values are encoded from the buffer beginning at `array`. `type` must contain exactly one type code.
+/// This method must be matched by a subsequent ``decodeArrayOfObjCType:count:at:`` message.
+/// You should not use this method to encode C arrays of Objective-C objects.
- (void)encodeArrayOfObjCType:(const char *)type count:(NSUInteger)count at:(const void *)array;
+
+/// Encodes a buffer of data of an unspecified type.
+///
+/// The buffer to be encoded begins at `byteaddr`, and its length in bytes is given by `length`.
+/// This method must be matched by a corresponding ``decodeBytesWithReturnedLength:`` message.
- (void)encodeBytes:(nullable const void *)byteaddr length:(NSUInteger)length;
+/// Decodes and returns a previously-encoded object.
+///
+/// `NSCoder`'s implementation invokes ``decodeValueOfObjCType:at:size:`` to decode the object data.
+/// Subclasses may need to override this method if they override any of the corresponding `encode...Object` methods.
- (nullable id)decodeObject;
+
+/// Decodes a previously-encoded object, returning an error if decoding fails.
- (nullable id)decodeTopLevelObjectAndReturnError:(NSError **)error API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) NS_SWIFT_UNAVAILABLE("Use 'decodeTopLevelObject() throws' instead");
+
+/// Decodes a series of potentially different Objective-C types.
+///
+/// `types` is a single C string containing any number of type codes. The variable arguments consist of one or more pointer arguments, each of which specifies the buffer in which to place a single decoded value.
+/// This method matches an ``encodeValuesOfObjCTypes:`` message used during encoding.
+/// You should not use this method to decode Objective-C objects.
- (void)decodeValuesOfObjCTypes:(const char *)types, ...;
+
+/// Decodes an array of `count` items, whose Objective-C type is given by `itemType`.
+///
+/// The items are decoded into the buffer beginning at `array`, which must be large enough to contain them all. `itemType` must contain exactly one type code.
+/// This method matches an ``encodeArrayOfObjCType:count:at:`` message used during encoding.
+/// You should not use this method to decode C arrays of Objective-C objects.
- (void)decodeArrayOfObjCType:(const char *)itemType count:(NSUInteger)count at:(void *)array;
+
+/// Decodes a buffer of data whose types are unspecified.
+///
+/// The buffer's length is returned by reference in `lengthp`. If you need the bytes beyond the scope of the current `@autoreleasepool` block, you must copy them.
+/// This method matches an ``encodeBytes:length:`` message used during encoding.
- (nullable void *)decodeBytesWithReturnedLength:(NSUInteger *)lengthp NS_RETURNS_INNER_POINTER;
#if TARGET_OS_OSX
+/// Encodes a property list.
+///
+/// `NSCoder`'s implementation invokes ``encodeValueOfObjCType:at:`` to encode the property list.
+/// This method must be matched by a subsequent ``decodePropertyList`` message.
- (void)encodePropertyList:(id)aPropertyList;
+
+/// Decodes a property list that was previously encoded with ``encodePropertyList:``.
- (nullable id)decodePropertyList;
#endif
+/// This method is present for historical reasons and has no effect.
- (void)setObjectZone:(nullable NSZone *)zone NS_AUTOMATED_REFCOUNT_UNAVAILABLE;
+
+/// This method is present for historical reasons and has no effect.
+///
+/// `NSCoder`'s implementation returns the default memory zone, as given by `NSDefaultMallocZone()`.
- (nullable NSZone *)objectZone NS_AUTOMATED_REFCOUNT_UNAVAILABLE;
+/// The system version in effect for the archive.
+///
+/// During encoding, the current version. During decoding, the version that was in effect when the data was encoded.
+/// Subclasses that implement decoding must override this property to return the system version of the data being decoded.
@property (readonly) unsigned int systemVersion;
+/// A Boolean value that indicates whether the receiver supports keyed coding of objects.
+///
+/// `NO` by default. Concrete subclasses that support keyed coding, such as `NSKeyedArchiver`, need to override this property to return `YES`.
@property (readonly) BOOL allowsKeyedCoding;
+/// Encodes an object and associates it with the string key.
+///
+/// Subclasses must override this method to identify multiple encodings of `object` and encode a reference to `object` instead.
- (void)encodeObject:(nullable id)object forKey:(NSString *)key;
+
+/// An encoding method for subclasses to override to conditionally encode an object, preserving common references to it, only if it has been unconditionally encoded.
+///
+/// Subclasses must override this method if they support keyed coding.
- (void)encodeConditionalObject:(nullable id)object forKey:(NSString *)key;
+
+/// Encodes a Boolean value and associates it with the string `key`.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (void)encodeBool:(BOOL)value forKey:(NSString *)key;
+
+/// Encodes a C integer value and associates it with the string key.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (void)encodeInt:(int)value forKey:(NSString *)key;
+
+/// Encodes a 32-bit integer value and associates it with the string key.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (void)encodeInt32:(int32_t)value forKey:(NSString *)key;
+
+/// Encodes a 64-bit integer value and associates it with the string key.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (void)encodeInt64:(int64_t)value forKey:(NSString *)key;
+
+/// Encodes a floating point value and associates it with the string key.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (void)encodeFloat:(float)value forKey:(NSString *)key;
+
+/// Encodes a double-precision floating point value and associates it with the string key.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (void)encodeDouble:(double)value forKey:(NSString *)key;
+
+/// Encodes a buffer of data, given its length and a pointer, and associates it with a string key.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (void)encodeBytes:(nullable const uint8_t *)bytes length:(NSUInteger)length forKey:(NSString *)key;
+/// Returns a Boolean value that indicates whether an encoded value is available for a string.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (BOOL)containsValueForKey:(NSString *)key;
+
+/// Decodes and returns a previously-encoded object that was associated with the string `key`.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (nullable id)decodeObjectForKey:(NSString *)key;
+
+/// Decodes and returns a previously-encoded object for the given key, returning an error if decoding fails.
- (nullable id)decodeTopLevelObjectForKey:(NSString *)key error:(NSError **)error API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) NS_SWIFT_UNAVAILABLE("Use 'decodeObject(of:, forKey:)' instead");
+
+/// Decodes and returns a boolean value that was previously encoded and associated with the string `key`.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (BOOL)decodeBoolForKey:(NSString *)key;
+
+/// Decodes and returns an int value that was previously encoded and associated with the string `key`.
+///
+/// If the encoded integer does not fit into the default integer size, the method raises an `NSRangeException`. Subclasses must override this method if they perform keyed coding.
- (int)decodeIntForKey:(NSString *)key;
+
+/// Decodes and returns a 32-bit integer value that was previously encoded and associated with the string `key`.
+///
+/// If the encoded integer does not fit into a 32-bit integer, the method raises an `NSRangeException`. Subclasses must override this method if they perform keyed coding.
- (int32_t)decodeInt32ForKey:(NSString *)key;
+
+/// Decodes and returns a 64-bit integer value that was previously encoded and associated with the string `key`.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (int64_t)decodeInt64ForKey:(NSString *)key;
+
+/// Decodes and returns a float value that was previously encoded and associated with the string `key`.
+///
+/// If the value was encoded as a double, the extra precision is lost. Subclasses must override this method if they perform keyed coding.
- (float)decodeFloatForKey:(NSString *)key;
+
+/// Decodes and returns a double value that was previously encoded and associated with the string `key`.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (double)decodeDoubleForKey:(NSString *)key;
+
+/// Decodes a buffer of data that was previously encoded with ``encodeBytes:length:forKey:`` and associated with the string `key`.
+///
+/// The buffer's length is returned by reference in `lengthp`. The returned bytes are immutable. Subclasses must override this method if they perform keyed coding.
- (nullable const uint8_t *)decodeBytesForKey:(NSString *)key returnedLength:(nullable NSUInteger *)lengthp NS_RETURNS_INNER_POINTER; // returned bytes immutable!
/// Decode bytes from the decoder. The length of the bytes must be greater than or equal to the `length` parameter.
@@ -85,14 +274,30 @@
/// If the result exists, but is of insufficient length, then the decoder uses `failWithError` to fail the entire decode operation. The result of that is configurable on a per-NSCoder basis using `NSDecodingFailurePolicy`.
- (nullable const uint8_t *)decodeBytesForKey:(NSString *)key minimumLength:(NSUInteger)length API_AVAILABLE(macos(15.4), ios(18.4), watchos(11.4), tvos(18.4), visionos(2.4)) NS_RETURNS_INNER_POINTER;
+/// Encodes an integer value and associates it with the string key.
+///
+/// Subclasses must override this method if they perform keyed coding.
- (void)encodeInteger:(NSInteger)value forKey:(NSString *)key API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0));
+
+/// Decodes and returns an NSInteger value that was previously encoded and associated with the string `key`.
+///
+/// If the encoded integer does not fit into the NSInteger size, the method raises an `NS