-
Notifications
You must be signed in to change notification settings - Fork 571
Foundation tvOS 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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/FoundationErrors.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/FoundationErrors.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSArray.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSArray.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAttributedString.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAttributedString.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAutoreleasePool.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAutoreleasePool.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSAutoreleasePool.h 2026-04-18 19:07:10
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBundle.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBundle.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteCountFormatter.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteCountFormatter.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteOrder.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSByteOrder.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCache.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCache.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCache.h 2026-04-18 19:07:12
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendar.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendar.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendar.h 2026-04-18 20:41:04
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCalendar.h 2026-05-27 00:13:04
@@ -18,25 +18,46 @@
#define NS_CALENDAR_DEPRECATED_MAC(A, B, ...) NS_DEPRECATED_MAC(A, B, __VA_ARGS__)
#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));
@@ -50,158 +71,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.
@@ -209,6 +433,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.
@@ -216,6 +441,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".
@@ -224,6 +453,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.
@@ -232,82 +464,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.
@@ -330,8 +584,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.
@@ -340,6 +606,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.
@@ -348,6 +615,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.
@@ -355,16 +623,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).
@@ -373,6 +653,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.
@@ -392,6 +673,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));
@@ -414,39 +698,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.
@@ -454,6 +813,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.
@@ -461,6 +823,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.
@@ -471,6 +836,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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCharacterSet.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCharacterSet.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCharacterSet.h 2026-04-18 19:07:12
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCoder.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCoder.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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/AppleTVOS.platform/Developer/SDKs/AppleTVOS.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 `NSRangeException`. Subclasses must override this method if they perform keyed coding.
- (NSInteger)decodeIntegerForKey:(NSString *)key API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0));
+/// Indicates whether the archiver requires all archived classes to resist object substitution attacks.
+///
+/// Secure coders check a set of allowed classes before decoding objects, and all objects must implement `NSSecureCoding`.
// Returns YES if this coder requires secure coding. Secure coders check a list of allowed classes before decoding objects, and all objects must implement NSSecureCoding.
@property (readonly) BOOL requiresSecureCoding API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0));
+/// Decodes an object for the key, restricted to the specified class.
+///
+/// If the coder requires secure coding, then an exception will be thrown if the class to be decoded does not implement `NSSecureCoding` or is not `isKindOfClass:` of the argument.
+/// If the coder does not require secure coding, then the class argument is ignored.
// Specify what the expected class of the allocated object is. If the coder responds YES to -requiresSecureCoding, then an exception will be thrown if the class to be decoded does not implement NSSecureCoding or is not isKindOfClass: of the argument. If the coder responds NO to -requiresSecureCoding, then the class argument is ignored and no check of the class of the decoded object is performed, exactly as if decodeObjectForKey: had been called.
- (nullable id)decodeObjectOfClass:(Class)aClass forKey:(NSString *)key API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0));
+
+/// Decodes an object for the key and restricted class, returning an error if decoding fails.
- (nullable id)decodeTopLevelObjectOfClass:(Class)aClass forKey:(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");
/**
@@ -113,8 +318,13 @@
*/
- (nullable NSDictionary *)decodeDictionaryWithKeysOfClass:(Class)keyCls objectsOfClass:(Class)objectCls forKey:(NSString *)key API_AVAILABLE(macos(11.0), ios(14.0), watchos(7.0), tvos(14.0)) NS_REFINED_FOR_SWIFT;
+/// Decodes an object for the key, restricted to the specified classes.
+///
+/// The class of the object may be any class in the provided `NSSet`, or a subclass of any class in the set.
// The class of the object may be any class in the provided NSSet, or a subclass of any class in the set. Otherwise, the behavior is the same as -decodeObjectOfClass:forKey:.
- (nullable id)decodeObjectOfClasses:(nullable NSSet<Class> *)classes forKey:(NSString *)key API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) NS_REFINED_FOR_SWIFT;
+
+/// Decodes an object for the key and restricted classes, returning an error if decoding fails.
- (nullable id)decodeTopLevelObjectOfClasses:(nullable NSSet<Class> *)classes forKey:(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");
/**
@@ -135,20 +345,19 @@
*/
- (nullable NSDictionary *)decodeDictionaryWithKeysOfClasses:(NSSet<Class> *)keyClasses objectsOfClasses:(NSSet<Class> *)objectClasses forKey:(NSString *)key API_AVAILABLE(macos(11.0), ios(14.0), watchos(7.0), tvos(14.0)) NS_REFINED_FOR_SWIFT;
+/// Returns a decoded property list for the specified key.
+///
+/// This method calls ``decodeObjectOfClasses:forKey:`` with a set allowing only property list types.
// Calls -decodeObjectOfClasses:forKey: with a set allowing only property list types.
- (nullable id)decodePropertyListForKey:(NSString *)key API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0));
+/// The set of coded classes allowed for secure coding.
+///
+/// Secure coders check this set of allowed classes before decoding objects, and all objects must implement `NSSecureCoding`.
// Get the current set of allowed classes.
@property (nullable, readonly, copy) NSSet<Class> *allowedClasses API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0));
-/*!
- @abstract Signals to this coder that the decode has failed.
- @parameter non-nil error that describes the reason why the decode failed
- @discussion
- Sets an error on this NSCoder once per TopLevel decode; calling it repeatedly will have no effect until the call stack unwinds to one of the TopLevel decode entry-points.
-
- This method is only meaningful to call for decodes.
-
+/*
Typically, you would want to call this method in your -initWithCoder: implementation when you detect situations like:
- lack of secure coding
- corruption of your data
@@ -172,60 +381,81 @@
The kind of unwinding you get is determined by the decodingFailurePolicy property of this NSCoder (which defaults to NSDecodingFailurePolicyRaiseException to match historical behavior).
*/
+
+/// Signals to this coder that the decode operation has failed.
+///
+/// Typically, you call this method in your ``NSCoding/init(coder:)`` implementation. You should set the error when you detect problems such as lack of secure coding, data corruption, or a domain validation failure.
+///
+/// This method is only meaningful to call for decodes.
+///
+/// The effect of calling this method depends on the value of ``decodingFailurePolicy``, as follows:
+///
+/// - If the policy is ``DecodingFailurePolicy/raiseException``, calling this method throws an exception immediately. Swift code cannot catch this kind of exception.
+/// - If the policy is ``DecodingFailurePolicy/setErrorAndReturn``, calling this method sets the error property once per call to one of the `decode` methods. Calling it repeatedly has no effect until the call stack unwinds to one of these methods' entry points.
+///
+/// After calling `failWithError:` within your ``NSCoding/init(coder:)`` implementation, you should clean up and return `nil` as early as possible.
+///
+/// - Parameter error: An error that indicates why decoding failed.
- (void)failWithError:(NSError *)error API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0));
-/*!
- @abstract Defines the behavior this NSCoder should take on decode failure (i.e. corrupt archive, invalid data, etc.).
- @discussion
- The default result of this property is NSDecodingFailurePolicyRaiseException, subclasses can change this to an alternative policy.
- */
+/// The action the coder should take when decoding fails.
+///
+/// A decode call can fail for the following reasons:
+///
+/// - The keyed archive data is corrupt or missing.
+/// - A type mismatch occurs, such as expecting a class but encountering a numeric type instead. This also occurs when `decodeInteger(forKey:)` encounters a value encoded as floating-point, or vice versa.
+/// - A secure coding violation occurs. This happens when you attempt to decode an object that doesn't conform to `NSSecureCoding`, or when the encoded type doesn't match any of the expected types.
@property (readonly) NSDecodingFailurePolicy decodingFailurePolicy API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0));
-/*!
- @abstract The current error (if there is one) for the current TopLevel decode.
- @discussion
- The meaning of this property changes based on the result of the decodingFailurePolicy property:
- For NSDecodingFailurePolicyRaiseException, this property will always be nil.
- For NSDecodingFailurePolicySetErrorAndReturn, this property can be non-nil, and if so, indicates that there was a failure while decoding the archive (specifically its the very first error encountered).
-
- While .error is non-nil, all attempts to decode data from this coder will return a nil/zero-equivalent value.
-
- This error is consumed by a TopLevel decode API (which resets this coder back to a being able to potentially decode data).
- */
+/// An error in the top-level decode.
+///
+/// The meaning of this property depends on the setting of the `decodingFailurePolicy` property. For `NSDecodingFailurePolicyRaiseException`, this property is always `nil`. For `NSDecodingFailurePolicySetErrorAndReturn`, a non-`nil` value represents the first error encountered while decoding the archive.
+///
+/// While `error` is non-`nil`, all attempts to decode data from this coder will return a `nil`/zero-equivalent value. This error is consumed by a top-level decode API, which resets the coder back to being able to potentially decode data.
@property (nullable, readonly, copy) NSError *error API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0));
@end
#if TARGET_OS_OSX
+/// Returns the next object from the coder.
+///
+/// Given an `NSCoder`, returns an object previously written with `NXWriteNSObject()`. The returned object is autoreleased.
+///
+/// - Parameter decoder: The coder from which to read the object.
+/// - Returns: The next object from the coder.
FOUNDATION_EXPORT NSObject * _Nullable NXReadNSObjectFromCoder(NSCoder *decoder) API_DEPRECATED("Not supported", macos(10.0,10.5), ios(2.0,2.0), watchos(2.0,2.0), tvos(9.0,9.0));
-/* Given an NSCoder, returns an object previously written with
- NXWriteNSObject(). The returned object is autoreleased. */
@interface NSCoder (NSTypedstreamCompatibility)
+/// Encodes an old-style object onto the coder.
+///
+/// @DeprecationSummary {
+/// Apple discourages the use of this symbol.
+/// }
+///
+/// No sharing is done across separate ``encodeNXObject:`` invocations. Callers must have implemented an ``NSCoding/encode(with:)``, which parallels the `write:` methods, on all of their classes that may be touched by this operation.
- (void)encodeNXObject:(id)object API_DEPRECATED("Not supported", macos(10.0,10.5), ios(2.0,2.0), watchos(2.0,2.0), tvos(9.0,9.0));
-/* Writes old-style object onto the coder. No sharing is done across
- separate -encodeNXObject:. Callers must have implemented an
- -encodeWithCoder:, which parallels the -write: methods, on all of
- their classes which may be touched by this operation. Object's
- -replacementObjectForCoder: compatibility method will take care
- of calling -startArchiving:. */
-
+
+/// Decodes an object previously written with ``encodeNXObject:``.
+///
+/// @DeprecationSummary {
+/// Apple discourages the use of this symbol.
+/// }
+///
+/// No sharing is done across separate ``decodeNXObject`` invocations. Callers must have implemented an ``NSCoding/init(coder:)``, which parallels the `read:` methods, on all of their classes that may be touched by this operation. The returned object is autoreleased.
- (nullable id)decodeNXObject API_DEPRECATED("Not supported", macos(10.0,10.5), ios(2.0,2.0), watchos(2.0,2.0), tvos(9.0,9.0));
-/* Reads an object previously written with -encodeNXObject:. No
- sharing is done across separate -decodeNXObject. Callers must
- have implemented an -initWithCoder:, which parallels the -read:
- methods, on all of their classes which may be touched by this
- operation. Object's -awakeAfterUsingCoder: compatibility method
- will take care of calling -awake and -finishUnarchiving. The
- returned object is autoreleased. */
@end
#endif
@interface NSCoder(NSDeprecated)
-/* This method is unsafe because it could potentially cause buffer overruns. You should use -decodeValueOfObjCType:at:size: instead.
- */
+/// Decodes a single value, whose Objective-C type is given by `type`.
+///
+/// @DeprecationSummary {
+/// Use ``decodeValueOfObjCType:at:size:`` instead.
+/// }
+///
+/// This method is unsafe because it could potentially cause buffer overruns.
- (void)decodeValueOfObjCType:(const char *)type at:(void *)data API_DEPRECATED_WITH_REPLACEMENT("decodeValueOfObjCType:at:size:", 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
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSComparisonPredicate.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSComparisonPredicate.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSComparisonPredicate.h 2026-04-18 19:07:14
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSComparisonPredicate.h 2026-05-27 00:45:18
@@ -6,58 +6,116 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
-// Flags(s) that can be passed to the factory to indicate that a operator operating on strings should do so in a case insensitive fashion.
+/// Constants that describe the possible types of string comparison for comparison predicates.
typedef NS_OPTIONS(NSUInteger, NSComparisonPredicateOptions) {
+ /// A case-insensitive predicate. You represent this option in a predicate format string using a `[c]` following a string operation (for example, `"NeXT" like[c] "next"`).
NSCaseInsensitivePredicateOption = 0x01,
+ /// A diacritic-insensitive predicate. You represent this option in a predicate format string using a `[d]` following a string operation (for example, `"naïve" like[d] "naive"`).
NSDiacriticInsensitivePredicateOption = 0x02,
- NSNormalizedPredicateOption API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 0x04, /* Indicate that the strings to be compared have been preprocessed; this supersedes other options and is intended as a performance optimization option */
+ /// Indicates that the strings to be compared have been preprocessed; this supersedes other options and is intended as a performance optimization option.
+ NSNormalizedPredicateOption API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0)) = 0x04,
};
-// Describes how the operator is modified: can be direct, ALL, or ANY
+/// Constants that describe the possible types of modifier for a comparison predicate.
typedef NS_ENUM(NSUInteger, NSComparisonPredicateModifier) {
- NSDirectPredicateModifier = 0, // Do a direct comparison
- NSAllPredicateModifier, // ALL toMany.x = y
- NSAnyPredicateModifier // ANY toMany.x = y
+ /// A predicate to compare directly the left and right hand sides.
+ NSDirectPredicateModifier = 0,
+ /// A predicate to compare all entries in the destination of a to-many relationship.
+ NSAllPredicateModifier,
+ /// A predicate to match with any entry in the destination of a to-many relationship.
+ NSAnyPredicateModifier
};
-// Type basic set of operators defined. Most are obvious; NSCustomSelectorPredicateOperatorType allows a developer to create an operator which uses the custom selector specified in the constructor to do the evaluation.
+/// Defines the type of comparison for a comparison predicate.
typedef NS_ENUM(NSUInteger, NSPredicateOperatorType) {
- NSLessThanPredicateOperatorType = 0, // compare: returns NSOrderedAscending
- NSLessThanOrEqualToPredicateOperatorType, // compare: returns NSOrderedAscending || NSOrderedSame
- NSGreaterThanPredicateOperatorType, // compare: returns NSOrderedDescending
- NSGreaterThanOrEqualToPredicateOperatorType, // compare: returns NSOrderedDescending || NSOrderedSame
- NSEqualToPredicateOperatorType, // isEqual: returns true
- NSNotEqualToPredicateOperatorType, // isEqual: returns false
+ /// A less-than predicate.
+ NSLessThanPredicateOperatorType = 0,
+ /// A less-than-or-equal-to predicate.
+ NSLessThanOrEqualToPredicateOperatorType,
+ /// A greater-than predicate.
+ NSGreaterThanPredicateOperatorType,
+ /// A greater-than-or-equal-to predicate.
+ NSGreaterThanOrEqualToPredicateOperatorType,
+ /// An equal-to predicate.
+ NSEqualToPredicateOperatorType,
+ /// A not-equal-to predicate.
+ NSNotEqualToPredicateOperatorType,
+ /// A full regular expression matching predicate.
NSMatchesPredicateOperatorType,
+ /// A simple subset of the `MATCHES` predicate, similar in behavior to SQL `LIKE`.
NSLikePredicateOperatorType,
+ /// A begins-with predicate.
NSBeginsWithPredicateOperatorType,
+ /// An ends-with predicate.
NSEndsWithPredicateOperatorType,
- NSInPredicateOperatorType, // rhs contains lhs returns true
+ /// A predicate to determine if the left hand side is in the right hand side. For strings, returns `YES` if the left hand side is a substring of the right hand side. For collections, returns `YES` if the left hand side is in the right hand side.
+ NSInPredicateOperatorType,
+ /// A predicate that uses a custom selector that takes a single argument and returns a `BOOL` value. The selector is invoked on the left hand side with the right hand side as the argument.
NSCustomSelectorPredicateOperatorType,
- NSContainsPredicateOperatorType API_AVAILABLE(macos(10.5), ios(3.0), watchos(2.0), tvos(9.0)) = 99, // lhs contains rhs returns true
+ /// A predicate to determine if the left hand side contains the right hand side. Returns `YES` if `[lhs contains rhs]`; the left hand side must be an `NSExpression` object that evaluates to a collection.
+ NSContainsPredicateOperatorType API_AVAILABLE(macos(10.5), ios(3.0), watchos(2.0), tvos(9.0)) = 99,
+ /// A predicate to determine if the left hand side lies at or between bounds specified by the right hand side. The right hand side must be an array in which the first element sets the lower bound and the second element the upper, inclusive.
NSBetweenPredicateOperatorType API_AVAILABLE(macos(10.5), ios(3.0), watchos(2.0), tvos(9.0))
};
@class NSPredicateOperator;
@class NSExpression;
-// Comparison predicates are predicates which do some form of comparison between the results of two expressions and return a BOOL. They take an operator, a left expression, and a right expression, and return the result of invoking the operator with the results of evaluating the expressions.
+/// A specialized predicate for comparing expressions.
+///
+/// Use comparison predicates to compare the results of two expressions. You create a comparison predicate with an operator, a left expression, and a right expression, and use instances of the ``NSExpression`` class to represent those expressions. When you evaluate the predicate, it returns a `BOOL` value as the result of invoking the operator with the results of evaluating the expressions.
API_AVAILABLE(macos(10.4), ios(3.0), watchos(2.0), tvos(9.0))
@interface NSComparisonPredicate : NSPredicate
+/// Creates and returns a predicate of a given type formed by combining given left and right expressions using a given modifier and options.
+/// - Parameters:
+/// - lhs: The left hand expression.
+/// - rhs: The right hand expression.
+/// - modifier: The modifier to apply.
+/// - type: The predicate operator type.
+/// - options: The options to apply. For no options, pass `0`.
+/// - Returns: A new predicate of type `type` formed by combining the given left and right expressions using the `modifier` and `options`.
+ (NSComparisonPredicate *)predicateWithLeftExpression:(NSExpression *)lhs rightExpression:(NSExpression *)rhs modifier:(NSComparisonPredicateModifier)modifier type:(NSPredicateOperatorType)type options:(NSComparisonPredicateOptions)options;
+/// Returns a new predicate formed by combining the left and right expressions using a given selector.
+/// - Parameters:
+/// - lhs: The left hand side expression.
+/// - rhs: The right hand side expression.
+/// - selector: The selector to use for comparison. The method defined by the selector must take a single argument and return a `BOOL` value.
+/// - Returns: A new predicate formed by combining the left and right expressions using `selector`.
+ (NSComparisonPredicate *)predicateWithLeftExpression:(NSExpression *)lhs rightExpression:(NSExpression *)rhs customSelector:(SEL)selector;
+/// Creates a predicate to a specified type that you form by combining specified left and right expressions using a specified modifier and options.
+/// - Parameters:
+/// - lhs: The left hand expression.
+/// - rhs: The right hand expression.
+/// - modifier: The modifier to apply.
+/// - type: The predicate operator type.
+/// - options: The options to apply. For no options, pass `0`.
+/// - Returns: The receiver, initialized to a predicate of type `type` formed by combining the left and right expressions using the `modifier` and `options`.
- (instancetype)initWithLeftExpression:(NSExpression *)lhs rightExpression:(NSExpression *)rhs modifier:(NSComparisonPredicateModifier)modifier type:(NSPredicateOperatorType)type options:(NSComparisonPredicateOptions)options NS_DESIGNATED_INITIALIZER;
+/// Creates a predicate that you form by combining specified left and right expressions using a specified selector.
+/// - Parameters:
+/// - lhs: The left hand expression.
+/// - rhs: The right hand expression.
+/// - selector: The selector to use. The method defined by the selector must take a single argument and return a `BOOL` value.
+/// - Returns: The receiver, initialized by combining the left and right expressions using `selector`.
- (instancetype)initWithLeftExpression:(NSExpression *)lhs rightExpression:(NSExpression *)rhs customSelector:(SEL)selector NS_DESIGNATED_INITIALIZER;
+/// Creates a predicate by decoding from the coder you specify.
+/// - Parameter coder: The coder to read data from.
- (nullable instancetype)initWithCoder:(NSCoder *)coder NS_DESIGNATED_INITIALIZER;
+/// The predicate type for the receiver.
@property (readonly) NSPredicateOperatorType predicateOperatorType;
+/// The comparison predicate modifier for the receiver. The default value is `NSDirectPredicateModifier`.
@property (readonly) NSComparisonPredicateModifier comparisonPredicateModifier;
+/// The left expression for the receiver.
@property (readonly, retain) NSExpression *leftExpression;
+/// The right expression for the receiver.
@property (readonly, retain) NSExpression *rightExpression;
+/// The selector for the receiver, or `NULL` if there is none.
@property (nullable, readonly) SEL customSelector;
+/// The options to use for the receiver.
@property (readonly) NSComparisonPredicateOptions options;
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCompoundPredicate.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCompoundPredicate.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCompoundPredicate.h 2026-04-18 19:07:15
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSCompoundPredicate.h 2026-05-27 00:01:41
@@ -10,24 +10,52 @@
// Compound predicates are predicates which act on the results of evaluating other operators. We provide the basic boolean operators: AND, OR, and NOT.
+/// Constants that describe the possible types of a compound predicate.
typedef NS_ENUM(NSUInteger, NSCompoundPredicateType) {
- NSNotPredicateType = 0,
+ /// A logical NOT predicate.
+ NSNotPredicateType = 0,
+ /// A logical AND predicate.
NSAndPredicateType,
+ /// A logical OR predicate.
NSOrPredicateType,
};
+/// A specialized predicate that evaluates logical combinations of other predicates.
+///
+/// Use ``NSCompoundPredicate`` to create an `AND` or `OR` compound predicate of one or more other predicates, or the `NOT` of a single predicate. For the logical `AND` and `OR` operations:
+///
+/// - An `AND` predicate with no subpredicates evaluates to <doc://com.apple.documentation/documentation/swift/true>.
+/// - An `OR` predicate with no subpredicates evaluates to <doc://com.apple.documentation/documentation/swift/false>.
+/// - A compound predicate with one or more subpredicates evaluates to the truth of its subpredicates.
API_AVAILABLE(macos(10.4), ios(3.0), watchos(2.0), tvos(9.0))
@interface NSCompoundPredicate : NSPredicate
+/// Returns the receiver that a specified type initializes using predicates from a specified array.
+///
+/// For applications linked on macOS 10.5 or later, the `subpredicates` array is copied. For applications linked on OS X v10.4, the `subpredicates` array is retained (for binary compatibility).
- (instancetype)initWithType:(NSCompoundPredicateType)type subpredicates:(NSArray<NSPredicate *> *)subpredicates NS_DESIGNATED_INITIALIZER;
+/// Creates a predicate by decoding from the coder you specify.
- (nullable instancetype)initWithCoder:(NSCoder *)coder NS_DESIGNATED_INITIALIZER;
+/// The predicate type for the receiver.
@property (readonly) NSCompoundPredicateType compoundPredicateType;
+/// The receiver's subpredicates.
@property (readonly, copy) NSArray *subpredicates;
/*** Convenience Methods ***/
+/// Returns a new predicate that you form using an AND operation on the predicates in a specified array.
+///
+/// - Parameters:
+/// - subpredicates: An array of `NSPredicate` objects.
+/// - Returns: A new predicate formed by AND-ing the predicates specified by `subpredicates`.
+///
+/// An AND predicate with no subpredicates evaluates to TRUE.
+ (NSCompoundPredicate *)andPredicateWithSubpredicates:(NSArray<NSPredicate *> *)subpredicates NS_SWIFT_NAME(init(andPredicateWithSubpredicates:));
+/// Returns a new predicate that you form using an OR operation on the predicates in a specified array.
+///
+/// An OR predicate with no subpredicates evaluates to FALSE.
+ (NSCompoundPredicate *)orPredicateWithSubpredicates:(NSArray<NSPredicate *> *)subpredicates NS_SWIFT_NAME(init(orPredicateWithSubpredicates:));
+/// Returns a new predicate that you form using a NOT operation on a specified predicate.
+ (NSCompoundPredicate *)notPredicateWithSubpredicate:(NSPredicate *)predicate NS_SWIFT_NAME(init(notPredicateWithSubpredicate:));
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSData.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSData.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSData.h 2026-04-18 22:35:18
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSData.h 2026-05-27 00:11:58
@@ -9,166 +9,488 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
-/**************** Read/Write Options ****************/
+/* *************** Read/Write Options ****************/
+/// Options for methods used to read data objects.
typedef NS_OPTIONS(NSUInteger, NSDataReadingOptions) {
- NSDataReadingMappedIfSafe = 1UL << 0, // Hint to map the file in if possible and safe
- NSDataReadingUncached = 1UL << 1, // Hint to get the file not to be cached in the kernel
- NSDataReadingMappedAlways API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) = 1UL << 3, // Hint to map the file in if possible. This takes precedence over NSDataReadingMappedIfSafe if both are given.
-
- // Options with old names for NSData reading methods. Please stop using these old names.
- NSDataReadingMapped API_DEPRECATED_WITH_REPLACEMENT("NSDataReadingMappedIfSafe", 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)) = NSDataReadingMappedIfSafe, // Deprecated name for NSDataReadingMappedIfSafe
- NSMappedRead API_DEPRECATED_WITH_REPLACEMENT("NSDataReadingMapped", 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)) = NSDataReadingMapped, // Deprecated name for NSDataReadingMapped
- NSUncachedRead API_DEPRECATED_WITH_REPLACEMENT("NSDataReadingUncached", 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)) = NSDataReadingUncached // Deprecated name for NSDataReadingUncached
+ /// A hint indicating the file should be mapped into virtual memory, if possible and safe.
+ NSDataReadingMappedIfSafe = 1UL << 0,
+ /// A hint indicating the file should not be stored in the file-system caches.
+ ///
+ /// For data being read once and discarded, this option can improve performance.
+ NSDataReadingUncached = 1UL << 1,
+ /// Hint to map the file in if possible.
+ ///
+ /// This takes precedence over `NSDataReadingMappedIfSafe` if both are given.
+ NSDataReadingMappedAlways API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) = 1UL << 3,
+
+ /// Deprecated name for `NSDataReadingMappedIfSafe`.
+ NSDataReadingMapped API_DEPRECATED_WITH_REPLACEMENT("NSDataReadingMappedIfSafe", 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)) = NSDataReadingMappedIfSafe,
+ /// Deprecated name for `NSDataReadingMapped`.
+ NSMappedRead API_DEPRECATED_WITH_REPLACEMENT("NSDataReadingMapped", 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)) = NSDataReadingMapped,
+ /// Deprecated name for `NSDataReadingUncached`.
+ NSUncachedRead API_DEPRECATED_WITH_REPLACEMENT("NSDataReadingUncached", 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)) = NSDataReadingUncached
};
+/// Options for methods used to write data objects.
typedef NS_OPTIONS(NSUInteger, NSDataWritingOptions) {
- NSDataWritingAtomic = 1UL << 0, // Hint to use auxiliary file when saving; equivalent to atomically:YES
- NSDataWritingWithoutOverwriting API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) = 1UL << 1, // Hint to prevent overwriting an existing file. Cannot be combined with NSDataWritingAtomic.
+ /// An option to write data to an auxiliary file first and then replace the original file with the auxiliary file when the write completes.
+ ///
+ /// This option is equivalent to using a write method that takes the parameter `atomically` as `YES`.
+ NSDataWritingAtomic = 1UL << 0,
+ /// An option that attempts to write data to a file and fails with an error if the destination file already exists.
+ ///
+ /// You can't combine this constant with `NSDataWritingAtomic` because atomic allows the system to overwrite the original file.
+ NSDataWritingWithoutOverwriting API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0)) = 1UL << 1,
+ /// An option to not encrypt the file when writing it out.
+ ///
+ /// The system doesn't store the file in an encrypted format and your app can access this file at boot time and while the device is unlocked.
NSDataWritingFileProtectionNone API_AVAILABLE(macos(11.0), ios(4.0), watchos(2.0), tvos(9.0)) = 0x10000000,
+ /// An option to make the file accessible only while the device is unlocked.
+ ///
+ /// The system stores the file in an encrypted format and your app may only read or write to the file while the device is unlocked. At all other times, any attempts your app makes to read and write the file will fail.
NSDataWritingFileProtectionComplete API_AVAILABLE(macos(11.0), ios(4.0), watchos(2.0), tvos(9.0)) = 0x20000000,
+ /// An option to allow the file to be accessible while the device is unlocked or the file is already open.
+ ///
+ /// Your app cannot open the file to read it or write to it when the device is locked, but your app can create new files with this class. If one of these files is open when the device is locked, your app can read and write to the opened file.
NSDataWritingFileProtectionCompleteUnlessOpen API_AVAILABLE(macos(11.0), ios(5.0), watchos(2.0), tvos(9.0)) = 0x30000000,
+ /// An option to allow the file to be accessible after a user first unlocks the device.
+ ///
+ /// The app can read or write to the file while the device is unlocked, but while it's booting up, the file has the protection equivalent to `NSDataWritingFileProtectionComplete`.
NSDataWritingFileProtectionCompleteUntilFirstUserAuthentication API_AVAILABLE(macos(11.0), ios(5.0), watchos(2.0), tvos(9.0)) = 0x40000000,
NSDataWritingFileProtectionCompleteWhenUserInactive API_AVAILABLE(ios(17.0), watchos(10.0), tvos(17.0)) API_UNAVAILABLE(macos) = 0x50000000,
+ /// An option the system uses when determining the file protection options that the system assigns to the data.
NSDataWritingFileProtectionMask API_AVAILABLE(macos(11.0), ios(4.0), watchos(2.0), tvos(9.0)) = 0xf0000000,
- // Options with old names for NSData writing methods. Please stop using these old names.
- NSAtomicWrite API_DEPRECATED_WITH_REPLACEMENT("NSDataWritingAtomic", 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)) = NSDataWritingAtomic // Deprecated name for NSDataWritingAtomic
+ /// An option that attempts to write data to an auxiliary file first and then exchange the files.
+ ///
+ /// @DeprecationSummary {
+ /// Use `NSDataWritingAtomic` instead.
+ /// }
+ NSAtomicWrite API_DEPRECATED_WITH_REPLACEMENT("NSDataWritingAtomic", 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)) = NSDataWritingAtomic
};
-/**************** Data Search Options ****************/
+/* *************** Data Search Options ****************/
+/// Options for method used to search data objects.
+///
+/// These options are used with the ``NSData/range(of:options:in:)`` method.
typedef NS_OPTIONS(NSUInteger, NSDataSearchOptions) {
+ /// Search from the end of the data object.
NSDataSearchBackwards = 1UL << 0,
+ /// Search is limited to start (or end, if searching backwards) of the data object.
+ ///
+ /// This option performs searching only on bytes at the beginning of the range (or the end when using `NSDataSearchBackwards`). No match at the beginning or end means nothing is found, even if a matching sequence of bytes occurs elsewhere in the data object.
NSDataSearchAnchored = 1UL << 1
} API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
-/**************** Base 64 Options ****************/
+/* *************** Base 64 Options ****************/
+/// Options for methods used to Base64 encode data.
typedef NS_OPTIONS(NSUInteger, NSDataBase64EncodingOptions) {
- // Use zero or one of the following to control the maximum line length after which a line ending is inserted. No line endings are inserted by default.
+ /// Set the maximum line length to 64 characters, after which a line ending is inserted.
NSDataBase64Encoding64CharacterLineLength = 1UL << 0,
+ /// Set the maximum line length to 76 characters, after which a line ending is inserted.
NSDataBase64Encoding76CharacterLineLength = 1UL << 1,
- // Use zero or more of the following to specify which kind of line ending is inserted. The default line ending is CR LF.
+ /// When a maximum line length is set, specify that the line ending to insert should include a carriage return.
NSDataBase64EncodingEndLineWithCarriageReturn = 1UL << 4,
+ /// When a maximum line length is set, specify that the line ending to insert should include a line feed.
NSDataBase64EncodingEndLineWithLineFeed = 1UL << 5,
} API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
+/// Options to modify the decoding algorithm used to decode Base64 encoded data.
typedef NS_OPTIONS(NSUInteger, NSDataBase64DecodingOptions) {
- // Use the following option to modify the decoding algorithm so that it ignores unknown non-Base64 bytes, including line ending characters.
+ /// Modify the decoding algorithm so that it ignores unknown non-Base-64 bytes, including line ending characters.
NSDataBase64DecodingIgnoreUnknownCharacters = 1UL << 0
} API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
-/**************** Immutable Data ****************/
+/* *************** Immutable Data ****************/
+/// A static byte buffer in memory.
+///
+/// In Swift, the buffer bridges to ``Data``; use ``NSData`` when you need reference semantics or other Foundation-specific behavior.
+///
+/// [NSData](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/OldStylePlists/OldStylePLists.html#//apple_ref/doc/uid/20001012-47169) and its mutable subclass ``NSMutableData`` provide data objects, or object-oriented wrappers for byte buffers. Data objects let simple allocated buffers (that is, data with no embedded pointers) take on the behavior of Foundation objects.
+///
+/// The size of the data is subject to a theoretical limit of about 8 exabytes (1 EB = 10^18 bytes; in practice, the limit should not be a factor).
+///
+/// [NSData](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/OldStylePlists/OldStylePLists.html#//apple_ref/doc/uid/20001012-47169) is _toll-free bridged_ with its Core Foundation counterpart, `CFData`. 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 ``Data`` structure, which bridges to the ``NSData`` class and its mutable subclass ``NSMutableData``. For more information about value types, see [Working with Foundation Types](https://developer.apple.com/documentation/swift/working-with-foundation-types).
+///
+/// ### Writing Data Atomically
+///
+/// [NSData](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/OldStylePlists/OldStylePLists.html#//apple_ref/doc/uid/20001012-47169) provides methods for atomically saving their contents to a file, which guarantee that the data is either saved in its entirety, or it fails completely. An atomic write first writes the data to a temporary file and then, only if this write succeeds, moves the temporary file to its final location.
+///
+/// Although atomic write operations minimize the risk of data loss due to corrupt or partially written files, they may not be appropriate when writing to a temporary directory, the user's home directory or other publicly accessible directories. When you work with a publicly accessible file, treat that file as an untrusted and potentially dangerous resource. An attacker may compromise or corrupt these files. The attacker can also replace the files with hard or symbolic links, causing your write operations to overwrite or corrupt other system resources.
+///
+/// Avoid using the ``write(to:atomically:)`` method (and the related methods) when working inside a publicly accessible directory. Instead, use ``FileHandle`` with an existing file descriptor to securely write the file.
+///
+/// For more information, see [Securing File Operations](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Articles/RaceConditions.html#//apple_ref/doc/uid/TP40002585-SW9) in [Secure Coding Guide](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Introduction.html#//apple_ref/doc/uid/TP40002415).
@interface NSData : NSObject <NSCopying, NSMutableCopying, NSSecureCoding>
+/// The number of bytes contained by the data object.
@property (readonly) NSUInteger length;
-/*
- The -bytes method returns a pointer to a contiguous region of memory managed by the receiver.
- If the regions of memory represented by the receiver are already contiguous, it does so in O(1) time, otherwise it may take longer
- Using -enumerateByteRangesUsingBlock: will be efficient for both contiguous and discontiguous data.
- */
+/// A pointer to the data object's contents.
+///
+/// If the ``NSData/length`` of the [NSData](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/OldStylePlists/OldStylePLists.html#//apple_ref/doc/uid/20001012-47169) object is 0, this property returns `nil`.
+///
+/// For an immutable data object, the returned pointer is valid until the data object is deallocated. For a mutable data object, the returned pointer is valid until the data object is deallocated or the data is mutated.
@property (readonly) const void *bytes NS_RETURNS_INNER_POINTER;
@end
@interface NSData (NSExtendedData)
+/// A string that contains a hexadecimal representation of the data object's contents in a property list format.
@property (readonly, copy) NSString *description;
+/// Copies a number of bytes from the start of the data object into a given buffer.
+///
+/// The number of bytes copied is the smaller of the `length` parameter and the ``NSData/length`` of the data encapsulated in the object.
+/// - Parameters:
+/// - buffer: A buffer into which to copy data.
+/// - length: The number of bytes from the start of the receiver's data to copy to `buffer`.
- (void)getBytes:(void *)buffer length:(NSUInteger)length;
+/// Copies a range of bytes from the data object into a given buffer.
+///
+/// If `range` isn't within the receiver's range of bytes, an ``NSExceptionName/rangeException`` is raised.
+/// - Parameters:
+/// - buffer: A buffer into which to copy data.
+/// - range: The range of bytes in the receiver's data to copy to `buffer`. The range must lie within the range of bytes of the receiver's data.
- (void)getBytes:(void *)buffer range:(NSRange)range;
+/// Returns a Boolean value indicating whether this data object is the same as another.
+///
+/// Two data objects are equal if they hold the same number of bytes, and if the bytes at the same position in the objects are the same.
+/// - Parameter other: The data object with which to compare the receiver.
+/// - Returns: `YES` if the contents of `otherData` are equal to the contents of the receiver, otherwise `NO`.
- (BOOL)isEqualToData:(NSData *)other;
+/// Returns a new data object containing the data object's bytes that fall within the limits specified by a given range.
+///
+/// A sample using this method can be found in [Working With Binary Data](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/BinaryData/Tasks/WorkingBinaryData.html#//apple_ref/doc/uid/20000717).
+/// - Parameter range: The range in the receiver from which to get the data. If this range is not within the data object's range of bytes, ``NSExceptionName/rangeException`` is raised.
+/// - Returns: A data object containing the receiver's bytes that fall within the limits specified by `range`.
- (NSData *)subdataWithRange:(NSRange)range;
+/// Writes the data object's bytes to the file specified by a given path.
+///
+/// This method may not be appropriate when writing to publicly accessible files. To securely write data to a public location, use ``FileHandle`` instead. For more information, see [Securing File Operations](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Articles/RaceConditions.html#//apple_ref/doc/uid/TP40002585-SW9) in [Secure Coding Guide](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Introduction.html#//apple_ref/doc/uid/TP40002415).
+/// - Parameters:
+/// - path: The location to which to write the receiver's bytes. If `path` contains a tilde (~) character, you must expand it with ``NSString/expandingTildeInPath`` before invoking this method.
+/// - useAuxiliaryFile: If `YES`, the data is written to a backup file, and then--assuming no errors occur--the backup file is renamed to the name specified by `path`; otherwise, the data is written directly to `path`.
+/// - Returns: `YES` if the operation succeeds, otherwise `NO`.
- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile;
+/// Writes the data object's bytes to the location specified by a given URL.
+///
+/// Since at present only `file://` URLs are supported, there is no difference between this method and ``NSData/write(toFile:atomically:)``, except for the type of the first argument.
+///
+/// This method may not be appropriate when writing to publicly accessible files. To securely write data to a public location, use ``FileHandle`` instead. For more information, see [Securing File Operations](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Articles/RaceConditions.html#//apple_ref/doc/uid/TP40002585-SW9) in [Secure Coding Guide](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Introduction.html#//apple_ref/doc/uid/TP40002415).
+/// - Parameters:
+/// - url: The location to which to write the receiver's bytes. Only `file://` URLs are supported.
+/// - atomically: If `YES`, the data is written to a backup location, and then--assuming no errors occur--the backup location is renamed to the name specified by `aURL`; otherwise, the data is written directly to `aURL`. `atomically` is ignored if `aURL` is not of a type the supports atomic writes.
+/// - Returns: `YES` if the operation succeeds, otherwise `NO`.
- (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)atomically; // the atomically flag is ignored if the url is not of a type the supports atomic writes
+/// Writes the data object's bytes to the file specified by a given path.
+///
+/// This method may not be appropriate when writing to publicly accessible files. To securely write data to a public location, use ``FileHandle`` instead. For more information, see [Securing File Operations](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Articles/RaceConditions.html#//apple_ref/doc/uid/TP40002585-SW9) in [Secure Coding Guide](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Introduction.html#//apple_ref/doc/uid/TP40002415).
+/// - Parameters:
+/// - path: The location to which to write the receiver's bytes.
+/// - writeOptionsMask: A mask that specifies options for writing the data. Constant components are described in ``NSData/WritingOptions``.
+/// - errorPtr: If there is an error writing out the data, upon return contains an error object that describes the problem.
+/// - Returns: `YES` if the operation succeeds, otherwise `NO`.
- (BOOL)writeToFile:(NSString *)path options:(NSDataWritingOptions)writeOptionsMask error:(NSError **)errorPtr;
+/// Writes the data object's bytes to the location specified by a given URL.
+///
+/// Since at present only `file://` URLs are supported, there is no difference between this method and ``NSData/write(toFile:options:)``, except for the type of the first argument.
+///
+/// This method may not be appropriate when writing to publicly accessible files. To securely write data to a public location, use ``FileHandle`` instead. For more information, see [Securing File Operations](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Articles/RaceConditions.html#//apple_ref/doc/uid/TP40002585-SW9) in [Secure Coding Guide](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Introduction.html#//apple_ref/doc/uid/TP40002415).
+/// - Parameters:
+/// - url: The location to which to write the receiver's bytes.
+/// - writeOptionsMask: A mask that specifies options for writing the data. Constant components are described in ``NSData/WritingOptions``.
+/// - errorPtr: If there is an error writing out the data, upon return contains an error object that describes the problem.
+/// - Returns: `YES` if the operation succeeds, otherwise `NO`.
- (BOOL)writeToURL:(NSURL *)url options:(NSDataWritingOptions)writeOptionsMask error:(NSError **)errorPtr;
+/// Finds and returns the range of the first occurrence of the given data, within the given range, subject to given options.
+///
+/// - Parameters:
+/// - dataToFind: The data for which to search.
+/// - mask: A mask specifying search options. The ``NSData/SearchOptions`` options may be specified singly or by combining them with the C bitwise `OR` operator.
+/// - searchRange: The range within the receiver in which to search for `dataToFind`. If this range is not within the data object's range of bytes, ``NSExceptionName/rangeException`` is raised.
+/// - Returns: An `NSRange` structure giving the location and length of `dataToFind` within `searchRange`, modulo the options in `mask`. The range returned is relative to the start of the searched data, not the passed-in search range. Returns `{NSNotFound, 0}` if `dataToFind` is not found or is empty.
- (NSRange)rangeOfData:(NSData *)dataToFind options:(NSDataSearchOptions)mask range:(NSRange)searchRange API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
-/*
- 'block' is called once for each contiguous region of memory in the receiver (once total for contiguous NSDatas), until either all bytes have been enumerated, or the 'stop' parameter is set to YES.
- */
+/// Enumerates each range of bytes in the data object using a block.
+///
+/// The enumeration block is called once for each contiguous region of memory in the receiver (once total for a contiguous [NSData](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/OldStylePlists/OldStylePLists.html#//apple_ref/doc/uid/20001012-47169) object), until either all bytes have been enumerated, or the `stop` parameter is set to `YES`.
+/// - Parameter block: The block to apply to byte ranges in the array. The block takes three arguments:
+/// - `bytes`: The bytes for the current range. This pointer is valid until the data object is deallocated.
+/// - `byteRange`: The range of the current data bytes.
+/// - `stop`: A reference to a Boolean value. The block can set the value to `YES` to stop further processing of the data. The stop argument is an out-only argument. You should only ever set this Boolean to `YES` within the Block.
- (void) enumerateByteRangesUsingBlock:(void (NS_NOESCAPE ^)(const void *bytes, NSRange byteRange, BOOL *stop))block API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
@end
@interface NSData (NSDataCreation)
+/// Creates an empty data object.
+///
+/// This method is declared primarily for the use of mutable subclasses of [NSData](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/OldStylePlists/OldStylePLists.html#//apple_ref/doc/uid/20001012-47169).
+ (instancetype)data;
+/// Creates a data object containing a given number of bytes copied from a given buffer.
+///
+/// - Parameters:
+/// - bytes: A buffer containing data for the new object.
+/// - length: The number of bytes to copy from `bytes`. This value must not exceed the length of `bytes`.
+ (instancetype)dataWithBytes:(nullable const void *)bytes length:(NSUInteger)length;
+/// Creates a data object that holds a given number of bytes from a given buffer.
+///
+/// The returned object takes ownership of the `bytes` pointer and frees it on deallocation. Therefore, `bytes` must point to a memory block allocated with `malloc`.
+/// - Parameters:
+/// - bytes: A buffer containing data for the new object. `bytes` must point to a memory block allocated with `malloc`.
+/// - length: The number of bytes to hold from `bytes`. This value must not exceed the length of `bytes`.
+ (instancetype)dataWithBytesNoCopy:(void *)bytes length:(NSUInteger)length;
+/// Creates a data object that holds a given number of bytes from a given buffer.
+///
+/// - Parameters:
+/// - bytes: A buffer containing data for the new object. If `freeWhenDone` is `YES`, `bytes` must point to a memory block allocated with `malloc`.
+/// - length: The number of bytes to hold from `bytes`. This value must not exceed the length of `bytes`.
+/// - b: If `YES`, the returned object takes ownership of the `bytes` pointer and frees it on deallocation.
+ (instancetype)dataWithBytesNoCopy:(void *)bytes length:(NSUInteger)length freeWhenDone:(BOOL)b;
+/// Creates a data object by reading every byte from the file at a given path.
+///
+/// This method returns `nil` if the data object could not be created. In this case, `errorPtr` will contain an ``NSError`` indicating the problem.
+/// - Parameters:
+/// - path: The absolute path of the file from which to read data.
+/// - readOptionsMask: A mask that specifies options for reading the data. Constant components are described in ``NSData/ReadingOptions``.
+/// - errorPtr: If an error occurs, upon return contains an error object that describes the problem.
+ (nullable instancetype)dataWithContentsOfFile:(NSString *)path options:(NSDataReadingOptions)readOptionsMask error:(NSError **)errorPtr;
+/// Creates a data object from the data at the provided file URL using specific reading options.
+///
+/// > Important:
+/// > As this method runs synchronously and blocks the calling thread until it finishes, don't invoke it from the main thread. Use file coordination or one of the nonblocking file-related APIs instead.
+/// - Parameters:
+/// - url: The location on disk of the data to read.
+/// - readOptionsMask: The mask specifying the options to use when reading the data. For more information, see ``NSData/ReadingOptions``.
+/// - errorPtr: `nil` if the data is read; otherwise, an error object describing the failure.
+/// - Returns: A data object that contains the file's data, or `nil` if the system can't create one.
+ (nullable instancetype)dataWithContentsOfURL:(NSURL *)url options:(NSDataReadingOptions)readOptionsMask error:(NSError **)errorPtr;
+/// Creates a data object by reading every byte from the file at a given path.
+///
+/// This method returns `nil` if the data object could not be created. If you need to know the reason for failure, use ``NSData/dataWithContentsOfFile:options:error:``.
+///
+/// This method is equivalent to calling ``NSData/dataWithContentsOfFile:options:error:`` and passing no options.
+///
+/// A sample using this method can be found in [Working With Binary Data](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/BinaryData/Tasks/WorkingBinaryData.html#//apple_ref/doc/uid/20000717).
+/// - Parameter path: The absolute path of the file from which to read data.
+ (nullable instancetype)dataWithContentsOfFile:(NSString *)path;
+/// Creates a data object from the data at the specified file URL.
+///
+/// > Important:
+/// > As this method runs synchronously and blocks the calling thread until it finishes, don't invoke it from the main thread. Use file coordination or one of the nonblocking file-related APIs instead.
+///
+/// If you specify a malformed URL or the referenced location doesn't exist on disk, the initializer fails and returns `nil`. To handle such errors, use ``NSData/init(contentsOfURL:options:)-95rht`` instead.
+/// - Parameter url: The location on disk of the data to read.
+/// - Returns: A data object that contains the file's data, or `nil` if the system can't create one.
+ (nullable instancetype)dataWithContentsOfURL:(NSURL *)url;
+/// Initializes a data object filled with a given number of bytes copied from a given buffer.
+///
+/// A data object initialized by adding to it `length` bytes of data copied from the buffer `bytes`. The returned object might be different than the original receiver.
- (instancetype)initWithBytes:(nullable const void *)bytes length:(NSUInteger)length;
+/// Initializes a data object filled with a given number of bytes of data from a given buffer.
+///
+/// The returned object takes ownership of the `bytes` pointer and frees it on deallocation. Therefore, `bytes` must point to a memory block allocated with `malloc`.
+/// - Parameters:
+/// - bytes: A buffer containing data for the new object. `bytes` must point to a memory block allocated with `malloc`.
+/// - length: The number of bytes to hold from `bytes`. This value must not exceed the length of `bytes`.
+/// - Returns: A data object initialized by adding to it `length` bytes of data from the buffer `bytes`. The returned object might be different than the original receiver.
- (instancetype)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)length;
+/// Initializes a newly allocated data object by adding the given number of bytes from the given buffer.
+///
+/// - Parameters:
+/// - bytes: A buffer containing data for the new object. If `flag` is `YES`, `bytes` must point to a memory block allocated with `malloc`.
+/// - length: The number of bytes to hold from `bytes`. This value must not exceed the length of `bytes`.
+/// - b: If `YES`, the returned object takes ownership of the `bytes` pointer and frees it on deallocation.
- (instancetype)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)length freeWhenDone:(BOOL)b;
+/// Initializes a data object filled with a given number of bytes of data from a given buffer, with a custom deallocator block.
+///
+/// Use this method to define your own deallocation behavior for the data buffer you provide.
+///
+/// In order to avoid any inadvertent strong reference cycles, you should avoid capturing pointers to any objects that may in turn maintain strong references to the `NSData` object. This includes explicit references to `self`, and implicit references to `self` due to direct instance variable access. To make it easier to avoid these references, the `deallocator` block takes two parameters, a pointer to the `buffer`, and its length; you should always use these values instead of trying to use references from outside the block.
+/// - Parameters:
+/// - bytes: A buffer containing data for the new object.
+/// - length: The number of bytes to hold from `bytes`. This value must not exceed the length of `bytes`.
+/// - deallocator: A block to invoke when the resulting `NSData` object is deallocated.
+/// - Returns: A data object initialized by adding to it `length` bytes of data from the buffer `bytes`. The returned object might be different than the original receiver.
- (instancetype)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)length deallocator:(nullable void (^)(void *bytes, NSUInteger length))deallocator API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
+/// Initializes a data object with the content of the file at a given path.
+///
+/// This method is equivalent to ``NSData/init(contentsOfFile:options:)`` with no options.
+/// - Parameter path: The absolute path of the file from which to read data.
+/// - Returns: A data object initialized by reading into it the data from the file specified by `path`.
- (nullable instancetype)initWithContentsOfFile:(NSString *)path options:(NSDataReadingOptions)readOptionsMask error:(NSError **)errorPtr;
+/// Creates a data object from the data at the provided file URL using specific reading options.
+///
+/// > Important:
+/// > As this method runs synchronously and blocks the calling thread until it finishes, don't invoke it from the main thread. Use file coordination or one of the nonblocking file-related APIs instead.
+///
+/// If the system can't create an instance, the initializer may throw in Swift, or return `nil` in Objective-C.
+/// - Parameters:
+/// - url: The location on disk of the data to read.
+/// - readOptionsMask: The mask specifying the options to use when reading the data. For more information, see ``NSData/ReadingOptions``.
+/// - errorPtr: `nil` if the data is read; otherwise, an error object describing the failure.
- (nullable instancetype)initWithContentsOfURL:(NSURL *)url options:(NSDataReadingOptions)readOptionsMask error:(NSError **)errorPtr;
+/// Initializes a data object with the content of the file at a given path.
+///
+/// This method is equivalent to ``NSData/init(contentsOfFile:options:)`` with no options.
+/// - Parameter path: The absolute path of the file from which to read data.
+/// - Returns: A data object initialized by reading into it the data from the file specified by `path`.
- (nullable instancetype)initWithContentsOfFile:(NSString *)path;
+/// Creates a data object from the data at the specified file URL, or returns `nil` if the system can't create one.
+///
+/// > Important:
+/// > As this method runs synchronously and blocks the calling thread until it finishes, don't invoke it from the main thread. Use file coordination or one of the nonblocking file-related APIs instead.
+///
+/// If you specify a malformed URL or the referenced location doesn't exist on disk, the initializer fails and returns `nil`. To handle such errors, use ``NSData/init(contentsOfURL:options:)-5abi3`` instead.
+/// - Parameter url: The location on disk of the data to read.
- (nullable instancetype)initWithContentsOfURL:(NSURL *)url;
+/// Initializes a data object with the contents of another data object.
+///
+/// - Parameter data: A data object.
+/// - Returns: A data object initialized with the contents `data`.
- (instancetype)initWithData:(NSData *)data;
+/// Creates a data object containing the contents of another data object.
+///
+/// - Parameter data: A data object.
+ (instancetype)dataWithData:(NSData *)data;
@end
@interface NSData (NSDataBase64Encoding)
-/* Create an NSData from a Base-64 encoded NSString using the given options. By default, returns nil when the input is not recognized as valid Base-64.
-*/
+/// Initializes a data object with the given Base64 encoded string.
+///
+/// The default implementation of this method will reject non-alphabet characters, including line break characters. To support different encodings and ignore non-alphabet characters, specify an `options` value of ``NSData/Base64DecodingOptions/ignoreUnknownCharacters``.
+/// - Parameters:
+/// - base64String: A Base-64 encoded string.
+/// - options: A mask that specifies options for Base-64 decoding the data. Possible values are given in ``NSData/Base64DecodingOptions``.
+/// - Returns: A data object built by Base64 decoding the provided string. Returns `nil` if the data object could not be decoded.
- (nullable instancetype)initWithBase64EncodedString:(NSString *)base64String options:(NSDataBase64DecodingOptions)options API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
-/* Create a Base-64 encoded NSString from the receiver's contents using the given options.
-*/
+/// Creates a Base64 encoded string from the receiver's contents using the given options.
+///
+/// By default, no line endings are inserted.
+///
+/// If you specify one of the line length options (``NSData/Base64EncodingOptions/lineLength64Characters`` or ``NSData/Base64EncodingOptions/lineLength76Characters``) but don't specify the kind of line ending to insert, the default line ending is Carriage Return + Line Feed.
+/// - Parameter options: A mask that specifies options for Base-64 encoding the data. Possible values are given in ``NSData/Base64EncodingOptions``.
+/// - Returns: A Base64 encoded string.
- (NSString *)base64EncodedStringWithOptions:(NSDataBase64EncodingOptions)options API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
-/* Create an NSData from a Base-64, UTF-8 encoded NSData. By default, returns nil when the input is not recognized as valid Base-64.
-*/
+/// Initializes a data object with the given Base64 encoded data.
+///
+/// The default implementation of this method will reject non-alphabet characters, including line break characters. To support different encodings and ignore non-alphabet characters, specify an `options` value of ``NSData/Base64DecodingOptions/ignoreUnknownCharacters``.
+/// - Parameters:
+/// - base64Data: A Base64, UTF-8 encoded data object.
+/// - options: A mask that specifies options for Base64 decoding the data. Possible values are given in ``NSData/Base64DecodingOptions``.
+/// - Returns: A data object containing the Base64 decoded data. Returns `nil` if the data object could not be decoded.
- (nullable instancetype)initWithBase64EncodedData:(NSData *)base64Data options:(NSDataBase64DecodingOptions)options API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
-/* Create a Base-64, UTF-8 encoded NSData from the receiver's contents using the given options.
-*/
+/// Creates a Base64, UTF-8 encoded data object from the receiver's contents using the given options.
+///
+/// By default, no line endings are inserted.
+///
+/// If you specify one of the line length options (``NSData/Base64EncodingOptions/lineLength64Characters`` or ``NSData/Base64EncodingOptions/lineLength76Characters``) but don't specify the kind of line ending to insert, the default line ending is Carriage Return + Line Feed.
+/// - Parameter options: A mask that specifies options for Base64 encoding the data. Possible values are given in ``NSData/Base64EncodingOptions``.
+/// - Returns: A Base64, UTF-8 encoded data object.
- (NSData *)base64EncodedDataWithOptions:(NSDataBase64EncodingOptions)options API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
@end
-/* Various algorithms provided for compression APIs. See NSData and NSMutableData.
- */
+/// An algorithm that indicates how to compress or decompress data.
+///
+/// Choose an algorithm that best suits the needs of your app:
+///
+/// - ``lzfse`` -- The algorithm offers faster speed and generally achieves better compression than ``zlib``. However, it is slower than ``lz4`` and doesn't compress as well as ``lzma``.
+/// - ``zlib`` -- Use this algorithm if your app requires interoperability with non-Apple devices. For example, if you are transferring data to another device where it needs to be compressed or decompressed.
+/// - ``lz4`` -- Use this algorithm if speed is critical, and you're willing to sacrifice compression ratio to achieve it.
+/// - ``lzma`` -- Use this algorithm if compression ratio is critical, and you're willing to sacrifice speed to achieve it. It is an order of magnitude slower for both compression and decompression than other choices.
typedef NS_ENUM(NSInteger, NSDataCompressionAlgorithm) {
-
- // LZFSE is the recommended compression algorithm if you don't have a specific reason to use another algorithm. Note that LZFSE is intended for use with Apple devices only. This algorithm generally compresses better than Zlib, but not as well as LZMA. It is generally slower than LZ4.
+
+ /// The LZFSE compression algorithm, recommended for use on Apple platforms.
+ ///
+ /// LZFSE is the recommended compression algorithm if you don't have a specific reason to use another algorithm. Note that LZFSE is intended for use with Apple devices only. This algorithm generally compresses better than Zlib, but not as well as LZMA. It is generally slower than LZ4.
NSDataCompressionAlgorithmLZFSE = 0,
-
- // LZ4 is appropriate if compression speed is critical. LZ4 generally sacrifices compression ratio in order to achieve its greater speed.
- // This implementation of LZ4 makes a small modification to the standard format, which is described in greater detail in <compression.h>.
- NSDataCompressionAlgorithmLZ4,
-
- // LZMA is appropriate if compression ratio is critical and memory usage and compression speed are not a factor. LZMA is an order of magnitude slower for both compression and decompression than other algorithms. It can also use a very large amount of memory, so if you need to compress large amounts of data on embedded devices with limited memory you should probably avoid LZMA.
- // Encoding uses LZMA level 6 only, but decompression works with any compression level.
+
+ /// The LZ4 compression algorithm, recommended for fast compression.
+ ///
+ /// LZ4 is appropriate if compression speed is critical. LZ4 generally sacrifices compression ratio in order to achieve its greater speed.
+ NSDataCompressionAlgorithmLZ4, // This implementation of LZ4 makes a small modification to the standard format, which is described in greater detail in <compression.h>.
+
+ /// The LZMA compression algorithm, recommended for high-compression ratio.
+ ///
+ /// LZMA is appropriate if compression ratio is critical and memory usage and compression speed are not a factor. LZMA is an order of magnitude slower for both compression and decompression than other algorithms. It can also use a very large amount of memory, so if you need to compress large amounts of data on embedded devices with limited memory you should probably avoid LZMA.
+ /// Encoding uses LZMA level 6 only, but decompression works with any compression level.
NSDataCompressionAlgorithmLZMA,
-
- // Zlib is appropriate if you want a good balance between compression speed and compression ratio, but only if you need interoperability with non-Apple platforms. Otherwise, LZFSE is generally a better choice than Zlib.
- // Encoding uses Zlib level 5 only, but decompression works with any compression level. It uses the raw DEFLATE format as described in IETF RFC 1951.
+
+ /// The zlib compression algorithm, recommended for cross-platform compression.
+ ///
+ /// Zlib is appropriate if you want a good balance between compression speed and compression ratio, but only if you need interoperability with non-Apple platforms. Otherwise, LZFSE is generally a better choice than Zlib.
+ /// Encoding uses Zlib level 5 only, but decompression works with any compression level. It uses the raw DEFLATE format as described in IETF RFC 1951.
NSDataCompressionAlgorithmZlib,
} API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
@interface NSData (NSDataCompression)
-/* These methods return a compressed or decompressed version of the receiver using the specified algorithm.
- */
+/// Returns a new data object by decompressing data object's bytes.
+///
+/// Use this method to inflate in-memory data when you need uncompressed bytes. Specify the same algorithm used to compress the data to successfully decompress it.
+///
+/// The following example shows how to create a new ``NSData`` instance from data compressed with the ``NSData/CompressionAlgorithm/zlib`` algorithm:
+///
+/// ```swift
+/// do {
+/// let uncompressedData = try compressedData.decompressed(using: .zlib)
+/// } catch {
+/// print ("Decompression error: \(error)")
+/// }
+/// ```
+/// - Parameters:
+/// - algorithm: An algorithm used to decompress the data. For a list of available algorithms, see ``NSData/CompressionAlgorithm``.
+/// - error: On return, a pointer to an ``NSError`` instance that indicates why decompressing the data failed, or `nil` if no error occurred.
+/// - Returns: An ``NSData`` instance that contains the decompressed buffer data.
- (nullable instancetype)decompressedDataUsingAlgorithm:(NSDataCompressionAlgorithm)algorithm error:(NSError **)error API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
+/// Returns a new data object by compressing the data object's bytes.
+///
+/// Use this method to compress in-memory data when you want to reduce memory usage and can afford the time to compress and decompress it. If your data object is already in a compressed format, such as media formats like JPEG images or AAC audio, additional compression may provide minimal or no reduction in memory usage.
+///
+/// To restore this data, use ``NSData/decompressed(using:)``, and specify the algorithm originally used to compress the data.
+///
+/// The following example shows how to compress the data from a string and prints the sizes of the data instances to illustrate the amount of compression:
+///
+/// ```swift
+/// var string = "NSData and its mutable subclass NSMutableData provide data objects, or object-oriented wrappers for byte buffers. Data objects let simple allocated buffers (that is, data with no embedded pointers) take on the behavior of Foundation objects."
+/// let data = Data(string.utf8) as NSData
+/// print ("original data size: \(data.count) bytes")
+/// do {
+/// let compressedData = try data.compressed(using: .zlib)
+/// print("zlib compressed size: \(compressedData.count) bytes")
+/// } catch {
+/// print ("Compression error: \(error)")
+/// }
+/// // Prints:
+/// // original data size: 241 bytes
+/// // zlib compressed size: 158 bytes
+/// ```
+/// - Parameters:
+/// - algorithm: An algorithm used to compress the data. For a list of available algorithms, see ``NSData/CompressionAlgorithm``.
+/// - error: On return, a pointer to an ``NSError`` instance that indicates why compressing the data failed, or `nil` if no error occurred.
+/// - Returns: An ``NSData`` instance that contains the compressed buffer data.
- (nullable instancetype)compressedDataUsingAlgorithm:(NSDataCompressionAlgorithm)algorithm error:(NSError **)error API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
@end
@@ -176,59 +498,227 @@
@interface NSData (NSDeprecated)
+/// Copies a data object's contents into a given buffer.
+///
+/// You can see a sample using this method in [Working With Binary Data](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/BinaryData/Tasks/WorkingBinaryData.html#//apple_ref/doc/uid/20000717).
+/// - Parameter buffer: A buffer into which to copy the receiver's data. The buffer must be at least ``NSData/length`` bytes.
- (void)getBytes:(void *)buffer API_DEPRECATED("This method is unsafe because it could potentially cause buffer overruns. Use -getBytes:length: instead.", macos(10.0,10.10), ios(2.0,8.0), watchos(2.0,2.0), tvos(9.0,9.0));
+/// Creates a data object from the mapped file at a given path.
+///
+/// This method returns `nil` if the data object could not be created
+///
+/// Because of file mapping restrictions, this method should only be used if the file is guaranteed to exist for the duration of the data object's existence. It is generally safer to use the ``NSData/dataWithContentsOfFile:`` method.
+///
+/// This methods assumes mapped files are available from the underlying operating system. A mapped file uses virtual memory techniques to avoid copying pages of the file into memory until they are actually needed.
+/// - Parameter path: The absolute path of the file from which to read data.
+ (nullable id)dataWithContentsOfMappedFile:(NSString *)path API_DEPRECATED("Use +dataWithContentsOfURL:options:error: and NSDataReadingMappedIfSafe or NSDataReadingMappedAlways instead.", macos(10.0,10.10), ios(2.0,8.0), watchos(2.0,2.0), tvos(9.0,9.0));
+/// Initializes a data object with the contents of the mapped file specified by a given path.
+///
+/// - Parameter path: The absolute path of the file from which to read data.
+/// - Returns: A data object initialized by reading into it the mapped file specified by `path`.
- (nullable id)initWithContentsOfMappedFile:(NSString *)path API_DEPRECATED("Use -initWithContentsOfURL:options:error: and NSDataReadingMappedIfSafe or NSDataReadingMappedAlways instead.", macos(10.0,10.10), ios(2.0,8.0), watchos(2.0,2.0), tvos(9.0,9.0));
-/* These methods first appeared in NSData.h on OS X 10.9 and iOS 7.0. They are deprecated in the same releases in favor of the methods in the NSDataBase64Encoding category. However, these methods have existed for several releases, so they may be used for applications targeting releases prior to OS X 10.9 and iOS 7.0.
-*/
+/// Initializes a data object initialized with the given Base64 encoded string.
+///
+/// Although this method was only introduced publicly for iOS 7, it has existed since iOS 4; you can use it if your application needs to target an operating system prior to iOS 7. This method behaves like ``NSData/init(base64EncodedString:options:)``, but ignores all unknown characters.
+/// - Parameter base64String: A Base-64 encoded string.
+/// - Returns: A data object built by Base-64 decoding the provided string. Returns `nil` if the data object could not be decoded.
- (nullable id)initWithBase64Encoding:(NSString *)base64String API_DEPRECATED("Use initWithBase64EncodedString:options: instead", macos(10.6,10.9), ios(4.0,7.0), watchos(2.0,2.0), tvos(9.0,9.0));
+/// Initializes a Base64 encoded string from the string.
+///
+/// This method is equivalent to calling ``NSData/base64EncodedString(options:)`` with no options specified.
+///
+/// ### Special Considerations
+///
+/// Although this method was only introduced publicly for iOS 7, it has existed since iOS 4; you can use it if your application needs to target an operating system prior to iOS 7.
+/// - Returns: A Base-64 encoded string.
- (NSString *)base64Encoding API_DEPRECATED("Use base64EncodedStringWithOptions: instead", macos(10.6,10.9), ios(4.0,7.0), watchos(2.0,2.0), tvos(9.0,9.0));
@end
-/**************** Mutable Data ****************/
+/* *************** Mutable Data ****************/
+/// An object representing a dynamic byte buffer in memory.
+///
+/// In Swift, this object bridges to ``Data``; use ``NSMutableData`` when you need reference semantics or other Foundation-specific behavior.
+///
+/// `NSMutableData` and its superclass `NSData` provide data objects, or object-oriented wrappers for byte buffers. Data objects let simple allocated buffers (that is, data with no embedded pointers) take on the behavior of Foundation objects. `NSData` creates static data objects, and `NSMutableData` creates dynamic data objects. You can easily convert one type of data object to the other with the initializer that takes an `NSData` object or an `NSMutableData` object as an argument.
+///
+/// The following ``NSData`` methods change when used on a mutable data object:
+///
+/// - ``NSData/init(bytesNoCopy:length:freeWhenDone:)``
+/// - ``NSData/init(bytesNoCopy:length:deallocator:)``
+/// - ``NSData/init(bytesNoCopy:length:)``
+/// - ``NSData/dataWithBytesNoCopy:length:freeWhenDone:``
+/// - ``NSData/dataWithBytesNoCopy:length:``
+///
+/// When called, the bytes are immediately copied and then the buffer is freed.
+///
+/// `NSMutableData` is "toll-free bridged" with its Core Foundation counterpart, `CFData`. 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 ``Data`` structure, which bridges to the ``NSMutableData`` class and its immutable superclass ``NSData``. For more information about value types, see [Working with Foundation Types](https://developer.apple.com/documentation/swift/working-with-foundation-types).
@interface NSMutableData : NSData
+/// A pointer to the data contained by the mutable data object.
+///
+/// If the length of the receiver's data is not zero, this property is guaranteed to contain a pointer to the object's internal bytes. If the length of receiver's data _is_ zero, this property may or may not contain `NULL` dependent upon many factors related to how the object was created (moreover, in this case the method result might change between different releases). The returned pointer is valid until the data object is deallocated.
+///
+/// > Note:
+/// > This property is similar to, but different than the ``NSData/bytes`` property. The ``NSData/bytes`` property contains a pointer to a constant. You can use The ``NSData/bytes`` pointer to read the data managed by the data object, but you cannot modify that data. However, if the ``NSMutableData/mutableBytes`` property contains a non-`null` pointer, this pointer points to mutable data. You can use the ``NSMutableData/mutableBytes`` pointer to modify the data managed by the data object.
+///
+/// A sample using this method can be found in [Working With Mutable Binary Data](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/BinaryData/Tasks/WorkingMutableData.html#//apple_ref/doc/uid/20002150).
@property (readonly) void *mutableBytes NS_RETURNS_INNER_POINTER;
+/// The number of bytes contained in the mutable data object.
+///
+/// The mutable data object's length parameter is read-writeable. You can set this parameter to expand or truncate the number of bytes contained by the data object. If the mutable data object is expanded, the additional bytes are filled with zeros.
+///
+/// > Important:
+/// > Changing the length of a mutable data object invalidate any existing data pointers returned by the ``NSData/bytes`` or ``NSMutableData/mutableBytes`` properties.
@property NSUInteger length;
@end
@interface NSMutableData (NSExtendedMutableData)
+/// Appends to the receiver a given number of bytes from a given buffer.
+///
+/// A sample using this method can be found in [Working With Mutable Binary Data](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/BinaryData/Tasks/WorkingMutableData.html#//apple_ref/doc/uid/20002150).
+/// - Parameters:
+/// - bytes: A buffer containing data to append to the receiver's content.
+/// - length: The number of bytes from `bytes` to append.
- (void)appendBytes:(const void *)bytes length:(NSUInteger)length;
+/// Appends the content of another data object to the receiver.
+///
+/// - Parameter other: The data object whose content is to be appended to the contents of the receiver.
- (void)appendData:(NSData *)other;
+/// Increases the length of the receiver by a given number of bytes.
+///
+/// The additional bytes are all set to `0`.
+///
+/// > Important:
+/// > Changing the length of a mutable data object invalidates any existing data pointers returned by the ``NSData/bytes`` or ``NSMutableData/mutableBytes`` properties.
+/// - Parameter extraLength: The number of bytes by which to increase the receiver's length.
- (void)increaseLengthBy:(NSUInteger)extraLength;
+/// Replaces with a given set of bytes a given range within the contents of the receiver.
+///
+/// If the location of `range` isn't within the receiver's range of bytes, an `NSRangeException` is raised. The receiver is resized to accommodate the new bytes, if necessary.
+///
+/// A sample using this method is given in [Working With Mutable Binary Data](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/BinaryData/Tasks/WorkingMutableData.html#//apple_ref/doc/uid/20002150).
+/// - Parameters:
+/// - range: The range within the receiver's contents to replace with `bytes`. The range must not exceed the bounds of the receiver.
+/// - bytes: The data to insert into the receiver's contents.
- (void)replaceBytesInRange:(NSRange)range withBytes:(const void *)bytes;
+/// Replaces with zeroes the contents of the receiver in a given range.
+///
+/// If the location of `range` isn't within the receiver's range of bytes, an `NSRangeException` is raised. The receiver is resized to accommodate the new bytes, if necessary.
+/// - Parameter range: The range within the contents of the receiver to be replaced by zeros. The range must not exceed the bounds of the receiver.
- (void)resetBytesInRange:(NSRange)range;
+/// Replaces the entire contents of the receiver with the contents of another data object.
+///
+/// As part of its implementation, this method calls ``NSMutableData/replaceBytes(in:withBytes:)``.
+/// - Parameter data: The data object whose content replaces that of the receiver.
- (void)setData:(NSData *)data;
+/// Replaces with a given set of bytes a given range within the contents of the receiver.
+///
+/// If the length of `range` is not equal to `replacementLength`, the receiver is resized to accommodate the new bytes. Any bytes past `range` in the receiver are shifted to accommodate the new bytes. You can therefore pass `NULL` for `replacementBytes` and `0` for `replacementLength` to delete bytes in the receiver in the range `range`. You can also replace a range (which might be zero-length) with more bytes than the length of the range, which has the effect of insertion (or "replace some and insert more").
+/// - Parameters:
+/// - range: The range within the receiver's contents to replace with `bytes`. The range must not exceed the bounds of the receiver.
+/// - replacementBytes: The data to insert into the receiver's contents.
+/// - replacementLength: The number of bytes to take from `replacementBytes`.
- (void)replaceBytesInRange:(NSRange)range withBytes:(nullable const void *)replacementBytes length:(NSUInteger)replacementLength;
@end
@interface NSMutableData (NSMutableDataCreation)
+/// Creates and returns a mutable data object capable of holding the specified number of bytes.
+///
+/// This method doesn't necessarily allocate the requested memory right away. Mutable data objects allocate additional memory as needed, so `aNumItems` simply establishes the object's initial capacity. When it does allocate the initial memory, though, it allocates the specified amount. This method sets the length of the data object to `0`.
+///
+/// If the capacity specified in `aNumItems` is greater than four memory pages in size, this method may round the amount of requested memory up to the nearest full page.
+/// - Parameter aNumItems: The number of bytes the new data object can initially contain.
+/// - Returns: A new `NSMutableData` object capable of holding `aNumItems` bytes. The returned object has the same memory alignment guarantees as `malloc(_:)`.
+ (nullable instancetype)dataWithCapacity:(NSUInteger)aNumItems;
+/// Creates and returns an mutable data object containing a given number of zeroed bytes.
+///
+/// - Parameter length: The number of bytes the new data object initially contains.
+/// - Returns: A new `NSMutableData` object of `length` bytes, filled with zeros. The returned object has the same memory alignment guarantees as `malloc(_:)`.
+ (nullable instancetype)dataWithLength:(NSUInteger)length;
+/// Returns an initialized mutable data object capable of holding the specified number of bytes.
+///
+/// This method doesn't necessarily allocate the requested memory right away. Mutable data objects allocate additional memory as needed, so `capacity` simply establishes the object's initial capacity. When it does allocate the initial memory, though, it allocates the specified amount. This method sets the length of the data object to `0`.
+///
+/// If the capacity specified in `capacity` is greater than four memory pages in size, this method may round the amount of requested memory up to the nearest full page.
+/// - Parameter capacity: The number of bytes the data object can initially contain.
+/// - Returns: An initialized `NSMutableData` object capable of holding `capacity` bytes. The returned object has the same memory alignment guarantees as `malloc(_:)`.
- (nullable instancetype)initWithCapacity:(NSUInteger)capacity;
+/// Initializes and returns a mutable data object containing a given number of zeroed bytes.
+///
+/// - Parameter length: The number of bytes the object initially contains.
+/// - Returns: An initialized `NSMutableData` object containing `length` zeroed bytes. The returned object has the same memory alignment guarantees as `malloc(_:)`.
- (nullable instancetype)initWithLength:(NSUInteger)length;
@end
@interface NSMutableData (NSMutableDataCompression)
-/* These methods compress or decompress the receiver's contents in-place using the specified algorithm. If the operation is not successful, these methods leave the receiver unchanged..
- */
+/// Decompresses the data object's bytes.
+///
+/// Use this method to inflate in-memory data when you need uncompressed bytes. Specify the same algorithm used to compress the data to successfully decompress it.
+///
+/// The following example shows how to inflate an instance of ``NSMutableData`` compressed with the ``NSData/CompressionAlgorithm/zlib`` algorithm:
+///
+/// ```swift
+/// do {
+/// data.decompress(using: .zlib)
+/// } catch {
+/// print ("Decompression error: \(error)")
+/// }
+/// ```
+/// - Parameters:
+/// - algorithm: The algorithm to use for decompressing the data. For a list of available algorithms, see ``NSData/CompressionAlgorithm``.
+/// - error: On return, a pointer to an ``NSError`` instance that indicates why decompressing the data failed, or `nil` if no error occurred.
- (BOOL)decompressUsingAlgorithm:(NSDataCompressionAlgorithm)algorithm error:(NSError **)error API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
+/// Compresses the data object's bytes using an algorithm that you specify.
+///
+/// Use this method to compress in-memory data when you want to reduce memory usage and can afford the time to compress and decompress the data. If your data object is already in a compressed format, such as media formats like JPEG images or AAC audio, ``NSMutableData/compress(using:)`` may provide minimal or no benefit.
+///
+/// The following example shows how to compress data from a string and prints the sizes of the data instances to illustrate the amount of compression:
+///
+/// ```swift
+/// var string = "NSData and its mutable subclass NSMutableData provide data objects, or object-oriented wrappers for byte buffers. Data objects let simple allocated buffers (that is, data with no embedded pointers) take on the behavior of Foundation objects."
+/// let data = NSMutableData(data: Data(string.utf8))
+/// print ("original data size: \(data.length)")
+/// do {
+/// try data.compress(using: .zlib)
+/// print("zlib compressed size: \(data.length)")
+/// } catch {
+/// print ("Compression error: \(error)")
+/// }
+/// // Prints:
+/// // original data size: 241
+/// // zlib compressed size: 158
+/// ```
+/// - Parameters:
+/// - algorithm: The algorithm to use to compress the data. For a list of available algorithms, see ``NSData/CompressionAlgorithm``.
+/// - error: On return, a pointer to an ``NSError`` instance that indicates why compressing the data failed, or `nil` if no error occurred.
- (BOOL)compressUsingAlgorithm:(NSDataCompressionAlgorithm)algorithm error:(NSError **)error API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
@end
#if !0
-/**************** Purgeable Data ****************/
+/* *************** Purgeable Data ****************/
+/// A mutable data object containing bytes that can be discarded when they're no longer needed.
+///
+/// ``NSPurgeableData`` objects inherit their creation methods from their superclass, ``NSMutableData`` while providing a default implementation of the ``NSDiscardableContent`` protocol.
+///
+/// All ``NSPurgeableData`` objects begin "accessed" to ensure that they are not instantly discarded. The ``NSDiscardableContent/beginContentAccess()`` method marks the object's bytes as "accessed," thus protecting them from being discarded, and must be called before accessing the object, or else an exception will be raised. This method returns <doc://com.apple.documentation/documentation/swift/true> if the bytes have not been discarded and if they have been successfully marked as "accessed". Any method that directly or indirectly accesses these bytes or their length when they are not "accessed" will raise an exception. When you are done with the data, call ``NSDiscardableContent/endContentAccess()`` to allow them to be discarded in order to quickly free up memory.
+///
+/// You may use these objects by themselves, and do not necessarily have to use them in conjunction with ``NSCache`` to get the purging behavior. The ``NSCache`` class incorporates a caching mechanism with some auto-removal policies to ensure that its memory footprint does not get too large.
+///
+/// ``NSPurgeableData`` objects should not be used as keys in hashing-based collections, because the value of the bytes pointer can change after every mutation of the data.
API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0))
@interface NSPurgeableData : NSMutableData <NSDiscardableContent>
@end
diff -ruN /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSDate.h /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSDate.h
--- /Applications/Xcode_26.5.0.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSDate.h 2026-04-18 19:07:14
+++ /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSDate.h 2026-05-27 00:45:55
@@ -9,58 +9,207 @@
NS_HEADER_AUDIT_BEGIN(nullability, sendability)
+/// A notification posted whenever the system clock is changed.
+///
+/// This can be initiated by a call to `settimeofday()` or the user changing values in the Date and Time Preference panel. The notification object is `nil`. This notification does not contain a `userInfo` dictionary.
FOUNDATION_EXPORT NSNotificationName const NSSystemClockDidChangeNotification API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
+/// A number of seconds.
+///
+/// An `NSTimeInterval` value is always specified in seconds; it yields sub-millisecond precision over a range of 10,000 years.
+///
+/// On its own, a time interval does not specify a unique point in time, or even a span between specific times. Combining a time interval with one or more known reference points yields an `NSDate` or `NSDateInterval` value.
typedef double NSTimeInterval;
#define NSTimeIntervalSince1970 978307200.0
-NS_SWIFT_SENDABLE // Immutable with no mutable subclasses
+
+/// A representation of a specific point in time, independent of any calendar or time zone.
+///
+/// In Swift, use this type when you need reference semantics or other Foundation-specific behavior.
+///
+/// ``NSDate`` objects encapsulate a single point in time, independent of any particular calendrical system or time zone. Date objects are immutable, representing an invariant time interval relative to an absolute reference date (00:00:00 UTC on 1 January 2001).
+///
+/// The ``NSDate`` class provides methods for comparing dates, calculating the time interval between two dates, and creating a new date from a time interval relative to another date. ``NSDate`` objects can be used in conjunction with ``DateFormatter`` objects to create localized representations of dates and times, as well as with ``NSCalendar`` objects to perform calendar arithmetic.
+///
+/// ``NSDate`` is _toll-free bridged_ with its Core Foundation counterpart, <doc://com.apple.documentation/documentation/corefoundation/cfdate>. 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 ``Date`` structure, which bridges to the ``NSDate`` class. For more information about value types, see <doc://com.apple.documentation/documentation/swift/working-with-foundation-types>.
+///
+/// ### Subclassing Notes
+///
+/// You might subclass ``NSDate`` in order to make it easier to work with a particular calendrical system, or to work with date and time values with a finer temporal granularity.
+///
+/// #### Methods to Override and Other Requirements
+///
+/// If you want to subclass ``NSDate`` to obtain behavior different than that provided by the private or public subclasses, you must:
+///
+/// - Declare a suitable instance variable to hold the date and time value (relative to an absolute reference date)
+/// - Override the ``timeIntervalSinceReferenceDate-property`` instance method to provide the correct date and time value based on your instance variable
+/// - Override ``init(timeIntervalSinceReferenceDate:)``, one of the designated initializer methods
+/// - If creating a subclass that represents a calendrical system, define methods that partition past and future periods into the units of this calendar
+/// - Implement the methods required by the ``NSCopying`` and [NSCoding](https://developer.apple.com/library/archive/documentation/Swift/Conceptual/BuildingCocoaApps/WritingSwiftClassesWithObjective-CBehavior.html#//apple_ref/doc/uid/TP40014216-CH5-ID152) protocols, because ``NSDate`` adopts these protocols
+///
+///
+///
+/// #### Special Considerations
+///
+/// Your subclass may use a different reference date than the absolute reference date used by ``NSDate`` (00:00:00 UTC on 1 January 2001). If it does, it must still use the absolute reference date in its implementations of the methods ``timeIntervalSinceReferenceDate-property`` and ``init(timeIntervalSinceReferenceDate:)``. That is, the reference date referred to in the titles of these methods is the absolute reference date. If you do not use the absolute reference date in these methods, comparisons between ``NSDate`` objects of your subclass and `NSDate` objects of a private subclass will not work.
+NS_SWIFT_SENDABLE
@interface NSDate : NSObject <NSCopying, NSSecureCoding>
+/// The interval between the date object and 00:00:00 UTC on 1 January 2001.
+///
+/// This property's value is negative if the date object is earlier than the system's absolute reference date (00:00:00 UTC on 1 January 2001).
@property (readonly) NSTimeInterval timeIntervalSinceReferenceDate;
+/// Returns a date object initialized to the current date and time.
+///
+/// This method is a designated initializer for `NSDate`.
- (instancetype)init NS_DESIGNATED_INITIALIZER;
+/// Returns a date object initialized relative to 00:00:00 UTC on 1 January 2001 by a given number of seconds.
+///
+/// - Parameter ti: The number of seconds to add to the reference date (00:00:00 UTC on 1 January 2001). A negative value means the receiver will be earlier than the reference date.
+///
+/// This method is a designated initializer for the `NSDate` class and is declared primarily for the use of subclasses of `NSDate`. When you subclass `NSDate` to create a concrete date class, you must override this method.
- (instancetype)initWithTimeIntervalSinceReferenceDate:(NSTimeInterval)ti NS_DESIGNATED_INITIALIZER;
+/// Returns a date object initialized from data in the given unarchiver.
- (nullable instancetype)initWithCoder:(NSCoder *)coder NS_DESIGNATED_INITIALIZER;
@end
@interface NSDate (NSExtendedDate)
+/// Returns the interval between the receiver and another given date.
+///
+/// - Parameter anotherDate: The date with which to compare the receiver. You must pass a non-`nil` date object.
+/// - Returns: The interval between the receiver and the `anotherDate` parameter. If the receiver is earlier than `anotherDate`, the return value is negative. If `anotherDate` is `nil`, the results are undefined.
- (NSTimeInterval)timeIntervalSinceDate:(NSDate *)anotherDate;
+/// The interval between the date object and the current date and time.
+///
+/// If the date object is earlier than the current date and time, this property's value is negative.
@property (readonly) NSTimeInterval timeIntervalSinceNow;
+/// The interval between the date object and 00:00:00 UTC on 1 January 1970.
+///
+/// This property's value is negative if the date object is earlier than 00:00:00 UTC on 1 January 1970.
@property (readonly) NSTimeInterval timeIntervalSince1970;
+/// Returns a new date object that is set to a given number of seconds relative to the receiver.
+///
+/// @DeprecationSummary Use `dateByAddingTimeInterval:` instead.
+///
+/// - Parameter seconds: The number of seconds to add to the receiver. Use a negative value for seconds to have the returned object specify a date before the receiver.
+/// - Returns: A new `NSDate` object that is set to `seconds` seconds relative to the receiver. The date returned might have a representation different from the receiver's.
- (id)addTimeInterval:(NSTimeInterval)seconds API_DEPRECATED("Use dateByAddingTimeInterval instead", macos(10.0,10.6), ios(2.0,4.0), watchos(2.0,2.0), tvos(9.0,9.0));
+/// Returns a new date object that is set to a given number of seconds relative to the receiver.
+///
+/// - Parameter ti: The number of seconds to add to the receiver. Use a negative value for seconds to have the returned object specify a date before the receiver.
+/// - Returns: A new `NSDate` object that is set to `seconds` seconds relative to the receiver. The date returned might have a representation different from the receiver's.
- (instancetype)dateByAddingTimeInterval:(NSTimeInterval)ti API_AVAILABLE(macos(10.6), ios(2.0), watchos(2.0), tvos(9.0));
+/// Returns the earlier of the receiver and another given date.
+///
+/// - Parameter anotherDate: The date with which to compare the receiver.
+/// - Returns: The earlier of the receiver and `anotherDate`, determined using `timeIntervalSinceDate:`. If the receiver and `anotherDate` represent the same date, returns the receiver.
- (NSDate *)earlierDate:(NSDate *)anotherDate;
+/// Returns the later of the receiver and another given date.
+///
+/// - Parameter anotherDate: The date with which to compare the receiver.
+/// - Returns: The later of the receiver and `anotherDate`, determined using `timeIntervalSinceDate:`. If the receiver and `anotherDate` represent the same date, returns the receiver.
- (NSDate *)laterDate:(NSDate *)anotherDate;
+/// Indicates the temporal ordering of the receiver and another given date.
+///
+/// - Parameter other: The date with which to compare the receiver. This value must not be `nil`. If the value is `nil`, the behavior is undefined and may change in future versions of macOS.
+/// - Returns: `NSOrderedSame` if the two dates are exactly equal, `NSOrderedDescending` if the receiver is later in time than `other`, and `NSOrderedAscending` if the receiver is earlier in time than `other`.
+///
+/// This method detects sub-second differences between dates. If you want to compare dates with a less fine granularity, use `timeIntervalSinceDate:` to compare the two dates.
- (NSComparisonResult)compare:(NSDate *)other;
+/// Returns a Boolean value that indicates whether a given object is a date that is exactly equal the receiver.
+///
+/// - Parameter otherDate: The date to compare with the receiver.
+/// - Returns: `YES` if the `otherDate` is an `NSDate` object and is exactly equal to the receiver, otherwise `NO`.
+///
+/// This method detects sub-second differences between dates. If you want to compare dates with a less fine granularity, use `timeIntervalSinceDate:` to compare the two dates.
- (BOOL)isEqualToDate:(NSDate *)otherDate;
+/// A string representation of the date object.
+///
+/// The representation is useful for debugging only. There are a number of options to acquire a formatted string for a date including: date formatters (see `NSDateFormatter`), and the `NSDate` methods `descriptionWithLocale:`.
@property (readonly, copy) NSString *description;
+/// Returns a string representation of the date using the given locale.
+///
+/// - Parameter locale: An `NSLocale` object. If you pass `nil`, `NSDate` formats the date in the same way as the `description` property.
+/// - Returns: A string representation of the receiver, using the given locale, or if the locale argument is `nil`, in the international format `YYYY-MM-DD HH:MM:SS +/-HHMM`, where `+/-HHMM` represents the time zone offset in hours and minutes from UTC (for example, "2001-03-24 10:45:32 +0600").
- (NSString *)descriptionWithLocale:(nullable id)locale;
+/// The interval between 00:00:00 UTC on 1 January 2001 and the current date and time.
+///
+/// This method is the primitive method for `NSDate`. If you subclass `NSDate`, you must override this method with your own implementation for it.
@property (class, readonly) NSTimeInterval timeIntervalSinceReferenceDate;
@end
@interface NSDate (NSDateCreation)
+/// Creates and returns a new date object set to the current date and time.
+///
+/// This method uses the default initializer method for the class, `init`.
+ (instancetype)date;
+/// Creates and returns a date object set to a given number of seconds from the current date and time.
+///
+/// - Parameter secs: The number of seconds from the current date and time for the new date. Use a negative value to specify a date before the current date.
+/// - Returns: An `NSDate` object set to `secs` seconds from the current date and time.
+ (instancetype)dateWithTimeIntervalSinceNow:(NSTimeInterval)secs;
+/// Creates and returns a date object set to a given number of seconds from 00:00:00 UTC on 1 January 2001.
+///
+/// - Parameter ti: The number of seconds from the absolute reference date (00:00:00 UTC on 1 January 2001) for the new date. Use a negative argument to specify a date and time before the reference date.
+/// - Returns: An `NSDate` object set to `ti` seconds from the absolute reference date.
+ (instancetype)dateWithTimeIntervalSinceReferenceDate:(NSTimeInterval)ti;
+/// Creates and returns a date object set to the given number of seconds from 00:00:00 UTC on 1 January 1970.
+///
+/// - Parameter secs: The number of seconds from the reference date (00:00:00 UTC on 1 January 1970) for the new date. Use a negative argument to specify a date and time before the reference date.
+/// - Returns: An `NSDate` object set to `secs` seconds from the reference date.
+///
+/// This method is useful for creating `NSDate` objects from `time_t` values returned by BSD system functions.
+ (instancetype)dateWithTimeIntervalSince1970:(NSTimeInterval)secs;
+/// Creates and returns a date object set to a given number of seconds from the specified date.
+///
+/// - Parameter secsToBeAdded: The number of seconds to add to `date`. Use a negative argument to specify a date and time before `date`.
+/// - Parameter date: The date.
+/// - Returns: An `NSDate` object set to `secsToBeAdded` seconds from `date`.
+ (instancetype)dateWithTimeInterval:(NSTimeInterval)secsToBeAdded sinceDate:(NSDate *)date;
+/// A date object representing a date in the distant future.
+///
+/// You can pass this value when an `NSDate` object is required to have the date argument essentially ignored. For example, the `NSWindow` method `nextEventMatchingMask:untilDate:inMode:dequeue:` returns `nil` if an event specified in the event mask does not happen before the specified date. You can use the object returned by `distantFuture` as the date argument to wait indefinitely for the event to occur.
@property (class, readonly, copy) NSDate *distantFuture;
+/// A date object representing a date in the distant past.
+///
+/// You can use this object as a control date, a guaranteed temporal boundary.
@property (class, readonly, copy) NSDate *distantPast;
+/// The current date and time, as of the time of access.
+///
+/// This is equivalent to initializing a new instance with `NSDate()` (or `[[NSDate alloc] init]` in Objective-C). The `NSDate` instance doesn't automatically update its time after you retrieve it.
@property (class, readonly, copy) NSDate *now