libpurple/stringref.h

   1 /* TODO: Can we just replace this whole thing with a GCache */
   2
   3 /* purple
   4  *
   5  * Purple is the legal property of its developers, whose names are too numerous
   6  * to list here.  Please refer to the COPYRIGHT file distributed with this
   7  * source distribution.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  22  *
  23  */
  24
  25 #ifndef _PURPLE_STRINGREF_H_
  26 #define _PURPLE_STRINGREF_H_
  27 /**
  28  * SECTION:stringref
  29  * @section_id: libpurple-stringref
  30  * @short_description: <filename>stringref.h</filename>
  31  * @title: Reference-counted Immutable Strings
  32  */
  33
  34 typedef struct _PurpleStringref PurpleStringref;
  35
  36 G_BEGIN_DECLS
  37
  38 /**
  39  * purple_stringref_new:
  40  * @value: This will be the value of the string; it will be
  41  *              duplicated.
  42  *
  43  * Creates an immutable reference-counted string object.  The newly
  44  * created object will have a reference count of 1.
  45  *
  46  * Returns: A newly allocated string reference object with a refcount
  47  *         of 1.
  48  */
  49 PurpleStringref *purple_stringref_new(const char *value);
  50
  51 /**
  52  * purple_stringref_new_noref:
  53  * @value: This will be the value of the string; it will be
  54  *              duplicated.
  55  *
  56  * Creates an immutable reference-counted string object.  The newly
  57  * created object will have a reference count of zero, and if it is
  58  * not referenced before the next iteration of the mainloop it will
  59  * be freed at that time.
  60  *
  61  * Returns: A newly allocated string reference object with a refcount
  62  *         of zero.
  63  */
  64 PurpleStringref *purple_stringref_new_noref(const char *value);
  65
  66 /**
  67  * purple_stringref_printf:
  68  * @format: A printf-style format specification.
  69  * @...: The arguments for the format specification.
  70  *
  71  * Creates an immutable reference-counted string object from a printf
  72  * format specification and arguments.  The created object will have a
  73  * reference count of 1.
  74  *
  75  * Returns: A newly allocated string reference object with a refcount
  76  *         of 1.
  77  */
  78 PurpleStringref *purple_stringref_printf(const char *format, ...);
  79
  80 /**
  81  * purple_stringref_ref:
  82  * @stringref: String to be referenced.
  83  *
  84  * Increase the reference count of the given stringref.
  85  *
  86  * Returns: A pointer to the referenced string.
  87  */
  88 PurpleStringref *purple_stringref_ref(PurpleStringref *stringref);
  89
  90 /**
  91  * purple_stringref_unref:
  92  * @stringref: String to be dereferenced.
  93  *
  94  * Decrease the reference count of the given stringref.  If this
  95  * reference count reaches zero, the stringref will be freed; thus
  96  * you MUST NOT use this string after dereferencing it.
  97  */
  98 void purple_stringref_unref(PurpleStringref *stringref);
  99
 100 /**
 101  * purple_stringref_value:
 102  * @stringref: String reference from which to retrieve the value.
 103  *
 104  * Retrieve the value of a stringref.
 105  *
 106  * Note: This value should not be cached or stored in a local variable.
 107  *       While there is nothing inherently incorrect about doing so, it
 108  *       is easy to forget that the cached value is in fact a
 109  *       reference-counted object and accidentally use it after
 110  *       dereferencing.  This is more problematic for a reference-
 111  *       counted object than a heap-allocated object, as it may seem to
 112  *       be valid or invalid nondeterministically based on how many
 113  *       other references to it exist.
 114  *
 115  * Returns: The contents of the string reference.
 116  */
 117 const char *purple_stringref_value(const PurpleStringref *stringref);
 118
 119 /**
 120  * purple_stringref_cmp:
 121  * @s1: The reference string.
 122  * @s2: The string to compare against the reference.
 123  *
 124  * Compare two stringrefs for string equality.  This returns the same
 125  * value as strcmp would, where <0 indicates that s1 is "less than" s2
 126  * in the ASCII lexicography, 0 indicates equality, etc.
 127  *
 128  * Returns: An ordering indication on s1 and s2.
 129  */
 130 int purple_stringref_cmp(const PurpleStringref *s1, const PurpleStringref *s2);
 131
 132 /**
 133  * purple_stringref_len:
 134  * @stringref: The string in whose length we are interested.
 135  *
 136  * Find the length of the string inside a stringref.
 137  *
 138  * Returns: The length of the string in stringref
 139  */
 140 size_t purple_stringref_len(const PurpleStringref *stringref);
 141
 142 G_END_DECLS
 143
 144 #endif /* _PURPLE_STRINGREF_H_ */