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>