eina_stringshare_example_01_page

Like all examples we start by including Eina:

#include <stdio.h>

Here we declare some variables and initialize eina:

#include <Eina.h>
int
main(int argc EINA_UNUSED, char **argv EINA_UNUSED)
{
const char *str, *str2;
const char *prologe = "The Cylons were created by man. They rebelled. They "
"evolved.";
const char *prologe2 = "%d Cylon models. %d are known. %d live in secret. "
"%d will be revealed.";
const char *prologe3 = "There are many copies. And they have a plan.";
eina_init();
Eina.h
Eina Utility library.
eina_init
EINA_API int eina_init(void)
Initializes the Eina library.
Definition eina_main.c:291
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition eina_types.h:339

We start the substantive part of the example by showing how to make a part of a string shared and how to get the length of a shared string:

str = eina_stringshare_add_length(prologe, 31);
printf("%s\n", str);
printf("length: %d\n", eina_stringshare_strlen(str));
eina_stringshare_add_length
EINA_API Eina_Stringshare * eina_stringshare_add_length(const char *str, unsigned int slen)
Retrieves an instance of a string with a specific size for use in a program.
Definition eina_stringshare.c:573
eina_stringshare_strlen
EINA_API int eina_stringshare_strlen(Eina_Stringshare *str)
Notes that the given string must be shared.
Definition eina_stringshare.c:726

As we add shared strings we also need to delete them when done using them:

eina_stringshare_del(str);
eina_stringshare_del
EINA_API void eina_stringshare_del(Eina_Stringshare *str)
Notes that the given string has lost an instance.
Definition eina_stringshare.c:533

There are many ways of creating shared strings including an equivalent to sprintf:

str = eina_stringshare_printf(prologe2, 12, 7, 4, 1);
printf("%s\n", str);
eina_stringshare_del(str);

An equivalent to snprintf:

str = eina_stringshare_nprintf(45, "%s", prologe3);

But the simplest way of creating a shared string is through eina_stringshare_add():

printf("%s\n", str);

Sometimes you already have a pointer to a shared string and want to use it, so to make sure the provider of the pointer won't free it while you're using it you can increase the shared string's ref count:

str2 = eina_stringshare_add(prologe3);
printf("%s\n", str2);
eina_stringshare_add
EINA_API Eina_Stringshare * eina_stringshare_add(const char *str)
Retrieves an instance of a string for use in a program.
Definition eina_stringshare.c:606

Whenever you have a pointer to a shared string and would like to change it's value you should use eina_stringshare_replace():

eina_stringshare_ref(str2);
eina_stringshare_del(str2);
printf("%s\n", str2);
eina_stringshare_ref
EINA_API Eina_Stringshare * eina_stringshare_ref(Eina_Stringshare *str)
Increment references of the given shared string.
Definition eina_stringshare.c:685

Warning
  Don't use eina_stringshare_del() followed by eina_share_common_add(), under some circumstances you might end up deleting a shared string some other piece of code is using.

We created str but haven't deleted it yet, and while we called eina_stringshare_del() on str2, we created it and then increased the ref count so it's still alive:

eina_stringshare_replace(&str, prologe);
printf("%s\n", str);
eina_stringshare_del(str);
eina_stringshare_del(str2);
eina_stringshare_replace
static Eina_Bool eina_stringshare_replace(Eina_Stringshare **p_str, const char *news)
Replace the previously stringshared pointer with new content.
Definition eina_inline_stringshare.x:78

You can see the full source code here.