function s = replaceBetween(str, start, stop, value, varargin)
% REPLACEBETWEEN Replace bounded substring in string elements
%    S = REPLACEBETWEEN(STR, START_PAT, END_PAT, NEW) replaces the
%    substring in STR that occurs between START_PAT and END_PAT with
%    NEW but does not replace START_PAT and END_PAT themselves. If
%    multiple nonoverlapping START_PAT and END_PAT pairs are found, the
%    characters between each pair are replaced.
% 
%    S = REPLACEBETWEEN(STR, START_POS, END_POS, NEW) replaces the
%    substrings in STR that occur between numeric positions START_POS and
%    END_POS, including the characters at those positions, with NEW.
%    START_POS and END_POS must be integers between 1 and the number of
%    characters in STR. If START_POS and END_POS are the same number, then
%    REPLACEBETWEEN replaces the character at START_POS. If END_POS equals
%    START_POS - 1, then REPLACEBETWEEN does not replace any characters but
%    does insert NEW between START_POS and END_POS.
%
%    NOTES: 
%    * STR and NEW must be text, which means they can be a string array,
%      a character vector, or a cell array of character vectors. START_PAT 
%      and END_PAT must be text or a pattern array. The output S has the 
%      same data type as STR.
% 
%    * START_PAT and END_PAT are an open set (i.e., bounds
%      are included in the output) while the START_POS and END_POS numeric
%      positions are a closed set (i.e., bounds are not included in the
%      output).
%
%    * Position, text, and pattern bounds can be mixed. Their inclusivity persists
%      with the argument type.
%
%    S = REPLACEBETWEEN(..., 'Boundaries', B) forces the bounds to be
%    inclusive when B is 'inclusive' and forces the bounds to be exclusive
%    when B is 'exclusive'.
%
%    If B is 'exclusive' and you specify numeric bounds, then START_POS and
%    END_POS can be integers between 0 and strlength(STR) + 1.
%
%    Examples:
%        STR = "The quick brown fox jumps";
%        START_PAT = 'quick';
%        END_PAT = 'fox';
%        NEW = ' red ';
%        replaceBetween(STR,START_PAT,END_PAT,NEW)
%
%        % returns "The quick red fox jumps"
%
%        STR = 'The quick brown fox jumps over the lazy dog';
%        START_PAT = 'jumps';
%        END_PAT = 'lazy';
%        NEW = 'sneaks by the sleeping';
%        replaceBetween(STR,START_PAT,END_PAT,NEW,'Boundaries','inclusive')
%
%        % returns 'The quick brown fox sneaks by the sleeping dog'
%
%        STR = 'The quick brown fox jumps over the lazy dog';
%        START_PAT = textBoundary + lettersPattern;
%        END_PAT = lettersPattern + textBoundary;
%        NEW = ' ';
%        replaceBetween(STR,START_PAT,END_PAT,NEW)
%
%        % returns 'The dog'
%
%    See also REPLACE, ERASE, ERASEBETWEEN, EXTRACTBETWEEN, PATTERN

%   Copyright 2016-2020 The MathWorks, Inc.

    narginchk(4, Inf);
    
    if ~isTextStrict(str)
        error(fillMessageHoles('MATLAB:string:MustBeCharCellArrayOrString',...
                               'MATLAB:string:FirstInput'));
    end

    try
        s = string(str);
        
        if nargin == 4
            s = s.replaceBetween(start, stop, value);
        else
            s = s.replaceBetween(start, stop, value, varargin{:});
        end
        
        s = convertStringToOriginalTextType(s, str);
        
    catch ex
        if strcmp(ex.identifier, 'MATLAB:string:CannotConvertMissingElementToChar')
            error(fillMessageHoles('MATLAB:string:CannotInsertMissingIntoChar',...
                                   'MATLAB:string:MissingDisplayText'));
        end
        ex.throw;
    end
end
