XbBuilderNode: libxmlb Reference Manual

## XbBuilderNode XbBuilderNode |

## Functions

gboolean | (*XbBuilderNodeTraverseFunc) ()
gint | (*XbBuilderNodeSortFunc) ()
XbBuilderNode * | xb_builder_node_new ()
XbBuilderNode * | xb_builder_node_insert ()
void | xb_builder_node_insert_text ()
gboolean | xb_builder_node_has_flag ()
void | xb_builder_node_add_flag ()
const gchar * | xb_builder_node_get_element ()
void | xb_builder_node_set_element ()
const gchar * | xb_builder_node_get_text ()
guint64 | xb_builder_node_get_text_as_uint ()
void | xb_builder_node_set_text ()
void | xb_builder_node_tokenize_text ()
const gchar * | xb_builder_node_get_tail ()
void | xb_builder_node_set_tail ()
const gchar * | xb_builder_node_get_attr ()
guint64 | xb_builder_node_get_attr_as_uint ()
void | xb_builder_node_set_attr ()
void | xb_builder_node_remove_attr ()
void | xb_builder_node_add_child ()
void | xb_builder_node_remove_child ()
GPtrArray * | xb_builder_node_get_children ()
XbBuilderNode * | xb_builder_node_get_first_child ()
XbBuilderNode * | xb_builder_node_get_last_child ()
XbBuilderNode * | xb_builder_node_get_child ()
void | xb_builder_node_unlink ()
XbBuilderNode * | xb_builder_node_get_parent ()
guint | xb_builder_node_depth ()
void | xb_builder_node_traverse ()
void | xb_builder_node_sort_children ()
gchar * | xb_builder_node_export ()
GPtrArray * | xb_builder_node_get_tokens ()
void | xb_builder_node_add_token ()

## Types and Values

#define | XB_TYPE_BUILDER_NODE
struct | XbBuilderNodeClass
enum | XbBuilderNodeFlags
| XbBuilderNode

## Description

## Functions

### XbBuilderNodeTraverseFunc ()

    gboolean
    (*XbBuilderNodeTraverseFunc) (XbBuilderNode *bn,
                                  gpointer user_data);

### XbBuilderNodeSortFunc ()

    gint
    (*XbBuilderNodeSortFunc) (XbBuilderNode *bn1,
                              XbBuilderNode *bn2,
                              gpointer user_data);

### xb_builder_node_new ()

    XbBuilderNode *
    xb_builder_node_new (const gchar *element);

Creates a new builder node.

#### Parameters

element | An element name, e.g. "component" |

#### Returns

a new XbBuilderNode.

[transfer full]

Since: 0.1.0

### xb_builder_node_insert ()

    XbBuilderNode *
    xb_builder_node_insert (XbBuilderNode *parent,
                            const gchar *element,
                            ...);

Creates a new builder node.

[skip]

#### Parameters

parent | A XbBuilderNode, or `NULL` |
element | An element name, e.g. "component" |
... | any attributes to add to the node, terminated by `NULL` |

#### Returns

a new XbBuilderNode.

[transfer full]

Since: 0.1.0

### xb_builder_node_insert_text ()

    void
    xb_builder_node_insert_text (XbBuilderNode *parent,
                                 const gchar *element,
                                 const gchar *text,
                                 ...);

Creates a new builder node with optional node text.

[skip]

#### Parameters

parent | A XbBuilderNode, or `NULL` |
element | An element name, e.g. "id" |
text | node text, e.g. "gimp.desktop". | [allow-none]
... | any attributes to add to the node, terminated by `NULL` |

Since: 0.1.0

### xb_builder_node_has_flag ()

    gboolean
    xb_builder_node_has_flag (XbBuilderNode *self,
                              XbBuilderNodeFlags flag);

Checks a flag on the builder node.

#### Parameters

self | a XbBuilderNode |
flag | a XbBuilderNodeFlags |

#### Returns

`TRUE` if `flag` is set

Since: 0.1.0

### xb_builder_node_add_flag ()

    void
    xb_builder_node_add_flag (XbBuilderNode *self,
                              XbBuilderNodeFlags flag);

Adds a flag to the builder node.

#### Parameters

self | a XbBuilderNode |
flag | a XbBuilderNodeFlags |

Since: 0.1.0

### xb_builder_node_get_element ()

    const gchar *
    xb_builder_node_get_element (XbBuilderNode *self);

Gets the element from the builder node.

#### Parameters

self | a XbBuilderNode |

#### Returns

string, or `NULL` if unset

Since: 0.1.0

### xb_builder_node_set_element ()

    void
    xb_builder_node_set_element (XbBuilderNode *self,
                                 const gchar *element);

Sets the element name on the builder node.

#### Parameters

self | a XbBuilderNode |
element | a string element |

Since: 0.1.0

### xb_builder_node_get_text ()

    const gchar *
    xb_builder_node_get_text (XbBuilderNode *self);

Gets the text from the builder node.

#### Parameters

self | a XbBuilderNode |

#### Returns

string, or `NULL` if unset

Since: 0.1.0

### xb_builder_node_get_text_as_uint ()

    guint64
    xb_builder_node_get_text_as_uint (XbBuilderNode *self);

Gets the text from the builder node.

#### Parameters

self | a XbBuilderNode |

#### Returns

integer, or 0 if unset

Since: 0.1.3

### xb_builder_node_set_text ()

    void
    xb_builder_node_set_text (XbBuilderNode *self,
                              const gchar *text,
                              gssize text_len);

Sets the text on the builder node.

#### Parameters

self | a XbBuilderNode |
text | a string. | [allow-none]
text_len | length of `text` , or -1 if `text` is NUL terminated |

Since: 0.1.0

### xb_builder_node_tokenize_text ()

    void
    xb_builder_node_tokenize_text (XbBuilderNode *self);

Tokenize text added with `xb_builder_node_set_text()`.

When searching, libxmlb often has to tokenize strings before they can be compared. This is done in the "fast path" and makes searching for non-ASCII text much slower.

Adding the tokens to the deduplicated string table allows much faster searching at the expense of a ~5% size increase of the silo.

This function adds all valid UTF-8 and ASCII search words generated from the value of `xb_builder_node_set_text()`.

The transliteration locale (e.g. `en_GB`) is read from the `xml:lang` node attribute if set.

#### Parameters

self | a XbBuilderNode |

Since: 0.3.1

### xb_builder_node_get_tail ()

    const gchar *
    xb_builder_node_get_tail (XbBuilderNode *self);

Gets the tail from the builder node.

#### Parameters

self | a XbBuilderNode |

#### Returns

string, or `NULL` if unset

Since: 0.1.12

### xb_builder_node_set_tail ()

    void
    xb_builder_node_set_tail (XbBuilderNode *self,
                              const gchar *tail,
                              gssize tail_len);

Sets the tail on the builder node.

#### Parameters

self | a XbBuilderNode |
tail | a string. | [allow-none]
tail_len | length of `tail` , or -1 if `tail` is NUL terminated |

Since: 0.1.12

### xb_builder_node_get_attr ()

    const gchar *
    xb_builder_node_get_attr (XbBuilderNode *self,
                              const gchar *name);

Gets an attribute from the builder node.

#### Parameters

self | a XbBuilderNode |
name | attribute name, e.g. `type` |

#### Returns

string, or `NULL` if unset

Since: 0.1.0

### xb_builder_node_get_attr_as_uint ()

    guint64
    xb_builder_node_get_attr_as_uint (XbBuilderNode *self,
                                      const gchar *name);

Gets an attribute from the builder node.

#### Parameters

self | a XbBuilderNode |
name | attribute name, e.g. `priority` |

#### Returns

integer, or 0 if unset

Since: 0.1.3

### xb_builder_node_set_attr ()

    void
    xb_builder_node_set_attr (XbBuilderNode *self,
                              const gchar *name,
                              const gchar *value);

Adds an attribute to the builder node.

#### Parameters

self | a XbBuilderNode |
name | attribute name, e.g. `type` |
value | attribute value, e.g. `desktop` |

Since: 0.1.0

### xb_builder_node_remove_attr ()

    void
    xb_builder_node_remove_attr (XbBuilderNode *self,
                                 const gchar *name);

Removes an attribute from the builder node.

#### Parameters

self | a XbBuilderNode |
name | attribute name, e.g. `type` |

Since: 0.1.0

### xb_builder_node_add_child ()

    void
    xb_builder_node_add_child (XbBuilderNode *self,
                               XbBuilderNode *child);

Adds a child builder node.

#### Parameters

self | A XbBuilderNode |
child | A XbBuilderNode |

Since: 0.1.0

### xb_builder_node_remove_child ()

    void
    xb_builder_node_remove_child (XbBuilderNode *self,
                                  XbBuilderNode *child);

Removes a child builder node.

#### Parameters

self | A XbBuilderNode |
child | A XbBuilderNode |

Since: 0.1.1

### xb_builder_node_get_children ()

    GPtrArray *
    xb_builder_node_get_children (XbBuilderNode *self);

Gets the children of the builder node.

#### Parameters

self | a XbBuilderNode |

#### Returns

children.

[transfer none][element-type XbBuilderNode]

Since: 0.1.0

### xb_builder_node_get_first_child ()

    XbBuilderNode *
    xb_builder_node_get_first_child (XbBuilderNode *self);

Gets the first child of the builder node.

#### Parameters

self | a XbBuilderNode |

#### Returns

a XbBuilderNode, or `NULL`.

[transfer none]

Since: 0.1.12

### xb_builder_node_get_last_child ()

    XbBuilderNode *
    xb_builder_node_get_last_child (XbBuilderNode *self);

Gets the last child of the builder node.

#### Parameters

self | a XbBuilderNode |

#### Returns

a XbBuilderNode, or `NULL`.

[transfer none]

Since: 0.1.12

### xb_builder_node_get_child ()

    XbBuilderNode *
    xb_builder_node_get_child (XbBuilderNode *self,
                               const gchar *element,
                               const gchar *text);

Finds a child builder node by the element name, and optionally text value.

#### Parameters

self | a XbBuilderNode |
element | An element name, e.g. "url" |
text | node text, e.g. "gimp.desktop". | [allow-none]

#### Returns

a new XbBuilderNode, or `NULL` if not found.

[transfer full]

Since: 0.1.1

### xb_builder_node_unlink ()

    void
    xb_builder_node_unlink (XbBuilderNode *self);

Unlinks a XbBuilderNode from a tree, resulting in two separate trees.

This should not be used from the function called by `xb_builder_node_traverse()` otherwise the entire tree will not be traversed.

Instead use xb_builder_node_add_flag(bn,XB_BUILDER_NODE_FLAG_IGNORE);

#### Parameters

self | a XbBuilderNode |

Since: 0.1.1

### xb_builder_node_get_parent ()

    XbBuilderNode *
    xb_builder_node_get_parent (XbBuilderNode *self);

Gets the parent node for the current node.

#### Parameters

self | a XbBuilderNode |

#### Returns

a new XbBuilderNode, or `NULL` no parent exists.

[transfer full]

Since: 0.1.1

### xb_builder_node_depth ()

    guint
    xb_builder_node_depth (XbBuilderNode *self);

Gets the depth of the node tree, where 0 is the root node.

#### Parameters

self | a XbBuilderNode |

Since: 0.1.1

### xb_builder_node_traverse ()

    void
    xb_builder_node_traverse (XbBuilderNode *self,
                              GTraverseType order,
                              GTraverseFlags flags,
                              gint max_depth,
                              XbBuilderNodeTraverseFunc func,
                              gpointer user_data);

Traverses a tree starting from `self` . It calls the given function for each node visited.

The traversal can be halted at any point by returning TRUE from `func` .

#### Parameters

self | a XbBuilderNode |
order | a GTraverseType, e.g. `G_PRE_ORDER` |
flags | a GTraverseFlags, e.g. `G_TRAVERSE_ALL` |
max_depth | the maximum depth of the traversal, or -1 for no limit |
func | a XbBuilderNodeTraverseFunc. | [scope call]
user_data | user pointer to pass to `func` , or `NULL` |

Since: 0.1.1

### xb_builder_node_sort_children ()

    void
    xb_builder_node_sort_children (XbBuilderNode *self,
                                   XbBuilderNodeSortFunc func,
                                   gpointer user_data);

Sorts the node children using a custom sort function.

#### Parameters

self | a XbBuilderNode |
func | a XbBuilderNodeSortFunc. | [scope call]
user_data | user pointer to pass to `func` , or `NULL` |

Since: 0.1.3

### xb_builder_node_export ()

    gchar *
    xb_builder_node_export (XbBuilderNode *self,
                            XbNodeExportFlags flags,
                            GError **error);

Exports the node to XML.

#### Parameters

self | a XbBuilderNode |
flags | some XbNodeExportFlags, e.g. XB_NODE_EXPORT_FLAG_NONE |
error | the GError, or `NULL` |

#### Returns

XML data, or `NULL` for an error

Since: 0.1.5

### xb_builder_node_get_tokens ()

    GPtrArray *
    xb_builder_node_get_tokens (XbBuilderNode *self);

Gets the tokens of the builder node.

#### Parameters

self | a XbBuilderNode |

#### Returns

tokens.

[transfer none][element-type utf8][nullable]

Since: 0.3.1

### xb_builder_node_add_token ()

    void
    xb_builder_node_add_token (XbBuilderNode *self,
                               const gchar *token);

Adds a token to the builder node.

#### Parameters

self | a XbBuilderNode |
token | a new token |

Since: 0.3.1

## Types and Values

### XB_TYPE_BUILDER_NODE

    #define             XB_TYPE_BUILDER_NODE

### struct XbBuilderNodeClass

    struct XbBuilderNodeClass {
    	GObjectClass parent_class;
    };

### enum XbBuilderNodeFlags

The flags used when building a node.

#### Members

XB_BUILDER_NODE_FLAG_NONE |  |
XB_BUILDER_NODE_FLAG_IGNORE |  |
XB_BUILDER_NODE_FLAG_LITERAL_TEXT |  |
XB_BUILDER_NODE_FLAG_HAS_TEXT |  |
XB_BUILDER_NODE_FLAG_HAS_TAIL |  |
XB_BUILDER_NODE_FLAG_TOKENIZE_TEXT |  |
XB_BUILDER_NODE_FLAG_STRIP_TEXT |  |

### XbBuilderNode

    typedef struct _XbBuilderNode XbBuilderNode;