%--------------------------------------------------%
% vim: ft=mercury ts=4 sw=4 et
%--------------------------------------------------%
% Copyright (C) 2006-2007 The University of Melbourne.
% Copyright (C) 2014-2015, 2018, 2022-2024 The Mercury team.
% This file is distributed under the terms specified in COPYING.LIB.
%--------------------------------------------------%
%
% File: string.builder.m.
% Main author: maclarty.
%
% This module implements a string builder stream. It can be used
% to build up a string using string or character writers.
%
% To build up a string using this module, you first construct an initial
% string builder state by calling the init function. You can then use
% any instances of stream.writer that write strings or characters to update the
% string builder state, using string.builder.handle as the stream argument.
% Once you have finished writing to the string builder, you can get the final
% string by calling string.builder.to_string/1.
%
% For example:
%
%     State0 = string.builder.init,
%     stream.string_writer.put_int(string.builder.handle, 5, State0, State),
%     Str = string.builder.to_string(State),  % Str = "5".
%
%--------------------------------------------------%

:- module string.builder.
:- interface.

:- import_module char.
:- import_module stream.

%--------------------------------------------------%

:- type handle
    --->    handle.

:- type state.

:- func init = (string.builder.state::uo) is det.

    % Add a character to the end of the string builder.
    %
:- pred append_char(char::in,
    string.builder.state::di, string.builder.state::uo) is det.

    % Add a string to the end of the string builder.
    %
:- pred append_string(string::in,
    string.builder.state::di, string.builder.state::uo) is det.

    % Add a list of strings to the end of the string builder.
    %
:- pred append_strings(list(string)::in,
    string.builder.state::di, string.builder.state::uo) is det.

    % append_strings_sep(Sep, Strings, !State):
    %
    % Add a list of strings to the end of the string builder,
    % with the given separator string between each pair.
    %
:- pred append_strings_sep(string::in, list(string)::in,
    string.builder.state::di, string.builder.state::uo) is det.

%--------------------------------------------------%

:- pred format(string::in, list(poly_type)::in,
    string.builder.state::di, string.builder.state::uo) is det.

%--------------------------------------------------%

    % Return the total number of code points in the string that
    % to_string would return, without constructing that string (yet).
    %
    % Note that once you call this function, you cannot add any new entries
    % to the given string builder state, because it loses its uniqueness.
    %
:- func total_num_code_points(string.builder.state) = int.

    % Succeed if and only if the total number of code points in the string
    % that to_string would return is at most the given number. Determine this
    % without constructing that string (yet).
    %
    % Note that once you call this predicate, you cannot add any new entries
    % to the given string builder state, because it loses its uniqueness.
    %
:- pred total_num_code_points_is_at_most(string.builder.state::in, int::in)
    is semidet.

%--------------------------------------------------%

    % Return the string that the previous calls to append_* constructed.
    %
:- func to_string(string.builder.state::in) = (string::uo) is det.

%--------------------------------------------------%

:- instance stream.stream(string.builder.handle, string.builder.state).

:- instance stream.output(string.builder.handle, string.builder.state).

:- instance stream.writer(string.builder.handle, string, string.builder.state).
:- instance stream.writer(string.builder.handle, char, string.builder.state).

%--------------------------------------------------%
%--------------------------------------------------%