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.

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.

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

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)

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

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 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.

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.

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.

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

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.

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

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.

Removes an item from the IxSet.

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.

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.

An empty IxSet.

Converts a Set to an IxSet.

Converts a list to an IxSet.

Converts an IxSet to a Set of its elements.

Converts an IxSet to its list of elements.

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.

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.

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.

Like getOne with a user-provided default.

Returns the number of unique items in the IxSet.

Return True if the IxSet is empty, False otherwise.

An infix intersection operation.

An infix union operation.

Takes the union of the two IxSets.

Takes the intersection of the two IxSets.

Infix version of getEQ.

Infix version of getLT.

Infix version of getGT.

Infix version of getLTE.

Infix version of getGTE.

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

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

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

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

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

Creates the subset that matches all the provided indices.

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.

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.

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.

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.

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.

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.

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

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.

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.

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].

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].

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.