extra

Extra functions I use.

https://github.com/ndmitchell/extra#readme

LTS Haskell 23.1:1.7.16@rev:1
Stackage Nightly 2024-12-22:1.8
Latest on Hackage:1.8

See all snapshots extra appears in

BSD-3-Clause licensed and maintained by Neil Mitchell
This version can be pinned in stack with:extra-1.8@sha256:57d9200fbea2e88e05e0be35925511764827b1c86d3214106b0b610f331fc40c,2725

Module documentation for 1.8

Extra Hackage version Stackage version Build status

A library of extra functions for the standard Haskell libraries. Most functions are simple additions, filling out missing functionality. A few functions are available in later versions of GHC, but this package makes them available back to GHC 7.10. A few examples:

  • Control.Monad.Extra.concatMapM provides a monadic version of concatMap, in the same way that mapM is a monadic version of map.
  • Data.Tuple.Extra.fst3 provides a function to get the first element of a triple.
  • Control.Exception.Extra.retry provides a function that retries an IO action a number of times.
  • Data.Either.Extra.fromLeft is a function available in GHC 8.0 and above. On GHC 8.0 and above this package reexports the version from Data.Either while on GHC 7.10 and below it defines an equivalent version.

The module Extra documents all functions provided by this library. Modules such as Data.List.Extra provide extra functions over Data.List and also reexport Data.List. Users are recommended to replace Data.List imports with Data.List.Extra if they need the extra functionality.

Which functions?

When producing a library of extra functions I have been guided by a few principles. I encourage others with small useful utility functions contribute them here, perhaps as a temporary stop before proposing they join the standard libraries.

  • I have been using most of these functions in my packages - they have proved useful enough to be worth copying/pasting into each project.
  • The functions follow the spirit of the original Prelude/base libraries. I am happy to provide partial functions (e.g. fromRight), and functions which are specialisations of more generic functions (whenJust).
  • Most of the functions have trivial implementations that are obvious from their name/signature. If a beginner couldn’t write the function, it probably doesn’t belong here.
  • I have defined only a few new data types or type aliases. It’s a package for defining new utilities on existing types, not new types or concepts.

Base versions

A mapping between base versions and GHC compiler versions can be found here.

Contributing

My general contribution preferences are available here. In addition, this repo contains some generated code which is checked in, namely src/Extra.hs and test/TestGen.hs. You can generate those files by either running runghc Generate.hs or ghci (which uses the .ghci file) and typing :generate. All PR’s should contain regenerated versions of those files.

Changes

Changelog for Extra (* = breaking change)

1.8, released 2024-10-19
#109, add guarded to lift predicates into Alternatives
* #112, make Data.List.Extra.compareLength work on list/int only
#112, add compareLength to List.NonEmpty and Foldable
1.7.16, released 2024-05-11
Fix to actually work with GHC 9.10
1.7.15, released 2024-05-10
#111, work with GHC 9.10
Test with GHC 9.8
1.7.14, released 2023-07-01
#106, add compatibility with GHC 9.7
#103, future-proof against addition of Data.List.unsnoc
1.7.13, released 2023-04-22
#102, add mwhen :: Monoid a => Bool -> a -> a
#99, make replace with an empty from intersperse the replacement
#101, future-proof against addition of Data.List.!?
1.7.12, released 2022-09-02
#98, make both lazy in its argument
#98, make first3,second3,third3 lazy in their argument
#98, make firstM,secondM lazy in their argument
#86, add notNull for Foldable
1.7.11, released 2022-08-21
#95, add List.repeatedlyNE and NonEmpty.repeatedly
#94, add groupOnKey
#91, add foldl1' to NonEmpty
1.7.10, released 2021-08-29
#81, add assertIO function
#85, add !? to do !! list indexing returning a Maybe
#80, add strict Var functions modifyVar', modifyVar_', writeVar'
1.7.9, released 2020-12-19
#72, add pureIf
#73, make takeEnd, dropEnd, splitAtEnd: return immediately if i <= 0
#71, add compareLength and comparingLength
1.7.8, released 2020-09-12
#68, make sure Data.Foldable.Extra is exposed
1.7.7, released 2020-08-25
#67, defer to System.IO readFile', hGetContents' in GHC 9.0
1.7.6, released 2020-08-21
#66, add lots of functions to Data.Foldable.Extra (anyM etc)
1.7.5, released 2020-08-12
#65, add Data.Foldable.Extra
#65, add sum', product', sumOn' and productOn'
1.7.4, released 2020-07-15
#59, add whileJustM and untilJustM
#61, optimise nubOrd (10% or so)
Add first3, second3, third3
1.7.3, released 2020-05-30
#58, add disjointOrd and disjointOrdBy
1.7.2, released 2020-05-25
#56, add zipWithLongest
#57, make duration in MonadIO
Simplify and optimise Barrier
Mark modules that are empty as DEPRECATED
Remove support for GHC 7.10
1.7.1, released 2020-03-10
Add NOINLINE to errorIO to work around a GHC 8.4 bug
1.7, released 2020-03-05
* #40, delete deprecated function for
* zipFrom now truncates lists, rather than error, just like zip
1.6.21, released 2020-03-02
#54, deprecate nubOn since its O(n^2). Use nubOrdOn
#53, add some nub functions to NonEmpty
1.6.20, released 2020-02-16
Add firstM, secondM
1.6.19, released 2020-02-11
#50, add headDef, lastDef, and dropEnd1
1.6.18, released 2019-08-21
Make errorIO include a call stack
Make maximumOn and minimumOn apply the function once per element
1.6.17, released 2019-05-31
Add enumerate
1.6.16, released 2019-05-25
Add atomicModifyIORef_ and atomicModifyIORef'_
1.6.15, released 2019-04-22
#45, add NonEmpty.Extra for extra appending functions
#42, add fromMaybeM
Remove support for GHC 7.4, 7.6 and 7.8
1.6.14, released 2018-12-10
Add mapLeft and mapRight
1.6.13, released 2018-10-14
#40, deprecate Data.List.Extra.for (clashes with Traversable)
1.6.12, released 2018-09-24
#39, add curry3/uncurry3
1.6.11, released 2018-09-18
#38, make escapeHTML replace ' with &#39;
1.6.10, released 2018-09-04
#37, make a duration/sleep test more robust (wider bounds)
1.6.9, released 2018-07-12
Add loop, the non-monadic version of loopM
#36, add whenMaybe and whenMaybeM
1.6.8, released 2018-05-24
Add notNull
Add listDirectories
1.6.7, released 2018-05-23
#35, add fold1M and fold1M_
#34, lots of documentation typos
1.6.6, released 2018-04-16
Add escapeJSON and unescapeJSON
Add escapeHTML and unescapeHTML
1.6.5, released 2018-03-24
#33, improve error messages on test suite failures
1.6.4, released 2018-02-23
Add dropPrefix and dropSuffix
1.6.3, released 2018-01-26
Add maximumOn and minimumOn
#31, add nubSort, nubSortBy and nubSortOn
1.6.2, released 2017-12-07
Mark the partial functions with Partial
Add Partial constraint
1.6.1, released 2017-11-30
Add newTempFileWithin and newTempDirWithin
Mark the Extra module as deprecated, used for documentation only
1.6, released 2017-06-16
#23, delete subtractTime
Require QuickCheck-2.10
1.5.3, released 2017-06-12
Add readMaybe, readEither
1.5.2, released 2017-04-04
Add errorWithoutStackTrace to Control.Exception.Extra
1.5.1, released 2016-10-25
#25, add zipFrom and zipWithFrom
#24, add eitherToMaybe and maybeToEither
Add fromLeft' and fromRight'
1.5, released 2016-07-21
Change fromLeft/fromRight signatures to follow the base libraries
1.4.12, released 2016-07-18
Add writeVar
1.4.11, released 2016-07-15
Require QuickCheck 2.9
#23, deprecate offsetTimeIncrease and subtract
#22, improve offsetTime to give reliable measurements
Depend on the clock library
1.4.10, released 2016-06-15
Add Data.Typeable.Extra containing typeRep, Proxy, (:~:)
1.4.9, released 2016-06-01
Add line1
1.4.8, released 2016-05-26
Add displayException
1.4.7, released 2016-05-22
#21, add concatForM
1.4.6, released 2016-05-11
#11, add maybeM and eitherM
1.4.5, released 2016-04-29
#17, change fileEq on files that do not exist to be an error
1.4.4, released 2016-04-29
#14, add mconcatMap and mconcatMapM
#16, add fileEq
#15, add isMac
1.4.3, released 2016-01-07
Add Data.Version.Extra
1.4.2, released 2015-09-14
Make concatMapM/mapMaybeM faster
1.4.1, released 2015-08-04
Make temp file functions workaround GHC bug #10731
Add retryBool
1.4, released 2015-07-23
Add stripInfix and stripInfixEnd
1.3.1, released 2015-07-17
#9, support directory-1.2.3
1.3, released 2015-06-20
Add whenJustM
Add errorIO
1.2, released 2015-05-18
Add onceFork
Make once async exception safe
Fix a deadlock in once when two people request in parallel
Fix a missing hClose in captureOutput
1.1, released 2015-02-17
#7, add nubOrd, nubOrdOn, nubOrdBy
#6, add groupSortOn and groupSortBy
#5, add splitAtEnd
1.0.1, released 2015-01-09
Make listFilesAvoid drop trailing path separators before testing
#3, add a constraint base >= 4.4
1.0, released 2014-11-27
No changes
0.8, released 2014-11-12
Fix a bug in writeFileEncoding/writeFileUTF8
0.7, released 2014-11-03
Fix for missing case in withNumCapabilities
0.6, released 2014-10-31
Ensure barrier is thread-safe
Make subsequent signalBarrier calls throw an exception
Add timeout function
Make sure sleep never wraps round an Int
0.5.1, released 2014-10-28
Use uncons from GHC 7.9 and above
0.5, released 2014-10-28
Use the sortOn from GHC 7.9 and above
Remove getProcessorCount
Remove getDirectoryContentsRecursive in favour of listFilesRecursive
Change the signature for newTempFile/newTempDir
Add a once function
0.4, released 2014-10-23
Remove all but the extractors on triples
Remove groupSortOn
Remove dropAround
0.3.2, released 2014-10-21
Remove use of ===, allows older QuickCheck versions
0.3.1, released 2014-10-20
Fix a bug in breakEnd/spanEnd
0.3, released 2014-10-18
Rename showTime to showDuration
Add stringException
Eliminate rep/reps, use replace instead
Switch distinct for allSame/anySame
Optimise the numeric conversions
Rename chop to repeatedly
Add whenM/unlessM
Redo the Tuple module, additions and deletions
Add newTempFile, newTempDir
Add createDirectoryPrivate
Rename strip* to trim*
Generalise showException
0.2, released 2014-10-07
Redo the cons/uncons functions
Add withTempDir
Rename withTemporaryFile to withTempFile
Change trim to strip (follow text naming convention)
Ensure operators get exported
0.1, released 2014-10-06
Initial version, still unstable