relude

Safe, performant, user-friendly and lightweight Haskell Standard Library

https://github.com/kowainik/relude

Version on this page:1.2.1.0@rev:1
LTS Haskell 22.43:1.2.2.0
Stackage Nightly 2024-11-30:1.2.2.0
Latest on Hackage:1.2.2.0

See all snapshots relude appears in

relude

Logo

GitHub CI Hackage Stackage LTS Stackage Nightly License: MIT

relude is a safe, performant, user-friendly and lightweight Haskell standard library.

The default Prelude is not perfect and doesn’t always satisfy one’s needs. At this stage you may want to try an alternative prelude library. In this README we are going to give you convincing reasons to consider using relude as such alternative in your next project.

relude has some strong goals and principles that it sticks to. That principles defines the library decisions and might tell you more about the priorities of the library. So below you can find the key design principles behind relude:

  1. Productivity. You can be more productive with a “non-standard” standard library, and relude helps you with writing safer and more efficient code faster.

  2. Total programming. Usage of partial functions can lead to unexpected bugs and runtime exceptions in pure code. The types of partial functions lie about their behaviour. And even if it is not always possible to rely only on total functions, relude strives to encourage best-practices and reduce the chances of introducing a bug.

Partial Total
head :: [a] -> a head :: NonEmpty a -> a
tail :: [a] -> [a] tail :: NonEmpty a -> [a]
read :: Read a => String -> a readMaybe :: Read a => String -> Maybe a
fromJust :: Maybe a -> a fromMaybe :: a -> Maybe a -> a
  1. Type-safety. We use the “make invalid states unrepresentable” motto as one of our guiding principles. If it is possible, we express this concept through the types.

    Example: Here the function’s name type and actions are aligned with each other

    whenNotNull :: Applicative f => [a] -> (NonEmpty a -> f ()) -> f ()
    

    While in here, the type could represent an unreachable state:

    whenNotNull :: Applicative f => [a] -> ([a] -> f ()) -> f ()
    
  2. Performance. We prefer Text over String, use space-leaks-free functions (e.g. our custom performant sum and product), introduce {-# INLINE #-} and {-# SPECIALIZE #-} pragmas where appropriate, and make efficient container types (e.g. Map, HashMap, Set) more accessible.

  3. Minimalism (low number of dependencies). We do not force users of relude to stick to any specific lens or text formatting or logging library. Where possible, relude depends only on boot libraries. The Dependency graph of relude can give you a clearer picture.

  4. Convenience. Despite minimalism, we want to bring commonly used types and functions into scope, and make available functions easier to use. Some examples of conveniences:

    • No need to add containers, unordered-containers, text and bytestring to dependencies in your .cabal file to use the main API of these libraries
    • No need to import types like NonEmpty, Text, Set, Reader[T], MVar, STM
    • Functions like liftIO, fromMaybe, sortWith are available by default as well
    • IO actions are lifted to MonadIO
  5. Excellent documentation.

  6. User-friendliness. Anyone should be able to quickly migrate to relude. Only some basic familiarity with the common libraries like text and containers should be enough (but not necessary).

  7. Exploration. We have space to experiment with new ideas and proposals without introducing breaking changes. relude uses the approach with Extra.* modules which are not exported by default. The chosen approach makes it quite easy for us to provide new functionality without breaking anything and let the users decide to use it or not.

In addition to our key design principles, the following list of anti-goals describes what relude is trying to avoid:

  1. Rewrite base from the ground up. With relude you don’t need to unlearn what you already knew, you can leverage existing knowledge to achieve higher productivity.
  2. Invent custom abstractions. Learning abstractions is hard, so we do our best not to introduce new overwhelming concepts.
  3. Rename common definitions. If something is called foo in base, it’s also called foo in relude. So, relude doesn’t rename any existing abstractions, but it may introduce a few new ones, if their benefits outweigh learning curve.

This README contains an introduction to relude and a tutorial on how to use it.

For a general introduction to alternative preludes, check the excellent blog post by Type Classes that highlights relude.

For guiding development principles behind relude and comparison with base, check out the following talk:

  • Introduction to relude — an alternative Haskell prelude

Structure of this tutorial

This tutorial has several parts:

  1. When to use an alternative prelude?
  2. Get started
  3. Difference from Prelude
  4. Reexports
  5. What’s new?
  6. Migration guide
  7. Comparison with other alternative preludes
  8. For developers

This is neither a tutorial on Haskell Standard Library nor a tutorial on each function contained in relude. For latter see the detailed documentation of every data type, type class and function together with examples and usages in the Haddock documentation for relude.

When to use an alternative prelude?

[Back to the Table of Contents] ↑

The module with the name Prelude is a module imported by default in every Haskell source file of your project. If you want to use some data types or functions which are not exposed by Prelude, you need to import them, adding necessary libraries to your project dependencies. Unlike ordinary libraries, alternative preludes provide a different set of available by default functions and data types by replacing the Prelude module.

Replacing default Prelude from base has the following disadvantages:

  1. Increased entry threshold: you need to learn a different standard library.
    • relude tries to lower this threshold as much as possible: it comes with the excellent documentation, no custom abstractions, and behavior is changed only for a small subset of functions.
  2. Extra dependencies: adding more libraries to dependencies increases build times and maintenance burden.
    • relude depends only on the boot libraries (almost) which results in small build time, follows PVP and cares about backwards compatibility.

However, using an alternative prelude, specifically relude, has the following advantages:

  1. Increased code safety: no partial functions, no space-leak functions.
  2. Increased productivity: no need to import common functions and data types, more common idioms are provided.
  3. Increased performance: some functions in relude are faster than in the default Prelude.

Taking into consideration all the above points, we put together our recommendations when to use relude:

  1. When you develop an application (e.g. CLI tool, web-app). In that case, greater productivity is more important than a low number of dependencies.
  2. When writing a big framework. Some of them can be bigger than applications.

And when you may want to stay with the default standard:

  1. When you write a small library that is supposed to be used by other people in their projects.

Get started

[Back to the Table of Contents] ↑

If you want to start using relude in your project, you can set the library up for you by one of the following ways.

Mixins

[Back to the Table of Contents] ↑

This is the recommended way to use a custom prelude.

You can use the Cabal feature mixins to replace the default Prelude with Relude without the need to add extra dependencies or to import Relude manually in each module. For this you need to add the following lines into your .cabal file:

  mixins:   base hiding (Prelude)
          , relude (Relude as Prelude)
          , relude

NOTE: this requires Cabal version to be at least 2.2

The above syntax does the following:

  1. Makes all modules of base available except Prelude.
  2. Renames the Relude module in relude to Prelude.
  3. Additionally allows importing all other modules from relude (extra modules and reexports from other libraries).

See the following complete example of how your .cabal file may look like after the set up:

cabal-version:       2.2
name:                prelude-example
version:             0.0.0.0

library
  exposed-modules:     Example
  build-depends:       base >= 4.14 && < 4.17
                     , relude ^>= 1.1.0.0

  mixins:              base hiding (Prelude)
                     , relude (Relude as Prelude)
                     , relude

  default-language:    Haskell2010

NOTE: if you use summoner to generate a Haskell project, the tool automatically creates the mixins field when you specify a custom prelude.

If you want to restrict allowed modules in relude to a specific list (e.g. use only Relude.Extra.Enum or Relude.Unsafe or Data.Text from text), you can alternatively list them explicitly under the first mixins entry field as well, like this:

  mixins: base hiding (Prelude)
        , relude (Relude as Prelude
                 , Relude.Extra.Enum
                 , Relude.Unsafe
                 , Data.Text
                 )

If you want to bring only all Extra.* modules into scope, you can add a single Relude.Extra module to mixins, and after that you can import all extra functions and data types from Relude.Extra. This is the easiest way to bring all functions and types from relude to your project (excluding Relude.Unsafe).

  mixins: base hiding (Prelude)
        , relude (Relude as Prelude
                 , Relude.Extra
                 )

NOTE: due to the existing stack issue, mixins technique doesn’t work with the stack repl at the moment. Please, consider this before using this method of turning relude on in the project.

If having stack repl crucial for your workflow, see the following options of how to use Relude in your project.

NoImplicitPrelude

[Back to the Table of Contents] ↑

For this option, you need to disable the default Prelude module first. To disable the built-in prelude on module basis, you can add the following pragma at the top of your file:

{-# LANGUAGE NoImplicitPrelude #-}

if you want to disable the default Prelude for every module by default, you can specify this directly in your project .cabal file:

default-extensions: NoImplicitPrelude

Then you need to add relude as a dependency of your project.

After doing all above, you can now use Relude in any module of your project by adding a single import:

import Relude

base-noprelude

[Back to the Table of Contents] ↑

:warning: This strategy is not reccommended. The package base-noprelude is currently not being maintained and its use is likely to cause issues with newer versions of ghc and libraries.

Alternatively, you can use the base-noprelude trick to enable alternative preludes. This approach can be helpful if you want to have your own Prelude module with some custom functions, not provided by relude. To use the trick, perform the following steps:

  1. Replace the base dependency with the corresponding version of base-noprelude in your .cabal file.

  2. Add the relude dependency to your .cabal file.

  3. Create the file called Prelude.hs in your source directory with the following content:

    module Prelude
        ( module Relude
        ) where
    
    import Relude
    
  4. Add this module to exposed-modules in your .cabal file:

    exposed-modules: Prelude
    
  5. Optionally modify your Prelude module to include more or fewer functions. Potentially, you can hide something from the Relude module. Or maybe you want to add something from Relude.Extra.* modules! Customize the module for your needs.

This is a very convenient way to add a custom prelude to your project because you don’t need to import module manually inside each file and enable the NoImplicitPrelude extension.

Difference from Prelude

[Back to the Table of Contents] ↑

Main differences from Prelude can be grouped into the following categories:

  • Changed behavior of common functions
    • head, tail, last, init work with NonEmpty a instead of [a].
    • lines, unlines, words, unwords work with Text instead of String.
    • show is polymorphic over the return type.
    • Functions sum and product are strict now, which makes them more efficient.
    • You can’t call elem and notElem functions over Set and HashSet. These functions are forbidden for these two types due to performance reasons.
    • error takes Text.
    • undefined triggers a compiler warning, because you probably don’t want to leave undefined in your code. Either use throwIO, Except, error or bug.
  • Not reexported
    • read
    • lookup for lists
    • log
  • Completely new functions are brought into scope
  • New reexports
    • See the Reexports section for a detailed overview.

Reexports

[Back to the Table of Contents] ↑

relude reexports some parts of the following libraries:

If you want to clean up your imports after switching to relude, you can use the relude-specific .hlint.yaml configuration for this task. With this config, HLint will produce warnings and hints on how to have more benefits from relude.

base

Multiple sorting functions are available for different use-cases:

  • sortBy :: (a -> a -> Ordering) -> [a] -> [a]: sorts a list using given custom comparator.
  • sortWith :: Ord b => (a -> b) -> [a] -> [a]: sorts a list based on some property of its elements.
  • sortOn :: Ord b => (a -> b) -> [a] -> [a]: similar to sortWith, but more time-efficient if function is calculated slowly (though less space-efficient). So you should write sortOn length (would sort elements by length) but sortWith fst (would sort list of pairs by first element).

readMaybe and readEither are similar to read but unlike it, they are total and return either Maybe or Either with a parse error.

(&) is the reverse application. The following three expressions are semantically equivalent:

  • g (f x)
  • g $ f $ x
  • x & f & g

Some generally useful modules from base package are exported, e.g. Control.Applicative, Data.Traversable, Data.Monoid, Data.List, and many more.

liftIO and MonadIO are exported by default. A lot of IO functions are generalized to MonadIO.

Bifunctor type class with useful instances is exported.

  • first and second functions apply a function to the first and second part of a Bifunctor (fst and snd for tuples, Left and Right for Either).
  • bimap takes two functions and applies them to the first and second parts respectively.

trace, traceM, traceShow, etc. are available by default. However, GHC will warn you if you accidentally leave them in code. Same goes for the undefined function.

We also have data Undefined = Undefined (which also comes with the warning).

relude reexports Exception type from the base package and introduces the bug function as an alternative to error. There is also a very convenient Exc pattern-synonym to handle exceptions of different types.

See Relude.Exception module for details on exceptions.

containers & unordered-containers

The following types from these two packages are exported:

  • Maps: strict versions of Map, HashMap, IntMap.
  • Sets: Set, HashSet, IntSet.
  • Sequences: Seq.

text & bytestring

relude exports Text and ByteString (as well as their lazy versions — LText and LByteString).

Also, some functions now work with Text instead of Stringwords, lines, etc.

In addition, relude provides specialised versions of the IO functions to work with Text and ByteStringreadFileText, writeFileBS, etc.

show is polymorphic and can produce strict or lazy Text or ByteString as well as String.

Also, toText|toLText|toString can convert Text|LText|String types to Text|LText|String. If you want to convert to and from ByteString use encodeUtf8|decodeUtf8 functions.

transformers & mtl

The following parts of these two libraries are exported:

  • Transformers: State[T], Reader[T], ExceptT, MaybeT.
  • Classes: MonadReader, MonadState.

Deepseq

All the main parts of the deepseq library are exported. For instance, if you want to force the deep evaluation of some value (in IO), you can write evaluateNF a. Additionally, the WHNF evaluation is possible with provided evaluateWHNF.

What’s new?

[Back to the Table of Contents] ↑

Finally, let’s move to part describing the new cool features we bring with relude.

Available by default

  • Safe analogue for the list functions:

    head :: NonEmpty a -> a    -- the first element of the list
    tail :: NonEmpty a -> [a]  -- the list without the first element
    last :: NonEmpty a -> a    -- the last element of the list
    init :: NonEmpty a -> [a]  -- the list without the last element
    

    You can also still work with lists for these functions. Using viaNonEmpty function you will get Maybe a from the list:

    -- viaNonEmpty head :: [a] -> Maybe a
    ghci> viaNonEmpty head [1,2,3]
    Just 1
    ghci> viaNonEmpty head []
    Nothing
    
  • uncons splits a list at the first element.

  • ordNub and sortNub are O(n log n) versions of nub (which is quadratic), also, hashNub and unstableNub are almost O(n) versions of nub, and intNub for fast Ints nub.

  • whenM, unlessM, ifM, guardM — monadic guard combinators, that work with any Monad, e.g. whenM (doesFileExist "foo").

  • General fold functions:

    foldMapA :: (Monoid b, Applicative m, Foldable f) => (a -> m b) -> f a -> m b
    foldMapM :: (Monoid b, Monad m, Foldable f) => (a -> m b) -> f a -> m b
    
  • when(Just|Nothing|Left|Right|NotEmpty)[M][_] functions that let you conditionally execute something.

    Before:

    case mbX of
        Nothing -> return ()
        Just x  -> f x
    

    After:

    whenJust mbX $ \x ->
        f x
    
  • for_ and forM_ for loops.

    for_ files $ \file -> do
        ...
    
  • andM, allM, anyM, orM are monadic versions of the corresponding functions from base.

  • Conversions between Either and Maybe, e.g. rightToMaybe and maybeToLeft with clear semantics.

  • using(Reader|State)[T] functions as aliases for flip run(Reader|State)[T].

  • One type class for creating singleton containers (even monomorphic ones like Text).

  • evaluateWHNF and evaluateNF functions as clearer and lifted aliases for evaluate and evaluate . force.

  • MonadFail instance for Either.

Extra bonuses

relude has a number of Extra modules that are not exposed by default (they are not a part of the Relude module). You need to import such modules separately.

These extra modules include the following functionality:

  • Convenient functions to work with (Bounded a, Enum a) types:

    1. universe :: (Bounded a, Enum a) => [a]: get all values of the type.

      ghci> universe @Bool
      [True,False]
      
    2. inverseMap :: (Bounded a, Enum a, Ord k) => (a -> k) -> k -> Maybe a: convert functions like show to parsers:

      readMyEnums :: Text -> Maybe MyEnum
      readMyEnums = inverseMap myShow
      
  • Nice helpers to deal with newtypes in a more pleasant way:

    ghci> newtype Foo = Foo Bool deriving Show
    ghci> under not (Foo True)
    Foo False
    
  • Functions to operate with CallStack:

    ghci> foo :: HasCallStack => String; foo = ownName
    ghci> foo
    "foo"
    
  • Foldable1 typeclass that contains generalized interface for folding non-empty structures like NonEmpty.

  • StaticMap and DynamicMap type classes as a general interface for Map-like data structures.

  • And much more!

Explore Extra modules: Relude.Extra

Migration guide

[Back to the Table of Contents] ↑

This section of the guide helps to migrate your project from base to the relude library.

In order to replace the default Prelude with relude you should start with instructions provided in the Get Started section.

Code changes

This section describes what you need to change to make your code compile with relude.

  1. Enable -XOverloadedStrings extension by default for your project.

  2. Since head, tail, last and init work for NonEmpty you should refactor your code in one of the described below ways:

    1. Change [a] to NonEmpty a where it makes sense.
    2. Use functions which return Maybe. There is the viaNonEmpty function for this. And you can use it like viaNonEmpty last l.
      • tail is drop 1. It’s almost never a good idea to use tail from Prelude.
    3. Add import qualified Relude.Unsafe as Unsafe and replace the function with its qualified usage: Unsafe.head.
  3. If you use fromJust or !! you should import them from import qualified Relude.Unsafe as Unsafe.

  4. If you use foldr or forM_ or similar for something like Maybe a or Either a b it is recommended to replace usages of such functions with the monomorhpic alternatives:

    • Maybe

      • (?:) :: Maybe a -> a -> a
      • fromMaybe :: a -> Maybe a -> a
      • maybeToList :: Maybe a -> [a]
      • maybeToMonoid :: Monoid m => Maybe m -> m
      • maybe :: b -> (a -> b) -> Maybe a -> b
      • whenJust :: Applicative f => Maybe a -> (a -> f ()) -> f ()
      • whenJustM :: Monad m => m (Maybe a) -> (a -> m ()) -> m ()
    • Either

      • fromLeft :: a -> Either a b -> a
      • fromRight :: b -> Either a b -> b
      • either :: (a -> c) -> (b -> c) -> Either a b -> c
      • whenRight_ :: Applicative f => Either l r -> (r -> f ()) -> f ()
      • whenRightM_ :: Monad m => m (Either l r) -> (r -> m ()) -> m ()
  5. Replace the String type with more efficient and suitable ones (e.g. Text):

    • Replace (++) with (<>) for String-like types.
    • Use toText/toLText/toString functions to convert to Text/LazyText/String types.
    • Use encodeUtf8/decodeUtf8 to convert to/from ByteString.
    • Use (putStr[Ln]|readFile|writeFile|appendFile)[Text|LText|BS|LBS] functions.
  6. Since show doesn’t come from Show anymore, you need to import the Text.Show module if you want to implement Show instance manually. This can be done in the following way:

import qualified Text.Show

data MyType = ...

instance Show MyType where
    show :: MyType -> String
    show = ...
  1. Run hlint using .hlint.yaml file from relude package to cleanup code and imports.

Running HLint on CI

Instead of storing a relude-specific .hlint.yaml file inside your repository, you can run HLint with this file automatically on any CI service such as Travis CI or Circle CI. For this you need to:

  1. Find the commit hash of the relude version you are using (can be found in releases).
  2. Run the command that downloads .hlint.yaml for that version.
  3. Run hlint using this file.

For the latest relude version, this can be achieved by executing the following two commands on your CI:

curl https://raw.githubusercontent.com/kowainik/relude/v1.1.0.0/.hlint.yaml -o .hlint-relude.yaml
curl -sSL https://raw.github.com/ndmitchell/neil/master/misc/travis.sh | sh -s -- hlint -h .hlint-relude.yaml .

See an example of this feature described in the following blog post about Travis CI settings:

Comparison with other alternative preludes

[Back to the Table of Contents] ↑

There are quite a few libraries that can be used as alternative preludes in Haskell, let’s compare Relude with some of them.

Relude vs Protolude

[Back to the Table of Contents] ↑

Protolude is one of the most popular alternative preludes. It’s also relatively small, but:

  1. relude has custom HLint rules specific to it: you can use them to remove redundant imports or find hints on how to use functions from relude. Moreover, the HLint rules are generated using Dhall and there is a blog post about this technique. This allows to maintain HLint rules with less effort, even though it is already not an easy task.
  2. One significant difference: head in protolude returns Maybe a while in relude it works with NonEmpty.
  3. relude uses type-level features to provide better error messages on the difference from Prelude, and also to forbid elem and notElem functions for Set and HashSet (because elem from Foldable runs in O(n) time and you can accidentally use elem from Foldable but with relude you can’t).
  4. Protolude supports older GHC versions (from GHC 7.6.1) while relude only supports from GHC 8.4. So if you aim ancient GHC versions, protolude might be a better choice. But because of that it contains a lot of CPP, code is scary in some places as a consequence and it is more difficult to add, remove or change things there.
  5. relude has much better documentation:
  6. relude has fewer dependencies and is slightly lighter because of that but still is very powerful and useful.
  7. relude is opt-in oriented and has a notion of Extra.* modules that are not exported by default from the Relude module. That means that we do not spoil the global namespace but still have a lot of useful features, like polymorphic functions to work with every newtype, Enum/Bounded-related useful utilities, functions to take a name of any type as Text and much more. It is a straightforward process to make them accessible package-wide with the base-noprelude trick!

For Developers

[Back to the Table of Contents] ↑

Generating .hlint.yaml

Note, that we are using custom hlint setting which are Relude specific. To keep it up to date don’t forget to reflect your changes in this file. We are using Dhall to maintain the configurations (lang version 22.0.0). To use it follow the steps below.

First time:

$ cabal v2-install dhall-yaml-1.2.10

To generate hlint file:

$ dhall-to-yaml-ng <<< './hlint/hlint.dhall' > .hlint.yaml

Check that you have generated valid .hlint.yaml file without parse errors:

$ hlint test/Spec.hs

See our blog post where we describe the details of the implementation for this solution:

Producing dependency graph

Install cabal-plan first:

$ cabal v2-install cabal-plan
$ cabal-plan --version
cabal-plan 0.6.2.0

Then draw the graph only for the library dependencies:

cabal-plan dot --root lib:relude | dot -Tpng -o relude-dependency-graph.png

Updating license headers

Install the headroom tool and run it from this repository:

cabal v2-install headroom-0.4.3.0
headroom run
rg "SPDX-License-Identifier : MPL-2.0" --files-with-matches src/ | xargs sed -i 's/SPDX-License-Identifier : MPL-2.0/SPDX-License-Identifier : MIT/g'

Changes

Changelog

relude uses PVP Versioning. The changelog is available on GitHub.

1.2.1.0 – Oct 4, 2023

  • #439: Support GHC-9.6.
  • Upgrade dependencies. Allow:
    • ghc-prim-0.10
    • text-2.1
    • bytestring-2.12
    • containers-0.7
    • deepseq-1.5
    • hedgehod-1.3
    • doctest-0.22
  • Upgrade tests to work with GHC-9.6.

1.2.0.0 – Mar 1, 2023

  • #420: Support GHC-9.4.
  • Reexport type (~) from Data.Type.Equality for GHC-9.4.
  • Add -Wredundant-strictness-flags and -Wforall-identifier warnings for GHC-9.4.
  • #430: Upgrade dependencies:
    • ghc-prim-0.9
    • mtl-2.3
    • hedgehog-1.2
    • doctest-0.21
  • Drop support of GHC-8.2.

1.1.0.0 — Jun 9, 2022

  • #388: Support GHC-9.2.

  • #363: Remove the Option type, reexported from Data.Semigroup (which was removed in base-4.16, GHC 9.2)

    Migration guide: Use Maybe instead of Option.

  • #372: Warn on usages of readFileText, readFileLText, readFile and readFile'.

    NOTE: This is a breaking change if you build with -Werror and use the above functions. Use readFileBS / readFileLBS instead to convert to Text / LText / String using decodeUtf8 and similar functions.

  • #394: Support hashable-1.4.

  • #408: Switch benchmarks from criterion to tasty-bench.

  • #404: Fix condidion for ordNubOn, intNub, intNubOn export for Relude.Nub module. Use min version of containers-0.6.0 instead of min version of GHC 8.4.

  • Minor documentation improvements and fixes.

1.0.0.1 — Mar 15, 2021

  • Minor documentation changes.

1.0.0.0 — Mar 12, 2021

  • #353: Reexport most common modules from the following libraries:

    • containers
    • unordered-containers
    • text
    • bytestring

    Now, when using relude, you don’t need to add these libraries to your .cabal file to enjoy their main API. Try removing them from your .cabal file after upgrading to this version of relude to see if you still need them.

    To utilise this feature, update the mixin part of your package configuration (if you’re using the mixins approach) to the following:

    mixins:   base hiding (Prelude)
            , relude (Relude as Prelude)
            , relude
    
  • #345: Support GHC-9.0.

  • Upgrade minor GHC versions to GHC-8.10.4 and GHC-8.8.4.

  • #268: Drop support of GHC-8.0.2.

  • #270: Standardise universe, universeNonEmpty and inverseMap functions that previously were introduced in the Relude.Extra.Enum module. Relude.Enum module created that is exported in the main Relude module by default.

    Migration guide: If you were using any of these functions you can now remove Relude.Extra.Enum from your imports and explicit mixins section as they are available for you with the Relude module.

  • Remove the Eq constraint on universeNonEmpty

  • #269: Remove the Relude.Extra.Validation module.

    Migration guide: If you use Relude.Extra.Validation in you project you need to:

    1. Add validation-selective into the build-depends section of your .cabal file.

    2. Change imports of Relude.Extra.Validation to Validation:

      -- Was:
      import Relude.Extra.Validation (Validation (..), ..)
      -- Became:
      import Validation (Validation (..), ..)
      
  • #346, #347: Reimplement ordNub through nubOrd from containers. Add ordNubOn, intNub and intNubOn functions.

  • #327: Add infinitely as more strictly typed forever.

  • #311: Add maybeAt function — the non-operator version of !!? with its arguments flipped.

  • #314: Add lifted versions of functions to work with Handle:

    • hFlush
    • hIsEOF
    • hSetBuffering
    • hGetBuffering
  • #305: Add lifted versions of functions to work with environment:

    • getArgs
    • lookupEnv
  • Add lifted version of the readFile' function.

  • Reexport the BufferMode type from base.

  • #309: Reexport span from Data.List.

  • #319: Implement partitionWith.

  • #307: Add foldr1 to Foldable1.

  • #316: Add average and average1 — efficient functions for finding average on foldable structures.

  • #306: Add maximumOn1 and minimumOn1 to Foldable1.

  • #301: Add traceShowWith to Relude.Debug.

  • #304, #317: Various documentation improvements.

  • Updates to relude-specific .hlint rules.

Thanks @googleson78, @sushi-shi, @rektrex, @aleator, @mjgpy3, @dalpd, @Bodigrim for helping with this release!

0.7.0.0 — May 14, 2020

  • #253: Support GHC-8.10. Upgrade GHC-8.8 to 8.8.3.

  • Significant documentation improvements:

    • Add high-level description to each reexported module.
    • Add String Conversion Table.
    • Add NonEmpty lists functions tables.
    • Add @since annotations.
    • Improve README.
    • Inline some external reexports into explicit lists of exports.
    • Rewrite top-level cabal description.
  • #234: Reexport scanl1, scanr1, scanl' from Data.List.

  • #256: Make cycle total function.

  • #233: Add etaReaderT to Relude.Monad.Trans to help with performance.

  • #294: Add atomicModifyIORef_ and atomicModifyIORef'_.

  • #293: Add memptyIfFalse and memptyIfTrue functions.

  • Reexport NonEmpty functions from Relude.List.NonEmpty instead of Relude.List.Reexport.

  • #239: Reexport more STM functions that work with TMVar from Relude.Lifted.Concurrent.

  • #227: Create Relude.Extra module

  • #228: Add universeNonEmpty function.

  • #249: Breaking change: Fix infix of the Relude.Extra.Lens (^.) operator. Change it to infixl 8.

  • Reexport partial read from Relude.Unsafe for consistency.

  • #244: Remove deprecated functions: prec, dupe and mapBoth.

    Migration rules:

    • prec: use prev instead
    • dupe: use dup instead
    • mapBoth: use bimapBoth instead
  • #246: Deprecate Relude.Extra.Validation in favour of validation-selective

    Migration rules: If you use Relude.Extra.Validation in you project you need to:

    1. Add validation-selective into the build-depends section of your .cabal file.

    2. Change imports of Relude.Extra.Validation to Validation:

      -- Was:
      import Relude.Extra.Validation (Validation (..), ..)
      -- Became:
      import Validation (Validation (..), ..)
      
  • #196: Deprecate mapToFst and mapToSnd. Introduce toFst and toSnd in Relude.Extra.Tuple as shorter aliases for mapToFst. Implement fmapToFst and fmapToSnd. Add more HLint rules for Relude.Extra.Tuple functions.

    Migration rules:

    • Replace mapToFst with toFst
    • Replace mapToSnd with toSnd
    • You can now use fmapToFst and fmapToSnd instead of [f]map (mapToFst f) and [f]map (mapToSnd f)
  • #286: Breaking change: readEither is not polymorphic over the first argument anymore. Now it takes String.

    Migration rules: Use one of the conversion function from the Relude.String.Conversion module to covert your old input value into String.

    For example, if you had

    readEither @Text @Int myText
    

    Now it should become:

    readEither @Int (toString myText)
    
  • #281: Move One property tests from doctest to hedgehog. Significant test time boost.

  • #264: Support Dhall-16.0.0 in HLint rules.

0.6.0.0 — Oct 30, 2019

  • #171: Add custom type errors to various functions and instances.

    • head, tail, last, init
    • words, unwords, lines, unlines
    • error
    • ToText, ToLText, ToString instances for bytestrings
    • Foldable1 instance for ordinary lists
    • Monad instance for Validation

    (by @vrom911, @chshersh)

  • #164: Reexport ShortByteString, toShort/fromShort functions. (by @vrom911)

  • #182: Support GHC-8.8.1. (by @chshersh)

  • #168, #197: Improve documentation significantly (more and better examples, better wording). (by @chshersh, @vrom911, @Cmdv)

  • #177: Improve usage of performance pragmas. (by @chshersh)

  • #167: Rename functions (and deprecate old versions):

    • prec to prev
    • dupe to dup

    (by @Cmdv, @chshersh)

  • #192: Reexport foldMap' from Data.Foldable. (by @tfausak)

  • #201: Implement !!? as a safe equivalent of !! that returns a Maybe. (by @kutyel)

  • #203: Implement the guarded combinator. (by @JonathanLorimer)

  • #214: Add mapMaybeM function. (by @vrom911)

  • #174: Implement bimapBoth in Relude.Extra.Tuple module, mark mapBoth as DEPRECATED. (by @astynax)

  • #221: Improve documentation for the Validation module significantly. (by @chshersh)

  • #176: Implement property-based tests for Validation laws. (by @astynax)

  • #172: Add Monoid and Semigroup instances for the Validation type. (by @mauriciofierrom)

  • #156: Implement helper type-level functions in Relude.Extra.Type. (by @TheMatten)

  • #170: Implement Elem type family. (by @kutyel)

  • #165: Re-export GHC.Float.atan2. (by @ethercrow)

  • #155: Implement foldlSC — short-circuting list fold — in Relude.Extra.Foldable. (by @josephcsible)

  • #158: Support GHC-8.6.5. (by @chshersh)

  • #148: Migrate HLint rules to the latest Dhall spec. (by @vrom911)

  • #178: Made die be polymorphic in its return type. (by @ilyakooo0)

  • #162, #189, #190, #191, #193, #194, #195: Various refactorings and code improvements:

    • Breaking change: Reorder type parameters to asumMap
    • Implement andM, orM, allM, and anyM in terms of &&^ and ||^
    • Use foldr instead of explicit recursion and toList
    • Use mapToFst instead of zip to improve list fusion in inverseMap
    • Implement foldMap1 for NonEmpty in terms of foldr
    • Use $> instead of *> and pure where possible
    • Implement asumMap and foldMapA by coercing foldMap
    • Return Failure early in <* and *> too

    (by @josephcsible)

  • #187: Remove tasty and tasty-hedgehog dependencies and their redundant imports. (by @dalpd)

0.5.0 — Mar 18, 2019

  • #127: Implement Relude.Extra.Lens module.
  • #125: Moved many numerical functions and types in Relude.Numeric. Reexport toIntegralSized from Data.Bits. Add integerToBounded and integerToNatural in Relude.Numeric.
  • #121: Reexport Ap from Data.Monoid. Change definition of foldMapA to use Ap.
  • #129: Add appliedTo and chainedTo as named versions of operators =<< and <**>.
  • #138: Add RealFloat to Relude.Numeric.
  • #144: Add traverseToSnd and friends to Relude.Extra.Tuple.
  • #140: Improve text of custom compile-time error messages for elem functions.
  • #136: Cover Relude.Extra.* modules with custom HLint rules.
  • #146: Improve documentation for Relude.File file: be more explicit about system locale issues.
  • Improve documentation for One typeclass and add tests.
  • Support ghc-8.6.4 and ghc-8.4.4. Drop support for ghc-8.6.1 and ghc-8.4.3.

0.4.0 — Nov 6, 2018

  • #70: Reexport Contravariant for GHC >= 8.6.1.
  • #103: Drop utf8-string dependency and improve performance of conversion functions.
  • #98: Reexport Bifoldable related stuff from base.
  • #99: Reexport Bitraversable related stuff from base.
  • #100: Add Relude.Extra.Validation with Validationdata type.
  • #89: Add Relude.Extra.Type module containing a typeName function.
  • #92 Add Relude.Extra.Tuple module, containing dupe, mapToFst, mapToSnd, and mapBoth functions.
  • #97: Add (&&^) and (||^) operators.
  • #81: Add asumMap to Foldable functions.
  • #80: Add hlint rules for whenLeft, whenLeftM, whenRight and whenRightM.
  • #79: Add HLint rules for One typeclass.
  • Remove openFile and hClose.
  • #83: Make documentation for nub functions prettier.
  • #109: Use Dhall v3.0.0 for hlint file generation.

0.3.0

  • #41: Add Foldable1.

  • #63: Remove Print typeclass. Add put[L]BS[Ln] functions. trace functions now take String as argument instead of Text.

    Important: this is a breaking change. If you used polymorphic putStrLn you need to remove type application or switch to one of the monomorphic functions. Also, you can’t abstract over Print typeclass anymore.

  • #66: Export (>>>) and (<<<) from Control.Category.

  • #59: Introduce flap function and its operator version ??.

  • #64: Improve performance of functions from Foldable1. Add foldl1' function.

  • Reexport uncons from base.

  • Rewrite die implementation to use die from base.

  • #19: Rewrite .hlint.yaml to Dhall.

  • Move stdin- and stdout-related functions to new module Relude.Lifted.Terminal.

  • #67: Add HLint rules for put* functions.

  • #22: readFile, writeFile and appendFile now work with String. Add lifted version of hClose. Add readFile, writeFile and appendFile alternatives for Text and ByteString.

  • #61: Add under2 and underF2 functions to Relude.Extra.Newtype.

  • #60: Add hoistMaybe and hoistEither functions.

0.2.0

  • #43: Implement Relude.Extra.Newtype module.
  • #46: Add a function that returns its own name.
  • #48: Export <&> from base. Also reexport fromLeft and fromRight from base where possible.
  • #49: Speed up and refactor property tests.
  • #54: Improve documentation. Add more examples to documentation and more tests. Reexport withReader and withReaderT. Remove safeHead. Rename Relude.List.Safe to Relude.List.NonEmpty.

0.1.1

  • #44: Implement parser deriviation from pretty-printers.

0.1.0

  • #7: Remove Container.Class.Container. Export Foldable.
  • #2: Remove microlens from dependencies.
  • #10: Remove VarArg module.
  • #9: Remove safe-exceptions from dependencies. Reexport Exception and SomeException from Control.Exception instead.
  • #11: Remove TypeOps module and type-operators dependency.
  • #13: Remove list, getContents, interact, getArgs, note functions. Remove Lifted.ST module. Rename Lifted.Env to Lifted.Exit.
  • #16: Rename whenLeft, whenRight, whenLeftM, whenRightM to whenLeft_ and whenRight_, whenLeftM_ and whenRightM_. Add whenLeft, whenRight, whenLeftM, whenRightM which return the value.
  • #18: Add LazyStrict type class for conversions.
  • map is not fmap anymore. Reexport map from Data.List
  • #12: Remove liquid-haskell support.
  • #20: Add viaNonEmpty function.
  • #21: Add MonadFail instance for Either.
  • #17: Add foldMapA and foldMapM functions.
  • #4: Rename package to Relude.
  • #14: Add Relude.Extra.* modules which are not exported by default but have useful functions.
  • #8: Introduce StaticMap and DynamicMap type classes as universal interface for Map-like structures.