From 037e5cb4f8ac8ad7f204bd1fc366698ba85b9d31 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 --- Data/Vector/Generic/Mutable.hs | 16 ++++++++++++++++ Data/Vector/Mutable.hs | 16 ++++++++++++++++ Data/Vector/Primitive/Mutable.hs | 16 ++++++++++++++++ Data/Vector/Storable/Mutable.hs | 16 ++++++++++++++++ Data/Vector/Unboxed/Mutable.hs | 16 ++++++++++++++++ 5 files changed, 80 insertions(+) diff --git a/Data/Vector/Generic/Mutable.hs b/Data/Vector/Generic/Mutable.hs index c878064e..38a2d8f6 100644 --- a/Data/Vector/Generic/Mutable.hs +++ b/Data/Vector/Generic/Mutable.hs @@ -526,10 +526,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 @@ -547,10 +553,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 @@ -565,18 +575,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/Data/Vector/Mutable.hs b/Data/Vector/Mutable.hs index c53c3040..4e07fc82 100644 --- a/Data/Vector/Mutable.hs +++ b/Data/Vector/Mutable.hs @@ -229,10 +229,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 @@ -241,10 +247,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 @@ -258,18 +268,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/Data/Vector/Primitive/Mutable.hs b/Data/Vector/Primitive/Mutable.hs index 051e1d14..6f0f20f8 100644 --- a/Data/Vector/Primitive/Mutable.hs +++ b/Data/Vector/Primitive/Mutable.hs @@ -171,10 +171,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 @@ -183,10 +189,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 @@ -201,18 +211,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/Data/Vector/Storable/Mutable.hs b/Data/Vector/Storable/Mutable.hs index afac3742..11d928ff 100644 --- a/Data/Vector/Storable/Mutable.hs +++ b/Data/Vector/Storable/Mutable.hs @@ -300,10 +300,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 @@ -312,10 +318,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 @@ -330,18 +340,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/Data/Vector/Unboxed/Mutable.hs b/Data/Vector/Unboxed/Mutable.hs index a702f842..e3ab74d7 100644 --- a/Data/Vector/Unboxed/Mutable.hs +++ b/Data/Vector/Unboxed/Mutable.hs @@ -100,10 +100,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 @@ -112,10 +118,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 @@ -130,18 +140,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