← Back to branch summary

~ubuntu-branches/ubuntu/lucid/rhythmbox/lucid-proposed

« back to all changes in this revision

Viewing changes to doc/reference/xml/rb-refstring.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-03-29 10:12:48 UTC
  • mfrom: (1.1.45 upstream)
  • Revision ID: james.westby@ubuntu.com-20100329101248-fu29j0q1s2dx8k99
Tags: 0.12.8-0ubuntu1
* New upstream version
* debian/patches/90_autoreconf.patch:
  - new version update

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/reference/xml/rb-refstring.xml
1
 
<?xml version="1.0"?>
2
 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
3
 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
 
<refentry id="rhythmbox-rb-refstring">
5
 
<refmeta>
6
 
<refentrytitle role="top_of_page" id="rhythmbox-rb-refstring.top_of_page">rb-refstring</refentrytitle>
7
 
<manvolnum>3</manvolnum>
8
 
<refmiscinfo>RHYTHMBOX Library</refmiscinfo>
9
 
</refmeta>
10
 
 
11
 
<refnamediv>
12
 
<refname>rb-refstring</refname>
13
 
<refpurpose></refpurpose>
14
 
</refnamediv>
15
 
 
16
 
<refsynopsisdiv id="rhythmbox-rb-refstring.synopsis" role="synopsis">
17
 
<title role="synopsis.title">Synopsis</title>
18
 
 
19
 
<synopsis>
20
 
<link linkend="void">void</link>                <link linkend="rb-refstring-system-init">rb_refstring_system_init</link>            (void);
21
 
<link linkend="void">void</link>                <link linkend="rb-refstring-system-shutdown">rb_refstring_system_shutdown</link>        (void);
22
 
<link linkend="RBRefString">RBRefString</link> *       <link linkend="rb-refstring-new">rb_refstring_new</link>                    (const <link linkend="char">char</link> *init);
23
 
<link linkend="RBRefString">RBRefString</link> *       <link linkend="rb-refstring-find">rb_refstring_find</link>                   (const <link linkend="char">char</link> *init);
24
 
<link linkend="RBRefString">RBRefString</link> *       <link linkend="rb-refstring-ref">rb_refstring_ref</link>                    (<link linkend="RBRefString">RBRefString</link> *val);
25
 
<link linkend="void">void</link>                <link linkend="rb-refstring-unref">rb_refstring_unref</link>                  (<link linkend="RBRefString">RBRefString</link> *val);
26
 
const <link linkend="char">char</link> *        <link linkend="rb-refstring-get">rb_refstring_get</link>                    (const <link linkend="RBRefString">RBRefString</link> *val);
27
 
const <link linkend="char">char</link> *        <link linkend="rb-refstring-get-folded">rb_refstring_get_folded</link>             (<link linkend="RBRefString">RBRefString</link> *val);
28
 
const <link linkend="char">char</link> *        <link linkend="rb-refstring-get-sort-key">rb_refstring_get_sort_key</link>           (<link linkend="RBRefString">RBRefString</link> *val);
29
 
<link linkend="guint">guint</link>               <link linkend="rb-refstring-hash">rb_refstring_hash</link>                   (<link linkend="gconstpointer">gconstpointer</link> p);
30
 
<link linkend="gboolean">gboolean</link>            <link linkend="rb-refstring-equal">rb_refstring_equal</link>                  (<link linkend="gconstpointer">gconstpointer</link> ap,
31
 
                                                         <link linkend="gconstpointer">gconstpointer</link> bp);
32
 
</synopsis>
33
 
</refsynopsisdiv>
34
 
 
35
 
 
36
 
 
37
 
 
38
 
 
39
 
 
40
 
 
41
 
 
42
 
 
43
 
<refsect1 id="rhythmbox-rb-refstring.description" role="desc">
44
 
<title role="desc.title">Description</title>
45
 
<para>
46
 
</para>
47
 
</refsect1>
48
 
 
49
 
<refsect1 id="rhythmbox-rb-refstring.details" role="details">
50
 
<title role="details.title">Details</title>
51
 
<refsect2 id="rb-refstring-system-init" role="function">
52
 
<title>rb_refstring_system_init ()</title>
53
 
<indexterm zone="rb-refstring-system-init"><primary sortas="rb_refstring_system_init">rb_refstring_system_init</primary></indexterm><programlisting><link linkend="void">void</link>                rb_refstring_system_init            (void);</programlisting>
54
 
<para>
55
 
Sets up the refstring system.  Called on startup.</para>
56
 
<para>
57
 
</para></refsect2>
58
 
<refsect2 id="rb-refstring-system-shutdown" role="function">
59
 
<title>rb_refstring_system_shutdown ()</title>
60
 
<indexterm zone="rb-refstring-system-shutdown"><primary sortas="rb_refstring_system_shutdown">rb_refstring_system_shutdown</primary></indexterm><programlisting><link linkend="void">void</link>                rb_refstring_system_shutdown        (void);</programlisting>
61
 
<para>
62
 
Frees all data associated with the refstring system.
63
 
Only called on shutdown.</para>
64
 
<para>
65
 
</para></refsect2>
66
 
<refsect2 id="rb-refstring-new" role="function">
67
 
<title>rb_refstring_new ()</title>
68
 
<indexterm zone="rb-refstring-new"><primary sortas="rb_refstring_new">rb_refstring_new</primary></indexterm><programlisting><link linkend="RBRefString">RBRefString</link> *       rb_refstring_new                    (const <link linkend="char">char</link> *init);</programlisting>
69
 
<para>
70
 
Returns an <link linkend="RBRefString"><type>RBRefString</type></link> for the specified string.
71
 
If one already exists, its reference count is incremented and it is
72
 
returned.  Otherwise, a new <link linkend="RBRefString"><type>RBRefString</type></link> is created and returned.</para>
73
 
<para>
74
 
</para><variablelist role="params">
75
 
<varlistentry><term><parameter>init</parameter>&#160;:</term>
76
 
<listitem><simpara> string to intern
77
 
</simpara></listitem></varlistentry>
78
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="RBRefString"><type>RBRefString</type></link> for <parameter>init</parameter>
79
 
</simpara></listitem></varlistentry>
80
 
</variablelist></refsect2>
81
 
<refsect2 id="rb-refstring-find" role="function">
82
 
<title>rb_refstring_find ()</title>
83
 
<indexterm zone="rb-refstring-find"><primary sortas="rb_refstring_find">rb_refstring_find</primary></indexterm><programlisting><link linkend="RBRefString">RBRefString</link> *       rb_refstring_find                   (const <link linkend="char">char</link> *init);</programlisting>
84
 
<para>
85
 
Returns an existing <link linkend="RBRefString"><type>RBRefString</type></link> for <parameter>init</parameter> if one exists,
86
 
otherwise returns NULL.  If an existing refstring is found,
87
 
its reference count is increased.</para>
88
 
<para>
89
 
</para><variablelist role="params">
90
 
<varlistentry><term><parameter>init</parameter>&#160;:</term>
91
 
<listitem><simpara> string to find
92
 
</simpara></listitem></varlistentry>
93
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> existing <link linkend="RBRefString"><type>RBRefString</type></link>, or NULL
94
 
</simpara></listitem></varlistentry>
95
 
</variablelist></refsect2>
96
 
<refsect2 id="rb-refstring-ref" role="function">
97
 
<title>rb_refstring_ref ()</title>
98
 
<indexterm zone="rb-refstring-ref"><primary sortas="rb_refstring_ref">rb_refstring_ref</primary></indexterm><programlisting><link linkend="RBRefString">RBRefString</link> *       rb_refstring_ref                    (<link linkend="RBRefString">RBRefString</link> *val);</programlisting>
99
 
<para>
100
 
Increases the reference count for an existing <link linkend="RBRefString"><type>RBRefString</type></link>.
101
 
The refstring is returned for convenience.</para>
102
 
<para>
103
 
</para><variablelist role="params">
104
 
<varlistentry><term><parameter>val</parameter>&#160;:</term>
105
 
<listitem><simpara> a <link linkend="RBRefString"><type>RBRefString</type></link> to reference
106
 
</simpara></listitem></varlistentry>
107
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the same refstring
108
 
</simpara></listitem></varlistentry>
109
 
</variablelist></refsect2>
110
 
<refsect2 id="rb-refstring-unref" role="function">
111
 
<title>rb_refstring_unref ()</title>
112
 
<indexterm zone="rb-refstring-unref"><primary sortas="rb_refstring_unref">rb_refstring_unref</primary></indexterm><programlisting><link linkend="void">void</link>                rb_refstring_unref                  (<link linkend="RBRefString">RBRefString</link> *val);</programlisting>
113
 
<para>
114
 
Drops a reference to an <link linkend="RBRefString"><type>RBRefString</type></link>.  If this is the last
115
 
reference, the string will be freed.</para>
116
 
<para>
117
 
</para><variablelist role="params">
118
 
<varlistentry><term><parameter>val</parameter>&#160;:</term>
119
 
<listitem><simpara> <link linkend="RBRefString"><type>RBRefString</type></link> to unref
120
 
</simpara></listitem></varlistentry>
121
 
</variablelist></refsect2>
122
 
<refsect2 id="rb-refstring-get" role="function">
123
 
<title>rb_refstring_get ()</title>
124
 
<indexterm zone="rb-refstring-get"><primary sortas="rb_refstring_get">rb_refstring_get</primary></indexterm><programlisting>const <link linkend="char">char</link> *        rb_refstring_get                    (const <link linkend="RBRefString">RBRefString</link> *val);</programlisting>
125
 
<para>
126
 
Returns the actual string for a <link linkend="RBRefString"><type>RBRefString</type></link>.</para>
127
 
<para>
128
 
</para><variablelist role="params">
129
 
<varlistentry><term><parameter>val</parameter>&#160;:</term>
130
 
<listitem><simpara> an <link linkend="RBRefString"><type>RBRefString</type></link>
131
 
</simpara></listitem></varlistentry>
132
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> underlying string, must not be freed
133
 
</simpara></listitem></varlistentry>
134
 
</variablelist></refsect2>
135
 
<refsect2 id="rb-refstring-get-folded" role="function">
136
 
<title>rb_refstring_get_folded ()</title>
137
 
<indexterm zone="rb-refstring-get-folded"><primary sortas="rb_refstring_get_folded">rb_refstring_get_folded</primary></indexterm><programlisting>const <link linkend="char">char</link> *        rb_refstring_get_folded             (<link linkend="RBRefString">RBRefString</link> *val);</programlisting>
138
 
<para>
139
 
Returns the case-folded version of the string underlying <parameter>val</parameter>.
140
 
The case-folded string is cached inside the <link linkend="RBRefString"><type>RBRefString</type></link> for
141
 
speed.  See <parameter>rb_search_fold</parameter> for information on case-folding
142
 
strings.</para>
143
 
<para>
144
 
</para><variablelist role="params">
145
 
<varlistentry><term><parameter>val</parameter>&#160;:</term>
146
 
<listitem><simpara> an <link linkend="RBRefString"><type>RBRefString</type></link>
147
 
</simpara></listitem></varlistentry>
148
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> case-folded string, must not be freed
149
 
</simpara></listitem></varlistentry>
150
 
</variablelist></refsect2>
151
 
<refsect2 id="rb-refstring-get-sort-key" role="function">
152
 
<title>rb_refstring_get_sort_key ()</title>
153
 
<indexterm zone="rb-refstring-get-sort-key"><primary sortas="rb_refstring_get_sort_key">rb_refstring_get_sort_key</primary></indexterm><programlisting>const <link linkend="char">char</link> *        rb_refstring_get_sort_key           (<link linkend="RBRefString">RBRefString</link> *val);</programlisting>
154
 
<para>
155
 
Returns the sort key version of the string underlying <parameter>val</parameter>.
156
 
The sort key string is cached inside the <link linkend="RBRefString"><type>RBRefString</type></link> for speed.
157
 
Sort key strings are not generally human readable, so don't display
158
 
them anywhere.  See <parameter>g_utf8_collate_key_for_filename</parameter> for information
159
 
on sort keys.</para>
160
 
<para>
161
 
</para><variablelist role="params">
162
 
<varlistentry><term><parameter>val</parameter>&#160;:</term>
163
 
<listitem><simpara> an <link linkend="RBRefString"><type>RBRefString</type></link>
164
 
</simpara></listitem></varlistentry>
165
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> sort key string, must not be freed.
166
 
</simpara></listitem></varlistentry>
167
 
</variablelist></refsect2>
168
 
<refsect2 id="rb-refstring-hash" role="function">
169
 
<title>rb_refstring_hash ()</title>
170
 
<indexterm zone="rb-refstring-hash"><primary sortas="rb_refstring_hash">rb_refstring_hash</primary></indexterm><programlisting><link linkend="guint">guint</link>               rb_refstring_hash                   (<link linkend="gconstpointer">gconstpointer</link> p);</programlisting>
171
 
<para>
172
 
Hash function suitable for use with <parameter>GHashTable</parameter>.</para>
173
 
<para>
174
 
</para><variablelist role="params">
175
 
<varlistentry><term><parameter>p</parameter>&#160;:</term>
176
 
<listitem><simpara> an <link linkend="RBRefString"><type>RBRefString</type></link>
177
 
</simpara></listitem></varlistentry>
178
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> hash value for the string underlying <parameter>p</parameter>
179
 
</simpara></listitem></varlistentry>
180
 
</variablelist></refsect2>
181
 
<refsect2 id="rb-refstring-equal" role="function">
182
 
<title>rb_refstring_equal ()</title>
183
 
<indexterm zone="rb-refstring-equal"><primary sortas="rb_refstring_equal">rb_refstring_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            rb_refstring_equal                  (<link linkend="gconstpointer">gconstpointer</link> ap,
184
 
                                                         <link linkend="gconstpointer">gconstpointer</link> bp);</programlisting>
185
 
<para>
186
 
Key equality function suitable for use with <link linkend="GHashTable"><type>GHashTable</type></link>.
187
 
Equality checks for <link linkend="RBRefString"><type>RBRefString</type></link> are just pointer comparisons,
188
 
since there can only be one refstring for a given string.</para>
189
 
<para>
190
 
</para><variablelist role="params">
191
 
<varlistentry><term><parameter>ap</parameter>&#160;:</term>
192
 
<listitem><simpara> an <link linkend="RBRefString"><type>RBRefString</type></link>
193
 
</simpara></listitem></varlistentry>
194
 
<varlistentry><term><parameter>bp</parameter>&#160;:</term>
195
 
<listitem><simpara> another <link linkend="RBRefstring"><type>RBRefstring</type></link>
196
 
</simpara></listitem></varlistentry>
197
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the strings are the same
198
 
</simpara></listitem></varlistentry>
199
 
</variablelist></refsect2>
200
 
 
201
 
</refsect1>
202
 
 
203
 
 
204
 
 
205
 
 
206
 
</refentry>