3ae0fe5353dde3edb02f93077fd11ef77b7b4fce
[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-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>Create 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>Vector containing the dimensions of the cell to create.</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>m1, m2,..</term>
39                 <listitem>
40                     <para>Dimensions of the cell to create.</para>
41                 </listitem>
42             </varlistentry>
43         </variablelist>
44     </refsection>
45     <refsection>
46         <title>Description</title>
47         <para>Returns the create cell of empty matrices.</para>
48         <variablelist>
49             <varlistentry>
50                 <term>cell()</term>
51                 <listitem>
52                     <para>
53                         returns a <literal>(0,0)</literal> cell array of empty
54                         matrices.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>cell(m1)</term>
60                 <listitem>
61                     <para>
62                         returns a <literal>(m1,m1)</literal> cell array of empty
63                         matrices.
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>cell(m1,m2)</term>
69                 <listitem>
70                     <para>
71                         returns a <literal>(m1,m2) </literal>cell array of empty
72                         matrices.
73                     </para>
74                 </listitem>
75             </varlistentry>
76             <varlistentry>
77                 <term>cell(m1,m2,..,mn)</term>
78                 <listitem>
79                     <para>
80                         creates a <literal>(m1,m2,..,mn)</literal> cell array of empty
81                         matrices.
82                     </para>
83                 </listitem>
84             </varlistentry>
85             <varlistentry>
86                 <term>cell(x)</term>
87                 <listitem>
88                     <para>returns a cell array of empty matrices with: the first
89                         dimension of the cell array is <literal>x(1)</literal>, the second
90                         dimension is <literal>x(2), ...</literal>
91                     </para>
92                 </listitem>
93             </varlistentry>
94         </variablelist>
95     </refsection>
96     <refsection>
97         <title>Remarks</title>
98         <para>
99             <literal>cell(x) </literal>is not the same size that
100             <literal>x</literal>.
101         </para>
102         <para>
103             <literal>cell()</literal> is equivalent to
104             <literal>cell(0)</literal>.
105         </para>
106         <para>If A is a cell array, you can access the contents of an element of A
107             by using <literal>A(m1, m2, ..., mn).entries</literal>, the expression
108             <literal>A(1,1) = zeros(2,2)</literal> is not valid, the right syntax is
109             <literal>A(1,1).entries = zeros(2,2)</literal>.
110         </para>
111         <para>If A is a cell array, you can get its dimensions by using
112             <literal>A.dims</literal> which returns an <literal>int32</literal> value that cannot be used as a subscript for the cell array. In this case, the best way to get the cell array dimensions is <literal>size(A)</literal>.
113         </para>
114     </refsection>
115     <refsection>
116         <title>Examples</title>
117         <programlisting role="example"><![CDATA[ 
118 a=cell(3)
119 b=cell(3,1)
120 c=cell([2,3,4])
121
122 // Assigning cell entries
123 b=cell(3,1);
124
125 // Assigning the first element of b using the 'entries' field
126 b(1).entries=1:3
127
128 // Assigning the second element of b using the 'entries' field
129 b(2).entries='Scilab'
130
131 // Assigning the third element of b using the 'entries' field
132 b(3).entries=poly(1:3,'s')
133
134 // Assigning sub-cells
135 X=cell(3,2);
136 X(:,1)=b
137
138 // Extracting a sub-cell: result is a cell
139 b(1)
140 b(1:2)
141
142 // Extracting a sub-cell value: result is an array
143 b(1).entries
144
145 // Dimensions of b as an int32 value (cannont be used as an index)
146 b.dims
147 // Dimensions of b as a double value
148 size(b)
149
150  ]]></programlisting>
151     </refsection>
152     <refsection role="see also">
153         <title>See Also</title>
154         <simplelist type="inline">
155             <member>
156                 <link linkend="eye">eye</link>
157             </member>
158             <member>
159                 <link linkend="ones">ones</link>
160             </member>
161             <member>
162                 <link linkend="zeros">zeros</link>
163             </member>
164         </simplelist>
165     </refsection>
166 </refentry>