XML QName

## XML QName XML QName — XML Namespace-qualified names. |

## Synopsis

    typedef             raptor_qname;
    raptor_qname *      raptor_new_qname                    (raptor_namespace_stack *nstack,
                                                             const unsigned char *name,
                                                             const unsigned char *value);
    raptor_qname *      raptor_new_qname_from_namespace_local_name
                                                            (raptor_world *world,
                                                             raptor_namespace *ns,
                                                             const unsigned char *local_name,
                                                             const unsigned char *value);
    raptor_qname *      raptor_new_qname_from_namespace_uri (raptor_namespace_stack *nstack,
                                                             raptor_uri *uri,
                                                             int xml_version);
    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,
                                                             const unsigned char *name,
                                                             size_t name_len);
    int                 raptor_qname_write                  (raptor_qname *qname,
                                                             raptor_iostream *iostr);
    unsigned char *     raptor_qname_format_as_xml          (const raptor_qname *qname,
                                                             size_t *length_p);
    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,
                                                             const unsigned char *name,
                                                             const unsigned char *value);

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)
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_world *world,
                                                             raptor_namespace *ns,
                                                             const unsigned char *local_name,
                                                             const 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.

`world` : | raptor_world object
`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_new_qname_from_namespace_uri ()

    raptor_qname *      raptor_new_qname_from_namespace_uri (raptor_namespace_stack *nstack,
                                                             raptor_uri *uri,
                                                             int xml_version);

Make an appropriate XML Qname from the namespaces on a namespace stack

Makes a qname from the in-scope namespaces in a stack if the URI matches the prefix and the rest is a legal XML name.

`nstack` : | namespace stack
`uri` : | URI to use to make qname
`xml_version` : | XML Version
Returns : | raptor_qname for the URI 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,
                                                             const unsigned char *name,
                                                             size_t name_len);

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); 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
Returns : | new raptor_uri object or NULL on failure

### raptor_qname_write ()

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

Write a formatted qname to an iostream

`qname` : | QName to write
`iostr` : | raptor iosteram
Returns : | non-0 on failure

### raptor_qname_format_as_xml ()

    unsigned char *     raptor_qname_format_as_xml          (const raptor_qname *qname,
                                                             size_t *length_p);

Format a qname in an XML style into a newly allocated string.

Generates a string of the form a:b="value" or a="value" depending on the qname's prefix. Double quotes are always used.

If `length_p` is not NULL, the length of the string is stored in the address it points to.

`qname` : | qname object
`length_p` : | pointer to length (or NULL)
Returns : | qname formatted as newly allocated string or NULL 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 : | new string name or NULL on failure