<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="rasqal-section-variable">
<refmeta>
<refentrytitle role="top_of_page" id="rasqal-section-variable.top_of_page">Variables</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>RASQAL Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Variables</refname>
<refpurpose>Variable with names and literal value.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="rasqal-section-variable.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
                    <link linkend="rasqal-variable">rasqal_variable</link>;
<link linkend="rasqal-variable">rasqal_variable</link>*    <link linkend="rasqal-new-variable">rasqal_new_variable</link>                 (<link linkend="rasqal-query">rasqal_query</link> *rq,
                                                         unsigned <link linkend="char">char</link> *name,
                                                         <link linkend="rasqal-literal">rasqal_literal</link> *value);
<link linkend="rasqal-variable">rasqal_variable</link>*    <link linkend="rasqal-new-variable-typed">rasqal_new_variable_typed</link>           (<link linkend="rasqal-query">rasqal_query</link> *rq,
                                                         <link linkend="rasqal-variable-type">rasqal_variable_type</link> type,
                                                         unsigned <link linkend="char">char</link> *name,
                                                         <link linkend="rasqal-literal">rasqal_literal</link> *value);
<link linkend="rasqal-variable">rasqal_variable</link>*    <link linkend="rasqal-new-variable-from-variable">rasqal_new_variable_from_variable</link>   (<link linkend="rasqal-variable">rasqal_variable</link> *v);
<link linkend="void">void</link>                <link linkend="rasqal-free-variable">rasqal_free_variable</link>                (<link linkend="rasqal-variable">rasqal_variable</link> *v);
<link linkend="void">void</link>                <link linkend="rasqal-variable-print">rasqal_variable_print</link>               (<link linkend="rasqal-variable">rasqal_variable</link> *v,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);
<link linkend="void">void</link>                <link linkend="rasqal-variable-set-value">rasqal_variable_set_value</link>           (<link linkend="rasqal-variable">rasqal_variable</link> *v,
                                                         <link linkend="rasqal-literal">rasqal_literal</link> *l);
enum                <link linkend="rasqal-variable-type">rasqal_variable_type</link>;
</synopsis>
</refsynopsisdiv>









<refsect1 id="rasqal-section-variable.description" role="desc">
<title role="desc.title">Description</title>
<para>
A class to hold a variable with optional name and a
<link linkend="rasqal-literal"><type>rasqal_literal</type></link> value.  The name is not required for SPARQL
anonymous variables, when constructed with
<link linkend="rasqal-new-variable-typed"><function>rasqal_new_variable_typed()</function></link> and type <link linkend="RASQAL-VARIABLE-TYPE-ANONYMOUS:CAPS"><type>RASQAL_VARIABLE_TYPE_ANONYMOUS</type></link>.
</para>
</refsect1>

<refsect1 id="rasqal-section-variable.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="rasqal-variable" role="struct">
<title>rasqal_variable</title>
<indexterm zone="rasqal-variable"><primary>rasqal_variable</primary></indexterm><programlisting>typedef struct {
  const unsigned char *name;
  rasqal_literal* value;
  int offset;
  rasqal_variable_type type;
  struct rasqal_expression_s* expression;
} rasqal_variable;
</programlisting>
<para>
Binding between a variable name and a value.
</para>
<para>
Includes internal field <parameter>offset</parameter> for recording the offset into the
(internal) rasqal_query variables array.</para>
<para>

</para><variablelist role="struct">
<varlistentry>
<term><link linkend="rasqal-literal">rasqal_literal</link>&nbsp;*<structfield>value</structfield>;</term>
<listitem><simpara> Variable value or NULL if unbound.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="int">int</link>&nbsp;<structfield>offset</structfield>;</term>
<listitem><simpara> Internal.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="rasqal-variable-type">rasqal_variable_type</link>&nbsp;<structfield>type</structfield>;</term>
<listitem><simpara> Variable type.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term>struct&nbsp;<link linkend="rasqal-expression-s">rasqal_expression_s</link>&nbsp;*<structfield>expression</structfield>;</term>
<listitem><simpara> Expression when the variable is a computed SELECT expression 
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-variable" role="function">
<title>rasqal_new_variable ()</title>
<indexterm zone="rasqal-new-variable"><primary>rasqal_new_variable</primary></indexterm><programlisting><link linkend="rasqal-variable">rasqal_variable</link>*    rasqal_new_variable                 (<link linkend="rasqal-query">rasqal_query</link> *rq,
                                                         unsigned <link linkend="char">char</link> *name,
                                                         <link linkend="rasqal-literal">rasqal_literal</link> *value);</programlisting>
<para>
Constructor - Create a new Rasqal normal variable.
</para>
<para>
The variable must be associated with a query, since variable
names are only significant with a single query.
</para>
<para>
This creates a regular variable that can be returned of type
RASQAL_VARIABLE_TYPE_NORMAL.  Use rasqal_new_variable_typed
to create other variables.
</para>
<para>
The <parameter>name</parameter> and <parameter>value</parameter> become owned by the rasqal_variable structure</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>rq</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-query"><type>rasqal_query</type></link> to associate the variable with
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> variable name
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
<listitem><simpara> variable <link linkend="rasqal-literal"><type>rasqal_literal</type></link> value (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="rasqal-variable"><type>rasqal_variable</type></link> or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-variable-typed" role="function">
<title>rasqal_new_variable_typed ()</title>
<indexterm zone="rasqal-new-variable-typed"><primary>rasqal_new_variable_typed</primary></indexterm><programlisting><link linkend="rasqal-variable">rasqal_variable</link>*    rasqal_new_variable_typed           (<link linkend="rasqal-query">rasqal_query</link> *rq,
                                                         <link linkend="rasqal-variable-type">rasqal_variable_type</link> type,
                                                         unsigned <link linkend="char">char</link> *name,
                                                         <link linkend="rasqal-literal">rasqal_literal</link> *value);</programlisting>
<para>
Constructor - Create a new typed Rasqal variable.
</para>
<para>
The variable must be associated with a query, since variable
names are only significant with a single query.
</para>
<para>
The <parameter>name</parameter> and <parameter>value</parameter> become owned by the rasqal_variable structure</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>rq</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-query"><type>rasqal_query</type></link> to associate the variable with
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
<listitem><simpara> variable type defined by enumeration rasqal_variable_type
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> variable name
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
<listitem><simpara> variable <link linkend="rasqal-literal"><type>rasqal_literal</type></link> value (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="rasqal-variable"><type>rasqal_variable</type></link> or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-variable-from-variable" role="function">
<title>rasqal_new_variable_from_variable ()</title>
<indexterm zone="rasqal-new-variable-from-variable"><primary>rasqal_new_variable_from_variable</primary></indexterm><programlisting><link linkend="rasqal-variable">rasqal_variable</link>*    rasqal_new_variable_from_variable   (<link linkend="rasqal-variable">rasqal_variable</link> *v);</programlisting>
<para>
Copy Constructor - Create a new Rasqal variable from an existing one
</para>
<para>
This does a deep copy of all variable fields</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>v</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-variable"><type>rasqal_variable</type></link> to copy
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="rasqal-variable"><type>rasqal_variable</type></link> or NULL on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-free-variable" role="function">
<title>rasqal_free_variable ()</title>
<indexterm zone="rasqal-free-variable"><primary>rasqal_free_variable</primary></indexterm><programlisting><link linkend="void">void</link>                rasqal_free_variable                (<link linkend="rasqal-variable">rasqal_variable</link> *v);</programlisting>
<para>
Destructor - Destroy a Rasqal variable object.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>v</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-variable"><type>rasqal_variable</type></link> object
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-variable-print" role="function">
<title>rasqal_variable_print ()</title>
<indexterm zone="rasqal-variable-print"><primary>rasqal_variable_print</primary></indexterm><programlisting><link linkend="void">void</link>                rasqal_variable_print               (<link linkend="rasqal-variable">rasqal_variable</link> *v,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);</programlisting>
<para>
Print a Rasqal variable in a debug format.
</para>
<para>
The print debug format may change in any release.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>v</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="rasqal-variable"><type>rasqal_variable</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fh</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="FILE:CAPS"><type>FILE</type></link>* handle to print to
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-variable-set-value" role="function">
<title>rasqal_variable_set_value ()</title>
<indexterm zone="rasqal-variable-set-value"><primary>rasqal_variable_set_value</primary></indexterm><programlisting><link linkend="void">void</link>                rasqal_variable_set_value           (<link linkend="rasqal-variable">rasqal_variable</link> *v,
                                                         <link linkend="rasqal-literal">rasqal_literal</link> *l);</programlisting>
<para>
Set the value of a Rasqal variable.
</para>
<para>
The variable value is an input parameter and is copied in, not shared.
If the variable value is NULL, any existing value is deleted.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>v</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="rasqal-variable"><type>rasqal_variable</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="rasqal-literal"><type>rasqal_literal</type></link> value to set (or NULL)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-variable-type" role="enum">
<title>enum rasqal_variable_type</title>
<indexterm zone="rasqal-variable-type"><primary>rasqal_variable_type</primary></indexterm><programlisting>typedef enum {
  RASQAL_VARIABLE_TYPE_UNKNOWN   = 0,
  RASQAL_VARIABLE_TYPE_NORMAL    = 1,
  RASQAL_VARIABLE_TYPE_ANONYMOUS = 2
} rasqal_variable_type;
</programlisting>
<para>
Rasqal variable types.
</para>
<para>
ANONYMOUS can be used in queries but cannot be returned in a
result.</para>
<para>

</para><variablelist role="enum">
<varlistentry id="RASQAL-VARIABLE-TYPE-UNKNOWN:CAPS" role="constant">
<term><literal>RASQAL_VARIABLE_TYPE_UNKNOWN</literal></term>
<listitem><simpara> Internal.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-VARIABLE-TYPE-NORMAL:CAPS" role="constant">
<term><literal>RASQAL_VARIABLE_TYPE_NORMAL</literal></term>
<listitem><simpara> The regular variable type.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-VARIABLE-TYPE-ANONYMOUS:CAPS" role="constant">
<term><literal>RASQAL_VARIABLE_TYPE_ANONYMOUS</literal></term>
<listitem><simpara> Anonymous variable type.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
