<refentry id="streamtuner-st-util-api">
<refmeta>
<refentrytitle>st-util</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>STREAMTUNER Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>st-util</refname><refpurpose>miscellaneous utility functions.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>



#define     <link linkend="ST-NUMERIC-CAPS">ST_NUMERIC</link>
<link linkend="char">char</link>*       <link linkend="st-format-bitrate">st_format_bitrate</link>               (<link linkend="int">int</link> bitrate);
<link linkend="char">char</link>*       <link linkend="st-format-samplerate">st_format_samplerate</link>            (<link linkend="int">int</link> samplerate);
<link linkend="char">char</link>*       <link linkend="st-format-channels">st_format_channels</link>              (<link linkend="int">int</link> channels);
<link linkend="char">char</link>*       <link linkend="st-format-audio-properties">st_format_audio_properties</link>      (<link linkend="int">int</link> bitrate,
                                             <link linkend="int">int</link> samplerate,
                                             <link linkend="int">int</link> channels);
<link linkend="char">char</link>*       <link linkend="st-strchr-span">st_strchr_span</link>                  (const <link linkend="char">char</link> *str,
                                             <link linkend="int">int</link> c);
<link linkend="char">char</link>*       <link linkend="st-strstr-span">st_strstr_span</link>                  (const <link linkend="char">char</link> *big,
                                             const <link linkend="char">char</link> *little);
<link linkend="char">char</link>*       <link linkend="st-str-has-prefix-span">st_str_has_prefix_span</link>          (const <link linkend="char">char</link> *str,
                                             const <link linkend="char">char</link> *prefix);
<link linkend="gboolean">gboolean</link>    <link linkend="st-str-like">st_str_like</link>                     (const <link linkend="char">char</link> *str,
                                             const <link linkend="char">char</link> *charset);
<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="st-pixbuf-new-from-file">st_pixbuf_new_from_file</link>         (const <link linkend="char">char</link> *filename);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="st-hig-section-new">st_hig_section_new</link>              (const <link linkend="char">char</link> *title,
                                             <link linkend="GtkWidget">GtkWidget</link> *contents);
<link linkend="void">void</link>        <link linkend="st-set-tooltip">st_set_tooltip</link>                  (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             const <link linkend="char">char</link> *tooltip);
</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="ST-NUMERIC-CAPS"/>ST_NUMERIC</title>
<indexterm><primary>ST_NUMERIC</primary></indexterm><programlisting>#define ST_NUMERIC			"0123456789"
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="st-format-bitrate"/>st_format_bitrate ()</title>
<indexterm><primary>st_format_bitrate</primary></indexterm><programlisting><link linkend="char">char</link>*       st_format_bitrate               (<link linkend="int">int</link> bitrate);</programlisting>
<para>
Formats <parameter>bitrate</parameter> as a string.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>bitrate</parameter>&nbsp;:</term>
<listitem><simpara> a bitrate to format, expressed in kilobits per seconds.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>bitrate</parameter> formatted as a string, which should be freed
when no longer needed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-format-samplerate"/>st_format_samplerate ()</title>
<indexterm><primary>st_format_samplerate</primary></indexterm><programlisting><link linkend="char">char</link>*       st_format_samplerate            (<link linkend="int">int</link> samplerate);</programlisting>
<para>
Formats <parameter>samplerate</parameter> as a string.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>samplerate</parameter>&nbsp;:</term>
<listitem><simpara> a samplerate to format, expressed in Hz.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>samplerate</parameter> formatted as a string, which should be
freed when no longer needed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-format-channels"/>st_format_channels ()</title>
<indexterm><primary>st_format_channels</primary></indexterm><programlisting><link linkend="char">char</link>*       st_format_channels              (<link linkend="int">int</link> channels);</programlisting>
<para>
Formats <parameter>channels</parameter> as a string.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>channels</parameter>&nbsp;:</term>
<listitem><simpara> a number of audio channels, which must be greater than
0.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <parameter>channels</parameter> formatted as a string, which should be
freed when no longer needed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-format-audio-properties"/>st_format_audio_properties ()</title>
<indexterm><primary>st_format_audio_properties</primary></indexterm><programlisting><link linkend="char">char</link>*       st_format_audio_properties      (<link linkend="int">int</link> bitrate,
                                             <link linkend="int">int</link> samplerate,
                                             <link linkend="int">int</link> channels);</programlisting>
<para>
Formats <parameter>bitrate</parameter>, <parameter>samplerate</parameter> and <parameter>channels</parameter> as a string.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>bitrate</parameter>&nbsp;:</term>
<listitem><simpara> a bitrate expressed in kbps, or 0.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>samplerate</parameter>&nbsp;:</term>
<listitem><simpara> a samplerate expressed in kbps, or 0.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>channels</parameter>&nbsp;:</term>
<listitem><simpara> a number of audio channels, or 0.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a formatted string, which should be freed when no
longer needed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-strchr-span"/>st_strchr_span ()</title>
<indexterm><primary>st_strchr_span</primary></indexterm><programlisting><link linkend="char">char</link>*       st_strchr_span                  (const <link linkend="char">char</link> *str,
                                             <link linkend="int">int</link> c);</programlisting>
<para>
Locates the first occurrence of <parameter>c</parameter> (converted to a char) in <parameter>str</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>c</parameter>&nbsp;:</term>
<listitem><simpara> a character to locate, which must not be 0.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the character following the first
occurrence of <parameter>c</parameter> in <parameter>str</parameter>, or <literal>NULL</literal> if <parameter>c</parameter> does not appear in <parameter>str</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-strstr-span"/>st_strstr_span ()</title>
<indexterm><primary>st_strstr_span</primary></indexterm><programlisting><link linkend="char">char</link>*       st_strstr_span                  (const <link linkend="char">char</link> *big,
                                             const <link linkend="char">char</link> *little);</programlisting>
<para>
Locates the first occurrence of <parameter>little</parameter> in <parameter>big</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>big</parameter>&nbsp;:</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>little</parameter>&nbsp;:</term>
<listitem><simpara> a string to search for in <parameter>big</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the character following the first
occurrence of <parameter>little</parameter> in <parameter>big</parameter>, or <literal>NULL</literal> if <parameter>little</parameter> does not appear
in <parameter>big</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-str-has-prefix-span"/>st_str_has_prefix_span ()</title>
<indexterm><primary>st_str_has_prefix_span</primary></indexterm><programlisting><link linkend="char">char</link>*       st_str_has_prefix_span          (const <link linkend="char">char</link> *str,
                                             const <link linkend="char">char</link> *prefix);</programlisting>
<para>
Checks if <parameter>str</parameter> begins with <parameter>prefix</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>prefix</parameter>&nbsp;:</term>
<listitem><simpara> the prefix to look for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the character following <parameter>prefix</parameter> in <parameter>str</parameter>,
or <literal>NULL</literal> if <parameter>str</parameter> does not begin with <parameter>prefix</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-str-like"/>st_str_like ()</title>
<indexterm><primary>st_str_like</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    st_str_like                     (const <link linkend="char">char</link> *str,
                                             const <link linkend="char">char</link> *charset);</programlisting>
<para>
Checks if all the characters of <parameter>str</parameter> are members of <parameter>charset</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
<listitem><simpara> a string.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>charset</parameter>&nbsp;:</term>
<listitem><simpara> a set of characters.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> if all the characters of <parameter>str</parameter> are members of
<parameter>charset</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-pixbuf-new-from-file"/>st_pixbuf_new_from_file ()</title>
<indexterm><primary>st_pixbuf_new_from_file</primary></indexterm><programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  st_pixbuf_new_from_file         (const <link linkend="char">char</link> *filename);</programlisting>
<para>
Creates a new pixbuf by loading an image from a file. If the file
cannot be loaded, <link linkend="st-notice"><function>st_notice()</function></link> will be used to print the error.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>filename</parameter>&nbsp;:</term>
<listitem><simpara> the name of the file to load.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link>, or <literal>NULL</literal> on error.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-hig-section-new"/>st_hig_section_new ()</title>
<indexterm><primary>st_hig_section_new</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>*  st_hig_section_new              (const <link linkend="char">char</link> *title,
                                             <link linkend="GtkWidget">GtkWidget</link> *contents);</programlisting>
<para>
Creates a new HIG-compliant section, as defined by
<ulink url="http://developer.gnome.org/projects/gup/hig/2.0/design-window.html" type="http">Window Layout</ulink>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>title</parameter>&nbsp;:</term>
<listitem><simpara> the section title.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>contents</parameter>&nbsp;:</term>
<listitem><simpara> the widget to use as section contents.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new <link linkend="GtkVBox"><type>GtkVBox</type></link> containing <parameter>title</parameter> and <parameter>contents</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-set-tooltip"/>st_set_tooltip ()</title>
<indexterm><primary>st_set_tooltip</primary></indexterm><programlisting><link linkend="void">void</link>        st_set_tooltip                  (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             const <link linkend="char">char</link> *tooltip);</programlisting>
<para>
Sets the tooltip of <parameter>widget</parameter> using the global <link linkend="GtkTooltips"><type>GtkTooltips</type></link> object
used by streamtuner.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>widget</parameter>&nbsp;:</term>
<listitem><simpara> a widget.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>tooltip</parameter>&nbsp;:</term>
<listitem><simpara> a tooltip text.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
