% -*- texinfo -*-
% @deftypefn {Function File} {@var{varname} =} genvarname (@var{str})
% @deftypefnx {Function File} {@var{varname} =} genvarname (@var{str}, @var{exclusions})
% Create unique variable(s) from @var{str}. If @var{exclusions} is
% given, then the variable(s) will be unique to each other and to
% @var{exclusions} (@var{exclusions} may be either a string or a cellstr).
%
% If @var{str} is a cellstr, then a unique variable is created for each
% cell in @var{str}.
%
% @example
% @group
% x = 3.141;
% genvarname ('x', who )
% @result{} x1
% @end group
% @end example
%
% If @var{wanted} is a cell array, genvarname will make sure the returned
% strings are distinct:
%
% @example
% @group
% genvarname (@{'foo', 'foo'@})
% @result{}
% @{
% [1,1] = foo
% [1,2] = foo1
% @}
% @end group
% @end example
%
% Note that the result is a char array/cell array of strings, not the
% variables themselves. To define a variable, @code{eval} can be
% used. The following trivial example sets @code{x} to @code{42}.
%
% @example
% @group
% name = genvarname ('x');
% eval([name ' = 42']);
% @result{} x = 42
% @end group
% @end example
%
% Also, this can be useful for creating unique struct field names.
%
% @example
% @group
% x = struct ;
% for i = 1:3
% x.(genvarname ('a', fieldnames (x))) = i;
% end
% @result{}
% x =
% @{
% a = 1
% a1 = 2
% a2 = 3
% @}
% @end group
% @end example
%
% Since variable names may only contain letters, digits and underscores,
% genvarname replaces any sequence of disallowed characters with
% an underscore. Also, variables may not begin with a digit; in this
% case an underscore is added before the variable name.
%
% Variable names beginning and ending with two underscores '__' are valid but
% they are used internally by octave and should generally be avoided, therefore
% genvarname will not generate such names.
%
% genvarname will also make sure that returned names do not clash with
% keywords such as 'for' and 'if'. A number will be appended if necessary.
% Note, however, that this does @strong{not} include function names,
% such as 'sin'. Such names should be included in @var{avoid} if necessary.
% @seealso{isvarname, exist, tmpnam, eval}
% @end deftypefn