[SE-0494][StdLib] Add `isTriviallyIdentical(to:)` Methods to Array, ArraySlice, and ContiguousArray #82438

vanvoorden · 2025-06-23T23:39:52Z

Background

SE-0494 has been accepted by LSG.

Changes

Our Array already performs a "fast path" for equality checking in our == operator.¹ We can implement a similar check for isIdentical:

extension Array {
  @_alwaysEmitIntoClient
  public func isTriviallyIdentical(to other: Self) -> Bool {
    self._buffer.identity == other._buffer.identity
  }
}

There are similar fast paths in ArraySlice and ContiguousArray.²³

Test Plan

New tests were added for Array, ArraySlice, and ContiguousArray.

Benchmarks

New benchmarks were added for Array, ArraySlice, and ContiguousArray.

Azoy · 2025-06-24T17:20:19Z

stdlib/public/core/Array.swift

I would prefer this (and everything else in this PR) to be @_alwaysEmitIntoClient instead.

@Azoy TBH… I have zero experience with either option. From reading through SE-0376 it sounds like backDeployed came with some advantages:

While @_alwaysEmitIntoClient can be used to back deploy APIs, there are some drawbacks to using it. Since a copy of the function is always emitted, there is code size overhead for every client even if the client's deployment target is new enough that the library API would always be available at runtime. Additionally, if the implementation of the API were to change in order to improve performance, fix a bug, or close a security hole then the client would need to be recompiled against a new SDK before users benefit from those changes.

I don't see much discussion in that proposal over when a library maintainer would still prefer _alwaysEmitIntoClient.

I did find this discussion from @lorentey:

#75433 (comment)

It sounds like one issue here was that debugDescription was used to conform to a protocol. Our isIdentical function here would not be used to conform to a protocol. It sounds like that might make safer shipping backDeployed?

But we did leave a FIXME comment:

e39613b

That we eventually want to make this backDeployed.

Hmm… would you have any more specific ideas why we prefer _alwaysEmitIntoClient here for these changes?

Because @backDeployed commits this as the stdlib's ABI vs. @_aEIC which does not. If we find we need to replace this in the future with some more generalized thing or such, we pay the price of having to maintain this forever instead of just being able to update the definition. @_aEIC is the best attribute in my opinion because it is the "pay for what you use" attribute both for the stdlib and the client. The stdlib doesn't have to take the code size hit (unless it started using it in its own opaque implementation) or the ABI hit, and clients don't pay for anything unless they use it themselves or use something that uses it.

There's also the fact that @backDeployed introduces a runtime availability check for some configurations which does have a performance cost vs. @_aEIC which does not.

@Azoy SGTM. I'll make the changes and push a new commit. Thanks!

@Azoy would you have any opinion about #82055 and #82439? Same tradeoff for preferring aEIC on those?

stdlib/public/core/Array.swift

vanvoorden · 2025-10-16T23:24:55Z

stdlib/public/core/ArraySlice.swift

+  @_alwaysEmitIntoClient
+  public func isTriviallyIdentical(to other: Self) -> Bool {
+    self._buffer.identity == other._buffer.identity &&
+    self.count == other.count


@lorentey I think we have to check the count here… or else we could have the same buffer with two different ranges that compare as identical. But if the buffer identity itself already defends against that then I can remove this extra check.

This does appear sound for all cases I've seen in practice -- the buffer identity is simply the address of its first element, and including the count guarantees that the two slices are backed by the same region of memory.

But two slices being backed by the same memory does not necessarily imply that they must be identical slices. It does leave me worried that this shortcut may misfire in some exotic/hypothetical cases, such as if two distinct bridged read-only NSArray instances somehow end up getting backed by overlapping memory regions, and therefore two array slices may be backed by the same memory, but still be distinguishable -- for example, by looking at their startIndex. I'm not aware of any actual NSArray subclass that would do that, but I do believe it is technically possible.

To avoid this (and (perhaps more practical) similar cases I may be missing), I think we should just follow best practice and simply compare all stored properties, with no clever shortcuts, like in the draft below:

extension _SliceBuffer { @_alwaysEmitIntoClient internal func isTriviallyIdentical(to other: Self) -> Bool { self.owner == other.owner && self.subscriptBaseAddress == other.subscriptBaseAddress && self.startIndex == other.startIndex && self.endIndexAndFlags == other.endIndexAndFlags } } extension ArraySlice { @_alwaysEmitIntoClient public func isTriviallyIdentical(to other: Self) -> Bool { self._buffer.isTriviallyIdentical(to: other._buffer) } }

(Note that this only applies to array slices; I believe comparing _buffer.identity will suffice for Array and ContiguousArray. In the bridged case, the identity is simply the object identity of the NSArray instance.)

@lorentey Ahh… that's a good idea! I'll push a new commit. Thanks!

Hmm… I'm running into trouble now trying to compare self.owner to other.owner because of the Builtin.NativeObject type…

https://github.com/swiftlang/swift/blob/swift-6.2-RELEASE/stdlib/public/core/Builtin.swift#L135-L140

I think I need this one… but for some reason I'm not able to call it without a compiler error…

stdlib/public/core/Array.swift

vanvoorden · 2025-10-20T20:50:49Z

@swift-ci Please smoke test

vanvoorden · 2025-10-21T18:17:34Z

@swift-ci Please smoke test

vanvoorden · 2025-10-21T19:39:05Z

I think the smoke test failures might be related to #84925.

benrimmington · 2025-10-22T20:36:22Z

stdlib/public/core/SliceBuffer.swift

+      // FIXME: use builtin == function
+      // self.owner == other.owner,
+      unsafe unsafeBitCast(self.owner, to: Int.self) == unsafeBitCast(other.owner, to: Int.self),


I think you'll need to use:

== for Embedded Swift, because owner is Builtin.NativeObject (via the _SliceBuffer.AnyObject typealias).

=== for standard Swift, because owner is Swift.AnyObject.

The status page lists AnyObject as currently supported in Embedded Swift, so perhaps this can be simplified in the future?

@benrimmington Ahh… that's a good idea! I'll push a new commit. Thanks!

benrimmington · 2025-10-22T21:14:30Z

Since your tests are the same for all types, you could try moving them to:

test/stdlib/Inputs/CommonArrayTests.gyb

where they'll be used by:

vanvoorden · 2025-10-22T22:41:51Z

@swift-ci Please smoke test

vanvoorden · 2025-11-03T18:46:57Z

@swift-ci Please smoke test

vanvoorden · 2025-11-24T18:49:11Z

@swift-ci Please smoke test

vanvoorden · 2025-11-26T00:11:39Z

@swift-ci Please test

vanvoorden · 2025-11-26T04:50:33Z

@swift-ci Please test macOS platform

vanvoorden · 2025-11-26T06:49:35Z

@swift-ci please Apple silicon benchmark

vanvoorden · 2025-11-26T18:12:16Z

@swift-ci Please test macOS platform

vanvoorden · 2025-11-26T19:12:51Z

@swift-ci Please benchmark

benrimmington · 2025-12-03T19:55:23Z

stdlib/public/core/Array.swift

+  /// compare equal with `==`, but not all equal arrays are considered
+  /// identical.
+  ///
+  /// - Complexity: O(1)


@amartini51 Please could you review this documentation comment for the Array.isTriviallyIdentical(to:) method.

(ArraySlice, ContiguousArray, Dictionary, Set, String, and Substring will share basically the same documentation.)

My suggestions and observations are:

Capitalize the word "Boolean".

Possibly combine and generalize the first two sentences.

Returns a Boolean value indicating whether this instance is indistinguishable from the other instance.

Possibly generalize the last paragraph (by replacing "array" with "instance" or "value").

The fourth list item (Equatable) is repeated in the last paragraph.

Are fenced code blocks (with three backticks) allowed in the standard library?

These are all great ideas and I'm also open to workshopping this documentation from a more "conceptual" POV. So I think maybe as an alternative to some of the more tactical feedback on cleaning up specific details of this documentation using the current overall philosophy I am also open to brainstorming together how else we could think about teaching the ideas of these operations to engineers that are new to this topic. Some potential ideas and directions that sounded interesting were shared in our review thread.¹

Because documentation fixes are easy to patch on release branches I also think we might be able to prioritize landing the implementations and getting the code right first so we can make sure that lands before the branch cut. If we then spend more time on improving documentation and we need to potentially patch after a branch cut then that is a very low risk change as opposed to trying to patch an implementation fix.

How does that sound to you? Any more ideas about that?

Footnotes

https://forums.swift.org/t/se-0494-add-isidentical-to-methods-for-quick-comparisons-to-concrete-types/82296/68 ↩

vanvoorden · 2025-12-05T22:54:14Z

@swift-ci Please Build Toolchain macOS Platform

amartini51

Replying to the points in the comment where I was at-mentioned:

Yes, Boolean needs to be capitalized per Apple style guide.
Yes, we can continue to iterate on the docs after the implementation lands. Thanks for including them in your initial PR!
As you combine the first two sentences, ensure the abstract remains a single sentence without links or code voice. (The abstract is the text before the first blank line.) It needs to stand on its own in places like IDE help, autocomplete, and navigation where the rest of the docs aren’t shown.
The stdlib normally uses indented code listings, although DocC does support both. I’m not sure where the precedent for indentation comes from, but it might be from the pre-DocC tools we used to publish documentation from comments.
The word “trivial” appears in the symbol name and was discussed as part of the SE proposal, but there isn’t anything in the docs here about that part of the API. Can we add something? My understanding is that this returns true only when the arrays can be trivially compared — that this is always fast, but == might be slower.

stdlib/public/core/Array.swift

lorentey · 2025-12-08T21:19:15Z

@swift-ci test

amartini51 · 2025-12-08T22:24:16Z

stdlib/public/core/Array.swift

+  /// Returns a boolean value indicating whether this array is identical to
+  /// `other`.


Copying @benrimmington's suggestion from below, which I also think is an improvement:

Suggested change

/// Returns a boolean value indicating whether this array is identical to

/// `other`.

/// Returns a Boolean value indicating whether this instance is indistinguishable

/// from the other instance.

Although I think it works fine with "array" instead of "instance".

Co-Authored-By: Ben Rimmington <[email protected]>

Co-authored-by: Alex Martini <[email protected]>

vanvoorden · 2025-12-09T01:39:42Z

@swift-ci Please test

vanvoorden · 2025-12-09T01:39:50Z

@swift-ci please Apple silicon benchmark

vanvoorden · 2025-12-09T01:39:57Z

@swift-ci Please benchmark

vanvoorden · 2025-12-09T01:40:06Z

@swift-ci Please Build Toolchain macOS Platform

vanvoorden · 2025-12-09T02:45:23Z

@amartini51 I appreciate all the help working through the documentation! I think my preference for now is to go ahead and try to land these implementations so we can start soaking ASAP. But I do want to open a new task for us to continue workshopping the documentation across all the types we merged in this proposal. I can tag you over there if you are interested in helping us to keep the conversation going. Thanks!

vanvoorden · 2025-12-11T18:55:15Z

@lorentey I think this one looks good to merge now. Thanks!

vanvoorden · 2025-12-12T02:50:50Z

@benrimmington @amartini51 We can track documentation improvements over in #86000. Thanks!

vanvoorden · 2025-12-17T22:11:44Z

@lorentey Thanks for all the help! Please let us know if you have any more ideas to help improve the documentation and we can always pick those changes in later on.

vanvoorden force-pushed the array-identical branch from 8ab92b0 to 0ccbcec Compare June 24, 2025 04:48

Azoy reviewed Jun 24, 2025

View reviewed changes

vanvoorden marked this pull request as ready for review August 12, 2025 07:07

vanvoorden requested review from a team and eeckstein as code owners August 12, 2025 07:07

vanvoorden mentioned this pull request Aug 22, 2025

[RFC] Add isIdentical Methods to Concrete Types vanvoorden/swift-evolution#1

Closed

vanvoorden force-pushed the array-identical branch 2 times, most recently from 781b431 to 8d86f96 Compare August 26, 2025 00:59

vanvoorden force-pushed the array-identical branch from 8d86f96 to 51a04aa Compare September 3, 2025 22:57

vanvoorden force-pushed the array-identical branch from 51a04aa to c1a4725 Compare October 16, 2025 23:21

vanvoorden changed the title ~~[StdLib][RFC][DNM] Add isIdentical Methods for Quick Comparisons to Array, ArraySlice, and ContiguousArray~~ [SE-0494][StdLib] Add isIdentical Methods for Quick Comparisons to Array, ArraySlice, and ContiguousArray Oct 16, 2025

vanvoorden changed the title ~~[SE-0494][StdLib] Add isIdentical Methods for Quick Comparisons to Array, ArraySlice, and ContiguousArray~~ [SE-0494][StdLib] Add isTriviallyIdentical(to:) Methods for Quick Comparisons to Array, ArraySlice, and ContiguousArray Oct 16, 2025

vanvoorden commented Oct 16, 2025

View reviewed changes

stdlib/public/core/Array.swift Show resolved Hide resolved

vanvoorden commented Oct 16, 2025

View reviewed changes

vanvoorden mentioned this pull request Oct 17, 2025

[SE-0494][StdLib] Add isTriviallyIdentical(to:) Methods #84991

Closed

benrimmington reviewed Oct 20, 2025

View reviewed changes

stdlib/public/core/Array.swift Outdated Show resolved Hide resolved

vanvoorden changed the title ~~[SE-0494][StdLib] Add isTriviallyIdentical(to:) Methods for Quick Comparisons to Array, ArraySlice, and ContiguousArray~~ [SE-0494][StdLib] Add isTriviallyIdentical(to:) Methods to Array, ArraySlice, and ContiguousArray Oct 20, 2025

vanvoorden requested review from Azoy, benrimmington and lorentey October 22, 2025 18:57

benrimmington reviewed Oct 22, 2025

View reviewed changes

vanvoorden requested a review from benrimmington October 23, 2025 22:12

benrimmington requested a review from amartini51 December 3, 2025 19:52

benrimmington reviewed Dec 3, 2025

View reviewed changes

amartini51 reviewed Dec 5, 2025

View reviewed changes

stdlib/public/core/Array.swift Outdated Show resolved Hide resolved

stdlib/public/core/Array.swift Outdated Show resolved Hide resolved

stdlib/public/core/Array.swift Outdated Show resolved Hide resolved

stdlib/public/core/Array.swift Outdated Show resolved Hide resolved

lorentey approved these changes Dec 8, 2025

View reviewed changes

stdlib/public/core/Array.swift Outdated Show resolved Hide resolved

amartini51 reviewed Dec 8, 2025

View reviewed changes

vanvoorden and others added 3 commits December 8, 2025 17:39

[stdlib] array identical

048091d

Co-Authored-By: Ben Rimmington <[email protected]>

Apply suggestions from code review

fd66cc6

Co-authored-by: Alex Martini <[email protected]>

Update stdlib/public/core/Array.swift

ee14e1f

vanvoorden force-pushed the array-identical branch from 34ecc96 to ee14e1f Compare December 9, 2025 01:39

vanvoorden mentioned this pull request Dec 12, 2025

[SE-0494][StdLib] Improve isTriviallyIdentical(to:) Documentation #86000

Open

lorentey merged commit 05d4565 into swiftlang:main Dec 17, 2025
8 checks passed

		/// Returns a boolean value indicating whether this array is identical to
		/// `other`.

[SE-0494][StdLib] Add isTriviallyIdentical(to:) Methods to Array, ArraySlice, and ContiguousArray #82438

[SE-0494][StdLib] Add isTriviallyIdentical(to:) Methods to Array, ArraySlice, and ContiguousArray #82438

Uh oh!

Conversation

vanvoorden commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Changes

Test Plan

Benchmarks

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Azoy Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lorentey Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vanvoorden commented Oct 20, 2025

Uh oh!

vanvoorden commented Oct 21, 2025

Uh oh!

vanvoorden commented Oct 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benrimmington commented Oct 22, 2025

Uh oh!

vanvoorden commented Oct 22, 2025

Uh oh!

vanvoorden commented Nov 3, 2025

Uh oh!

vanvoorden commented Nov 24, 2025

Uh oh!

vanvoorden commented Nov 26, 2025

Uh oh!

vanvoorden commented Nov 26, 2025

Uh oh!

vanvoorden commented Nov 26, 2025

Uh oh!

vanvoorden commented Nov 26, 2025

Uh oh!

vanvoorden commented Nov 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Footnotes

Uh oh!

vanvoorden commented Dec 5, 2025

Uh oh!

amartini51 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

[SE-0494][StdLib] Add `isTriviallyIdentical(to:)` Methods to Array, ArraySlice, and ContiguousArray #82438

[SE-0494][StdLib] Add `isTriviallyIdentical(to:)` Methods to Array, ArraySlice, and ContiguousArray #82438

vanvoorden commented Jun 23, 2025 •

edited

Loading

Azoy Jun 24, 2025 •

edited

Loading

lorentey Oct 17, 2025 •

edited

Loading

amartini51 Dec 8, 2025 •

edited

Loading

vanvoorden commented Dec 9, 2025 •

edited

Loading