Cats Documentation

The Reducible type class extends Foldable to provide reduction methods that do not require an initial value (unlike fold). This makes it ideal for abstracting over non-empty collections like NonEmptyList or NonEmptyVector.

Key characteristics:

• Unlike Foldable which requires a Monoid (for fold), Reducible only requires a Semigroup (for reduce).
• It provides guarantees that operations won't throw exceptions on empty collections when used with non-empty types.
• It includes eager reduction (reduceLeft) and lazy reduction (reduceRight) using Eval.

import cats._
import cats.data._
import cats.syntax.all._

// Example usage with NonEmptyList
Reducible[NonEmptyList].reduce(NonEmptyList.of("a", "b", "c"))

The Validated[+E, +A] data type is used for error accumulation. It is similar to Either, but unlike Either (which is a Monad and follows a fail-fast approach), Validated is an Applicative Functor. This allows it to collect multiple errors instead of stopping at the first one encountered.

It has two projections:

• Valid[+A](a: A): Represents a successful computation.
• Invalid[+E](e: E): Represents a failed computation containing error(s).

Note: Because it is not a Monad, you cannot use for-comprehensions (which rely on flatMap) to compose Validated instances. Instead, you must use Applicative syntax like .mapN.

sealed abstract class Validated[+E, +A] extends Product with Serializable

final case class Valid[+A](a: A) extends Validated[Nothing, A]
final case class Invalid[+E](e: E) extends Validated[E, Nothing]

The Foldable[F] type class is implemented for data structures that can be folded into a summary value. It is primarily built upon two core methods:

• foldLeft(fa, b)(f): Performs an eager, left-associative fold over fa.
• foldRight(fa, b)(f): Performs a lazy, right-associative fold over fa.

For a collection like List(1, 2, 3) with a starting value 0 and addition +:

• foldLeft executes as ((0 + 1) + 2) + 3.
• foldRight executes as 0 + (1 + (2 + 3)).

If you are defining a new data structure, providing implementations for foldLeft and foldRight allows you to automatically gain access to a wide range of other Foldable operations.

A NonEmptyList[A] is a specialized data type that guarantees at least one element exists by construction. This makes it a safer alternative to List[A] for operations that are undefined for empty collections (like head).

Key benefits:

• Totality: Operations like head and tail are always well-defined because an empty NonEmptyList cannot be created.
• Error Reporting: It is ideal for use with Validated or Ior to ensure that an Invalid state always contains at least one error.
• Domain Logic: It allows you to move validation to the boundaries of your program, enabling functions to accept NonEmptyList instead of List and Option, thus avoiding unnecessary null/empty checks in your core logic.

The Ior[A, B] data type represents an inclusive-or relationship. Unlike Either, which is exclusive (either A or B), an Ior can contain an A, a B, or both an A and a B.

Ior is right-biased, meaning map and flatMap operate on the right side (B). When using Monad or Applicative instances, Ior accumulates values on the left side (requiring a Semigroup for A), similar to how Validated works. This allows you to accumulate non-fatal warnings on the left while continuing with the computation on the right.

import cats.data._

val right = Ior.right[String, Int](3)
val left = Ior.left[String, Int]("Error")
val both = Ior.both("Warning", 3)

The Writer[L, A] datatype represents a computation that produces a tuple containing a value of type A (the output) and a value of type L (the logging side). When composing operations like flatMap, the logs are automatically combined using an implicit Semigroup[L].

To access the contents of a Writer, use the .run method.

import cats.data.Writer
import cats.instances._

val mapExample = Writer("map Example", 1).map(_ + 1)

mapExample.run

The Const[A, B] data type is a container that stores a value of type A but carries a phantom type parameter B. The type parameter B is not used in the data structure itself, but it allows you to carry type information through functional transformations. It behaves similarly to the const function, which returns the first argument and ignores the second.

case class Const[A, B](getConst: A)