octave_packages/m/strings/strjust.m

   1 ## Copyright (C) 2000-2012 Paul Kienzle
   2 ## Copyright (C) 2009 Jaroslav Hajek
   3 ##
   4 ## This file is part of Octave.
   5 ##
   6 ## Octave is free software; you can redistribute it and/or modify it
   7 ## under the terms of the GNU General Public License as published by
   8 ## the Free Software Foundation; either version 3 of the License, or (at
   9 ## your option) any later version.
  10 ##
  11 ## Octave is distributed in the hope that it will be useful, but
  12 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 ## General Public License for more details.
  15 ##
  16 ## You should have received a copy of the GNU General Public License
  17 ## along with Octave; see the file COPYING.  If not, see
  18 ## <http://www.gnu.org/licenses/>.
  19
  20 ## -*- texinfo -*-
  21 ## @deftypefn  {Function File} {} strjust (@var{s})
  22 ## @deftypefnx {Function File} {} strjust (@var{s}, @var{pos})
  23 ## Return the text, @var{s}, justified according to @var{pos}, which may
  24 ## be @samp{"left"}, @samp{"center"}, or @samp{"right"}.  If @var{pos}
  25 ## is omitted it defaults to @samp{"right"}.
  26 ##
  27 ## Null characters are replaced by spaces.  All other character
  28 ## data are treated as non-white space.
  29 ##
  30 ## Example:
  31 ##
  32 ## @example
  33 ## @group
  34 ## strjust (["a"; "ab"; "abc"; "abcd"])
  35 ##      @result{}
  36 ##         "   a"
  37 ##         "  ab"
  38 ##         " abc"
  39 ##         "abcd"
  40 ## @end group
  41 ## @end example
  42 ## @seealso{deblank, strrep, strtrim, untabify}
  43 ## @end deftypefn
  44
  45 function y = strjust (s, pos = "right")
  46
  47   if (nargin < 1 || nargin > 2)
  48     print_usage ();
  49   elseif (! ischar (s) || ndims (s) > 2)
  50     error ("strjust: S must be a string or 2-D character matrix");
  51   endif
  52
  53   if (isempty (s))
  54     y = s;
  55     return;
  56   endif
  57
  58   ## Apparently, Matlab considers nulls to be blanks as well; however, does
  59   ## not preserve the nulls, but rather converts them to blanks.  That's a
  60   ## bit unexpected, but it allows simpler processing, because we can move
  61   ## just the nonblank characters. So we'll do the same here.
  62
  63   [nr, nc] = size (s);
  64   ## Find the indices of all nonblanks.
  65   nonbl = s != " " & s != "\0";
  66   [idx, jdx] = find (nonbl);
  67
  68   if (strcmpi (pos, "right"))
  69     ## We wish to find the maximum column index for each row. Because jdx is
  70     ## sorted, we can take advantage of the fact that assignment is processed
  71     ## sequentially and for duplicate indices the last value will remain.
  72     maxs = repmat (nc, [nr, 1]);
  73     maxs(idx) = jdx;
  74     shift = nc - maxs;
  75   elseif (strcmpi (pos, "left"))
  76     ## See above for explanation.
  77     mins = ones (nr, 1);
  78     mins(flipud (idx(:))) = flipud (jdx(:));
  79     shift = 1 - mins;
  80   else
  81     ## Use both of the above to achieve centering.
  82     mins = ones (nr, 1);
  83     mins(flipud (idx(:))) = flipud (jdx(:));
  84     maxs = repmat (nc, [nr, 1]);
  85     maxs(idx) = jdx;
  86     shift = floor ((nc + 1 - maxs - mins) / 2);
  87   endif
  88
  89   ## Adjust the column indices.
  90   jdx += shift(idx);
  91
  92   ## Create a blank matrix and position the nonblank characters.
  93   y = repmat (" ", nr, nc);
  94   y(sub2ind ([nr, nc], idx, jdx)) = s(nonbl);
  95
  96 endfunction
  97
  98
  99 %!assert (strjust (["a"; "ab"; "abc"; "abcd"]),
 100 %!        ["   a";"  ab"; " abc"; "abcd"]);
 101 %!assert (strjust ([" a"; "  ab"; "abc"; "abcd"], "left"),
 102 %!        ["a   "; "ab  "; "abc "; "abcd"]);
 103 %!assert (strjust (["a"; "ab"; "abc"; "abcd"], "CENTER"),
 104 %!        [" a  "; " ab"; "abc "; "abcd"]);
 105 %!assert (strjust (["";""]), "");
 106
 107 %% Test input validation
 108 %!error <Invalid call to strjust> strjust ()
 109 %!error <Invalid call to strjust> strjust (["a";"ab"], "center", 1)
 110 %!error <S must be a string> strjust (ones(3,3))
 111 %!error <S must be a string> strjust (char (ones(3,3,3)))
 112