← Back to branch summary

~ubuntu-branches/ubuntu/karmic/libtinymail/karmic

« back to all changes in this revision

Viewing changes to docs/devel/reference/xml/tny-iterator.xml

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2007-10-12 11:21:12 UTC
  • Revision ID: james.westby@ubuntu.com-20071012112112-fod9fs7yrooxjr7i
Tags: upstream-0.0.2
Import upstream version 0.0.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/devel/reference/xml/tny-iterator.xml
 
1
<refentry id="libtinymail-tny-iterator">
 
2
<refmeta>
 
3
<refentrytitle role="top_of_page">TnyIterator</refentrytitle>
 
4
<manvolnum>3</manvolnum>
 
5
<refmiscinfo>LIBTINYMAIL Library</refmiscinfo>
 
6
</refmeta>
 
7
 
 
8
<refnamediv>
 
9
<refname>TnyIterator</refname>
 
10
<refpurpose>A iterator type for a list</refpurpose>
 
11
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
 
12
</refnamediv>
 
13
 
 
14
<refsynopsisdiv role="synopsis">
 
15
<title role="synopsis.title">Synopsis</title>
 
16
<anchor id="TnyIterator"/>
 
17
<synopsis>
 
18
 
 
19
 
 
20
 
 
21
                    <link linkend="TnyIterator-struct">TnyIterator</link>;
 
22
                    <link linkend="TnyIteratorIface">TnyIteratorIface</link>;
 
23
<link linkend="void">void</link>                <link linkend="tny-iterator-next">tny_iterator_next</link>                   (<link linkend="TnyIterator">TnyIterator</link> *self);
 
24
<link linkend="void">void</link>                <link linkend="tny-iterator-prev">tny_iterator_prev</link>                   (<link linkend="TnyIterator">TnyIterator</link> *self);
 
25
<link linkend="void">void</link>                <link linkend="tny-iterator-first">tny_iterator_first</link>                  (<link linkend="TnyIterator">TnyIterator</link> *self);
 
26
<link linkend="void">void</link>                <link linkend="tny-iterator-nth">tny_iterator_nth</link>                    (<link linkend="TnyIterator">TnyIterator</link> *self,
 
27
                                                         <link linkend="guint">guint</link> nth);
 
28
<link linkend="GObject">GObject</link>*            <link linkend="tny-iterator-get-current">tny_iterator_get_current</link>            (<link linkend="TnyIterator">TnyIterator</link> *self);
 
29
<link linkend="gboolean">gboolean</link>            <link linkend="tny-iterator-is-done">tny_iterator_is_done</link>                (<link linkend="TnyIterator">TnyIterator</link> *self);
 
30
<link linkend="TnyList">TnyList</link>*            <link linkend="tny-iterator-get-list">tny_iterator_get_list</link>               (<link linkend="TnyIterator">TnyIterator</link> *self);
 
31
 
 
32
</synopsis>
 
33
</refsynopsisdiv>
 
34
 
 
35
<refsect1 role="object_hierarchy">
 
36
<title role="object_hierarchy.title">Object Hierarchy</title>
 
37
<synopsis>
 
38
 
 
39
  <link linkend="GInterface">GInterface</link>
 
40
   +----TnyIterator
 
41
</synopsis>
 
42
 
 
43
</refsect1>
 
44
 
 
45
 
 
46
 
 
47
 
 
48
 
 
49
 
 
50
 
 
51
 
 
52
<refsect1 role="desc">
 
53
<title role="desc.title">Description</title>
 
54
<para>
 
55
An iterator for a <link linkend="TnyList"><type>TnyList</type></link> is used for iterating over a list. The iterator is an instance that keeps the
 
56
position state information. The <link linkend="TnyList"><type>TnyList</type></link> instance will not by itself keep a position state. Only iterators
 
57
can keep a position state for a list.
 
58
</para>
 
59
</refsect1>
 
60
 
 
61
<refsect1 role="details">
 
62
<title role="details.title">Details</title>
 
63
<refsect2>
 
64
<title><anchor id="TnyIterator-struct" role="struct"/>TnyIterator</title>
 
65
<indexterm><primary>TnyIterator</primary></indexterm><programlisting>typedef struct _TnyIterator TnyIterator;</programlisting>
 
66
<para>
 
67
 
 
68
</para></refsect2>
 
69
<refsect2>
 
70
<title><anchor id="TnyIteratorIface" role="struct"/>TnyIteratorIface</title>
 
71
<indexterm><primary>TnyIteratorIface</primary></indexterm><programlisting>typedef struct {
 
72
        GTypeInterface parent;
 
73
 
 
74
        void (*next_func) (TnyIterator *self);
 
75
        void (*prev_func) (TnyIterator *self);
 
76
        void (*first_func) (TnyIterator *self);
 
77
        void (*nth_func) (TnyIterator *self, guint nth);
 
78
        GObject* (*get_current_func) (TnyIterator *self);
 
79
 
 
80
        gboolean (*is_done) (TnyIterator *self);
 
81
        TnyList* (*get_list_func) (TnyIterator *self);
 
82
} TnyIteratorIface;
 
83
</programlisting>
 
84
<para>
 
85
 
 
86
</para></refsect2>
 
87
<refsect2>
 
88
<title><anchor id="tny-iterator-next" role="function"/>tny_iterator_next ()</title>
 
89
<indexterm><primary>tny_iterator_next</primary></indexterm><programlisting><link linkend="void">void</link>                tny_iterator_next                   (<link linkend="TnyIterator">TnyIterator</link> *self);</programlisting>
 
90
<para>
 
91
Moves the iterator to the next node</para>
 
92
<para>
 
93
 
 
94
</para><variablelist role="params">
 
95
<varlistentry><term><parameter>self</parameter>&nbsp;:</term>
 
96
<listitem><simpara> A <link linkend="TnyIterator"><type>TnyIterator</type></link> instance
 
97
</simpara></listitem></varlistentry>
 
98
</variablelist></refsect2>
 
99
<refsect2>
 
100
<title><anchor id="tny-iterator-prev" role="function"/>tny_iterator_prev ()</title>
 
101
<indexterm><primary>tny_iterator_prev</primary></indexterm><programlisting><link linkend="void">void</link>                tny_iterator_prev                   (<link linkend="TnyIterator">TnyIterator</link> *self);</programlisting>
 
102
<para>
 
103
Moves the iterator to the previous node</para>
 
104
<para>
 
105
 
 
106
</para><variablelist role="params">
 
107
<varlistentry><term><parameter>self</parameter>&nbsp;:</term>
 
108
<listitem><simpara> A <link linkend="TnyIterator"><type>TnyIterator</type></link> instance
 
109
</simpara></listitem></varlistentry>
 
110
</variablelist></refsect2>
 
111
<refsect2>
 
112
<title><anchor id="tny-iterator-first" role="function"/>tny_iterator_first ()</title>
 
113
<indexterm><primary>tny_iterator_first</primary></indexterm><programlisting><link linkend="void">void</link>                tny_iterator_first                  (<link linkend="TnyIterator">TnyIterator</link> *self);</programlisting>
 
114
<para>
 
115
Moves the iterator to the first node</para>
 
116
<para>
 
117
 
 
118
</para><variablelist role="params">
 
119
<varlistentry><term><parameter>self</parameter>&nbsp;:</term>
 
120
<listitem><simpara> A <link linkend="TnyIterator"><type>TnyIterator</type></link> instance
 
121
</simpara></listitem></varlistentry>
 
122
</variablelist></refsect2>
 
123
<refsect2>
 
124
<title><anchor id="tny-iterator-nth" role="function"/>tny_iterator_nth ()</title>
 
125
<indexterm><primary>tny_iterator_nth</primary></indexterm><programlisting><link linkend="void">void</link>                tny_iterator_nth                    (<link linkend="TnyIterator">TnyIterator</link> *self,
 
126
                                                         <link linkend="guint">guint</link> nth);</programlisting>
 
127
<para>
 
128
Moves the iterator to the nth node</para>
 
129
<para>
 
130
 
 
131
</para><variablelist role="params">
 
132
<varlistentry><term><parameter>self</parameter>&nbsp;:</term>
 
133
<listitem><simpara> A <link linkend="TnyIterator"><type>TnyIterator</type></link> instance
 
134
</simpara></listitem></varlistentry>
 
135
<varlistentry><term><parameter>nth</parameter>&nbsp;:</term>
 
136
<listitem><simpara> The nth position
 
137
</simpara></listitem></varlistentry>
 
138
</variablelist></refsect2>
 
139
<refsect2>
 
140
<title><anchor id="tny-iterator-get-current" role="function"/>tny_iterator_get_current ()</title>
 
141
<indexterm><primary>tny_iterator_get_current</primary></indexterm><programlisting><link linkend="GObject">GObject</link>*            tny_iterator_get_current            (<link linkend="TnyIterator">TnyIterator</link> *self);</programlisting>
 
142
<para>
 
143
Does not move the iterator. Returns the object at the current position. If
 
144
there's no current position, this method returns NULL. If not NULL, the 
 
145
returned value must be unreferenced after use.</para>
 
146
<para>
 
147
 
 
148
</para><variablelist role="params">
 
149
<varlistentry><term><parameter>self</parameter>&nbsp;:</term>
 
150
<listitem><simpara> A <link linkend="TnyIterator"><type>TnyIterator</type></link> instance
 
151
</simpara></listitem></varlistentry>
 
152
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the currect object or NULL
 
153
 
 
154
</simpara></listitem></varlistentry>
 
155
</variablelist></refsect2>
 
156
<refsect2>
 
157
<title><anchor id="tny-iterator-is-done" role="function"/>tny_iterator_is_done ()</title>
 
158
<indexterm><primary>tny_iterator_is_done</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            tny_iterator_is_done                (<link linkend="TnyIterator">TnyIterator</link> *self);</programlisting>
 
159
<para>
 
160
Does the iterator point to some valid list item? You can use this property
 
161
to make loops like:
 
162
</para>
 
163
<para>
 
164
Example:
 
165
<informalexample><programlisting>
 
166
TnyList *list = tny_simple_list_new ();
 
167
TnyIterator *iter = tny_list_create_iterator (list);
 
168
while (!tny_iterator_is_done (iter))
 
169
{
 
170
   GObject *cur = tny_iterator_get_current (iter);
 
171
   ...
 
172
   g_object_unref (cur);
 
173
   tny_iterator_next (iter);
 
174
}
 
175
g_object_unref (G_OBJECT (iter));
 
176
g_object_unref (G_OBJECT (list));
 
177
</programlisting></informalexample></para>
 
178
<para>
 
179
 
 
180
</para><variablelist role="params">
 
181
<varlistentry><term><parameter>self</parameter>&nbsp;:</term>
 
182
<listitem><simpara> A <link linkend="TnyIterator"><type>TnyIterator</type></link> instance
 
183
</simpara></listitem></varlistentry>
 
184
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> TRUE if it points to a valid list item, FALSE otherwise
 
185
 
 
186
</simpara></listitem></varlistentry>
 
187
</variablelist></refsect2>
 
188
<refsect2>
 
189
<title><anchor id="tny-iterator-get-list" role="function"/>tny_iterator_get_list ()</title>
 
190
<indexterm><primary>tny_iterator_get_list</primary></indexterm><programlisting><link linkend="TnyList">TnyList</link>*            tny_iterator_get_list               (<link linkend="TnyIterator">TnyIterator</link> *self);</programlisting>
 
191
<para>
 
192
Does not move the iterator. Returns the list of which this iterator is an
 
193
iterator. The returned list object should be unreferenced after use. Remember
 
194
when using this property that lists shouldn't change while iterating them.</para>
 
195
<para>
 
196
 
 
197
</para><variablelist role="params">
 
198
<varlistentry><term><parameter>self</parameter>&nbsp;:</term>
 
199
<listitem><simpara> A <link linkend="TnyIterator"><type>TnyIterator</type></link> instance
 
200
</simpara></listitem></varlistentry>
 
201
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The <link linkend="TnyList"><type>TnyList</type></link> instance being iterated
 
202
 
 
203
</simpara></listitem></varlistentry>
 
204
</variablelist></refsect2>
 
205
 
 
206
</refsect1>
 
207
 
 
208
 
 
209
 
 
210
<refsect1>
 
211
<title>See Also</title>
 
212
<para>
 
213
<link linkend="TnyList"><type>TnyList</type></link>
 
214
</para>
 
215
</refsect1>
 
216
 
 
217
</refentry>