Revert f56158b2 "[doc] string pages improved" for specific files where
[scilab.git] / scilab / modules / string / help / en_US / strcat.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4 * Copyright (C) INRIA -
5 *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14 *
15 -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:db="http://docbook.org/ns/docbook" xml:id="strcat" xml:lang="en">
19     <refnamediv>
20         <refname>strcat</refname>
21         <refpurpose>concatenates character strings</refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Syntax</title>
25         <synopsis>
26             txt = strcat(strings)
27             txt = strcat(strings, string_added)
28             txt = strcat(strings, string_added, "r")
29             txt = strcat(strings, string_added, "c")
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>strings</term>
37                 <listitem>
38                     <para>vector, matrix, or hypermatrix of strings.</para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>string_added</term>
43                 <listitem>
44                     <para>
45                         a string added, default value is the zero length character
46                         string <literal>""</literal>.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>txt</term>
52                 <listitem>
53                     <para>a string.</para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>"r" | "c" flag</term>
58                 <listitem>
59                     <para>
60                         <literal>"r"</literal> glues together all <emphasis role="bold">r</emphasis>ows
61                         of each column,  in the array <varname>strings</varname>.
62                         If <varname>strings</varname> is a matrix, <varname>txt</varname> is a
63                         <emphasis role="bold">r</emphasis>ow of longer strings.
64                         <literal>"c"</literal> glues all columns of each row.
65                     </para>
66                 </listitem>
67             </varlistentry>
68         </variablelist>
69     </refsection>
70     <refsection>
71         <title>Description</title>
72         <para>
73             <code>txt = strcat(strings)</code> concatenates character strings:
74             <literal>txt = strings(1) + ... + strings(n)</literal>.
75         </para>
76         <para>
77             <code>txt = strcat(strings, string_added)</code> returns
78             <literal>txt = strings(1) + string_added + ... + string_added + strings(n)</literal>.
79         </para>
80         <para>
81             The plus symbol does the same: <code>"a"+"b"</code> is the
82             same as <code>strcat(["a","b"]).</code>.
83         </para>
84         <para>
85             If the size of <varname>strings</varname> is one, it returns
86             <code>txt = strings(1)</code>;
87         </para>
88         <para>
89             <code>strcat('A','B')</code> returns <literal>'A'</literal> and not
90             <literal>'AB'</literal> as <code>strcat(['A','B'])</code>.
91         </para>
92         <para>
93             If <varname>strings</varname> is a matrix of strings,
94             <code>txt = strcat(strings, "", "r")</code> returns a row vector of strings.
95             Each entry of <varname>txt</varname> results from the concatenation of rows along
96             the related column.
97             <code>txt = strcat(strings, "", "c")</code> returns a column vector of strings.
98             Each entry of <varname>txt</varname> results from the concatenation of columns along
99             the related row.
100         </para>
101     </refsection>
102     <refsection>
103         <title>Examples</title>
104         <programlisting role="example"><![CDATA[
105 strcat(string(1:10),',')
106 strcat(["a","b"])
107 strcat(["a","b"],'|')
108 strcat('A')
109 strcat('A','B')
110 strcat(['A','B'])
111 strcat(['A','B'],'')
112
113 m =["a" "b" ; "c" "d"];
114 strcat(m, "r")
115 strcat(m, "", "r")
116 strcat(m, "", "c")
117
118 strcat(m, "_and_", "r")
119 strcat(m, "_and_", "c")
120
121     ]]></programlisting>
122     </refsection>
123     <refsection role="see also">
124         <title>See also</title>
125         <simplelist type="inline">
126             <member>
127                 <link linkend="string">string</link>
128             </member>
129             <member>
130                 <link linkend="strings">strings</link>
131             </member>
132             <member>
133                 <link linkend="strsplit">strsplit</link>
134             </member>
135             <member>
136                 <link linkend="brackets">brackets []</link>
137             </member>
138         </simplelist>
139     </refsection>
140 </refentry>