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