\hypertarget{group__Eina__UStringshare__Group}{}\doxysection{Unicode Stringshare}
\label{group__Eina__UStringshare__Group}\index{Unicode Stringshare@{Unicode Stringshare}}


These functions allow you to store one copy of a string, and use it throughout your program.  


\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
static \mbox{\hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\+\_\+\+Bool}} \mbox{\hyperlink{group__Eina__UStringshare__Group_gacfea21a44781e0775b7e2eabb613e2db}{eina\+\_\+ustringshare\+\_\+replace}} (const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$$\ast$p\+\_\+str, const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$news)
\begin{DoxyCompactList}\small\item\em Replace the previously stringshared pointer with new content. \end{DoxyCompactList}\item 
static \mbox{\hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\+\_\+\+Bool}} \mbox{\hyperlink{group__Eina__UStringshare__Group_gad0941766d69e2596f28c7a400518c85a}{eina\+\_\+ustringshare\+\_\+replace\+\_\+length}} (const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$$\ast$p\+\_\+str, const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$news, unsigned int slen)
\begin{DoxyCompactList}\small\item\em Replace the previously stringshared pointer with a new content. \end{DoxyCompactList}\item 
const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$ \mbox{\hyperlink{group__Eina__UStringshare__Group_ga697804d63e3c57a69b305bb22a808d74}{eina\+\_\+ustringshare\+\_\+add\+\_\+length}} (const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$str, unsigned int slen)
\begin{DoxyCompactList}\small\item\em Retrieves an instance of a string for use in a program. \end{DoxyCompactList}\item 
const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$ \mbox{\hyperlink{group__Eina__UStringshare__Group_ga673940abd2256986b97a4fba0f11ef2d}{eina\+\_\+ustringshare\+\_\+add}} (const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$str)
\begin{DoxyCompactList}\small\item\em Retrieves an instance of a string for use in a program. \end{DoxyCompactList}\item 
const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$ \mbox{\hyperlink{group__Eina__UStringshare__Group_ga54a37b27109bb814712ae827d8360f1a}{eina\+\_\+ustringshare\+\_\+ref}} (const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$str)
\begin{DoxyCompactList}\small\item\em Increments references of the given shared string. \end{DoxyCompactList}\item 
void \mbox{\hyperlink{group__Eina__UStringshare__Group_ga0b5dcf75a420e01836b7ce5231282e30}{eina\+\_\+ustringshare\+\_\+del}} (const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$str)
\begin{DoxyCompactList}\small\item\em Notes that the given string has lost an instance. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__Eina__UStringshare__Group_gafd7d67f9becf670fd2014e3db66d2bf3}{eina\+\_\+ustringshare\+\_\+strlen}} (const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$str)
\begin{DoxyCompactList}\small\item\em Notes that the given string {\bfseries{must}} be shared. \end{DoxyCompactList}\item 
void \mbox{\hyperlink{group__Eina__UStringshare__Group_ga8217d6c9ec05be1ef4d6c36695804c1e}{eina\+\_\+ustringshare\+\_\+dump}} (void)
\begin{DoxyCompactList}\small\item\em Dumps the contents of the share\+\_\+common. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
These functions allow you to store one copy of a string, and use it throughout your program. 

This is a method to reduce the number of duplicated strings kept in memory. It\textquotesingle{}s pretty common for the same strings to be dynamically allocated repeatedly between applications and libraries, especially in circumstances where you could have multiple copies of a structure that allocates the string. So rather than duplicating and freeing these strings, you request a read-\/only pointer to an existing string and only incur the overhead of a hash lookup.

It sounds like micro-\/optimizing, but profiling has shown this can have a significant impact as you scale the number of copies up. It improves string creation/destruction speed, reduces memory use and decreases memory fragmentation, so a win all-\/around.

For more information, you can look at the \mbox{\hyperlink{tutorial_ustringshare_page}{UStringshare Tutorial}}. 

\doxysubsection{Function Documentation}
\mbox{\Hypertarget{group__Eina__UStringshare__Group_gacfea21a44781e0775b7e2eabb613e2db}\label{group__Eina__UStringshare__Group_gacfea21a44781e0775b7e2eabb613e2db}} 
\index{Unicode Stringshare@{Unicode Stringshare}!eina\_ustringshare\_replace@{eina\_ustringshare\_replace}}
\index{eina\_ustringshare\_replace@{eina\_ustringshare\_replace}!Unicode Stringshare@{Unicode Stringshare}}
\doxysubsubsection{\texorpdfstring{eina\_ustringshare\_replace()}{eina\_ustringshare\_replace()}}
{\footnotesize\ttfamily static \mbox{\hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\+\_\+\+Bool}} eina\+\_\+ustringshare\+\_\+replace (\begin{DoxyParamCaption}\item[{const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$$\ast$}]{p\+\_\+str,  }\item[{const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$}]{news }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}



Replace the previously stringshared pointer with new content. 

The string pointed by {\itshape p\+\_\+str} should be previously stringshared or {\ttfamily NULL} and it will be \mbox{\hyperlink{group__Eina__UStringshare__Group_ga0b5dcf75a420e01836b7ce5231282e30}{eina\+\_\+ustringshare\+\_\+del()}}. The new string will be passed to \mbox{\hyperlink{group__Eina__UStringshare__Group_ga673940abd2256986b97a4fba0f11ef2d}{eina\+\_\+ustringshare\+\_\+add()}} and then assigned to {\ttfamily $\ast$p\+\_\+str}.


\begin{DoxyParams}{Parameters}
{\em p\+\_\+str} & pointer to the stringhare to be replaced. Must not be {\ttfamily NULL}, but {\ttfamily $\ast$p\+\_\+str} may be {\ttfamily NULL} as it is a valid stringshare handle. \\
\hline
{\em news} & new string to be stringshared, may be {\ttfamily NULL}.\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
\mbox{\hyperlink{group__Eina__Types__Group_ga05c12dacc8b4058994df842b41be85fc}{EINA\+\_\+\+TRUE}} if the strings were different and thus replaced, \mbox{\hyperlink{group__Eina__Types__Group_ga1feb115f8e9913e806e090d9bd5a7301}{EINA\+\_\+\+FALSE}} if the strings were the same after shared. 
\end{DoxyReturn}


References EINA\+\_\+\+FALSE, EINA\+\_\+\+TRUE, eina\+\_\+ustringshare\+\_\+add(), and eina\+\_\+ustringshare\+\_\+del().

\mbox{\Hypertarget{group__Eina__UStringshare__Group_gad0941766d69e2596f28c7a400518c85a}\label{group__Eina__UStringshare__Group_gad0941766d69e2596f28c7a400518c85a}} 
\index{Unicode Stringshare@{Unicode Stringshare}!eina\_ustringshare\_replace\_length@{eina\_ustringshare\_replace\_length}}
\index{eina\_ustringshare\_replace\_length@{eina\_ustringshare\_replace\_length}!Unicode Stringshare@{Unicode Stringshare}}
\doxysubsubsection{\texorpdfstring{eina\_ustringshare\_replace\_length()}{eina\_ustringshare\_replace\_length()}}
{\footnotesize\ttfamily static \mbox{\hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\+\_\+\+Bool}} eina\+\_\+ustringshare\+\_\+replace\+\_\+length (\begin{DoxyParamCaption}\item[{const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$$\ast$}]{p\+\_\+str,  }\item[{const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$}]{news,  }\item[{unsigned int}]{slen }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}



Replace the previously stringshared pointer with a new content. 

The string pointed by {\itshape p\+\_\+str} should be previously stringshared or {\ttfamily NULL} and it will be \mbox{\hyperlink{group__Eina__UStringshare__Group_ga0b5dcf75a420e01836b7ce5231282e30}{eina\+\_\+ustringshare\+\_\+del()}}. The new string will be passed to \mbox{\hyperlink{group__Eina__UStringshare__Group_ga697804d63e3c57a69b305bb22a808d74}{eina\+\_\+ustringshare\+\_\+add\+\_\+length()}} and then assigned to {\ttfamily $\ast$p\+\_\+str}.


\begin{DoxyParams}{Parameters}
{\em p\+\_\+str} & pointer to the stringhare to be replaced. Must not be {\ttfamily NULL}, but {\ttfamily $\ast$p\+\_\+str} may be {\ttfamily NULL} as it is a valid stringshare handle. \\
\hline
{\em news} & new string to be stringshared, may be {\ttfamily NULL}. \\
\hline
{\em slen} & The string size ($<$= strlen(str)).\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
\mbox{\hyperlink{group__Eina__Types__Group_ga05c12dacc8b4058994df842b41be85fc}{EINA\+\_\+\+TRUE}} if the strings were different and thus replaced, \mbox{\hyperlink{group__Eina__Types__Group_ga1feb115f8e9913e806e090d9bd5a7301}{EINA\+\_\+\+FALSE}} if the strings were the same after shared. 
\end{DoxyReturn}


References EINA\+\_\+\+FALSE, EINA\+\_\+\+TRUE, eina\+\_\+ustringshare\+\_\+add\+\_\+length(), and eina\+\_\+ustringshare\+\_\+del().

\mbox{\Hypertarget{group__Eina__UStringshare__Group_ga697804d63e3c57a69b305bb22a808d74}\label{group__Eina__UStringshare__Group_ga697804d63e3c57a69b305bb22a808d74}} 
\index{Unicode Stringshare@{Unicode Stringshare}!eina\_ustringshare\_add\_length@{eina\_ustringshare\_add\_length}}
\index{eina\_ustringshare\_add\_length@{eina\_ustringshare\_add\_length}!Unicode Stringshare@{Unicode Stringshare}}
\doxysubsubsection{\texorpdfstring{eina\_ustringshare\_add\_length()}{eina\_ustringshare\_add\_length()}}
{\footnotesize\ttfamily const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}}$\ast$ eina\+\_\+ustringshare\+\_\+add\+\_\+length (\begin{DoxyParamCaption}\item[{const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$}]{str,  }\item[{unsigned int}]{slen }\end{DoxyParamCaption})}



Retrieves an instance of a string for use in a program. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em str} & The string to retrieve an instance of. \\
\hline
\mbox{\texttt{ in}}  & {\em slen} & The string size ($<$= strlen(str)). \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A pointer to an instance of the string on success, {\ttfamily NULL} on failure.
\end{DoxyReturn}
This function retrieves an instance of {\ttfamily str}. If {\ttfamily str} is {\ttfamily NULL}, then {\ttfamily NULL} is returned. If {\ttfamily str} is already stored, it is just returned and its reference counter is increased. Otherwise it is added to the strings to be searched and a duplicated string of {\ttfamily str} is returned.

This function does not check string size, but uses the exact given size. This can be used to share\+\_\+common part of a larger buffer or substring.

\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__Eina__UStringshare__Group_ga673940abd2256986b97a4fba0f11ef2d}{eina\+\_\+ustringshare\+\_\+add()}} 
\end{DoxySeeAlso}


Referenced by eina\+\_\+ustringshare\+\_\+replace\+\_\+length().

\mbox{\Hypertarget{group__Eina__UStringshare__Group_ga673940abd2256986b97a4fba0f11ef2d}\label{group__Eina__UStringshare__Group_ga673940abd2256986b97a4fba0f11ef2d}} 
\index{Unicode Stringshare@{Unicode Stringshare}!eina\_ustringshare\_add@{eina\_ustringshare\_add}}
\index{eina\_ustringshare\_add@{eina\_ustringshare\_add}!Unicode Stringshare@{Unicode Stringshare}}
\doxysubsubsection{\texorpdfstring{eina\_ustringshare\_add()}{eina\_ustringshare\_add()}}
{\footnotesize\ttfamily const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}}$\ast$ eina\+\_\+ustringshare\+\_\+add (\begin{DoxyParamCaption}\item[{const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$}]{str }\end{DoxyParamCaption})}



Retrieves an instance of a string for use in a program. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em str} & The NULL-\/terminated string to retrieve an instance of. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A pointer to an instance of the string on success, {\ttfamily NULL} on failure.
\end{DoxyReturn}
This function retrieves an instance of {\ttfamily str}. If {\ttfamily str} is {\ttfamily NULL}, then {\ttfamily NULL} is returned. If {\ttfamily str} is already stored, it is just returned and its reference counter is increased. Otherwise it is added to the strings to be searched and a duplicated string of {\ttfamily str} is returned.

The string {\ttfamily str} must be NULL-\/terminated (\textquotesingle{}\textbackslash{}0\textquotesingle{}) and its full length will be used. To use part of the string or non-\/null terminated, use \mbox{\hyperlink{group__Eina__Stringshare__Group_gabe8ecf4121011cb792f36ecd8c44e470}{eina\+\_\+stringshare\+\_\+add\+\_\+length()}} instead.

\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__Eina__UStringshare__Group_ga697804d63e3c57a69b305bb22a808d74}{eina\+\_\+ustringshare\+\_\+add\+\_\+length()}} 
\end{DoxySeeAlso}


Referenced by eina\+\_\+ustringshare\+\_\+replace().

\mbox{\Hypertarget{group__Eina__UStringshare__Group_ga54a37b27109bb814712ae827d8360f1a}\label{group__Eina__UStringshare__Group_ga54a37b27109bb814712ae827d8360f1a}} 
\index{Unicode Stringshare@{Unicode Stringshare}!eina\_ustringshare\_ref@{eina\_ustringshare\_ref}}
\index{eina\_ustringshare\_ref@{eina\_ustringshare\_ref}!Unicode Stringshare@{Unicode Stringshare}}
\doxysubsubsection{\texorpdfstring{eina\_ustringshare\_ref()}{eina\_ustringshare\_ref()}}
{\footnotesize\ttfamily const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}}$\ast$ eina\+\_\+ustringshare\+\_\+ref (\begin{DoxyParamCaption}\item[{const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$}]{str }\end{DoxyParamCaption})}



Increments references of the given shared string. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em str} & The shared string. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A pointer to an instance of the string on success, {\ttfamily NULL} on failure.
\end{DoxyReturn}
This is similar to eina\+\_\+share\+\_\+common\+\_\+add(), but it\textquotesingle{}s faster since it will avoid lookups if possible, but on the down side it requires the parameter to be shared before, in other words, it must be the return of a previous \mbox{\hyperlink{group__Eina__UStringshare__Group_ga673940abd2256986b97a4fba0f11ef2d}{eina\+\_\+ustringshare\+\_\+add()}}.

There is no unref since this is the work of \mbox{\hyperlink{group__Eina__UStringshare__Group_ga0b5dcf75a420e01836b7ce5231282e30}{eina\+\_\+ustringshare\+\_\+del()}}. \mbox{\Hypertarget{group__Eina__UStringshare__Group_ga0b5dcf75a420e01836b7ce5231282e30}\label{group__Eina__UStringshare__Group_ga0b5dcf75a420e01836b7ce5231282e30}} 
\index{Unicode Stringshare@{Unicode Stringshare}!eina\_ustringshare\_del@{eina\_ustringshare\_del}}
\index{eina\_ustringshare\_del@{eina\_ustringshare\_del}!Unicode Stringshare@{Unicode Stringshare}}
\doxysubsubsection{\texorpdfstring{eina\_ustringshare\_del()}{eina\_ustringshare\_del()}}
{\footnotesize\ttfamily void eina\+\_\+ustringshare\+\_\+del (\begin{DoxyParamCaption}\item[{const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$}]{str }\end{DoxyParamCaption})}



Notes that the given string has lost an instance. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em str} & String The given string.\\
\hline
\end{DoxyParams}
This function decreases the reference counter associated to {\ttfamily str} if it exists. If that counter reaches 0, the memory associated to {\ttfamily str} is freed. If {\ttfamily str} is {\ttfamily NULL}, the function returns immediately.

\begin{DoxyNote}{Note}
If the given pointer is not shared, bad things will happen, likely a segmentation fault. 
\end{DoxyNote}


Referenced by eina\+\_\+ustringshare\+\_\+replace(), and eina\+\_\+ustringshare\+\_\+replace\+\_\+length().

\mbox{\Hypertarget{group__Eina__UStringshare__Group_gafd7d67f9becf670fd2014e3db66d2bf3}\label{group__Eina__UStringshare__Group_gafd7d67f9becf670fd2014e3db66d2bf3}} 
\index{Unicode Stringshare@{Unicode Stringshare}!eina\_ustringshare\_strlen@{eina\_ustringshare\_strlen}}
\index{eina\_ustringshare\_strlen@{eina\_ustringshare\_strlen}!Unicode Stringshare@{Unicode Stringshare}}
\doxysubsubsection{\texorpdfstring{eina\_ustringshare\_strlen()}{eina\_ustringshare\_strlen()}}
{\footnotesize\ttfamily int eina\+\_\+ustringshare\+\_\+strlen (\begin{DoxyParamCaption}\item[{const \mbox{\hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode}} $\ast$}]{str }\end{DoxyParamCaption})}



Notes that the given string {\bfseries{must}} be shared. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em str} & The shared string to know the length. It is safe to give {\ttfamily NULL}, in that case {\ttfamily -\/1} is returned. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
The length of a shared string.
\end{DoxyReturn}
This function is a cheap way to known the length of a shared string.

\begin{DoxyNote}{Note}
If the given pointer is not shared, bad things will happen, likely a segmentation fault. If in doubt, try strlen(). 
\end{DoxyNote}
\mbox{\Hypertarget{group__Eina__UStringshare__Group_ga8217d6c9ec05be1ef4d6c36695804c1e}\label{group__Eina__UStringshare__Group_ga8217d6c9ec05be1ef4d6c36695804c1e}} 
\index{Unicode Stringshare@{Unicode Stringshare}!eina\_ustringshare\_dump@{eina\_ustringshare\_dump}}
\index{eina\_ustringshare\_dump@{eina\_ustringshare\_dump}!Unicode Stringshare@{Unicode Stringshare}}
\doxysubsubsection{\texorpdfstring{eina\_ustringshare\_dump()}{eina\_ustringshare\_dump()}}
{\footnotesize\ttfamily void eina\+\_\+ustringshare\+\_\+dump (\begin{DoxyParamCaption}\item[{void}]{ }\end{DoxyParamCaption})}



Dumps the contents of the share\+\_\+common. 

This function dumps all strings in the share\+\_\+common to stdout with a DDD\+: prefix per line and a memory usage summary. 