* Bug #10816 fixed - Allow the usage of the '$' keyword in the part function.
[scilab.git] / scilab / modules / string / help / en_US / part.xml
index 4b92914..56d4c77 100644 (file)
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) INRIA - 
- * 
+ * Copyright (C) Samuel GOUGEON - 2013 : $ is now supported. More examples.
+ *
  * This file must be used under the terms of the CeCILL.
  * This source file is licensed as described in the file COPYING, which
  * you should have received as part of this distribution.  The terms
  * are also available at    
- * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
  *
  -->
-<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" version="5.0-subset Scilab" xml:id="part" xml:lang="en">
-  <info>
-    <pubdate>$LastChangedDate: 2006-08-08 16:57:13 +0200 (Tue, 08 Aug 2006)
-      $
-    </pubdate>
-  </info>
-  <refnamediv>
-    <refname>part</refname>
-    <refpurpose>extraction of strings</refpurpose>
-  </refnamediv>
-  <refsynopsisdiv>
-    <title>Calling Sequence</title>
-    <synopsis>[strings_out] = part(strings_in, v)</synopsis>
-  </refsynopsisdiv>
-  <refsection>
-    <title>Arguments</title>
-    <variablelist>
-      <varlistentry>
-        <term>strings_in, strings_out</term>
-        <listitem>
-          <para>Matrix of character strings.</para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term>v</term>
-        <listitem>
-          <para>Integer row vector.</para>
-        </listitem>
-      </varlistentry>
-    </variablelist>
-  </refsection>
-  <refsection>
-    <title>Description</title>
-    <para>
-      Let <literal>s[k]</literal> stands for the <literal>k</literal>
-      character of string <literal>s</literal> ( or the white space character if
-      <literal>k &gt;length(s)</literal>).
-    </para>
-    <para>
-      <literal>part</literal> returns <literal>strings_out</literal>, a
-      matrix of character strings, such that <literal>strings_out(i,j)</literal>
-      is the string <literal>"s[v(1)]...s[v(n)]"</literal> (
-      <literal>s=strings_in(i,j)</literal> ).
-    </para>
-  </refsection>
-  <refsection>
-    <title>Examples</title>
-    <programlisting role="example"><![CDATA[ 
-// returns characters position 8 to 11
-part("How to use ""part"" ?",8:11)
+<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">
+    <refnamediv>
+        <refname>part</refname>
+        <refpurpose>string built from extracted characters</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>[strings_out] = part(strings_in, v)</synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>strings_in, strings_out</term>
+                <listitem>
+                    <para>matrices of character strings.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>v</term>
+                <listitem>
+                    <para>
+                        an integer row vector. <literal>$</literal> is accepted and means length(strings_in)
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            Let <literal>s[k]</literal> stands for the <literal>k</literal>
+            character of string <literal>s</literal> (or the white space
+            character if <literal>k &gt;length(s)</literal>).
+        </para>
+        <para>
+            <function>part</function> returns <varname>strings_out</varname>, a
+            matrix of character strings, such that
+            <literal>strings_out(i,j)</literal> is the string
+            <literal>"s[v(1)]...s[v(n)]"</literal>
+            (<literal>s=strings_in(i,j)</literal>).
+        </para>
+    </refsection>
+    <refsection>
+        <title>Examples</title>
+        <programlisting role="example"><![CDATA[
+// Returns characters position 8 to 11
+part("How to use ""part"" ?", 8:11)
+
+// Returns characters position 2 to 4 for each element
+// No characters replaced by ''
+c = part(['a', 'abc', 'abcd'], 2:4)
+
+// Returns character position 1 for each element and add characters position
+// 4 to 7 of each element
+c = part(['abcdefg', 'hijklmn', 'opqrstu'], [1, 4:7]);
+
+// Returns character 4 for each element, add characters position 1 to 7 and
+// add character position 4 for each element
+c = part(['abcdefg', 'hijklmn', 'opqrstu'], [4, 1:7, 4]);
+
+// Returns character position 1, add again character position 1 and
+// character position 2
+c=part(['a', 'abc', 'abcd'], [1, 1, 2])
+
 
-// returns characters position 2 to 4 for each element
-// no characters replaced by ''
-c = part(['a','abc','abcd'],2:4)
+part(['a', 'abc', 'abcd'], [1])                // =>  ['a' 'a' 'a']
+part(['a', 'abc', 'abcd'], [1, 1])             // =>  ['aa' 'aa' 'aa']
+part(['a', 'abc', 'abcd'], [1, 1, 2])  // =>  ['aa' 'aab' 'aab']
 
-// returns character position 1 for each element and add characters position 4 to 7 of each element
-c = part(['abcdefg','hijklmn','opqrstu'],[1,4:7]);
+// Repeating a character N times:
+N = 10; part('-', ones(1:N))           // => '----------'
 
-// returns character 4 for each element, add characters position 1 to 7 and add character position 4 for each element
-c = part(['abcdefg','hijklmn','opqrstu'],[4,1:7,4]);
+// Repeating a pattern N times:
+N = 6; pat = '- '; 
+part(pat, ones(1:N).*.(1:length(pat))) // => '- - - - - - '
 
-// returns character position 1,add again character position 1 and character position 2
-c=part(['a','abc','abcd'],[1,1,2])
+// Using $ = implicit length of strings: 
+// 1)
+part(['a string' 'another longer one'], $-2:$ ) // => [ 'ing' 'one']
 
-// a a a  
-part(['a','abc','abcd'],[1])
+// 2) Another implementation for strrev():
+part('Hello world', $:-1:1)              // => 'dlrow olleH'
 
-// aa aa aa 
-part(['a','abc','abcd'],[1,1])
+// 3) With unranging $:
+part('Hello world', [ $ 4:5 ])   // => 'dlo'
 
-// aa aab aab 
-part(['a','abc','abcd'],[1,1,2])
- ]]></programlisting>
-  </refsection>
-  <refsection role="see also">
-    <title>See Also</title>
-    <simplelist type="inline">
-      <member>
-        <link linkend="string">string</link>
-      </member>
-      <member>
-        <link linkend="length">length</link>
-      </member>
-    </simplelist>
-  </refsection>
+// 4) Mixing scalar or unrangin $ with ranging ones is not possible:
+part("Hello", [ 1 $-1:$ $ ])      // =>  error
+    ]]></programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="string">string</link>
+            </member>
+            <member>
+                <link linkend="strsplit">strsplit</link>
+            </member>
+            <member>
+                <link linkend="length">length</link>
+            </member>
+        </simplelist>
+    </refsection>
+    
+    <refsection>
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>5.5.0</revnumber>
+                <revremark>
+                    <literal>$</literal> standing for length(input_strings) is now accepted in indices of selected characters
+                </revremark>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>