data-interval-2.0.1: Interval datatype, interval arithmetic and interval-based containers

Copyright (c) Masahiro Sakai 2016 BSD-style masahiro.sakai@gmail.com provisional non-portable (BangPatterns, TupleSections) Safe Haskell2010

Data.IntervalMap.Strict

Description

Mapping from intervals to values.

API of this module is strict in both the keys and the values. If you need value-lazy maps, use Data.IntervalMap.Lazy instead. The IntervalMap type itself is shared between the lazy and strict modules, meaning that the same IntervalMap value can be passed to functions in both modules (although that is rarely needed).

These modules are intended to be imported qualified, to avoid name clashes with Prelude functions, e.g.

 import Data.IntervalMap.Strict (IntervalMap)
import qualified Data.IntervalMap.Strict as IntervalMap
Synopsis

Strictness properties

This module satisfies the following strictness properties:

1. Key arguments are evaluated to WHNF;
2. Keys and values are evaluated to WHNF before they are stored in the map.

Here's an example illustrating the first property:

delete undefined m  ==  undefined

Here are some examples that illustrate the second property:

map (\ v -> undefined) m  ==  undefined      -- m is not empty
mapKeysMonotonic (\ k -> undefined) m  ==  undefined  -- m is not empty

IntervalMap type

data IntervalMap r a Source #

A Map from non-empty, disjoint intervals over k to values a.

Unlike IntervalSet, IntervalMap never merge adjacent mappings, even if adjacent intervals are connected and mapped to the same value.

Instances

Operators

(!) :: Ord k => IntervalMap k a -> k -> a infixl 9 Source #

Find the value at a key. Calls error when the element can not be found.

(\\) :: Ord k => IntervalMap k a -> IntervalMap k b -> IntervalMap k a infixl 9 Source #

Same as difference.

Query

null :: Ord k => IntervalMap k a -> Bool Source #

Is the map empty?

member :: Ord k => k -> IntervalMap k a -> Bool Source #

Is the key a member of the map? See also notMember.

notMember :: Ord k => k -> IntervalMap k a -> Bool Source #

Is the key not a member of the map? See also member.

lookup :: Ord k => k -> IntervalMap k a -> Maybe a Source #

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.

findWithDefault :: Ord k => a -> k -> IntervalMap k a -> a Source #

The expression (findWithDefault def k map) returns the value at key k or returns default value def when the key is not in the map.

span :: Ord k => IntervalMap k a -> Interval k Source #

convex hull of key intervals.

Construction

whole :: Ord k => a -> IntervalMap k a Source #

The map that maps whole range of k to a.

empty :: Ord k => IntervalMap k a Source #

The empty map.

singleton :: Ord k => Interval k -> a -> IntervalMap k a Source #

A map with a single interval.

Insertion

insert :: Ord k => Interval k -> a -> IntervalMap k a -> IntervalMap k a Source #

insert a new key and value in the map. If the key is already present in the map, the associated value is replaced with the supplied value.

insertWith :: Ord k => (a -> a -> a) -> Interval k -> a -> IntervalMap k a -> IntervalMap k a Source #

Insert with a function, combining new value and old value. insertWith f key value mp will insert the pair (interval, value) into mp. If the interval overlaps with existing entries, the value for the entry is replace with (f new_value old_value).

Delete/Update

delete :: Ord k => Interval k -> IntervalMap k a -> IntervalMap k a Source #

Delete an interval and its value from the map. When the interval does not overlap with the map, the original map is returned.

adjust :: Ord k => (a -> a) -> Interval k -> IntervalMap k a -> IntervalMap k a Source #

Update a value at a specific interval with the result of the provided function. When the interval does not overlatp with the map, the original map is returned.

update :: Ord k => (a -> Maybe a) -> Interval k -> IntervalMap k a -> IntervalMap k a Source #

The expression (update f i map) updates the value x at i (if it is in the map). If (f x) is Nothing, the element is deleted. If it is (Just y), the key i is bound to the new value y.

alter :: Ord k => (Maybe a -> Maybe a) -> Interval k -> IntervalMap k a -> IntervalMap k a Source #

The expression (alter f i map) alters the value x at i, or absence thereof. alter can be used to insert, delete, or update a value in a IntervalMap.

Combine

union :: Ord k => IntervalMap k a -> IntervalMap k a -> IntervalMap k a Source #

The expression (union t1 t2) takes the left-biased union of t1 and t2. It prefers t1 when overlapping keys are encountered,

unionWith :: Ord k => (a -> a -> a) -> IntervalMap k a -> IntervalMap k a -> IntervalMap k a Source #

Union with a combining function.

unions :: Ord k => [IntervalMap k a] -> IntervalMap k a Source #

The union of a list of maps: (unions == foldl union empty).

unionsWith :: Ord k => (a -> a -> a) -> [IntervalMap k a] -> IntervalMap k a Source #

The union of a list of maps, with a combining operation: (unionsWith f == foldl (unionWith f) empty).

intersection :: Ord k => IntervalMap k a -> IntervalMap k a -> IntervalMap k a Source #

Intersection of two maps. Return data in the first map for the keys existing in both maps.

intersectionWith :: Ord k => (a -> b -> c) -> IntervalMap k a -> IntervalMap k b -> IntervalMap k c Source #

Intersection with a combining function.

difference :: Ord k => IntervalMap k a -> IntervalMap k b -> IntervalMap k a Source #

Return elements of the first map not existing in the second map.

Traversal

map :: (a -> b) -> IntervalMap k a -> IntervalMap k b Source #

Map a function over all values in the map.

mapKeysMonotonic :: forall k1 k2 a. (Ord k1, Ord k2) => (k1 -> k2) -> IntervalMap k1 a -> IntervalMap k2 a Source #

mapKeysMonotonic f s is the map obtained by applying f to each key of s. f must be strictly monotonic. That is, for any values x and y, if x < y then f x < f y.

Conversion

elems :: IntervalMap k a -> [a] Source #

Return all elements of the map in the ascending order of their keys.

keys :: IntervalMap k a -> [Interval k] Source #

Return all keys of the map in ascending order. Subject to list

assocs :: IntervalMap k a -> [(Interval k, a)] Source #

An alias for toAscList. Return all key/value pairs in the map in ascending key order.

keysSet :: Ord k => IntervalMap k a -> IntervalSet k Source #

The set of all keys of the map.

List

fromList :: Ord k => [(Interval k, a)] -> IntervalMap k a Source #

Build a map from a list of key/value pairs. If the list contains more than one value for the same key, the last value for the key is retained.

fromListWith :: Ord k => (a -> a -> a) -> [(Interval k, a)] -> IntervalMap k a Source #

Build a map from a list of key/value pairs with a combining function.

toList :: IntervalMap k a -> [(Interval k, a)] Source #

Convert the map to a list of key/value pairs.

Ordered List

toAscList :: IntervalMap k a -> [(Interval k, a)] Source #

Convert the map to a list of key/value pairs where the keys are in ascending order.

toDescList :: IntervalMap k a -> [(Interval k, a)] Source #

Convert the map to a list of key/value pairs where the keys are in descending order.

Filter

filter :: Ord k => (a -> Bool) -> IntervalMap k a -> IntervalMap k a Source #

Filter all values that satisfy some predicate.

split :: Ord k => Interval k -> IntervalMap k a -> (IntervalMap k a, IntervalMap k a, IntervalMap k a) Source #

The expression (split i map) is a triple (map1,map2,map3) where the keys in map1 are smaller than i, the keys in map2 are included in i, and the keys in map3 are larger than i.

Submap

isSubmapOf :: (Ord k, Eq a) => IntervalMap k a -> IntervalMap k a -> Bool Source #

This function is defined as (isSubmapOf = isSubmapOfBy (==)).

isSubmapOfBy :: Ord k => (a -> b -> Bool) -> IntervalMap k a -> IntervalMap k b -> Bool Source #

The expression (isSubmapOfBy f t1 t2) returns True if all keys in t1 are in tree t2, and when f returns True when applied to their respective values.

isProperSubmapOf :: (Ord k, Eq a) => IntervalMap k a -> IntervalMap k a -> Bool Source #

Is this a proper submap? (ie. a submap but not equal). Defined as (isProperSubmapOf = isProperSubmapOfBy (==)).

isProperSubmapOfBy :: Ord k => (a -> b -> Bool) -> IntervalMap k a -> IntervalMap k b -> Bool Source #

Is this a proper submap? (ie. a submap but not equal). The expression (isProperSubmapOfBy f m1 m2) returns True when m1 and m2 are not equal, all keys in m1 are in m2, and when f returns True when applied to their respective values.