[Amendment] SE-0240: Ordered Collection Diffing

The review of an amendment to SE-0240: Ordered Collection Diffing begins now and runs through Tuesday, June 25th, 2019.

This amendment is to add a new method, inverse(), to the CollectionDifference type. The diff to the previous proposal can be found here.

Reviews are an important part of the Swift evolution process. All review feedback should be either on this forum thread or, if you would like to keep your feedback private, directly to me as the review manager via email or direct message on the forums. If you send me email, please put "SE-0240" somewhere in the subject line.

What goes into a review of a proposal?

The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift.

When reviewing a proposal, here are some questions to consider:

  • What is your evaluation of the proposal?
  • Is the problem being addressed significant enough to warrant a change to Swift?
  • Does this proposal fit well with the feel and direction of Swift?
  • If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
  • How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

Thank you for contributing to Swift!

Ben Cohen
Review Manager

9 Likes

Shouldn't the method be called inversed() (or inverted()) since it returns a new instance, rather than modifying the callee?

No. inverse() is a noun (the inverse of the difference), not an imperative verb. inverted() is also an option, but both are valid per the naming guidelines.

2 Likes

Ah, I see. inverse() sounds like a pretty good name, then.

1 Like

In favor. It’s a natural extension with the right name.

1 Like

+1 I don't see any reason not to add it.

1 Like

-1

No, swift library not need this algorithm implementation. Swift should be so lightweight as possible. Diff implementation is not so widely used as, for example, sorting algorithms of collections. IMO, swift library is helper for algorithm implementations, not the implementations directly.

This diff implementation should be somewhere in "Swift Foundation" or in another apple-maintained swift package.

I used other libraries with similar feature

In-depth study, I wrote my own swift implementation of this

There's a bunch of background (as well as some lively discussion) on the topic of naming in the pitch thread :slight_smile:

I think the ship has sailed on where this implementation lives, @Nekitosss. This isn't a full review of SE-0240, just the amendments.

What is your evaluation of the proposal?

:+1:t2: adding the inverse() function seems logical to me. Being able to undo an applied diff can be very useful when dealing with UI changes.

I also look after a Swift diffing library, and I'm looking forward to not having to anymore :joy:

4 Likes

+1. This is a straightforward addition. I am also happy to see that the SE process is flexible enough to support a minor amendment like this.

+1, though I would prefer inverted over inverse.

"Inverse" feels pretty mathy/academic. That's not necessary bad, but IME it's rarely used outside of that context in spoken (US) english.

The only thing that comes to my mind when I hear "inverse" is the Inverse-square law.
The thing that comes to mind when I hear "inverted" is some sort of aerial trick.

The YouTube search results for inverse and inverted seems to show this well.

Since I believe they're synonyms, I would prefer to use the term that's more approachable due to it's usage outside of specialized domains.

#360InvertedBikeShedding :sunglasses:

+1 to the amendment.

To me, “inverse” feeling more mathy is exactly why it’s a more appropriate name for this than “inverted”. It’s a term of art. Just like an inverse mathematical function or an inverse matrix, an inverse diff is used to undo the original diff.

8 Likes

That could be a discussion in and of itself, but a "term of art" has inherent tradeoffs. It's saying there isn't a descriptive word in the popular vernacular, so we have to use a word that is less popular to describe something specific to a single domain that won't have a relevant meaning to laymen.

For people familiar with that domain, it feels natural. To anyone else, it feels foreign. e.g.

Great if you're familiar with those mathematical concepts, useless if you're not.

Given Swift's focus on approachability and education, when terms are synonyms, IMO the choice should lean towards the term with a more general usage.

But this is well into the bike-shedding territory so it's definitely not worth losing sleep over either way :slight_smile:

But the word in more general use, “inverted”, doesn't really have the right meaning when used in its common sense. So perhaps that is only more confusing than using a word that some may be unfamiliar with initially. As you said yourself:

1 Like

You seem to be arguing that high school math is too lofty a reach.

3 Likes

If you're in Jr. High, come from a place without that level of education readily available, or just don't like math, then yes.

To be clear my point isn't that terms that requires explanation/education should never be used, but that when there is a clear more approachable alternative, that alternative should be used.

1 Like

The term you so strenuously protest is the one you can find on wikipedia, because it happens to be the correct one. A CollectionDifference represents a function; the extension on RRC that uses it is called applying, consistent with a function. No matter what, the transformation that cancels it out is, well, an inverse function.

Anyway, if you're in junior high or in a place with no education and you get to the point where you're using collection diffing, you're probably eager to learn. Something that helps people who are eager to learn is using correct terminology. "inverse" isn't crazy jargon.

11 Likes

To be clear...as previously stated this is bike shedding and a pretty small issue, so I'm dropping it after this.

I never said it was.

If this was a mathematical API, it's use in math would make it the preferred term. This is not for mathematicians. This is a generalized API for use in working with Collections

If your background is in math (or you just like it), that term may make more sense because it's already familiar. My point is I think people outside of that realm rarely see/hear that term used, so it has little relevance to their existing experience.

IMO preferring mathematical terms over more generally used terms hurts a language's approachability and interest from people who aren't already in that domain. This would be far from the worst offender, but I think it's still relevant.

This is going to earn me ten years in bikeshedding + wikilawyering purgatory; nevertheless...

inverse is a noun, but more specifically, it's a participle of the verb invert. If the stdlib were to provide both mutating and nonmutating versions of this operation, the naming guidelines would fairly unambiguously require that they be called invert() and inverted():

When the operation is naturally described by a verb , use the verb’s imperative for the mutating method and apply the “ed” or “ing” suffix to name its nonmutating counterpart. [boldface original]

In this case, I don't think it really matters that no invert() method will be provided. The product is still the result of applying the operation invert, so the "naturally described by a verb" rules should apply.

I agree that inverse is more consistent with math terminology. But consistency with the language's own specific naming guidelines is more important than consistency with abstract algebra, especially in a case like this where the options are close to being interchangeable from a linguistic standpoint.

The issue I see with inverted() is that the word “inverted” has at least two uses: the mathematical one that we are discussing here, and a colloquial one that means something akin to “flipped upside down.” In order for users to understand the actual meaning of the function, they must already understand what an inverse is, so I don’t buy that inverted() is a more understandable name than inverse(). It’s only “more generally used” because there are multiple meanings which do not coincide with the actual operation that the function performs. inverse() does not suffer from the same dual meaning issue, so it’s better in that sense.

10 Likes