------------------------------------------------------------------------------
-- Copyright (c) 2011, Natacha Porté --
-- --
-- Permission to use, copy, modify, and distribute this software for any --
-- purpose with or without fee is hereby granted, provided that the above --
-- copyright notice and this permission notice appear in all copies. --
-- --
-- THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES --
-- WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF --
-- MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR --
-- ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES --
-- WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN --
-- ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF --
-- OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. --
------------------------------------------------------------------------------
------------------------------------------------------------------------------
-- Natools.Accumulators is a collection of interfaces for data structures --
-- that allow efficient accumulation of data. --
-- --
-- String_Accumulator is meant for creation of long strings through --
-- repeated calls of Append, and later retrieval of the full buffer through --
-- one of the To_String subprograms. Length, Tail and Unappend are --
-- helper utilities that might not be very efficient but can occasionnally --
-- be useful. Hard_Reset and Soft_Reset both clear the internal state, with --
-- Soft_Reset aimed for speed while Hard_Reset aims for best memory release --
-- --
-- String_Accumulator_Stack adds a stack structure on top of --
-- String_Accumulator, to allow temporary substrings to be created using --
-- similar facilities. All operations on String_Accumulator except --
-- Hard_Reset and Soft_Reset, when applied to String_Accumulator_Stack, are --
-- meant to be forwarded to the top accumulator of the stack. Push and Pop --
-- change the stack state, while Hard_Reset and Soft_Reset apply to the --
-- whole stack, with the same semantics as for String_Accumulator. --
------------------------------------------------------------------------------
package Natools.Accumulators is
pragma Pure (Accumulators);
type String_Accumulator is interface;
procedure Append (To : in out String_Accumulator; Text : String)
is abstract;
-- Append the given String to the internal buffer
procedure Hard_Reset (Acc : in out String_Accumulator)
is abstract;
-- Empty the internal buffer and free all possible memory
function Length (Acc : String_Accumulator) return Natural
is abstract;
-- Return the length of the internal buffer
procedure Soft_Reset (Acc : in out String_Accumulator)
is abstract;
-- Empty the internal buffer for reuse
function Tail (Acc : String_Accumulator; Size : Natural) return String
is abstract;
-- Return the last characters from the internal buffer
function To_String (Acc : String_Accumulator) return String
is abstract;
-- Output the whole internal buffer as a String
procedure To_String (Acc : String_Accumulator; Output : out String)
is abstract;
-- Write the whole internal buffer into the String, which must be
-- large enough.
procedure Unappend (From : in out String_Accumulator; Text : String)
is abstract;
-- Remove the given suffix from the internal buffer
-- Do nothing if the given text is not a prefix the internal buffer
type String_Accumulator_Stack is interface and String_Accumulator;
procedure Push (Acc : in out String_Accumulator_Stack)
is abstract;
-- Push the current internal buffer and start with an empty one
procedure Pop (Acc : in out String_Accumulator_Stack)
is abstract;
-- Drop the current internal buffer and use the previsouly pushed one
-- instead
-- Raise Program_Error when trying to pop the last internal buffer
end Natools.Accumulators;