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