Add joined(by:)

[timvermeulen]

This PR adds 4 ways of joining sequences of sequences with a separator, two of which let you base the separator on the sequences right before and after it:

extension Sequence where Element: Sequence {
  public func joined(by separator: Element.Element)
    -> JoinedBySequence<Self, CollectionOfOne<Element.Element>>
  
  public func joined<Separator>(
    by separator: Separator
  ) -> JoinedBySequence<Self, Separator>
    where Separator: Collection, Separator.Element == Element.Element
  
  public func joined(
    by separator: (Element, Element) throws -> Element.Element
  ) rethrows -> [Element.Element]
  
  public func joined<Separator>(
    by separator: (Element, Element) throws -> Separator
  ) rethrows -> [Element.Element]
    where Separator: Sequence, Separator.Element == Element.Element
}

Also adds the following building blocks internally:

• Either and EitherSequence
• FlattenCollection that flattens a collection of collections without separators
• InterspersedMap that maps the sequence's elements and intersperses them with new elements at the same time

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary

[kylemacomber]

Top notch work!

So much great stuff here, which I'm sure we'll be able to mine for future additions!

[kylemacomber]

I assume this public access control is accidental?

Suggested change

	public struct Iterator: IteratorProtocol {
	internal struct Iterator: IteratorProtocol {

[kylemacomber]

Suggested change

	public mutating func next() -> Result? {
	internal mutating func next() -> Result? {

[kylemacomber]

Suggested change

	public func makeIterator() -> Iterator {
	internal func makeIterator() -> Iterator {

[LucianoPAlmeida]

Since enum decl is internal, this may also be internal too?

[natecook1000]

Looks great, @timvermeulen! 🎉

[natecook1000]

@swift-ci Please test