Mercurial > hg > octave-lyh
annotate scripts/strings/strcat.m @ 14821:aad7d7ee8e8a
Clarify doc string for strcat.
* scripts/strings/strcat.m: Clarify that the trailing spaces of the inputs
are eliminated before the are concatentated.
author | Ben Abbott <bpabbott@mac.com> |
---|---|
date | Fri, 29 Jun 2012 17:23:19 -0400 |
parents | f3d52523cde1 |
children | 5d3a684236b0 |
rev | line source |
---|---|
14138
72c96de7a403
maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents:
12931
diff
changeset
|
1 ## Copyright (C) 1994-2012 John W. Eaton |
10032 | 2 ## Copyright (C) 2009 Jaroslav Hajek |
2313 | 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 | |
7016 | 8 ## the Free Software Foundation; either version 3 of the License, or (at |
9 ## your option) any later version. | |
2313 | 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 | |
7016 | 17 ## along with Octave; see the file COPYING. If not, see |
18 ## <http://www.gnu.org/licenses/>. | |
920 | 19 |
3361 | 20 ## -*- texinfo -*- |
21 ## @deftypefn {Function File} {} strcat (@var{s1}, @var{s2}, @dots{}) | |
8442
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
22 ## Return a string containing all the arguments concatenated |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
23 ## horizontally. If the arguments are cells strings, @code{strcat} |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
24 ## returns a cell string with the individual cells concatenated. |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
25 ## For numerical input, each element is converted to the |
14821
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
26 ## corresponding ASCII character. Trailing white space for each of |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
27 ## the inputs (@var{s1}, @var{S2}, @dots{}) is eliminated before they |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
28 ## are concatenated. |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
29 ## |
10821
693e22af08ae
Grammarcheck documentation of m-files
Rik <octave@nomad.inbox5.com>
parents:
10037
diff
changeset
|
30 ## For example: |
3426 | 31 ## |
3361 | 32 ## @example |
33 ## @group | |
14821
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
34 ## strcat ("|", " leading space is preserved", "|") |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
35 ## @result{} | leading space is perserved| |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
36 ## @end group |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
37 ## @end example |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
38 ## |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
39 ## @example |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
40 ## @group |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
41 ## strcat ("|", "trailing space is eliminated ", "|") |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
42 ## @result{} |trailing space is eliminated| |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
43 ## @end group |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
44 ## @end example |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
45 ## |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
46 ## @example |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
47 ## @group |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
48 ## strcat ("homogeneous space |", " ", "| is also eliminated") |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
49 ## @result{} homogeneous space || is also eliminated |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
50 ## @end group |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
51 ## @end example |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
52 ## |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
53 ## @example |
aad7d7ee8e8a
Clarify doc string for strcat.
Ben Abbott <bpabbott@mac.com>
parents:
14363
diff
changeset
|
54 ## @group |
3361 | 55 ## s = [ "ab"; "cde" ]; |
56 ## strcat (s, s, s) | |
14327
4d917a6a858b
doc: Use Octave coding conventions in @example blocks of docstrings.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
57 ## @result{} |
8442
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
58 ## "ab ab ab " |
3361 | 59 ## "cdecdecde" |
60 ## @end group | |
61 ## @end example | |
8442
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
62 ## |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
63 ## @example |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
64 ## @group |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
65 ## s = @{ "ab"; "cde" @}; |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
66 ## strcat (s, s, s) |
14327
4d917a6a858b
doc: Use Octave coding conventions in @example blocks of docstrings.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
67 ## @result{} |
8442
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
68 ## @{ |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
69 ## [1,1] = ababab |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
70 ## [2,1] = cdecdecde |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
71 ## @} |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
72 ## @end group |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
73 ## @end example |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
74 ## |
502e58a0d44f
Fix docstrings, add examples, references and tests to string functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8143
diff
changeset
|
75 ## @seealso{cstrcat, char, strvcat} |
3361 | 76 ## @end deftypefn |
2697 | 77 |
2314 | 78 ## Author: jwe |
79 | |
6138 | 80 function st = strcat (varargin) |
920 | 81 |
7504
ddcf233d765b
detect cellstr args in strcat
John W. Eaton <jwe@octave.org>
parents:
7411
diff
changeset
|
82 if (nargin > 0) |
7540
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
83 if (nargin == 1) |
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
84 st = varargin{1}; |
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
85 elseif (nargin > 1) |
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
86 ## Convert to cells of strings |
11191
01ddaedd6ad5
Reverse changeset b1f4bdc276b6. Use all lower case for "uniformoutput" option.
Rik <octave@nomad.inbox5.com>
parents:
11149
diff
changeset
|
87 uo = "uniformoutput"; |
12931
cefd568ea073
Replace function handles with function names in cellfun calls for 15% speedup.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
88 reals = cellfun ("isreal", varargin); |
10032 | 89 if (any (reals)) |
12931
cefd568ea073
Replace function handles with function names in cellfun calls for 15% speedup.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
90 varargin(reals) = cellfun ("char", varargin(reals), uo, false); |
10032 | 91 endif |
12931
cefd568ea073
Replace function handles with function names in cellfun calls for 15% speedup.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
92 chars = cellfun ("isclass", varargin, "char"); |
10032 | 93 allchar = all (chars); |
12931
cefd568ea073
Replace function handles with function names in cellfun calls for 15% speedup.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
94 varargin(chars) = cellfun ("cellstr", varargin(chars), uo, false); |
cefd568ea073
Replace function handles with function names in cellfun calls for 15% speedup.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
95 if (! all (cellfun ("isclass", varargin, "cell"))) |
10032 | 96 error ("strcat: inputs must be strings or cells of strings"); |
97 endif | |
7504
ddcf233d765b
detect cellstr args in strcat
John W. Eaton <jwe@octave.org>
parents:
7411
diff
changeset
|
98 |
10037
e60f038146e1
further simplify strcat
Jaroslav Hajek <highegg@gmail.com>
parents:
10032
diff
changeset
|
99 ## We don't actually need to bring all cells to common size, because |
e60f038146e1
further simplify strcat
Jaroslav Hajek <highegg@gmail.com>
parents:
10032
diff
changeset
|
100 ## cellfun can now expand scalar cells. |
e60f038146e1
further simplify strcat
Jaroslav Hajek <highegg@gmail.com>
parents:
10032
diff
changeset
|
101 err = common_size (varargin{:}); |
10032 | 102 |
103 if (err) | |
104 error ("strcat: arguments must be the same size, or be scalars"); | |
105 endif | |
7540
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
106 |
10037
e60f038146e1
further simplify strcat
Jaroslav Hajek <highegg@gmail.com>
parents:
10032
diff
changeset
|
107 ## Cellfun handles everything for us. |
12931
cefd568ea073
Replace function handles with function names in cellfun calls for 15% speedup.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
108 st = cellfun ("horzcat", varargin{:}, uo, false); |
7540
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
109 |
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
110 if (allchar) |
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
111 ## If all inputs were strings, return strings. |
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
112 st = char (st); |
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
113 endif |
7504
ddcf233d765b
detect cellstr args in strcat
John W. Eaton <jwe@octave.org>
parents:
7411
diff
changeset
|
114 endif |
ddcf233d765b
detect cellstr args in strcat
John W. Eaton <jwe@octave.org>
parents:
7411
diff
changeset
|
115 else |
6046 | 116 print_usage (); |
920 | 117 endif |
118 | |
7504
ddcf233d765b
detect cellstr args in strcat
John W. Eaton <jwe@octave.org>
parents:
7411
diff
changeset
|
119 endfunction |
920 | 120 |
6138 | 121 ## test the dimensionality |
122 ## 1d | |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
123 %!assert (strcat ("ab ", "ab "), "abab") |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
124 %!assert (strcat ({"ab "}, "ab "), {"ab ab"}) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
125 %!assert (strcat ("ab ", {"ab "}), {"abab "}) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
126 %!assert (strcat ({"ab "}, {"ab "}), {"ab ab "}) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
127 %!assert (strcat ("", "ab"), "ab") |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
128 %!assert (strcat ("", {"ab"}, {""}), {"ab"}) |
6138 | 129 ## 2d |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
130 %!assert (strcat (["ab ";"cde"], ["ab ";"cde"]), ["abab ";"cdecde"]) |
7411 | 131 |
7540
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
132 ## test for deblanking implied trailing spaces of character input |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
133 %!assert (strcat ("foo", "bar"), "foobar") |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
134 %!assert (strcat (["a"; "bb"], ["foo"; "bar"]), ["afoo "; "bbbar"]) |
7540
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
135 |
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
136 ## test for mixing character and cell inputs |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
137 %!assert (strcat ("a", {"bc", "de"}, "f"), {"abcf", "adef"}) |
7411 | 138 |
7540
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
139 ## test for scalar strings with vector strings |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
140 %!assert (strcat (["a"; "b"], "c"), ["ac"; "bc"]) |
7540
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
141 |
3422f39573b1
strcat.m: Matlab compatibility, with cstrcat.m replacing conventional strcat.m.
Ben Abbott <bpabbott@mac.com>
parents:
7504
diff
changeset
|
142 ## test with cells with strings of differing lengths |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
143 %!assert (all (strcmp (strcat ({"a", "bb"}, "ccc"), {"accc", "bbccc"}))) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
144 %!assert (all (strcmp (strcat ("a", {"bb", "ccc"}), {"abb", "accc"}))) |
7411 | 145 |
8143
3a4694d67dbb
strcat.m: Compatibility of non-char data
Ben Abbott <bpabbott@mac.com>
parents:
7813
diff
changeset
|
146 %!assert (strcat (1, 2), strcat (char(1), char(2))) |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
147 %!assert (strcat ("", 2), strcat ([], char(2))) |
7411 | 148 |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
149 %!error strcat () |
8143
3a4694d67dbb
strcat.m: Compatibility of non-char data
Ben Abbott <bpabbott@mac.com>
parents:
7813
diff
changeset
|
150 |