Mercurial > pidgin3 / file comparison

comparison: libpurple/stringref.h

libpurple/stringref.h

branch
gtkdoc-conversion
changeset 35403
9282701d7aa9
parent 35393
00f876b129bc
child 35442
84e906df98dd
child 37045
aadac46d3bb3
equal deleted inserted replaced
35402:6eae3b385153 35403:9282701d7aa9
32 typedef struct _PurpleStringref PurpleStringref; 32 typedef struct _PurpleStringref PurpleStringref;
33 33
34 G_BEGIN_DECLS 34 G_BEGIN_DECLS
35 35
36 /** 36 /**
37 * purple_stringref_new:
38 * @value: This will be the value of the string; it will be
39 * duplicated.
40 *
37 * Creates an immutable reference-counted string object. The newly 41 * Creates an immutable reference-counted string object. The newly
38 * created object will have a reference count of 1. 42 * created object will have a reference count of 1.
39 *
40 * @value: This will be the value of the string; it will be
41 * duplicated.
42 * 43 *
43 * Returns: A newly allocated string reference object with a refcount 44 * Returns: A newly allocated string reference object with a refcount
44 * of 1. 45 * of 1.
45 */ 46 */
46 PurpleStringref *purple_stringref_new(const char *value); 47 PurpleStringref *purple_stringref_new(const char *value);
47 48
48 /** 49 /**
50 * purple_stringref_new_noref:
51 * @value: This will be the value of the string; it will be
52 * duplicated.
53 *
49 * Creates an immutable reference-counted string object. The newly 54 * Creates an immutable reference-counted string object. The newly
50 * created object will have a reference count of zero, and if it is 55 * created object will have a reference count of zero, and if it is
51 * not referenced before the next iteration of the mainloop it will 56 * not referenced before the next iteration of the mainloop it will
52 * be freed at that time. 57 * be freed at that time.
53 *
54 * @value: This will be the value of the string; it will be
55 * duplicated.
56 * 58 *
57 * Returns: A newly allocated string reference object with a refcount 59 * Returns: A newly allocated string reference object with a refcount
58 * of zero. 60 * of zero.
59 */ 61 */
60 PurpleStringref *purple_stringref_new_noref(const char *value); 62 PurpleStringref *purple_stringref_new_noref(const char *value);
61 63
62 /** 64 /**
65 * purple_stringref_printf:
66 * @format: A printf-style format specification.
67 *
63 * Creates an immutable reference-counted string object from a printf 68 * Creates an immutable reference-counted string object from a printf
64 * format specification and arguments. The created object will have a 69 * format specification and arguments. The created object will have a
65 * reference count of 1. 70 * reference count of 1.
66 *
67 * @format: A printf-style format specification.
68 * 71 *
69 * Returns: A newly allocated string reference object with a refcount 72 * Returns: A newly allocated string reference object with a refcount
70 * of 1. 73 * of 1.
71 */ 74 */
72 PurpleStringref *purple_stringref_printf(const char *format, ...); 75 PurpleStringref *purple_stringref_printf(const char *format, ...);
73 76
74 /** 77 /**
78 * purple_stringref_ref:
79 * @stringref: String to be referenced.
80 *
75 * Increase the reference count of the given stringref. 81 * Increase the reference count of the given stringref.
76 *
77 * @stringref: String to be referenced.
78 * 82 *
79 * Returns: A pointer to the referenced string. 83 * Returns: A pointer to the referenced string.
80 */ 84 */
81 PurpleStringref *purple_stringref_ref(PurpleStringref *stringref); 85 PurpleStringref *purple_stringref_ref(PurpleStringref *stringref);
82 86
83 /** 87 /**
88 * purple_stringref_unref:
89 * @stringref: String to be dereferenced.
90 *
84 * Decrease the reference count of the given stringref. If this 91 * Decrease the reference count of the given stringref. If this
85 * reference count reaches zero, the stringref will be freed; thus 92 * reference count reaches zero, the stringref will be freed; thus
86 * you MUST NOT use this string after dereferencing it. 93 * you MUST NOT use this string after dereferencing it.
87 *
88 * @stringref: String to be dereferenced.
89 */ 94 */
90 void purple_stringref_unref(PurpleStringref *stringref); 95 void purple_stringref_unref(PurpleStringref *stringref);
91 96
92 /** 97 /**
98 * purple_stringref_value:
99 * @stringref: String reference from which to retrieve the value.
100 *
93 * Retrieve the value of a stringref. 101 * Retrieve the value of a stringref.
94 * 102 *
95 * Note: This value should not be cached or stored in a local variable. 103 * Note: This value should not be cached or stored in a local variable.
96 * While there is nothing inherently incorrect about doing so, it 104 * While there is nothing inherently incorrect about doing so, it
97 * is easy to forget that the cached value is in fact a 105 * is easy to forget that the cached value is in fact a
99 * dereferencing. This is more problematic for a reference- 107 * dereferencing. This is more problematic for a reference-
100 * counted object than a heap-allocated object, as it may seem to 108 * counted object than a heap-allocated object, as it may seem to
101 * be valid or invalid nondeterministically based on how many 109 * be valid or invalid nondeterministically based on how many
102 * other references to it exist. 110 * other references to it exist.
103 * 111 *
104 * @stringref: String reference from which to retrieve the value.
105 *
106 * Returns: The contents of the string reference. 112 * Returns: The contents of the string reference.
107 */ 113 */
108 const char *purple_stringref_value(const PurpleStringref *stringref); 114 const char *purple_stringref_value(const PurpleStringref *stringref);
109 115
110 /** 116 /**
117 * purple_stringref_cmp:
118 * @s1: The reference string.
119 * @s2: The string to compare against the reference.
120 *
111 * Compare two stringrefs for string equality. This returns the same 121 * Compare two stringrefs for string equality. This returns the same
112 * value as strcmp would, where <0 indicates that s1 is "less than" s2 122 * value as strcmp would, where <0 indicates that s1 is "less than" s2
113 * in the ASCII lexicography, 0 indicates equality, etc. 123 * in the ASCII lexicography, 0 indicates equality, etc.
114 *
115 * @s1: The reference string.
116 *
117 * @s2: The string to compare against the reference.
118 * 124 *
119 * Returns: An ordering indication on s1 and s2. 125 * Returns: An ordering indication on s1 and s2.
120 */ 126 */
121 int purple_stringref_cmp(const PurpleStringref *s1, const PurpleStringref *s2); 127 int purple_stringref_cmp(const PurpleStringref *s1, const PurpleStringref *s2);
122 128
123 /** 129 /**
130 * purple_stringref_len:
131 * @stringref: The string in whose length we are interested.
132 *
124 * Find the length of the string inside a stringref. 133 * Find the length of the string inside a stringref.
125 *
126 * @stringref: The string in whose length we are interested.
127 * 134 *
128 * Returns: The length of the string in stringref 135 * Returns: The length of the string in stringref
129 */ 136 */
130 size_t purple_stringref_len(const PurpleStringref *stringref); 137 size_t purple_stringref_len(const PurpleStringref *stringref);
131 138

Mercurial Repository: pidgin3

mercurial