ixset-typed-0.5.1.0: Efficient relational queries on Haskell sets.

Safe Haskell | None
Language | Haskell2010

Data.IxSet.Typed

Contents

- Set type
  - Declaring indices
  - TH derivation of indices
- Changes to set
- Creation
- Conversion
- Size checking
- Set operations
- Indexing
- Index creation helpers
- Debugging and optimization

Description

An efficient implementation of queryable sets.

Assume you have a family of types such as:

    data Entry      = Entry Author [Author] Updated Id Content
      deriving (Show, Eq, Ord, Data, Typeable)
    newtype Updated = Updated UTCTime
      deriving (Show, Eq, Ord, Data, Typeable)
    newtype Id      = Id Int64
      deriving (Show, Eq, Ord, Data, Typeable)
    newtype Content = Content String
      deriving (Show, Eq, Ord, Data, Typeable)
    newtype Author  = Author Email
      deriving (Show, Eq, Ord, Data, Typeable)
    type Email      = String
    data Test = Test
      deriving (Show, Eq, Ord, Data, Typeable)

1. Decide what parts of your type you want indexed and make your type an instance of `Indexable`. Use `ixFun` and `ixGen` to build indices:

       type EntryIxs = '[Author, Id, Updated, Test]
       type IxEntry  = IxSet EntryIxs Entry

       instance Indexable EntryIxs Entry where
         indices = ixList
                     (ixGen (Proxy :: Proxy Author))        -- out of order
                     (ixGen (Proxy :: Proxy Id))
                     (ixGen (Proxy :: Proxy Updated))
                     (ixGen (Proxy :: Proxy Test))          -- bogus index

   The use of `ixGen` requires the `Data` and `Typeable` instances above. You can build indices manually using `ixFun`. You can also use the Template Haskell function `inferIxSet` to generate an `Indexable` instance automatically.

2. Use `insert`, `insertList`, `delete`, `updateIx`, `deleteIx` and `empty` to build up an `IxSet` collection:

       entries  = insertList [e1, e2, e3, e4] (empty :: IxEntry)
       entries1 = foldr delete entries [e1, e3]
       entries2 = updateIx (Id 4) e5 entries

3. Use the query functions below to grab data from it:

       entries @= Author "john@doe.com" @< Updated t1

   Statement above will find all items in entries updated earlier than `t1` by `john@doe.com`.

4. Text index

   If you want to do add a text index create a calculated index. Then if you want all entries with either `word1` or `word2`, you change the instance to:

       newtype Word = Word String
         deriving (Show, Eq, Ord)

       getWords (Entry _ _ _ _ (Content s)) = map Word $ words s

       type EntryIxs = '[..., Word]
       instance Indexable EntryIxs Entry where
           indices = ixList
                       ...
                       (ixFun getWords)

   Now you can do this query to find entries with any of the words:

       entries @+ [Word "word1", Word "word2"]

   And if you want all entries with both:

       entries @* [Word "word1", Word "word2"]

5. Find only the first author

   If an `Entry` has multiple authors and you want to be able to query on the first author only, define a `FirstAuthor` datatype and create an index with this type. Now you can do:

       newtype FirstAuthor = FirstAuthor Email
         deriving (Show, Eq, Ord)

       getFirstAuthor (Entry author _ _ _ _) = [FirstAuthor author]

       type EntryIxs = '[..., FirstAuthor]
       instance Indexable EntryIxs Entry where
           indices = ixList
                       ...
                       (ixFun getFirstAuthor)

       entries @= (FirstAuthor "john@doe.com")  -- guess what this does

Synopsis

- data IxSet (ixs :: [Type]) a
- data IxList (ixs :: [Type]) a
- class (All Ord ixs, Ord a) => Indexable (ixs :: [Type]) a where
  - indices :: IxList ixs a
- class Ord ix => IsIndexOf ix (ixs :: [Type])
- type family All (c :: Type -> Constraint) (xs :: [Type])
- data Ix ix a
- ixList :: forall (ixs :: [Type]) a r. MkIxList ixs ixs a r => r
- class MkIxList (ixs :: [Type]) (ixs' :: [Type]) a r | r -> a ixs ixs'
- ixFun :: Ord ix => (a -> [ix]) -> Ix ix a
- ixGen :: forall proxy a ix. (Ord ix, Data a, Typeable ix) => proxy ix -> Ix ix a
- noCalcs :: t -> ()
- inferIxSet :: String -> Name -> Name -> [Name] -> Q [Dec]
- type IndexOp = forall k a. (Ord k, Ord a) => k -> a -> Map k (Set a) -> Map k (Set a)
- type SetOp = forall a. Ord a => a -> Set a -> Set a
- change :: forall (ixs :: [Type]) a. Indexable ixs a => SetOp -> IndexOp -> a -> IxSet ixs a -> IxSet ixs a
- insert :: forall (ixs :: [Type]) a. Indexable ixs a => a -> IxSet ixs a -> IxSet ixs a
- insertList :: forall (ixs :: [Type]) a. Indexable ixs a => [a] -> IxSet ixs a -> IxSet ixs a
- delete :: forall (ixs :: [Type]) a. Indexable ixs a => a -> IxSet ixs a -> IxSet ixs a
- updateIx :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> a -> IxSet ixs a -> IxSet ixs a
- deleteIx :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a
- empty :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a
- fromSet :: forall (ixs :: [Type]) a. Indexable ixs a => Set a -> IxSet ixs a
- fromList :: forall (ixs :: [Type]) a. Indexable ixs a => [a] -> IxSet ixs a
- toSet :: forall (ixs :: [Type]) a. IxSet ixs a -> Set a
- toList :: forall (ixs :: [Type]) a. IxSet ixs a -> [a]
- toAscList :: forall proxy ix (ixs :: [Type]) a. IsIndexOf ix ixs => proxy ix -> IxSet ixs a -> [a]
- toDescList :: forall proxy ix (ixs :: [Type]) a. IsIndexOf ix ixs => proxy ix -> IxSet ixs a -> [a]
- getOne :: forall a (ixs :: [Type]). Ord a => IxSet ixs a -> Maybe a
- getOneOr :: forall a (ixs :: [Type]). Ord a => a -> IxSet ixs a -> a
- size :: forall (ixs :: [Type]) a. IxSet ixs a -> Int
- null :: forall (ixs :: [Type]) a. IxSet ixs a -> Bool
- (&&&) :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a -> IxSet ixs a -> IxSet ixs a
- (|||) :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a -> IxSet ixs a -> IxSet ixs a
- union :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a -> IxSet ixs a -> IxSet ixs a
- intersection :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a -> IxSet ixs a -> IxSet ixs a
- (@=) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> ix -> IxSet ixs a
- (@<) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> ix -> IxSet ixs a
- (@>) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> ix -> IxSet ixs a
- (@<=) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> ix -> IxSet ixs a
- (@>=) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> ix -> IxSet ixs a
- (@><) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> (ix, ix) -> IxSet ixs a
- (@>=<) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> (ix, ix) -> IxSet ixs a
- (@><=) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> (ix, ix) -> IxSet ixs a
- (@>=<=) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> (ix, ix) -> IxSet ixs a
- (@+) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> [ix] -> IxSet ixs a
- (@*) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> [ix] -> IxSet ixs a
- getEQ :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a
- getLT :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a
- getGT :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a
- getLTE :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a
- getGTE :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a
- getRange :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> ix -> IxSet ixs a -> IxSet ixs a
- groupBy :: forall ix (ixs :: [Type]) a. IsIndexOf ix ixs => IxSet ixs a -> [(ix, [a])]
- groupAscBy :: forall ix (ixs :: [Type]) a. IsIndexOf ix ixs => IxSet ixs a -> [(ix, [a])]
- groupDescBy :: forall ix (ixs :: [Type]) a. IsIndexOf ix ixs => IxSet ixs a -> [(ix, [a])]
- indexKeys :: forall ix (ixs :: [Type]) a. IsIndexOf ix ixs => IxSet ixs a -> [ix]
- flatten :: (Typeable a, Data a, Typeable b) => a -> [b]
- flattenWithCalcs :: (Data c, Typeable a, Data a, Typeable b) => (a -> c) -> a -> [b]
- stats :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a -> (Int, Int, Int, Int)

# Set type

data IxSet (ixs :: [Type]) a Source #

Set with associated indices.

The type-level list `ixs` contains all types that are valid index keys. The type `a` is the type of elements in the indexed set.

On strictness: An `IxSet` is "mostly" spine-strict. It is generally spine-strict in the set itself. All operations on `IxSet` with the exception of queries are spine-strict in the indices as well. Query operations, however, are lazy in the indices, so querying a number of times and subsequently selecting the result will not unnecessarily rebuild all indices.

#### Instances

Instances details

Foldable (IxSet ixs) Source # |

Instance details

Defined in Data.IxSet.Typed

Methods

fold :: Monoid m => IxSet ixs m -> m Source #

foldMap :: Monoid m => (a -> m) -> IxSet ixs a -> m Source #

foldMap' :: Monoid m => (a -> m) -> IxSet ixs a -> m Source #

foldr :: (a -> b -> b) -> b -> IxSet ixs a -> b Source #

foldr' :: (a -> b -> b) -> b -> IxSet ixs a -> b Source #

foldl :: (b -> a -> b) -> b -> IxSet ixs a -> b Source #

foldl' :: (b -> a -> b) -> b -> IxSet ixs a -> b Source #

foldr1 :: (a -> a -> a) -> IxSet ixs a -> a Source #

foldl1 :: (a -> a -> a) -> IxSet ixs a -> a Source #

toList :: IxSet ixs a -> [a] Source #

null :: IxSet ixs a -> Bool Source #

length :: IxSet ixs a -> Int Source #

elem :: Eq a => a -> IxSet ixs a -> Bool Source #

maximum :: Ord a => IxSet ixs a -> a Source #

minimum :: Ord a => IxSet ixs a -> a Source #

sum :: Num a => IxSet ixs a -> a Source #

product :: Num a => IxSet ixs a -> a Source #

(All NFData ixs, NFData a) => NFData (IxSet ixs a) Source # |
Instance details Defined in Data.IxSet.Typed Methods rnf :: IxSet ixs a -> () Source #
Indexable ixs a => Monoid (IxSet ixs a) Source # |
Instance details Defined in Data.IxSet.Typed Methods mempty :: IxSet ixs a Source # mappend :: IxSet ixs a -> IxSet ixs a -> IxSet ixs a Source # mconcat :: [IxSet ixs a] -> IxSet ixs a Source #
Indexable ixs a => Semigroup (IxSet ixs a) Source # |
Instance details Defined in Data.IxSet.Typed Methods (<>) :: IxSet ixs a -> IxSet ixs a -> IxSet ixs a Source # sconcat :: NonEmpty (IxSet ixs a) -> IxSet ixs a Source # stimes :: Integral b => b -> IxSet ixs a -> IxSet ixs a Source #
(Indexable ixs a, Read a) => Read (IxSet ixs a) Source # |
Instance details Defined in Data.IxSet.Typed Methods readsPrec :: Int -> ReadS (IxSet ixs a) Source # readList :: ReadS [IxSet ixs a] Source # readPrec :: ReadPrec (IxSet ixs a) Source # readListPrec :: ReadPrec [IxSet ixs a] Source #
(Indexable ixs a, Show a) => Show (IxSet ixs a) Source # |
Instance details Defined in Data.IxSet.Typed Methods showsPrec :: Int -> IxSet ixs a -> ShowS Source # show :: IxSet ixs a -> String Source # showList :: [IxSet ixs a] -> ShowS Source #
Indexable ixs a => Eq (IxSet ixs a) Source # |
Instance details Defined in Data.IxSet.Typed Methods (==) :: IxSet ixs a -> IxSet ixs a -> Bool Source # (/=) :: IxSet ixs a -> IxSet ixs a -> Bool Source #
Indexable ixs a => Ord (IxSet ixs a) Source # |

Instance details

Defined in Data.IxSet.Typed

Methods

compare :: IxSet ixs a -> IxSet ixs a -> Ordering Source #

(<) :: IxSet ixs a -> IxSet ixs a -> Bool Source #

(<=) :: IxSet ixs a -> IxSet ixs a -> Bool Source #

(>) :: IxSet ixs a -> IxSet ixs a -> Bool Source #

(>=) :: IxSet ixs a -> IxSet ixs a -> Bool Source #

max :: IxSet ixs a -> IxSet ixs a -> IxSet ixs a Source #

min :: IxSet ixs a -> IxSet ixs a -> IxSet ixs a Source #

(Indexable ixs a, Typeable ixs, SafeCopy a, Typeable a) => SafeCopy (IxSet ixs a) Source # |
Instance details Defined in Data.IxSet.Typed Methods version :: Version (IxSet ixs a) Source # kind :: Kind (IxSet ixs a) Source # getCopy :: Contained (Get (IxSet ixs a)) Source # putCopy :: IxSet ixs a -> Contained Put Source # internalConsistency :: Consistency (IxSet ixs a) Source # objectProfile :: Profile (IxSet ixs a) Source # errorTypeName :: Proxy (IxSet ixs a) -> String Source #

data IxList (ixs :: [Type]) a Source #

#### Instances

Instances details

MkIxList ('[] :: [Type]) ixs a (IxList ixs a) Source # |
Instance details Defined in Data.IxSet.Typed Methods ixList' :: (IxList ('[] :: [Type]) a -> IxList ixs a) -> IxList ixs a
(All NFData ixs, NFData a) => NFData (IxList ixs a) Source # |
Instance details Defined in Data.IxSet.Typed Methods rnf :: IxList ixs a -> () Source #

class (All Ord ixs, Ord a) => Indexable (ixs :: [Type]) a where Source #

Associate indices with a given type. The constraint ``Indexable` ixs a` says that we know how to build index sets of type ``IxSet` ixs a`.

In order to use an `IxSet` on a particular type, you have to make it an instance of `Indexable` yourself. There are no predefined instances of `IxSet`.

Methods

indices :: IxList ixs a Source #

Define how the indices for this particular type should look like.

Use the `ixList` function to construct the list of indices, and use `ixFun` (or `ixGen`) for individual indices.

class Ord ix => IsIndexOf ix (ixs :: [Type]) Source #

Constraint for membership in the type-level list. Says that `ix` is contained in the index list `ixs`.

Minimal complete definition

access, mapAt

#### Instances

Instances details

Ord ix => IsIndexOf ix (ix ': ixs) Source # |
Instance details Defined in Data.IxSet.Typed Methods access :: IxList (ix ': ixs) a -> Ix ix a mapAt :: All Ord (ix ': ixs) => (Ix ix a -> Ix ix a) -> (forall ix'. Ord ix' => Ix ix' a -> Ix ix' a) -> IxList (ix ': ixs) a -> IxList (ix ': ixs) a
IsIndexOf ix ixs => IsIndexOf ix (ix' ': ixs) Source # |
Instance details Defined in Data.IxSet.Typed Methods access :: IxList (ix' ': ixs) a -> Ix ix a mapAt :: All Ord (ix' ': ixs) => (Ix ix a -> Ix ix a) -> (forall ix'0. Ord ix'0 => Ix ix'0 a -> Ix ix'0 a) -> IxList (ix' ': ixs) a -> IxList (ix' ': ixs) a

type family All (c :: Type -> Constraint) (xs :: [Type]) Source #

The constraint `All c xs` says the `c` has to hold for all elements in the type-level list `xs`.

Example:

    All Ord '[Int, Char, Bool]

is equivalent to

    (Ord Int, Ord Char, Ord Bool)

#### Instances

Instances details

type All c ('[] :: [Type]) Source # |
Instance details Defined in Data.IxSet.Typed type All c ('[] :: [Type]) = ()
type All c (x ': xs) Source # |
Instance details Defined in Data.IxSet.Typed type All c (x ': xs) = (c x, All c xs)

## Declaring indices

data Ix ix a Source #

`Ix` is a `Map` from some key (of type `ix`) to a `Set` of values (of type `a`) for that key.

#### Instances

Instances details

(NFData ix, NFData a) => NFData (Ix ix a) Source # |
Instance details Defined in Data.IxSet.Typed.Ix Methods rnf :: Ix ix a -> () Source #
MkIxList ixs ixs' a r => MkIxList (ix ': ixs) ixs' a (Ix ix a -> r) Source # |
Instance details Defined in Data.IxSet.Typed Methods ixList' :: (IxList (ix ': ixs) a -> IxList ixs' a) -> Ix ix a -> r

ixList :: forall (ixs :: [Type]) a r. MkIxList ixs ixs a r => r Source #

Create an (empty) `IxList` from a number of indices. Useful in the `Indexable` `indices` method. Use `ixFun` and `ixGen` for the individual indices.

Note that this function takes a variable number of arguments. Here are some example types at which the function can be used:

    ixList :: Ix ix1 a -> IxList '[ix1] a
    ixList :: Ix ix1 a -> Ix ix2 a -> IxList '[ix1, ix2] a
    ixList :: Ix ix1 a -> Ix ix2 a -> Ix ix3 a -> IxList '[ix1, ix2, ix3] a
    ixList :: ...

Concrete example use:

    instance Indexable '[..., Index1Type, Index2Type] Type where
        indices = ixList
                    ...
                    (ixFun getIndex1)
                    (ixGen (Proxy :: Proxy Index2Type))

class MkIxList (ixs :: [Type]) (ixs' :: [Type]) a r | r -> a ixs ixs' Source #

Class that allows a variable number of arguments to be passed to the `ixSet` and `mkEmpty` functions. See the documentation of these functions for more information.

Minimal complete definition

ixList'

#### Instances

Instances details

MkIxList ('[] :: [Type]) ixs a (IxList ixs a) Source # |
Instance details Defined in Data.IxSet.Typed Methods ixList' :: (IxList ('[] :: [Type]) a -> IxList ixs a) -> IxList ixs a
MkIxList ixs ixs' a r => MkIxList (ix ': ixs) ixs' a (Ix ix a -> r) Source # |
Instance details Defined in Data.IxSet.Typed Methods ixList' :: (IxList (ix ': ixs) a -> IxList ixs' a) -> Ix ix a -> r

ixFun :: Ord ix => (a -> [ix]) -> Ix ix a Source #

Create a functional index. Provided function should return a list of indices where the value should be found.

    getIndices :: Type -> [IndexType]
    getIndices value = [...indices...]

    instance Indexable '[IndexType] Type where
        indices = ixList (ixFun getIndices)

This is the recommended way to create indices.

ixGen :: forall proxy a ix. (Ord ix, Data a, Typeable ix) => proxy ix -> Ix ix a Source #

Create a generic index. Provided example is used only as type source so you may use a `Proxy`. This uses flatten to traverse values using their `Data` instances.

    instance Indexable '[IndexType] Type where
        indices = ixList (ixGen (Proxy :: Proxy Type))

In production systems consider using `ixFun` in place of `ixGen` as the former one is much faster.

## TH derivation of indices

noCalcs :: t -> () Source #

Function to be used as third argument in `inferIxSet` when you don't want any calculated values.

inferIxSet :: String -> Name -> Name -> [Name] -> Q [Dec] Source #

Template Haskell helper function for automatically building an `Indexable` instance from a data type, e.g.

    data Foo = Foo Int String
      deriving (Eq, Ord, Data, Typeable)

and

    inferIxSet "FooDB" ''Foo 'noCalcs [''Int, ''String]

will define:

    type FooDB = IxSet '[Int, String] Foo
    instance Indexable '[Int, String] Foo where
      ...

with `Int` and `String` as indices defined via

      ixFun (flattenWithCalcs noCalcs)

each.

WARNING: This function uses `flattenWithCalcs` for index generation, which in turn uses an SYB type-based traversal. It is often more efficient (and sometimes more correct) to explicitly define the indices using `ixFun`.

# Changes to set

type IndexOp = forall k a. (Ord k, Ord a) => k -> a -> Map k (Set a) -> Map k (Set a) Source #

type SetOp = forall a. Ord a => a -> Set a -> Set a Source #

change :: forall (ixs :: [Type]) a. Indexable ixs a => SetOp -> IndexOp -> a -> IxSet ixs a -> IxSet ixs a Source #

Higher order operator for modifying `IxSet`s. Use this when your final function should have the form `a -> `IxSet` a -> `IxSet` a`, e.g. `insert` or `delete`.

insert :: forall (ixs :: [Type]) a. Indexable ixs a => a -> IxSet ixs a -> IxSet ixs a Source #

Inserts an item into the `IxSet`. If your data happens to have a primary key this function might not be what you want. See `updateIx`.

insertList :: forall (ixs :: [Type]) a. Indexable ixs a => [a] -> IxSet ixs a -> IxSet ixs a Source #

delete :: forall (ixs :: [Type]) a. Indexable ixs a => a -> IxSet ixs a -> IxSet ixs a Source #

Removes an item from the `IxSet`.

updateIx :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> a -> IxSet ixs a -> IxSet ixs a Source #

Will replace the item with the given index of type `ix`. Only works if there is at most one item with that index in the `IxSet`. Will not change `IxSet` if you have more than one item with given index.

deleteIx :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a Source #

Will delete the item with the given index of type `ix`. Only works if there is at most one item with that index in the `IxSet`. Will not change `IxSet` if you have more than one item with given index.

# Creation

empty :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a Source #

An empty `IxSet`.

fromSet :: forall (ixs :: [Type]) a. Indexable ixs a => Set a -> IxSet ixs a Source #

Converts a `Set` to an `IxSet`.

fromList :: forall (ixs :: [Type]) a. Indexable ixs a => [a] -> IxSet ixs a Source #

Converts a list to an `IxSet`.

# Conversion

toSet :: forall (ixs :: [Type]) a. IxSet ixs a -> Set a Source #

Converts an `IxSet` to a `Set` of its elements.

toList :: forall (ixs :: [Type]) a. IxSet ixs a -> [a] Source #

Converts an `IxSet` to its list of elements.

toAscList :: forall proxy ix (ixs :: [Type]) a. IsIndexOf ix ixs => proxy ix -> IxSet ixs a -> [a] Source #

Converts an `IxSet` to its list of elements.

List will be sorted in ascending order by the index `ix`.

The list may contain duplicate entries if a single value produces multiple keys.

toDescList :: forall proxy ix (ixs :: [Type]) a. IsIndexOf ix ixs => proxy ix -> IxSet ixs a -> [a] Source #

Converts an `IxSet` to its list of elements.

List will be sorted in descending order by the index `ix`.

The list may contain duplicate entries if a single value produces multiple keys.

getOne :: forall a (ixs :: [Type]). Ord a => IxSet ixs a -> Maybe a Source #

If the `IxSet` is a singleton it will return the one item stored in it. If `IxSet` is empty or has many elements this function returns `Nothing`.

getOneOr :: forall a (ixs :: [Type]). Ord a => a -> IxSet ixs a -> a Source #

Like `getOne` with a user-provided default.

# Size checking

size :: forall (ixs :: [Type]) a. IxSet ixs a -> Int Source #

Returns the number of unique items in the `IxSet`.

null :: forall (ixs :: [Type]) a. IxSet ixs a -> Bool Source #

Return `True` if the `IxSet` is empty, `False` otherwise.

# Set operations

(&&&) :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a -> IxSet ixs a -> IxSet ixs a infixr 5 Source #

An infix `intersection` operation.

(|||) :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a -> IxSet ixs a -> IxSet ixs a infixr 5 Source #

An infix `union` operation.

union :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a -> IxSet ixs a -> IxSet ixs a Source #

Takes the union of the two `IxSet`s.

intersection :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a -> IxSet ixs a -> IxSet ixs a Source #

Takes the intersection of the two `IxSet`s.

# Indexing

(@=) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> ix -> IxSet ixs a Source #

Infix version of `getEQ`.

(@<) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> ix -> IxSet ixs a Source #

Infix version of `getLT`.

(@>) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> ix -> IxSet ixs a Source #

Infix version of `getGT`.

(@<=) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> ix -> IxSet ixs a Source #

Infix version of `getLTE`.

(@>=) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> ix -> IxSet ixs a Source #

Infix version of `getGTE`.

(@><) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> (ix, ix) -> IxSet ixs a Source #

Returns the subset with indices in the open interval (k,k).

(@>=<) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> (ix, ix) -> IxSet ixs a Source #

Returns the subset with indices in [k,k).

(@><=) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> (ix, ix) -> IxSet ixs a Source #

Returns the subset with indices in (k,k].

(@>=<=) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> (ix, ix) -> IxSet ixs a Source #

Returns the subset with indices in [k,k].

(@+) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> [ix] -> IxSet ixs a Source #

Creates the subset that has an index in the provided list.

(@*) :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => IxSet ixs a -> [ix] -> IxSet ixs a Source #

Creates the subset that matches all the provided indices.

getEQ :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a Source #

Returns the subset with an index equal to the provided key. The set must be indexed over key type, doing otherwise results in runtime error.

getLT :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a Source #

Returns the subset with an index less than the provided key. The set must be indexed over key type, doing otherwise results in runtime error.

getGT :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a Source #

Returns the subset with an index greater than the provided key. The set must be indexed over key type, doing otherwise results in runtime error.

getLTE :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a Source #

Returns the subset with an index less than or equal to the provided key. The set must be indexed over key type, doing otherwise results in runtime error.

getGTE :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> IxSet ixs a -> IxSet ixs a Source #

Returns the subset with an index greater than or equal to the provided key. The set must be indexed over key type, doing otherwise results in runtime error.

getRange :: forall (ixs :: [Type]) a ix. (Indexable ixs a, IsIndexOf ix ixs) => ix -> ix -> IxSet ixs a -> IxSet ixs a Source #

Returns the subset with an index within the interval provided. The bottom of the interval is closed and the top is open, i. e. [k1;k2). The set must be indexed over key type, doing otherwise results in runtime error.

groupBy :: forall ix (ixs :: [Type]) a. IsIndexOf ix ixs => IxSet ixs a -> [(ix, [a])] Source #

Returns lists of elements paired with the indices determined by type inference.

groupAscBy :: forall ix (ixs :: [Type]) a. IsIndexOf ix ixs => IxSet ixs a -> [(ix, [a])] Source #

Returns lists of elements paired with the indices determined by type inference.

The resulting list will be sorted in ascending order by `ix`. The values in `[a]` will be sorted in ascending order as well.

groupDescBy :: forall ix (ixs :: [Type]) a. IsIndexOf ix ixs => IxSet ixs a -> [(ix, [a])] Source #

Returns lists of elements paired with the indices determined by type inference.

The resulting list will be sorted in descending order by `ix`.

NOTE: The values in `[a]` are currently sorted in ascending order. But this may change if someone bothers to add `toDescList`. So do not rely on the sort order of the resulting list.

indexKeys :: forall ix (ixs :: [Type]) a. IsIndexOf ix ixs => IxSet ixs a -> [ix] Source #

Returns the list of index keys being used for a particular index.

# Index creation helpers

flatten :: (Typeable a, Data a, Typeable b) => a -> [b] Source #

Generically traverses the argument to find all occurences of values of type `b` and returns them as a list.

This function properly handles `String` as `String` not as `[`Char`]`.

flattenWithCalcs :: (Data c, Typeable a, Data a, Typeable b) => (a -> c) -> a -> [b] Source #

Generically traverses the argument and calculated values to find all occurences of values of type `b` and returns them as a list. Equivalent to:

    flatten (x,calcs x)

This function properly handles `String` as `String` not as `[`Char`]`.

# Debugging and optimization

stats :: forall (ixs :: [Type]) a. Indexable ixs a => IxSet ixs a -> (Int, Int, Int, Int) Source #

Statistics about `IxSet`. This function returns quadruple consisting of

1. total number of elements in the set
2. number of declared indices
3. number of keys in all indices
4. number of values in all keys in all indices.

This can aid you in debugging and optimisation.