Vector specialized to use
Data.Vector.Storable.
Modulevector-sized-1.6.1Haskell2010
Data.Vector.Storable.Sized
This module re-exports the functionality in Data.Vector.Generic.Sized
specialized to Data.Vector.Storable.
Functions returning a vector determine the size from the type context unless
they have a ' suffix in which case they take an explicit Proxy argument.
Functions where the resulting vector size is not known until runtime are not exported.
Contents
- Accessors
- Length information
- Indexing
- Monadic indexing
- Extracting subvectors (slicing)
- Construction
- Initialization
- Monadic initialization
- Unfolding
- Enumeration
- Concatenation
- Restricting memory usage
- Modifying vectors
- Bulk updates
- Accumulations
- Permutations
- Lenses
- Elementwise operations
- Indexing
- Mapping
- Monadic mapping
- Zipping
- Monadic zipping
- Unzipping
- Working with predicates
- Searching
- Folding
- Specialised folds
- Monadic folds
- Monadic sequencing
- Prefix sums (scans)
- Conversions
- Lists
- Mutable vectors
- Unsized Vectors
Synopsis
- type Vector
- pattern SomeSized
- type MVector
- value length
- value length'
- value knownLength
- value knownLength'
- value index
- value index'
- value unsafeIndex
- value head
- value last
- value indexM
- value indexM'
- value unsafeIndexM
- value headM
- value lastM
- value slice
- value slice'
- value init
- value tail
- value take
- value take'
- value drop
- value drop'
- value splitAt
- value splitAt'
- value empty
- value singleton
- value fromTuple
- pattern Build
- value replicate
- value replicate'
- value generate
- value generate'
- value iterateN
- value iterateN'
- value replicateM
- value replicateM'
- value generateM
- value generateM'
- value unfoldrN
- value unfoldrN'
- value enumFromN
- value enumFromN'
- value enumFromStepN
- value enumFromStepN'
- value cons
- value snoc
- value ++
- value force
- value //
- value update
- value update_
- value unsafeUpd
- value unsafeUpdate
- value unsafeUpdate_
- value accum
- value accumulate
- value accumulate_
- value unsafeAccum
- value unsafeAccumulate
- value unsafeAccumulate_
- value reverse
- value backpermute
- value unsafeBackpermute
- value ix
- value ix'
- value _head
- value _last
- value indexed
- value map
- value imap
- value concatMap
- value mapM
- value imapM
- value mapM_
- value imapM_
- value forM
- value forM_
- value zipWith
- value zipWith3
- value zipWith4
- value zipWith5
- value zipWith6
- value izipWith
- value izipWith3
- value izipWith4
- value izipWith5
- value izipWith6
- value zip
- value zip3
- value zip4
- value zip5
- value zip6
- value zipWithM
- value izipWithM
- value zipWithM_
- value izipWithM_
- value unzip
- value unzip3
- value unzip4
- value unzip5
- value unzip6
- value elem
- value notElem
- value find
- value findIndex
- value elemIndex
- value foldl
- value foldl1
- value foldl'
- value foldl1'
- value foldr
- value foldr1
- value foldr'
- value foldr1'
- value ifoldl
- value ifoldl'
- value ifoldr
- value ifoldr'
- value all
- value any
- value and
- value or
- value sum
- value product
- value maximum
- value maximumBy
- value minimum
- value minimumBy
- value maxIndex
- value maxIndexBy
- value minIndex
- value minIndexBy
- value foldM
- value ifoldM
- value fold1M
- value foldM'
- value ifoldM'
- value fold1M'
- value foldM_
- value ifoldM_
- value fold1M_
- value foldM'_
- value ifoldM'_
- value fold1M'_
- value sequence
- value sequence_
- value prescanl
- value prescanl'
- value postscanl
- value postscanl'
- value scanl
- value scanl'
- value scanl1
- value scanl1'
- value prescanr
- value prescanr'
- value postscanr
- value postscanr'
- value scanr
- value scanr'
- value scanr1
- value scanr1'
- value toList
- value fromList
- value fromListN
- value fromListN'
- value withSizedList
- value freeze
- value thaw
- value copy
- value unsafeFreeze
- value unsafeThaw
- value toSized
- value withSized
- value fromSized
- value withVectorUnsafe
- value zipVectorsUnsafe
- Packagevector-sized-1.6.1
- Exports180
- LanguageHaskell2010
- LicenceBSD-3-Clause
- SourceSized.hs
Pattern synonym that lets you treat an unsized vector as if it "contained" a sized vector. If you pattern match on an unsized vector, its contents will be the sized vector counterpart.
testFunc :: Unsized.Vector Int -> Int
testFunc (SomeSized v) =
sum (zipWith (+) v (replicate 1))
-- ^ here, v is `Sized.Vector n Int`, and we have
`KnownNat n`
The n type variable will be properly instantiated to whatever the
length of the vector is, and you will also have a KnownNat n
instance available. You can get n in scope by turning on
ScopedTypeVariables and matching on SomeSized (v :: Sized.Vector
n Int).
Without this, you would otherwise have to use withSized to do the same thing:
testFunc :: Unsized.Vector Int -> Int
testFunc u = withSized u $ \v ->
sum (zipWith (+) v (replicate 1))
Remember that the type of final result of your function (the Int,
here) must not depend on n. However, the types of the intermediate
values are allowed to depend on n.
This is especially useful in do blocks, where you can pattern match on
the unsized results of actions, to use the sized vector in the rest of
the do block. You also get a KnownNat n constraint for the
remainder of the do block.
-- If you had:
getAVector :: IO (Unsized.Vector Int)
main :: IO ()
main = do
SomeSized v <- getAVector -- v is `Sized.Vector n Int`
-- get n in scope
SomeSized (v :: Sized.Vector n Int) <- getAVector
print v
Remember that the final type of the result of the do block ((), here)
must not depend on n. However, the
Also useful in ghci, where you can pattern match to get sized vectors from unsized vectors.
ghci> SomeSized v <- pure (myUnsizedVector :: Unsized.Vector Int)
-- ^ v is `Sized.Vector n Int`
This enables interactive exploration with sized vectors in ghci, and is useful for using with other libraries and functions that expect sized vectors in an interactive setting.
(Note that as of GHC 8.6, you cannot get the n in scope in your ghci
session using ScopedTypeVariables, like you can with do blocks)
You can also use this as a constructor, to take a sized vector and "hide" the size, to produce an unsized vector:
SomeSized :: Sized.Vector n a -> Unsized.Vector a
Data.Vector.Generic.Mutable.Sized.Vector specialized to use
Data.Vector.Storable.Mutable.
Accessors
Length information
value
knownLength O(1) Reveal a KnownNat instance for a vector's length, determined at runtime.
value
knownLength' Indexing
O(1) Safe indexing using a Finite.
O(1) Safe indexing using a Proxy.
O(1) Indexing using an Int without bounds checking.
O(1) Yield the first element of a non-empty vector.
O(1) Yield the last element of a non-empty vector.
Monadic indexing
O(1) Safe indexing in a monad. See the documentation for indexM for an explanation of why this is useful.
O(1) Yield the first element of a non-empty vector in a monad. See the documentation for indexM for an explanation of why this is useful.
O(1) Yield the last element of a non-empty vector in a monad. See the documentation for indexM for an explanation of why this is useful.
Extracting subvectors (slicing)
value
slice O(1) Yield a slice of the vector without copying it with an inferred length argument.
value
slice' O(1) Yield a slice of the vector without copying it with an explicit length argument.
O(1) Yield all but the last element of a non-empty vector without copying.
O(1) Yield all but the first element of a non-empty vector without copying.
O(1) Yield the first n elements. The resulting vector always contains
this many elements. The length of the resulting vector is inferred from the
type.
O(1) Yield the first n elements. The resulting vector always contains
this many elements. The length of the resulting vector is given explicitly
as a Proxy argument.
O(1) Yield all but the the first n elements. The given vector must
contain at least this many elements. The length of the resulting vector is
inferred from the type.
O(1) Yield all but the the first n elements. The given vector must
contain at least this many elements. The length of the resulting vector is
givel explicitly as a Proxy argument.
O(1) Yield the first n elements, paired with the rest, without copying.
The lengths of the resulting vectors are inferred from the type.
O(1) Yield the first n elements paired with the remainder without
copying. The length of the first resulting vector is passed explicitly as a
Proxy argument.
Construction
Initialization
O(1) Empty vector.
O(1) Vector with exactly one element.
O(n) Construct a vector in a type safe manner using a tuple.
fromTuple (1,2) :: Vector 2 Int
fromTuple ("hey", "what's", "going", "on") :: Vector 4 String
O(n) Construct a vector in a type-safe manner using a sized linked list.
Build (1 :< 2 :< 3 :< Nil) :: Vector 3 Int
Build ("not" :< "much" :< Nil) :: Vector 2 String
Can also be used as a pattern.
O(n) Construct a vector with the same element in each position where the length is inferred from the type.
O(n) Construct a vector with the same element in each position where the length is given explicitly as a Proxy argument.
O(n) construct a vector of the given length by applying the function to each index where the length is inferred from the type.
O(n) construct a vector of the given length by applying the function to each index where the length is given explicitly as a Proxy argument.
O(n) Apply function n times to value. Zeroth element is original value.
The length is inferred from the type.
O(n) Apply function n times to value. Zeroth element is original value.
The length is given explicitly as a Proxy argument.
Monadic initialization
O(n) Execute the monadic action n times and store the results in a
vector where n is inferred from the type.
O(n) Execute the monadic action n times and store the results in a
vector where n is given explicitly as a Proxy argument.
O(n) Construct a vector of length n by applying the monadic action to
each index where n is inferred from the type.
O(n) Construct a vector of length n by applying the monadic action to
each index where n is given explicitly as a Proxy argument.
Unfolding
O(n) Construct a vector with exactly n elements by repeatedly applying
the generator function to the a seed. The length is inferred from the
type.
O(n) Construct a vector with exactly n elements by repeatedly applying
the generator function to the a seed. The length is given explicitly
as a Proxy argument.
Enumeration
O(n) Yield a vector of length n containing the values x, x+1, ...,
x + (n - 1). The length is inferred from the type.
O(n) Yield a vector of length n containing the values x, x+1, ...,
x + (n - 1). The length is given explicitly as a Proxy argument.
O(n) Yield a vector of the given length containing the values x, x+y,
x+2y, ..., x + (n - 1)y. The length is inferred from the type.
O(n) Yield a vector of the given length containing the values x, x+y,
x+2y, ..., x + (n - 1)y. The length is given explicitly as a Proxy argument.
Concatenation
O(n) Prepend an element.
O(n) Append an element.
O(m+n) Concatenate two vectors.
Restricting memory usage
O(n) Yield the argument but force it not to retain any extra memory, possibly by copying it.
This is especially useful when dealing with slices. For example:
force (slice 0 2 <huge vector>)Here, the slice retains a reference to the huge vector. Forcing it creates a copy of just the elements that belong to the slice and allows the huge vector to be garbage collected.
Modifying vectors
Bulk updates
value
(//) O(m+n) For each pair (i,a) from the list, replace the vector
element at position i by a.
<5,9,2,7> // [(2,1),(0,3),(2,8)] = <3,9,8,7>value
update O(m+n) For each pair (i,a) from the vector of index/value pairs,
replace the vector element at position i by a.
update <5,9,2,7> <(2,1),(0,3),(2,8)> = <3,9,8,7>value
update_ O(m+n) For each index i from the index vector and the
corresponding value a from the value vector, replace the element of the
initial vector at position i by a.
update_ <5,9,2,7> <2,0,2> <1,3,8> = <3,9,8,7>This function is useful for instances of Vector that cannot store pairs. Otherwise, update is probably more convenient.
update_ xs is ys = update xs (zip is ys)
value
unsafeUpd Same as (//) but without bounds checking.
value
unsafeUpdate Same as update but without bounds checking.
value
unsafeUpdate_ Same as update_ but without bounds checking.
Accumulations
value
accum O(m+n) For each pair (i,b) from the list, replace the vector element
a at position i by f a b.
accum (+) <5,9,2> [(2,4),(1,6),(0,3),(1,7)] = <5+3, 9+6+7, 2+4>value
accumulate O(m+n) For each pair (i,b) from the vector of pairs, replace the vector
element a at position i by f a b.
accumulate (+) <5,9,2> <(2,4),(1,6),(0,3),(1,7)> = <5+3, 9+6+7, 2+4>value
accumulate_ O(m+n) For each index i from the index vector and the
corresponding value b from the the value vector,
replace the element of the initial vector at
position i by f a b.
accumulate_ (+) <5,9,2> <2,1,0,1> <4,6,3,7> = <5+3, 9+6+7, 2+4>This function is useful for instances of Vector that cannot store pairs. Otherwise, accumulate is probably more convenient:
accumulate_ f as is bs = accumulate f as (zip is bs)
value
unsafeAccum Same as accum but without bounds checking.
value
unsafeAccumulate Same as accumulate but without bounds checking.
value
unsafeAccumulate_ Same as accumulate_ but without bounds checking.
Permutations
O(n) Reverse a vector.
value
backpermute O(n) Yield the vector obtained by replacing each element i of the
index vector by xs. This is equivalent to !imap (xs but is
often much more efficient.!) is
backpermute <a,b,c,d> <0,3,2,3,1,0> = <a,d,c,d,b,a>value
unsafeBackpermute Same as backpermute but without bounds checking.
Lenses
Lens to access (O(1)) and update (O(n)) an arbitrary element by its index.
Type-safe lens to access (O(1)) and update (O(n)) an arbitrary element by its index which should be supplied via TypeApplications.
Lens to access (O(1)) and update (O(n)) the first element of a non-empty vector.
Lens to access (O(1)) and update (O(n)) the last element of a non-empty vector.
Elementwise operations
Indexing
O(n) Pair each element in a vector with its index.
Mapping
O(n) Map a function over a vector.
O(n) Apply a function to every element of a vector and its index.
O(n*m) Map a function over a vector and concatenate the results. The function is required to always return the same length vector.
Monadic mapping
O(n) Apply the monadic action to all elements of the vector, yielding a vector of results.
O(n) Apply the monadic action to every element of a vector and its index, yielding a vector of results.
O(n) Apply the monadic action to all elements of a vector and ignore the results.
O(n) Apply the monadic action to every element of a vector and its index, ignoring the results.
O(n) Apply the monadic action to all elements of the vector, yielding a
vector of results. Equvalent to flip mapM.
O(n) Apply the monadic action to all elements of a vector and ignore the
results. Equivalent to flip mapM_.
Zipping
O(n) Zip two vectors of the same length with the given function.
Zip three vectors with the given function.
O(n) Zip two vectors of the same length with a function that also takes the elements' indices).
O(n) Zip two vectors of the same length.
Monadic zipping
O(n) Zip the two vectors of the same length with the monadic action and yield a vector of results.
O(n) Zip the two vectors with a monadic action that also takes the element index and yield a vector of results.
O(n) Zip the two vectors with the monadic action and ignore the results.
O(n) Zip the two vectors with a monadic action that also takes the element index and ignore the results.
Unzipping
O(min(m,n)) Unzip a vector of pairs.
Working with predicates
Searching
O(n) Check if the vector contains an element.
O(n) Check if the vector does not contain an element (inverse of elem).
Folding
O(n) Left fold.
O(n) Left fold on non-empty vectors.
O(n) Left fold with strict accumulator.
O(n) Left fold on non-empty vectors with strict accumulator.
O(n) Right fold.
O(n) Right fold on non-empty vectors.
O(n) Right fold with a strict accumulator.
O(n) Right fold on non-empty vectors with strict accumulator.
O(n) Left fold (function applied to each element and its index).
O(n) Left fold with strict accumulator (function applied to each element and its index).
O(n) Right fold (function applied to each element and its index).
O(n) Right fold with strict accumulator (function applied to each element and its index).
Specialised folds
O(n) Check if all elements satisfy the predicate.
O(n) Check if any element satisfies the predicate.
O(n) Check if all elements are True
O(n) Check if any element is True
O(n) Compute the sum of the elements.
O(n) Compute the product of the elements.
O(n) Yield the maximum element of the non-empty vector.
O(n) Yield the maximum element of the non-empty vector according to the given comparison function.
O(n) Yield the minimum element of the non-empty vector.
O(n) Yield the minimum element of the non-empty vector according to the given comparison function.
O(n) Yield the index of the maximum element of the non-empty vector.
O(n) Yield the index of the maximum element of the non-empty vector according to the given comparison function.
O(n) Yield the index of the minimum element of the non-empty vector.
O(n) Yield the index of the minimum element of the non-empty vector according to the given comparison function.
Monadic folds
O(n) Monadic fold.
O(n) Monadic fold (action applied to each element and its index).
O(n) Monadic fold over non-empty vectors.
O(n) Monadic fold with strict accumulator.
O(n) Monadic fold with strict accumulator (action applied to each element and its index).
O(n) Monadic fold over non-empty vectors with strict accumulator.
O(n) Monadic fold that discards the result.
O(n) Monadic fold that discards the result (action applied to each element and its index).
O(n) Monadic fold over non-empty vectors that discards the result.
O(n) Monadic fold with strict accumulator that discards the result.
O(n) Monadic fold with strict accumulator that discards the result (action applied to each element and its index).
O(n) Monad fold over non-empty vectors with strict accumulator that discards the result.
Monadic sequencing
Evaluate each action and collect the results.
Evaluate each action and discard the results.
Prefix sums (scans)
O(n) Prescan with strict accumulator.
O(n) Scan.
O(n) Scan with strict accumulator.
O(n) Haskell-style scan.
O(n) Haskell-style scan with strict accumulator.
O(n) Scan over a non-empty vector.
O(n) Scan over a non-empty vector with a strict accumulator.
O(n) Right-to-left prescan.
O(n) Right-to-left prescan with strict accumulator.
O(n) Right-to-left scan.
O(n) Right-to-left scan with strict accumulator.
O(n) Right-to-left Haskell-style scan.
O(n) Right-to-left Haskell-style scan with strict accumulator.
O(n) Right-to-left scan over a non-empty vector.
O(n) Right-to-left scan over a non-empty vector with a strict accumulator.
Conversions
Lists
O(n) Convert a vector to a list.
O(n) Convert a list to a vector.
O(n) Convert the first n elements of a list to a vector. The length of
the resulting vector is inferred from the type.
O(n) Convert the first n elements of a list to a vector. The length of
the resulting vector is given explicitly as a Proxy argument.
O(n) Takes a list and returns a continuation providing a vector with a size parameter corresponding to the length of the list.
Essentially converts a list into a vector with the proper size parameter, determined at runtime.
See withSized
Mutable vectors
O(n) Yield an immutable copy of the mutable vector.
O(n) Yield a mutable copy of the immutable vector.
O(n) Copy an immutable vector into a mutable one.
O(1) Unsafely convert a mutable vector to an immutable one withouy copying. The mutable vector may not be used after this operation.
O(n) Unsafely convert an immutable vector to a mutable one without copying. The immutable vector may not be used after this operation.
Unsized Vectors
Apply a function on unsized vectors to a sized vector. The function must preserve the size of the vector, this is not checked.
Apply a function on two unsized vectors to sized vectors. The function must preserve the size of the vectors, this is not checked.