Copyright	(c) Dong Han 2017-2020
License	BSD
Maintainer	winterland1989@gmail.com
Stability	experimental
Portability	non-portable
Safe Haskell	None
Language	Haskell2010

Z.Data.Array.UnliftedArray

Description

GHC contains three general classes of value types:

Unboxed types: values are machine values made up of fixed numbers of bytes
Unlifted types: values are pointers, but strictly evaluated
Lifted types: values are pointers, lazily evaluated

The first category can be stored in a ByteArray, and this allows types in category 3 that are simple wrappers around category 1 types to be stored more efficiently using a ByteArray. This module provides the same facility for category 2 types.

GHC has two primitive types, ArrayArray# and MutableArrayArray#. These are arrays of pointers, but of category 2 values, so they are known to not be bottom. This allows types that are wrappers around such types to be stored in an array without an extra level of indirection.

The way that the ArrayArray# API works is that one can read and write ArrayArray# values to the positions. This works because all category 2 types share a uniform representation, unlike unboxed values which are represented by varying (by type) numbers of bytes. However, using the this makes the internal API very unsafe to use, as one has to coerce values to and from ArrayArray#.

The API presented by this module is more type safe. UnliftedArray and MutableUnliftedArray are parameterized by the type of arrays they contain, and the coercions necessary are abstracted into a class, PrimUnlifted, of things that are eligible to be stored.

Synopsis

class PrimUnlifted a where
- writeUnliftedArray# :: MutableArrayArray# s -> Int# -> a -> State# s -> State# s
- readUnliftedArray# :: MutableArrayArray# s -> Int# -> State# s -> (#State# s, a#)
- indexUnliftedArray# :: ArrayArray# -> Int# -> a
data MutableUnliftedArray s a = MutableUnliftedArray (MutableArrayArray# s)
data UnliftedArray a = UnliftedArray ArrayArray#
unsafeNewUnliftedArray :: PrimMonad m => Int -> m (MutableUnliftedArray (PrimState m) a)
newUnliftedArray :: (PrimMonad m, PrimUnlifted a) => Int -> a -> m (MutableUnliftedArray (PrimState m) a)
setUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> Int -> a -> m ()
sizeofUnliftedArray :: UnliftedArray e -> Int
sizeofMutableUnliftedArray :: MutableUnliftedArray s e -> Int
writeUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> a -> m ()
readUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> m a
indexUnliftedArray :: PrimUnlifted a => UnliftedArray a -> Int -> a
unsafeFreezeUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> m (UnliftedArray a)
sameMutableUnliftedArray :: MutableUnliftedArray s a -> MutableUnliftedArray s a -> Bool
copyUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> UnliftedArray a -> Int -> Int -> m ()
copyMutableUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> MutableUnliftedArray (PrimState m) a -> Int -> Int -> m ()
freezeUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> Int -> m (UnliftedArray a)
thawUnliftedArray :: PrimMonad m => UnliftedArray a -> Int -> Int -> m (MutableUnliftedArray (PrimState m) a)
cloneUnliftedArray :: UnliftedArray a -> Int -> Int -> UnliftedArray a
cloneMutableUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> Int -> m (MutableUnliftedArray (PrimState m) a)

Documentation

class PrimUnlifted a where Source #

Methods

writeUnliftedArray# :: MutableArrayArray# s -> Int# -> a -> State# s -> State# s Source #

readUnliftedArray# :: MutableArrayArray# s -> Int# -> State# s -> (#State# s, a#) Source #

indexUnliftedArray# :: ArrayArray# -> Int# -> a Source #

Instances

PrimUnlifted ByteArray Source #
Instance details Defined in Z.Data.Array.UnliftedArray Methods writeUnliftedArray# :: MutableArrayArray# s -> Int# -> ByteArray -> State# s -> State# s Source # readUnliftedArray# :: MutableArrayArray# s -> Int# -> State# s -> (#State# s, ByteArray#) Source # indexUnliftedArray# :: ArrayArray# -> Int# -> ByteArray Source #
PrimUnlifted (IORef a) Source #
Instance details Defined in Z.Data.Array.UnliftedArray Methods writeUnliftedArray# :: MutableArrayArray# s -> Int# -> IORef a -> State# s -> State# s Source # readUnliftedArray# :: MutableArrayArray# s -> Int# -> State# s -> (#State# s, IORef a#) Source # indexUnliftedArray# :: ArrayArray# -> Int# -> IORef a Source #
PrimUnlifted (MVar a) Source #
Instance details Defined in Z.Data.Array.UnliftedArray Methods writeUnliftedArray# :: MutableArrayArray# s -> Int# -> MVar a -> State# s -> State# s Source # readUnliftedArray# :: MutableArrayArray# s -> Int# -> State# s -> (#State# s, MVar a#) Source # indexUnliftedArray# :: ArrayArray# -> Int# -> MVar a Source #
PrimUnlifted (PrimArray a) Source #
Instance details Defined in Z.Data.Array.UnliftedArray Methods writeUnliftedArray# :: MutableArrayArray# s -> Int# -> PrimArray a -> State# s -> State# s Source # readUnliftedArray# :: MutableArrayArray# s -> Int# -> State# s -> (#State# s, PrimArray a#) Source # indexUnliftedArray# :: ArrayArray# -> Int# -> PrimArray a Source #
PrimUnlifted (MutableByteArray s) Source #
Instance details Defined in Z.Data.Array.UnliftedArray Methods writeUnliftedArray# :: MutableArrayArray# s0 -> Int# -> MutableByteArray s -> State# s0 -> State# s0 Source # readUnliftedArray# :: MutableArrayArray# s0 -> Int# -> State# s0 -> (#State# s0, MutableByteArray s#) Source # indexUnliftedArray# :: ArrayArray# -> Int# -> MutableByteArray s Source #
PrimUnlifted (STRef s a) Source #
Instance details Defined in Z.Data.Array.UnliftedArray Methods writeUnliftedArray# :: MutableArrayArray# s0 -> Int# -> STRef s a -> State# s0 -> State# s0 Source # readUnliftedArray# :: MutableArrayArray# s0 -> Int# -> State# s0 -> (#State# s0, STRef s a#) Source # indexUnliftedArray# :: ArrayArray# -> Int# -> STRef s a Source #
PrimUnlifted (MutablePrimArray s a) Source #
Instance details Defined in Z.Data.Array.UnliftedArray Methods writeUnliftedArray# :: MutableArrayArray# s0 -> Int# -> MutablePrimArray s a -> State# s0 -> State# s0 Source # readUnliftedArray# :: MutableArrayArray# s0 -> Int# -> State# s0 -> (#State# s0, MutablePrimArray s a#) Source # indexUnliftedArray# :: ArrayArray# -> Int# -> MutablePrimArray s a Source #

data MutableUnliftedArray s a Source #

Constructors

MutableUnliftedArray (MutableArrayArray# s)

data UnliftedArray a Source #

Constructors

UnliftedArray ArrayArray#

Instances

PrimUnlifted a => Arr (UnliftedArray :: Type -> Type) a Source #
Instance details Defined in Z.Data.Array Associated Types type MArr UnliftedArray = (mar :: Type -> Type -> Type) Source # Methods newArr :: (PrimMonad m, PrimState m ~ s) => Int -> m (MArr UnliftedArray s a) Source # newArrWith :: (PrimMonad m, PrimState m ~ s) => Int -> a -> m (MArr UnliftedArray s a) Source # readArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> Int -> m a Source # writeArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> Int -> a -> m () Source # setArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> Int -> Int -> a -> m () Source # indexArr :: UnliftedArray a -> Int -> a Source # indexArr' :: UnliftedArray a -> Int -> (#a#) Source # indexArrM :: Monad m => UnliftedArray a -> Int -> m a Source # freezeArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> Int -> Int -> m (UnliftedArray a) Source # thawArr :: (PrimMonad m, PrimState m ~ s) => UnliftedArray a -> Int -> Int -> m (MArr UnliftedArray s a) Source # unsafeFreezeArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> m (UnliftedArray a) Source # unsafeThawArr :: (PrimMonad m, PrimState m ~ s) => UnliftedArray a -> m (MArr UnliftedArray s a) Source # copyArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> Int -> UnliftedArray a -> Int -> Int -> m () Source # copyMutableArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> Int -> MArr UnliftedArray s a -> Int -> Int -> m () Source # moveArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> Int -> MArr UnliftedArray s a -> Int -> Int -> m () Source # cloneArr :: UnliftedArray a -> Int -> Int -> UnliftedArray a Source # cloneMutableArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> Int -> Int -> m (MArr UnliftedArray s a) Source # resizeMutableArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> Int -> m (MArr UnliftedArray s a) Source # shrinkMutableArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> Int -> m () Source # sameMutableArr :: MArr UnliftedArray s a -> MArr UnliftedArray s a -> Bool Source # sizeofArr :: UnliftedArray a -> Int Source # sizeofMutableArr :: (PrimMonad m, PrimState m ~ s) => MArr UnliftedArray s a -> m Int Source # sameArr :: UnliftedArray a -> UnliftedArray a -> Bool Source #
PrimUnlifted a => Vec (UnliftedArray :: Type -> Type) a Source #
Instance details Defined in Z.Data.Vector.Base Associated Types type IArray UnliftedArray :: Type -> Type Source # Methods toArr :: UnliftedArray a -> (IArray UnliftedArray a, Int, Int) Source # fromArr :: IArray UnliftedArray a -> Int -> Int -> UnliftedArray a Source #
(PrimUnlifted a, ShowT a) => ShowT (UnliftedArray a) Source #
Instance details Defined in Z.Data.Text.ShowT Methods toTextBuilder :: Int -> UnliftedArray a -> TextBuilder () Source #
(PrimUnlifted a, FromValue a) => FromValue (UnliftedArray a) Source #
Instance details Defined in Z.Data.JSON.Base Methods fromValue :: Value -> Converter (UnliftedArray a) Source #
(PrimUnlifted a, EncodeJSON a) => EncodeJSON (UnliftedArray a) Source #
Instance details Defined in Z.Data.JSON.Base Methods encodeJSON :: UnliftedArray a -> Builder () Source #
(PrimUnlifted a, ToValue a) => ToValue (UnliftedArray a) Source #
Instance details Defined in Z.Data.JSON.Base Methods toValue :: UnliftedArray a -> Value Source #
type MArr (UnliftedArray :: Type -> Type) Source #
Instance details Defined in Z.Data.Array type MArr (UnliftedArray :: Type -> Type) = (MutableUnliftedArray :: Type -> Type -> Type)
type IArray (UnliftedArray :: Type -> Type) Source #
Instance details Defined in Z.Data.Vector.Base type IArray (UnliftedArray :: Type -> Type) = (UnliftedArray :: Type -> Type)

unsafeNewUnliftedArray Source #

Arguments

:: PrimMonad m
=> Int	size
-> m (MutableUnliftedArray (PrimState m) a)

Creates a new MutableUnliftedArray. This function is unsafe because it initializes all elements of the array as pointers to the array itself. Attempting to read one of these elements before writing to it is in effect an unsafe coercion from the MutableUnliftedArray s a to the element type.

newUnliftedArray Source #

Arguments

:: (PrimMonad m, PrimUnlifted a)
=> Int	size
-> a	initial value
-> m (MutableUnliftedArray (PrimState m) a)

Creates a new MutableUnliftedArray with the specified value as initial contents. This is slower than unsafeNewUnliftedArray, but safer.

setUnliftedArray Source #

Arguments

:: (PrimMonad m, PrimUnlifted a)
=> MutableUnliftedArray (PrimState m) a	destination
-> Int	offset
-> Int	length
-> a	value to fill with
-> m ()

sizeofUnliftedArray :: UnliftedArray e -> Int Source #

Yields the length of an UnliftedArray.

sizeofMutableUnliftedArray :: MutableUnliftedArray s e -> Int Source #

Yields the length of a MutableUnliftedArray.

writeUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> a -> m () Source #

readUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> m a Source #

indexUnliftedArray :: PrimUnlifted a => UnliftedArray a -> Int -> a Source #

unsafeFreezeUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> m (UnliftedArray a) Source #

Freezes a MutableUnliftedArray, yielding an UnliftedArray. This simply marks the array as frozen in place, so it should only be used when no further modifications to the mutable array will be performed.

sameMutableUnliftedArray :: MutableUnliftedArray s a -> MutableUnliftedArray s a -> Bool Source #

Determines whether two MutableUnliftedArray values are the same. This is object/pointer identity, not based on the contents.

copyUnliftedArray Source #

Arguments

:: PrimMonad m
=> MutableUnliftedArray (PrimState m) a	destination
-> Int	offset into destination
-> UnliftedArray a	source
-> Int	offset into source
-> Int	number of elements to copy
-> m ()

Copies the contents of an immutable array into a mutable array.

copyMutableUnliftedArray Source #

Arguments

:: PrimMonad m
=> MutableUnliftedArray (PrimState m) a	destination
-> Int	offset into destination
-> MutableUnliftedArray (PrimState m) a	source
-> Int	offset into source
-> Int	number of elements to copy
-> m ()

Copies the contents of one mutable array into another.

freezeUnliftedArray Source #

Arguments

:: PrimMonad m
=> MutableUnliftedArray (PrimState m) a	source
-> Int	offset
-> Int	length
-> m (UnliftedArray a)

Freezes a portion of a MutableUnliftedArray, yielding an UnliftedArray. This operation is safe, in that it copies the frozen portion, and the existing mutable array may still be used afterward.

thawUnliftedArray Source #

Arguments

:: PrimMonad m
=> UnliftedArray a	source
-> Int	offset
-> Int	length
-> m (MutableUnliftedArray (PrimState m) a)

Thaws a portion of an UnliftedArray, yielding a MutableUnliftedArray. This copies the thawed portion, so mutations will not affect the original array.

cloneUnliftedArray Source #

Arguments

:: UnliftedArray a	source
-> Int	offset
-> Int	length
-> UnliftedArray a

Creates a copy of a portion of an UnliftedArray

cloneMutableUnliftedArray Source #

Arguments

:: PrimMonad m
=> MutableUnliftedArray (PrimState m) a	source
-> Int	offset
-> Int	length
-> m (MutableUnliftedArray (PrimState m) a)

Creates a new MutableUnliftedArray containing a copy of a portion of another mutable array.