pidgin 2.14.14dev
stringref.h File Reference

Reference-counted immutable strings. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct _PurpleStringref PurpleStringref
 

Functions

PurpleStringref * purple_stringref_new (const char *value)
 Creates an immutable reference-counted string object. More...
 
PurpleStringref * purple_stringref_new_noref (const char *value)
 Creates an immutable reference-counted string object. More...
 
PurpleStringref * purple_stringref_printf (const char *format,...)
 Creates an immutable reference-counted string object from a printf format specification and arguments. More...
 
PurpleStringref * purple_stringref_ref (PurpleStringref *stringref)
 Increase the reference count of the given stringref. More...
 
void purple_stringref_unref (PurpleStringref *stringref)
 Decrease the reference count of the given stringref. More...
 
const char * purple_stringref_value (const PurpleStringref *stringref)
 Retrieve the value of a stringref. More...
 
int purple_stringref_cmp (const PurpleStringref *s1, const PurpleStringref *s2)
 Compare two stringrefs for string equality. More...
 
size_t purple_stringref_len (const PurpleStringref *stringref)
 Find the length of the string inside a stringref. More...
 

Detailed Description

Reference-counted immutable strings.

Definition in file stringref.h.

Typedef Documentation

◆ PurpleStringref

typedef struct _PurpleStringref PurpleStringref

Definition at line 36 of file stringref.h.

Function Documentation

◆ purple_stringref_cmp()

int purple_stringref_cmp ( const PurpleStringref *  s1,
const PurpleStringref *  s2 
)

Compare two stringrefs for string equality.

This returns the same value as strcmp would, where <0 indicates that s1 is "less than" s2 in the ASCII lexicography, 0 indicates equality, etc.

Parameters
s1The reference string.
s2The string to compare against the reference.
Returns
An ordering indication on s1 and s2.

◆ purple_stringref_len()

size_t purple_stringref_len ( const PurpleStringref *  stringref)

Find the length of the string inside a stringref.

Parameters
stringrefThe string in whose length we are interested.
Returns
The length of the string in stringref

◆ purple_stringref_new()

PurpleStringref * purple_stringref_new ( const char *  value)

Creates an immutable reference-counted string object.

The newly created object will have a reference count of 1.

Parameters
valueThis will be the value of the string; it will be duplicated.
Returns
A newly allocated string reference object with a refcount of 1.

◆ purple_stringref_new_noref()

PurpleStringref * purple_stringref_new_noref ( const char *  value)

Creates an immutable reference-counted string object.

The newly created object will have a reference count of zero, and if it is not referenced before the next iteration of the mainloop it will be freed at that time.

Parameters
valueThis will be the value of the string; it will be duplicated.
Returns
A newly allocated string reference object with a refcount of zero.

◆ purple_stringref_printf()

PurpleStringref * purple_stringref_printf ( const char *  format,
  ... 
)

Creates an immutable reference-counted string object from a printf format specification and arguments.

The created object will have a reference count of 1.

Parameters
formatA printf-style format specification.
Returns
A newly allocated string reference object with a refcount of 1.

◆ purple_stringref_ref()

PurpleStringref * purple_stringref_ref ( PurpleStringref *  stringref)

Increase the reference count of the given stringref.

Parameters
stringrefString to be referenced.
Returns
A pointer to the referenced string.

◆ purple_stringref_unref()

void purple_stringref_unref ( PurpleStringref *  stringref)

Decrease the reference count of the given stringref.

If this reference count reaches zero, the stringref will be freed; thus you MUST NOT use this string after dereferencing it.

Parameters
stringrefString to be dereferenced.

◆ purple_stringref_value()

const char * purple_stringref_value ( const PurpleStringref *  stringref)

Retrieve the value of a stringref.

Note
This value should not be cached or stored in a local variable. While there is nothing inherently incorrect about doing so, it is easy to forget that the cached value is in fact a reference-counted object and accidentally use it after dereferencing. This is more problematic for a reference- counted object than a heap-allocated object, as it may seem to be valid or invalid nondeterministically based on how many other references to it exist.
Parameters
stringrefString reference from which to retrieve the value.
Returns
The contents of the string reference.