length(): documents changes for cells and structures arrays
[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 an array M of cells or of structures is the number of elements of the array.
65             It is equivalent to <literal>size(M, "*")</literal>.
66         </para>
67         <para>
68             The length of a mlist is by default the number of elements in the
69             mlist, but you can overload it (see example). Note that for a non-string
70             hypermatrix, there is no need to overload the function. Indeed, <function>length</function>
71             returns the product of the dimensions of the hypermatrix.
72         </para>
73         <para>
74             <code>length('123')</code> is <literal>3</literal>.
75             <code>length([1,2;3,4])</code> is <literal>4</literal>.
76         </para>
77         <para>
78             <warning>
79                 WARNING : <function>length</function> of a sparse matrix
80                 returns the max of dimensions and not the product
81                 of the dimensions. (For example:
82                 <code>length(sparse(eye(12,2)))</code>
83                 returns <code>max(12,2)</code> and not <literal>24</literal>).
84                 Please use <literal>size(...,'*')</literal> with sparse matrix.
85             </warning>
86         </para>
87     </refsection>
88     <refsection>
89         <title>Examples</title>
90         <programlisting role="example"><![CDATA[
91 length([123 ; 456 ])
92 length(['hello world',SCI])
93 length(rand(2,2,2))
94
95     ]]></programlisting>
96         <programlisting role="example"><![CDATA[
97
98 a = mlist(["myMlistT" "field1" "field2"],"aexample","bexampleb");
99 length(a)
100 // returns 3 default behaviour if length not overloaded for mlist
101
102 // we create an overload function for mlist of type myMlistT
103 function r = %myMlistT_length(M)
104     r = length(M.field1)
105 endfunction
106
107 length(a)
108 // returns 8 result of length(a.field1)
109     ]]></programlisting>
110     </refsection>
111     <refsection role="see also">
112         <title>See also</title>
113         <simplelist type="inline">
114             <member>
115                 <link linkend="size">size</link>
116             </member>
117         </simplelist>
118     </refsection>
119     <refsection>
120         <title>History</title>
121         <revhistory>
122             <revision>
123                 <revnumber>5.4.0</revnumber>
124                 <revremark>
125                     This function allows overloading for mlist type.
126                 </revremark>
127             </revision>
128             <revision>
129                 <revnumber>6.0.0</revnumber>
130                 <revremark>
131                     <itemizedlist>
132                         <listitem>
133                             The <literal>length()</literal> of any array C of cells was formerly
134                             always 3, whatever are the number of dimensions and the sizes of the
135                             array. It is now the number of elements of the array at null depth
136                             (without recursive counting), equal to <literal>size(C, "*")</literal>.
137                         </listitem>
138                         <listitem>
139                             The <literal>length()</literal> of any array S of structures was formerly
140                             equal to its number of fields +2, whatever are the number of dimensions
141                             and the sizes of the array. It is now the number of elements of the
142                             array at null depth, equal to <literal>size(S, "*")</literal>.
143                         </listitem>
144                     </itemizedlist>
145                 </revremark>
146             </revision>
147         </revhistory>
148     </refsection>
149 </refentry>