\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 \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$ \hyperlink{group__Eina__UStringshare__Group_ga697804d63e3c57a69b305bb22a808d74}{eina\+\_\+ustringshare\+\_\+add\+\_\+length} (const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$str, unsigned int slen)
\begin{DoxyCompactList}\small\item\em Retrieve an instance of a string for use in a program. \end{DoxyCompactList}\item 
const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$ \hyperlink{group__Eina__UStringshare__Group_ga673940abd2256986b97a4fba0f11ef2d}{eina\+\_\+ustringshare\+\_\+add} (const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$str)
\begin{DoxyCompactList}\small\item\em Retrieve an instance of a string for use in a program. \end{DoxyCompactList}\item 
const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$ \hyperlink{group__Eina__UStringshare__Group_ga54a37b27109bb814712ae827d8360f1a}{eina\+\_\+ustringshare\+\_\+ref} (const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$str)
\begin{DoxyCompactList}\small\item\em Increment references of the given shared string. \end{DoxyCompactList}\item 
void \hyperlink{group__Eina__UStringshare__Group_ga0b5dcf75a420e01836b7ce5231282e30}{eina\+\_\+ustringshare\+\_\+del} (const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$str)
\begin{DoxyCompactList}\small\item\em Note that the given string has lost an instance. \end{DoxyCompactList}\item 
int \hyperlink{group__Eina__UStringshare__Group_gafd7d67f9becf670fd2014e3db66d2bf3}{eina\+\_\+ustringshare\+\_\+strlen} (const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$str)
\begin{DoxyCompactList}\small\item\em Note that the given string {\bfseries must} be shared. \end{DoxyCompactList}\item 
void \hyperlink{group__Eina__UStringshare__Group_ga8217d6c9ec05be1ef4d6c36695804c1e}{eina\+\_\+ustringshare\+\_\+dump} (void)
\begin{DoxyCompactList}\small\item\em Dump the contents of the share\+\_\+common. \end{DoxyCompactList}\item 
\hypertarget{group__Eina__UStringshare__Group_gacfea21a44781e0775b7e2eabb613e2db}{}static \hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\+\_\+\+Bool} {\bfseries eina\+\_\+ustringshare\+\_\+replace} (const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$$\ast$p\+\_\+str, const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$news)\label{group__Eina__UStringshare__Group_gacfea21a44781e0775b7e2eabb613e2db}

\item 
\hypertarget{group__Eina__UStringshare__Group_gad0941766d69e2596f28c7a400518c85a}{}static \hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\+\_\+\+Bool} {\bfseries eina\+\_\+ustringshare\+\_\+replace\+\_\+length} (const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$$\ast$p\+\_\+str, const \hyperlink{group__Eina__Unicode__String_ga00d6dbe6710822ef81e9539fc57c4b12}{Eina\+\_\+\+Unicode} $\ast$news, unsigned int slen)\label{group__Eina__UStringshare__Group_gad0941766d69e2596f28c7a400518c85a}

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

\subsection{Function Documentation}
\hypertarget{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[{eina\+\_\+ustringshare\+\_\+add\+\_\+length}]{\setlength{\rightskip}{0pt plus 5cm}const {\bf Eina\+\_\+\+Unicode}$\ast$ eina\+\_\+ustringshare\+\_\+add\+\_\+length (
\begin{DoxyParamCaption}
\item[{const {\bf Eina\+\_\+\+Unicode} $\ast$}]{str, }
\item[{unsigned int}]{slen}
\end{DoxyParamCaption}
)}\label{group__Eina__UStringshare__Group_ga697804d63e3c57a69b305bb22a808d74}


Retrieve 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\+L\+L} on failure.
\end{DoxyReturn}
This function retrieves an instance of {\ttfamily str}. If {\ttfamily str} is {\ttfamily N\+U\+L\+L}, then {\ttfamily N\+U\+L\+L} 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}
\hyperlink{group__Eina__UStringshare__Group_ga673940abd2256986b97a4fba0f11ef2d}{eina\+\_\+ustringshare\+\_\+add()} 
\end{DoxySeeAlso}


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

\hypertarget{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[{eina\+\_\+ustringshare\+\_\+add}]{\setlength{\rightskip}{0pt plus 5cm}const {\bf Eina\+\_\+\+Unicode}$\ast$ eina\+\_\+ustringshare\+\_\+add (
\begin{DoxyParamCaption}
\item[{const {\bf Eina\+\_\+\+Unicode} $\ast$}]{str}
\end{DoxyParamCaption}
)}\label{group__Eina__UStringshare__Group_ga673940abd2256986b97a4fba0f11ef2d}


Retrieve 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\+L\+L} on failure.
\end{DoxyReturn}
This function retrieves an instance of {\ttfamily str}. If {\ttfamily str} is {\ttfamily N\+U\+L\+L}, then {\ttfamily N\+U\+L\+L} 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 \hyperlink{group__Eina__Stringshare__Group_ga7102630f25d779cd216e48f1369f65b1}{eina\+\_\+stringshare\+\_\+add\+\_\+length()} instead.

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


References eina\+\_\+ustringshare\+\_\+add\+\_\+length().

\hypertarget{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[{eina\+\_\+ustringshare\+\_\+ref}]{\setlength{\rightskip}{0pt plus 5cm}const {\bf Eina\+\_\+\+Unicode}$\ast$ eina\+\_\+ustringshare\+\_\+ref (
\begin{DoxyParamCaption}
\item[{const {\bf Eina\+\_\+\+Unicode} $\ast$}]{str}
\end{DoxyParamCaption}
)}\label{group__Eina__UStringshare__Group_ga54a37b27109bb814712ae827d8360f1a}


Increment 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\+L\+L} 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 \hyperlink{group__Eina__UStringshare__Group_ga673940abd2256986b97a4fba0f11ef2d}{eina\+\_\+ustringshare\+\_\+add()}.

There is no unref since this is the work of \hyperlink{group__Eina__UStringshare__Group_ga0b5dcf75a420e01836b7ce5231282e30}{eina\+\_\+ustringshare\+\_\+del()}. \hypertarget{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[{eina\+\_\+ustringshare\+\_\+del}]{\setlength{\rightskip}{0pt plus 5cm}void eina\+\_\+ustringshare\+\_\+del (
\begin{DoxyParamCaption}
\item[{const {\bf Eina\+\_\+\+Unicode} $\ast$}]{str}
\end{DoxyParamCaption}
)}\label{group__Eina__UStringshare__Group_ga0b5dcf75a420e01836b7ce5231282e30}


Note 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\+L\+L}, the function returns immediately.

\begin{DoxyNote}{Note}
If the given pointer is not shared, bad things will happen, likely a segmentation fault. 
\end{DoxyNote}
\hypertarget{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[{eina\+\_\+ustringshare\+\_\+strlen}]{\setlength{\rightskip}{0pt plus 5cm}int eina\+\_\+ustringshare\+\_\+strlen (
\begin{DoxyParamCaption}
\item[{const {\bf Eina\+\_\+\+Unicode} $\ast$}]{str}
\end{DoxyParamCaption}
)}\label{group__Eina__UStringshare__Group_gafd7d67f9becf670fd2014e3db66d2bf3}


Note 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\+L\+L}, in that case {\ttfamily -\/1} is returned.\\
\hline
\end{DoxyParams}
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}
\hypertarget{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[{eina\+\_\+ustringshare\+\_\+dump}]{\setlength{\rightskip}{0pt plus 5cm}void eina\+\_\+ustringshare\+\_\+dump (
\begin{DoxyParamCaption}
\item[{void}]{}
\end{DoxyParamCaption}
)}\label{group__Eina__UStringshare__Group_ga8217d6c9ec05be1ef4d6c36695804c1e}


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

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