Add RingArray module

Author: harendra-kumar

core/src/Streamly/Data/Array.hs

@@ -107,8 +107,6 @@ module Streamly.Data.Array
     )
 where
 
-#include "inline.hs"
-
 import Streamly.Internal.Data.Array
 import Streamly.Internal.Data.MutByteArray (Unbox(..), Serialize(..))
 

core/src/Streamly/Data/RingArray.hs

@@ -0,0 +1,95 @@
+{-# LANGUAGE CPP #-}
+-- |
+-- Module      : Streamly.Data.RingArray
+-- Copyright   : (c) 2025 Composewell Technologies
+--
+-- License     : BSD3
+-- Maintainer  : streamly@composewell.com
+-- Stability   : released
+-- Portability : GHC
+--
+-- This module provides APIs to create and use unboxed, mutable ring arrays of
+-- fixed size. Ring arrays are useful to keep a circular buffer or a sliding
+-- window of elements.
+--
+-- RingArrays are of fixed size but there is a way to expand the size of the
+-- ring, you can copy the ring to a MutArray, expand the MutArray and the cast
+-- it back to RingArray.
+--
+-- This module is designed to be imported qualified:
+--
+-- >>> import qualified Streamly.Data.RingArray as Ring
+--
+-- For ring arrays that work on boxed types, not requiring the 'Unbox'
+-- constraint, please refer to "Streamly.Data.RingArray.Generic".
+--
+-- Please refer to "Streamly.Internal.Data.RingArray" for functions that have
+-- not yet been released.
+--
+
+module Streamly.Data.RingArray
+    ( RingArray
+
+    -- * Construction
+    , createOfLast
+    , castMutArray -- XXX this is unsafeFreeze in Array module
+    , castMutArrayWith
+    -- , unsafeCastMutArray
+    -- , unsafeCastMutArrayWith
+
+    -- * Moving the Head
+    , moveForward
+    , moveReverse
+    -- , moveBy
+
+    -- * In-place Mutation
+    , insert
+    , replace
+    , replace_
+    , putIndex
+    , modifyIndex
+
+    -- * Random Access
+    , getIndex
+    , unsafeGetIndex
+    , unsafeGetHead
+
+    -- * Conversion
+    , toList
+    , toMutArray
+
+    -- * Streams
+    , read
+    , readRev
+
+    -- * Unfolds
+    , reader
+    , readerRev
+
+    -- * Size
+    , length
+    , byteLength
+
+    -- * Casting
+    , cast
+    -- , unsafeCast
+    , asBytes
+    , asMutArray
+    -- , asMutArray_
+
+    -- * Folds
+    -- , foldlM'
+    , fold
+
+    -- * Stream of Rings
+    , ringsOf
+    , scanRingsOf
+
+    -- * Fast Byte Comparisons
+    , eqArray
+    , eqArrayN
+
+    ) where
+
+import Streamly.Internal.Data.RingArray
+import Prelude hiding (read, length)

core/src/Streamly/Internal/Data/RingArray.hs

@@ -292,7 +292,7 @@ unsafeCastMutArray = unsafeCastMutArrayWith 0
 -- the ring head at @index@ position in the array.
 --
 -- This operation throws an error if the index is not within the array bounds.
--- It returns Nothing if the array cannot be cast into ring because the array
+-- It returns 'Nothing' if the array cannot be cast into ring because the array
 -- is a slice. In that case clone the array and cast it or stream the array and
 -- use 'createOfLast' to create a ring.
 --
@@ -306,8 +306,10 @@ castMutArrayWith i arr
     | otherwise = Nothing
 
 -- | Cast a MutArray to a ring sharing the same memory without copying. The
--- ring head is at index 0 of the array. Cast fails with Nothing if the array
--- is a slice.
+-- ring head is at index 0 of the array. The size of the ring is equal to the
+-- MutArray length.
+--
+-- See 'castMutArrayWith' for failure scenario.
 --
 -- >>> castMutArray = RingArray.castMutArrayWith 0
 --
@@ -832,6 +834,10 @@ asMutArray rb =
     , ringHead rb
     )
 
+-- | Like 'asMutArray' but does not return the ring head.
+--
+-- >>> asMutArray_ = fst . RingArray.asMutArray
+--
 {-# INLINE asMutArray_ #-}
 asMutArray_ :: RingArray a -> MutArray a
 asMutArray_ rb =

core/streamly-core.cabal

@@ -455,7 +455,6 @@ library
 
                      -- Pre-release modules
                      -- , Streamly.Data.Pipe
-                     -- , Streamly.Data.RingArray
                      -- , Streamly.Data.RingArray.Generic
                      -- , Streamly.Data.IORef
                      -- , Streamly.Data.List
@@ -466,18 +465,18 @@ library
                      -- , Streamly.Data.Either.Strict
 
                      -- streamly-core released modules in alphabetic order
-                     -- NOTE: these must be added to streamly.cabal as well
                      , Streamly.Console.Stdio
                      , Streamly.Control.Exception
-                     , Streamly.Data.MutByteArray
                      , Streamly.Data.Array
                      , Streamly.Data.Array.Generic
+                     , Streamly.Data.Fold
                      , Streamly.Data.MutArray
                      , Streamly.Data.MutArray.Generic
-                     , Streamly.Data.Fold
-                     , Streamly.Data.Scanl
+                     , Streamly.Data.MutByteArray
                      , Streamly.Data.Parser
                      , Streamly.Data.ParserK
+                     , Streamly.Data.RingArray
+                     , Streamly.Data.Scanl
                      , Streamly.Data.Stream
                      , Streamly.Data.StreamK
                      , Streamly.Data.Unfold