Update cell help page.
[scilab.git] / scilab / modules / data_structures / help / en_US / cell.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) 2007-2008 - INRIA
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
11  *
12  -->
13 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="cell" xml:lang="en">
14     <refnamediv>
15         <refname>cell</refname>
16         <refpurpose>creates a cell array of empty matrices</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>
21             c = cell()
22             c = cell(m1)
23             c = cell(m1, m2)
24             c = cell(m1, m2, ..., mn)
25             c = cell(x)
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>x</term>
33                 <listitem>
34                     <para>
35                         a vector containing the dimensions of the cell to create.
36                     </para>
37                 </listitem>
38             </varlistentry>
39             <varlistentry>
40                 <term>m1, m2, ..., mn</term>
41                 <listitem>
42                     <para>
43                         dimensions of the cell to create.
44                     </para>
45                 </listitem>
46             </varlistentry>
47         </variablelist>
48     </refsection>
49     <refsection>
50         <title>Description</title>
51         <para>
52             <function>cell</function> returns a cell array of empty matrices.
53         </para>
54         <variablelist>
55             <varlistentry>
56                 <term>cell()</term>
57                 <listitem>
58                     <para>
59                         returns a <literal>(0, 0)</literal> cell array of empty matrices.
60                     </para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>cell(m1)</term>
65                 <listitem>
66                     <para>
67                         returns a <literal>(m1, m1)</literal> cell array of empty matrices.
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>cell(m1, m2)</term>
73                 <listitem>
74                     <para>
75                         returns a <literal>(m1, m2) </literal> cell array of empty matrices.
76                     </para>
77                 </listitem>
78             </varlistentry>
79             <varlistentry>
80                 <term>cell(m1,m2,..,mn)</term>
81                 <listitem>
82                     <para>
83                         creates a <literal>(m1, m2, ..., mn)</literal> cell array of empty matrices.
84                     </para>
85                 </listitem>
86             </varlistentry>
87             <varlistentry>
88                 <term>cell(x)</term>
89                 <listitem>
90                     <para>
91                         returns a cell array of empty matrices with: the first dimension of the cell array is <literal>x(1)</literal>, the second dimension is <literal>x(2)</literal> and so on.
92                     </para>
93                 </listitem>
94             </varlistentry>
95         </variablelist>
96     </refsection>
97     <refsection>
98         <title>Remarks</title>
99         <para>
100             <code>cell(x)</code> is not the same size that <varname>x</varname>.
101         </para>
102         <para>
103             <code>cell()</code> is equivalent to <code>cell(0)</code>.
104         </para>
105         <para>
106             If <literal>A</literal> is a cell array, you can access the contents of an element of <literal>A</literal> by using <code>A{m1, m2, ..., mn}</code>. The expression <code>A(1,1) = zeros(2,2)</code> is not valid, the right syntax is
107             <code>A{1,1} = zeros(2,2)</code>.
108         </para>
109     </refsection>
110     <refsection>
111         <title>Examples</title>
112         <programlisting role="example"><![CDATA[ 
113 a = cell(3)
114 b = cell(3,1)
115 c = cell([2,3,4])
116  
117 // Assigning cell entries
118 b = cell(3,1);
119  
120 // Assigning the first element of b using {}
121 b{1} = 1:3
122  
123 // Assigning the second element of b using {}
124 b{2} = 'Scilab'
125  
126 // Assigning the third element of b using the 'entries' field
127 b{3} = poly(1:3,'s')
128  
129 // Assigning sub-cells
130 X = cell(3,2);
131 X{:,1} = b
132  
133 // Extracting a sub-cell: result is a cell
134 b{1}
135 b{1:2}
136  
137 // Extracting a sub-cell value: result is an array
138 b{1}
139  
140 // Dimensions of b as a double value
141 size(b)
142  ]]></programlisting>
143     </refsection>
144     <refsection role="see also">
145         <title>See Also</title>
146         <simplelist type="inline">
147             <member>
148                 <link linkend="eye">eye</link>
149             </member>
150             <member>
151                 <link linkend="ones">ones</link>
152             </member>
153             <member>
154                 <link linkend="zeros">zeros</link>
155             </member>
156             <member>
157                 <link linkend="iscell">iscell</link>
158             </member>
159         </simplelist>
160     </refsection>
161     <refsection>
162         <title>History</title>
163         <revhistory>
164             <revision>
165                 <revnumber>6.0.0</revnumber>
166                 <revremark>
167                     <para>
168                         Fields "entries" and "dims" do not exist anymore. To assign or extract an element, use {}.
169                     </para>
170                 </revremark>
171             </revision>
172         </revhistory>
173     </refsection>
174 </refentry>