Mercurial > octave
view scripts/general/genvarname.m @ 14327:4d917a6a858b stable
doc: Use Octave coding conventions in @example blocks of docstrings.
* accumarray.m, accumdim.m, bar.m, base2dec.m, bincoeff.m, bitcmp.m, bitset.m,
celldisp.m, chop.m, clabel.m, cloglog.m, colon.m, compass.m, computer.m,
contour3.m, contourc.m, corr.m, cstrcat.m, ctime.m, cylinder.m, date.m,
dec2base.m, demo.m, dir.m, dlmwrite.m, expm.m, ezcontourf.m, ezcontour.m,
ezmeshc.m, ezmesh.m, ezplot.m, ezsurfc.m, ezsurf.m, feather.m, findobj.m,
flipdim.m, fplot.m, genvarname.m, getfield.m, hankel.m, hilb.m, hist.m,
idivide.m, index.m, int2str.m, interp1.m, is_leap_year.m, ismember.m,
isocolors.m, isonormals.m, isosurface.m, kurtosis.m, legendre.m, linkprop.m,
logit.m, logm.m, __makeinfo__.m, __marching_cube__.m, median.m, mkoctfile.m,
moment.m, mpoles.m, orderfields.m, pcg.m, pcr.m, plot3.m, plotmatrix.m,
polyaffine.m, polygcd.m, poly.m, polyout.m, print.m, qp.m, quadgk.m, qzhess.m,
randi.m, rat.m, refreshdata.m, residue.m, rose.m, rot90.m, saveas.m, saveobj.m,
shiftdim.m, skewness.m, spaugment.m, spdiags.m, sqp.m, stem.m, str2num.m,
strcat.m, strjust.m, strread.m, strsplit.m, structfun.m, subplot.m,
subsindex.m, substruct.m, surfl.m, surfnorm.m, svds.m, uimenu.m, union.m,
voronoi.m, warning_ids.m, wblpdf.m: Use Octave coding conventions in
@example blocks of docstrings.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Sat, 04 Feb 2012 22:12:50 -0800 |
parents | 72c96de7a403 |
children | f3d52523cde1 |
line wrap: on
line source
## Copyright (C) 2008-2012 Bill Denney, Robert Platt ## ## 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 3 of the License, 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, see ## <http://www.gnu.org/licenses/>. ## -*- 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; ## endfor ## @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 ## Authors: Rob Platt <robert.platt@postgrad.manchester.ac.uk> ## Bill Denney <bill@denney.ws> function varname = genvarname (str, exclusions) strinput = ischar (str); ## Process the inputs if (nargin < 2) exclusions = {}; elseif (ischar (exclusions)) if (rows (exclusions) != 1) error ("genvarname: if more than one exclusion is given, it must be a cellstr"); endif exclusions = {exclusions}; elseif (! iscellstr (exclusions)) error ("genvarname: EXCLUSIONS must be a string or a cellstr"); endif if (ischar (str)) if (rows (str) != 1) error ("genvarname: if more than one STR is given, it must be a cellstr"); endif str = {str}; elseif (! iscellstr (str)) error ("genvarname: STR must be a string or a cellstr"); endif validchars = cstrcat ("A":"Z", "a":"z", "0":"9", "_"); varname = cell (size (str)); for i = 1:numel (str) ## Perform any modifications to the varname to make sure that it is ## a valid variable name. ## remove invalid characters str{i}(! ismember (str{i}, validchars)) = "_"; ## do not use keywords if (iskeyword (str{i})) str{i} = cstrcat ("_", str{i}); endif ## double underscores at the beginning and end are reserved variables underscores = (str{i} == "_"); if (any (underscores)) firstnon = find (!underscores, 1); lastnon = find (!underscores, 1, "last"); str{i}([1:firstnon-2, lastnon+2:end]) = []; endif ## The variable cannot be empty if (isempty (str{i})) str{i} = "x"; endif ## it cannot start with a number if (ismember (str{i}(1), "0":"9")) str{i} = cstrcat ("_", str{i}); endif ## make sure that the variable is unique relative to other variables ## and the exclusions list excluded = any (strcmp (str{i}, exclusions)); if (excluded && ismember (str{i}(end), "0":"9")) ## if it is not unique and ends with a digit, add an underscore to ## make the variable name more readable ("x1_1" instead of "x11") str{i}(end+1) = "_"; endif varname(i) = str(i); idx = 0; while excluded idx++; varname{i} = sprintf("%s%d", str{i}, idx); excluded = any (strcmp (varname{i}, exclusions)); endwhile exclusions(end+1) = varname(i); endfor if strinput varname = varname{1}; endif endfunction ## Tests ## a single argument %!assert(genvarname("a"), "a") ## a single argument with a non-conflicting exception %!assert(genvarname("a", "b"), "a") ## a single argument with a conflicting exception %!assert(genvarname("a", "a"), "a1") ## a single argument as a cell %!assert(genvarname({"a"}), {"a"}) %!assert(genvarname({"a"}, "b"), {"a"}) %!assert(genvarname({"a"}, {"b"}), {"a"}) %!assert(genvarname({"a"}, "a"), {"a1"}) %!assert(genvarname({"a"}, {"a"}), {"a1"}) ## Test different arguments ## orientation %!assert(genvarname({"a" "b"}), {"a" "b"}) %!assert(genvarname({"a";"b"}), {"a";"b"}) %!assert(genvarname({"a" "a"}), {"a" "a1"}) %!assert(genvarname({"a" "b";"c" "d"}), {"a" "b";"c" "d"}) %!assert(genvarname({"a" "a" "a";"a" "a" "a"}), {"a" "a2" "a4";"a1" "a3" "a5"}) ## more than one repetition %!assert(genvarname({"a" "a" "a"}), {"a" "a1" "a2"}) %!assert(genvarname({"a" "a" "a"}, {"a" "a1" "a2"}), {"a3" "a4" "a5"}) ## more than one repetition not in order %!assert(genvarname({"a" "b" "a" "b" "a"}), {"a" "b" "a1" "b1" "a2"}) ## Variable name munging %!assert (genvarname ("__x__"), "_x_") %!assert (genvarname ("123456789"), "_123456789") %!assert (genvarname ("_$1__"), "_1_") %!assert (genvarname ("__foo__", "_foo_"), "_foo_1") %!assert (genvarname ("1million_and1", "_1million_and1"), "_1million_and1_1") %!assert (genvarname ({"", "", ""}), {"x", "x1", "x2"}) %!assert (genvarname ("if"), "_if") %!assert (genvarname ({"if", "if", "if"}), {"_if", "_if1", "_if2"})