New materialize() operator over BlockingObservable

[sgleadow]

This is based on a discussion in #1355 and on previous changes in #1354.

We introduce new extension to BlockingObservable called materialize() which returns a result type capturing the completed/failed status of the sequence, along with and elements and the error. The result type looks like this:

public enum SequenceMaterializeResult<T> {
    case completed(elements: [T])
    case failed(elements: [T], error: Error)
}

Internally, the rest of the BlockingObservable+Operators use SequenceMaterializeResult, and only throw at the last minute if an unexpected error occurs. This is mostly to maintain a backwards compatible interface for the existing operators, so it's a non-breaking change.

[freak4pc]

Looks really good, I just have one comment over naming that I'd like to discuss, and also I think it would be really nice to add a quick section on using this operator here: https://github.com/ReactiveX/RxSwift/blob/master/Documentation/UnitTests.md#integration-tests

[freak4pc]

Not sure on the naming here,
Would expect MaterializedSequenceResult<T> perhaps

Also wondering if it could be nice to go with elements and errors similar to RxSwiftExt's operators that extend materialize?

[sgleadow]

The rename totally make sense, I'll do that. In terms of errors do you mean in the enum case name or in the associated value parameter?

I'm not sure plural errors makes sense given it's only a single error that terminates the sequence? (I think, Rx newbie here).

1. In case name:

public enum MaterializedSequenceResult<T> {
    case completed(elements: [T])
    case errors(elements: [T], error: Error)
}

2. In associated value name

public enum MaterializedSequenceResult<T> {
    case completed(elements: [T])
    case failed(elements: [T], errors: [Error])
}

[sgleadow]

Good point, examples added to UnitTests.md documentation

[freak4pc]

Cleaned up the documentation a bit, and after thinking this over night yesterday - .completed and .failed make sense to me. Even though there is a disparity between what materialize() returns in RxSwift vs RxBlocking, I think that should be fine mostly.

I think this PR is all good to go on my end. Let's wait for @kzaher to review this and merge :)

[freak4pc]

@sgleadow Could you also real quickly add a CHANGELOG entry with something along the lines of "Added materialize() operator for RxBlocking's BlockingObservable`"

[sgleadow]

Thanks for the help. I had no idea you could push to my fork!

I've added a line to the CHANGELOG referencing this PR.

[freak4pc]

@sgleadow Yeah you can do it only through GitHub's UI apparently but its sometimes helpful for README stuff :) Thanks for all the hard work! @sgleadow

Don't think there's anything blocking (pun intended) here, as soon as @kzaher finds the time

[kzaher]

I've found some smaller items, but in general looks good.

[kzaher]

eith -> with?

[kzaher]

I think we should document this, what completed means, what failed means and what is this enum for.

[freak4pc]

I actually added this in the documentation: https://github.com/ReactiveX/RxSwift/pull/1383/files/d416ff5e5c4f461c8afe262824f7d34f73d06e81#diff-6eb6c44aac5cc628cd1c254752e52e36R101

Did you want to see something besides that?

[freak4pc]

Or your mean inline documentation block for that enum ?

[sgleadow]

I've tweaked the UnitTests.md and added an example of the successful case, not just the error case.

Although if you mean inline docs like @freak4pc mentioned, I can add that.

[sgleadow]

I looked through other parts of the RxSwift codebase and thought an inline comment describing the MaterializedSequenceResult was also appropriate, so I've added that also.

[kzaher]

Typo sequene

[kzaher]

Typo eith.