Copyright | (c) Artem Chirkin |
---|---|

License | BSD3 |

Safe Haskell | None |

Language | Haskell2010 |

Mutable DataFrames living in IO.

## Synopsis

- data IODataFrame (t :: Type) (ns :: [k]) where
- pattern XIOFrame :: forall (t :: Type) (xns :: [XNat]). () => forall (ns :: [Nat]). (FixedDims xns ns, Dimensions ns) => IODataFrame t ns -> IODataFrame t xns

- data SomeIODataFrame (t :: Type) = forall (ns :: [Nat]).Dimensions ns => SomeIODataFrame (IODataFrame t ns)
- castDataFrame :: forall (t :: Type) (xns :: [XNat]) (ns :: [Nat]). FixedDims xns ns => IODataFrame t ns -> IODataFrame t xns
- newDataFrame :: forall (t :: Type) ns. (PrimBytes t, Dimensions ns) => IO (IODataFrame t ns)
- newPinnedDataFrame :: forall (t :: Type) ns. (PrimBytes t, Dimensions ns) => IO (IODataFrame t ns)
- oneMoreDataFrame :: forall (t :: Type) ns. IODataFrame t ns -> IO (IODataFrame t ns)
- subDataFrameView :: forall (t :: Type) b bi bd as bs asbs. (SubFrameIndexCtx b bi bd, KnownDim bd, ConcatList as (b :+ bs) asbs) => Idxs (as +: bi) -> IODataFrame t asbs -> IODataFrame t (bd :+ bs)
- subDataFrameView' :: forall (t :: Type) as bs asbs. ConcatList as bs asbs => Idxs as -> IODataFrame t asbs -> IODataFrame t bs
- copyDataFrame :: forall (t :: Type) b bi bd as bs asbs. (SubFrameIndexCtx b bi bd, KnownDim bd, ExactDims bs, PrimArray t (DataFrame t (bd :+ bs)), ConcatList as (b :+ bs) asbs) => Idxs (as +: bi) -> DataFrame t (bd :+ bs) -> IODataFrame t asbs -> IO ()
- copyMutableDataFrame :: forall (t :: Type) b bi bd as bs asbs. (SubFrameIndexCtx b bi bd, ExactDims bs, PrimBytes t, ConcatList as (b :+ bs) asbs) => Idxs (as +: bi) -> IODataFrame t (bd :+ bs) -> IODataFrame t asbs -> IO ()
- copyDataFrame' :: forall (t :: Type) as bs asbs. (ExactDims bs, PrimArray t (DataFrame t bs), ConcatList as bs asbs) => Idxs as -> DataFrame t bs -> IODataFrame t asbs -> IO ()
- copyMutableDataFrame' :: forall (t :: Type) as bs asbs. (ExactDims bs, PrimBytes t, ConcatList as bs asbs) => Idxs as -> IODataFrame t bs -> IODataFrame t asbs -> IO ()
- copyDataFrameOff :: forall (t :: Type) as bs asbs. (Dimensions bs, PrimArray t (DataFrame t bs), ConcatList as bs asbs) => Int -> DataFrame t bs -> IODataFrame t asbs -> IO ()
- copyMutableDataFrameOff :: forall (t :: Type) as bs asbs. (ExactDims bs, PrimBytes t, ConcatList as bs asbs) => Int -> IODataFrame t bs -> IODataFrame t asbs -> IO ()
- freezeDataFrame :: forall (t :: Type) ns. PrimArray t (DataFrame t ns) => IODataFrame t ns -> IO (DataFrame t ns)
- unsafeFreezeDataFrame :: forall (t :: Type) ns. PrimArray t (DataFrame t ns) => IODataFrame t ns -> IO (DataFrame t ns)
- thawDataFrame :: forall (t :: Type) ns. (Dimensions ns, PrimArray t (DataFrame t ns)) => DataFrame t ns -> IO (IODataFrame t ns)
- thawPinDataFrame :: forall (t :: Type) ns. (Dimensions ns, PrimArray t (DataFrame t ns)) => DataFrame t ns -> IO (IODataFrame t ns)
- unsafeThawDataFrame :: forall (t :: Type) ns. (Dimensions ns, PrimArray t (DataFrame t ns)) => DataFrame t ns -> IO (IODataFrame t ns)
- withThawDataFrame :: forall (t :: Type) ns r. PrimArray t (DataFrame t ns) => (t -> IO r) -> (IODataFrame t ns -> IO r) -> DataFrame t ns -> IO r
- writeDataFrame :: forall (t :: Type) ns. PrimBytes (DataFrame t ('[] :: KindOf ns)) => IODataFrame t ns -> Idxs ns -> DataFrame t ('[] :: KindOf ns) -> IO ()
- writeDataFrameOff :: forall (t :: Type) ns. PrimBytes (DataFrame t ('[] :: KindOf ns)) => IODataFrame t ns -> Int -> DataFrame t ('[] :: KindOf ns) -> IO ()
- readDataFrame :: forall (t :: Type) ns. PrimBytes (DataFrame t ('[] :: KindOf ns)) => IODataFrame t ns -> Idxs ns -> IO (DataFrame t ('[] :: KindOf ns))
- readDataFrameOff :: forall (t :: Type) ns. PrimBytes (DataFrame t ('[] :: KindOf ns)) => IODataFrame t ns -> Int -> IO (DataFrame t ('[] :: KindOf ns))
- isDataFramePinned :: forall (t :: Type) ns. IODataFrame t ns -> Bool
- getDataFrameSteps :: forall (t :: Type) ns. IODataFrame t ns -> CumulDims
- withDataFramePtr :: forall (t :: Type) ns (r :: Type). PrimBytes t => IODataFrame t ns -> (Ptr t -> IO r) -> IO r

# Documentation

data IODataFrame (t :: Type) (ns :: [k]) where Source #

Mutable DataFrame that lives in IO. Internal representation is always a MutableByteArray.

pattern XIOFrame :: forall (t :: Type) (xns :: [XNat]). () => forall (ns :: [Nat]). (FixedDims xns ns, Dimensions ns) => IODataFrame t ns -> IODataFrame t xns | Data frame with some dimensions missing at compile time. Pattern-match against its constructor to get a Nat-indexed mutable data frame. |

data SomeIODataFrame (t :: Type) Source #

Mutable DataFrame of unknown dimensionality

forall (ns :: [Nat]).Dimensions ns => SomeIODataFrame (IODataFrame t ns) |

castDataFrame :: forall (t :: Type) (xns :: [XNat]) (ns :: [Nat]). FixedDims xns ns => IODataFrame t ns -> IODataFrame t xns Source #

Allow coercing between `XNat`

-indexed and `Nat`

-indexed Mutable DataFrames.

newDataFrame :: forall (t :: Type) ns. (PrimBytes t, Dimensions ns) => IO (IODataFrame t ns) Source #

Create a new mutable DataFrame.

newPinnedDataFrame :: forall (t :: Type) ns. (PrimBytes t, Dimensions ns) => IO (IODataFrame t ns) Source #

Create a new mutable DataFrame.

oneMoreDataFrame :: forall (t :: Type) ns. IODataFrame t ns -> IO (IODataFrame t ns) Source #

Create a new mutable DataFrame of the same size.

subDataFrameView :: forall (t :: Type) b bi bd as bs asbs. (SubFrameIndexCtx b bi bd, KnownDim bd, ConcatList as (b :+ bs) asbs) => Idxs (as +: bi) -> IODataFrame t asbs -> IODataFrame t (bd :+ bs) Source #

View a part of a DataFrame.

This function does not perform a copy. All changes to a new DataFrame will be reflected in the original DataFrame as well.

If any of the dims in `as`

or `b`

is unknown (`a ~ XN m`

),
then this function is unsafe and can throw an `OutOfDimBounds`

exception.
Otherwise, its safety is guaranteed by the type system.

subDataFrameView' :: forall (t :: Type) as bs asbs. ConcatList as bs asbs => Idxs as -> IODataFrame t asbs -> IODataFrame t bs Source #

View a part of a DataFrame.

This function does not perform a copy. All changes to a new DataFrame will be reflected in the original DataFrame as well.

This is a simpler version of `subDataFrameView`

that allows
to view over one index at a time.

If any of the dims in `as`

is unknown (`a ~ XN m`

),
then this function is unsafe and can throw an `OutOfDimBounds`

exception.
Otherwise, its safety is guaranteed by the type system.

copyDataFrame :: forall (t :: Type) b bi bd as bs asbs. (SubFrameIndexCtx b bi bd, KnownDim bd, ExactDims bs, PrimArray t (DataFrame t (bd :+ bs)), ConcatList as (b :+ bs) asbs) => Idxs (as +: bi) -> DataFrame t (bd :+ bs) -> IODataFrame t asbs -> IO () Source #

Copy one DataFrame into another mutable DataFrame at specified position.

In contrast to `copyDataFrame'`

, this function allows to copy over a range
of contiguous indices over a single dimension.
For example, you can write a 3x4 matrix into a 7x4 matrix, starting at indices 0..3.

This function is safe (no `OutOfDimBounds`

exception possible).
If any of the dims in `as`

is unknown (`a ~ XN m`

),
you may happen to write data beyond dataframe bounds.
In this case, this function does nothing.
If (`b ~ XN m`

) and (`Idx bi + Dim bd > Dim b`

), this function copies only as
many elements as fits into the dataframe along this dimension (possibly none).

copyMutableDataFrame :: forall (t :: Type) b bi bd as bs asbs. (SubFrameIndexCtx b bi bd, ExactDims bs, PrimBytes t, ConcatList as (b :+ bs) asbs) => Idxs (as +: bi) -> IODataFrame t (bd :+ bs) -> IODataFrame t asbs -> IO () Source #

Copy one mutable DataFrame into another mutable DataFrame at specified position.

In contrast to `copyMutableDataFrame'`

, this function allows to copy over a range
of contiguous indices over a single dimension.
For example, you can write a 3x4 matrix into a 7x4 matrix, starting at indices 0..3.

This function is safe (no `OutOfDimBounds`

exception possible).
If any of the dims in `as`

is unknown (`a ~ XN m`

),
you may happen to write data beyond dataframe bounds.
In this case, this function does nothing.
If (`b ~ XN m`

) and (`Idx bi + Dim bd > Dim b`

), this function copies only as
many elements as fits into the dataframe along this dimension (possibly none).

copyDataFrame' :: forall (t :: Type) as bs asbs. (ExactDims bs, PrimArray t (DataFrame t bs), ConcatList as bs asbs) => Idxs as -> DataFrame t bs -> IODataFrame t asbs -> IO () Source #

Copy one DataFrame into another mutable DataFrame at specified position.

This is a simpler version of `copyDataFrame`

that allows
to copy over one index at a time.

This function is safe (no `OutOfDimBounds`

exception possible).
If any of the dims in `as`

is unknown (`a ~ XN m`

),
you may happen to write data beyond dataframe bounds.
In this case, this function does nothing.

copyMutableDataFrame' :: forall (t :: Type) as bs asbs. (ExactDims bs, PrimBytes t, ConcatList as bs asbs) => Idxs as -> IODataFrame t bs -> IODataFrame t asbs -> IO () Source #

Copy one mutable DataFrame into another mutable DataFrame at specified position.

This is a simpler version of `copyMutableDataFrame`

that allows
to copy over one index at a time.

This function is safe (no `OutOfDimBounds`

exception possible).
If any of the dims in `as`

is unknown (`a ~ XN m`

),
you may happen to write data beyond dataframe bounds.
In this case, this function does nothing.

copyDataFrameOff :: forall (t :: Type) as bs asbs. (Dimensions bs, PrimArray t (DataFrame t bs), ConcatList as bs asbs) => Int -> DataFrame t bs -> IODataFrame t asbs -> IO () Source #

Copy one DataFrame into another mutable DataFrame by offset in primitive elements.

This is a low-level copy function; you have to keep in mind the row-major layout of Mutable DataFrames. Offset bounds are not checked. You will get an undefined behavior if you write beyond the DataFrame bounds.

copyMutableDataFrameOff :: forall (t :: Type) as bs asbs. (ExactDims bs, PrimBytes t, ConcatList as bs asbs) => Int -> IODataFrame t bs -> IODataFrame t asbs -> IO () Source #

Copy one mutable DataFrame into another mutable DataFrame by offset in primitive elements.

This is a low-level copy function; you have to keep in mind the row-major layout of Mutable DataFrames. Offset bounds are not checked. You will get an undefined behavior if you write beyond the DataFrame bounds

freezeDataFrame :: forall (t :: Type) ns. PrimArray t (DataFrame t ns) => IODataFrame t ns -> IO (DataFrame t ns) Source #

Copy content of a mutable DataFrame into a new immutable DataFrame.

unsafeFreezeDataFrame :: forall (t :: Type) ns. PrimArray t (DataFrame t ns) => IODataFrame t ns -> IO (DataFrame t ns) Source #

Make a mutable DataFrame immutable, without copying.

thawDataFrame :: forall (t :: Type) ns. (Dimensions ns, PrimArray t (DataFrame t ns)) => DataFrame t ns -> IO (IODataFrame t ns) Source #

Create a new mutable DataFrame and copy content of immutable one in there.

thawPinDataFrame :: forall (t :: Type) ns. (Dimensions ns, PrimArray t (DataFrame t ns)) => DataFrame t ns -> IO (IODataFrame t ns) Source #

Create a new mutable DataFrame and copy content of immutable one in there. The result array is pinned and aligned.

unsafeThawDataFrame :: forall (t :: Type) ns. (Dimensions ns, PrimArray t (DataFrame t ns)) => DataFrame t ns -> IO (IODataFrame t ns) Source #

UnsafeCoerces an underlying byte array.

withThawDataFrame :: forall (t :: Type) ns r. PrimArray t (DataFrame t ns) => (t -> IO r) -> (IODataFrame t ns -> IO r) -> DataFrame t ns -> IO r Source #

Given two continuations `f`

and `g`

.
If the input DataFrame is a single broadcast value, use it in `f`

.
Otherwise, create a new mutable DataFrame and copy content of immutable one
in there; then use it in `g`

.

This function is useful when `thawDataFrame`

cannot be used due to
`Dimensions ns`

constraint being not available.

writeDataFrame :: forall (t :: Type) ns. PrimBytes (DataFrame t ('[] :: KindOf ns)) => IODataFrame t ns -> Idxs ns -> DataFrame t ('[] :: KindOf ns) -> IO () Source #

Write a single element at the specified index.

This function is safe (no `OutOfDimBounds`

exception possible).
If any of the dims in `ns`

is unknown (`n ~ XN m`

),
you may happen to write data beyond dataframe bounds.
In this case, this function does nothing.

writeDataFrameOff :: forall (t :: Type) ns. PrimBytes (DataFrame t ('[] :: KindOf ns)) => IODataFrame t ns -> Int -> DataFrame t ('[] :: KindOf ns) -> IO () Source #

Write a single element at the specified element offset.

This is a low-level write function; you have to keep in mind the row-major layout of Mutable DataFrames. Offset bounds are not checked. You will get an undefined behavior if you write beyond the DataFrame bounds.

readDataFrame :: forall (t :: Type) ns. PrimBytes (DataFrame t ('[] :: KindOf ns)) => IODataFrame t ns -> Idxs ns -> IO (DataFrame t ('[] :: KindOf ns)) Source #

Read a single element at the specified index.

If any of the dims in `ns`

is unknown (`n ~ XN m`

),
then this function is unsafe and can throw an `OutOfDimBounds`

exception.
Otherwise, its safety is guaranteed by the type system.

readDataFrameOff :: forall (t :: Type) ns. PrimBytes (DataFrame t ('[] :: KindOf ns)) => IODataFrame t ns -> Int -> IO (DataFrame t ('[] :: KindOf ns)) Source #

Read a single element at the specified element offset.

This is a low-level read function; you have to keep in mind the row-major layout of Mutable DataFrames. Offset bounds are not checked. You will get an undefined behavior if you read beyond the DataFrame bounds.

isDataFramePinned :: forall (t :: Type) ns. IODataFrame t ns -> Bool Source #

Check if the byte array wrapped by this DataFrame is pinned, which means cannot be relocated by GC.

getDataFrameSteps :: forall (t :: Type) ns. IODataFrame t ns -> CumulDims Source #

Get cumulative dimensions `ns`

of a `IODataFrame t ns`

withDataFramePtr :: forall (t :: Type) ns (r :: Type). PrimBytes t => IODataFrame t ns -> (Ptr t -> IO r) -> IO r Source #

Allow arbitrary IO operations on a pointer to the beginning of the data keeping the data from garbage collecting until the arg function returns.

Warning: do not let `Ptr t`

leave the scope of the arg function,
the data may be garbage-collected by then.

Warning: use this function on a pinned DataFrame only; otherwise, the data may be relocated before the arg fun finishes.