Commit f0ce5316 authored by Mart Lubbers's avatar Mart Lubbers

Merge branch 'docs'

parents 295ac466 9a2511c5
Pipeline #8105 passed with stage
in 1 minute and 51 seconds
......@@ -5,8 +5,17 @@ from Control.Monad import class Monad
from Control.Applicative import class Applicative
from Data.Maybe import :: Maybe
/**
* A type representing something that may have failed.
* @var The error type.
* @var The value type.
*/
:: MaybeError a b = Error a | Ok b
/**
* Like {{`MaybeError`}} but with {{`String`}} as error type.
* @var The value type.
*/
:: MaybeErrorString a :== MaybeError String a
instance Functor (MaybeError a)
......
......@@ -3,7 +3,7 @@ implementation module Data.Foldable
from StdFunc import o, id, flip
from StdMisc import abort
import Control.Applicative
import Control.Monad
from Control.Monad import class Monad(..), >>=
import qualified Data.List as DL
import Data.Either
import Data.Monoid
......@@ -118,131 +118,66 @@ instance Foldable (Const m) where
mf Nothing y = Just y
mf (Just x) y = Just (f x y)
// Monadic fold over the elements of a structure,
// associating to the right, i.e. from right to left.
foldrM :: (a b -> m b) b (t a) -> m b | Foldable t & Monad m
foldrM f z0 xs = foldl f` pure xs z0
where f` k x z = f x z >>= k
// Monadic fold over the elements of a structure,
// associating to the left, i.e. from left to right.
foldlM :: (b a -> m b) b (t a) -> m b | Foldable t & Monad m
foldlM f z0 xs = foldr f` pure xs z0
where f` x k z = f z x >>= k
// Map each element of a structure to an action, evaluate
// these actions from left to right, and ignore the results.
traverse_ :: (a -> f b) (t a) -> f () | Foldable t & Applicative, *> f
traverse_ f x = foldr ((*>) o f) (pure ()) x
// 'for_' is 'traverse_' with its arguments flipped.
//for_ :: (t a) (a -> f b) -> f () | Foldable t, Applicative f
for_ x f :== flip traverse_ x f
// Map each element of a structure to a monadic action, evaluate
// these actions from left to right, and ignore the results.
mapM_ :: (a -> m b) (t a) -> m () | Foldable t & Monad m
mapM_ f x = foldr ((\ma mb -> ma >>= \_ -> mb) o f) (pure ()) x
// 'forM_' is 'mapM_' with its arguments flipped.
//forM_ :: (t a) (a -> m b) -> m () | Foldable t & Monad m
forM_ x f :== flip mapM_ x f
// Evaluate each action in the structure from left to right,
// and ignore the results.
sequenceA_ :: (t (f a)) -> f () | Foldable t & Applicative, *> f
sequenceA_ x = foldr (*>) (pure ()) x
// Evaluate each monadic action in the structure from left to right,
// and ignore the results.
//sequence_ :: (t (m a)) -> m () | Foldable t & Monad m
sequence_ x :== foldr (\ma mb -> ma >>= \_ -> mb) (pure ()) x
// The sum of a collection of actions, generalizing 'concat'.
//asum :: (t (f a)) -> f a | Foldable t & Alternative f
asum x :== foldr (<|>) empty x
// The sum of a collection of actions, generalizing 'concat'.
//msum :: (t (m a)) -> m a | Foldable t & MonadPlus m
msum x :== foldr mplus mzero x
// These use foldr rather than foldMap to avoid repeated concatenation.
// List of elements of a structure.
//toList :: (t a) -> [a] | Foldable t
toList t :== build (\ c n -> foldr c n t)
//build :: (A.: (a b -> b) b -> b) -> [a]
build g :== g (\x xs -> [x:xs]) []
// The concatenation of all the elements of a container of lists.
concat :: (t [a]) -> [a] | Foldable t
concat x = fold x
// Map a function over all the elements of a container and concatenate
// the resulting lists.
concatMap :: (a -> [b]) (t a) -> [b] | Foldable t
concatMap f x = foldMap f x
// 'and' returns the conjunction of a container of Bools. For the
// result to be 'True', the container must be finite; 'False', however,
// results from a 'False' value finitely far from the left end.
and :: (t Bool) -> Bool | Foldable t
and x = getAll (foldMap All x)
// 'or' returns the disjunction of a container of Bools. For the
// result to be 'False', the container must be finite; 'True', however,
// results from a 'True' value finitely far from the left end.
or :: (t Bool) -> Bool | Foldable t
or x = getAny (foldMap Any x)
// Determines whether any element of the structure satisfies the predicate.
any :: (a -> Bool) (t a) -> Bool | Foldable t
any p x = getAny (foldMap (Any o p) x)
// Determines whether all elements of the structure satisfy the predicate.
all :: (a -> Bool) (t a) -> Bool | Foldable t
all p x = getAll (foldMap (All o p) x)
// The 'sum' function computes the sum of the numbers of a structure.
sum :: (t a) -> a | Foldable t & + a & zero a
sum x = getSum (foldMap Sum x)
// The 'product' function computes the product of the numbers of a structure.
product :: (t a) -> a | Foldable t & * a & one a
product x = getProduct (foldMap Product x)
// The largest element of a non-empty structure.
maximum :: (t a) -> a | Foldable t & Ord a
maximum x = foldr1 max x
// The largest element of a non-empty structure with respect to the
// given greater-than function.
maximumBy :: (a a -> Bool) (t a) -> a | Foldable t
maximumBy cmp x = foldr1 max` x
where max` x y = if (cmp x y) x y
// The least element of a non-empty structure.
minimum :: (t a) -> a | Foldable t & Ord a
minimum x = foldr1 min x
// The least element of a non-empty structure with respect to the
// given lesser-than function.
minimumBy :: (a a -> Bool) (t a) -> a | Foldable t
minimumBy cmp x = foldr1 min` x
where min` x y = if (cmp x y) x y
// Does the element occur in the structure?
elem :: a (t a) -> Bool | Foldable t & == a
elem x y = any (\z -> x == z) y
// 'notElem' is the negation of 'elem'.
notElem :: a (t a) -> Bool | Foldable t & == a
notElem x y = not (elem x y)
// The 'find' function takes a predicate and a structure and returns
// the leftmost element of the structure matching the predicate, or
// 'Nothing' if there is no such element.
find :: (a -> Bool) (t a) -> Maybe a | Foldable t
find p x = listToMaybe (concatMap (\x -> if (p x) [x] []) x)
definition module Data.Func
/**
* Function application.
* @type (a -> b) a -> b
*/
($) infixr 0
($) f :== f
/**
* Function application.
* @type a -> a
*/
app f :== f
/**
* Apply a state function to a list of values.
* See also {{`mapSt`}}.
*
* @param The function.
* @param The list of values.
* @param The initial state.
* @result The final state.
*/
seqSt :: !(a .st -> .st) ![a] !.st -> .st
/**
* Apply a state function to a list of values and return the results.
* See also {{`seqSt`}}.
*
* @param The function.
* @param The list of values.
* @param The initial state.
* @result The value results and the final state.
*/
mapSt :: !(a .st -> (!b,!.st)) ![a] !.st -> (![b],!.st)
/**
* The fixed point combinator, reducing `fix f` to `f (fix f)`.
*/
fix :: !(a -> a) -> a
/**
* Apply a binary function on another domain.
*
* Typical usage: `sortBy (on (<) toInt) :: [a] -> [a] | toInt a`
*/
on :: (b b -> c) (a -> b) -> (a a -> c)
//Evaluate the expression
/**
* Completely evaluate an expression (not just to head normal form like strictness).
*/
hyperstrict :: !.a -> .a
......@@ -35,16 +35,24 @@ null :: (Heap a) -> Bool
size :: (Heap a) -> Int
//empty :: Heap a
/**
* @type Heap a
*/
empty :== Empty
//singleton :: a -> Heap a | Ord a
/**
* @type a -> Heap a | Ord a
*/
singleton x :== singletonWith (<=) x
//singletonWith :: (a a -> Bool) a -> Heap a
/**
* @type (a a -> Bool) a -> Heap a
*/
singletonWith f a :== Heap 1 f (Node 0 a Nil)
//insert :: a (Heap a) -> (Heap a) | Ord a
/**
* @type a (Heap a) -> (Heap a) | Ord a
*/
insert :== insertWith (<=)
insertWith :: (a a -> Bool) a (Heap a) -> Heap a
......@@ -55,7 +63,9 @@ replicate :: a Int -> Heap a | Ord a
uncons :: (Heap a) -> Maybe (a, Heap a) | Ord a
//viewMin :: (Heap a) -> Maybe (a, Heap a) | Ord a
/**
* @type (Heap a) -> Maybe (a, Heap a) | Ord a
*/
viewMin :== uncons
minimum :: (Heap a) -> a
......@@ -74,18 +84,39 @@ partition :: (a -> Bool) (Heap a) -> (Heap a, Heap a)
split :: a (Heap a) -> (Heap a, Heap a, Heap a)
/**
* @type Int (Heap a) -> Heap a
*/
take :== withList o 'L'.take
/**
* @type Int (Heap a) -> Heap a
*/
drop :== withList o 'L'.drop
/**
* @type Int (Heap a) -> (Heap a, Heap a)
*/
splitAt :== splitWithList o 'L'.splitAt
/**
* @type (a -> Bool) (Heap a) -> (Heap a, Heap a)
*/
break :== splitWithList o 'L'.break
/**
* @type (a -> Bool) (Heap a) -> (Heap a, Heap a)
*/
span :== splitWithList o 'L'.span
/**
* @type (a -> Bool) (Heap a) -> Heap a
*/
takeWhile :== withList o 'L'.takeWhile
/**
* @type (a -> Bool) (Heap a) -> Heap a
*/
dropWhile :== withList o 'L'.dropWhile
nub :: (Heap a) -> Heap a
......
......@@ -4,14 +4,59 @@ from Data.Functor import class Functor
from Data.Maybe import :: Maybe
import StdList, GenEq
/**
* An element in the list, or Nothing if it does not exist.
*/
(!?) infixl 9 :: ![.a] !Int -> Maybe .a
/**
* The first element of the list.
*/
head :: ![.a] -> .a
/**
* Everything except the first element of the list.
*/
tail :: !u:[.a] -> u:[.a]
/**
* Check if a list is empty.
*/
isnull :: ![.a] -> Bool
/**
* Keep a number of elements at the end of the list.
*
* @param The number of elements to retain
* @param The list
* @result A list with the (|list| - n) last elements of the original list
*/
keep :: !Int ![a] -> [a]
/**
* Unzip a list of three-tuples to a three-tuple of lists.
*/
unzip3 :: ![(.a,.b,.c)] -> ([.a],[.b],[.c])
/**
* Unzip a list of four-tuples to a four-tuple of lists.
*/
unzip4 :: ![(.a,.b,.c,.d)] -> ([.a],[.b],[.c],[.d])
/**
* Unzip a list of five-tuples to a five-tuple of lists.
*/
unzip5 :: ![(.a,.b,.c,.d,.e)] -> ([.a],[.b],[.c],[.d],[.e])
/**
* Replace elements in a list when a condition matches.
*
* @param The condition p.
* The first parameter is the replacement; the second, the old element.
* @param The replacement r
* @param The original list
* @result The original list, with all elements x for which p r x holds replaced by r
*/
replaceInList :: !(a a -> Bool) !a ![a] -> [a]
splitWith :: !(a -> Bool) ![a] -> (![a],![a])
sortByIndex :: ![(!Int,!a)] -> [a]
......
definition module Data.Map
/**
* This module provides a dynamic Map type for creating mappings from keys to values
* Internally it uses an AVL tree to organize the key-value pairs stored in the mapping
* such that lookup, insert and delete operations can be performed in O(log n).
*/
* This module provides a dynamic Map type for creating mappings from keys to values
* Internally it uses an AVL tree to organize the key-value pairs stored in the mapping
* such that lookup, insert and delete operations can be performed in O(log n).
*/
from Data.Maybe import :: Maybe (..)
from StdOverloaded import class ==, class <
......@@ -19,89 +19,65 @@ from StdOverloaded import class < (..)
import StdClass
/**
* The abstract Map type provides the mapping.
* The parameter k is the key type on which the data structure
* is indexed. The parameter v is the type of the values
* stored in the mapping. For example "Map Int String" is a mapping
* "from" integers "to" strings.
*/
//:: Map k v = MLeaf
//| MNode !(Map k v) !k !Int v !(Map k v)
:: Map k a
= Bin !Int !k !a !(Map k a) !(Map k a)
* The abstract Map type provides the mapping.
* For example "Map Int String" is a mapping "from" integers "to" strings.
*
* @var The key type on which the data structure is indexed.
* @var The type of the values stored in the mapping.
*/
:: Map k v
= Bin !Int !k !v !(Map k v) !(Map k v)
| Tip
instance Monoid (Map k v) | < k
instance == (Map k a) | == k & == a
instance == (Map k v) | == k & == v
//Basic functions
//null :: !(Map k a) -> Bool
//null :: !(Map k a) -> Bool
/**
* Check if a Map is empty.
* @type (Map k a) -> Bool
*/
null mp :== case mp of
Tip -> True
_ -> False
/**
* Create an empty Map
*
* @return An empty map
*/
* Create an empty Map.
* @return An empty map
*/
newMap :: w:(Map k u:v), [ w <= u]
singleton :: !k !a -> Map k a
/**
* Create a Map with one element.
*/
singleton :: !k !v -> Map k v
/**
* The number of elements in a Map.
*/
mapSize :: !(Map k v) -> Int
/**
* Adds or replaces the value for a given key.
*
* @param The key value to add/update
* @param The value to add/update at the key position
* @param The original mapping
* @return The modified mapping with the added value
*/
* Adds or replaces the value for a given key.
*
* @param The key value to add/update
* @param The value to add/update at the key position
* @param The original mapping
* @return The modified mapping with the added value
*/
put :: !k !a !(Map k a) -> Map k a | < k
/**
* Searches for a value at a given key position. Works only for non-unique
* mappings.
*
* @param The key to look for
* @param The orginal mapping
* @return When found, the value at the key position, if not: Nothing
*/
// | /O(log n)/. Lookup the value at a key in the map.
//
// The function will return the corresponding value as @('Just` value)@,
// or 'Nothing' if the key isn't in the map.
//
// An example of using @get@:
//
// > import Prelude hiding (get)
// > import Data.Map
// >
// > employeeDept = fromList([("John","Sales"), ("Bob","IT")])
// > deptCountry = fromList([("IT","USA"), ("Sales","France")])
// > countryCurrency = fromList([("USA", "Dollar"), ("France", "Euro")])
// >
// > employeeCurrency :: String -> Maybe String
// > employeeCurrency name = do
// > dept <- get name employeeDept
// > country <- get dept deptCountry
// > get country countryCurrency
// >
// > main = do
// > putStrLn $ "John's currency: " ++ (toString (employeeCurrency "John"))
// > putStrLn $ "Pete's currency: " ++ (toString (employeeCurrency "Pete"))
//
// The output of this program:
//
// > John's currency: Just "Euro"
// > Pete's currency: Nothing
//get :: !k !(Map k a) -> Maybe a | < k
/**
* Searches for a value at a given key position. Works only for non-unique
* mappings.
*
* @type k (Map k v) -> Maybe v | < k
* @param The key to look for
* @param The orginal mapping
* @return When found, the value at the key position, if not: Nothing
*/
get k m :== get` k m
where
get` _ Tip = Nothing
......@@ -111,7 +87,11 @@ get k m :== get` k m
(get` k r)
(Just x))
/**
* Searches for a value at a given key position. Works also for unique mappings.
*/
getU :: !k !w:(Map k v) -> x:(!Maybe v, !y:(Map k v)) | == k & < k, [ x <= y, w <= y]
/**
* Removes the value at a given key position. The mapping itself can be spine unique.
*
......@@ -121,69 +101,100 @@ getU :: !k !w:(Map k v) -> x:(!Maybe v, !y:(Map k v)) | == k & < k, [ x <= y, w
*/
del :: !k !(Map k a) -> Map k a | < k
/**
* Removes the value at a given key position. The mapping can be unique.
*/
delU :: !a !.(Map a b) -> u:(!v:(Maybe b), !Map a b) | == a & < a, [u <= v] // !k !w:(Map k u:v) -> x:(Maybe u:v, !y:(Map k u:v)) | == k & < k, [ w y <= u, x <= y, w <= y]
foldrWithKey :: !(k v u:a -> u:a) !u:a !(Map k v) -> u:a
//foldrNoKey :: !(v u:a -> u:a) !u:a !(Map k v) -> u:a
foldlWithKey :: !(u:a k v -> u:a) !u:a !(Map k v) -> u:a
//foldlNoKey :: !(a -> b -> a) !a !(Map c b) -> a
filterWithKey :: !(k a -> Bool) !(Map k a) -> Map k a
/**
* @type (v a -> a) a (Map k v) -> a
*/
foldrNoKey f x m :== foldrWithKey (\_ v acc -> f v acc) x m
/**
* @type (a v -> a) a (Map k v) -> a
*/
foldlNoKey f x m :== foldlWithKey (\acc _ v -> f acc v) x m
/**
* Filter elements in a Map.
*
* @param The predicate function.
* @param The Map.
* @return A new Map that contains exactly those pairs (k,v) from the original Map for which p k v holds.
*/
filterWithKey :: !(k v -> Bool) !(Map k v) -> Map k v
//keys :: !(Map k a) -> [k]
/**
* A list of the keys in a Map.
* @type (Map k v) -> [k]
*/
keys m :== foldrWithKey (\k _ ks -> [k : ks]) [] m
//elems :: !(Map k a) -> [a]
/**
* A list of the elements in a Map.
* @type (Map k v) -> [v]
*/
elems m :== foldrNoKey (\x xs -> [x:xs]) [] m
//Conversion functions
/**
* Converts a mapping to a list of key value pairs.
* Because of the internal ordering of the mapping the resulting
* list is sorted ascending on the key part of the tuple.
*
* @param The original mapping
* @return A list of key/value tuples in the mapping
*/
* Converts a mapping to a list of key value pairs.
* Because of the internal ordering of the mapping the resulting
* list is sorted ascending on the key part of the tuple.
*
* @type (Map k v) -> [(k,v)]
* @param The original mapping
* @return A list of key/value tuples in the mapping
*/
toList m :== toAscList m
toAscList m :== foldrWithKey (\k x xs -> [(k,x):xs]) [] m
/**
* Converts a list of key/value tuples to a mapping.
*
* @param A list of key/value tuples
* @return A mapping containing all the tuples in the list
*/
fromList :: !u:[v:(!a, !b)] -> Map a b | == a & < a, [u <= v]
/**
* Adds or replaces a list of key/value pairs.
*
* @param A list of key/value tuples
* @param The original mapping
* @return The modified mapping with the added values
*/
//putList :: !u:[v:(!a, !b)] !u:(Map a b) -> Map a b | == a & < a, [u <= v]
* Same as toList.
* @type (Map k v) -> [(k,v)]
*/
toAscList m :== foldrWithKey (\k x xs -> [(k,x):xs]) [] m
/**
* Removes the values at given key positions. The mapping itself can be spine unique.
*
* @param The list of keys to remove
* @param The original mapping
* @return The modified mapping with the values/keys removed
*/
//delList :: ![a] !.(Map a b) -> Map a b | == a & < a
* Converts a list of key/value tuples to a mapping.
*
* @param A list of key/value tuples
* @return A mapping containing all the tuples in the list
*/
fromList :: !u:[v:(!a, !b)] -> Map a b | == a & < a, [u <= v]
derive JSONEncode Map
derive JSONDecode Map
derive gEq Map
/**
* Check if a key exists in a Map.
*/
member :: !k !(Map k a) -> Bool | < k
/**
* Checks if a key is not a member of a Map.
* @type k (Map k v) -> Bool | < k
*/
notMember k m :== not (member k m)
/**
* Find an element in a Map.
* Aborts when the element is not found.
*/
find :: !k !(Map k a) -> a | < k
/**
* Find an element in a Map.
* When the key does not exist, return a default.
*
* @param The default.
* @param The key to look up.
*/
findWithDefault :: !a !k !(Map k a) -> a | < k
alter :: !((Maybe a) -> Maybe a) !k !(Map k a) -> Map k a | < k
......@@ -215,12 +226,24 @@ mergeWithKey :: !(k a b -> Maybe c) !((Map k a) -> Map k c) !((Map k b) -> Map k
foldlStrict :: !(a b -> a) !a ![b] -> a
foldrNoKey f x m :== foldrWithKey (\_ v acc -> f v acc) x m
foldlNoKey f x m :== foldlWithKey (\acc _ v -> f acc v) x m
/**
* Removes the values at given key positions. The mapping itself can be spine unique.