HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

ModuleListLike-4.7.8.4Haskell2010

Data.ListLike

Generic operations over list-like structures

Written by John Goerzen, jgoerzen@complete.org

Please start with the introduction at Data.ListLike#intro.

  • 4 types
  • 5 classes
  • 11 values
  • PackageListLike-4.7.8.4
  • Exports113
  • LanguageHaskell2010
  • LicenceBSD-3-Clause
  • SourceListLike.hs

Introduction

0 declarations

Welcome to ListLike.

This module provides abstractions over typical list operations. It is designed to let you freely interchange different ways to represent sequences of data. It works with lists, various types of ByteStrings, and much more.

In this module, you'll find generic versions of most of the functions you're used to using in the Prelude, Data.List, and System.IO. They carry the same names, too. Therefore, you'll want to be careful how you import the module. I suggest using:

import qualified Data.ListLike as LL

Then, you can use LL.fold, LL.map, etc. to get the generic version of the functions you want. Alternatively, you can hide the other versions from Prelude and import specific generic functions from here, such as:

import Prelude hiding (map)
import Data.ListLike (map)

The module Data.ListLike actually simply re-exports the items found in a number of its sub-modules. If you want a smaller subset of Data.ListLike, look at the documentation for its sub-modules and import the relevant one.

In most cases, functions here can act as drop-in replacements for their list-specific counterparts. They will use the same underlying implementations for lists, so there should be no performance difference.

You can make your own types instances of ListLike as well. For more details, see the notes for the ListLike typeclass.

Creation & Basic Functions

12 declarations
methodempty :: full
#

The empty list

methodsingleton :: item -> full
#

Creates a single-element list out of an element

methodcons :: item -> full -> full
#

Like (:) for lists: adds an element to the beginning of a list

methodsnoc :: full -> item -> full
#

Adds an element to the *end* of a ListLike.

methodappend :: full -> full -> full
#

Combines two lists. Like (++).

methoduncons :: full -> Maybe (item, full)
#

Extract head and tail, return Nothing if empty

methodhead :: full -> item
#

Extracts the first element of a ListLike.

methodlast :: full -> item
#

Extracts the last element of a ListLike.

methodtail :: full -> full
#

Gives all elements after the head.

methodinit :: full -> full
#

All elements of the list except the last one. See also inits.

methodnull :: full -> Bool
#

Tests whether the list is empty.

List transformations

4 declarations
methodmap :: ListLike full' item' => (item -> item') -> full -> full'
#

Apply a function to each element, returning any other valid ListLike. rigidMap will always be at least as fast, if not faster, than this function and is recommended if it will work for your purposes. See also mapM.

methodrigidMap :: (item -> item) -> full -> full
#

Like map, but without the possibility of changing the type of the item. This can have performance benefits for things such as ByteStrings, since it will let the ByteString use its native low-level map implementation.

methodreverse :: full -> full
#

Reverse the elements in a list.

methodintersperse :: item -> full -> full
#

Add an item between each element in the structure

Conversions

methodtoList :: l -> [Item l]
#

The toList function extracts a list of Item l from the structure l. It should satisfy fromList . toList = id.

methodfromList :: [Item l] -> l
#

The fromList function constructs the structure l from the given list of Item l

methodfromListLike :: ListLike full' item => full -> full'
#

Converts one ListLike to another. See also toList'. Default implementation is fromListLike = map id

Reducing lists (folds), from FoldableLL

6 declarations
methodfoldl :: (a -> item -> a) -> a -> full -> a
#

Left-associative fold

methodfoldl' :: (a -> item -> a) -> a -> full -> a
#

Strict version of foldl.

methodfoldl1 :: (item -> item -> item) -> full -> item
#

A variant of foldl with no base case. Requires at least 1 list element.

methodfoldr :: (item -> b -> b) -> b -> full -> b
#

Right-associative fold

methodfoldr' :: (item -> b -> b) -> b -> full -> b
#

Strict version of foldr

methodfoldr1 :: (item -> item -> item) -> full -> item
#

Like foldr, but with no starting value

Special folds

methodconcat :: ListLike full' full => full' -> full
#

Flatten the structure.

methodconcatMap :: ListLike full' item' => (item -> full') -> full -> full'
#

Map a function over the items and concatenate the results. See also rigidConcatMap.

methodrigidConcatMap :: (item -> full) -> full -> full
#

Like concatMap, but without the possibility of changing the type of the item. This can have performance benefits for some things such as ByteString.

methodany :: (item -> Bool) -> full -> Bool
#

True if any items satisfy the function

methodall :: (item -> Bool) -> full -> Bool
#

True if all items satisfy the function

methodmaximum :: Ord item => full -> item
#

The maximum value of the list

methodminimum :: Ord item => full -> item
#

The minimum value of the list

valuefoldMap :: (FoldableLL full item, Monoid m) => (item -> m) -> full -> m
#

Map each element to a monoid, then combine the results

Building lists

0 declarations

Scans

Accumulating maps

Infinite lists

methoditerate :: (item -> item) -> item -> full
#

An infinite list of repeated calls of the function to args

methodrepeat :: item -> full
#

An infinite list where each element is the same

methodreplicate :: Int -> item -> full
#

Generate a structure with the specified length with every element set to the item passed in. See also genericReplicate

methodcycle :: full -> full
#

Converts a finite list into a circular one

Unfolding

Sublists

0 declarations

Extracting sublists

methodtake :: Int -> full -> full
#

Takes the first n elements of the list. See also genericTake.

methoddrop :: Int -> full -> full
#

Drops the first n elements of the list. See also genericDrop

methodtakeWhile :: (item -> Bool) -> full -> full
#

Returns all elements at start of list that satisfy the function.

methoddropWhile :: (item -> Bool) -> full -> full
#

Drops all elements from the start of the list that satisfy the function.

methoddropWhileEnd :: (item -> Bool) -> full -> full
#

Drops all elements from the end of the list that satisfy the function.

methodbreak :: (item -> Bool) -> full -> (full, full)
#

The equivalent of span (not . f)

methodgroup :: (ListLike full' full, Eq item) => full -> full'
#

Split a list into sublists, each which contains equal arguments. For order-preserving types, concatenating these sublists will produce the original list. See also groupBy.

methodinits :: ListLike full' full => full -> full'
#

All initial segments of the list, shortest first

methodtails :: ListLike full' full => full -> full'
#

All final segnemts, longest first

Predicates

methodisPrefixOf :: Eq item => full -> full -> Bool
#

True when the first list is at the beginning of the second.

methodisSuffixOf :: Eq item => full -> full -> Bool
#

True when the first list is at the beginning of the second.

methodisInfixOf :: Eq item => full -> full -> Bool
#

True when the first list is wholly containted within the second

Modify based on predicate

methodstripPrefix :: Eq item => full -> full -> Maybe full
#

Remove a prefix from a listlike if possible

methodstripSuffix :: Eq item => full -> full -> Maybe full
#

Remove a suffix from a listlike if possible

Searching lists

0 declarations

Searching by equality

methodelem :: Eq item => item -> full -> Bool
#

True if the item occurs in the list

methodnotElem :: Eq item => item -> full -> Bool
#

True if the item does not occur in the list

Searching with a predicate

methodfind :: (item -> Bool) -> full -> Maybe item
#

Take a function and return the first matching element, or Nothing if there is no such element.

methodfilter :: (item -> Bool) -> full -> full
#

Returns only the elements that satisfy the function.

methodpartition :: (item -> Bool) -> full -> (full, full)
#

Returns the lists that do and do not satisfy the function. Same as (filter p xs, filter (not . p) xs)

Indexing lists

5 declarations
methodindex :: full -> Int -> item
#

The element at 0-based index i. Raises an exception if i is out of bounds. Like (!!) for lists.

methodelemIndex :: Eq item => item -> full -> Maybe Int
#

Returns the index of the element, if it exists.

methodfindIndex :: (item -> Bool) -> full -> Maybe Int
#

Take a function and return the index of the first matching element, or Nothing if no element matches

methodfindIndices :: ListLike result Int => (item -> Bool) -> full -> result
#

Returns the indices of all elements satisfying the function

Zipping and unzipping lists

3 declarations
valuezip
  1. :: (ListLike full item, ListLike fullb itemb, ListLike result (item, itemb))
  2. => full
  3. -> fullb
  4. -> result
#

Takes two lists and returns a list of corresponding pairs.

valuezipWith
  1. :: (ListLike full item, ListLike fullb itemb, ListLike result resultitem)
  2. => item -> itemb -> resultitem
  3. -> full
  4. -> fullb
  5. -> result
#

Takes two lists and combines them with a custom combining function

valueunzip
  1. :: (ListLike full (itema, itemb), ListLike ra itema, ListLike rb itemb)
  2. => full
  3. -> (ra, rb)
#

Converts a list of pairs into two separate lists of elements

Monadic Operations

5 declarations
methodsequence :: (Applicative m, ListLike fullinp (m item)) => fullinp -> m full
#

Evaluate each action in the sequence and collect the results

methodrigidMapM :: Monad m => (item -> m item) -> full -> m full
#

Like mapM, but without the possibility of changing the type of the item. This can have performance benefits with some types.

valuemapM_ :: (Monad m, FoldableLL full item) => (item -> m b) -> full -> m ()
#

A map in monad space, discarding results.

Input and Output

1 declaration
classclass ListLike full item => ListLikeIO full item | full -> item where
#

An extension to ListLike for those data types that support I/O. These functions mirror those in System.IO for the most part. They also share the same names; see the comments in Data.ListLike for help importing them.

Note that some types may not be capable of lazy reading or writing. Therefore, the usual semantics of System.IO functions regarding laziness may or may not be available from a particular implementation.

Minimal complete definition:

  • hGetLine

  • hGetContents

  • hGet

  • hGetNonBlocking

  • hPutStr

Methods

Instances13ListLikeIO, …

Special lists

0 declarations

Strings

methodlines :: ListLike full s => s -> full
#

Breaks a string into a list of strings

methodwords :: ListLike full s => s -> full
#

Breaks a string into a list of words

methodfromStringLike :: StringLike s' => s -> s'
#

Deprecated. Use fromString . toString or something more efficient using local knowledge

"Set" operations

methodnub :: Eq item => full -> full
#

Removes duplicate elements from the list. See also nubBy

methoddelete :: Eq item => item -> full -> full
#

Removes the first instance of the element from the list. See also deleteBy

methoddeleteFirsts :: Eq item => full -> full -> full
#

List difference. Removes from the first list the first instance of each element of the second list. See (\\) and deleteFirstsBy

methodunion :: Eq item => full -> full -> full
#

List union: the set of elements that occur in either list. Duplicate elements in the first list will remain duplicate. See also unionBy.

methodintersect :: Eq item => full -> full -> full
#

List intersection: the set of elements that occur in both lists. See also intersectBy

Ordered lists

methodsort :: Ord item => full -> full
#

Sorts the list. On data types that do not preserve ordering, or enforce their own ordering, the result may not be what you expect. See also sortBy.

methodinsert :: Ord item => item -> full -> full
#

Inserts the element at the last place where it is still less than or equal to the next element. On data types that do not preserve ordering, or enforce their own ordering, the result may not be what you expect. On types such as maps, this may result in changing an existing item. See also insertBy.

Generalized functions

0 declarations

The "By" operations

User-supplied equality (replacing an Eq context)

methodnubBy :: (item -> item -> Bool) -> full -> full
#

Generic version of nub

methodunionBy :: (item -> item -> Bool) -> full -> full -> full
#

Generic version of union

User-supplied comparison (replacing an Ord context)

methodsortBy :: (item -> item -> Ordering) -> full -> full
#

Sort function taking a custom comparison function

methodinsertBy :: (item -> item -> Ordering) -> item -> full -> full
#

Like insert, but with a custom comparison function

The "generic" operations

Notes on specific instances

0 declarations

Lists

Functions for operating on regular lists almost all use the native implementations in Data.List, Prelude, or similar standard modules. The exceptions are:

Arrays

Array is an instance of ListLike. Here are some notes about it:

  • The index you use must be an integral

  • ListLike functions that take an index always take a 0-based index for compatibility with other ListLike instances. This is translated by the instance functions into the proper offset from the bounds in the Array.

  • ListLike functions preserve the original Array index numbers when possible. Functions such as cons will reduce the lower bound to do their job. snoc and append increase the upper bound. drop raises the lower bound and take lowers the upper bound.

  • Functions that change the length of the array by an amount not known in advance, such as filter, will generate a new array with the lower bound set to 0. Furthermore, these functions cannot operate on infinite lists because they must know their length in order to generate the array. hGetContents and its friends will therefore require the entire file to be read into memory before processing is possible.

  • empty, singleton, and fromList also generate an array with the lower bound set to 0.

  • Many of these functions will generate runtime exceptions if you have not assigned a value to every slot in the array.

ByteStrings

Both strict and lazy ByteStreams can be used with ListLike.

ByteString ListLike instances operate on Word8 elements. This is because both Data.ByteString.ByteString and Data.ByteString.Char8.ByteString have the same underlying type. If you wish to use the Char8 representation, the newtype wrappers CharString and CharStringLazy are available.

Most ListLike operations map directly to ByteStream options. Notable exceptions:

  • map uses the ListLike implementation. rigidMap is more efficient. The same goes for concatMap vs. rigidConcatMap.

  • isInfixOf, sequence, mapM and similar monad operations, insert, union, intersect, sortBy, and similar functions are not implemented in ByteStream and use a naive default implementation.

  • The lazy ByteStream module implements fewer funtions than the strict ByteStream module. In some cases, default implementations are used. In others, notably related to I/O, the lazy ByteStreams are converted back and forth to strict ones as appropriate.

datadata Chars
#

Constructors

Instances13IsList, Eq, Ord, Show, IsString, Semigroup, …
  • IsList CharsDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • Eq CharsDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • Ord CharsDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • Show CharsDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • IsString CharsDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • Semigroup CharsDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • Monoid CharsDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • NFData CharsDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • StringLike CharsDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • ListLike Chars CharDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • FoldableLL Chars CharDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • ListLikeIO Chars CharDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
  • type Item Chars = CharDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
newtypenewtype CharString
#

Newtype wrapper around Data.ByteString.Char8.ByteString, this allows for ListLike instances with Char elements.

Constructors

Instances13IsList, Eq, Ord, Read, Show, IsString, …
newtypenewtype CharStringLazy
#

Newtype wrapper around Data.ByteString.Lazy.Char8.ByteString, this allows for ListLike instances with Char elements.

Constructors

Instances13IsList, Eq, Ord, Read, Show, IsString, …

Base Typeclasses

0 declarations

The ListLike class

classclass (IsList full, item ~ Item full, FoldableLL full item, Monoid full) => ListLike full item | full -> item where
#

The class implementing list-like functions.

It is worth noting that types such as Data.Map.Map can be instances of ListLike. Due to their specific ways of operating, they may not behave in the expected way in some cases. For instance, cons may not increase the size of a map if the key you have given is already in the map; it will just replace the value already there.

Implementators must define at least:

  • singleton

  • head

  • tail

  • null or genericLength

Instances19ListLike, …

The FoldableLL class

classclass FoldableLL full item | full -> item where
#

This is the primary class for structures that are to be considered foldable. A minimum complete definition provides foldl and foldr.

Instances of FoldableLL can be folded, and can be many and varied.

These functions are used heavily in Data.ListLike.

Instances19FoldableLL, …

The StringLike class

classclass IsString s => StringLike s where
#

An extension to ListLike for those data types that are similar to a String. Minimal complete definition is toString and fromString.

Instances17StringLike, …

The InfiniteListLike class

classclass ListLike full item => InfiniteListLike full item | full -> item where
#

An extension to ListLike for those data types that are capable of dealing with infinite lists. Some ListLike functions are capable of working with finite or infinite lists. The functions here require infinite list capability in order to work at all.

Instances2InfiniteListLike