title: What's the best name for a non-mutating "add" method on an immutable collection?
body: <p>Sorry for the waffly title - if I could come up with a concise title, I wouldn't have to ask the question.</p>
  
  <p>Suppose I have an immutable list type. It has an operation <code>Foo(x)</code> which returns a new immutable list with the specified argument as an extra element at the end. So to build up a list of strings with values "Hello", "immutable", "world" you could write:</p>
  
  <pre class="lang-cs prettyprint-override"><code>var empty = new ImmutableList&lt;string&gt;();
  var list1 = empty.Foo("Hello");
  var list2 = list1.Foo("immutable");
  var list3 = list2.Foo("word");
  </code></pre>
  
  <p>(This is C# code, and I'm most interested in a C# suggestion if you feel the language is important. It's not fundamentally a language question, but the idioms of the language may be important.)</p>
  
  <p>The important thing is that the existing lists are <em>not</em> altered by <code>Foo</code> - so <code>empty.Count</code> would still return 0.</p>
  
  <p>Another (more idiomatic) way of getting to the end result would be:</p>
  
  <pre class="lang-cs prettyprint-override"><code>var list = new ImmutableList&lt;string&gt;().Foo("Hello")
                                        .Foo("immutable")
                                        .Foo("word");
  </code></pre>
  
  <p>My question is: <strong>what's the best name for Foo?</strong></p>
  
  <p><strong>EDIT 3</strong>: As I reveal later on, the name of the type might not actually be <code>ImmutableList&lt;T&gt;</code>, which makes the position clear. Imagine instead that it's <code>TestSuite</code> and that it's immutable because the whole of the framework it's a part of is immutable...</p>
  
  <p>(End of edit 3)</p>
  
  <p>Options I've come up with so far:</p>
  
  <ul>
  <li><code>Add</code>: common in .NET, but implies mutation of the original list</li>
  <li><code>Cons</code>: I believe this is the normal name in functional languages, but meaningless to those without experience in such languages</li>
  <li><code>Plus</code>: my favourite so far, it doesn't imply mutation <em>to me</em>. Apparently this is also <a href="http://en.wikibooks.org/wiki/Haskell/MonadPlus" rel="noreferrer">used in Haskell</a> but with slightly different expectations (a Haskell programmer might expect it to add two lists together rather than adding a single value to the other list).</li>
  <li><code>With</code>: consistent with some other immutable conventions, but doesn't have quite the same "additionness" to it IMO.</li>
  <li><code>And</code>: not very descriptive.</li>
  <li>Operator overload for + : I really don't like this much; I generally think operators should only be applied to lower level types. I'm willing to be persuaded though!</li>
  </ul>
  
  <p>The criteria I'm using for choosing are:</p>
  
  <ul>
  <li>Gives the correct impression of the result of the method call (i.e. that it's the original list with an extra element)</li>
  <li>Makes it as clear as possible that it doesn't mutate the existing list</li>
  <li>Sounds reasonable when chained together as in the second example above</li>
  </ul>
  
  <p>Please ask for more details if I'm not making myself clear enough...</p>
  
  <p><strong>EDIT 1:</strong> Here's my reasoning for preferring <code>Plus</code> to <code>Add</code>. Consider these two lines of code:</p>
  
  <pre class="lang-cs prettyprint-override"><code>list.Add(foo);
  list.Plus(foo);
  </code></pre>
  
  <p>In my view (and this <em>is</em> a personal thing) the latter is clearly buggy - it's like writing "x + 5;" as a statement on its own. The first line looks like it's okay, until you remember that it's immutable. In fact, the way that the plus operator on its own doesn't mutate its operands is another reason why <code>Plus</code> is my favourite. Without the slight ickiness of operator overloading, it still gives the same connotations, which include (for me) not mutating the operands (or method target in this case).</p>
  
  <p><strong>EDIT 2:</strong> Reasons for not liking Add.</p>
  
  <p>Various answers are effectively: "Go with Add. That's what <code>DateTime</code> does, and <code>String</code> has <code>Replace</code> methods etc which don't make the immutability obvious." I agree - there's precedence here. However, I've seen plenty of people call <code>DateTime.Add</code> or <code>String.Replace</code> and <em>expect mutation</em>. There are loads of newsgroup questions (and probably SO ones if I dig around) which are answered by "You're ignoring the return value of <code>String.Replace</code>; strings are immutable, a new string gets returned."</p>
  
  <p>Now, I should reveal a subtlety to the question - the type might <em>not</em> actually be an immutable list, but a different immutable type. In particular, I'm working on a benchmarking framework where you add tests to a suite, and that creates a new suite. It might be obvious that:</p>
  
  <pre class="lang-cs prettyprint-override"><code>var list = new ImmutableList&lt;string&gt;();
  list.Add("foo");
  </code></pre>
  
  <p>isn't going to accomplish anything, but it becomes a <em>lot</em> murkier when you change it to:</p>
  
  <pre class="lang-cs prettyprint-override"><code>var suite = new TestSuite&lt;string, int&gt;();
  suite.Add(x =&gt; x.Length);
  </code></pre>
  
  <p>That looks like it should be okay. Whereas this, to me, makes the mistake clearer:</p>
  
  <pre class="lang-cs prettyprint-override"><code>var suite = new TestSuite&lt;string, int&gt;();
  suite.Plus(x =&gt; x.Length);
  </code></pre>
  
  <p>That's just begging to be:</p>
  
  <pre class="lang-cs prettyprint-override"><code>var suite = new TestSuite&lt;string, int&gt;().Plus(x =&gt; x.Length);
  </code></pre>
  
  <p>Ideally, I would like my users not to have to be told that the test suite is immutable. I want them to fall into the pit of success. This <em>may</em> not be possible, but I'd like to try.</p>
  
  <p>I apologise for over-simplifying the original question by talking only about an immutable list type. Not all collections are quite as self-descriptive as <code>ImmutableList&lt;T&gt;</code> :)</p>