Bump version numbers to 6.2.0
[scilab.git] / scilab / modules / string / help / en_US / part.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  * Copyright (C) Samuel GOUGEON - 2013 : $ is now supported. More examples.
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xml:id="part" xml:lang="en">
21     <refnamediv>
22         <refname>part</refname>
23         <refpurpose>Extraction of characters from strings</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>strings_out = part(strings_in, v)</synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>strings_in</term>
34                 <listitem>
35                     <para>a character string or a matrix of character string.</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>v</term>
40                 <listitem>
41                     <para>
42                         a vector of integer values containing the indices of characters to be extracted.
43                         <literal>$</literal> is accepted and means length(strings_in).
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>strings_out</term>
49                 <listitem>
50                     <para>a character string or matrix of character string.</para>
51                 </listitem>
52             </varlistentry>
53         </variablelist>
54     </refsection>
55     <refsection>
56         <title>Description</title>
57         <para>
58             This function extracts characters from strings. The characters to be
59             extracted are referred to by their indices contained in <literal>v</literal>.
60         </para>
61
62         <para>
63             <literal>strings_out</literal> is filled with whitespace characters when indices
64             are beyond the input string's length.
65         </para>
66         <para>
67             <literal>v</literal> may contain <literal>$</literal> symbol which stands for the
68             length of <literal>string_in</literal>.
69         </para>
70     </refsection>
71     <refsection>
72         <title>Examples</title>
73         <programlisting role="example"><![CDATA[
74 // Returns characters position 8 to 11
75 part("How to use ""part"" ?", 8:11)
76
77 // Returns characters position 2 to 4 for each element
78 // No characters replaced by ''
79 c = part(['a', 'abc', 'abcd'], 2:4)
80
81 // Returns character position 1 for each element and add characters position
82 // 4 to 7 of each element
83 c = part(['abcdefg', 'hijklmn', 'opqrstu'], [1, 4:7]);
84
85 // Returns character 4 for each element, add characters position 1 to 7 and
86 // add character position 4 for each element
87 c = part(['abcdefg', 'hijklmn', 'opqrstu'], [4, 1:7, 4]);
88
89 // Returns character position 1, add again character position 1 and
90 // character position 2
91 c=part(['a', 'abc', 'abcd'], [1, 1, 2])
92
93
94 part(['a', 'abc', 'abcd'], [1])         // =>  ['a' 'a' 'a']
95 part(['a', 'abc', 'abcd'], [1 1])       // =>  ['aa' 'aa' 'aa']
96 part(['a', 'abc', 'abcd'], [1 1 2])     // =>  ['aa ' 'aab' 'aab']
97
98 // Repeating a character N times:
99 N = 10; part('-', ones(1:N))            // => '----------'
100
101 // Repeating a pattern N times:
102 N = 6; pat = '- ';
103 part(pat, ones(1:N).*.(1:length(pat))) // => '- - - - - - '
104
105 // Using $ = implicit length of strings:
106 // 1)
107 part(['a string' 'another longer one'], $-2:$ ) // => [ 'ing' 'one']
108
109 // 2) Another implementation for strrev():
110 part('Hello world', $:-1:1)        // => 'dlrow olleH'
111
112 // 3) With unranging $:
113 part('Hello world', [ $ 4:5 ])     // => 'dlo'
114
115 // 4) Mixing scalar or unranging $ with ranging ones is not possible:
116 part("Hello", [ 1 $-1:$ $ ])       // =>  error
117     ]]></programlisting>
118     </refsection>
119     <refsection role="see also">
120         <title>See also</title>
121         <simplelist type="inline">
122             <member>
123                 <link linkend="string">string</link>
124             </member>
125             <member>
126                 <link linkend="strsplit">strsplit</link>
127             </member>
128             <member>
129                 <link linkend="length">length</link>
130             </member>
131         </simplelist>
132     </refsection>
133
134     <refsection>
135         <title>History</title>
136         <revhistory>
137             <revision>
138                 <revnumber>5.5.0</revnumber>
139                 <revremark>
140                     <literal>$</literal> standing for length(input_strings) is now accepted in indices of selected characters
141                 </revremark>
142             </revision>
143         </revhistory>
144     </refsection>
145 </refentry>