<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto"><div><span></span></div><div><div></div><div><span style="background-color: rgba(255, 255, 255, 0);">I think those mutating functions <b>below</b> are fine. However the non mutating ones feel a bit awkward since they don't read well and are less clear than just "union" and "unionInPlace".</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">But there is also a consistency argument (about Collection methods). Though "Set" is "more mathematical" than other data structures like Array or Dictionary.</span></div><div><br></div><div>For reference the "current" implementation:</div><div><br></div><div><blockquote type="cite"><span style="background-color: rgba(255, 255, 255, 0);">Hi everyone,</span><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">First - I want to thank all of the contributors on this discussion for helping us with this obviously tricky naming problem.</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">Dave has already described some of the thinking that has gone into the iterations of the API for Set. You’ve seen stages of that evolution here.</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">We’re at the point where we need to make a decision and move on. Not because it’s impossible to come up with better ideas, but because we want to continue to work on the remaining aspects of the naming proposals that we’ve put forth on this list. </span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">In the future, there is always the opportunity for members of the community and members of the core team to propose ideas like newly discovered names, improvements to the language like keywords for mutation-in-place or special operators, or whatever great thing comes next. If we decide to do those, then we will be sure to consider the impact on the APIs we choose today. There are many tools in our toolbox for rolling out those improvements (deprecation and replacement being the one we’ve used countless times for framework and library API).</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">So: by incorporating your ideas in this thread, along with those from other members of the API naming working group, and by adhering to the proposed guidelines as closely as possible, we’re going to go with the following API changes for SetAlgebra for Swift 3:</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// Returns the set of elements contained in `self`, in `other`, or in both `self` and `other`.</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// EXISTING: union</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">@warn_unused_result</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">func</span><span class=""> insertingContentsOf(other: </span><span class="">Self</span><span class="">) -> </span><span class="">Self</span></span></div><p class="" style="margin: 0px; line-height: normal; min-height: 13px;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><br class="webkit-block-placeholder"></span></p><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// Insert all elements of `other` into `self`.</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// EXISTING: unionInPlace</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">mutating</span><span class=""> </span><span class="">func</span><span class="">insertContentsOf(other: </span><span class="">Self</span><span class="">)</span></span></div><p class="" style="margin: 0px; line-height: normal; min-height: 13px;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><br class="webkit-block-placeholder"></span></p><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// Returns the set of elements contained in both `self` and `other`.</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// EXISTING: intersect</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">@warn_unused_result</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">func</span><span class=""> intersection(other: </span><span class="">Self</span><span class="">) -> </span><span class="">Self</span></span></div><div class="" style="margin: 0px; line-height: normal; min-height: 13px;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""></span><br class=""></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// Removes all elements of `self` that are not also present in `other`.</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// EXISTING: intersectInPlace</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">mutating</span><span class=""> </span><span class="">func</span><span class=""> intersect(other: </span><span class="">Self</span><span class="">)</span></span></div><div class="" style="margin: 0px; line-height: normal; min-height: 13px;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""></span><br class=""></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// Returns the set of elements contained in `self` or in `other`, but not in both `self` and `other`.</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// EXISTING: exclusiveOr</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">@warn_unused_result</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">func</span><span class=""> invertingIntersection(other: </span><span class="">Self</span><span class="">) -> </span><span class="">Self</span></span></div><p class="" style="margin: 0px; line-height: normal; min-height: 13px;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><br class="webkit-block-placeholder"></span></p><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// Replaces `self` with a set containing all elements contained in either `self` or `other`, but not both.</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// EXISTING: exclusiveOrInPlace</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">mutating</span><span class=""> </span><span class="">func</span><span class="">invertIntersection(other: </span><span class="">Self</span><span class="">)</span></span></div><p class="" style="margin: 0px; line-height: normal; min-height: 13px;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><br class="webkit-block-placeholder"></span></p><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// Returns the set of elements contained in `self` but not in `other`.</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// EXISTING: subtract</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">@warn_unused_result</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">func</span><span class=""> removingContentsOf(other: </span><span class="">Self</span><span class="">) -> </span><span class="">Self</span></span></div><p class="" style="margin: 0px; line-height: normal; min-height: 13px;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><br class="webkit-block-placeholder"></span></p><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// Removes all elements of `other` from `self`.</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">/// EXISTING: subtractInPlace</span></span></div><div class="" style="margin: 0px; line-height: normal;"><span style="background-color: rgba(255, 255, 255, 0);"><span class=""> </span><span class="">mutating</span><span class=""> </span><span class="">func</span><span class="">removeContentsOf(other: </span><span class="">Self</span><span class="">)</span></span></div></div><div class=""><span class="" style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">Here is a summary of the reasons behind the decision:</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">1. As Dave said, it is important that we are able to apply our guidelines without an exception to such a core type. It’s not just about one particular Set type either, as these methods appear on many places in API (for example — all options are now Sets as well), thanks to Swift support for protocol-oriented-programming.</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">2. Using ‘<font class="">insert</font>’ instead of ‘<font class="">union</font>’ makes the method part of a family with the existing API on SetAlgebra:<font class=""> <span class="">mutating</span><span class=""> </span><span class="">func</span><span class="">insert(member:</span><span class="">)</span></font>. Indeed - the language of ‘<font class="">insert</font>’ has been in the markdown comment since the beginning. The same justification applies to using ‘<font class="">remove</font>’ instead of ‘<font class="">subtract</font>’.</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">3. The <font class="">ContentsOf</font> suffix is precedented by RangeReplaceableCollection, as a way to disambiguate inserting the contents of some collection vs the collection itself. It makes sense to reuse it here instead of using new terminology.</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">4. With the decision to use ‘<font class="">insert</font>’ and ‘<font class="">remove</font>’, we have built a very succinct vocabulary of operations on set: </span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><span class="Apple-tab-span" style="white-space: pre;"> </span>operations which add content (<font class="">insert</font>)</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><span class="Apple-tab-span" style="white-space: pre;"> </span>operations which remove content (<font class="">remove</font>). </span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">That leaves us with operations which both add and remove content. Intersect is straightforward enough and does not have significant naming challenges, so we keep it and apply the noun-phrase rule to the non-mutating function to distinguish it from the mutating function. exclusiveOr is trickier. However, I believe the suggestion made here of using <font class="">invert</font> leads us to a succinct name that conveys the right meaning, without putting two verbs in the base name.</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">We will also add additional documentation to each of these methods to describe their mathematical underpinnings. I hope that will aid developers in finding the right method, if they are not already familiar with the terminology we choose.</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">Again, sincere thanks for all of your input here.</span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);"><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);">- Tony</span></div></blockquote></div><div><br></div><div>===============================</div><div><br></div><div>- Maximilian</div><div><br>Am 16.02.2016 um 04:28 schrieb Ricardo Parada <<a href="mailto:rparada@mac.com">rparada@mac.com</a>>:<br><br></div><blockquote type="cite"><div><meta http-equiv="Content-Type" content="text/html charset=utf-8">Hi Maximilian,<div class=""><br class=""></div><div class="">I think using Term of Art for Sets is fine for the non-mutable methods. They map well to the operators: ∪ (union), ∩ (intersection), ∖ (difference), △ (symmetric difference), <span style="vertical-align: super; font-size: 12px;" class="">c </span>(complement).<div class=""><br class=""></div><div class="">When it comes to mutating the set it is all about merging or removing members. The english language works just fine for the mutable methods. There is no need for using a Term of Art for these.</div><div class=""><br class=""></div><div class=""><div class=""><b class="">Non-mutable</b></div><div class=""><br class=""></div><div class=""><font face="Consolas" class=""><font size="2" class="">let union = </font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font size="2" class="">a.union(b)</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font color="#438139" size="2" class="">// </font></font><font color="#438139" face="Consolas" size="2" class="">a ∪ b </font></div><div class=""><font face="Consolas" class=""><font size="2" class="">let intersection = </font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font size="2" class="">a.intersection(b)</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font color="#438139" size="2" class="">// </font></font><font color="#438139" face="Consolas" size="2" class="">a ∩ b</font></div><div class=""><font face="Consolas" class=""><font size="2" class="">let difference = </font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font size="2" class="">a.difference(b)</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font color="#438139" size="2" class="">// a </font></font><font color="#438139" face="Consolas" size="2" class="">\ b</font></div><div class=""><font face="Consolas" size="2" class=""><br class=""></font></div><div class=""><font face="Consolas" size="2" class="">let symmetricDifference = <span class="Apple-tab-span" style="white-space: pre;"> </span>a.symmetricDifference(b)<span class="Apple-tab-span" style="white-space: pre;"> </span><font color="#438139" class="">// a</font></font><font color="#438139" class=""><font face="Consolas" style="font-size: 12px;" class=""> </font><span style="font-size: 12px;" class="">△</span> <span style="font-family: Consolas; font-size: small;" class="">b</span></font></div><div class=""><div class=""><font face="Consolas" class=""><font size="2" class="">let symmetricDifference =</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font size="2" class="">a.intersectionComplement(b)</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font color="#438139" size="2" class="">// (a </font></font><font color="#438139" face="Consolas" size="2" class="">∩ b)</font><span style="vertical-align: super; color: rgb(67, 129, 58); font-size: 12px;" class="">c</span><span style="color: rgb(67, 129, 57); font-family: Consolas; font-size: small;" class=""> </span><span style="color: rgb(67, 129, 57); font-family: Consolas; font-size: small;" class=""> == </span><span style="color: rgb(67, 129, 57); font-family: Consolas; font-size: small;" class="">a </span><span style="color: rgb(67, 129, 57); font-family: Consolas; font-size: small;" class="">△</span><span style="color: rgb(67, 129, 57); font-family: Consolas; font-size: small;" class=""> </span><span style="color: rgb(67, 129, 57); font-family: Consolas; font-size: small;" class="">b</span></div><div class=""><font face="Consolas" class=""><font size="2" class="">let symmetricDifference = </font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font size="2" class="">a.unionWithoutIntersection(b)</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font color="#438139" size="2" class="">// (a </font></font><font color="#438139" face="Consolas" size="2" class="">∪ b) \ (a ∩ b) == a △ b</font></div><div class=""></div><div class=""><font face="Consolas" class=""><font size="2" class="">let symmetricDifference = </font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font size="2" class="">a.unionMinusIntersection(b)</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font color="#438139" size="2" class="">// </font></font><font color="#438139" face="Consolas" size="2" class="">(a ∪ b) \ (a ∩ b) == a △ b</font></div></div><div class=""><div class=""></div></div></div><div class=""><br class=""></div><div class="">For the four "symmetric difference" alternatives listed above I am not sure I like <font face="Consolas" size="2" class="">intersectionComplement</font> because there is a relative complement and an absolute complement. It is not clear which complement I am referring to. If it was up to me I would pick <font face="Consolas" size="2" class="">symmetricDifference</font> or <font face="Consolas" size="2" class="">unionWithoutIntersection</font>. I am used to both of these but think <font face="Consolas" size="2" class="">unionWithoutIntersection</font> gives a better visual of what it is. Everybody understands union, intersection and difference.</div><div class=""><br class=""></div><div class=""><div class=""><b class="">Mutable (verb-based)</b></div><div class=""><br class=""></div><div class="">I like the verb <font face="Consolas" class="">merge</font> better than <font face="Consolas" class="">add</font> because it conveys the idea that two members that are equal become one, i.e. there are no duplicate members. But <font face="Consolas" class="">add</font> could work equally well.</div><div class=""><br class=""></div><div class="">If <font face="Consolas" size="2" class="">a</font> is a mutable set then you may add:</div><div class=""><br class=""></div><div class=""><div class=""><font face="Consolas" class=""><font size="2" class="">a.merge(membersIn: b)</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font color="#438139" size="2" class="">// union in-place</font></font></div><div class=""><font face="Consolas" class=""><font size="2" class="">a.remove(membersNotIn: b)</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font color="#438139" size="2" class="">// intersection in-place</font></font></div><div class=""><font face="Consolas" class=""><font size="2" class="">a.remove(membersIn: b)</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font color="#438139" size="2" class="">// difference in-place</font></font></div><div class=""><font face="Consolas" class=""><font size="2" class="">a.merge(membersRemovingIntersection: b)</font><span class="Apple-tab-span" style="font-size: small; white-space: pre;"> </span><font color="#438139" size="2" class="">// symmetric difference in-place</font></font></div></div><div class=""><font face="Consolas" size="2" class=""><br class=""></font></div><div class=""><font face="Consolas" size="2" class=""><br class=""></font></div><div class=""><font face="Consolas" size="2" class=""><br class=""></font></div><div class=""><br class=""><div><blockquote type="cite" class=""><div class="">On Feb 15, 2016, at 6:20 AM, Maximilian Hünenberger via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><meta http-equiv="content-type" content="text/html; charset=utf-8" class=""><div dir="auto" class=""><div class=""></div><div class="">I also prefer (2). Isn't "union", "intersection", ... a "Term of Art"? See the guidelines under "<strong style="box-sizing: border-box; background-color: rgba(255, 255, 255, 0);" class="">Stick to the established meaning</strong>".</div><div class=""><br class=""></div><div class="">So we should stick to the mathematical naming.</div><div class=""><br class=""></div><div class="">Since these terms almost always return a new instance we should have an obvious mutating version with an "inPlace" suffix.</div><div class=""><br class=""></div><div class="">- Maximilian</div><div class=""><br class="">Am 14.02.2016 um 22:37 schrieb Xiaodi Wu via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>>:<br class=""><br class=""></div><blockquote type="cite" class=""><div class="">From a 10,000-ft view, I'd suggest that the noun/verb rule consistently runs into a problem with mathematical terms.<br class=""><br class="">In general, mathematical functions don't have verb forms. You 'compute' the reciprocal, or 'find' the reciprocal, or 'take' the reciprocal, you don't 'reciprocate' or 'reciprocalize'. Likewise for trigonometric functions, etc. Nor can you really 'cross produce'...<br class=""><br class="">So consistent is this trend that where two words might be noun/verb counterparts, like intersect/intersection and transform/transformation, common math usage treats both as acceptable nouns.<br class=""><br class="">In colloquial usage, you might verb the noun, but then by definition the verb and noun become the same. Then, to generate a noun phrase/participle/etc. that looks different from the verb, you have to noun-ify the verbed noun.<br class=""><br class="">Without an exception for mathematical function names, the only solution to fulfill these new Swift rules are clobbering the well-known math name or not using the math name at all. Indeed all proposed solutions so far come down to one of four options, either applied globally or only to sets for now, punting the rest down the road:<br class=""><br class="">(1) Abandon the rule, making a new one (e.g.: .=)<br class="">(2) Make an exception to the rule for math function names<br class="">(3) Generate the least offensive noun-ified verbed nouns based on math function names<br class="">(4) Don't use math function names<br class=""><br class="">(1) is off the table, according to the core team. My vote at this point is for (2), and I see that a few others have voiced that opinion. It'd be nice to get a sense from the core team if that is even a possibility. (3) has elicited a lot of discussion and visceral reactions. (4) might be workable for sets alone but surely can't be a generalized solution for all mathematical concepts to be encountered in Swift.<br class=""><div class="gmail_quote"><div dir="ltr" class="">On Sun, Feb 14, 2016 at 3:14 PM Tyler Fleming Cloutier via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:<br class=""></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word" 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" target="_blank" class="">dabrahams@apple.com</a>> wrote:</div><br class=""><div class=""><br style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><span style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing: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;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" target="_blank" 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;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing: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;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><br style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><blockquote type="cite" style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><blockquote type="cite" class="">On Feb 14, 2016, at 8:27 AM, Dave Abrahams <<a href="mailto:dabrahams@apple.com" target="_blank" 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/" target="_blank" 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=""> </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" target="_blank" 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" target="_blank" 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;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><span style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing: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;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><span style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing: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;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><span style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing: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;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><br class=""></div></blockquote><div class=""><br class=""></div></div></div><div style="word-wrap:break-word" class=""><div class=""><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></div><div style="word-wrap:break-word" class=""><div class=""><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;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><blockquote type="cite" style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing: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" target="_blank" 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=""> </span><span style="white-space:pre-wrap" class=""> </span><span style="white-space:pre-wrap" class=""> </span><span style="white-space:pre-wrap" class=""> </span>a.merged(with: b)<br class="">let intersection =<span class=""> </span><span style="white-space:pre-wrap" class=""> </span><span style="white-space:pre-wrap" class=""> </span>a.members(in: b)<br class="">let difference =<span class=""> </span><span style="white-space:pre-wrap" class=""> </span><span style="white-space:pre-wrap" class=""> </span>a.removingMembers(in: b)<br class="">let symmetricDifference =<span class=""> </span><span style="white-space:pre-wrap" class=""> </span>a.merged(with: b, removingMembersInCommon: true)<br class=""><br class="">Mutable (In-Place)<br class=""><br class="">a.merge(with: b)<span style="white-space:pre-wrap" class=""> </span><span style="white-space:pre-wrap" class=""> </span>// union in-place<br class="">a.removeMembers(notIn: b)<span style="white-space:pre-wrap" class=""> </span>// intersect in-place<br class="">a.removeMembers(in: b)<span style="white-space:pre-wrap" class=""> </span><span style="white-space:pre-wrap" class=""> </span>// difference in-place<br class="">a.merge(with: b, removeMembersInCommon: true)<span style="white-space:pre-wrap" class=""> </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" target="_blank" class="">swift-evolution@swift.org</a> <<a href="mailto:swift-evolution@swift.org" target="_blank" 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" target="_blank" class="">swift-evolution@swift.org</a><br class=""><<a href="mailto:swift-evolution@swift.org" target="_blank" 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 style="white-space:pre-wrap" class=""> </span><span style="white-space:pre-wrap" class=""> </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=""> </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=""> </span><br class="">-Dave<br class=""><br class="">_______________________________________________<br class="">swift-evolution mailing list<br class=""><a href="mailto:swift-evolution@swift.org" target="_blank" class="">swift-evolution@swift.org</a> <<a href="mailto:swift-evolution@swift.org" target="_blank" class="">mailto:swift-evolution@swift.org</a>><br class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" target="_blank" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class=""><<a href="https://lists.swift.org/mailman/listinfo/swift-evolution" target="_blank" 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" target="_blank" class="">swift-evolution@swift.org</a><br class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" target="_blank" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class=""></blockquote><br class=""></blockquote><br class="">--<span class=""> </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;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><span style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;float:none;display:inline!important" class="">--<span class=""> </span></span><br style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px" class=""><span style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;float:none;display:inline!important" class="">-Dave</span></div></blockquote></div></div>_______________________________________________<br class="">
swift-evolution mailing list<br class="">
<a href="mailto:swift-evolution@swift.org" target="_blank" class="">swift-evolution@swift.org</a><br class="">
<a href="https://lists.swift.org/mailman/listinfo/swift-evolution" rel="noreferrer" target="_blank" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class="">
</blockquote></div>
</div></blockquote><blockquote type="cite" class=""><div class=""><span class="">_______________________________________________</span><br class=""><span class="">swift-evolution mailing list</span><br class=""><span class=""><a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a></span><br class=""><span class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a></span><br class=""></div></blockquote></div>_______________________________________________<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">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class=""></div></blockquote></div><br class=""></div></div></div></div></blockquote></div></body></html>