## Copyright (C) 2006 Bill Denney
##
## This file is part of Octave.
##
## Octave 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; either version 2, or (at your option)
## any later version.
##
## Octave 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 Octave; see the file COPYING.  If not, write to the Free
## Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
## 02110-1301, USA.

## -*- texinfo -*-
## @deftypefn {Function File} @var{string} = regexprep(@var{string}, @var{pat}, @var{repstr}, @var{options})
## Replace matches of @var{pat} in @var{string} with @var{repstr}.
##
## @var{options} may be zero or more of
## @table @samp
## @item N
## Replace the Nth match of @var{pat}.
##
## @item ignorecase
## Ignore case for the pattern matching (see @code{regexpi}).
## 
## @item once
## Replace only the first occurance of @var{pat} in the result. (The
## same effect as @var{N} = 1, but more efficient behind the scenes.)
##
## @item warnings
## This option is ignored, but it does not give an error.
##
## @end table
## @seealso{regexp,regexpi}
## @end deftypefn

function string = regexprep(string, pat, repstr, varargin)

  ## Parse input arguements

  n = -1;
  once = 0;
  ignorecase = 0;
  for i = 1:length(varargin)
    if isnumeric(varargin{i})
      if (varargin{i} < 0)
	warning("regexprep: negative value for N given; all matches will be replaced");
      endif

      if (n < 0)
	n = varargin{i};
      else
	error("regexprep: conflicting options given for N");
      endif
    elseif strcmpi(varargin{i}, "ignorecase")
      ignorecase = 1;
    elseif strcmpi(varargin{i}, "once")
      once = 1;
    elseif strcmpi(varargin{i}, "warnings") ## for compatability
    else
      ## I could do more type checking here, but it will just throw an
      ## error for things like cells or other types, and that's OK by
      ## me.
      error("regexprep: Unrecognised option '%s'", varargin{i});
    endif
  endfor

  if ((n > 1) && once)
    error("regexprep: once option was given, and a value for N other than 1 was given");
  endif

  ## Do the matching and replacing

  ## choose how to invoke regexp
  options = {};
  if (once)
    options(end+1) = 'once';
  endif

  if (ignorecase)
    [st, en] = regexpi(string, pat, options{:});
  else
    [st, en] = regexp(string, pat, options{:});
  endif

  if (n > 0)
    if (length(st) >= n)
      st = st(n);
    else
      warning("regexprep: fewer matches than N, original string returned");
      st = [];
    endif
  endif

  for i = length(st):-1:1
    string = [string(1:st(i)-1) repstr string(en(i)+1:length(string))];
  endfor

endfunction

## Tests

## Test a general replacement
%!assert(regexprep("a[b]c{d}e-f=g", "[^A-Za-z0-9_]", "_"), "a_b_c_d_e_f_g");

## Make sure it works at the beginning and end
%!assert(regexprep("a[b]c{d}e-f=g", "a", "_"), "_[b]c{d}e-f=g");
%!assert(regexprep("a[b]c{d}e-f=g", "g", "_"), "a[b]c{d}e-f=_");

## Options
%!assert(regexprep("a[b]c{d}e-f=g", "[^A-Za-z0-9_]", "_", "once"), "a_b]c{d}e-f=g");
%!assert(regexprep("a[b]c{d}e-f=g", "[^A-Z0-9_]", "_", "ignorecase"), "a_b_c_d_e_f_g");
%!assert(regexprep("a[b]c{d}e-f=g", "[^A-Za-z0-9_]", "_", 2), "a[b_c{d}e-f=g");

## Option combinations
%!assert(regexprep("a[b]c{d}e-f=g", "[^A-Z0-9_]", "_", "once", "ignorecase"), "a_b]c{d}e-f=g");
%!assert(regexprep("a[b]c{d}e-f=g", "[^A-Z0-9_]", "_", 3, "ignorecase"), "a[b]c_d}e-f=g");
%!fail(regexprep("a[b]c{d}e-f=g", "[^A-Z0-9_]", "_", 3, "once"), "regexprep: once option was given, and a value for N other than 1 was given");