Literal

## Literal Literal — RDF literals and RDF query-specific literals. |

## Synopsis

    typedef             rasqal_literal;
    enum                rasqal_literal_type;
    rasqal_literal*     rasqal_new_typed_literal            (rasqal_world *world,
                                                             rasqal_literal_type type,
                                                             unsigned char *string);
    rasqal_literal*     rasqal_new_boolean_literal          (rasqal_world *world,
                                                             int value);
    rasqal_literal*     rasqal_new_decimal_literal          (rasqal_world *world,
                                                             unsigned char *string);
    rasqal_literal*     rasqal_new_decimal_literal_from_decimal
                                                            (rasqal_world *world,
                                                             unsigned char *string,
                                                             rasqal_xsd_decimal *decimal);
    rasqal_literal*     rasqal_new_double_literal           (rasqal_world *world,
                                                             double d);
    rasqal_literal*     rasqal_new_float_literal            (rasqal_world *world,
                                                             float f);
    rasqal_literal*     rasqal_new_integer_literal          (rasqal_world *world,
                                                             rasqal_literal_type type,
                                                             int integer);
    rasqal_literal*     rasqal_new_pattern_literal          (rasqal_world *world,
                                                             unsigned char *pattern,
                                                             const char *flags);
    rasqal_literal*     rasqal_new_simple_literal           (rasqal_world *world,
                                                             rasqal_literal_type type,
                                                             unsigned char *string);
    rasqal_literal*     rasqal_new_string_literal           (rasqal_world *world,
                                                             unsigned char *string,
                                                             const char *language,
                                                             raptor_uri *datatype,
                                                             unsigned char *datatype_qname);
    rasqal_literal*     rasqal_new_uri_literal              (rasqal_world *world,
                                                             raptor_uri *uri);
    rasqal_literal*     rasqal_new_variable_literal         (rasqal_world *world,
                                                             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);
    raptor_uri*         rasqal_literal_datatype             (rasqal_literal *l);
    int                 rasqal_literal_equals               (rasqal_literal *l1,
                                                             rasqal_literal *l2);
    rasqal_literal_type  rasqal_literal_get_rdf_term_type   (rasqal_literal *l);
    int                 rasqal_literal_is_rdf_literal       (rasqal_literal *l);
    int                 rasqal_literal_print                (rasqal_literal *l,
                                                             FILE *fh);
    void                rasqal_literal_print_type           (rasqal_literal *l,
                                                             FILE *fh);
    int                 rasqal_literal_same_term            (rasqal_literal *l1,
                                                             rasqal_literal *l2);
    rasqal_literal*     rasqal_literal_value                (rasqal_literal *l);

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

### enum rasqal_literal_type

    typedef enum {
      /* internal */
      RASQAL_LITERAL_UNKNOWN,
      RASQAL_LITERAL_BLANK,
      RASQAL_LITERAL_URI,
      RASQAL_LITERAL_STRING,
      RASQAL_LITERAL_XSD_STRING,
      RASQAL_LITERAL_BOOLEAN,
      RASQAL_LITERAL_INTEGER,
      RASQAL_LITERAL_FLOAT,
      RASQAL_LITERAL_DOUBLE,
      RASQAL_LITERAL_DECIMAL,
      RASQAL_LITERAL_DATETIME,
      /* internal */
      RASQAL_LITERAL_FIRST_XSD = RASQAL_LITERAL_XSD_STRING,
      /* internal */
      RASQAL_LITERAL_LAST_XSD = RASQAL_LITERAL_DATETIME,
      RASQAL_LITERAL_UDT,
      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 | XSD_STRING)

(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 Plain Literal - no datatype (SPARQL r:Literal)
`RASQAL_LITERAL_XSD_STRING` | String xsd:string
`RASQAL_LITERAL_BOOLEAN` | Boolean literal xsd:boolean.
`RASQAL_LITERAL_INTEGER` | Integer literal xsd:integer.
`RASQAL_LITERAL_FLOAT` | Floating point literal xsd:float.
`RASQAL_LITERAL_DOUBLE` | Double floating point literal xsd:double.
`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_UDT` | User defined typed literal with unknown datatype URI
`RASQAL_LITERAL_PATTERN` | Pattern literal for a regex.
`RASQAL_LITERAL_QNAME` | XML Qname literal.
`RASQAL_LITERAL_VARIABLE` | Variable literal.
`RASQAL_LITERAL_LAST` | Internal.

### rasqal_new_typed_literal ()

    rasqal_literal*     rasqal_new_typed_literal            (rasqal_world *world,
                                                             rasqal_literal_type type,
                                                             unsigned char *string);

Constructor - Create a new Rasqal integer literal from a string

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

`world` : | rasqal world object
`type` : | Type of literal such as RASQAL_LITERAL_INTEGER or RASQAL_LITERAL_BOOLEAN
`string` : | lexical form - ownership not taken
Returns : | New rasqal_literal or NULL on failure

### rasqal_new_boolean_literal ()

    rasqal_literal*     rasqal_new_boolean_literal          (rasqal_world *world,
                                                             int value);

Constructor - Create a new Rasqal boolean literal.

`world` : | rasqal world object
`value` : | non-0 for true, 0 for false
Returns : | New rasqal_literal or NULL on failure

### rasqal_new_decimal_literal ()

    rasqal_literal*     rasqal_new_decimal_literal          (rasqal_world *world,
                                                             unsigned char *string);

Constructor - Create a new Rasqal decimal literal.

`world` : | rasqal world object
`string` : | decimal literal
Returns : | New rasqal_literal or NULL on failure

### rasqal_new_decimal_literal_from_decimal ()

    rasqal_literal*     rasqal_new_decimal_literal_from_decimal
                                                            (rasqal_world *world,
                                                             unsigned char *string,
                                                             rasqal_xsd_decimal *decimal);

Constructor - Create a new Rasqal decimal literal.

`world` : | rasqal world object
`string` : | decimal literal string
`decimal` : | rasqal XSD Decimal
Returns : | New rasqal_literal or NULL on failure

### rasqal_new_double_literal ()

    rasqal_literal*     rasqal_new_double_literal           (rasqal_world *world,
                                                             double d);

Constructor - Create a new Rasqal double literal.

`world` : | rasqal world object
`d` : | double literal
Returns : | New rasqal_literal or NULL on failure

### rasqal_new_float_literal ()

    rasqal_literal*     rasqal_new_float_literal            (rasqal_world *world,
                                                             float f);

Constructor - Create a new Rasqal float literal.

`world` : | rasqal world object
`f` : | float literal
Returns : | New rasqal_literal or NULL on failure

### rasqal_new_integer_literal ()

    rasqal_literal*     rasqal_new_integer_literal          (rasqal_world *world,
                                                             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

`world` : | rasqal world object
`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_pattern_literal ()

    rasqal_literal*     rasqal_new_pattern_literal          (rasqal_world *world,
                                                             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. They are freed also on failure. The set of flags recognised depends on the regex library and the query language.

`world` : | rasqal world object
`pattern` : | regex pattern
`flags` : | regex flags
Returns : | New rasqal_literal or NULL on failure

### rasqal_new_simple_literal ()

    rasqal_literal*     rasqal_new_simple_literal           (rasqal_world *world,
                                                             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. It is freed also on failure.

`world` : | rasqal world object
`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_string_literal ()

    rasqal_literal*     rasqal_new_string_literal           (rasqal_world *world,
                                                             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. They are freed also on failure.

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()`

`world` : | rasqal world object
`string` : | UTF-8 string lexical form
`language` : | RDF language (xml:lang) (or NULL)
`datatype` : | datatype URI (or NULL for plain literal)
`datatype_qname` : | datatype qname string (or NULL for plain literal)
Returns : | New rasqal_literal or NULL on failure

### rasqal_new_uri_literal ()

    rasqal_literal*     rasqal_new_uri_literal              (rasqal_world *world,
                                                             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. The uri is freed also on failure.

`world` : | rasqal world object
`uri` : | raptor_uri uri
Returns : | New rasqal_literal or NULL on failure

### rasqal_new_variable_literal ()

    rasqal_literal*     rasqal_new_variable_literal         (rasqal_world *world,
                                                             rasqal_variable *variable);

Constructor - Create a new Rasqal variable literal.

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

`world` : | rasqal_world object
`variable` : | rasqal_variable to use
Returns : | New rasqal_literal or NULL on failure

### 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 or NULL
Returns : | a new rasqal_literal object or NULL if `l` was NULL.

### rasqal_free_literal ()

    void                rasqal_free_literal                 (rasqal_literal *l);

Destructor - destroy an rasqal_literal object.

`l` : | rasqal_literal object

### 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 or if the literal was an unbound variable.

### 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_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_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_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 RASQAL_COMPARE_RDF: use RDF term comparison RASQAL_COMPARE_URI: allow comparison of URIs (typically for SPARQL ORDER)

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_datatype ()

    raptor_uri*         rasqal_literal_datatype             (rasqal_literal *l);

Get the datatype URI of a literal

`l` : | rasqal_literal object
Returns : | shared pointer to raptor_uri of datatype or NULL on failure or no value

### 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_get_rdf_term_type ()

    rasqal_literal_type  rasqal_literal_get_rdf_term_type   (rasqal_literal *l);

Get the RDF term type of a literal

An RDF term can be one of three choices: 1. URI: RASQAL_LITERAL_URI 2. literal: RASQAL_LITERAL_STRING 3. blank node: RASQAL_LITERAL_BLANK

Other non RDF-term cases include: NULL pointer, invalid literal, unknown type, a variable or other special cases (such as XML QName or Regex pattern) which all turn into RASQAL_LITERAL_UNKNOWN

`l` : | literal
Returns : | type or RASQAL_LITERAL_UNKNOWN if cannot be an RDF term

### rasqal_literal_is_rdf_literal ()

    int                 rasqal_literal_is_rdf_literal       (rasqal_literal *l);

Check if a literal is any RDF term literal - plain or typed literal

`l` : | rasqal_literal literal
Returns : | non-0 if the value is an RDF term literal

### rasqal_literal_print ()

    int                 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
Returns : | non-0 on failure

### 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_same_term ()

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

Check if literals are same term (URI, literal, blank)

`l1` : | rasqal_literal literal
`l2` : | rasqal_literal data literal
Returns : | non-0 if same

### rasqal_literal_value ()

    rasqal_literal*     rasqal_literal_value                (rasqal_literal *l);

Get the literal value looking up any variables needed

`l` : | rasqal_literal object
Returns : | literal value or NULL if has no value