<refentry id="pango-Miscellaneous-Utilities"><refmeta><refentrytitle role="top_of_page">Miscellaneous Utilities</refentrytitle><manvolnum>3</manvolnum><refmiscinfo>PANGO Library</refmiscinfo></refmeta><refnamediv><refname>Miscellaneous Utilities</refname><refpurpose>Various convenience and utility functions</refpurpose><!--[<xref linkend="desc" endterm="desc.title"/>]--></refnamediv><refsynopsisdiv role="synopsis"><title role="synopsis.title">Synopsis</title><synopsis><link linkend="char">char</link>**              <link linkend="pango-split-file-list">pango_split_file_list</link>               (const <link linkend="char">char</link> *str);<link linkend="char">char</link>*               <link linkend="pango-trim-string">pango_trim_string</link>                   (const <link linkend="char">char</link> *str);<link linkend="gint">gint</link>                <link linkend="pango-read-line">pango_read_line</link>                     (<link linkend="FILE:CAPS">FILE</link> *stream,                                                         <link linkend="GString">GString</link> *str);<link linkend="gboolean">gboolean</link>            <link linkend="pango-skip-space">pango_skip_space</link>                    (const <link linkend="char">char</link> **pos);<link linkend="gboolean">gboolean</link>            <link linkend="pango-scan-word">pango_scan_word</link>                     (const <link linkend="char">char</link> **pos,                                                         <link linkend="GString">GString</link> *out);<link linkend="gboolean">gboolean</link>            <link linkend="pango-scan-string">pango_scan_string</link>                   (const <link linkend="char">char</link> **pos,                                                         <link linkend="GString">GString</link> *out);<link linkend="gboolean">gboolean</link>            <link linkend="pango-scan-int">pango_scan_int</link>                      (const <link linkend="char">char</link> **pos,                                                         <link linkend="int">int</link> *out);<link linkend="char">char</link>*               <link linkend="pango-config-key-get">pango_config_key_get</link>                (const <link linkend="char">char</link> *key);<link linkend="void">void</link>                <link linkend="pango-lookup-aliases">pango_lookup_aliases</link>                (const <link linkend="char">char</link> *fontname,                                                         <link linkend="char">char</link> ***families,                                                         <link linkend="int">int</link> *n_families);<link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-enum">pango_parse_enum</link>                    (<link linkend="GType">GType</link> type,                                                         const <link linkend="char">char</link> *str,                                                         <link linkend="int">int</link> *value,                                                         <link linkend="gboolean">gboolean</link> warn,                                                         <link linkend="char">char</link> **possible_values);<link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-style">pango_parse_style</link>                   (const <link linkend="char">char</link> *str,                                                         <link linkend="PangoStyle">PangoStyle</link> *style,                                                         <link linkend="gboolean">gboolean</link> warn);<link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-variant">pango_parse_variant</link>                 (const <link linkend="char">char</link> *str,                                                         <link linkend="PangoVariant">PangoVariant</link> *variant,                                                         <link linkend="gboolean">gboolean</link> warn);<link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-weight">pango_parse_weight</link>                  (const <link linkend="char">char</link> *str,                                                         <link linkend="PangoWeight">PangoWeight</link> *weight,                                                         <link linkend="gboolean">gboolean</link> warn);<link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-stretch">pango_parse_stretch</link>                 (const <link linkend="char">char</link> *str,                                                         <link linkend="PangoStretch">PangoStretch</link> *stretch,                                                         <link linkend="gboolean">gboolean</link> warn);const <link linkend="char">char</link>*         <link linkend="pango-get-sysconf-subdirectory">pango_get_sysconf_subdirectory</link>      (void);const <link linkend="char">char</link>*         <link linkend="pango-get-lib-subdirectory">pango_get_lib_subdirectory</link>          (void);<link linkend="guint8">guint8</link>*             <link linkend="pango-log2vis-get-embedding-levels">pango_log2vis_get_embedding_levels</link>  (const <link linkend="gchar">gchar</link> *text,                                                         <link linkend="int">int</link> length,                                                         <link linkend="PangoDirection">PangoDirection</link> *pbase_dir);<link linkend="PangoLanguage">PangoLanguage</link>*      <link linkend="pango-language-get-default">pango_language_get_default</link>          (void);const <link linkend="char">char</link>*         <link linkend="pango-language-get-sample-string">pango_language_get_sample_string</link>    (<link linkend="PangoLanguage">PangoLanguage</link> *language);<link linkend="gboolean">gboolean</link>            <link linkend="pango-is-zero-width">pango_is_zero_width</link>                 (<link linkend="gunichar">gunichar</link> ch);<link linkend="void">void</link>                <link linkend="pango-quantize-line-geometry">pango_quantize_line_geometry</link>        (<link linkend="int">int</link> *thickness,                                                         <link linkend="int">int</link> *position);</synopsis></refsynopsisdiv><refsect1 role="desc"><title role="desc.title">Description</title><para>The functions and utilities in this section are mostly used from Pangobackends and modules, but may be useful for other purposes too.</para></refsect1><refsect1 role="details"><title role="details.title">Details</title><refsect2><title><anchor id="pango-split-file-list" role="function"/>pango_split_file_list ()</title><indexterm><primary>pango_split_file_list</primary></indexterm><programlisting><link linkend="char">char</link>**              pango_split_file_list               (const <link linkend="char">char</link> *str);</programlisting><para>Splits a <link linkend="G-SEARCHPATH-SEPARATOR:CAPS"><literal>G_SEARCHPATH_SEPARATOR</literal></link>-separated list of files, strippingwhite space and substituting ~/ with $HOME/.</para><para></para><variablelist role="params"><varlistentry><term><parameter>str</parameter>&nbsp;:</term><listitem><simpara> a <link linkend="G-SEARCHPATH-SEPARATOR:CAPS"><literal>G_SEARCHPATH_SEPARATOR</literal></link> separated list of filenames</simpara></listitem></varlistentry><varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a list of strings to be freed with <link linkend="g-strfreev"><function>g_strfreev()</function></link></simpara></listitem></varlistentry></variablelist></refsect2><refsect2><title><anchor id="pango-trim-string" role="function"/>pango_trim_string ()</title><indexterm><primary>pango_trim_string</primary></indexterm><programlisting><link linkend="char">char</link>*               pango_trim_string                   (const <link linkend="char">char</link> *str);</programlisting><para>Trims leading and trailing whitespace from a string.</para><para></para><variablelist role="params"><varlistentry><term><parameter>str</parameter>&nbsp;:</term><listitem><simpara> a string</simpara></listitem></varlistentry><varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A newly-allocated string that must be freed with <link linkend="g-free"><function>g_free()</function></link></simpara></listitem></varlistentry></variablelist></refsect2><refsect2><title><anchor id="pango-read-line" role="function"/>pango_read_line ()</title><indexterm><primary>pango_read_line</primary></indexterm><programlisting><link linkend="gint">gint</link>                pango_read_line                     (<link linkend="FILE:CAPS">FILE</link> *stream,                                                         <link linkend="GString">GString</link> *str);</programlisting><para>Reads an entire line from a file into a buffer. Lines maybe delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiteris not written into the buffer. Text after a '#' character is treated asa comment and skipped. '\' can be used to escape a # character.'\' proceeding a line delimiter combines adjacent lines. A '\' proceedingany other character is ignored and written into the output bufferunmodified.</para><para></para><variablelist role="params"><varlistentry><term><parameter>stream</parameter>&nbsp;:</term><listitem><simpara> a stdio stream</simpara></listitem></varlistentry><varlistentry><term><parameter>str</parameter>&nbsp;:</term><listitem><simpara> <link linkend="GString"><type>GString</type></link> buffer into which to write the result</simpara></listitem></varlistentry><varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 0 if the stream was already at an <link linkend="EOF:CAPS"><literal>EOF</literal></link> character, otherwise              the number of lines read (this is useful for maintaining              a line number counter which doesn't combine lines with '\')</simpara></listitem></varlistentry></variablelist></refsect2><refsect2><title><anchor id="pango-skip-space" role="function"/>pango_skip_space ()</title><indexterm><primary>pango_skip_space</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_skip_space                    (const <link linkend="char">char</link> **pos);</programlisting><para>Skips 0 or more characters of white space.</para><para></para><variablelist role="params"><varlistentry><term><parameter>pos</parameter>&nbsp;:</term><listitem><simpara> in/out string position</simpara></listitem></varlistentry><varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if skipping the white space leavesthe position at a '\0' character.</simpara></listitem></varlistentry></variablelist></refsect2><refsect2><title><anchor id="pango-scan-word" role="function"/>pango_scan_word ()</title><indexterm><primary>pango_scan_word</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_scan_word                     (const <link linkend="char">char</link> **pos,                                                         <link linkend="GString">GString</link> *out);</programlisting><para>Scans a word into a <link linkend="GString"><type>GString</type></link> buffer. A word consistsof [A-Za-z_] followed by zero or more [A-Za-z_0-9]Leading white space is skipped.</para><para></para><variablelist role="params"><varlistentry><term><parameter>pos</parameter>&nbsp;:</term><listitem><simpara> in/out string position</simpara></listitem></varlistentry><varlistentry><term><parameter>out</parameter>&nbsp;:</term><listitem><simpara> a <link linkend="GString"><type>GString</type></link> into which to write the result</simpara></listitem></varlistentry><varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if a parse error occurred.</simpara></listitem></varlistentry></variablelist></refsect2><refsect2><title><anchor id="pango-scan-string" role="function"/>pango_scan_string ()</title><indexterm><primary>pango_scan_string</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_scan_string                   (const <link linkend="char">char</link> **pos,                                                         <link linkend="GString">GString</link> *out);</programlisting><para>Scans a string into a <link linkend="GString"><type>GString</type></link> buffer. The string may eitherbe a sequence of non-white-space characters, or a quotedstring with '"'. Instead a quoted string, '\"' representsa literal quote. Leading white space outside of quotes is skipped.</para><para></para><variablelist role="params"><varlistentry><term><parameter>pos</parameter>&nbsp;:</term><listitem><simpara> in/out string position</simpara></listitem></varlistentry>