* Bug #10816 fixed - Allow the usage of the '$' keyword in the part function.
[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  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at    
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xml:id="part" xml:lang="en">
15     <refnamediv>
16         <refname>part</refname>
17         <refpurpose>string built from extracted characters</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>[strings_out] = part(strings_in, v)</synopsis>
22     </refsynopsisdiv>
23     <refsection>
24         <title>Arguments</title>
25         <variablelist>
26             <varlistentry>
27                 <term>strings_in, strings_out</term>
28                 <listitem>
29                     <para>matrices of character strings.</para>
30                 </listitem>
31             </varlistentry>
32             <varlistentry>
33                 <term>v</term>
34                 <listitem>
35                     <para>
36                         an integer row vector. <literal>$</literal> is accepted and means length(strings_in)
37                     </para>
38                 </listitem>
39             </varlistentry>
40         </variablelist>
41     </refsection>
42     <refsection>
43         <title>Description</title>
44         <para>
45             Let <literal>s[k]</literal> stands for the <literal>k</literal>
46             character of string <literal>s</literal> (or the white space
47             character if <literal>k &gt;length(s)</literal>).
48         </para>
49         <para>
50             <function>part</function> returns <varname>strings_out</varname>, a
51             matrix of character strings, such that
52             <literal>strings_out(i,j)</literal> is the string
53             <literal>"s[v(1)]...s[v(n)]"</literal>
54             (<literal>s=strings_in(i,j)</literal>).
55         </para>
56     </refsection>
57     <refsection>
58         <title>Examples</title>
59         <programlisting role="example"><![CDATA[
60 // Returns characters position 8 to 11
61 part("How to use ""part"" ?", 8:11)
62
63 // Returns characters position 2 to 4 for each element
64 // No characters replaced by ''
65 c = part(['a', 'abc', 'abcd'], 2:4)
66
67 // Returns character position 1 for each element and add characters position
68 // 4 to 7 of each element
69 c = part(['abcdefg', 'hijklmn', 'opqrstu'], [1, 4:7]);
70
71 // Returns character 4 for each element, add characters position 1 to 7 and
72 // add character position 4 for each element
73 c = part(['abcdefg', 'hijklmn', 'opqrstu'], [4, 1:7, 4]);
74
75 // Returns character position 1, add again character position 1 and
76 // character position 2
77 c=part(['a', 'abc', 'abcd'], [1, 1, 2])
78
79
80 part(['a', 'abc', 'abcd'], [1])         // =>  ['a' 'a' 'a']
81 part(['a', 'abc', 'abcd'], [1, 1])              // =>  ['aa' 'aa' 'aa']
82 part(['a', 'abc', 'abcd'], [1, 1, 2])   // =>  ['aa' 'aab' 'aab']
83
84 // Repeating a character N times:
85 N = 10; part('-', ones(1:N))            // => '----------'
86
87 // Repeating a pattern N times:
88 N = 6; pat = '- '; 
89 part(pat, ones(1:N).*.(1:length(pat))) // => '- - - - - - '
90
91 // Using $ = implicit length of strings: 
92 // 1)
93 part(['a string' 'another longer one'], $-2:$ ) // => [ 'ing' 'one']
94
95 // 2) Another implementation for strrev():
96 part('Hello world', $:-1:1)               // => 'dlrow olleH'
97
98 // 3) With unranging $:
99 part('Hello world', [ $ 4:5 ])    // => 'dlo'
100
101 // 4) Mixing scalar or unrangin $ with ranging ones is not possible:
102 part("Hello", [ 1 $-1:$ $ ])      // =>  error
103     ]]></programlisting>
104     </refsection>
105     <refsection role="see also">
106         <title>See Also</title>
107         <simplelist type="inline">
108             <member>
109                 <link linkend="string">string</link>
110             </member>
111             <member>
112                 <link linkend="strsplit">strsplit</link>
113             </member>
114             <member>
115                 <link linkend="length">length</link>
116             </member>
117         </simplelist>
118     </refsection>
119     
120     <refsection>
121         <title>History</title>
122         <revhistory>
123             <revision>
124                 <revnumber>5.5.0</revnumber>
125                 <revremark>
126                     <literal>$</literal> standing for length(input_strings) is now accepted in indices of selected characters
127                 </revremark>
128             </revision>
129         </revhistory>
130     </refsection>
131 </refentry>