section-uri: Raptor RDF Syntax Library Manual

## section-uri section-uri |

## Functions

raptor_uri * | raptor_new_uri ()
raptor_uri * | raptor_new_uri_from_counted_string ()
raptor_uri * | raptor_new_uri_from_uri_local_name ()
raptor_uri * | raptor_new_uri_from_uri_or_file_string ()
raptor_uri * | raptor_new_uri_relative_to_base ()
raptor_uri * | raptor_new_uri_relative_to_base_counted ()
raptor_uri * | raptor_new_uri_from_id ()
raptor_uri * | raptor_new_uri_for_rdf_concept ()
raptor_uri * | raptor_new_uri_for_xmlbase ()
raptor_uri * | raptor_new_uri_for_retrieval ()
void | raptor_free_uri ()
int | raptor_uri_compare ()
int | raptor_uri_equals ()
raptor_uri * | raptor_uri_copy ()
unsigned char * | raptor_uri_as_string ()
unsigned char * | raptor_uri_as_counted_string ()
unsigned char * | raptor_uri_to_relative_counted_uri_string ()
unsigned char * | raptor_uri_to_relative_uri_string ()
unsigned char * | raptor_uri_to_counted_string ()
unsigned char * | raptor_uri_to_string ()
size_t | raptor_uri_resolve_uri_reference ()
unsigned char * | raptor_uri_counted_filename_to_uri_string ()
unsigned char * | raptor_uri_filename_to_uri_string ()
int | raptor_uri_uri_string_is_absolute ()
int | raptor_uri_uri_string_is_file_uri ()
char * | raptor_uri_uri_string_to_filename ()
char * | raptor_uri_uri_string_to_filename_fragment ()
char * | raptor_uri_uri_string_to_counted_filename_fragment ()
int | raptor_uri_print ()
raptor_world * | raptor_uri_get_world ()
int | raptor_uri_write ()
int | raptor_uri_file_exists ()
int | raptor_uri_filename_exists ()
unsigned char * | raptor_uri_to_turtle_counted_string ()
unsigned char * | raptor_uri_to_turtle_string ()
int | raptor_uri_turtle_write ()

## Types and Values

typedef | raptor_uri

## Description

## Functions

### raptor_new_uri ()

    raptor_uri *
    raptor_new_uri (raptor_world *world,
                    const char *uri_string);

Constructor - create a raptor URI from a UTF-8 encoded Unicode string.

#### Parameters

world | raptor_world object |
uri_string | URI string. |

#### Returns

a new raptor_uri object or NULL on failure.

### raptor_new_uri_from_counted_string ()

    raptor_uri *
    raptor_new_uri_from_counted_string (raptor_world *world,
                                        const char *uri_string,
                                        size_t length);

Constructor - create a raptor URI 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 object |
uri_string | URI string. |
length | length of URI string |

#### Returns

a new raptor_uri object or NULL on failure.

### raptor_new_uri_from_uri_local_name ()

    raptor_uri *
    raptor_new_uri_from_uri_local_name (raptor_world *world,
                                        raptor_uri *uri,
                                        const char *local_name);

Constructor - create a raptor URI from an existing URI and a local name.

Creates a new URI from the concatenation of the `local_name` to the `uri` . This is NOT relative URI resolution, which is done by the `raptor_new_uri_relative_to_base()` constructor.

#### Parameters

world | raptor_world object |
uri | existing raptor_uri |
local_name | local name |

#### Returns

a new raptor_uri object or NULL on failure.

### raptor_new_uri_from_uri_or_file_string ()

    raptor_uri *
    raptor_new_uri_from_uri_or_file_string
                                   (raptor_world *world,
                                    raptor_uri *base_uri,
                                    const unsigned char *uri_or_file_string);

Constructor - create a raptor URI from a string that is a relative or absolute URI or a filename

If the `uri_or_file_string` is a filename PATH that exists, the result will be a URI file://PATH

#### Parameters

world | raptor_world object |
base_uri | existing base URI |
uri_or_file_string | URI string or filename |

#### Returns

a new raptor_uri object or NULL on failure

### raptor_new_uri_relative_to_base ()

    raptor_uri *
    raptor_new_uri_relative_to_base (raptor_world *world,
                                     raptor_uri *base_uri,
                                     const char *uri_string);

Constructor - create a raptor URI from a base URI and a relative URI string.

Use `raptor_new_uri_relative_to_base_counted()` if the URI string length is known

#### Parameters

world | raptor_world object |
base_uri | existing base URI |
uri_string | relative URI string |

#### Returns

a new raptor_uri object or NULL on failure.

### raptor_new_uri_relative_to_base_counted ()

    raptor_uri *
    raptor_new_uri_relative_to_base_counted
                                   (raptor_world *world,
                                    raptor_uri *base_uri,
                                    const char *uri_string,
                                    size_t uri_len);

Constructor - create a raptor URI from a base URI and a relative counted URI string.

#### Parameters

world | raptor_world object |
base_uri | existing base URI |
uri_string | relative URI string |
uri_len | length of URI string (or 0) |

#### Returns

a new raptor_uri object or NULL on failure.

### raptor_new_uri_from_id ()

    raptor_uri *
    raptor_new_uri_from_id (raptor_world *world,
                            raptor_uri *base_uri,
                            const char *id);

Constructor - create a new URI from a base URI and RDF ID.

This creates a URI equivalent to concatenating `base_uri` with

#### and `id` .

#### Parameters

world | raptor_world object |
base_uri | existing base URI |
id | RDF ID |

#### Returns

a new raptor_uri object or NULL on failure.

### raptor_new_uri_for_rdf_concept ()

    raptor_uri *
    raptor_new_uri_for_rdf_concept (raptor_world *world,
                                    const char *name);

Constructor - create a raptor URI for the RDF namespace concept name.

Example: u=raptor_new_uri_for_rdf_concept("value") creates a new URI for the rdf:value term.

#### Parameters

world | raptor_world object |
name | RDF namespace concept |

#### Returns

a new raptor_uri object or NULL on failure

### raptor_new_uri_for_xmlbase ()

    raptor_uri *
    raptor_new_uri_for_xmlbase (raptor_uri *old_uri);

Constructor - create a URI suitable for use as an XML Base.

Takes an existing URI and ensures it has a path (default /) and has no fragment or query arguments - XML base does not use these.

#### Parameters

old_uri | URI to transform |

#### Returns

new raptor_uri object or NULL on failure.

### raptor_new_uri_for_retrieval ()

    raptor_uri *
    raptor_new_uri_for_retrieval (raptor_uri *old_uri);

Constructor - create a URI suitable for retrieval.

Takes an existing URI and ensures it has a path (default /) and has no fragment - URI retrieval does not use the fragment part.

#### Parameters

old_uri | URI to transform |

#### Returns

new raptor_uri object or NULL on failure.

### raptor_free_uri ()

    void
    raptor_free_uri (raptor_uri *uri);

Destructor - destroy a raptor_uri object

#### Parameters

uri | URI to destroy |

### raptor_uri_compare ()

    int
    raptor_uri_compare (raptor_uri *uri1,
                        raptor_uri *uri2);

Compare two URIs, ala strcmp.

A NULL URI is always less than (never equal to) a non-NULL URI.

#### Parameters

uri1 | URI 1 (may be NULL) |
uri2 | URI 2 (may be NULL) |

#### Returns

-1 if uri1 < uri2, 0 if equal, 1 if uri1 > uri2

### raptor_uri_equals ()

    int
    raptor_uri_equals (raptor_uri *uri1,
                       raptor_uri *uri2);

Check if two URIs are equal.

A NULL URI is not equal to a non-NULL URI.

#### Parameters

uri1 | URI 1 (may be NULL) |
uri2 | URI 2 (may be NULL) |

#### Returns

non-0 if the URIs are equal

### raptor_uri_copy ()

    raptor_uri *
    raptor_uri_copy (raptor_uri *uri);

Constructor - get a copy of a URI.

#### Parameters

uri | URI object |

#### Returns

a new raptor_uri object or NULL on failure

### raptor_uri_as_string ()

    unsigned char *
    raptor_uri_as_string (raptor_uri *uri);

Get a string representation of a URI.

Returns a shared pointer to a string representation of `uri` . This string is shared and must not be freed, otherwise see use the `raptor_uri_to_string()` or `raptor_uri_to_counted_string()` methods.

#### Parameters

uri | raptor_uri object |

#### Returns

shared string representation of URI

### raptor_uri_as_counted_string ()

    unsigned char *
    raptor_uri_as_counted_string (raptor_uri *uri,
                                  size_t *len_p);

Get a string representation of a URI with count.

Returns a shared pointer to a string representation of `uri` along with the length of the string in `len_p` , if not NULL. This string is shared and must not be freed, otherwise see use the `raptor_uri_to_string()` or `raptor_uri_to_counted_string()` methods.

#### Parameters

uri | URI object |
len_p | address of length variable or NULL |

#### Returns

shared string representation of URI

### raptor_uri_to_relative_counted_uri_string ()

    unsigned char *
    raptor_uri_to_relative_counted_uri_string
                                   (raptor_uri *base_uri,
                                    raptor_uri *reference_uri,
                                    size_t *length_p);

Get the counted relative URI string of a URI against a base URI.

#### Parameters

base_uri | The base absolute URI to resolve against (or NULL) |
reference_uri | The reference absolute URI to use |
length_p | Location to store the length of the relative URI string or NULL |

#### Returns

A newly allocated relative URI string or NULL on failure

### raptor_uri_to_relative_uri_string ()

    unsigned char *
    raptor_uri_to_relative_uri_string (raptor_uri *base_uri,
                                       raptor_uri *reference_uri);

Get the relative URI string of a URI against a base URI.

#### Parameters

base_uri | The base absolute URI to resolve against |
reference_uri | The reference absolute URI to use |

#### Returns

A newly allocated relative URI string or NULL on failure

### raptor_uri_to_counted_string ()

    unsigned char *
    raptor_uri_to_counted_string (raptor_uri *uri,
                                  size_t *len_p);

Get a new counted string for a URI.

If `len_p` is not NULL, the length of the string is stored in it.

The memory allocated must be freed by the caller and `raptor_free_memory()` should be used for best portability.

#### Parameters

uri | raptor_uri object |
len_p | Pointer to length (or NULL) |

#### Returns

new string or NULL on failure

### raptor_uri_to_string ()

    unsigned char *
    raptor_uri_to_string (raptor_uri *uri);

Get a new string for a URI.

The memory allocated must be freed by the caller and `raptor_free_memory()` should be used for best portability.

#### Parameters

uri | raptor_uri object |

#### Returns

new string or NULL on failure

### raptor_uri_resolve_uri_reference ()

    size_t
    raptor_uri_resolve_uri_reference (const char *base_uri,
                                      const unsigned char *reference_uri,
                                      unsigned char *buffer,
                                      size_t length);

Resolve a URI against a base URI to create a new absolute URI.

#### Parameters

base_uri | Base URI string |
reference_uri | Reference URI string |
buffer | Destination URI output buffer |
length | Length of destination output buffer |

#### Returns

length of resolved string or 0 on failure (such as `buffer` too small)

### raptor_uri_counted_filename_to_uri_string ()

    unsigned char *
    raptor_uri_counted_filename_to_uri_string
                                   (const char *filename,
                                    size_t filename_len);

Converts a counted filename to a file: URI.

Handles the OS-specific escaping on turning filenames into URIs and returns a new buffer that the caller must `free()`. Turns a space in the filename into %20 and '%' into %25.

#### Parameters

filename | The filename to convert |
filename_len | length of `filename` or 0 to count it here |

#### Returns

A newly allocated string with the URI or NULL on failure

### raptor_uri_filename_to_uri_string ()

    unsigned char *
    raptor_uri_filename_to_uri_string (const char *filename);

Converts a filename to a file: URI.

Handles the OS-specific escaping on turning filenames into URIs and returns a new buffer that the caller must `free()`. Turns a space in the filename into %20 and '%' into %25.

#### Parameters

filename | The filename to convert |

#### Returns

A newly allocated string with the URI or NULL on failure

### raptor_uri_uri_string_is_absolute ()

    int
    raptor_uri_uri_string_is_absolute (const unsigned char *uri_string);

Check if a uri string is an absolute URI

#### Parameters

uri_string | uri to check write |

#### Returns

>0 if absolute, 0 if not, < 0 on failure

### raptor_uri_uri_string_is_file_uri ()

    int
    raptor_uri_uri_string_is_file_uri (const unsigned char *uri_string);

Check if a URI string is a file: URI.

#### Parameters

uri_string | The URI string to check |

#### Returns

Non zero if URI string is a file: URI

### raptor_uri_uri_string_to_filename ()

    char *
    raptor_uri_uri_string_to_filename (const char *uri_string);

Convert a file: URI to a filename.

Handles the OS-specific file: URIs to filename mappings. Returns a new buffer containing the filename that the caller must free.

See also `raptor_uri_uri_string_to_counted_filename_fragment()`

#### Parameters

uri_string | The file: URI to convert |

#### Returns

A newly allocated string with the filename or NULL on failure

### raptor_uri_uri_string_to_filename_fragment ()

    char *
    raptor_uri_uri_string_to_filename_fragment
                                   (const char *uri_string,
                                    unsigned char **fragment_p);

Convert a file: URI to a filename and fragment.

Handles the OS-specific file: URIs to filename mappings. Returns a new buffer containing the filename that the caller must free.

If `fragment_p` is given, a new string containing the URI fragment is returned, or NULL if none is present

See also `raptor_uri_uri_string_to_counted_filename_fragment()`

#### Parameters

uri_string | The file: URI to convert |
fragment_p | Address of pointer to store any URI fragment or NULL |

#### Returns

A newly allocated string with the filename or NULL on failure

### raptor_uri_uri_string_to_counted_filename_fragment ()

    char *
    raptor_uri_uri_string_to_counted_filename_fragment
                                   (const char *uri_string,
                                    size_t *len_p,
                                    unsigned char **fragment_p,
                                    size_t *fragment_len_p);

Convert a file: URI to a counted filename and counted fragment.

Handles the OS-specific file: URIs to filename mappings. Returns a new buffer containing the filename that the caller must free.

If `len_p` is present the length of the filename is returned

If `fragment_p` is given, a new string containing the URI fragment is returned, or NULL if none is present. If `fragment_len_p` is present the length is returned in it.

#### Parameters

uri_string | The file: URI to convert |
len_p | address of filename length variable or NULL |
fragment_p | Address of pointer to store any URI fragment or NULL |
fragment_len_p | address of length variable or NULL |

#### Returns

A newly allocated string with the filename or NULL on failure

### raptor_uri_print ()

    int
    raptor_uri_print (const raptor_uri *uri,
                      FILE *stream);

Print a URI to a file handle.

#### Parameters

uri | URI to print |
stream | The file handle to print to |

#### Returns

non-0 on failure

### raptor_uri_get_world ()

    raptor_world *
    raptor_uri_get_world (raptor_uri *uri);

Get the raptor_world object associated with a raptor_uri.

#### Parameters

uri | raptor_uri object |

#### Returns

raptor_world object

### raptor_uri_write ()

    int
    raptor_uri_write (raptor_uri *uri,
                      raptor_iostream *iostr);

Write a raptor URI to the iostream.

#### Parameters

uri | URI |
iostr | raptor iostream |

#### Returns

non-0 on failure

### raptor_uri_file_exists ()

    int
    raptor_uri_file_exists (raptor_uri *uri);

Check if a file: URI is a file that exists

#### Parameters

uri | URI string |

#### Returns

> 0 if file exists, 0 if does not exist, < 0 if not a file URI or error

### raptor_uri_filename_exists ()

    int
    raptor_uri_filename_exists (const unsigned char *path);

Check if `path` points to a file that exists

#### Parameters

path | file path |

#### Returns

> 0 if file exists, 0 if does not exist, < 0 on error

### raptor_uri_to_turtle_counted_string ()

    unsigned char *
    raptor_uri_to_turtle_counted_string (raptor_world *world,
                                         raptor_uri *uri,
                                         raptor_namespace_stack *nstack,
                                         raptor_uri *base_uri,
                                         size_t *len_p);

Convert raptor_uri 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.

#### Parameters

world | world |
uri | uri |
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_uri_to_turtle_string ()

    unsigned char *
    raptor_uri_to_turtle_string (raptor_world *world,
                                 raptor_uri *uri,
                                 raptor_namespace_stack *nstack,
                                 raptor_uri *base_uri);

Convert raptor_uri 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.

#### Parameters

world | world |
uri | uri |
nstack | namespace stack |
base_uri | base URI |

#### Returns

the new string or NULL on failure.

### raptor_uri_turtle_write ()

    int
    raptor_uri_turtle_write (raptor_world *world,
                             raptor_iostream *iostr,
                             raptor_uri *uri,
                             raptor_namespace_stack *nstack,
                             raptor_uri *base_uri);

Write raptor_uri 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

world | world |
iostr | iostream for writing |
uri | uri |
nstack | namespace stack |
base_uri | base URI |

#### Returns

non-0 on failure

## Types and Values

### raptor_uri

    raptor_uri* raptor_uri;

Raptor URI Class.