scala.util

Either

sealed abstract class Either[+A, +B] extends AnyRef

Represents a value of one of two possible types (a disjoint union.) Instances of Either are either an instance of scala.util.Left or scala.util.Right.

A common use of Either is as an alternative to scala.Option for dealing with possible missing values. In this usage, scala.None is replaced with a scala.util.Left which can contain useful information. scala.util.Right takes the place of scala.Some. Convention dictates that Left is used for failure and Right is used for success.

For example, you could use Either[String, Int] to detect whether a received input is a String or an Int.

val in = Console.readLine("Type Either a string or an Int: ")
val result: Either[String,Int] = try {
    Right(in.toInt)
  } catch {
    case e: Exception =>
      Left(in)
}

println( result match {
  case Right(x) => "You passed me the Int: " + x + ", which I will increment. " + x + " + 1 = " + (x+1)
  case Left(x) => "You passed me the String: " + x
})

A projection can be used to selectively operate on a value of type Either, depending on whether it is of type Left or Right. For example, to transform an Either using a function, in the case where it's a Left, one can first apply the left projection and invoke map on that projected Either. If a right projection is applied to that Left, the original Left is returned, unmodified.

val l: Either[String, Int] = Left("flower")
val r: Either[String, Int] = Right(12)
l.left.map(_.size): Either[Int, Int] // Left(6)
r.left.map(_.size): Either[Int, Int] // Right(12)
l.right.map(_.toDouble): Either[String, Double] // Left("flower")
r.right.map(_.toDouble): Either[String, Double] // Right(12.0)

Like with other types which define a map method, the same can be achieved using a for-comprehension:

for (s <- l.left) yield s.size // Left(6)

To support multiple projections as generators in for-comprehensions, the Either type also defines a flatMap method.

Source
Either.scala
Version

1.0, 11/10/2008

Since

2.7

Linear Supertypes
AnyRef, Any
Known Subclasses
Left, Right
Type Hierarchy Learn more about scaladoc diagrams
Ordering
  1. Alphabetic
  2. By inheritance
Inherited
  1. Either
  2. AnyRef
  3. Any
Implicitly
  1. by MergeableEither
  2. by any2stringadd
  3. by StringFormat
  4. by Ensuring
  5. by ArrowAssoc
  1. Hide All
  2. Show all
Learn more about member selection
Visibility
  1. Public
  2. All

Instance Constructors

  1. new Either()

Abstract Value Members

  1. abstract def isLeft: Boolean

    Returns true if this is a Left, false otherwise.

    Returns true if this is a Left, false otherwise.

    Left("tulip").isLeft // true
Right("venus fly-trap").isLeft // false

  2. abstract def isRight: Boolean

    Returns true if this is a Right, false otherwise.

    Returns true if this is a Right, false otherwise.

    Left("tulip").isRight // false
Right("venus fly-trap").isRight // true

Concrete Value Members

  1. final def !=(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any

  2. final def ##(): Int

    Definition Classes
    AnyRef → Any

  3. def +(other: String): String

    Implicit information
    This member is added by an implicit conversion from Either[A, B] to any2stringadd[Either[A, B]] performed by method any2stringadd in scala.Predef.
    Definition Classes
    any2stringadd

  4. def ->[B](y: B): (Either[A, B], B)

    Implicit information
    This member is added by an implicit conversion from Either[A, B] to ArrowAssoc[Either[A, B]] performed by method ArrowAssoc in scala.Predef.
    Definition Classes
    ArrowAssoc
    Annotations
    @inline()

  5. final def ==(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any

  6. final def asInstanceOf[T0]: T0

    Definition Classes
    Any

  7. def clone(): AnyRef

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  8. def ensuring(cond: (Either[A, B]) ⇒ Boolean, msg: ⇒ Any): Either[A, B]

    Implicit information
    This member is added by an implicit conversion from Either[A, B] to Ensuring[Either[A, B]] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring

  9. def ensuring(cond: (Either[A, B]) ⇒ Boolean): Either[A, B]

    Implicit information
    This member is added by an implicit conversion from Either[A, B] to Ensuring[Either[A, B]] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring

  10. def ensuring(cond: Boolean, msg: ⇒ Any): Either[A, B]

    Implicit information
    This member is added by an implicit conversion from Either[A, B] to Ensuring[Either[A, B]] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring

  11. def ensuring(cond: Boolean): Either[A, B]

    Implicit information
    This member is added by an implicit conversion from Either[A, B] to Ensuring[Either[A, B]] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring

  12. final def eq(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  13. def equals(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any

  14. def finalize(): Unit

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )

  15. def fold[X](fa: (A) ⇒ X, fb: (B) ⇒ X): X

    Applies fa if this is a Left or fb if this is a Right.

    Applies fa if this is a Left or fb if this is a Right.

    fa

    the function to apply if this is a Left

    fb

    the function to apply if this is a Right

    returns

    the results of applying the function

    Example: 

    1. val result: Either[Exception, Value] = possiblyFailingOperation()
log(result.fold(
  ex => "Operation failed with " + ex,
  v => "Operation produced value: " + v
))

  16. def formatted(fmtstr: String): String

    Returns string formatted according to given format string.

    Returns string formatted according to given format string. Format strings are as for String.format (@see java.lang.String.format).

    Implicit information
    This member is added by an implicit conversion from Either[A, B] to StringFormat[Either[A, B]] performed by method StringFormat in scala.Predef.
    Definition Classes
    StringFormat
    Annotations
    @inline()

  17. final def getClass(): Class[_]

    Definition Classes
    AnyRef → Any

  18. def hashCode(): Int

    Definition Classes
    AnyRef → Any

  19. final def isInstanceOf[T0]: Boolean

    Definition Classes
    Any

  20. def joinLeft[A1 >: A, B1 >: B, C](implicit ev: <:<[A1, Either[C, B1]]): Either[C, B1]

    Joins an Either through Left.

    Joins an Either through Left.

    This method requires that the left side of this Either is itself an Either type. That is, this must be some type like: 

    Either[Either[C, B], B]

    (which respects the type parameter bounds, shown below.)

    If this instance is a Left[Either[C, B]] then the contained Either[C, B] will be returned, otherwise this value will be returned unmodified.

    Left[Either[Int, String], String](Right("flower")).joinLeft // Result: Right("flower")
Left[Either[Int, String], String](Left(12)).joinLeft // Result: Left(12)
Right[Either[Int, String], String]("daisy").joinLeft // Result: Right("daisy")

    This method, and joinRight, are analogous to Option#flatten

  21. def joinRight[A1 >: A, B1 >: B, C](implicit ev: <:<[B1, Either[A1, C]]): Either[A1, C]

    Joins an Either through Right.

    Joins an Either through Right.

    This method requires that the right side of this Either is itself an Either type. That is, this must be some type like: 

    Either[A, Either[A, C]]

    (which respects the type parameter bounds, shown below.)

    If this instance is a Right[Either[A, C]] then the contained Either[A, C] will be returned, otherwise this value will be returned unmodified.

    Example: 

    1. Right[String, Either[String, Int]](Right(12)).joinRight // Result: Right(12)
Right[String, Either[String, Int]](Left("flower")).joinRight // Result: Left("flower")
Left[String, Either[String, Int]]("flower").joinRight // Result: Left("flower")

      This method, and joinLeft, are analogous to Option#flatten

  22. def left: LeftProjection[A, B]

    Projects this Either as a Left.

  23. def merge: B

    Implicit information
    This member is added by an implicit conversion from Either[A, B] to MergeableEither[B] performed by method MergeableEither in scala.util.Either.
    Definition Classes
    MergeableEither

  24. final def ne(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  25. final def notify(): Unit

    Definition Classes
    AnyRef

  26. final def notifyAll(): Unit

    Definition Classes
    AnyRef

  27. def right: RightProjection[A, B]

    Projects this Either as a Right.

  28. def swap: Product with Serializable with Either[B, A]

    If this is a Left, then return the left value in Right or vice versa.

    If this is a Left, then return the left value in Right or vice versa.

    Example: 

    1. val l: Either[String, Int] = Left("left")
val r: Either[Int, String] = l.swap // Result: Right("left")

  29. final def synchronized[T0](arg0: ⇒ T0): T0

    Definition Classes
    AnyRef

  30. def toString(): String

    Definition Classes
    AnyRef → Any

  31. final def wait(): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  32. final def wait(arg0: Long, arg1: Int): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  33. final def wait(arg0: Long): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

  34. def →[B](y: B): (Either[A, B], B)

    Implicit information
    This member is added by an implicit conversion from Either[A, B] to ArrowAssoc[Either[A, B]] performed by method ArrowAssoc in scala.Predef.
    Definition Classes
    ArrowAssoc

Inherited from AnyRef

Inherited from Any

Inherited by implicit conversion MergeableEither from Either[A, B] to MergeableEither[B]

Inherited by implicit conversion any2stringadd from Either[A, B] to any2stringadd[Either[A, B]]

Inherited by implicit conversion StringFormat from Either[A, B] to StringFormat[Either[A, B]]

Inherited by implicit conversion Ensuring from Either[A, B] to Ensuring[Either[A, B]]

Inherited by implicit conversion ArrowAssoc from Either[A, B] to ArrowAssoc[Either[A, B]]

Ungrouped