## General General — General library constants and utility functions |

## Synopsis

    #define             RAPTOR_VERSION
    #define             RAPTOR_VERSION_MAJOR
    #define             RAPTOR_VERSION_MINOR
    #define             RAPTOR_VERSION_RELEASE
    #define             RAPTOR_VERSION_STRING
    extern const unsigned int raptor_version_major;
    extern const unsigned int raptor_version_minor;
    extern const unsigned int raptor_version_release;
    extern const unsigned int raptor_version_decimal;
    extern const char * const raptor_copyright_string;
    extern const char * const raptor_home_url_string;
    extern const char * const raptor_license_string;
    extern const char * const raptor_short_copyright_string;
    extern const char * const raptor_version_string;
    extern const unsigned char * const raptor_owl_namespace_uri;
    extern const unsigned char * const raptor_rdf_namespace_uri;
    extern const unsigned char * const raptor_rdf_schema_namespace_uri;
    extern const unsigned char * const raptor_xml_literal_datatype_uri_string;
    extern const unsigned char * const raptor_xml_namespace_uri;
    extern const unsigned char * const raptor_xmlschema_datatypes_namespace_uri;
    void                (*raptor_statement_handler)         (void *user_data,
                                                             raptor_statement *statement);
    int                 raptor_snprintf                     (char *buffer,
                                                             size_t size,
                                                             const char *format,
                                                             ...);
    int                 raptor_vasprintf                    (char **ret,
                                                             const char *format,
                                                             va_list arguments);
    char *              raptor_vsnprintf                    (const char *format,
                                                             va_list arguments);
    int                 raptor_vsnprintf2                   (char *buffer,
                                                             size_t size,
                                                             const char *format,
                                                             va_list arguments);
    void                raptor_sort_r                       (void *base,
                                                             size_t nel,
                                                             size_t width,
                                                             raptor_data_compare_arg_handler compar,
                                                             void *user_data);
    void                (*raptor_log_handler)               (void *user_data,
                                                             raptor_log_message *message);
                        raptor_log_message;
    enum                raptor_log_level;
    const char *        raptor_log_level_get_label          (raptor_log_level level);
    enum                raptor_domain;
    const char *        raptor_domain_get_label             (raptor_domain domain);
    int                 (*raptor_data_compare_handler)      (const void *data1,
                                                             const void *data2);
    int                 (*raptor_data_compare_arg_handler)  (const void *data1,
                                                             const void *data2,
                                                             void *user_data);
    void                (*raptor_data_context_free_handler) (void *context,
                                                             void *object);
    int                 (*raptor_data_context_print_handler)
                                                            (void *context,
                                                             void *object,
                                                             FILE *fh);
    void                (*raptor_data_free_handler)         (void *data);
    void *              (*raptor_data_malloc_handler)       (size_t size);
    int                 (*raptor_data_print_handler)        (void *object,
                                                             FILE *fh);
    enum                raptor_syntax_bitflags;
                        raptor_syntax_description;
    int                 raptor_syntax_description_validate  (raptor_syntax_description *desc);
                        raptor_type_q;

## Description

How to get access to version numbers, set message and error handlers, list the parsed and serialized syntaxes provided in the library and various other utility functions.

## Details

### RAPTOR_VERSION

    #define RAPTOR_VERSION 20015

Raptor library version number

Format: major * 10000 + minor * 100 + release

### RAPTOR_VERSION_MAJOR

    #define RAPTOR_VERSION_MAJOR 2

Raptor library major version

### RAPTOR_VERSION_MINOR

    #define RAPTOR_VERSION_MINOR 0

Raptor library minor version

### RAPTOR_VERSION_RELEASE

    #define RAPTOR_VERSION_RELEASE 15

Raptor library release

### RAPTOR_VERSION_STRING

    #define RAPTOR_VERSION_STRING "2.0.15"

Raptor library version string

### raptor_version_major

    extern const unsigned int raptor_version_major;

Raptor major version number.

### raptor_version_minor

    extern const unsigned int raptor_version_minor;

Raptor minor version number.

### raptor_version_release

    extern const unsigned int raptor_version_release;

Raptor release version number.

### raptor_version_decimal

    extern const unsigned int raptor_version_decimal;

Raptor version as a decimal number.

Format: major * 10000 + minor * 100 + release

### raptor_copyright_string

    extern const char * const raptor_copyright_string;

Copyright string (multiple lines).

### raptor_home_url_string

    extern const char * const raptor_home_url_string;

Raptor home page URL.

### raptor_license_string

    extern const char * const raptor_license_string;

Raptor license string.

### raptor_short_copyright_string

    extern const char * const raptor_short_copyright_string;

Short copyright string (one line).

### raptor_version_string

    extern const char * const raptor_version_string;

Raptor version as a string.

### raptor_owl_namespace_uri

    extern const unsigned char * const raptor_owl_namespace_uri;

OWL (owl:) Namespace URI string.

### raptor_rdf_namespace_uri

    extern const unsigned char * const raptor_rdf_namespace_uri;

RDF Namespace (rdf:) URI string.

### raptor_rdf_schema_namespace_uri

    extern const unsigned char * const raptor_rdf_schema_namespace_uri;

RDF Schema (rdfs:) Namespace URI string.

### raptor_xml_literal_datatype_uri_string

    extern const unsigned char * const raptor_xml_literal_datatype_uri_string;

XML Literal datatype (rdf:XMLLiteral) URI string.

### raptor_xml_namespace_uri

    extern const unsigned char * const raptor_xml_namespace_uri;

XML Namespace (xml:) URI string.

### raptor_xmlschema_datatypes_namespace_uri

    extern const unsigned char * const raptor_xmlschema_datatypes_namespace_uri;

XML Schema datatypes (xsd:) namespace URI string.

### raptor_statement_handler ()

    void                (*raptor_statement_handler)         (void *user_data,
                                                             raptor_statement *statement);

Statement (triple) reporting handler function.

This handler function set with `raptor_parser_set_statement_handler()` on a parser receives statements as the parsing proceeds. The `statement` argument to the handler is shared and must be copied by the caller with `raptor_statement_copy()`.

`user_data` : | user data
`statement` : | statement to report

### raptor_snprintf ()

    int                 raptor_snprintf                     (char *buffer,
                                                             size_t size,
                                                             const char *format,
                                                             ...);

Format output into an allocated sized buffer

This provides a portable version `snprintf()` over variants on different systems.

If `buffer` is NULL, calculates the number of bytes needed to allocate for buffer and do no formatting.

`buffer` : | buffer (or NULL)
`size` : | bufer size (or 0)
`format` : | printf-style format string
`...` : | format arguments
Returns : | number of bytes allocated (excluding NUL) or 0 on failure

### raptor_vasprintf ()

    int                 raptor_vasprintf                    (char **ret,
                                                             const char *format,
                                                             va_list arguments);

Format output into a new buffer and return it

This is a wrapper around the (GNU) vasprintf function that is not always avaiable.

`ret` : | pointer to store buffer
`format` : | printf-style format string
`arguments` : | format arguments list
Returns : | number of bytes allocated (excluding NUL) or < 0 on failure

### raptor_vsnprintf ()

    char *              raptor_vsnprintf                    (const char *format,
                                                             va_list arguments);

Format output for a variable arguments list into a newly allocated buffer

`Deprecated`: This does not actually conform to vsnprintf's calling convention and does not return the allocated buffer length. Use `raptor_vsnprintf2()` or `raptor_vasprintf()` instead.

`format` : | printf-style format string
`arguments` : | variable arguments list
Returns : | a newly allocated string as the formatted result or NULL on failure

### raptor_vsnprintf2 ()

    int                 raptor_vsnprintf2                   (char *buffer,
                                                             size_t size,
                                                             const char *format,
                                                             va_list arguments);

Format output for a variable arguments list into an allocated sized buffer.

This is a wrapper around system versions of vsnprintf with different call and return conventions.

If `buffer` is NULL or size is 0 or the buffer size is too small, returns the number of bytes that would be needed for buffer

`buffer` : | buffer (or NULL)
`size` : | size of buffer (or 0)
`format` : | printf-style format string
`arguments` : | variable arguments list
Returns : | number of bytes allocated (excluding NUL) or <0 on failure

### raptor_sort_r ()

    void                raptor_sort_r                       (void *base,
                                                             size_t nel,
                                                             size_t width,
                                                             raptor_data_compare_arg_handler compar,
                                                             void *user_data);

Sort an array with an extra user data arg for the comparison funciton.

Sorts data at `base` of `nel` elememnts of width `width` using comparison function `comp` that takes args (void* data1, void* data2, `user_data`) and returns <0, 0, or >0 for object comparison.

`base` : | the array to be sorted
`nel` : | the number of elements in the array
`width` : | the size in bytes of each element of the array
`compar` : | comparison function
`user_data` : | a pointer to be passed to the comparison function

### raptor_log_handler ()

    void                (*raptor_log_handler)               (void *user_data,
                                                             raptor_log_message *message);

Handler function for log messages with location

Used during parsing and serializing for errors and warnings that may include location information. Handlers may be set by `raptor_world_set_log_handler()`.

`user_data` : | user data
`message` : | log message

### raptor_log_message

    typedef struct {
      int code;
      raptor_domain domain;
      raptor_log_level level;
      raptor_locator *locator;
      const char *text;
    } raptor_log_message;

Log message.

int `code`; | error code or < 0 if not used or known
raptor_domain `domain`; | message domain or RAPTOR_DOMAIN_NONE if not used or known
raptor_log_level `level`; | log message level
raptor_locator *`locator`; | location associated with message or NULL if not known
const char *`text`; | message string

### enum raptor_log_level

    typedef enum {
      RAPTOR_LOG_LEVEL_NONE,
      RAPTOR_LOG_LEVEL_TRACE,
      RAPTOR_LOG_LEVEL_DEBUG,
      RAPTOR_LOG_LEVEL_INFO,
      RAPTOR_LOG_LEVEL_WARN,
      RAPTOR_LOG_LEVEL_ERROR,
      RAPTOR_LOG_LEVEL_FATAL,
      RAPTOR_LOG_LEVEL_LAST = RAPTOR_LOG_LEVEL_FATAL
    } raptor_log_level;

Log levels

`RAPTOR_LOG_LEVEL_NONE` | Internal
`RAPTOR_LOG_LEVEL_TRACE` | very fine-grained tracing messages information
`RAPTOR_LOG_LEVEL_DEBUG` | fine-grained tracing messages suitable for debugging
`RAPTOR_LOG_LEVEL_INFO` | coarse-grained information messages
`RAPTOR_LOG_LEVEL_WARN` | warning messages of potentially harmful problems
`RAPTOR_LOG_LEVEL_ERROR` | error messages where the application can continue
`RAPTOR_LOG_LEVEL_FATAL` | fatal error message where the application will likely abort
`RAPTOR_LOG_LEVEL_LAST` | Internal

### raptor_log_level_get_label ()

    const char *        raptor_log_level_get_label          (raptor_log_level level);

Get label for a log message level

`level` : | log message level
Returns : | label string or NULL if level is not valid

### enum raptor_domain

    typedef enum {
      RAPTOR_DOMAIN_NONE,
      RAPTOR_DOMAIN_IOSTREAM,
      RAPTOR_DOMAIN_NAMESPACE,
      RAPTOR_DOMAIN_PARSER,
      RAPTOR_DOMAIN_QNAME,
      RAPTOR_DOMAIN_SAX2,
      RAPTOR_DOMAIN_SERIALIZER,
      RAPTOR_DOMAIN_TERM,
      RAPTOR_DOMAIN_TURTLE_WRITER,
      RAPTOR_DOMAIN_URI,
      RAPTOR_DOMAIN_WORLD,
      RAPTOR_DOMAIN_WWW,
      RAPTOR_DOMAIN_XML_WRITER,
      RAPTOR_DOMAIN_LAST = RAPTOR_DOMAIN_XML_WRITER
    } raptor_domain;

Log domain

`RAPTOR_DOMAIN_NONE` | Internal
`RAPTOR_DOMAIN_IOSTREAM` | I/O stream
`RAPTOR_DOMAIN_NAMESPACE` | XML Namespace / namespace stack
`RAPTOR_DOMAIN_PARSER` | RDF Parser
`RAPTOR_DOMAIN_QNAME` | XML QName
`RAPTOR_DOMAIN_SAX2` | XML SAX2
`RAPTOR_DOMAIN_SERIALIZER` | RDF Serializer
`RAPTOR_DOMAIN_TERM` | RDF Term
`RAPTOR_DOMAIN_TURTLE_WRITER` | Turtle Writer
`RAPTOR_DOMAIN_URI` | RDF Uri
`RAPTOR_DOMAIN_WORLD` | RDF world
`RAPTOR_DOMAIN_WWW` | WWW
`RAPTOR_DOMAIN_XML_WRITER` | XML Writer
`RAPTOR_DOMAIN_LAST` | Internal

### raptor_domain_get_label ()

    const char *        raptor_domain_get_label             (raptor_domain domain);

Get label for a domain

`domain` : | domain
Returns : | label string or NULL if domain is not valid

### raptor_data_compare_handler ()

    int                 (*raptor_data_compare_handler)      (const void *data1,
                                                             const void *data2);

Function to compare two data objects - signature like `strcmp()` and function pssed to `qsort()`

Designed to be passed into generic data structure constructors like `raptor_new_avltree()`.

`data1` : | first data object
`data2` : | second data object
Returns : | compare value <0 if `data1` is before `data2`, =0 if equal, >0 if `data1` is after `data2`

### raptor_data_compare_arg_handler ()

    int                 (*raptor_data_compare_arg_handler)  (const void *data1,
                                                             const void *data2,
                                                             void *user_data);

Function to compare two data objects with a user data argument

Designed to be used with `raptor_sort_r()` and compatible functions such as `raptor_sequence_sort_r()` which uses it.

`data1` : | first object
`data2` : | second object
`user_data` : | user data argument
Returns : | compare value <0 if `data1` is before `data2`, =0 if equal, >0 if `data1` is after `data2`

### raptor_data_context_free_handler ()

    void                (*raptor_data_context_free_handler) (void *context,
                                                             void *object);

Handler function for freeing a sequence item with a contextual pointer.

Set by `raptor_new_sequence_with_context()`.

`context` : | context data for the free function
`object` : | object to free

### raptor_data_context_print_handler ()

    int                 (*raptor_data_context_print_handler)
                                                            (void *context,
                                                             void *object,
                                                             FILE *fh);

Function function for printing an object with data context to a stream.

Set by `raptor_new_sequence_with_context()`

`context` : | context data for the print function
`object` : | object to print
`fh` : | FILE* to print to
Returns : | non-0 on failure

### raptor_data_free_handler ()

    void                (*raptor_data_free_handler)         (void *data);

Typedef for function to free a data object - signature like `free()`

Designed to be passed into generic data structure constructors like `raptor_new_avltree()`. If `data` is NULL, nothing should be done.

`data` : | data object or NULL

### raptor_data_malloc_handler ()

    void *              (*raptor_data_malloc_handler)       (size_t size);

Typedef for a function to allocate memory - signature like `malloc()`

Designed to be passed into constructors like raptor_www_fetch_to_string

`size` : | data size
Returns : | pointer to newly allocated memory or NULL on failure

### raptor_data_print_handler ()

    int                 (*raptor_data_print_handler)        (void *object,
                                                             FILE *fh);

Handler function for printing an object to a stream.

Set by `raptor_new_sequence()`

`object` : | object to print
`fh` : | FILE* to print to
Returns : | non-0 on failure

### enum raptor_syntax_bitflags

    typedef enum {
      RAPTOR_SYNTAX_NEED_BASE_URI = 1
    } raptor_syntax_bitflags;

Bit flags for raptor_syntax_description flags field

`RAPTOR_SYNTAX_NEED_BASE_URI` | the syntax requires a base URI

### raptor_syntax_description

    typedef struct {
      const char* names;
      unsigned int names_count;

      const char* label;

      const raptor_type_q* mime_types;
      unsigned int mime_types_count;

      const char* uri_strings;
      unsigned int uri_strings_count;

      unsigned int flags;
    } raptor_syntax_description;

Description of a syntax or file format.

const char *`names`; | array of syntax names - the first one (required) is the public name, the rest are aliases. The array is NULL terminated.
unsigned int `names_count`; | size of `names` array
const char *`label`; | long descriptive label for syntax
const raptor_type_q *`mime_types`; | Array of (MIME type, Q) values associated with the syntax (or NULL). If present the array is NULL terminated.
unsigned int `mime_types_count`; | size of `mime_types` array
const char *`uri_strings`; | array of URIs identifying the syntax (or NULL). The first one if present is the main URI, the rest are aliases. The array is NULL terminated.
unsigned int `uri_strings_count`; | size of `uri_strings` array
unsigned int `flags`; | See raptor_syntax_bitflags for the bits

### raptor_syntax_description_validate ()

    int                 raptor_syntax_description_validate  (raptor_syntax_description *desc);

Validate a syntax description has the required fields (name, labels) and update counts

`desc` : | description
Returns : | non-0 on failure

### raptor_type_q

    typedef struct {
      const char* mime_type;
      size_t mime_type_len;
      unsigned char q;
    } raptor_type_q;

(MIME Type, Q) pair

const char *`mime_type`; | MIME type string
size_t `mime_type_len`; | length of `mime_type`
unsigned char `q`; | Q value 0-10 standing for decimal 0.0-1.0