cats.InjectK[F, G]
cats.InjectK[F, G]
Construct a lazy Eval[A] instance.
Construct a lazy Eval[A] instance.
This type can be used for "lazy" values. In some sense it is equivalent to using a Function0 value.
This type will evaluate the computation every time the value is required. It should be avoided except when laziness is required and caching must be avoided. Generally, prefer Later.
Applicative functor.
Applicative functor.
Allows application of a function in an Applicative context to a value in an Applicative context
See: The Essence of the Iterator Pattern Also: Applicative programming with effects
Must obey the laws defined in cats.laws.ApplicativeLaws.
An applicative that also allows you to raise and or handle an error value.
An applicative that also allows you to raise and or handle an error value.
This type class allows one to abstract over error-handling applicatives.
Weaker version of Applicative[F]; has apply but not pure.
Weaker version of Applicative[F]; has apply but not pure.
Must obey the laws defined in cats.laws.ApplyLaws.
A type class abstracting over types that give rise to two independent cats.Foldables.
A type class of types which give rise to two independent, covariant functors.
A type class abstracting over types that give rise to two independent cats.Traverses.
CoflatMap
is the dual of FlatMap
.
CoflatMap
is the dual of FlatMap
.
Must obey the laws in cats.laws.CoflatMapLaws
Commutative Applicative.
Commutative Applicative.
Further than an Applicative, which just allows composition of independent effectful functions, in a Commutative Applicative those functions can be composed in any order, which guarantees that their effects do not interfere.
Must obey the laws defined in cats.laws.CommutativeApplicativeLaws.
Commutative Apply.
Commutative Apply.
Further than an Apply, which just allows composition of independent effectful functions, in a Commutative Apply those functions can be composed in any order, which guarantees that their effects do not interfere.
Must obey the laws defined in cats.laws.CommutativeApplyLaws.
Commutative FlatMap.
Commutative FlatMap.
Further than a FlatMap, which just allows composition of dependent effectful functions, in a Commutative FlatMap those functions can be composed in any order, which guarantees that their effects do not interfere.
Must obey the laws defined in cats.laws.CommutativeFlatMapLaws.
Commutative Monad.
Commutative Monad.
Further than a Monad, which just allows composition of dependent effectful functions, in a Commutative Monad those functions can be composed in any order, which guarantees that their effects do not interfere.
Must obey the laws defined in cats.laws.CommutativeMonadLaws.
Comonad
Comonad
Comonad is the dual of Monad. Whereas Monads allow for the composition of effectful functions, Comonads allow for composition of functions that extract the value from their context.
Must obey the laws defined in cats.laws.ComonadLaws.
Must obey the laws defined in cats.laws.ContravariantLaws.
ContravariantMonoidal functors are functors that supply
a unit along the diagonal map for the contramap2
operation.
ContravariantMonoidal functors are functors that supply
a unit along the diagonal map for the contramap2
operation.
Must obey the laws defined in cats.laws.ContravariantMonoidalLaws.
Based on ekmett's contravariant library: https://hackage.haskell.org/package/contravariant-1.4/docs/Data-Functor-Contravariant-Divisible.html
ContravariantSemigroupal is nothing more than something both contravariant and Semigroupal.
ContravariantSemigroupal is nothing more than something both contravariant and Semigroupal. It comes up enough to be useful, and composes well
Defer is a type class that shows the ability to defer creation inside of the type constructor F[_].
Defer is a type class that shows the ability to defer creation inside of the type constructor F[_].
This comes up with F[_] types that are implemented with a trampoline or are based on function application.
The law is that defer(fa) is equivalent to fa, but not evaluated immediately, so
scala> import cats._ scala> import cats.implicits._ scala> var evaluated = false scala> val dfa = Defer[Eval].defer { | evaluated = true | Eval.now(21) | } scala> evaluated res0: Boolean = false scala> Eq[Eval[Int]].eqv(dfa, Eval.now(21)) res1: Boolean = true
Eval is a monad which controls evaluation.
Eval is a monad which controls evaluation.
This type wraps a value (or a computation that produces a value)
and can produce it on command via the .value
method.
There are three basic evaluation strategies:
The Later and Always are both lazy strategies while Now is eager. Later and Always are distinguished from each other only by memoization: once evaluated Later will save the value to be returned immediately if it is needed again. Always will run its computation every time.
Eval supports stack-safe lazy computation via the .map and .flatMap methods, which use an internal trampoline to avoid stack overflows. Computation done within .map and .flatMap is always done lazily, even when applied to a Now instance.
It is not generally good style to pattern-match on Eval instances. Rather, use .map and .flatMap to chain computation, and use .value to get the result when needed. It is also not good style to create Eval instances whose computation involves calling .value on another Eval instance -- this can defeat the trampolining and lead to stack overflows.
FlatMap type class gives us flatMap, which allows us to have a value in a context (F[A]) and then feed that into a function that takes a normal value and returns a value in a context (A => F[B]).
FlatMap type class gives us flatMap, which allows us to have a value in a context (F[A]) and then feed that into a function that takes a normal value and returns a value in a context (A => F[B]).
One motivation for separating this out from Monad is that there are situations where we can implement flatMap but not pure. For example, we can implement map or flatMap that transforms the values of Map[K, ?], but we can't implement pure (because we wouldn't know what key to use when instantiating the new Map).
See https://github.com/typelevel/cats/issues/3 for some discussion. Must obey the laws defined in cats.laws.FlatMapLaws.
Data structures that can be folded to a summary value.
Data structures that can be folded to a summary value.
In the case of a collection (such as List
or Vector
), these
methods will fold together (combine) the values contained in the
collection to produce a single result. Most collection types have
foldLeft
methods, which will usually be used by the associated
Foldable[_]
instance.
Instances of Foldable should be ordered collections to allow for consistent folding.
Use the UnorderedFoldable
type class if you want to fold over unordered collections.
Foldable[F] is implemented in terms of two basic methods:
foldLeft(fa, b)(f)
eagerly folds fa
from left-to-right.foldRight(fa, b)(f)
lazily folds fa
from right-to-left.Beyond these it provides many other useful methods related to folding over F[A] values.
See: A tutorial on the universality and expressiveness of fold
Functor.
Functor.
The name is short for "covariant functor".
Must obey the laws defined in cats.laws.FunctorLaws.
FunctorFilter[F]
allows you to map
and filter out elements simultaneously.
Identity, encoded as type Id[A] = A
, a convenient alias to make
identity instances well-kinded.
Identity, encoded as type Id[A] = A
, a convenient alias to make
identity instances well-kinded.
The identity monad can be seen as the ambient monad that encodes
the effect of having no effect. It is ambient in the sense that
plain pure values are values of Id
.
For instance, the cats.Functor instance for cats.Id
allows us to apply a function A => B
to an Id[A]
and get an
Id[B]
. However, an Id[A]
is the same as A
, so all we're doing
is applying a pure function of type A => B
to a pure value of
type A
to get a pure value of type B
. That is, the instance
encodes pure unary function application.
Inject is a type class providing an injection from type A
into
type B
.
Inject is a type class providing an injection from type A
into
type B
. An injection is a function inj
which does not destroy
any information: for every b: B
there is at most one a: A
such
that inj(a) = b
.
Because of this all injections admit partial inverses prj
which
pair a value b: B
back with a single value a: A
.
1.0
Prior to cats 1.0, Inject handled injection for type constructors. For injection of type constructors, use InjectK.
InjectK for injection for cats.data.EitherK
InjectK is a type class providing an injection from type
constructor F
into type constructor G
.
InjectK is a type class providing an injection from type
constructor F
into type constructor G
. An injection is a
functor transformation inj
which does not destroy any
information: for every ga: G[A]
there is at most one fa: F[A]
such that inj(fa) = ga
.
Because of this all injections admit partial inverses prj
which
pair a value ga: G[A]
back with a single value fa: F[A]
.
The behavior of the default instances for the InjectK type class are described thoroughly in "Data types a la carte" (Swierstra 2008).
Prior to cats 1.0, InjectK was known as Inject.
Inject for injection for Either
http://www.staff.science.uu.nl/~swier004/publications/2008-jfp.pdf
Must obey the laws defined in cats.laws.InvariantLaws.
Invariant version of a Monoidal.
Invariant version of a Monoidal.
Must obey the laws defined in cats.laws.InvariantMonoidalLaws.
InvariantSemigroupal is nothing more than something both invariant and Semigroupal.
InvariantSemigroupal is nothing more than something both invariant and Semigroupal. It comes up enough to be useful, and composes well
Construct a lazy Eval[A] instance.
Construct a lazy Eval[A] instance.
This type should be used for most "lazy" values. In some sense it is equivalent to using a lazy val.
When caching is not required or desired (e.g. if the value produced may be large) prefer Always. When there is no computation necessary, prefer Now.
Once Later has been evaluated, the closure (and any values captured by the closure) will not be retained, and will be available for garbage collection.
Monad.
Monad.
Allows composition of dependent effectful functions.
See: Monads for functional programming
Must obey the laws defined in cats.laws.MonadLaws.
A monad that also allows you to raise and or handle an error value.
A monad that also allows you to raise and or handle an error value.
This type class allows one to abstract over error-handling monads.
MonoidK is a universal monoid which operates on kinds.
MonoidK is a universal monoid which operates on kinds.
This type class is useful when its type parameter F[_] has a structure that can be combined for any particular type, and which also has an "empty" representation. Thus, MonoidK is like a Monoid for kinds (i.e. parametrized types).
A MonoidK[F] can produce a Monoid[F[A]] for any type A.
Here's how to distinguish Monoid and MonoidK:
Some types that form a FlatMap, are also capable of forming an Apply that supports parallel composition.
Some types that form a FlatMap, are also capable of forming an Apply that supports parallel composition. The NonEmptyParallel type class allows us to represent this relationship.
This class defines a Reducible[F]
in terms of a Foldable[G]
together with a split
method, F[A]
=> (A, G[A])
.
This class defines a Reducible[F]
in terms of a Foldable[G]
together with a split
method, F[A]
=> (A, G[A])
.
This class can be used on any type where the first value (A
) and
the "rest" of the values (G[A]
) can be easily found.
NonEmptyTraverse, also known as Traversable1.
NonEmptyTraverse, also known as Traversable1.
NonEmptyTraverse
is like a non-empty Traverse
. In addition to the traverse and sequence
methods it provides nonEmptyTraverse and nonEmptySequence methods which require an Apply
instance instead of Applicative
.
An instance of NotNull[A]
indicates that A
does not have a static type
of Null
.
An instance of NotNull[A]
indicates that A
does not have a static type
of Null
.
This can be useful in preventing Null
from being inferred when a type
parameter is omitted.
This trait is used along with ambiguous implicits to achieve the goal of
preventing inference of Null
. This ambiguous implicit trick has been used
in the Scala community for some time. Here
is an early example of such a trick being used in a similar way to prevent a
Nothing
type.
Construct an eager Eval[A] instance.
Construct an eager Eval[A] instance.
In some sense it is equivalent to using a val.
This type should be used when an A value is already in hand, or when the computation to produce an A value is pure and very fast.
Some types that form a Monad, are also capable of forming an Applicative that supports parallel composition.
Some types that form a Monad, are also capable of forming an Applicative that supports parallel composition. The Parallel type class allows us to represent this relationship.
Data structures that can be reduced to a summary value.
Data structures that can be reduced to a summary value.
Reducible
is like a non-empty Foldable
. In addition to the fold
methods it provides reduce methods which do not require an initial
value.
In addition to the methods needed by Foldable
, Reducible
is
implemented in terms of two methods:
reduceLeftTo(fa)(f)(g)
eagerly reduces with an additional mapping functionreduceRightTo(fa)(f)(g)
lazily reduces with an additional mapping function
Representable.
Representable.
Is a witness to the isomorphism forall A. F[A] <-> Representation => A
Must obey the laws defined in cats.laws.RepresentableLaws i.e. tabulate andThen index = identity index andThen tabulate = identity
Inspired by the Haskell representable package http://hackage.haskell.org/package/representable-functors-3.2.0.2/docs/Data-Functor-Representable.html
SemigroupK is a universal semigroup which operates on kinds.
SemigroupK is a universal semigroup which operates on kinds.
This type class is useful when its type parameter F[_] has a structure that can be combined for any particular type. Thus, SemigroupK is like a Semigroup for kinds (i.e. parametrized types).
A SemigroupK[F] can produce a Semigroup[F[A]] for any type A.
Here's how to distinguish Semigroup and SemigroupK:
Semigroupal captures the idea of composing independent effectful values.
Semigroupal captures the idea of composing independent effectful values.
It is of particular interest when taken together with Functor - where Functor
captures the idea of applying a unary pure function to an effectful value,
calling product
with map
allows one to apply a function of arbitrary arity to multiple
independent effectful values.
That same idea is also manifested in the form of Apply, and indeed Apply extends both Semigroupal and Functor to illustrate this.
A type class to provide textual representation.
A type class to provide textual representation. It is meant to be a better "toString". Whereas toString exists for any Object, regardless of whether or not the creator of the class explicitly made a toString method, a Show instance will only exist if someone explicitly provided one.
A mix-in for inheriting tailRecM on monads which define a stack-safe flatMap.
A mix-in for inheriting tailRecM on monads which define a stack-safe flatMap. This is not an appropriate trait to use unless you are 100% certain your monad is stack-safe by definition! If your monad is not stack-safe, then the tailRecM implementation you will inherit will not be sound, and will result in unexpected stack overflows. This trait is only provided because a large number of monads do define a stack-safe flatMap, and so this particular implementation was being repeated over and over again.
Traverse, also known as Traversable.
Traverse, also known as Traversable.
Traversal over a structure with an effect.
Traversing with the cats.Id effect is equivalent to cats.Functor#map. Traversing with the cats.data.Const effect where the first type parameter has a cats.Monoid instance is equivalent to cats.Foldable#fold.
TraverseFilter
, also known as Witherable
, represents list-like structures
that can essentially have a traverse
and a filter
applied as a single
combined operation (traverseFilter
).
TraverseFilter
, also known as Witherable
, represents list-like structures
that can essentially have a traverse
and a filter
applied as a single
combined operation (traverseFilter
).
Based on Haskell's Data.Witherable
UnorderedFoldable
is like a Foldable
for unordered containers.
UnorderedTraverse
is like a Traverse
for unordered containers.
(Since version 1.0.0-RC1) renamed to Semigroupal
Hand rolling the type class boilerplate due to scala/bug#6260 and scala/bug#10458
Witness for: Id[A] <-> Unit => A
Symbolic aliases for various types are defined here.