7fcb8a0a7f25b366e5f81a4f8fe3bb4c1de28a18
[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"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xml:id="length" xml:lang="en">
20     <refnamediv>
21         <refname>length</refname>
22         <refpurpose>Number of characters of a string. Number of elements of an array or list.</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>n = length(M)</synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>M</term>
33                 <listitem>
34                     <para>
35                         a matrix (usual or polynomial or character string) or a
36                         list.
37                     </para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>n</term>
42                 <listitem>
43                     <para>an integer or a matrix of integers.</para>
44                 </listitem>
45             </varlistentry>
46         </variablelist>
47     </refsection>
48     <refsection>
49         <title>Description</title>
50         <para>
51             For usual or polynomial matrix <varname>n</varname> is the integer
52             equal to number of rows times number of columns
53             of <varname>M</varname>. (Also valid for <varname>M</varname>
54             a boolean matrix).
55         </para>
56         <para>
57             For matrices made of character strings (and in particular for a
58             character string) <function>length</function> returns in
59             <varname>n</varname> the length of entries of the matrix of
60             character strings <varname>M</varname>.
61         </para>
62         <para>
63             The length of a list is the number of elements in the list (also
64             given by <function>size</function>).
65         </para>
66         <para>
67             The length of an array M of cells or of structures is the number of elements of the array.
68             It is equivalent to <literal>size(M, "*")</literal>.
69         </para>
70         <para>
71             The length of a mlist is by default the number of elements in the
72             mlist, but you can overload it (see example). Note that for a non-string
73             hypermatrix, there is no need to overload the function. Indeed, <function>length</function>
74             returns the product of the dimensions of the hypermatrix.
75         </para>
76         <para>
77             <code>length('123')</code> is <literal>3</literal>.
78             <code>length([1,2;3,4])</code> is <literal>4</literal>.
79         </para>
80         <para>
81             <warning>
82                 WARNING : <function>length</function> of a sparse matrix
83                 returns the max of dimensions and not the product
84                 of the dimensions. (For example:
85                 <code>length(sparse(eye(12,2)))</code>
86                 returns <code>max(12,2)</code> and not <literal>24</literal>).
87                 Please use <literal>size(...,'*')</literal> with sparse matrix.
88             </warning>
89         </para>
90     </refsection>
91     <refsection>
92         <title>Examples</title>
93         <programlisting role="example"><![CDATA[
94 length([123 ; 456 ])
95 length(['hello world',SCI])
96 length(rand(2,2,2))
97
98     ]]></programlisting>
99         <programlisting role="example"><![CDATA[
100
101 a = mlist(["myMlistT" "field1" "field2"],"aexample","bexampleb");
102 length(a)
103 // returns 3 default behaviour if length not overloaded for mlist
104
105 // we create an overload function for mlist of type myMlistT
106 function r = %myMlistT_length(M)
107     r = length(M.field1)
108 endfunction
109
110 length(a)
111 // returns 8 result of length(a.field1)
112     ]]></programlisting>
113     </refsection>
114     <refsection role="see also">
115         <title>See also</title>
116         <simplelist type="inline">
117             <member>
118                 <link linkend="size">size</link>
119             </member>
120         </simplelist>
121     </refsection>
122     <refsection>
123         <title>History</title>
124         <revhistory>
125             <revision>
126                 <revnumber>5.4.0</revnumber>
127                 <revremark>
128                     This function allows overloading for mlist type.
129                 </revremark>
130             </revision>
131             <revision>
132                 <revnumber>6.0.0</revnumber>
133                 <revremark>
134                     <itemizedlist>
135                         <listitem>
136                             The <literal>length()</literal> of any array C of cells was formerly
137                             always 3, whatever are the number of dimensions and the sizes of the
138                             array. It is now the number of elements of the array at null depth
139                             (without recursive counting), equal to <literal>size(C, "*")</literal>.
140                         </listitem>
141                         <listitem>
142                             The <literal>length()</literal> of any array S of structures was formerly
143                             equal to its number of fields +2, whatever are the number of dimensions
144                             and the sizes of the array. It is now the number of elements of the
145                             array at null depth, equal to <literal>size(S, "*")</literal>.
146                         </listitem>
147                     </itemizedlist>
148                 </revremark>
149             </revision>
150         </revhistory>
151     </refsection>
152 </refentry>