Triples

## Triples Triples — RDF Triples |

## Synopsis

    enum                raptor_term_type;
                        raptor_term;
                        raptor_term_value;
                        raptor_term_blank_value;
                        raptor_term_literal_value;
    raptor_term *       raptor_new_term_from_blank          (raptor_world *world,
                                                             const unsigned char *blank);
    raptor_term *       raptor_new_term_from_counted_blank  (raptor_world *world,
                                                             const unsigned char *blank,
                                                             size_t length);
    raptor_term *       raptor_new_term_from_literal        (raptor_world *world,
                                                             const unsigned char *literal,
                                                             raptor_uri *datatype,
                                                             const unsigned char *language);
    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);
    raptor_term *       raptor_new_term_from_counted_uri_string
                                                            (raptor_world *world,
                                                             const unsigned char *uri_string,
                                                             size_t length);
    raptor_term *       raptor_new_term_from_uri            (raptor_world *world,
                                                             raptor_uri *uri);
    raptor_term *       raptor_new_term_from_uri_string     (raptor_world *world,
                                                             const unsigned char *uri_string);
    raptor_term *       raptor_term_copy                    (raptor_term *term);
    int                 raptor_term_compare                 (const raptor_term *t1,
                                                             const raptor_term *t2);
    int                 raptor_term_equals                  (raptor_term *t1,
                                                             raptor_term *t2);
    void                raptor_free_term                    (raptor_term *term);
    unsigned char *     raptor_term_to_counted_string       (raptor_term *term,
                                                             size_t *len_p);
    unsigned char *     raptor_term_to_string               (raptor_term *term);
    int                 raptor_term_ntriples_write          (const raptor_term *term,
                                                             raptor_iostream *iostr);
    unsigned char *     raptor_term_to_turtle_counted_string
                                                            (raptor_term *term,
                                                             raptor_namespace_stack *nstack,
                                                             raptor_uri *base_uri,
                                                             size_t *len_p);
    unsigned char *     raptor_term_to_turtle_string        (raptor_term *term,
                                                             raptor_namespace_stack *nstack,
                                                             raptor_uri *base_uri);
    int                 raptor_term_turtle_write            (raptor_iostream *iostr,
                                                             raptor_term *term,
                                                             raptor_namespace_stack *nstack,
                                                             raptor_uri *base_uri);
                        raptor_statement;
    raptor_statement *  raptor_new_statement                (raptor_world *world);
    raptor_statement *  raptor_new_statement_from_nodes     (raptor_world *world,
                                                             raptor_term *subject,
                                                             raptor_term *predicate,
                                                             raptor_term *object,
                                                             raptor_term *graph);
    void                raptor_free_statement               (raptor_statement *statement);
    raptor_statement *  raptor_statement_copy               (raptor_statement *statement);
    int                 raptor_statement_compare            (const raptor_statement *s1,
                                                             const raptor_statement *s2);
    int                 raptor_statement_equals             (const raptor_statement *s1,
                                                             const raptor_statement *s2);
    void                raptor_statement_init               (raptor_statement *statement,
                                                             raptor_world *world);
    void                raptor_statement_clear              (raptor_statement *statement);
    int                 raptor_statement_print              (const raptor_statement *statement,
                                                             FILE *stream);
    int                 raptor_statement_print_as_ntriples  (const raptor_statement *statement,
                                                             FILE *stream);
    int                 raptor_statement_ntriples_write     (const raptor_statement *statement,
                                                             raptor_iostream *iostr,
                                                             int write_graph_term);

## Description

Representation of RDF statements inside Raptor. They are a 3 or 4-tuple of raptor_term which cover the RDF terms of URI (`RAPTOR_TERM_TYPE_URI`), Literal (`RAPTOR_TERM_TYPE_LITERAL`) and Blank Node (`RAPTOR_TERM_TYPE_BLANK`).

## Details

### enum raptor_term_type

    typedef enum {
      RAPTOR_TERM_TYPE_UNKNOWN = 0,
      RAPTOR_TERM_TYPE_URI     = 1,
      RAPTOR_TERM_TYPE_LITERAL = 2,
      /* unused type 3 */
      RAPTOR_TERM_TYPE_BLANK   = 4
    } 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.

`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

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

    typedef union {
      raptor_uri *uri;

      raptor_term_literal_value literal;

      raptor_term_blank_value blank;
    } raptor_term_value;

Term value - this typedef exists solely for use in raptor_term

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

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.

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_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, creates a new internal identifier and uses it. This will use the handler set with `raptor_world_set_generate_bnodeid_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.

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

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

`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 unsigned 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.

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

`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 unsigned char *uri_string);

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

`world` : | raptor world
`uri_string` : | UTF-8 encoded URI string.
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

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

`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

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

`term` : | raptor_term object

### raptor_term_to_counted_string ()

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

Turns part of 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.

`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 part of raptor statement 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

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

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

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

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

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

`iostr` : | iostream for writing
`term` : | term
`nstack` : | namespace stack
`base_uri` : | base URI
Returns : | non-0 on failure

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

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)

### raptor_new_statement ()

    raptor_statement *  raptor_new_statement                (raptor_world *world);

Constructor - create a new raptor_statement.

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

`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

`statement` : | statement

### raptor_statement_copy ()

    raptor_statement *  raptor_statement_copy               (raptor_statement *statement);

Copy a raptor_statement.

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

`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

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

`statement` : | statement to initialize
`world` : | raptor world

### raptor_statement_clear ()

    void                raptor_statement_clear              (raptor_statement *statement);

Empty a raptor_statement of terms.

`statement` : | raptor_statement object

### raptor_statement_print ()

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

Print a raptor_statement to a stream.

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

`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

`statement` : | statement to write
`iostr` : | raptor iostream
`write_graph_term` : | flag to write graph term if present
Returns : | non-0 on failure