Literal 3 RASQAL Library
Literal RDF literals and RDF query-specific literals.

## Synopsis

    typedef     rasqal_literal;
    enum        rasqal_literal_type;
    rasqal_literal* rasqal_new_boolean_literal  (int value);
    rasqal_literal* rasqal_new_decimal_literal  (unsigned char *decimal);
    rasqal_literal* rasqal_new_double_literal   (double d);
    rasqal_literal* rasqal_new_floating_literal (double f);
    rasqal_literal* rasqal_new_integer_literal  (rasqal_literal_type type,
                                                 int integer);
    rasqal_literal* rasqal_new_pattern_literal  (unsigned char *pattern,
                                                 const char *flags);
    rasqal_literal* rasqal_new_simple_literal   (rasqal_literal_type type,
                                                 unsigned char *string);
    rasqal_literal* rasqal_new_string_literal   (unsigned char *string,
                                                 const char *language,
                                                 raptor_uri *datatype,
                                                 unsigned char *datatype_qname);
    rasqal_literal* rasqal_new_uri_literal      (raptor_uri *uri);
    rasqal_literal* rasqal_new_variable_literal (rasqal_variable *variable);
    rasqal_literal* rasqal_new_literal_from_literal
                                                (rasqal_literal *l);
    void        rasqal_free_literal             (rasqal_literal *l);
    rasqal_literal* rasqal_literal_as_node      (rasqal_literal *l);
    const unsigned char* rasqal_literal_as_string
                                                (rasqal_literal *l);
    const unsigned char* rasqal_literal_as_string_flags
                                                (rasqal_literal *l,
                                                 int flags,
                                                 int *error);
    rasqal_variable* rasqal_literal_as_variable (rasqal_literal *l);
    int         rasqal_literal_compare          (rasqal_literal *l1,
                                                 rasqal_literal *l2,
                                                 int flags,
                                                 int *error);
    int         rasqal_literal_equals           (rasqal_literal *l1,
                                                 rasqal_literal *l2);
    void        rasqal_literal_print            (rasqal_literal *l,
                                                 FILE *fh);
    void        rasqal_literal_print_type       (rasqal_literal *l,
                                                 FILE *fh);

## Description

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.

## Details

### rasqal_literal

    typedef struct rasqal_literal_s rasqal_literal;

Rasqal literal class.

rasqal_literal

### enum rasqal_literal_type

    typedef enum {
      /* internal */
      RASQAL_LITERAL_UNKNOWN,
      RASQAL_LITERAL_BLANK,
      RASQAL_LITERAL_URI,
      RASQAL_LITERAL_STRING,
      RASQAL_LITERAL_BOOLEAN,
      RASQAL_LITERAL_INTEGER,
      RASQAL_LITERAL_DOUBLE,
      /* deprecated */
      RASQAL_LITERAL_FLOATING = RASQAL_LITERAL_DOUBLE,
      RASQAL_LITERAL_FLOAT,
      RASQAL_LITERAL_DECIMAL,
      RASQAL_LITERAL_DATETIME,
      /* internal */
      RASQAL_LITERAL_FIRST_XSD = RASQAL_LITERAL_BOOLEAN,
      /* 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;

Types of literal.

The order in the enumeration is significant as it encodes the SPARQL term ordering conditions:

Blank Nodes << IRIS << RDF literals << typed literals

which coresponds to in enum values

BLANK << URI << STRING << (BOOLEAN | INTEGER | DOUBLE | FLOAT | DECIMAL | DATETIME) (RASQAL_LITERAL_FIRST_XSD ... RASQAL_LITERAL_LAST_XSD)

Not used (internal): PATTERN, QNAME, VARIABLE

See `rasqal_literal_compare()` when used with flags `RASQAL_COMPARE_XQUERY`

`RASQAL_LITERAL_UNKNOWN`

  Internal.

`RASQAL_LITERAL_BLANK`

  RDF blank node literal (SPARQL r:bNode)

`RASQAL_LITERAL_URI`

  RDF URI Literal (SPARQL r:URI)

`RASQAL_LITERAL_STRING`

  RDF Literal / xsd:string (SPARQL r:Literal)

`RASQAL_LITERAL_BOOLEAN`

  Boolean literal xsd:boolean.

`RASQAL_LITERAL_INTEGER`

  Integer literal xsd:integer.

`RASQAL_LITERAL_DOUBLE`

  Double floating point literal xsd:double.

`RASQAL_LITERAL_FLOATING`

  Deprecated `RASQAL_LITERAL_DOUBLE`.

`RASQAL_LITERAL_FLOAT`

  Floating point literal xsd:float.

`RASQAL_LITERAL_DECIMAL`

  Decimal integer xsd:decimal.

`RASQAL_LITERAL_DATETIME`

  Date/Time literal xsd:dateTime.

`RASQAL_LITERAL_FIRST_XSD`

  Internal.

`RASQAL_LITERAL_LAST_XSD`

  Internal.

`RASQAL_LITERAL_PATTERN`

  Pattern literal for a regex.

`RASQAL_LITERAL_QNAME`

  XML Qname literal.

`RASQAL_LITERAL_VARIABLE`

  Variable literal.

`RASQAL_LITERAL_LAST`

  Internal.

rasqal_literal_type

### rasqal_new_boolean_literal ()

    rasqal_literal* rasqal_new_boolean_literal  (int value);

Constructor - Create a new Rasqal boolean literal.

value :

  non-0 for true, 0 for false

Returns :

  New rasqal_literal or NULL on failure

rasqal_new_boolean_literal

### rasqal_new_decimal_literal ()

    rasqal_literal* rasqal_new_decimal_literal  (unsigned char *decimal);

Constructor - Create a new Rasqal decimal literal.

decimal :

  decimal literal

Returns :

  New rasqal_literal or NULL on failure

rasqal_new_decimal_literal

### rasqal_new_double_literal ()

    rasqal_literal* rasqal_new_double_literal   (double d);

Constructor - Create a new Rasqal double literal.

d :

  double literal

Returns :

  New rasqal_literal or NULL on failure

rasqal_new_double_literal

### rasqal_new_floating_literal ()

    rasqal_literal* rasqal_new_floating_literal (double f);

Deprecated: Use `rasqal_new_double_literal()`.

Constructor - Create a new Rasqal double literal.

f :

  floating literal

Returns :

  New rasqal_literal or NULL on failure

rasqal_new_floating_literal

### rasqal_new_integer_literal ()

    rasqal_literal* rasqal_new_integer_literal  (rasqal_literal_type type,
                                                 int integer);

Constructor - Create a new Rasqal integer literal.

The integer decimal number is turned into a rasqal integer literal and given a datatype of xsd:integer

type :

  Type of literal such as RASQAL_LITERAL_INTEGER or RASQAL_LITERAL_BOOLEAN

integer :

  int value

Returns :

  New rasqal_literal or NULL on failure

rasqal_new_integer_literal

### rasqal_new_pattern_literal ()

    rasqal_literal* rasqal_new_pattern_literal  (unsigned char *pattern,
                                                 const char *flags);

Constructor - Create a new Rasqal pattern literal.

The pattern and flags are input parameters and are stored in the literal, not copied. The set of flags recognised depends on the regex engine and the query language.

pattern :

  regex pattern

flags :

  regex flags

Returns :

  New rasqal_literal or NULL on failure

rasqal_new_pattern_literal

### rasqal_new_simple_literal ()

    rasqal_literal* rasqal_new_simple_literal   (rasqal_literal_type type,
                                                 unsigned char *string);

Constructor - Create a new Rasqal simple literal.

The string is an input parameter and is stored in the literal, not copied.

type :

  RASQAL_LITERAL_BLANK or RASQAL_LITERAL_BLANK_QNAME

string :

  the UTF-8 string value to store

Returns :

  New rasqal_literal or NULL on failure

rasqal_new_simple_literal

### rasqal_new_string_literal ()

    rasqal_literal* rasqal_new_string_literal   (unsigned char *string,
                                                 const char *language,
                                                 raptor_uri *datatype,
                                                 unsigned char *datatype_qname);

Constructor - Create a new Rasqal string literal.

All parameters are input parameters and if present are stored in the literal, not copied.

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.

If the string literal is datatyped and of certain types recognised it may be converted to a different literal type by rasqal_literal_string_to_native.

string :

  UTF-8 string lexical form

language :

  RDF language (xml:lang) (or NULL)

datatype :

  datatype URI (or NULL)

datatype_qname :

  datatype qname string (or NULL)

Returns :

  New rasqal_literal or NULL on failure

rasqal_new_string_literal

### rasqal_new_uri_literal ()

    rasqal_literal* rasqal_new_uri_literal      (raptor_uri *uri);

Constructor - Create a new Rasqal URI literal from a raptor URI.

The uri is an input parameter and is stored in the literal, not copied.

uri :

  raptor_uri uri

Returns :

  New rasqal_literal or NULL on failure

rasqal_new_uri_literal

### rasqal_new_variable_literal ()

    rasqal_literal* rasqal_new_variable_literal (rasqal_variable *variable);

Constructor - Create a new Rasqal variable literal.

variable is an input parameter and stored in the literal, not copied.

variable :

  rasqal_variable to use

Returns :

  New rasqal_literal or NULL on failure

rasqal_new_variable_literal

### rasqal_new_literal_from_literal ()

    rasqal_literal* rasqal_new_literal_from_literal
                                                (rasqal_literal *l);

Copy Constructor - create a new rasqal_literal object from an existing rasqal_literal object.

l :

  rasqal_literal object to copy

Returns :

  a new rasqal_literal object or NULL on failure

rasqal_new_literal_from_literal

### rasqal_free_literal ()

    void        rasqal_free_literal             (rasqal_literal *l);

Destructor - destroy an rasqal_literal object.

l :

  rasqal_literal object

rasqal_free_literal

### rasqal_literal_as_node ()

    rasqal_literal* rasqal_literal_as_node      (rasqal_literal *l);

Turn a literal into a new RDF string, URI or blank literal.

l :

  rasqal_literal object

Returns :

  the new rasqal_literal or NULL on failure

rasqal_literal_as_node

### rasqal_literal_as_string ()

    const unsigned char* rasqal_literal_as_string
                                                (rasqal_literal *l);

Return the string format of a literal.

l :

  rasqal_literal object

Returns :

  pointer to a shared string format of the literal.

rasqal_literal_as_string

### rasqal_literal_as_string_flags ()

    const unsigned char* rasqal_literal_as_string_flags
                                                (rasqal_literal *l,
                                                 int flags,
                                                 int *error);

Return the string format of a literal according to flags.

flag bits affects conversion: RASQAL_COMPARE_XQUERY: use XQuery conversion rules

If error is not NULL, *error is set to non-0 on error

l :

  rasqal_literal object

flags :

  comparison flags

error :

  pointer to error

Returns :

  pointer to a shared string format of the literal.

rasqal_literal_as_string_flags

### rasqal_literal_as_variable ()

    rasqal_variable* rasqal_literal_as_variable (rasqal_literal *l);

Get the variable inside a literal.

l :

  rasqal_literal object

Returns :

  the rasqal_variable or NULL if the literal is not a variable

rasqal_literal_as_variable

### rasqal_literal_compare ()

    int         rasqal_literal_compare          (rasqal_literal *l1,
                                                 rasqal_literal *l2,
                                                 int flags,
                                                 int *error);

Compare two literals with type promotion.

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).

The comparison returned is as for strcmp, first before second returns <0. equal returns 0, and first after second returns >0. For URIs, the string value is used for the comparsion.

flag bits affects comparisons: RASQAL_COMPARE_NOCASE: use case independent string comparisons RASQAL_COMPARE_XQUERY: use XQuery comparison and type promotion rules

If error is not NULL, *error is set to non-0 on error

l1 :

  rasqal_literal first literal

l2 :

  rasqal_literal second literal

flags :

  comparison flags

error :

  pointer to error

Returns :

  <0, 0, or >0 as described above.

rasqal_literal_compare

### rasqal_literal_equals ()

    int         rasqal_literal_equals           (rasqal_literal *l1,
                                                 rasqal_literal *l2);

Compare two literals with no type promotion.

If the l2 data literal value is a boolean, it will match the string "true" or "false" in the first literal l1.

l1 :

  rasqal_literal literal

l2 :

  rasqal_literal data literal

Returns :

  non-0 if equal

rasqal_literal_equals

### rasqal_literal_print ()

    void        rasqal_literal_print            (rasqal_literal *l,
                                                 FILE *fh);

Print a Rasqal literal in a debug format.

The print debug format may change in any release.

l :

  the rasqal_literal object

fh :

  the FILE* handle to print to

rasqal_literal_print

### rasqal_literal_print_type ()

    void        rasqal_literal_print_type       (rasqal_literal *l,
                                                 FILE *fh);

Print a string form for a rasqal literal type.

l :

  the rasqal_literal object

fh :

  the FILE* handle to print to

rasqal_literal_print_type