stringref.h File Reference
libpurple

Reference-counted immutable strings. More...

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.

## 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

  s1 | The reference string.
  s2 | The 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

  stringref | The 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

  value | This 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

  value | This 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

  format | A 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

  stringref | String 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

  stringref | String 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

  stringref | String reference from which to retrieve the value.

Returns
  The contents of the string reference.