annotate src/xmlnode.h @ 11719:109ee3bfeac5

[gaim-migrate @ 14010] SF Patch #1333770 from corfe83 "Many times in gaim we use the function g_slist_remove(list,node->data) to remove an element from a GSList. If we already have the pointer to the node we want to delete, it is faster to send it the pointer to the node to delete rather than the data of the node (we can do this by calling g_slist_delete_link(list,node)). This change was made while looking at glib's documentation and the code in glib's gslist.c. This is because as the remove/delete function traverses each node in the list, it doesn't need to spend an extra memory access to retrieve the data for each element in the node it is traversing and then compare, it can simply compare the pointer. In my tests outside of gaim, this makes a big difference if the node you are deleting is at a high index in the list. However, even if you're deleting the first node, it about breaks even. So, I've found each case in gaim where we are calling g_slist_remove, and we already have the pointer to the appropriate node to delete (this is often the case when we're doing a for or while loop on a GSList). I've then replaced it with the appropriate call to g_slist_delete_link. I, however, didn't do this in situations where we are explicitly removing the first element in the list, because in those situations it is an unnecessary change. There should be no difference in behavior, but just in case I've tried running it with valgrind, which reports the same number of memory leaks after my patch as before my patch. Of course, I can't guarantee that my normal behavior on gaim is hitting all the functions I've changed, but in general testing it Works For Me (tm)." As with the last patch, this one may not have a practical performance impact (or maybe it does, I have no idea), but it's not worse for any case. Given two ways of doing things where one is always at least as fast and may be faster under some cases, I like to prefer that faster way. This doesn't make the code any uglier, so I'm applying. committer: Tailor Script <[e-mail]>

/**
 * @file xmlnode.h XML DOM functions
 * @ingroup core
 *
 * gaim
 *
 * Gaim is the legal property of its developers, whose names are too numerous
 * to list here.  Please refer to the COPYRIGHT file distributed with this
 * source distribution.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
#ifndef _GAIM_XMLNODE_H_
#define _GAIM_XMLNODE_H_

/**
 * The valid types for an xmlnode
 */
typedef enum _XMLNodeType
{
	XMLNODE_TYPE_TAG,		/**< Just a tag */
	XMLNODE_TYPE_ATTRIB,	/**< Has attributes */
	XMLNODE_TYPE_DATA		/**< Has data */
} XMLNodeType;

/**
 * An xmlnode.
 */
typedef struct _xmlnode
{
	char *name;					/**< The name of the node. */
	XMLNodeType type;			/**< The type of the node. */
	char *data;					/**< The data for the node. */
	size_t data_sz;				/**< The size of the data. */
	struct _xmlnode *parent;	/**< The parent node or @c NULL.*/
	struct _xmlnode *child;		/**< The child node or @c NULL.*/
	struct _xmlnode *next;		/**< The next node or @c NULL. */
} xmlnode;

/**
 * Creates a new xmlnode.
 *
 * @param name The name of the node.
 *
 * @return The new node.
 */
xmlnode *xmlnode_new(const char *name);

/**
 * Creates a new xmlnode child.
 *
 * @param parent The parent node.
 * @param name   The name of the child node.
 *
 * @return The new child node.
 */
xmlnode *xmlnode_new_child(xmlnode *parent, const char *name);

/**
 * Inserts a node into a node as a child.
 *
 * @param parent The parent node to insert child into.
 * @param child  The child node to insert into parent.
 */
void xmlnode_insert_child(xmlnode *parent, xmlnode *child);

/**
 * Gets a child node named name.
 *
 * @param parent The parent node.
 * @param name   The child's name.
 *
 * @return The child or NULL.
 */
xmlnode *xmlnode_get_child(const xmlnode *parent, const char *name);

/**
 * Gets a child node named name in a namespace.
 *
 * @param parent The parent node.
 * @param name   The child's name.
 * @param xmlns  The namespace.
 *
 * @return The child or NULL.
 */
xmlnode *xmlnode_get_child_with_namespace(const xmlnode *parent, const char *name, const char *xmlns);

/**
 * Gets the next node with the same name as node.
 *
 * @param node The node of a twin to find.
 *
 * @return The twin of node or NULL.
 */
xmlnode *xmlnode_get_next_twin(xmlnode *node);

/**
 * Inserts data into a node.
 *
 * @param node   The node to insert data into.
 * @param data   The data to insert.
 * @param size   The size of the data to insert.  If data is
 *               null-terminated you can pass in -1.
 */
void xmlnode_insert_data(xmlnode *node, const char *data, gssize size);

/**
 * Gets data from a node.
 *
 * @param node The node to get data from.
 *
 * @return The data from the node.
 */
char *xmlnode_get_data(xmlnode *node);

/**
 * Sets an attribute for a node.
 *
 * @param node  The node to set an attribute for.
 * @param attr  The name of the attribute.
 * @param value The value of the attribute.
 */
void xmlnode_set_attrib(xmlnode *node, const char *attr, const char *value);

/**
 * Gets an attribute from a node.
 *
 * @param node The node to get an attribute from.
 * @param attr The attribute to get.
 *
 * @return The value of the attribute.
 */
const char *xmlnode_get_attrib(xmlnode *node, const char *attr);

/**
 * Removes an attribute from a node.
 *
 * @param node The node to remove an attribute from.
 * @param attr The attribute to remove.
 */
void xmlnode_remove_attrib(xmlnode *node, const char *attr);

/**
 * Returns the node in a string of xml.
 *
 * @param node The starting node to output.
 * @param len  Address for the size of the string.
 *
 * @return The node repersented as a string.  You must
 *         g_free this string when finished using it.
 */
char *xmlnode_to_str(xmlnode *node, int *len);

/**
 * Returns the node in a string of human readable xml.
 *
 * @param node The starting node to output.
 * @param len  Address for the size of the string.
 *
 * @return The node as human readable string including
 *         tab and new line characters.  You must
 *         g_free this string when finished using it.
 */
char *xmlnode_to_formatted_str(xmlnode *node, int *len);

/**
 * Creates a node from a string of XML.  Calling this on the
 * root node of an XML document will parse the entire document
 * into a tree of nodes, and return the xmlnode of the root.
 *
 * @param str  The string of xml.
 * @param size The size of the string, or -1 if @a str is
 *             NUL-terminated.
 *
 * @return The new node.
 */
xmlnode *xmlnode_from_str(const char *str, gssize size);

/**
 * Creates a new node from the source node.
 *
 * @param src The node to copy.
 *
 * @return A new copy of the src node.
 */
xmlnode *xmlnode_copy(xmlnode *src);

/**
 * Frees a node and all of it's children.
 *
 * @param node The node to free.
 */
void xmlnode_free(xmlnode *node);

#endif /* _GAIM_XMLNODE_H_ */