The empty list
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 declarationsWelcome 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 LLThen, 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 declarationsCreates a single-element list out of an element
Like (:) for lists: adds an element to the beginning of a list
Adds an element to the *end* of a ListLike.
Combines two lists. Like (++).
Extract head and tail, return Nothing if empty
Extracts the first element of a ListLike.
Extracts the last element of a ListLike.
Gives all elements after the head.
All elements of the list except the last one. See also inits.
Tests whether the list is empty.
Length of the list. See also genericLength.
List transformations
4 declarationsLike 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.
Reverse the elements in a list.
Add an item between each element in the structure
Conversions
The toList function extracts a list of Item l from the structure l.
It should satisfy fromList . toList = id.
The fromList function constructs the structure l from the given
list of Item l
Converts one ListLike to another. See also toList'.
Default implementation is fromListLike = map id
Reducing lists (folds), from FoldableLL
6 declarationsLeft-associative fold
Strict version of foldl.
A variant of foldl with no base case. Requires at least 1 list element.
Right-associative fold
Strict version of foldr
Like foldr, but with no starting value
Special folds
Flatten the structure.
Map a function over the items and concatenate the results. See also rigidConcatMap.
Like concatMap, but without the possibility of changing the type of the item. This can have performance benefits for some things such as ByteString.
Returns True if all elements are True
Returns True if any element is True
True if any items satisfy the function
True if all items satisfy the function
The sum of the list
The product of the list
The maximum value of the list
The minimum value of the list
Map each element to a monoid, then combine the results
Building lists
0 declarationsScans
Accumulating maps
Infinite lists
An infinite list of repeated calls of the function to args
An infinite list where each element is the same
Generate a structure with the specified length with every element set to the item passed in. See also genericReplicate
Converts a finite list into a circular one
Unfolding
Sublists
0 declarationsExtracting sublists
Takes the first n elements of the list. See also genericTake.
Drops the first n elements of the list. See also genericDrop
Equivalent to (take n xs, drop n xs). See also genericSplitAt.
Returns all elements at start of list that satisfy the function.
Drops all elements from the start of the list that satisfy the function.
Drops all elements from the end of the list that satisfy the function.
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.
All initial segments of the list, shortest first
All final segnemts, longest first
Predicates
True when the first list is at the beginning of the second.
True when the first list is at the beginning of the second.
True when the first list is wholly containted within the second
Modify based on predicate
Remove a prefix from a listlike if possible
Remove a suffix from a listlike if possible
Searching lists
0 declarationsSearching by equality
True if the item occurs in the list
True if the item does not occur in the list
Searching with a predicate
Take a function and return the first matching element, or Nothing if there is no such element.
Returns only the elements that satisfy the function.
Indexing lists
5 declarationsThe element at 0-based index i. Raises an exception if i is out of bounds. Like (!!) for lists.
Returns the index of the element, if it exists.
Returns the indices of the matching elements. See also findIndices
Take a function and return the index of the first matching element, or Nothing if no element matches
Returns the indices of all elements satisfying the function
Zipping and unzipping lists
3 declarationsTakes two lists and returns a list of corresponding pairs.
Takes two lists and combines them with a custom combining function
Converts a list of pairs into two separate lists of elements
Monadic Operations
5 declarationsEvaluate each action in the sequence and collect the results
Like mapM, but without the possibility of changing the type of the item. This can have performance benefits with some types.
A map in monad space, discarding results.
Input and Output
1 declarationAn 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
hGetLine :: Handle -> IO fullReads a line from the specified handle
hGetContents :: Handle -> IO fullRead entire handle contents. May be done lazily like
System.IO.hGetContents.hGet :: Handle -> Int -> IO fullRead specified number of bytes. See
System.IO.hGetfor particular semantics.hGetNonBlocking :: Handle -> Int -> IO fullNon-blocking read. See
System.IO.hGetNonBlockingfor more.hPutStr :: Handle -> full -> IO ()Writing entire data.
hPutStrLn :: Handle -> full -> IO ()Write data plus newline character.
getLine :: IO fullRead one line
getContents :: IO fullRead entire content from stdin. See hGetContents.
putStr :: full -> IO ()Write data to stdout.
putStrLn :: full -> IO ()Write data plus newline character to stdout.
interact :: (full -> full) -> IO ()Interact with stdin and stdout by using a function to transform input to output. May be lazy. See
System.IO.interactfor more.readFile :: FilePath -> IO fullRead file. May be lazy.
writeFile :: FilePath -> full -> IO ()Write data to file.
appendFile :: FilePath -> full -> IO ()Append data to file.
Instances13ListLikeIO, …
ListLikeIO CharString CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringListLikeIO CharStringLazy CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringListLikeIO Chars CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharsListLikeIO ByteString Word8Defined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanListLikeIO ByteString Word8Defined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanListLikeIO String CharDefined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanListLikeIO Text CharDefined in ListLike-4.7.8.4 · Data.ListLike.Text.Text · orphanListLikeIO Builder CharDefined in ListLike-4.7.8.4 · Data.ListLike.Text.Builder · orphanListLikeIO Text CharDefined in ListLike-4.7.8.4 · Data.ListLike.Text.TextLazy · orphanListLikeIO (Seq Char) CharDefined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanListLikeIO (UTF8 ByteString) CharDefined in ListLike-4.7.8.4 · Data.ListLike.UTF8 · orphanListLikeIO (UTF8 ByteString) CharDefined in ListLike-4.7.8.4 · Data.ListLike.UTF8 · orphan(Integral i, Ix i) => ListLikeIO (Array i Char) CharDefined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphan
Special lists
0 declarationsStrings
Converts the structure to a String
Breaks a string into a list of strings
Breaks a string into a list of words
Generalize the Show method t return any StringLike.
Deprecated. Use fromString . toString or something more efficient using local knowledge
Override this to avoid extra String conversions.
Override this to avoid extra String conversions.
"Set" operations
Removes duplicate elements from the list. See also nubBy
Removes the first instance of the element from the list. See also deleteBy
List difference. Removes from the first list the first instance
of each element of the second list. See (\\) and deleteFirstsBy
List union: the set of elements that occur in either list. Duplicate elements in the first list will remain duplicate. See also unionBy.
List intersection: the set of elements that occur in both lists. See also intersectBy
Ordered lists
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.
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 declarationsThe "By" operations
User-supplied equality (replacing an Eq context)
Generic version of nub
Generic version of deleteBy
Generic version of deleteFirsts
Generic version of union
Generic version of intersect
Generic version of group.
User-supplied comparison (replacing an Ord context)
Sort function taking a custom comparison function
Like insert, but with a custom comparison function
The "generic" operations
Length of the list
Generic version of take
Generic version of drop
Generic version of splitAt
Generic version of replicate
Notes on specific instances
0 declarationsLists
Functions for operating on regular lists almost all use the native implementations in Data.List, Prelude, or similar standard modules. The exceptions are:
hGet does not exist for String in the Haskell modules. It is implemented in terms of Data.ByteString.Lazy.
hGetNonBlocking is the same way.
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
ByteStreamand 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.
Instances13IsList, Eq, Ord, Show, IsString, Semigroup, …
IsList CharsDefined in ListLike-4.7.8.4 · Data.ListLike.CharsEq CharsDefined in ListLike-4.7.8.4 · Data.ListLike.CharsOrd CharsDefined in ListLike-4.7.8.4 · Data.ListLike.CharsShow CharsDefined in ListLike-4.7.8.4 · Data.ListLike.CharsIsString CharsDefined in ListLike-4.7.8.4 · Data.ListLike.CharsSemigroup CharsDefined in ListLike-4.7.8.4 · Data.ListLike.CharsMonoid CharsDefined in ListLike-4.7.8.4 · Data.ListLike.CharsNFData CharsDefined in ListLike-4.7.8.4 · Data.ListLike.CharsStringLike CharsDefined in ListLike-4.7.8.4 · Data.ListLike.CharsListLike Chars CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharsFoldableLL Chars CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharsListLikeIO Chars CharDefined in ListLike-4.7.8.4 · Data.ListLike.Charstype Item Chars = CharDefined in ListLike-4.7.8.4 · Data.ListLike.Chars
Newtype wrapper around Data.ByteString.Char8.ByteString, this allows for ListLike instances with Char elements.
Constructors
CSunCS :: ByteString
Instances13IsList, Eq, Ord, Read, Show, IsString, …
IsList CharStringDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringEq CharStringDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringOrd CharStringDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringRead CharStringDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringShow CharStringDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringIsString CharStringDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringSemigroup CharStringDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringMonoid CharStringDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringStringLike CharStringDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringListLike CharString CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringFoldableLL CharString CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringListLikeIO CharString CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringtype Item CharString = CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharString
Newtype wrapper around Data.ByteString.Lazy.Char8.ByteString, this allows for ListLike instances with Char elements.
Constructors
Instances13IsList, Eq, Ord, Read, Show, IsString, …
IsList CharStringLazyDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringEq CharStringLazyDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringOrd CharStringLazyDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringRead CharStringLazyDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringShow CharStringLazyDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringIsString CharStringLazyDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringSemigroup CharStringLazyDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringMonoid CharStringLazyDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringStringLike CharStringLazyDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringListLike CharStringLazy CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringFoldableLL CharStringLazy CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringListLikeIO CharStringLazy CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringtype Item CharStringLazy = CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharString
Base Typeclasses
0 declarationsThe ListLike class
class (IsList full, item ~ Item full, FoldableLL full item, Monoid full) => ListLike full item | full -> item whereThe 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, …
ListLike CharString CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringListLike CharStringLazy CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringListLike Chars CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharsListLike ByteString Word8Defined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanListLike ByteString Word8Defined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanListLike Text CharDefined in ListLike-4.7.8.4 · Data.ListLike.Text.Text · orphanListLike Builder CharDefined in ListLike-4.7.8.4 · Data.ListLike.Text.Builder · orphanListLike Text CharDefined in ListLike-4.7.8.4 · Data.ListLike.Text.TextLazy · orphanListLike (Seq a) aDefined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanListLike (DList a) aDefined in ListLike-4.7.8.4 · Data.ListLike.DList · orphanListLike (FMList a) aDefined in ListLike-4.7.8.4 · Data.ListLike.FMList · orphanListLike (UTF8 ByteString) CharDefined in ListLike-4.7.8.4 · Data.ListLike.UTF8 · orphanListLike (UTF8 ByteString) CharDefined in ListLike-4.7.8.4 · Data.ListLike.UTF8 · orphanListLike (Vector a) aDefined in ListLike-4.7.8.4 · Data.ListLike.Vector.Vector · orphanListLike [a] aDefined in ListLike-4.7.8.4 · Data.ListLike.BaseStorable a => ListLike (Vector a) aDefined in ListLike-4.7.8.4 · Data.ListLike.Vector.Storable · orphanUnbox a => ListLike (Vector a) aDefined in ListLike-4.7.8.4 · Data.ListLike.Vector.Unboxed · orphan(IsList (v a), Item (v a) ~ a, Monoid (v a), Eq (v a), Vector v a) => ListLike (v a) aDefined in ListLike-4.7.8.4 · Data.ListLike.Vector.Generic · orphan(Integral i, Ix i) => ListLike (Array i e) eDefined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphan
The FoldableLL class
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, …
FoldableLL CharString CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringFoldableLL CharStringLazy CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringFoldableLL Chars CharDefined in ListLike-4.7.8.4 · Data.ListLike.CharsFoldableLL ByteString Word8Defined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanFoldableLL ByteString Word8Defined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanFoldableLL Text CharDefined in ListLike-4.7.8.4 · Data.ListLike.Text.Text · orphanFoldableLL Builder CharDefined in ListLike-4.7.8.4 · Data.ListLike.Text.Builder · orphanFoldableLL Text CharDefined in ListLike-4.7.8.4 · Data.ListLike.Text.TextLazy · orphanFoldableLL (Seq a) aDefined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanFoldableLL (DList a) aDefined in ListLike-4.7.8.4 · Data.ListLike.DList · orphanFoldableLL (FMList a) aDefined in ListLike-4.7.8.4 · Data.ListLike.FMList · orphanFoldableLL (UTF8 ByteString) CharDefined in ListLike-4.7.8.4 · Data.ListLike.UTF8 · orphanFoldableLL (UTF8 ByteString) CharDefined in ListLike-4.7.8.4 · Data.ListLike.UTF8 · orphanFoldableLL (Vector a) aDefined in ListLike-4.7.8.4 · Data.ListLike.Vector.Vector · orphanFoldableLL [a] aDefined in ListLike-4.7.8.4 · Data.ListLike.FoldableLLStorable a => FoldableLL (Vector a) aDefined in ListLike-4.7.8.4 · Data.ListLike.Vector.Storable · orphanVector v a => FoldableLL (v a) aDefined in ListLike-4.7.8.4 · Data.ListLike.Vector.Generic · orphanUnbox a => FoldableLL (Vector a) aDefined in ListLike-4.7.8.4 · Data.ListLike.Vector.Unboxed · orphanIx i => FoldableLL (Array i e) eDefined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphan
The StringLike class
An extension to ListLike for those data types that are similar to a String. Minimal complete definition is toString and fromString.
Instances17StringLike, …
StringLike CharStringDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringStringLike CharStringLazyDefined in ListLike-4.7.8.4 · Data.ListLike.CharStringStringLike CharsDefined in ListLike-4.7.8.4 · Data.ListLike.CharsStringLike StringDefined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanStringLike TextDefined in ListLike-4.7.8.4 · Data.ListLike.Text.Text · orphanStringLike BuilderDefined in ListLike-4.7.8.4 · Data.ListLike.Text.Builder · orphanStringLike TextDefined in ListLike-4.7.8.4 · Data.ListLike.Text.TextLazy · orphanStringLike (Seq Char)Defined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphanStringLike (DList Char)Defined in ListLike-4.7.8.4 · Data.ListLike.DList · orphanStringLike (FMList Char)Defined in ListLike-4.7.8.4 · Data.ListLike.FMList · orphanStringLike (UTF8 ByteString)Defined in ListLike-4.7.8.4 · Data.ListLike.UTF8 · orphanStringLike (UTF8 ByteString)Defined in ListLike-4.7.8.4 · Data.ListLike.UTF8 · orphanStringLike (Vector Char)Defined in ListLike-4.7.8.4 · Data.ListLike.Vector.Vector · orphanStringLike (Vector Char)Defined in ListLike-4.7.8.4 · Data.ListLike.Vector.Storable · orphanStringLike (Vector Char)Defined in ListLike-4.7.8.4 · Data.ListLike.Vector.Unboxed · orphan(Eq (v Char), Vector v Char) => StringLike (v Char)Defined in ListLike-4.7.8.4 · Data.ListLike.Vector.Generic · orphan(Integral i, Ix i) => StringLike (Array i Char)Defined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphan
The InfiniteListLike class
Instances2InfiniteListLike
InfiniteListLike (FMList a) aDefined in ListLike-4.7.8.4 · Data.ListLike.FMList · orphanInfiniteListLike [a] aDefined in ListLike-4.7.8.4 · Data.ListLike.Instances · orphan