b2228b4c8317d6aff2284814c31bb4e8de75c399
[scilab.git] / scilab / modules / string / help / en_US / length.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" 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="length" xml:lang="en">
17     <refnamediv>
18         <refname>length</refname>
19         <refpurpose>length of object</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>n = length(M)</synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>M</term>
30                 <listitem>
31                     <para>
32                         a matrix (usual or polynomial or character string) or a
33                         list.
34                     </para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>n</term>
39                 <listitem>
40                     <para>an integer or a matrix of integers.</para>
41                 </listitem>
42             </varlistentry>
43         </variablelist>
44     </refsection>
45     <refsection>
46         <title>Description</title>
47         <para>
48             For usual or polynomial matrix <varname>n</varname> is the integer
49             equal to number of rows times number of columns
50             of <varname>M</varname>. (Also valid for <varname>M</varname>
51             a boolean matrix).
52         </para>
53         <para>
54             For matrices made of character strings (and in particular for a
55             character string) <function>length</function> returns in
56             <varname>n</varname> the length of entries of the matrix of
57             character strings <varname>M</varname>.
58         </para>
59         <para>
60             The length of a list is the number of elements in the list (also
61             given by <function>size</function>).
62         </para>
63         <para>
64             The length of a mlist is by default the number of elements in the
65             mlist, but you can overload it (see example). Note that for a non-string
66             hypermatrix, there is no need to overload the function. Indeed, <function>length</function>
67             returns the product of the dimensions of the hypermatrix.
68         </para>
69         <para>
70             <code>length('123')</code> is <literal>3</literal>.
71             <code>length([1,2;3,4])</code> is <literal>4</literal>.
72         </para>
73         <para>
74             <warning>
75                 WARNING : <function>length</function> of a sparse matrix
76                 returns the max of dimensions and not the product
77                 of the dimensions. (For example:
78                 <code>length(sparse(eye(12,2)))</code>
79                 returns <code>max(12,2)</code> and not <literal>24</literal>).
80                 Please use <literal>size(...,'*')</literal> with sparse matrix.
81             </warning>
82         </para>
83     </refsection>
84     <refsection>
85         <title>Examples</title>
86         <programlisting role="example"><![CDATA[
87 length([123 ; 456 ])
88 length(['hello world',SCI])
89 length(rand(2,2,2))
90
91     ]]></programlisting>
92         <programlisting role="example"><![CDATA[
93
94 a = mlist(["myMlistT" "field1" "field2"],"aexample","bexampleb");
95 length(a)
96 // returns 3 default behaviour if length not overloaded for mlist
97
98 // we create an overload function for mlist of type myMlistT
99 function r = %myMlistT_length(M)
100     r = length(M.field1)
101 endfunction
102
103 length(a)
104 // returns 8 result of length(a.field1)
105     ]]></programlisting>
106     </refsection>
107     <refsection role="see also">
108         <title>See also</title>
109         <simplelist type="inline">
110             <member>
111                 <link linkend="size">size</link>
112             </member>
113         </simplelist>
114     </refsection>
115     <refsection>
116         <title>History</title>
117         <revhistory>
118             <revision>
119                 <revnumber>5.4.0</revnumber>
120                 <revremark>
121                     This function allows overloading for mlist type.
122                 </revremark>
123             </revision>
124         </revhistory>
125     </refsection>
126 </refentry>