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, char **argv)
{
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 Utility library.
int eina_init(void)
Initialize the Eina library.
Definition eina_main.c:244

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 * eina_stringshare_add_length(const char *str, unsigned int slen)
Retrieve an instance of a string for use in a program.
Definition eina_stringshare.c:612
int eina_stringshare_strlen(Eina_Stringshare *str)
Note that the given string must be shared.
Definition eina_stringshare.c:767

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

void eina_stringshare_del(Eina_Stringshare *str)
Note that the given string has lost an instance.
Definition eina_stringshare.c:577

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 * eina_stringshare_printf(const char *fmt,...) EINA_PRINTF(1
Retrieve an instance of a string for use in a program from a format string.

An equivalent to snprintf:

str = eina_stringshare_nprintf(45, "%s", prologe3);
Eina_Stringshare * eina_stringshare_nprintf(unsigned int len, const char *fmt,...) EINA_PRINTF(2
Retrieve an instance of a string for use in a program from a format string with size limitation.

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 * eina_stringshare_add(const char *str)
Retrieve an instance of a string for use in a program.
Definition eina_stringshare.c:635

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

printf("%s\n", str2);
Eina_Stringshare Eina_Stringshare * eina_stringshare_ref(Eina_Stringshare *str)
Increment references of the given shared string.
Definition eina_stringshare.c:726
Warning
Don't use eina_stringshare_del() followed by eina_share_common_add(), under some circunstances 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);

You can see the full source code here.