Mercurial > pidgin3 / file comparison

comparison: libpurple/stringref.h

libpurple/stringref.h

changeset 15884
4de1981757fc
parent 15435
4b933b06d75e
child 16238
33bf2fd32108
child 18068
b6554e3c8224
child 19050
78ed2f8cd58d
child 20478
46933dc62880
equal deleted inserted replaced
15883:969b74a3e27a 15884:4de1981757fc
1 /** 1 /**
2 * @file stringref.h Reference-counted immutable strings 2 * @file stringref.h Reference-counted immutable strings
3 * @ingroup core 3 * @ingroup core
4 * 4 *
5 * gaim 5 * purple
6 * 6 *
7 * Gaim is the legal property of its developers, whose names are too numerous 7 * Purple is the legal property of its developers, whose names are too numerous
8 * to list here. Please refer to the COPYRIGHT file distributed with this 8 * to list here. Please refer to the COPYRIGHT file distributed with this
9 * source distribution. 9 * source distribution.
10 * 10 *
11 * This program is free software; you can redistribute it and/or modify 11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by 12 * it under the terms of the GNU General Public License as published by
21 * You should have received a copy of the GNU General Public License 21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, write to the Free Software 22 * along with this program; if not, write to the Free Software
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 * 24 *
25 */ 25 */
26 #ifndef _GAIM_STRINGREF_H_ 26 #ifndef _PURPLE_STRINGREF_H_
27 #define _GAIM_STRINGREF_H_ 27 #define _PURPLE_STRINGREF_H_
28 28
29 #ifdef __cplusplus 29 #ifdef __cplusplus
30 extern "C" { 30 extern "C" {
31 #endif 31 #endif
32 32
33 typedef struct _GaimStringref GaimStringref; 33 typedef struct _PurpleStringref PurpleStringref;
34 34
35 /** 35 /**
36 * Creates an immutable reference-counted string object. The newly 36 * Creates an immutable reference-counted string object. The newly
37 * created object will have a reference count of 1. 37 * created object will have a reference count of 1.
38 * 38 *
40 * duplicated. 40 * duplicated.
41 * 41 *
42 * @return A newly allocated string reference object with a refcount 42 * @return A newly allocated string reference object with a refcount
43 * of 1. 43 * of 1.
44 */ 44 */
45 GaimStringref *gaim_stringref_new(const char *value); 45 PurpleStringref *purple_stringref_new(const char *value);
46 46
47 /** 47 /**
48 * Creates an immutable reference-counted string object. The newly 48 * Creates an immutable reference-counted string object. The newly
49 * created object will have a reference count of zero, and if it is 49 * created object will have a reference count of zero, and if it is
50 * not referenced before the next iteration of the mainloop it will 50 * not referenced before the next iteration of the mainloop it will
54 * duplicated. 54 * duplicated.
55 * 55 *
56 * @return A newly allocated string reference object with a refcount 56 * @return A newly allocated string reference object with a refcount
57 * of zero. 57 * of zero.
58 */ 58 */
59 GaimStringref *gaim_stringref_new_noref(const char *value); 59 PurpleStringref *purple_stringref_new_noref(const char *value);
60 60
61 /** 61 /**
62 * Creates an immutable reference-counted string object from a printf 62 * Creates an immutable reference-counted string object from a printf
63 * format specification and arguments. The created object will have a 63 * format specification and arguments. The created object will have a
64 * reference count of 1. 64 * reference count of 1.
66 * @param format A printf-style format specification. 66 * @param format A printf-style format specification.
67 * 67 *
68 * @return A newly allocated string reference object with a refcount 68 * @return A newly allocated string reference object with a refcount
69 * of 1. 69 * of 1.
70 */ 70 */
71 GaimStringref *gaim_stringref_printf(const char *format, ...); 71 PurpleStringref *purple_stringref_printf(const char *format, ...);
72 72
73 /** 73 /**
74 * Increase the reference count of the given stringref. 74 * Increase the reference count of the given stringref.
75 * 75 *
76 * @param stringref String to be referenced. 76 * @param stringref String to be referenced.
77 * 77 *
78 * @return A pointer to the referenced string. 78 * @return A pointer to the referenced string.
79 */ 79 */
80 GaimStringref *gaim_stringref_ref(GaimStringref *stringref); 80 PurpleStringref *purple_stringref_ref(PurpleStringref *stringref);
81 81
82 /** 82 /**
83 * Decrease the reference count of the given stringref. If this 83 * Decrease the reference count of the given stringref. If this
84 * reference count reaches zero, the stringref will be freed; thus 84 * reference count reaches zero, the stringref will be freed; thus
85 * you MUST NOT use this string after dereferencing it. 85 * you MUST NOT use this string after dereferencing it.
86 * 86 *
87 * @param stringref String to be dereferenced. 87 * @param stringref String to be dereferenced.
88 */ 88 */
89 void gaim_stringref_unref(GaimStringref *stringref); 89 void purple_stringref_unref(PurpleStringref *stringref);
90 90
91 /** 91 /**
92 * Retrieve the value of a stringref. 92 * Retrieve the value of a stringref.
93 * 93 *
94 * @note This value should not be cached or stored in a local variable. 94 * @note This value should not be cached or stored in a local variable.
102 * 102 *
103 * @param stringref String reference from which to retrieve the value. 103 * @param stringref String reference from which to retrieve the value.
104 * 104 *
105 * @return The contents of the string reference. 105 * @return The contents of the string reference.
106 */ 106 */
107 const char *gaim_stringref_value(const GaimStringref *stringref); 107 const char *purple_stringref_value(const PurpleStringref *stringref);
108 108
109 /** 109 /**
110 * Compare two stringrefs for string equality. This returns the same 110 * Compare two stringrefs for string equality. This returns the same
111 * value as strcmp would, where <0 indicates that s1 is "less than" s2 111 * value as strcmp would, where <0 indicates that s1 is "less than" s2
112 * in the ASCII lexicography, 0 indicates equality, etc. 112 * in the ASCII lexicography, 0 indicates equality, etc.
115 * 115 *
116 * @param s2 The string to compare against the reference. 116 * @param s2 The string to compare against the reference.
117 * 117 *
118 * @return An ordering indication on s1 and s2. 118 * @return An ordering indication on s1 and s2.
119 */ 119 */
120 int gaim_stringref_cmp(const GaimStringref *s1, const GaimStringref *s2); 120 int purple_stringref_cmp(const PurpleStringref *s1, const PurpleStringref *s2);
121 121
122 /** 122 /**
123 * Find the length of the string inside a stringref. 123 * Find the length of the string inside a stringref.
124 * 124 *
125 * @param stringref The string in whose length we are interested. 125 * @param stringref The string in whose length we are interested.
126 * 126 *
127 * @return The length of the string in stringref 127 * @return The length of the string in stringref
128 */ 128 */
129 size_t gaim_stringref_len(const GaimStringref *stringref); 129 size_t purple_stringref_len(const PurpleStringref *stringref);
130 130
131 #ifdef __cplusplus 131 #ifdef __cplusplus
132 } 132 }
133 #endif 133 #endif
134 134
135 #endif /* _GAIM_STRINGREF_H_ */ 135 #endif /* _PURPLE_STRINGREF_H_ */

Mercurial Repository: pidgin3

mercurial