[swift-evolution] ed/ing, InPlace, Set/SetAlgebra naming resolution
Tyler Fleming Cloutier
cloutiertyler at aol.com
Sun Feb 14 14:17:44 CST 2016
> On Feb 14, 2016, at 8:27 AM, Dave Abrahams <dabrahams at apple.com> wrote:
>
>
> on Sat Feb 13 2016, Tyler Fleming Cloutier <cloutiertyler-AT-aol.com> wrote:
>
>> I would, personally, be very careful about discarding the mathematical
>> terms since they are so widely used and understood.
>
> IMO it's better to leave them aside than to use them in “creative” ways
> that might be misleading.
>
Agreed. I’m all for that.
>> One issue is that it’s going to be hard to search for the operation I
>> want considering I won’t be looking for "func
>> invertingMembershipOfContentsOf(other: Self) -> Self”. I’m concerned
>> people are going to have to do mental gymnastics to build the map from
>> math term to Swift function every time they want to look for a set
>> operation method. “func invertingMembershipOfContentsOf(other: Self)
>> -> Self” doesn’t exactly seem to fit in the commonly held Venn diagram
>> mental model of set operations. You could always have a documentation
>> comment that specifies the mathematical term so that people didn’t
>> have to double check themselves every time.
>>
>> That being said, if the autocomplete issue is not a concern, I’m of
>> the opinion that the names Ricardo proposed are short, clear, and are
>> not so hard to fit to my Venn diagram mental model.
>
> +1
>
>> However, I tend to think that if there has to be this much dancing to
>> name a set of fundamental operations, the guidelines aren’t
>> accomplishing their goal.
>
> I can't disagree.
>
>> It’s going to make it that much harder for people do design their own
>> APIs. I'm having quite a time trying to conform Mattt’s Surge API to
>> the guidelines.
>
> Please explain in detail. Without details we don't know what's wrong
> with the guidelines.
Ah, I apologize. I’ve gone into detail about this API on the list before, but I should have included the details here.
Here are my previous posts: https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160118/007560.html <https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160118/007560.html>
Basically the issues come down to the following. The Accelerate framework typical operates in a non-mutating way. This means that my API only has non mutating member functions and I should use the ed/ing rule according to the guidelines to name my methods.
This is very difficult for some methods. I’m able to frequently get around the problem for things like “sin” or “arctan” by keeping them as global functions, but I can’t do that for a number of methods. Consider:
remainder
dot (returns a scalar, thus there can’t be a mutating version, so should I just call it dot? Guidelines don’t really comment on this)
mean (same as above)
cross
reciprocal
threshold
copysign
fastFourierTransform
pow (arguably the method version should be called raisedTo)
I could force all these to be global functions only, but these are not as cut and dry as “sin” or “arctan”. I feel like I’d be splitting my API up into two parts just based on the fact that it’s difficult to use the ed/ing rule. That makes it very difficult for users to find certain functions in my API.
In this case there are no corresponding mutating operations because of the way Accelerate works, but one could certainly imagine an API with mutating counterparts. The way I read the guidelines, they seem to imply I should use ed/ing regardless of whether there is a mutating counterpart. I’d love to hear your thoughts on this.
Thanks,
Tyler
>
>>
>> Tyler
>>
>>> On Feb 13, 2016, at 9:09 PM, Ricardo Parada via swift-evolution <swift-evolution at swift.org> wrote:
>>>
>>> Hi Dave,
>>>
>>> I would be okay with staying away from the mathematical terms
>>> similar to what you are suggesting except that the union can still
>>> be made more concise if you use merged / merge for the base name and
>>> shorten the labels to a bare minimum without loosing clarity. In
>>> addition, the merge can have a second parameter with a default to
>>> false in order to implement the symmetric difference
>>> (a.k.a. exclusive or). Recall that symmetric difference is the
>>> union of two sets and then removing the intersection (or members in
>>> common). I think it looks perfect (concise and clear). What does
>>> everybody else think?
>>>
>>> Non-mutable
>>>
>>> let union = a.merged(with: b)
>>> let intersection = a.members(in: b)
>>> let difference = a.removingMembers(in: b)
>>> let symmetricDifference = a.merged(with: b, removingMembersInCommon: true)
>>>
>>> Mutable (In-Place)
>>>
>>> a.merge(with: b) // union in-place
>>> a.removeMembers(notIn: b) // intersect in-place
>>> a.removeMembers(in: b) // difference in-place
>>> a.merge(with: b, removeMembersInCommon: true) // symmetric difference in-place
>>>
>>> Ricardo Parada
>>>
>>>
>>>> On Feb 13, 2016, at 1:16 PM, Dave Abrahams via swift-evolution
>>>> <swift-evolution at swift.org <mailto:swift-evolution at swift.org>>
>>>> wrote:
>>>>
>>>>
>>>> on Fri Feb 12 2016, Ricardo Parada <swift-evolution at swift.org
>>>> <mailto:swift-evolution at swift.org>> wrote:
>>>>
>>>>> Hi all,
>>>>>
>>>>> I can’t make up my mind. Let me propose two different alternatives
>>>>> that I’m not sure if they have been considered:
>>>>>
>>>>> ALTERNATIVE 1
>>>>>
>>>>> Non-mutable (noun-based)
>>>>>
>>>>> - func union(other: Self) -> Self
>>>>> + func union(other: Self) -> Self Assumes union is a noun, i.e. not a verb
>>>>>
>>>>> - func intersect(other: Self) -> Self
>>>>> + func intersection(other: Self) -> Self
>>>>>
>>>>> - func subtract(other: Self) -> Self
>>>>> + func subtraction(other: Self) -> Self
>>>>>
>>>>> - func exclusiveOr(other: Self) -> Self
>>>>> + func symmetricSubtraction(other: Self) -> Self
>>>>>
>>>>> Mutable (verb-based)
>>>>>
>>>>> - mutating func unionInPlace(other: Self)
>>>>> + mutating func unite(other: Self)
>>>>>
>>>>> - mutating func intersectInPlace(other: Self)
>>>>> + mutating func intersect(other: Self)
>>>>>
>>>>> - mutating func subtractInPlace(other: Self)
>>>>> + mutating func subtract(other: Self)
>>>>>
>>>>> - mutating func exclusiveOrInPlace(other: Self)
>>>>> + mutating func symmetricSubtract(other: Self)
>>>>>
>>>>> Comments:
>>>>>
>>>>> With this alternative we keep the union name which I assume is
>>>>> popular. However, one has to accept unite as a verb (for the mutable
>>>>> version) as I wanted all the mutable methods use verbs for
>>>>> consistency. I think unite is acceptable because it can be found in
>>>>> the dictionary and it is a verb.
>>>>>
>>>>> Notice that all the non-mutable methods use nouns: union,
>>>>> intersection, subtraction and symmetricSubtraction.
>>>>>
>>>>> I understand some may oppose to symmetricSubtraction saying that
>>>>> symmetricSubraction is not as common as "exclusive or". However,
>>>>> using symmetricSubtraction is consistent with subtraction and it hints
>>>>> to a variation of the “subtraction" operation. We will get used to it
>>>>> quickly / easily.
>>>>>
>>>>> The mutable methods all use verbs: unite, intersect, subtract and symmetricSubtract.
>>>>>
>>>>> ALTERNATIVE 2
>>>>>
>>>>> Non-mutable
>>>>>
>>>>> - func union(other: Self) -> Self
>>>>> + func adding(other: Self) -> Self
>>>>>
>>>>> - func intersect(other: Self) -> Self
>>>>> + func intersecting(other: Self) -> Self
>>>>>
>>>>> - func exclusiveOr(other: Self) -> Self
>>>>> + func exclusiveOring(other: Self) -> Self
>>>>>
>>>>> - func subtract(other: Self) -> Self
>>>>> + func removing(other: Self) -> Self
>>>>>
>>>>> Mutable
>>>>>
>>>>> - mutating func unionInPlace(other: Self)
>>>>> + mutating func add(other: Self)
>>>>>
>>>>> - mutating func intersectInPlace(other: Self)
>>>>> + mutating func intersect(other: Self)
>>>>>
>>>>> - mutating func exclusiveOrInPlace(other: Self)
>>>>> + mutating func exclusiveOr(other: Self)
>>>>>
>>>>> - mutating func subtractInPlace(other: Self)
>>>>> + mutating func remove(other: Self)
>>>>>
>>>>> Comments: This alternative gives up on union in favor or add. Many
>>>>> may not like this, that is why I have it as the second alternative.
>>>>> It brings back exclusiveOr and treats it as a verb. Some may argue
>>>>> that exclusiveOr is a noun for the "exclusive or" operation.
>>>>
>>>> If we are going to force Set fit the naming guidelines, I would prefer
>>>> to stay away from the mathematical terms altogether.
>>>>
>>>> func insertingContentsOf(other: Self) -> Self // union
>>>> mutating func insertContentsOf(other)
>>>>
>>>> func members(in other: Self) -> Self // intersection
>>>> mutating func removeMembers(notIn: other)
>>>>
>>>> func removingMembersAndAddingNonMembers(in other: Self) -> Self // symmetric difference
>>>> mutating func removeMembersAndAddingNonMembers(in other: Self)
>>>>
>>>> func removingMembers(in other: Self) -> Self // subtract
>>>> mutating func removeMembers(in other: Self)
>>>>
>>>> If it would help with clarity, we could replace "in" with "foundIn"
>>>> above.
>>>>
>>>> --
>>>> -Dave
>>>>
>>>> _______________________________________________
>>>> swift-evolution mailing list
>>>> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
>>>> https://lists.swift.org/mailman/listinfo/swift-evolution
>>>> <https://lists.swift.org/mailman/listinfo/swift-evolution>
>>> _______________________________________________
>>> swift-evolution mailing list
>>> swift-evolution at swift.org
>>> https://lists.swift.org/mailman/listinfo/swift-evolution
>>
>
> --
> -Dave
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160214/2045662f/attachment.html>
More information about the swift-evolution
mailing list