section-literal

section-literal

Functions

rasqal_literal * rasqal_new_typed_literal ()
rasqal_literal * rasqal_new_boolean_literal ()
rasqal_literal * rasqal_new_datetime_literal_from_datetime ()
rasqal_literal * rasqal_new_decimal_literal ()
rasqal_literal * rasqal_new_decimal_literal_from_decimal ()
rasqal_literal * rasqal_new_double_literal ()
rasqal_literal * rasqal_new_float_literal ()
rasqal_literal * rasqal_new_floating_literal ()
rasqal_literal * rasqal_new_integer_literal ()
rasqal_literal * rasqal_new_numeric_literal_from_long ()
rasqal_literal * rasqal_new_pattern_literal ()
rasqal_literal * rasqal_new_simple_literal ()
rasqal_literal * rasqal_new_string_literal ()
rasqal_literal * rasqal_new_uri_literal ()
rasqal_literal * rasqal_new_variable_literal ()
rasqal_literal * rasqal_new_literal_from_literal ()
void rasqal_free_literal ()
rasqal_literal * rasqal_literal_as_node ()
const unsigned char * rasqal_literal_as_counted_string ()
const unsigned char * rasqal_literal_as_string ()
const unsigned char * rasqal_literal_as_string_flags ()
rasqal_variable * rasqal_literal_as_variable ()
int rasqal_literal_compare ()
raptor_uri * rasqal_literal_datatype ()
int rasqal_literal_equals ()
char * rasqal_literal_get_language ()
rasqal_literal_type rasqal_literal_get_rdf_term_type ()
rasqal_literal_type rasqal_literal_get_type ()
int rasqal_literal_is_rdf_literal ()
int rasqal_literal_print ()
void rasqal_literal_print_type ()
const char * rasqal_literal_type_label ()
int rasqal_literal_same_term ()
rasqal_literal * rasqal_literal_value ()

Types and Values

Description

Functions

rasqal_new_typed_literal ()

rasqal_literal *
rasqal_new_typed_literal (rasqal_world *world,
                          rasqal_literal_type type,
                          const 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

Parameters

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.

Parameters

world

rasqal world object

 

value

non-0 for true, 0 for false

 

Returns

New rasqal_literal or NULL on failure


rasqal_new_datetime_literal_from_datetime ()

rasqal_literal *
rasqal_new_datetime_literal_from_datetime
                               (rasqal_world *world,
                                rasqal_xsd_datetime *dt);

Constructor - Create a new Rasqal datetime literal from an existing datetime.

Takes ownership of dt

Parameters

world

rasqal world object

 

dt

rasqal XSD Datetime

 

Returns

New rasqal_literal or NULL on failure


rasqal_new_decimal_literal ()

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

Constructor - Create a new Rasqal decimal literal.

Parameters

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,
                                const char *string,
                                rasqal_xsd_decimal *decimal);

Constructor - Create a new Rasqal decimal literal.

Parameters

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.

Parameters

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

rasqal_new_float_literal is deprecated and should not be used in newly-written code.

Constructor - Create a new Rasqal float literal.

Deprecated : Use rasqal_new_floating_literal() with type RASQAL_LITERAL_FLOAT and double value.

Parameters

world

rasqal world object

 

f

float literal

 

Returns

New rasqal_literal or NULL on failure


rasqal_new_floating_literal ()

rasqal_literal *
rasqal_new_floating_literal (rasqal_world *world,
                             rasqal_literal_type type,
                             double d);

Constructor - Create a new Rasqal float literal from a double.

Parameters

world

rasqal world object

 

type

type - RASQAL_LITERAL_FLOAT or RASQAL_LITERAL_DOUBLE

 

d

floating literal (double)

 

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

Parameters

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

rasqal_literal *
rasqal_new_numeric_literal_from_long (rasqal_world *world,
                                      rasqal_literal_type type,
                                      long value Param3);

Constructor - Create a new Rasqal numeric literal from a long.

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

Parameters

world

rasqal world object

 

type

Type of literal such as RASQAL_LITERAL_INTEGER or RASQAL_LITERAL_BOOLEAN

 

value

long value

 

Returns

New rasqal_literal or NULL on failure


rasqal_new_pattern_literal ()

rasqal_literal *
rasqal_new_pattern_literal (rasqal_world *world,
                            const 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.

Parameters

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,
                           const 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.

Parameters

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,
                           const char *string,
                           const char *language,
                           raptor_uri *datatype,
                           const 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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

l

rasqal_literal object

 

Returns

the new rasqal_literal or NULL on failure or if the literal was an unbound variable.


rasqal_literal_as_counted_string ()

const unsigned char *
rasqal_literal_as_counted_string (rasqal_literal *l,
                                  size_t *len_p,
                                  int flags,
                                  int *error_p);

Return a counted 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

Parameters

l

rasqal_literal object

 

len_p

pointer to store length of string (or NULL)

 

flags

comparison flags

 

error_p

pointer to error

 

Returns

pointer to a shared string format of the literal.


rasqal_literal_as_string ()

const unsigned char *
rasqal_literal_as_string (rasqal_literal *l);

Return the string format of a literal.

Parameters

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_p);

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

Parameters

l

rasqal_literal object

 

flags

comparison flags

 

error_p

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.

Parameters

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_p);

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

Parameters

l1

rasqal_literal first literal

 

l2

rasqal_literal second literal

 

flags

comparison flags

 

error_p

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

Parameters

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.

Parameters

l1

rasqal_literal literal

 

l2

rasqal_literal data literal

 

Returns

non-0 if equal


rasqal_literal_get_language ()

char *
rasqal_literal_get_language (rasqal_literal *l);

Get the language of a literal (if set)

Parameters

l

literal

 

Returns

the literal language or NULL


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

Parameters

l

literal

 

Returns

type or RASQAL_LITERAL_UNKNOWN if cannot be an RDF term


rasqal_literal_get_type ()

rasqal_literal_type
rasqal_literal_get_type (rasqal_literal *l);

Get the type of a literal

Parameters

l

literal

 

Returns

the rasqal literal type or RASQAL_LITERAL_UNKNOWN if l is NULL


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

Parameters

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.

Parameters

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.

Parameters

l

the rasqal_literal object

 

fh

the FILE* handle to print to

 

rasqal_literal_type_label ()

const char *
rasqal_literal_type_label (rasqal_literal_type type);

Get a label for the rasqal literal type

Parameters

type

the rasqal_literal_type object

 

Returns

the label (shared string) or NULL if type is out of range or unknown


rasqal_literal_same_term ()

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

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

Parameters

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

Parameters

l

rasqal_literal object

 

Returns

literal value or NULL if has no value

Types and Values

rasqal_literal

typedef struct rasqal_literal_s rasqal_literal;

Rasqal literal class.


enum 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

Members

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_INTEGER_SUBTYPE

Internal.

 

RASQAL_LITERAL_DATE

Date literal xsd:date.

 

RASQAL_LITERAL_LAST

Internal.