<?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-literal">
<refmeta>
<refentrytitle role="top_of_page" id="rasqal-section-literal.top_of_page">Literal</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>RASQAL Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Literal</refname>
<refpurpose>RDF literals and RDF query-specific literals.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

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

<synopsis>
typedef             <link linkend="rasqal-literal">rasqal_literal</link>;
enum                <link linkend="rasqal-literal-type">rasqal_literal_type</link>;
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-typed-literal">rasqal_new_typed_literal</link>            (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="rasqal-literal-type">rasqal_literal_type</link> type,
                                                         unsigned <link linkend="char">char</link> *string);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-boolean-literal">rasqal_new_boolean_literal</link>          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="int">int</link> value);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-decimal-literal">rasqal_new_decimal_literal</link>          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         unsigned <link linkend="char">char</link> *string);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-decimal-literal-from-decimal">rasqal_new_decimal_literal_from_decimal</link>
                                                        (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="rasqal-xsd-decimal">rasqal_xsd_decimal</link> *decimal);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-double-literal">rasqal_new_double_literal</link>           (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="double">double</link> d);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-float-literal">rasqal_new_float_literal</link>            (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="float">float</link> f);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-integer-literal">rasqal_new_integer_literal</link>          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="rasqal-literal-type">rasqal_literal_type</link> type,
                                                         <link linkend="int">int</link> integer);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-pattern-literal">rasqal_new_pattern_literal</link>          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         unsigned <link linkend="char">char</link> *pattern,
                                                         const <link linkend="char">char</link> *flags);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-simple-literal">rasqal_new_simple_literal</link>           (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="rasqal-literal-type">rasqal_literal_type</link> type,
                                                         unsigned <link linkend="char">char</link> *string);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-string-literal">rasqal_new_string_literal</link>           (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         const <link linkend="char">char</link> *language,
                                                         <link linkend="raptor-uri">raptor_uri</link> *datatype,
                                                         unsigned <link linkend="char">char</link> *datatype_qname);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-uri-literal">rasqal_new_uri_literal</link>              (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-variable-literal">rasqal_new_variable_literal</link>         (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="rasqal-variable">rasqal_variable</link> *variable);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-new-literal-from-literal">rasqal_new_literal_from_literal</link>     (<link linkend="rasqal-literal">rasqal_literal</link> *l);
<link linkend="void">void</link>                <link linkend="rasqal-free-literal">rasqal_free_literal</link>                 (<link linkend="rasqal-literal">rasqal_literal</link> *l);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-literal-as-node">rasqal_literal_as_node</link>              (<link linkend="rasqal-literal">rasqal_literal</link> *l);
const unsigned <link linkend="char">char</link>* <link linkend="rasqal-literal-as-string">rasqal_literal_as_string</link>           (<link linkend="rasqal-literal">rasqal_literal</link> *l);
const unsigned <link linkend="char">char</link>* <link linkend="rasqal-literal-as-string-flags">rasqal_literal_as_string_flags</link>     (<link linkend="rasqal-literal">rasqal_literal</link> *l,
                                                         <link linkend="int">int</link> flags,
                                                         <link linkend="int">int</link> *error);
<link linkend="rasqal-variable">rasqal_variable</link>*    <link linkend="rasqal-literal-as-variable">rasqal_literal_as_variable</link>          (<link linkend="rasqal-literal">rasqal_literal</link> *l);
<link linkend="int">int</link>                 <link linkend="rasqal-literal-compare">rasqal_literal_compare</link>              (<link linkend="rasqal-literal">rasqal_literal</link> *l1,
                                                         <link linkend="rasqal-literal">rasqal_literal</link> *l2,
                                                         <link linkend="int">int</link> flags,
                                                         <link linkend="int">int</link> *error);
<link linkend="raptor-uri">raptor_uri</link>*         <link linkend="rasqal-literal-datatype">rasqal_literal_datatype</link>             (<link linkend="rasqal-literal">rasqal_literal</link> *l);
<link linkend="int">int</link>                 <link linkend="rasqal-literal-equals">rasqal_literal_equals</link>               (<link linkend="rasqal-literal">rasqal_literal</link> *l1,
                                                         <link linkend="rasqal-literal">rasqal_literal</link> *l2);
<link linkend="void">void</link>                <link linkend="rasqal-literal-print">rasqal_literal_print</link>                (<link linkend="rasqal-literal">rasqal_literal</link> *l,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);
<link linkend="void">void</link>                <link linkend="rasqal-literal-print-type">rasqal_literal_print_type</link>           (<link linkend="rasqal-literal">rasqal_literal</link> *l,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);
<link linkend="rasqal-literal">rasqal_literal</link>*     <link linkend="rasqal-literal-value">rasqal_literal_value</link>                (<link linkend="rasqal-literal">rasqal_literal</link> *l);
</synopsis>
</refsynopsisdiv>









<refsect1 id="rasqal-section-literal.description" role="desc">
<title role="desc.title">Description</title>
<para>
A class for handling RDF terms (URI, blank nodes, strings, datatyped
literals) as well as those natively used in a query such as
boolean, double, floating, integer, regex pattern and variables.
</para>
</refsect1>

<refsect1 id="rasqal-section-literal.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="rasqal-literal" role="typedef">
<title>rasqal_literal</title>
<indexterm zone="rasqal-literal"><primary>rasqal_literal</primary></indexterm><programlisting>typedef struct rasqal_literal_s rasqal_literal;
</programlisting>
<para>
Rasqal literal class.</para>
<para>

</para></refsect2>
<refsect2 id="rasqal-literal-type" role="enum">
<title>enum rasqal_literal_type</title>
<indexterm zone="rasqal-literal-type"><primary>rasqal_literal_type</primary></indexterm><programlisting>typedef enum {
  /* internal */
  RASQAL_LITERAL_UNKNOWN,
  RASQAL_LITERAL_BLANK,
  RASQAL_LITERAL_URI,
  RASQAL_LITERAL_STRING,
  RASQAL_LITERAL_BOOLEAN,
  RASQAL_LITERAL_INTEGER,
  RASQAL_LITERAL_DOUBLE,
  RASQAL_LITERAL_FLOAT,
  RASQAL_LITERAL_DECIMAL,
  RASQAL_LITERAL_DATETIME,
  /* internal */
  RASQAL_LITERAL_FIRST_XSD = RASQAL_LITERAL_STRING,
  /* internal */
  RASQAL_LITERAL_LAST_XSD = RASQAL_LITERAL_DATETIME,
  RASQAL_LITERAL_PATTERN,
  RASQAL_LITERAL_QNAME,
  RASQAL_LITERAL_VARIABLE,
  /* internal */
  RASQAL_LITERAL_LAST= RASQAL_LITERAL_VARIABLE
} rasqal_literal_type;
</programlisting>
<para>
Types of literal.
</para>
<para>
The order in the enumeration is significant as it encodes
the SPARQL term ordering conditions:
</para>
<para>
  Blank Nodes &lt;&lt; IRIs &lt;&lt; RDF literals &lt;&lt; typed literals
</para>
<para>
which coresponds to in enum values
</para>
<para>
  BLANK &lt;&lt; URI &lt;&lt; STRING &lt;&lt; 
    (BOOLEAN | INTEGER | DOUBLE | FLOAT | DECIMAL | DATETIME)
</para>
<para>
    (RASQAL_LITERAL_FIRST_XSD ... RASQAL_LITERAL_LAST_XSD)
</para>
<para>
Not used (internal): PATTERN, QNAME, VARIABLE
</para>
<para>
See <link linkend="rasqal-literal-compare"><function>rasqal_literal_compare()</function></link> when used with flags
<link linkend="RASQAL-COMPARE-XQUERY:CAPS"><literal>RASQAL_COMPARE_XQUERY</literal></link></para>
<para>

</para><variablelist role="enum">
<varlistentry id="RASQAL-LITERAL-UNKNOWN:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_UNKNOWN</literal></term>
<listitem><simpara> Internal.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-BLANK:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_BLANK</literal></term>
<listitem><simpara> RDF blank node literal (SPARQL r:bNode)
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-URI:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_URI</literal></term>
<listitem><simpara> RDF URI Literal (SPARQL r:URI)
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-STRING:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_STRING</literal></term>
<listitem><simpara> RDF Literal / xsd:string (SPARQL r:Literal)
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-BOOLEAN:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_BOOLEAN</literal></term>
<listitem><simpara> Boolean literal xsd:boolean.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-INTEGER:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_INTEGER</literal></term>
<listitem><simpara> Integer literal xsd:integer.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-DOUBLE:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_DOUBLE</literal></term>
<listitem><simpara> Double floating point literal xsd:double.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-FLOAT:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_FLOAT</literal></term>
<listitem><simpara> Floating point literal xsd:float.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-DECIMAL:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_DECIMAL</literal></term>
<listitem><simpara> Decimal integer xsd:decimal.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-DATETIME:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_DATETIME</literal></term>
<listitem><simpara> Date/Time literal xsd:dateTime.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-FIRST-XSD:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_FIRST_XSD</literal></term>
<listitem><simpara> Internal.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-LAST-XSD:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_LAST_XSD</literal></term>
<listitem><simpara> Internal.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-PATTERN:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_PATTERN</literal></term>
<listitem><simpara> Pattern literal for a regex.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-QNAME:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_QNAME</literal></term>
<listitem><simpara> XML Qname literal.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-VARIABLE:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_VARIABLE</literal></term>
<listitem><simpara> Variable literal.
</simpara></listitem>
</varlistentry>
<varlistentry id="RASQAL-LITERAL-LAST:CAPS" role="constant">
<term><literal>RASQAL_LITERAL_LAST</literal></term>
<listitem><simpara> Internal.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-typed-literal" role="function">
<title>rasqal_new_typed_literal ()</title>
<indexterm zone="rasqal-new-typed-literal"><primary>rasqal_new_typed_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_typed_literal            (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="rasqal-literal-type">rasqal_literal_type</link> type,
                                                         unsigned <link linkend="char">char</link> *string);</programlisting>
<para>
Constructor - Create a new Rasqal integer literal from a string
</para>
<para>
The integer decimal number is turned into a rasqal integer literal
and given a datatype of xsd:integer</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
<listitem><simpara> Type of literal such as RASQAL_LITERAL_INTEGER or RASQAL_LITERAL_BOOLEAN
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> lexical form - ownership not taken
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-boolean-literal" role="function">
<title>rasqal_new_boolean_literal ()</title>
<indexterm zone="rasqal-new-boolean-literal"><primary>rasqal_new_boolean_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_boolean_literal          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="int">int</link> value);</programlisting>
<para>
Constructor - Create a new Rasqal boolean literal.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
<listitem><simpara> non-0 for true, 0 for false
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-decimal-literal" role="function">
<title>rasqal_new_decimal_literal ()</title>
<indexterm zone="rasqal-new-decimal-literal"><primary>rasqal_new_decimal_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_decimal_literal          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         unsigned <link linkend="char">char</link> *string);</programlisting>
<para>
Constructor - Create a new Rasqal decimal literal.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> decimal literal
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-decimal-literal-from-decimal" role="function">
<title>rasqal_new_decimal_literal_from_decimal ()</title>
<indexterm zone="rasqal-new-decimal-literal-from-decimal"><primary>rasqal_new_decimal_literal_from_decimal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_decimal_literal_from_decimal
                                                        (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         <link linkend="rasqal-xsd-decimal">rasqal_xsd_decimal</link> *decimal);</programlisting>
<para>
Constructor - Create a new Rasqal decimal literal.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> decimal literal string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>decimal</parameter>&nbsp;:</term>
<listitem><simpara> rasqal XSD Decimal
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-double-literal" role="function">
<title>rasqal_new_double_literal ()</title>
<indexterm zone="rasqal-new-double-literal"><primary>rasqal_new_double_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_double_literal           (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="double">double</link> d);</programlisting>
<para>
Constructor - Create a new Rasqal double literal.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>d</parameter>&nbsp;:</term>
<listitem><simpara> double literal
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-float-literal" role="function">
<title>rasqal_new_float_literal ()</title>
<indexterm zone="rasqal-new-float-literal"><primary>rasqal_new_float_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_float_literal            (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="float">float</link> f);</programlisting>
<para>
Constructor - Create a new Rasqal float literal.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>f</parameter>&nbsp;:</term>
<listitem><simpara>  float literal
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-integer-literal" role="function">
<title>rasqal_new_integer_literal ()</title>
<indexterm zone="rasqal-new-integer-literal"><primary>rasqal_new_integer_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_integer_literal          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="rasqal-literal-type">rasqal_literal_type</link> type,
                                                         <link linkend="int">int</link> integer);</programlisting>
<para>
Constructor - Create a new Rasqal integer literal.
</para>
<para>
The integer decimal number is turned into a rasqal integer literal
and given a datatype of xsd:integer</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
<listitem><simpara> Type of literal such as RASQAL_LITERAL_INTEGER or RASQAL_LITERAL_BOOLEAN
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>integer</parameter>&nbsp;:</term>
<listitem><simpara> int value
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-pattern-literal" role="function">
<title>rasqal_new_pattern_literal ()</title>
<indexterm zone="rasqal-new-pattern-literal"><primary>rasqal_new_pattern_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_pattern_literal          (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         unsigned <link linkend="char">char</link> *pattern,
                                                         const <link linkend="char">char</link> *flags);</programlisting>
<para>
Constructor - Create a new Rasqal pattern literal.
</para>
<para>
The pattern and flags are input parameters and are stored in the
literal, not copied. They are freed also on failure.
The set of flags recognised depends on the regex engine and the query
language.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>pattern</parameter>&nbsp;:</term>
<listitem><simpara> regex pattern
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
<listitem><simpara> regex flags
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-simple-literal" role="function">
<title>rasqal_new_simple_literal ()</title>
<indexterm zone="rasqal-new-simple-literal"><primary>rasqal_new_simple_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_simple_literal           (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="rasqal-literal-type">rasqal_literal_type</link> type,
                                                         unsigned <link linkend="char">char</link> *string);</programlisting>
<para>
Constructor - Create a new Rasqal simple literal.
</para>
<para>
The string is an input parameter and is stored in the
literal, not copied. It is freed also on failure.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
<listitem><simpara> RASQAL_LITERAL_BLANK or RASQAL_LITERAL_BLANK_QNAME
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> the UTF-8 string value to store
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-string-literal" role="function">
<title>rasqal_new_string_literal ()</title>
<indexterm zone="rasqal-new-string-literal"><primary>rasqal_new_string_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_string_literal           (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         unsigned <link linkend="char">char</link> *string,
                                                         const <link linkend="char">char</link> *language,
                                                         <link linkend="raptor-uri">raptor_uri</link> *datatype,
                                                         unsigned <link linkend="char">char</link> *datatype_qname);</programlisting>
<para>
Constructor - Create a new Rasqal string literal.
</para>
<para>
All parameters are input parameters and if present are stored in
the literal, not copied. They are freed also on failure.
</para>
<para>
The datatype and datatype_qname parameters are alternatives; the
qname is a datatype that cannot be resolved till later since the
prefixes have not yet been declared or checked.
</para>
<para>
If the string literal is datatyped and of certain types recognised
it may be converted to a different literal type by
<link linkend="rasqal-literal-string-to-native"><function>rasqal_literal_string_to_native()</function></link></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara> UTF-8 string lexical form
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>language</parameter>&nbsp;:</term>
<listitem><simpara> RDF language (xml:lang) (or NULL)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>datatype</parameter>&nbsp;:</term>
<listitem><simpara> datatype URI (or NULL for plain literal)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>datatype_qname</parameter>&nbsp;:</term>
<listitem><simpara> datatype qname string (or NULL for plain literal)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-uri-literal" role="function">
<title>rasqal_new_uri_literal ()</title>
<indexterm zone="rasqal-new-uri-literal"><primary>rasqal_new_uri_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_uri_literal              (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="raptor-uri">raptor_uri</link> *uri);</programlisting>
<para>
Constructor - Create a new Rasqal URI literal from a raptor URI.
</para>
<para>
The uri is an input parameter and is stored in the literal, not copied.
The uri is freed also on failure.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="raptor-uri"><type>raptor_uri</type></link> uri
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-variable-literal" role="function">
<title>rasqal_new_variable_literal ()</title>
<indexterm zone="rasqal-new-variable-literal"><primary>rasqal_new_variable_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_variable_literal         (<link linkend="rasqal-world">rasqal_world</link> *world,
                                                         <link linkend="rasqal-variable">rasqal_variable</link> *variable);</programlisting>
<para>
Constructor - Create a new Rasqal variable literal.
</para>
<para>
variable is an input parameter and stored in the literal, not copied.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>world</parameter>&nbsp;:</term>
<listitem><simpara> rasqal_world object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>variable</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-variable"><type>rasqal_variable</type></link> to use
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> New <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-new-literal-from-literal" role="function">
<title>rasqal_new_literal_from_literal ()</title>
<indexterm zone="rasqal-new-literal-from-literal"><primary>rasqal_new_literal_from_literal</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_new_literal_from_literal     (<link linkend="rasqal-literal">rasqal_literal</link> *l);</programlisting>
<para>
Copy Constructor - create a new rasqal_literal object from an existing rasqal_literal object.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> object to copy
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="rasqal-literal"><type>rasqal_literal</type></link> object or NULL
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-free-literal" role="function">
<title>rasqal_free_literal ()</title>
<indexterm zone="rasqal-free-literal"><primary>rasqal_free_literal</primary></indexterm><programlisting><link linkend="void">void</link>                rasqal_free_literal                 (<link linkend="rasqal-literal">rasqal_literal</link> *l);</programlisting>
<para>
Destructor - destroy an rasqal_literal object.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> object
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-literal-as-node" role="function">
<title>rasqal_literal_as_node ()</title>
<indexterm zone="rasqal-literal-as-node"><primary>rasqal_literal_as_node</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_literal_as_node              (<link linkend="rasqal-literal">rasqal_literal</link> *l);</programlisting>
<para>
Turn a literal into a new RDF string, URI or blank literal.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the new <link linkend="rasqal-literal"><type>rasqal_literal</type></link> or NULL on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-literal-as-string" role="function">
<title>rasqal_literal_as_string ()</title>
<indexterm zone="rasqal-literal-as-string"><primary>rasqal_literal_as_string</primary></indexterm><programlisting>const unsigned <link linkend="char">char</link>* rasqal_literal_as_string           (<link linkend="rasqal-literal">rasqal_literal</link> *l);</programlisting>
<para>
Return the string format of a literal.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> pointer to a shared string format of the literal.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-literal-as-string-flags" role="function">
<title>rasqal_literal_as_string_flags ()</title>
<indexterm zone="rasqal-literal-as-string-flags"><primary>rasqal_literal_as_string_flags</primary></indexterm><programlisting>const unsigned <link linkend="char">char</link>* rasqal_literal_as_string_flags     (<link linkend="rasqal-literal">rasqal_literal</link> *l,
                                                         <link linkend="int">int</link> flags,
                                                         <link linkend="int">int</link> *error);</programlisting>
<para>
Return the string format of a literal according to flags.
</para>
<para>
flag bits affects conversion:
  RASQAL_COMPARE_XQUERY: use XQuery conversion rules
</para>
<para>
If <parameter>error</parameter> is not NULL, *error is set to non-0 on error</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
<listitem><simpara> comparison flags
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
<listitem><simpara> pointer to error
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> pointer to a shared string format of the literal.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-literal-as-variable" role="function">
<title>rasqal_literal_as_variable ()</title>
<indexterm zone="rasqal-literal-as-variable"><primary>rasqal_literal_as_variable</primary></indexterm><programlisting><link linkend="rasqal-variable">rasqal_variable</link>*    rasqal_literal_as_variable          (<link linkend="rasqal-literal">rasqal_literal</link> *l);</programlisting>
<para>
Get the variable inside a literal.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the <link linkend="rasqal-variable"><type>rasqal_variable</type></link> or NULL if the literal is not a variable
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-literal-compare" role="function">
<title>rasqal_literal_compare ()</title>
<indexterm zone="rasqal-literal-compare"><primary>rasqal_literal_compare</primary></indexterm><programlisting><link linkend="int">int</link>                 rasqal_literal_compare              (<link linkend="rasqal-literal">rasqal_literal</link> *l1,
                                                         <link linkend="rasqal-literal">rasqal_literal</link> *l2,
                                                         <link linkend="int">int</link> flags,
                                                         <link linkend="int">int</link> *error);</programlisting>
<para>
Compare two literals with type promotion.
</para>
<para>
The two literals are compared across their range.  If the types
are not the same, they are promoted.  If one is a double or float, the
other is promoted to double, otherwise for integers, otherwise
to strings (all literals have a string value).
</para>
<para>
The comparison returned is as for strcmp, first before second
returns &lt;0.  equal returns 0, and first after second returns &gt;0.
For URIs, the string value is used for the comparsion.
</para>
<para>
flag bits affects comparisons:
  RASQAL_COMPARE_NOCASE: use case independent string comparisons
  RASQAL_COMPARE_XQUERY: use XQuery comparison and type promotion rules
  RASQAL_COMPARE_RDF: use RDF term comparison
  RASQAL_COMPARE_URI: allow comparison of URIs (typically for SPARQL ORDER)
</para>
<para>
If <parameter>error</parameter> is not NULL, *error is set to non-0 on error</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l1</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> first literal
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>l2</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> second literal
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
<listitem><simpara> comparison flags
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
<listitem><simpara> pointer to error
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> &lt;0, 0, or &gt;0 as described above.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-literal-datatype" role="function">
<title>rasqal_literal_datatype ()</title>
<indexterm zone="rasqal-literal-datatype"><primary>rasqal_literal_datatype</primary></indexterm><programlisting><link linkend="raptor-uri">raptor_uri</link>*         rasqal_literal_datatype             (<link linkend="rasqal-literal">rasqal_literal</link> *l);</programlisting>
<para>
Get the datatype URI of a literal</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> shared pointer to <link linkend="raptor-uri"><type>raptor_uri</type></link> of datatype or NULL on failure or no value
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-literal-equals" role="function">
<title>rasqal_literal_equals ()</title>
<indexterm zone="rasqal-literal-equals"><primary>rasqal_literal_equals</primary></indexterm><programlisting><link linkend="int">int</link>                 rasqal_literal_equals               (<link linkend="rasqal-literal">rasqal_literal</link> *l1,
                                                         <link linkend="rasqal-literal">rasqal_literal</link> *l2);</programlisting>
<para>
Compare two literals with no type promotion.
</para>
<para>
If the l2 data literal value is a boolean, it will match
the string "true" or "false" in the first literal l1.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l1</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> literal
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>l2</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> data literal
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> non-0 if equal
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="rasqal-literal-print" role="function">
<title>rasqal_literal_print ()</title>
<indexterm zone="rasqal-literal-print"><primary>rasqal_literal_print</primary></indexterm><programlisting><link linkend="void">void</link>                rasqal_literal_print                (<link linkend="rasqal-literal">rasqal_literal</link> *l,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);</programlisting>
<para>
Print a Rasqal literal in a debug format.
</para>
<para>
The print debug format may change in any release.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="rasqal-literal"><type>rasqal_literal</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-literal-print-type" role="function">
<title>rasqal_literal_print_type ()</title>
<indexterm zone="rasqal-literal-print-type"><primary>rasqal_literal_print_type</primary></indexterm><programlisting><link linkend="void">void</link>                rasqal_literal_print_type           (<link linkend="rasqal-literal">rasqal_literal</link> *l,
                                                         <link linkend="FILE:CAPS">FILE</link> *fh);</programlisting>
<para>
Print a string form for a rasqal literal type.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="rasqal-literal"><type>rasqal_literal</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-literal-value" role="function">
<title>rasqal_literal_value ()</title>
<indexterm zone="rasqal-literal-value"><primary>rasqal_literal_value</primary></indexterm><programlisting><link linkend="rasqal-literal">rasqal_literal</link>*     rasqal_literal_value                (<link linkend="rasqal-literal">rasqal_literal</link> *l);</programlisting>
<para>
Get the literal value looking up any variables needed</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>l</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="rasqal-literal"><type>rasqal_literal</type></link> object
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> literal value or NULL if has no value
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
