What's the best name for a non-mutating "add" method on an immutable collection? [closed]

How about creating a wrapper class with an Augment (or AugmentWith) method?

Since this question is now basically a thesaurus: How about .Bring(). As in, give me this list and bring this element with it?

Foo = List.Bring('short'); .Bring('longer'); .Bring('woah'); 

It doesn't roll off the tongue, but it means it, to me.

Actually, AndBring() might be even better.

I'd go with operator overloading +. The reason is that that's the way it works in Python - .append() on a list mutates the list, while doing + with another list creates a new list. + also definitely does not imply mutation. I think that's why you like .Plus() so much, so if you don't want to operator overload, then you can go with .Plus().

list.copyAndAppend(elt)

How does that sound?)

As was previously mentioned, you're trying to do 2 things at once and micro-optimizing just for that purpose. If copying occurs away from original collection definition, names like "Add","Append" will only confuse.

"CloneAppend" is what I might use in this situation. Something tells me I wouldn't be in this situation. I believe that soon you'll find yourself in need of other kinds of similar operations like "CloneFirstN" or "CloneRemoveLast". And soon you'll realize that it's much better to chain the clone/copy method, append/remove whatever you need, then convert the collection back to immutable even if it takes an extra line of code.

Personally I would call the method Clone and call the parameter AdditionalValue as that is essentially what it appears to be doing and would be easily understandable e.g.

var empty = new ImmutableList<string>(); var list1 = empty.Clone("Hello"); var list2 = list1.Clone("immutable"); var list3 = list2.Clone("word"); 

For this kind of functions I usually use the verb at the second form, Added in this case.

This convention is used by Qt, for example QVector2D::normalized returns a normalized vector, while QVector2D::normalize normalizes a vector.

In the same way Added would return the object with a new added item.

I would go with "CreateNewListWithAdditionalItems"

I dont mind long names, but this one is telling you what it will actually do. Also I would throw an exception if you use Add or any other altering methods.

Borrowing from C, how about Concat

The problem with methods like String.Replace is that the user can mistakenly think that there's mutation going on because he can ignore the return value. So use an out parameter for the "return" value. The user can't ignore that:

public class ImmutableList<T> { public ImmutableList(params T[] items) { // ... } /// <summary> /// Creates a new list with the items in this list plus the supplied items. /// </summary> /// <param name="newList"> /// The new list created for the operation. /// This is also the return value of this method. /// </param> /// <param name="items">Items to add to the new list.</param> /// <returns>The new list.</returns> public ImmutableList<T> Add(out ImmutableList<T> newList, params T[] items) { // ... } } 

Usage:

var list = new ImmutableList<string>("Hello", "Immutable"); ImmutableList<string> newList; list.Add(out newList, "World"); 

Personally I'd go with Pad(..) perhaps if you're after a fluent style, also with an extension method of AndWith(..)

var list = new ImmutableList<string>().Pad("Hello") .AndWith("immutable") .AndWith("word"); 

I know this is beating a seemingly dead horse, but I think you may be approaching this in an odd way (hence the naming difficulty). When I have an immutable object, I don't often expect that the object will have functions that imply mutability (like Add or AddAll). I know that String & DateTime do this, but even I have fallen victim to forgetting to use the results from DateTime / String functions so I would avoid those pitfalls if possible.

If I were you, I would follow the Builder pattern similar to what Guava uses. See immutable collections in Guava. Basically the concept is that you construct the immutable object with everything it is ever going to contain. If you want to make a new immutable object, you need to use a new builder.

var suite = new TestSuite.Builder<string, int>().add(newTest).build(); 

You can expand upon the builder to allow a variety of modifications to the test suite (using standard list naming conventions like add / remove if you wish) before the user calls build.

A very late answer, but I wanted to add my two cents: I think the point here could be the verb tense more than the verb itself:

var output= myList.joinedWith("Element"); //or AddedTo, ConcatenatedTo... 

The participle changes the meaning, in my opinion: we are no adding anything to myList, but returning the result of the operation.

Another point in favor of Plus is the new mostly immutable Java time API, where plus() is for example used to add to Instants.

Instead/In addition to a name, immutable containers collections are a classic case for operator overloading (as is already the case for int/string/etc). There are two advantages here:

• conciseness: l1 = l + o1 + o2 rather than l1 = l.Add(o1).Add(o2)

• using assignment operators: l += o rather than l = l.Add(o)

Using operators also makes the code less error prone, it is common when switching from mutable to immutable types to forget the assignment and just write ie l.Add(o); (with disastrous effects) however just writing l+o; without using the result really sticks out.

You can see this in action in the collections that come as part of the F package.

Consistency in those things is important, I like to follow the naming conventions in Swift API Design Guidelines:

• Name functions and methods according to their side-effects

  • Those without side-effects should read as noun phrases, e.g. x.distance(to: y), i.successor().

  • Those with side-effects should read as imperative verb phrases, e.g., print(x), x.sort(), x.append(y).

  • Name mutating/non-mutating method pairs consistently. A mutating method will often have a non-mutating variant with similar semantics, but that returns a new value rather than updating an instance in-place.

    • When the operation is naturally described by a verb, use the verb’s imperative for the mutating method and apply the “ed” or “ing” suffix to name its non-mutating counterpart.

      Mutating	Non-mutating
      x.sort()	z = x.sorted()
      x.append(y)	z = x.appending(y)

    • When the operation is naturally described by a noun, use the noun for the non-mutating method and apply the “form” prefix to name its mutating counterpart.

      Non-mutating	Mutating
      x = y.union(z)	y.formUnion(z)
      j = c.successor(i)	c.formSuccessor(&i)

Since the mutating version of the method is Add, the non-mutating version could be Added or Adding:

// Note that following the convention results in code being written as english sentences var empty = new ImmutableList<string>(); var list1 = empty.Adding("Hello"); var list2 = list1.Adding("immutable"); // `list2` is equal to `list1` adding "immutable" var list3 = list2.Adding("word");