XML QName
3
RAPTOR Library

# XML QName

XML Namespace-qualified names.

## Synopsis

    typedef             raptor_qname;
    raptor_qname*       raptor_new_qname                    (raptor_namespace_stack *nstack,
                                                             unsigned char *name,
                                                             unsigned char *value,
                                                             raptor_simple_message_handler error_handler,
                                                             void *error_data);
    raptor_qname*       raptor_new_qname_from_namespace_local_name
                                                            (raptor_namespace *ns,
                                                             unsigned char *local_name,
                                                             unsigned char *value);
    raptor_qname*       raptor_qname_copy                   (raptor_qname *qname);
    void                raptor_free_qname                   (raptor_qname *name);
    int                 raptor_qname_equal                  (raptor_qname *name1,
                                                             raptor_qname *name2);
    raptor_uri*         raptor_qname_string_to_uri          (raptor_namespace_stack *nstack,
                                                             unsigned char *name,
                                                             size_t name_len,
                                                             raptor_simple_message_handler error_handler,
                                                             void *error_data);
    int                 raptor_iostream_write_qname         (raptor_iostream *iostr,
                                                             raptor_qname *qname);
    const unsigned char* raptor_qname_get_counted_value     (raptor_qname *name,
                                                             size_t *length_p);
    const unsigned char* raptor_qname_get_local_name        (raptor_qname *name);
    const raptor_namespace* raptor_qname_get_namespace      (raptor_qname *name);
    const unsigned char* raptor_qname_get_value             (raptor_qname *name);
    unsigned char*      raptor_qname_to_counted_name        (raptor_qname *qname,
                                                             size_t *length_p);

## Description

Wraps an XML name inside an associated XML namespace in some XML document context (typically). Mostly used inside parsing XML to manage qnames for XML element and attribute names.

## Details

### raptor_qname

    raptor_qname* raptor_qname;

Raptor XML qname class

### raptor_new_qname ()

    raptor_qname*       raptor_new_qname                    (raptor_namespace_stack *nstack,
                                                             unsigned char *name,
                                                             unsigned char *value,
                                                             raptor_simple_message_handler error_handler,
                                                             void *error_data);

Constructor - create a new XML qname.

Create a new qname from the local element/attribute name, with optional (attribute) value. The namespace stack is used to look up the name and find the namespace and generate the URI of the qname.

`nstack` :

  namespace stack to look up for namespaces

`name` :

  element or attribute name

`value` :

  attribute value (else is an element)

`error_handler` :

  function to call on an error

`error_data` :

  user data for error function

Returns :

  a new raptor_qname object or NULL on failure

### raptor_new_qname_from_namespace_local_name ()

    raptor_qname*       raptor_new_qname_from_namespace_local_name
                                                            (raptor_namespace *ns,
                                                             unsigned char *local_name,
                                                             unsigned char *value);

Constructor - create a new XML qname.

Create a new qname from the namespace and local element/attribute name, with optional (attribute) value.

`ns` :

  namespace of qname (or NULL)

`local_name` :

  element or attribute name

`value` :

  attribute value (else is an element)

Returns :

  a new raptor_qname object or NULL on failure

### raptor_qname_copy ()

    raptor_qname*       raptor_qname_copy                   (raptor_qname *qname);

Copy constructor - copy an existing XML qname.

`qname` :

  existing qname

Returns :

  a new raptor_qname object or NULL on failure

### raptor_free_qname ()

    void                raptor_free_qname                   (raptor_qname *name);

Destructor - destroy a raptor_qname object.

`name` :

  raptor_qname object

### raptor_qname_equal ()

    int                 raptor_qname_equal                  (raptor_qname *name1,
                                                             raptor_qname *name2);

Compare two XML Qnames for equality.

`name1` :

  first raptor_qname

`name2` :

  second raptor_name

Returns :

  non-0 if the qnames are equal.

### raptor_qname_string_to_uri ()

    raptor_uri*         raptor_qname_string_to_uri          (raptor_namespace_stack *nstack,
                                                             unsigned char *name,
                                                             size_t name_len,
                                                             raptor_simple_message_handler error_handler,
                                                             void *error_data);

Get the URI for a qname.

Utility function to turn a string representing a QName in the N3 style, into a new URI representing it. A NULL name or name ":" returns the default namespace URI. A name "p:" returns namespace name (URI) for the namespace with prefix "p".

Partially equivalent to qname=raptor_new_qname(nstack, name, NULL, error_handler, error_data); uri=raptor_uri_copy(qname->uri); raptor_free_qname(qname) but without making the qname, and it also handles the NULL and ":" name cases as well as error checking.

`nstack` :

  raptor_namespace_stack to decode the namespace

`name` :

  QName string or NULL

`name_len` :

  QName string length

`error_handler` :

  function to call on an error

`error_data` :

  user data for error function

Returns :

  new raptor_uri object or NULL on failure

### raptor_iostream_write_qname ()

    int                 raptor_iostream_write_qname         (raptor_iostream *iostr,
                                                             raptor_qname *qname);

Write a formatted qname to an iostream

`iostr` :

  raptor iosteram

`qname` :

  QName to write

Returns :

  non-0 on failure

### raptor_qname_get_counted_value ()

    const unsigned char* raptor_qname_get_counted_value     (raptor_qname *name,
                                                             size_t *length_p);

Get the raptor_value of an XML QName.

`name` :

  raptor_qname object

`length_p` :

  pointer to variable to store length of name (or NULL)

Returns :

  the value

### raptor_qname_get_local_name ()

    const unsigned char* raptor_qname_get_local_name        (raptor_qname *name);

Get the raptor_local_name of an XML QName.

`name` :

  raptor_qname object

Returns :

  the local_name

### raptor_qname_get_namespace ()

    const raptor_namespace* raptor_qname_get_namespace      (raptor_qname *name);

Get the raptor_namespace of an XML QName.

`name` :

  raptor_qname object

Returns :

  the namespace

### raptor_qname_get_value ()

    const unsigned char* raptor_qname_get_value             (raptor_qname *name);

Get the raptor_value of an XML QName.

`name` :

  raptor_qname object

Returns :

  the value

### raptor_qname_to_counted_name ()

    unsigned char*      raptor_qname_to_counted_name        (raptor_qname *qname,
                                                             size_t *length_p);

Get the string form of a QName name

`qname` :

  QName to write

`length_p` :

  pointer to variable to store length of name (or NULL)

Returns :

  string or NULL on failure