\hypertarget{group__Eina__UStringshare__Group}{}\section{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.  


\subsection*{Functions}
\begin{DoxyCompactItemize}
\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}\item 
\mbox{\Hypertarget{group__Eina__UStringshare__Group_gacfea21a44781e0775b7e2eabb613e2db}\label{group__Eina__UStringshare__Group_gacfea21a44781e0775b7e2eabb613e2db}} 
static \mbox{\hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\+\_\+\+Bool}} {\bfseries 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)
\item 
\mbox{\Hypertarget{group__Eina__UStringshare__Group_gad0941766d69e2596f28c7a400518c85a}\label{group__Eina__UStringshare__Group_gad0941766d69e2596f28c7a400518c85a}} 
static \mbox{\hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\+\_\+\+Bool}} {\bfseries 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)
\end{DoxyCompactItemize}


\subsection{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}{U\+Stringshare Tutorial}}. 

\subsection{Function Documentation}
\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}}
\subsubsection{\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}{Parameters}
{\em str} & The string to retrieve an instance of. \\
\hline
{\em slen} & The string size ($<$= strlen(str)). \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A pointer to an instance of the string on success, {\ttfamily N\+U\+LL} on failure.
\end{DoxyReturn}
This function retrieves an instance of {\ttfamily str}. If {\ttfamily str} is {\ttfamily N\+U\+LL}, then {\ttfamily N\+U\+LL} 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}
\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}}
\subsubsection{\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}{Parameters}
{\em str} & The N\+U\+L\+L-\/terminated string to retrieve an instance of. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A pointer to an instance of the string on success, {\ttfamily N\+U\+LL} on failure.
\end{DoxyReturn}
This function retrieves an instance of {\ttfamily str}. If {\ttfamily str} is {\ttfamily N\+U\+LL}, then {\ttfamily N\+U\+LL} 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 N\+U\+L\+L-\/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}
\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}}
\subsubsection{\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}{Parameters}
{\em str} & The shared string. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A pointer to an instance of the string on success, {\ttfamily N\+U\+LL} 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}}
\subsubsection{\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}{Parameters}
{\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 N\+U\+LL}, the function returns immediately.

\begin{DoxyNote}{Note}
If the given pointer is not shared, bad things will happen, likely a segmentation fault. 
\end{DoxyNote}
\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}}
\subsubsection{\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}{Parameters}
{\em str} & The shared string to know the length. It is safe to give {\ttfamily N\+U\+LL}, 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}}
\subsubsection{\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 D\+DD\+: prefix per line and a memory usage summary. 