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 text. 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>