container/Circular_Buffer.fz

# This file is part of the Fuzion language implementation.
#
# The Fuzion language implementation is free software: you can redistribute it
# and/or modify it under the terms of the GNU General Public License as published
# by the Free Software Foundation, version 3 of the License.
#
# The Fuzion language implementation is distributed in the hope that it will be
# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
# License for more details.
#
# You should have received a copy of the GNU General Public License along with The
# Fuzion language implementation.  If not, see <https://www.gnu.org/licenses/>.


# -----------------------------------------------------------------------
#
#  Tokiwa Software GmbH, Germany
#
#  Source code of Fuzion standard library feature Circular_Buffer
#
# -----------------------------------------------------------------------

# Circular_Buffer -- a circular buffer-like structure
#
# buffer to which elements can be enqueued and retrieved with a FIFO
# logic.
#
# it is usually backed by a fixed length array.
#
module:public Circular_Buffer
  (# type of elements stored in this buffer
   T type,

   # effect used to modify this buffer
   E type : effect) ref

is


  # length of this buffer.
  #
  public length i64 => abstract


  # amount of elements free for writing
  #
  public available i64 =>
    abstract


  # amount of elements available for reading
  public buffered i64 =>
    abstract


  # enqueue a single element into the buffer
  #
  # returns an error if the new element does not fit into the
  # buffer
  #
  public put (e T) outcome unit =>
    abstract


  # read a single element from the buffer
  #
  public get option T =>
    abstract


  # enqueue data into the buffer
  #
  # returns an error if the given sequence is too long to fit into
  # the buffer entirely
  #
  public enqueue (s Sequence T) outcome unit =>
    abstract


  # read elements from the buffer
  #
  public flush (n i64) array T
  pre
    debug: n ≤ buffered
  => abstract


  # create immutable array from this buffer
  #
  public as_array array T ! E =>
    abstract


  # create a list from this buffer
  #
  public as_list list T =>
    # since buffer is mutable,
    # we first copy the elements
    # to an immutable array.
    as_array.as_list


  # the current state of the buffer
  # as a string.
  #
  public redef as_string String => as_array.as_string