* Bug #10816 fixed - Allow the usage of the '$' keyword in the part function.
[scilab.git] / scilab / modules / string / help / en_US / part.xml
index 967fc6a..56d4c77 100644 (file)
-<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <!--
  * 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
  *
  -->
-<!DOCTYPE MAN SYSTEM "../../../../modules/helptools/help.dtd">
-<MAN>
-  <LANGUAGE>eng</LANGUAGE>
-  <TITLE>part</TITLE>
-  <TYPE>Scilab Function</TYPE>
-  <DATE>$LastChangedDate: 2006-08-08 16:57:13 +0200 (Tue, 08 Aug 2006) $</DATE>
-  <SHORT_DESCRIPTION name="part"> extraction of strings</SHORT_DESCRIPTION>
-  <CALLING_SEQUENCE>
-    <CALLING_SEQUENCE_ITEM>[c]=part(mp,v)  </CALLING_SEQUENCE_ITEM>
-  </CALLING_SEQUENCE>
-  <PARAM>
-    <PARAM_INDENT>
-      <PARAM_ITEM>
-        <PARAM_NAME>mp,c</PARAM_NAME>
-        <PARAM_DESCRIPTION>
-          <SP>: string matrices</SP>
-        </PARAM_DESCRIPTION>
-      </PARAM_ITEM>
-      <PARAM_ITEM>
-        <PARAM_NAME>v</PARAM_NAME>
-        <PARAM_DESCRIPTION>
-          <SP>: integer vector.</SP>
-        </PARAM_DESCRIPTION>
-      </PARAM_ITEM>
-    </PARAM_INDENT>
-  </PARAM>
-  <DESCRIPTION>
-    <P>
-    Let <VERB>s[k]</VERB> stands for the <VERB>k</VERB> character of string <VERB>s</VERB> ( 
-    or the white space character if <VERB>k &gt;length(s)</VERB>).</P>
-    <P><VERB>part</VERB> returns <VERB>c</VERB>, a matrix of character strings, such that 
-    <VERB>c(i,j)</VERB> is the string <VERB>&quot;s[v(1)]...s[v(n)]&quot;</VERB> ( <VERB>s=mp(i,j)</VERB> ).</P>
-  </DESCRIPTION>
-  <EXAMPLE>
-<![CDATA[
-c=part(['a','abc','abcd'],[1,1,2])
- ]]>
-  </EXAMPLE>
-  <SEE_ALSO>
-    <SEE_ALSO_ITEM>
-      <LINK>string</LINK>
-    </SEE_ALSO_ITEM>
-    <SEE_ALSO_ITEM>
-      <LINK>length</LINK>
-    </SEE_ALSO_ITEM>
-  </SEE_ALSO>
-</MAN>
+<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])
+
+
+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']
+
+// Repeating a character N times:
+N = 10; part('-', ones(1:N))           // => '----------'
+
+// Repeating a pattern N times:
+N = 6; pat = '- '; 
+part(pat, ones(1:N).*.(1:length(pat))) // => '- - - - - - '
+
+// Using $ = implicit length of strings: 
+// 1)
+part(['a string' 'another longer one'], $-2:$ ) // => [ 'ing' 'one']
+
+// 2) Another implementation for strrev():
+part('Hello world', $:-1:1)              // => 'dlrow olleH'
+
+// 3) With unranging $:
+part('Hello world', [ $ 4:5 ])   // => 'dlo'
+
+// 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>