[OrderedSet] Add OrderedSet.appending(contentsOf:)

[pm-dev]

Description

This PR adds a new public function on appending(contentsOf:) to OrderedSet. It is functionally equivalent to union(_:) but is more explicit about ordering. I find myself looking for this, rather than union because a mutating append(contentsOf:) already exists.

A counter argument to this addition would be to minimize duplicative APIs as much as possible to reduce API surface area. However, there's already precedent for "alternative" functions, given append(contentsOf:) and formUnion(_:) coexist. And in this case I believe it adds sufficient value to justify the addition.

It's second nature to look for an "append" on ordered collections in Swift. Arrays are ubiquitous and an append(contentsOf:) exists. However, unlike Array, OrderedSet does not support the + operator, so adding this as an alternative to union(_:) seems to fill a gap.

Detailed Design

The implementation is simple, copying the instance to a mutable value then calling append(contentsOf:) and returning the result. This is the same pattern to how union(_:) works.

Documentation

Symbol-level documentation has been added but I don't think it's necessary to update any guides, since this isn't adding any new functionality.

Testing

A new test_appending_Self has been added

Performance

Not profiled.

Source Impact

What is the impact of this change on existing users of this package? Does it deprecate or remove any existing API?

Checklist

• I've read the Contribution Guidelines
• My contributions are licensed under the Swift license.
• I've followed the coding style of the rest of the project.
• I've added tests covering all new code paths my change adds to the project (to the extent possible).
• I've added benchmarks covering new functionality (if appropriate).
• I've verified that my change does not break any existing tests or introduce unexpected benchmark regressions.
• I've updated the documentation (if appropriate).

[xwu]

However, unlike Array, OrderedSet does not support the + operator

Should OrderedSet just support the + operator?

[pm-dev]

Should OrderedSet just support the + operator?

Maybe so. Originally I thought + infers a semantic meaning of "concatenation" which doesn't totally make sense for sets (the Set type doesn't have a + operator). But maybe that's just overthinking it.