[stdlib] Rename flatten() to joined() (SE-0133)

[jtbandes]

What's in this pull request?

SE-0133: rename flatten() to joined().

Remaining step (pending core team feedback) will be to add a default value to the joined(separator:) variant for collections of Strings.

---

Before merging this pull request to apple/swift repository:

• Test pull request on Swift continuous integration.

Triggering Swift CI

The swift-ci is triggered by writing a comment on this PR addressed to the GitHub user @swift-ci. Different tests will run depending on the specific comment that you use. The currently available comments are:

Smoke Testing

Platform	Comment
All supported platforms	@swift-ci Please smoke test
All supported platforms	@swift-ci Please smoke test and merge
OS X platform	@swift-ci Please smoke test OS X platform
Linux platform	@swift-ci Please smoke test Linux platform

A smoke test on macOS does the following:

1. Builds the compiler incrementally.
2. Builds the standard library only for macOS. Simulator standard libraries and
   device standard libraries are not built.
3. lldb is not built.
4. The test and validation-test targets are run only for macOS. The optimized
   version of these tests are not run.

A smoke test on Linux does the following:

1. Builds the compiler incrementally.
2. Builds the standard library incrementally.
3. lldb is built incrementally.
4. The swift test and validation-test targets are run. The optimized version of these
   tests are not run.
5. lldb is tested.

Validation Testing

Platform	Comment
All supported platforms	@swift-ci Please test
All supported platforms	@swift-ci Please test and merge
OS X platform	@swift-ci Please test OS X platform
OS X platform	@swift-ci Please benchmark
Linux platform	@swift-ci Please test Linux platform

Lint Testing

Language	Comment
Python	@swift-ci Please Python lint

Note: Only members of the Apple organization can trigger swift-ci.

[CodaFi]

@swift-ci please smoke test and merge.

[jtbandes]

No, there's a real failure (in addition to all the other stuff that's broken right now). Typo on my part. I'll fix it right now.

[CodaFi]

Then let's try again, shall we?

@swift-ci please smoke test and merge.

[jtbandes]

I'm guessing it still won't pass due to all the UnsafePointer-related changes, but it's worth a shot :)

[jtbandes]

@CodaFi How about another shot now that CI builds are working?

[CodaFi]

@swift-ci please smoke test and merge.

[CodaFi]

Blocked on #3816. Now that that's fixed this will take one more build to sort.

[jtbandes]

Huh, now I know what the "update branch" button on github does.

[gribozavr]

@swift-ci Please test

[gribozavr]

LGTM. Linux failed for unrelated reasons, waiting for macOS.

[gribozavr]

@jtbandes Just noticed one thing. There are still two references to flatten(), in stdlib/public/core/Join.swift and stdlib/public/core/SequenceAlgorithms.swift.gyb, both in docs. Could you submit a separate PR with those fixes? (I'm asking for a separate PR so that we don't invalidate testing results on this PR, which is very close do being validated.)

[jtbandes]

@gribozavr Sure, I'll prepare a PR now. Also just submitted #3838 which is related.

[jtbandes]

🎉