Wait, what?
------------

Yes, polymorphism is great in Java. `Animal.speak()`, `Dog.speak()`, `Cat.speak()`, and so on.

But sometimes you want to be REALLY EXPLICIT about the possible types of objects you're dealing with, either (ha ha)
because they don't logically make sense in the same inheritance structure or because you want to limit your
possible cases to exactly two classes.

For example, let's say I'm dealing with my code and some third-party library that still uses `java.util.Date` (a class
that has been largely deprecated since JDK 1.1, and is almost always a strictly-worse choice than using either the newer
`java.time` apis, or Joda Time) .

Terrible, I know, but there's always *horrible legacy code* out there in the world.

I don't want to further propagate this old usage of a terrible deprecated class, so I, a Modern Java Developer, prefer
to use `java.time.LocalDateTime` in my code.

Except great, now I've gotta deal with grabbing a `List` from *these* and a `List` from *those* and
then do a bunch of gnarly conversion everywhere.

Using `Either.java`, I can instead easily build a `List>`. This tells me (and the compiler)
that I'm dealing with a bunch of things that are *either* a Date (yuck) or a LocalDateTime.

I can even nicely convert them all into LocalDateTimes:

```java

List> birthdays = allThePeople.stream()
.map(person -> Either.either(this::getDeprecatedDOBFromPerson, this::getNiceNewDOBFromPersonIfAvailable)
.collect(Collectors.toList());

List convertedBirthdays = birthdays.stream()
.map(eitherDateOrLocalDateTime.fold(
(Date deprecatedDOB) -> myFunctionToConvertDateToLocalDateTime(deprecatedDOB),
(LocalDatetime newDOB) -> newDOB
)).collect(Collectors.toList());
```

Boom. Now you have a list of LocalDateTimes, and it's explicit from the code that some of the people had deprecated
Dates, while others had nice, shiny new LocalDateTimes. Even the compiler can tell!

Other common use-cases for an `Either` include capturing and handling errors gracefully using
`Either`. As mentioned earlier, the convention in the Haskell world (from
which I totally "borrowed" the Either) is that an Either gives you "either the Right answer or whatever's Left" -- that
is, errors on the left, expected output on the right.

For this reason, this Either is right-biased; if you give it `Either.either(()->42, ()->"Hello, World!");`, you'll get a
`Right` containing `"Hello, World!"`, not a `Left` containing `42`. I swear, it's not a political thing; there just
needs to be a predictable rule-of-thumb for how to handle it when the Either gets *both* a left value *and* a right
value (after all, it's called an *Either*, not a *Both*).

`Result`
------

Because this errors-to-the-left, results-to-the-right idiom is so common, this library also includes a `Result` class,
which instead of being `Left` or `Right` is `Err` or `Ok`. Instead of `Either.either(() -> "left", () -> 42)`,
the constructor method you'll want is `Result.attempt(() -> someMethodThatMightThrowAnException())`. You can even chain
a series of possibly-failing functions using `map`:

```java
Result = Result.attempt(() -> someOperationThatMightFailOrReturnA())
.map(a -> someOtherOperationThatMightFailOReturnB(a))
.map(b -> someThirdOperationThatMightFailOrReturnC(b));
```

`EitherCollectors`
----------------

If you're working with *collections* of Eithers (for example, you're performing a series of validations, all of which can
*either* succeed *or* return a validation error message), you'll probably be interested in `EitherCollectors`, with its
`.toLeftBiased()` and `.toRightBiased()` methods for use with Java Streams:

```
// Let's say you have this variable already defined from your validations:
// List> validationResults

// And you want to fail the user's request if there's *any* error, and return *all* the errors if so. EitherCollectors can help!
Either, List> errorsOrSuccesses = validationResults.stream()
.collect(EitherCollectors.toLeftBiased());

// If there's even *one* left-hand ValidationError in our list, then we'll get a Left containing *all* the ValiidationErrors.
// If not, we'll get a Right containing any ValidationSuccess results.

// So we can do this:
return errorsOrSuccesses.fold(
(List errors) -> new UserFacingErrorsResponse(errors),
(List new SuccessResponse(successes)
);
```

So what else can it do?
-----------------------

Wanna see more? Check out the unit tests for a run-down of how Eithers behave. If those tests aren't descriptive enough,
or you think they should behave differently, open a Github issue! I built this because it didn't look like anyone else
had built it for Java yet, and I may have lost something in the translation. I'm totally open for feedback.

Cool! How do I get it for my project?
-------------------------------------

Simple! It's in Maven Central, so just add this to your pomfile (or the equivalent for gradle/sbt/lein/whatever):

```

com.spencerwi
Either.java
2.9.0