section-triples: Raptor RDF Syntax Library Manual

## section-triples section-triples |

## Functions

raptor_term * | raptor_new_term_from_blank ()
raptor_term * | raptor_new_term_from_counted_blank ()
raptor_term * | raptor_new_term_from_literal ()
raptor_term * | raptor_new_term_from_counted_literal ()
raptor_term * | raptor_new_term_from_counted_uri_string ()
raptor_term * | raptor_new_term_from_uri ()
raptor_term * | raptor_new_term_from_uri_string ()
raptor_term * | raptor_new_term_from_counted_string ()
raptor_term * | raptor_term_copy ()
int | raptor_term_compare ()
int | raptor_term_equals ()
void | raptor_free_term ()
unsigned char * | raptor_term_to_counted_string ()
unsigned char * | raptor_term_to_string ()
int | raptor_term_ntriples_write ()
unsigned char * | raptor_term_to_turtle_counted_string ()
unsigned char * | raptor_term_to_turtle_string ()
int | raptor_term_turtle_write ()
raptor_statement * | raptor_new_statement ()
raptor_statement * | raptor_new_statement_from_nodes ()
void | raptor_free_statement ()
raptor_statement * | raptor_statement_copy ()
int | raptor_statement_compare ()
int | raptor_statement_equals ()
void | raptor_statement_init ()
void | raptor_statement_clear ()
int | raptor_statement_print ()
int | raptor_statement_print_as_ntriples ()
int | raptor_statement_ntriples_write ()

## Types and Values

enum | raptor_term_type
| raptor_term
| raptor_term_value
| raptor_term_blank_value
| raptor_term_literal_value
| raptor_statement

## Description

## Functions

### raptor_new_term_from_blank ()

    raptor_term *
    raptor_new_term_from_blank (raptor_world *world,
                                const unsigned char *blank);

Constructor - create a new blank node statement term from a UTF-8 encoded blank node ID

Takes a copy of the passed in `blank`

If `blank` is NULL or an empty string, creates a new internal identifier and uses it. This will use the handler set with `raptor_world_set_generate_bnodeid_parameters()`

#### Parameters

world | raptor world |
blank | UTF-8 encoded blank node identifier (or NULL) |

#### Returns

new term or NULL on failure

### raptor_new_term_from_counted_blank ()

    raptor_term *
    raptor_new_term_from_counted_blank (raptor_world *world,
                                        const unsigned char *blank,
                                        size_t length);

Constructor - create a new blank node statement term from a counted UTF-8 encoded blank node ID

Takes a copy of the passed in `blank`

If `blank` is NULL, creates a new internal identifier and uses it. This will use the handler set with `raptor_world_set_generate_bnodeid_parameters()`

Note: The `blank` need not be NULL terminated - a NULL will be added to the copied string used.

#### Parameters

world | raptor world |
blank | UTF-8 encoded blank node identifier (or NULL) |
length | length of identifier (or 0) |

#### Returns

new term or NULL on failure

### raptor_new_term_from_literal ()

    raptor_term *
    raptor_new_term_from_literal (raptor_world *world,
                                  const unsigned char *literal,
                                  raptor_uri *datatype,
                                  const unsigned char *language);

Constructor - create a new literal statement term

Takes copies of the passed in `literal` , `datatype` , `language`

Only one of `language` or `datatype` may be given. If both are given, NULL is returned. If `language` is the empty string, it is the equivalent to NULL.

#### Parameters

world | raptor world |
literal | UTF-8 encoded literal string (or NULL for empty literal) |
datatype | literal datatype URI (or NULL) |
language | literal language (or NULL) |

#### Returns

new term or NULL on failure

### raptor_new_term_from_counted_literal ()

    raptor_term *
    raptor_new_term_from_counted_literal (raptor_world *world,
                                          const unsigned char *literal,
                                          size_t literal_len,
                                          raptor_uri *datatype,
                                          const unsigned char *language,
                                          unsigned char language_len);

Constructor - create a new literal statement term from a counted UTF-8 encoded literal string

Takes copies of the passed in `literal` , `datatype` , `language`

Only one of `language` or `datatype` may be given. If both are given, NULL is returned. If `language` is the empty string, it is the equivalent to NULL.

Note: The `literal` need not be NULL terminated - a NULL will be added to the copied string used.

#### Parameters

world | raptor world |
literal | UTF-8 encoded literal string (or NULL for empty literal) |
literal_len | length of literal |
datatype | literal datatype URI (or NULL) |
language | literal language (or NULL for no language) |
language_len | literal language length |

#### Returns

new term or NULL on failure

### raptor_new_term_from_counted_uri_string ()

    raptor_term *
    raptor_new_term_from_counted_uri_string
                                   (raptor_world *world,
                                    const char *uri_string,
                                    size_t length);

Constructor - create a new URI statement term from a UTF-8 encoded Unicode string

Note: The `uri_string` need not be NULL terminated - a NULL will be added to the copied string used.

#### Parameters

world | raptor world |
uri_string | UTF-8 encoded URI string. |
length | length of URI string |

#### Returns

new term or NULL on failure

### raptor_new_term_from_uri ()

    raptor_term *
    raptor_new_term_from_uri (raptor_world *world,
                              raptor_uri *uri);

Constructor - create a new URI statement term

Takes a copy (reference) of the passed in `uri`

#### Parameters

world | raptor world |
uri | uri |

#### Returns

new term or NULL on failure

### raptor_new_term_from_uri_string ()

    raptor_term *
    raptor_new_term_from_uri_string (raptor_world *world,
                                     const char *uri_string);

Constructor - create a new URI statement term from a UTF-8 encoded Unicode string

#### Parameters

world | raptor world |
uri_string | UTF-8 encoded URI string. |

#### Returns

new term or NULL on failure

### raptor_new_term_from_counted_string ()

    raptor_term *
    raptor_new_term_from_counted_string (raptor_world *world,
                                         unsigned char *string,
                                         size_t length);

Constructor - create a new term from a Turtle / N-Triples format string in UTF-8

See also `raptor_term_to_counted_string()` and `raptor_term_to_string()`

#### Parameters

world | raptor world |
string | N-Triples format string (UTF-8) |
length | length of `string` (or 0) |

#### Returns

new term or NULL on failure

### raptor_term_copy ()

    raptor_term *
    raptor_term_copy (raptor_term *term);

Copy constructor - get a copy of a statement term

#### Parameters

term | raptor term |

#### Returns

new term object or NULL on failure

### raptor_term_compare ()

    int
    raptor_term_compare (const raptor_term *t1,
                         const raptor_term *t2);

Compare a pair of raptor_term

If types are different, the raptor_term_type order is used.

Resource and datatype URIs are compared with `raptor_uri_compare()`, blank nodes and literals with `strcmp()`. If one literal has no language, it is earlier than one with a language. If one literal has no datatype, it is earlier than one with a datatype.

#### Parameters

t1 | first term |
t2 | second term |

#### Returns

<0 if t1 is before t2, 0 if equal, >0 if t1 is after t2

### raptor_term_equals ()

    int
    raptor_term_equals (raptor_term *t1,
                        raptor_term *t2);

Compare a pair of raptor_term for equality

#### Parameters

t1 | first term |
t2 | second term |

#### Returns

non-0 if the terms are equal

### raptor_free_term ()

    void
    raptor_free_term (raptor_term *term);

Destructor - destroy a raptor_term object.

#### Parameters

term | raptor_term object |

### raptor_term_to_counted_string ()

    unsigned char *
    raptor_term_to_counted_string (raptor_term *term,
                                   size_t *len_p);

Turns a raptor term into a N-Triples format counted string.

Turns the given `term` into an N-Triples escaped string using all the escapes as defined in http://www.w3.org/TR/rdf-testcases/ntriples

This function uses `raptor_term_ntriples_write()` to write to an raptor_iostream which is the prefered way to write formatted output.

See also `raptor_new_term_from_counted_string()` to reverse this.

See also `raptor_term_to_turtle_string()` to write as Turtle which will include Turtle syntax such as 'true' for booleans and """quoting"""

#### Parameters

term | raptor_term |
len_p | Pointer to location to store length of new string (if not NULL) |

#### Returns

the new string or NULL on failure. The length of the new string is returned in *`len_p` if len_p is not NULL.

### raptor_term_to_string ()

    unsigned char *
    raptor_term_to_string (raptor_term *term);

Turns a raptor term into a N-Triples format string.

Turns the given `term` into an N-Triples escaped string using all the escapes as defined in http://www.w3.org/TR/rdf-testcases/ntriples

See also `raptor_new_term_from_counted_string()` to reverse this.

See also `raptor_term_to_turtle_string()` to write as Turtle which will include Turtle syntax such as 'true' for booleans and """quoting"""

#### Parameters

term | raptor_term |

#### Returns

the new string or NULL on failure.

### raptor_term_ntriples_write ()

    int
    raptor_term_ntriples_write (const raptor_term *term,
                                raptor_iostream *iostr);

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

Write a raptor_term formatted in N-Triples format to a raptor_iostream

`Deprecated` : Use `raptor_term_escaped_write()` that allows configuring format detail flags.

#### Parameters

term | term to write |
iostr | raptor iostream |

#### Returns

non-0 on failure

### raptor_term_to_turtle_counted_string ()

    unsigned char *
    raptor_term_to_turtle_counted_string (raptor_term *term,
                                          raptor_namespace_stack *nstack,
                                          raptor_uri *base_uri,
                                          size_t *len_p);

Convert raptor_term to a string. Caller has responsibility to free the string.

Note: This creates and destroys several internal objects for each call so for more efficient writing, create a turtle serializer.

See also `raptor_term_to_counted_string()` which writes in simpler N-Triples with no Turtle abbreviated forms, and is quicker.

#### Parameters

term | term |
nstack | namespace stack |
base_uri | base URI |
len_p | Pointer to location to store length of new string (if not NULL) |

#### Returns

the new string or NULL on failure. The length of the new string is returned in *`len_p` if len_p is not NULL.

### raptor_term_to_turtle_string ()

    unsigned char *
    raptor_term_to_turtle_string (raptor_term *term,
                                  raptor_namespace_stack *nstack,
                                  raptor_uri *base_uri);

Convert raptor_term to a string. Caller has responsibility to free the string.

See also `raptor_term_to_counted_string()` which writes in simpler N-Triples with no Turtle abbreviated forms, and is quicker.

#### Parameters

term | term |
nstack | namespace stack |
base_uri | base URI |

#### Returns

the new string or NULL on failure.

### raptor_term_turtle_write ()

    int
    raptor_term_turtle_write (raptor_iostream *iostr,
                              raptor_term *term,
                              raptor_namespace_stack *nstack,
                              raptor_uri *base_uri);

Write raptor_term to a stream in turtle syntax (using QNames).

Note: This creates and destroys several internal objects for each call so for more efficient writing, create a turtle serializer.

#### Parameters

iostr | iostream for writing |
term | term |
nstack | namespace stack |
base_uri | base URI |

#### Returns

non-0 on failure

### raptor_new_statement ()

    raptor_statement *
    raptor_new_statement (raptor_world *world);

Constructor - create a new raptor_statement.

#### Parameters

world | raptor world |

#### Returns

new raptor statement or NULL on failure

### raptor_new_statement_from_nodes ()

    raptor_statement *
    raptor_new_statement_from_nodes (raptor_world *world,
                                     raptor_term *subject,
                                     raptor_term *predicate,
                                     raptor_term *object,
                                     raptor_term *graph);

Constructor - create a new raptor_statement from a set of terms

The `subject` , `predicate` , `object` and `graph` become owned by the statement.

#### Parameters

world | raptor world |
subject | subject term (or NULL) |
predicate | predicate term (or NULL) |
object | object term (or NULL) |
graph | graph name term (or NULL) |

#### Returns

new raptor statement or NULL on failure

### raptor_free_statement ()

    void
    raptor_free_statement (raptor_statement *statement);

Destructor

#### Parameters

statement | statement |

### raptor_statement_copy ()

    raptor_statement *
    raptor_statement_copy (raptor_statement *statement);

Copy a raptor_statement.

#### Parameters

statement | statement to copy |

#### Returns

a new raptor_statement or NULL on error

### raptor_statement_compare ()

    int
    raptor_statement_compare (const raptor_statement *s1,
                              const raptor_statement *s2);

Compare a pair of raptor_statement

Uses `raptor_term_compare()` to check ordering between subjects, predicates and objects of statements.

#### Parameters

s1 | first statement |
s2 | second statement |

#### Returns

<0 if s1 is before s2, 0 if equal, >0 if s1 is after s2

### raptor_statement_equals ()

    int
    raptor_statement_equals (const raptor_statement *s1,
                             const raptor_statement *s2);

Compare a pair of raptor_statement for equality

#### Parameters

s1 | first statement |
s2 | second statement |

#### Returns

non-0 if statements are equal

### raptor_statement_init ()

    void
    raptor_statement_init (raptor_statement *statement,
                           raptor_world *world);

Initialize a static raptor_statement.

#### Parameters

statement | statement to initialize |
world | raptor world |

### raptor_statement_clear ()

    void
    raptor_statement_clear (raptor_statement *statement);

Empty a raptor_statement of terms.

#### Parameters

statement | raptor_statement object |

### raptor_statement_print ()

    int
    raptor_statement_print (const raptor_statement *statement,
                            FILE *stream);

Print a raptor_statement to a stream.

#### Parameters

statement | raptor_statement object to print |
stream | FILE* stream |

#### Returns

non-0 on failure

### raptor_statement_print_as_ntriples ()

    int
    raptor_statement_print_as_ntriples (const raptor_statement *statement,
                                        FILE *stream);

Print a raptor_statement in N-Triples form.

#### Parameters

statement | raptor_statement to print |
stream | FILE* stream |

#### Returns

non-0 on failure

### raptor_statement_ntriples_write ()

    int
    raptor_statement_ntriples_write (const raptor_statement *statement,
                                     raptor_iostream *iostr,
                                     int write_graph_term);

Write a raptor_statement formatted in N-Triples or N-Quads format to a raptor_iostream

#### Parameters

statement | statement to write |
iostr | raptor iostream |
write_graph_term | flag to write graph term if present |

#### Returns

non-0 on failure

## Types and Values

### enum raptor_term_type

Type of term in a raptor_statement

Node type 3 is unused but exists to preserve numeric compatibility with librdf_node_type values.

#### Members

RAPTOR_TERM_TYPE_UNKNOWN | Internal |
RAPTOR_TERM_TYPE_URI | RDF URI |
RAPTOR_TERM_TYPE_LITERAL | RDF literal |
RAPTOR_TERM_TYPE_BLANK | RDF blank node |

### raptor_term

    typedef struct {
      raptor_world* world;

      int usage;

      raptor_term_type type;

      raptor_term_value value;
    } raptor_term;

An RDF statement term

#### Members

raptor_world *`world`; | world |
int `usage`; | usage reference count (if >0) |
raptor_term_type `type`; | term type |
raptor_term_value `value`; | term values per type |

### raptor_term_value

Term value - this typedef exists solely for use in raptor_term

#### Members

raptor_uri *`uri`; | uri value when term type is RAPTOR_TERM_TYPE_URI |
raptor_term_literal_value `literal`; | literal value when term type is RAPTOR_TERM_TYPE_LITERAL |
raptor_term_blank_value `blank`; | blank value when term type is RAPTOR_TERM_TYPE_BLANK |

### raptor_term_blank_value

    typedef struct {
      unsigned char *string;
      unsigned int string_len;
    } raptor_term_blank_value;

Blank term value - this typedef exists solely for use in raptor_term

#### Members

unsigned char *`string`; | literal string |
unsigned int `string_len`; | length of string |

### raptor_term_literal_value

    typedef struct {
      unsigned char *string;
      unsigned int string_len;

      raptor_uri *datatype;

      unsigned char *language;
      unsigned char language_len;
    } raptor_term_literal_value;

Literal term value - this typedef exists solely for use in raptor_term

Either `datatype` or `language` may be non-NULL but not both.

#### Members

unsigned char *`string`; | literal string |
unsigned int `string_len`; | length of string |
raptor_uri *`datatype`; | datatype URI (or NULL) |
unsigned char *`language`; | literal language (or NULL) |
unsigned char `language_len`; | length of language |

### raptor_statement

    typedef struct {
      raptor_world* world;
      int usage;
      raptor_term* subject;
      raptor_term* predicate;
      raptor_term* object;
      raptor_term* graph;
    } raptor_statement;

An RDF triple with optional graph name (quad)

See raptor_term for a description of how the fields may be used. As returned by a parser statement_handler.

#### Members

raptor_world *`world`; | world pointer |
int `usage`; | usage count |
raptor_term *`subject`; | statement subject |
raptor_term *`predicate`; | statement predicate |
raptor_term *`object`; | statement object |
raptor_term *`graph`; | statement graph name (or NULL if not present) |