Naming of `chained(with:)`

[xwu (Xiaodi Wu)]

@Nevin

And let me state my counterargument more clearly:

The fact that followed(by:) works equally well with both a sequence (as proposed) and a single element (not proposed, probably unnecessary), is a significant advantage and benefit. It is a point in favor of this spelling.

That is because, if people actually want the single-element version (which I doubt the will), then we can easily add it as an overload with the same name and behavior.

I think you have overlooked the point of @Jumhyn's argument.

Consider a collection type T where T.Element == T. (Perhaps one might use such a type to represent HTML, our favorite toy example these days.) Suppose I have two instances representing the following two snippets of HTML:

<!-- List A -->
<ol>
  <li>1</li>
  <li>2</li>
  <li>3</li>
</ol>
<!-- List B -->
<ol>
  <li>4</li>
  <li>5</li>
  <li>6</li>
</ol>

What is the semantic meaning of listA.followed(by: listB)? There are three possibilities:

1. 1
2. 2
3. 3

1. 4
2. 5
3. 6

1. 1
2. 2
3. 3
4. 4
5. 5
6. 6

1. 1
2. 2
3. 3
4. 1. 4
   2. 5
   3. 6

The words "contents of" gives a strong indication to the reader that the elements in the second list are added after the elements of the first list (middle result). It also allows users to distinguish append(contentsOf:) from append(_:) (bottom result); without that label, two methods with the same name would have different semantics.

Now, we are trying to name a method that has the semantics shown in the top result. It is true that, if we merely wish to iterate over the list items, the top and middle result behave identically. But the result of the method we're naming is a full-blown collection type; we can and might want to do something other than iteration. For instance, we might want to actually render the HTML represented by the result; at that point, the top and middle results behave differently.