octave_packages/m/strings/strcat.m

   1 ## Copyright (C) 1994-2012 John W. Eaton
   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} {} strcat (@var{s1}, @var{s2}, @dots{})
  22 ## Return a string containing all the arguments concatenated
  23 ## horizontally.  If the arguments are cells strings,  @code{strcat}
  24 ## returns a cell string with the individual cells concatenated.
  25 ## For numerical input, each element is converted to the
  26 ## corresponding ASCII character.  Trailing white space is eliminated.
  27 ## For example:
  28 ##
  29 ## @example
  30 ## @group
  31 ## s = [ "ab"; "cde" ];
  32 ## strcat (s, s, s)
  33 ##     @result{}
  34 ##         "ab ab ab "
  35 ##         "cdecdecde"
  36 ## @end group
  37 ## @end example
  38 ##
  39 ## @example
  40 ## @group
  41 ## s = @{ "ab"; "cde" @};
  42 ## strcat (s, s, s)
  43 ##     @result{}
  44 ##         @{
  45 ##           [1,1] = ababab
  46 ##           [2,1] = cdecdecde
  47 ##         @}
  48 ## @end group
  49 ## @end example
  50 ##
  51 ## @seealso{cstrcat, char, strvcat}
  52 ## @end deftypefn
  53
  54 ## Author: jwe
  55
  56 function st = strcat (varargin)
  57
  58   if (nargin > 0)
  59     if (nargin == 1)
  60       st = varargin{1};
  61     elseif (nargin > 1)
  62       ## Convert to cells of strings
  63       uo = "uniformoutput";
  64       reals = cellfun ("isreal", varargin);
  65       if (any (reals))
  66         varargin(reals) = cellfun ("char", varargin(reals), uo, false);
  67       endif
  68       chars = cellfun ("isclass", varargin, "char");
  69       allchar = all (chars);
  70       varargin(chars) = cellfun ("cellstr", varargin(chars), uo, false);
  71       if (! all (cellfun ("isclass", varargin, "cell")))
  72         error ("strcat: inputs must be strings or cells of strings");
  73       endif
  74
  75       ## We don't actually need to bring all cells to common size, because
  76       ## cellfun can now expand scalar cells.
  77       err = common_size (varargin{:});
  78
  79       if (err)
  80         error ("strcat: arguments must be the same size, or be scalars");
  81       endif
  82
  83       ## Cellfun handles everything for us.
  84       st = cellfun ("horzcat", varargin{:}, uo, false);
  85
  86       if (allchar)
  87         ## If all inputs were strings, return strings.
  88         st = char (st);
  89       endif
  90     endif
  91   else
  92     print_usage ();
  93   endif
  94
  95 endfunction
  96
  97 ## test the dimensionality
  98 ## 1d
  99 %!assert(strcat("ab ", "ab "), "abab")
 100 %!assert(strcat({"ab "}, "ab "), {"ab ab"})
 101 %!assert(strcat("ab ", {"ab "}), {"abab "})
 102 %!assert(strcat({"ab "}, {"ab "}), {"ab ab "})
 103 %!assert(strcat("", "ab"), "ab")
 104 %!assert(strcat("", {"ab"}, {""}), {"ab"})
 105 ## 2d
 106 %!assert(strcat(["ab ";"cde"], ["ab ";"cde"]), ["abab  ";"cdecde"])
 107
 108 ## test for deblanking implied trailing spaces of character input
 109 %!assert((strcmp (strcat ("foo", "bar"), "foobar")
 110 %!        && strcmp (strcat (["a"; "bb"], ["foo"; "bar"]), ["afoo "; "bbbar"])));
 111
 112 ## test for mixing character and cell inputs
 113 %!assert(all (strcmp (strcat ("a", {"bc", "de"}, "f"), {"abcf", "adef"})))
 114
 115 ## test for scalar strings with vector strings
 116 %!assert(all (strcmp (strcat (["a"; "b"], "c"), ["ac"; "bc"])))
 117
 118 ## test with cells with strings of differing lengths
 119 %!assert(all (strcmp (strcat ({"a", "bb"}, "ccc"), {"accc", "bbccc"})))
 120 %!assert(all (strcmp (strcat ("a", {"bb", "ccc"}), {"abb", "accc"})))
 121
 122 %!error strcat ();
 123
 124 %!assert (strcat (1, 2), strcat (char(1), char(2)))
 125
 126 %!assert (strcat ('', 2), strcat ([], char(2)))
 127