\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'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 ('\textbackslash{}0') 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'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. 