From e7d09b88074a87eafb45a05a3133752593d808d9 Mon Sep 17 00:00:00 2001 From: Aleksey Khudyakov Date: Sat, 1 May 2021 17:38:54 +0300 Subject: [PATCH] Add haddocks for mutable drop/take/init/tail and corresponding unsafe variants (#377) * Add haddocks for mutable take, drop, init & tail * Add documentation for unsafe variants --- vector/src/Data/Vector/Generic/Mutable.hs | 16 ++++++++++++++++ vector/src/Data/Vector/Mutable.hs | 16 ++++++++++++++++ vector/src/Data/Vector/Primitive/Mutable.hs | 16 ++++++++++++++++ vector/src/Data/Vector/Storable/Mutable.hs | 16 ++++++++++++++++ vector/src/Data/Vector/Unboxed/Mutable.hs | 16 ++++++++++++++++ 5 files changed, 80 insertions(+) diff --git a/vector/src/Data/Vector/Generic/Mutable.hs b/vector/src/Data/Vector/Generic/Mutable.hs index 3d097911..022567b6 100644 --- a/vector/src/Data/Vector/Generic/Mutable.hs +++ b/vector/src/Data/Vector/Generic/Mutable.hs @@ -528,10 +528,16 @@ slice :: MVector v a slice i n v = BOUNDS_CHECK(checkSlice) "slice" i n (length v) $ unsafeSlice i n v +-- | Take @n@ first elements of the mutable vector without making a +-- copy. For negative @n@ empty vector is returned. If @n@ is larger +-- than vector's length empty vector is returned, take :: MVector v a => Int -> v s a -> v s a {-# INLINE take #-} take n v = unsafeSlice 0 (min (max n 0) (length v)) v +-- | Drop @n@ first element of the mutable vector without making a +-- copy. For negative @n@ vector is returned unchanged and if @n@ is +-- larger than vector's length empty vector is returned. drop :: MVector v a => Int -> v s a -> v s a {-# INLINE drop #-} drop n v = unsafeSlice (min m n') (max 0 (m - n')) v @@ -549,10 +555,14 @@ splitAt n v = ( unsafeSlice 0 m v n' = max n 0 len = length v +-- | Drop last element of the mutable vector without making a copy. If +-- vector is empty exception is thrown. init :: MVector v a => v s a -> v s a {-# INLINE init #-} init v = slice 0 (length v - 1) v +-- | Drop first element of the mutable vector without making a copy. If +-- vector is empty exception is thrown. tail :: MVector v a => v s a -> v s a {-# INLINE tail #-} tail v = slice 1 (length v - 1) v @@ -567,18 +577,24 @@ unsafeSlice :: MVector v a => Int -- ^ starting index unsafeSlice i n v = UNSAFE_CHECK(checkSlice) "unsafeSlice" i n (length v) $ basicUnsafeSlice i n v +-- | Same as 'init' but doesn't do range checks. unsafeInit :: MVector v a => v s a -> v s a {-# INLINE unsafeInit #-} unsafeInit v = unsafeSlice 0 (length v - 1) v +-- | Same as 'tail' but doesn't do range checks. unsafeTail :: MVector v a => v s a -> v s a {-# INLINE unsafeTail #-} unsafeTail v = unsafeSlice 1 (length v - 1) v +-- | Unsafe variant of 'take'. If called with out of range @n@ it will +-- simply create invalid slice that likely violate memory safety unsafeTake :: MVector v a => Int -> v s a -> v s a {-# INLINE unsafeTake #-} unsafeTake n v = unsafeSlice 0 n v +-- | Unsafe variant of 'drop'. If called with out of range @n@ it will +-- simply create invalid slice that likely violate memory safety unsafeDrop :: MVector v a => Int -> v s a -> v s a {-# INLINE unsafeDrop #-} unsafeDrop n v = unsafeSlice n (length v - n) v diff --git a/vector/src/Data/Vector/Mutable.hs b/vector/src/Data/Vector/Mutable.hs index 7b301281..b1b430c6 100644 --- a/vector/src/Data/Vector/Mutable.hs +++ b/vector/src/Data/Vector/Mutable.hs @@ -231,10 +231,16 @@ slice :: Int -- ^ @i@ starting index {-# INLINE slice #-} slice = G.slice +-- | Take @n@ first elements of the mutable vector without making a +-- copy. For negative @n@ empty vector is returned. If @n@ is larger +-- than vector's length empty vector is returned, take :: Int -> MVector s a -> MVector s a {-# INLINE take #-} take = G.take +-- | Drop @n@ first element of the mutable vector without making a +-- copy. For negative @n@ vector is returned unchanged and if @n@ is +-- larger than vector's length empty vector is returned. drop :: Int -> MVector s a -> MVector s a {-# INLINE drop #-} drop = G.drop @@ -243,10 +249,14 @@ drop = G.drop splitAt :: Int -> MVector s a -> (MVector s a, MVector s a) splitAt = G.splitAt +-- | Drop last element of the mutable vector without making a copy. If +-- vector is empty exception is thrown. init :: MVector s a -> MVector s a {-# INLINE init #-} init = G.init +-- | Drop first element of the mutable vector without making a copy. If +-- vector is empty exception is thrown. tail :: MVector s a -> MVector s a {-# INLINE tail #-} tail = G.tail @@ -260,18 +270,24 @@ unsafeSlice :: Int -- ^ starting index {-# INLINE unsafeSlice #-} unsafeSlice = G.unsafeSlice +-- | Unsafe variant of 'take'. If called with out of range @n@ it will +-- simply create invalid slice that likely violate memory safety unsafeTake :: Int -> MVector s a -> MVector s a {-# INLINE unsafeTake #-} unsafeTake = G.unsafeTake +-- | Unsafe variant of 'drop'. If called with out of range @n@ it will +-- simply create invalid slice that likely violate memory safety unsafeDrop :: Int -> MVector s a -> MVector s a {-# INLINE unsafeDrop #-} unsafeDrop = G.unsafeDrop +-- | Same as 'init' but doesn't do range checks. unsafeInit :: MVector s a -> MVector s a {-# INLINE unsafeInit #-} unsafeInit = G.unsafeInit +-- | Same as 'tail' but doesn't do range checks. unsafeTail :: MVector s a -> MVector s a {-# INLINE unsafeTail #-} unsafeTail = G.unsafeTail diff --git a/vector/src/Data/Vector/Primitive/Mutable.hs b/vector/src/Data/Vector/Primitive/Mutable.hs index 7c64e6ac..c15df12f 100644 --- a/vector/src/Data/Vector/Primitive/Mutable.hs +++ b/vector/src/Data/Vector/Primitive/Mutable.hs @@ -191,10 +191,16 @@ slice :: Prim a {-# INLINE slice #-} slice = G.slice +-- | Take @n@ first elements of the mutable vector without making a +-- copy. For negative @n@ empty vector is returned. If @n@ is larger +-- than vector's length empty vector is returned, take :: Prim a => Int -> MVector s a -> MVector s a {-# INLINE take #-} take = G.take +-- | Drop @n@ first element of the mutable vector without making a +-- copy. For negative @n@ vector is returned unchanged and if @n@ is +-- larger than vector's length empty vector is returned. drop :: Prim a => Int -> MVector s a -> MVector s a {-# INLINE drop #-} drop = G.drop @@ -203,10 +209,14 @@ splitAt :: Prim a => Int -> MVector s a -> (MVector s a, MVector s a) {-# INLINE splitAt #-} splitAt = G.splitAt +-- | Drop last element of the mutable vector without making a copy. If +-- vector is empty exception is thrown. init :: Prim a => MVector s a -> MVector s a {-# INLINE init #-} init = G.init +-- | Drop first element of the mutable vector without making a copy. If +-- vector is empty exception is thrown. tail :: Prim a => MVector s a -> MVector s a {-# INLINE tail #-} tail = G.tail @@ -221,18 +231,24 @@ unsafeSlice :: Prim a {-# INLINE unsafeSlice #-} unsafeSlice = G.unsafeSlice +-- | Unsafe variant of 'take'. If called with out of range @n@ it will +-- simply create invalid slice that likely violate memory safety unsafeTake :: Prim a => Int -> MVector s a -> MVector s a {-# INLINE unsafeTake #-} unsafeTake = G.unsafeTake +-- | Unsafe variant of 'drop'. If called with out of range @n@ it will +-- simply create invalid slice that likely violate memory safety unsafeDrop :: Prim a => Int -> MVector s a -> MVector s a {-# INLINE unsafeDrop #-} unsafeDrop = G.unsafeDrop +-- | Same as 'init' but doesn't do range checks. unsafeInit :: Prim a => MVector s a -> MVector s a {-# INLINE unsafeInit #-} unsafeInit = G.unsafeInit +-- | Same as 'tail' but doesn't do range checks. unsafeTail :: Prim a => MVector s a -> MVector s a {-# INLINE unsafeTail #-} unsafeTail = G.unsafeTail diff --git a/vector/src/Data/Vector/Storable/Mutable.hs b/vector/src/Data/Vector/Storable/Mutable.hs index 77000c19..80d10d12 100644 --- a/vector/src/Data/Vector/Storable/Mutable.hs +++ b/vector/src/Data/Vector/Storable/Mutable.hs @@ -287,10 +287,16 @@ slice :: Storable a {-# INLINE slice #-} slice = G.slice +-- | Take @n@ first elements of the mutable vector without making a +-- copy. For negative @n@ empty vector is returned. If @n@ is larger +-- than vector's length empty vector is returned, take :: Storable a => Int -> MVector s a -> MVector s a {-# INLINE take #-} take = G.take +-- | Drop @n@ first element of the mutable vector without making a +-- copy. For negative @n@ vector is returned unchanged and if @n@ is +-- larger than vector's length empty vector is returned. drop :: Storable a => Int -> MVector s a -> MVector s a {-# INLINE drop #-} drop = G.drop @@ -299,10 +305,14 @@ splitAt :: Storable a => Int -> MVector s a -> (MVector s a, MVector s a) {-# INLINE splitAt #-} splitAt = G.splitAt +-- | Drop last element of the mutable vector without making a copy. If +-- vector is empty exception is thrown. init :: Storable a => MVector s a -> MVector s a {-# INLINE init #-} init = G.init +-- | Drop first element of the mutable vector without making a copy. If +-- vector is empty exception is thrown. tail :: Storable a => MVector s a -> MVector s a {-# INLINE tail #-} tail = G.tail @@ -317,18 +327,24 @@ unsafeSlice :: Storable a {-# INLINE unsafeSlice #-} unsafeSlice = G.unsafeSlice +-- | Unsafe variant of 'take'. If called with out of range @n@ it will +-- simply create invalid slice that likely violate memory safety unsafeTake :: Storable a => Int -> MVector s a -> MVector s a {-# INLINE unsafeTake #-} unsafeTake = G.unsafeTake +-- | Unsafe variant of 'drop'. If called with out of range @n@ it will +-- simply create invalid slice that likely violate memory safety unsafeDrop :: Storable a => Int -> MVector s a -> MVector s a {-# INLINE unsafeDrop #-} unsafeDrop = G.unsafeDrop +-- | Same as 'init' but doesn't do range checks. unsafeInit :: Storable a => MVector s a -> MVector s a {-# INLINE unsafeInit #-} unsafeInit = G.unsafeInit +-- | Same as 'tail' but doesn't do range checks. unsafeTail :: Storable a => MVector s a -> MVector s a {-# INLINE unsafeTail #-} unsafeTail = G.unsafeTail diff --git a/vector/src/Data/Vector/Unboxed/Mutable.hs b/vector/src/Data/Vector/Unboxed/Mutable.hs index 5543b76e..208f4abf 100644 --- a/vector/src/Data/Vector/Unboxed/Mutable.hs +++ b/vector/src/Data/Vector/Unboxed/Mutable.hs @@ -102,10 +102,16 @@ slice :: Unbox a {-# INLINE slice #-} slice = G.slice +-- | Take @n@ first elements of the mutable vector without making a +-- copy. For negative @n@ empty vector is returned. If @n@ is larger +-- than vector's length empty vector is returned, take :: Unbox a => Int -> MVector s a -> MVector s a {-# INLINE take #-} take = G.take +-- | Drop @n@ first element of the mutable vector without making a +-- copy. For negative @n@ vector is returned unchanged and if @n@ is +-- larger than vector's length empty vector is returned. drop :: Unbox a => Int -> MVector s a -> MVector s a {-# INLINE drop #-} drop = G.drop @@ -114,10 +120,14 @@ splitAt :: Unbox a => Int -> MVector s a -> (MVector s a, MVector s a) {-# INLINE splitAt #-} splitAt = G.splitAt +-- | Drop last element of the mutable vector without making a copy. If +-- vector is empty exception is thrown. init :: Unbox a => MVector s a -> MVector s a {-# INLINE init #-} init = G.init +-- | Drop first element of the mutable vector without making a copy. If +-- vector is empty exception is thrown. tail :: Unbox a => MVector s a -> MVector s a {-# INLINE tail #-} tail = G.tail @@ -132,18 +142,24 @@ unsafeSlice :: Unbox a {-# INLINE unsafeSlice #-} unsafeSlice = G.unsafeSlice +-- | Unsafe variant of 'take'. If called with out of range @n@ it will +-- simply create invalid slice that likely violate memory safety unsafeTake :: Unbox a => Int -> MVector s a -> MVector s a {-# INLINE unsafeTake #-} unsafeTake = G.unsafeTake +-- | Unsafe variant of 'drop'. If called with out of range @n@ it will +-- simply create invalid slice that likely violate memory safety unsafeDrop :: Unbox a => Int -> MVector s a -> MVector s a {-# INLINE unsafeDrop #-} unsafeDrop = G.unsafeDrop +-- | Same as 'init' but doesn't do range checks. unsafeInit :: Unbox a => MVector s a -> MVector s a {-# INLINE unsafeInit #-} unsafeInit = G.unsafeInit +-- | Same as 'tail' but doesn't do range checks. unsafeTail :: Unbox a => MVector s a -> MVector s a {-# INLINE unsafeTail #-} unsafeTail = G.unsafeTail