1 /** 2 * @file XMLNode.h 3 * @brief Class definition of XMLNode, a node in an XML document tree. 4 * @author Ben Bornstein 5 * 6 * <!-------------------------------------------------------------------------- 7 * This file is part of libSBML. Please visit http://sbml.org for more 8 * information about SBML, and the latest version of libSBML. 9 * 10 * Copyright (C) 2020 jointly by the following organizations: 11 * 1. California Institute of Technology, Pasadena, CA, USA 12 * 2. University of Heidelberg, Heidelberg, Germany 13 * 3. University College London, London, UK 14 * 15 * Copyright (C) 2019 jointly by the following organizations: 16 * 1. California Institute of Technology, Pasadena, CA, USA 17 * 2. University of Heidelberg, Heidelberg, Germany 18 * 19 * Copyright (C) 2013-2018 jointly by the following organizations: 20 * 1. California Institute of Technology, Pasadena, CA, USA 21 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 22 * 3. University of Heidelberg, Heidelberg, Germany 23 * 24 * Copyright (C) 2009-2013 jointly by the following organizations: 25 * 1. California Institute of Technology, Pasadena, CA, USA 26 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 27 * 28 * Copyright (C) 2006-2008 by the California Institute of Technology, 29 * Pasadena, CA, USA 30 * 31 * Copyright (C) 2002-2005 jointly by the following organizations: 32 * 1. California Institute of Technology, Pasadena, CA, USA 33 * 2. Japan Science and Technology Agency, Japan 34 * 35 * This library is free software; you can redistribute it and/or modify it 36 * under the terms of the GNU Lesser General Public License as published by 37 * the Free Software Foundation. A copy of the license agreement is provided 38 * in the file named "LICENSE.txt" included with this software distribution and 39 * also available online as http://sbml.org/software/libsbml/license.html 40 * ---------------------------------------------------------------------- --> 41 * 42 * @class XMLNode 43 * @sbmlbrief{core} A node in libSBML's XML document tree. 44 * 45 * LibSBML implements an XML abstraction layer. This layer presents a 46 * uniform XML interface to calling programs regardless of which underlying 47 * XML parser libSBML has actually been configured to use. The basic data 48 * object in the XML abstraction is a @em node, represented by XMLNode. 49 * 50 * An XMLNode can contain any number of children. Each child is another 51 * XMLNode, thereby forming a tree. The methods XMLNode::getNumChildren() 52 * and XMLNode::getChild(@if java long@endif) can be used to access the tree 53 * structure starting from a given node. 54 * 55 * Each XMLNode is subclassed from XMLToken, and thus has the same methods 56 * available as XMLToken. These methods include XMLToken::getNamespaces(), 57 * XMLToken::getPrefix(), XMLToken::getName(), XMLToken::getURI(), and 58 * XMLToken::getAttributes(). 59 * 60 * @section xmlnode-str2xmlnode Conversion between an XML string and an XMLNode 61 * 62 * LibSBML provides the following utility functions for converting an XML 63 * string (e.g., <code><annotation>...</annotation></code>) 64 * to/from an XMLNode object. 65 * 66 * @li XMLNode::toXMLString() returns a string representation of the XMLNode 67 * object. 68 * 69 * @li XMLNode::convertXMLNodeToString(@if java XMLNode@endif) (static 70 * function) returns a string representation of the given XMLNode object. 71 * 72 * @li XMLNode::convertStringToXMLNode(@if java String@endif) (static 73 * function) returns an XMLNode object converted from the given XML string. 74 * 75 * The returned XMLNode object by XMLNode::convertStringToXMLNode(@if java 76 * String@endif) is a dummy root (container) XMLNode if the given XML string 77 * has two or more top-level elements (e.g., 78 * "<code><p>...</p><p>...</p></code>"). In 79 * the dummy root node, each top-level element in the given XML string is 80 * contained as a child XMLNode. XMLToken::isEOF() can be used to identify 81 * if the returned XMLNode object is a dummy node or not. Here is an 82 * example: 83 @if cpp 84 @code{.cpp} 85 // Checks if the XMLNode object returned by XMLNode::convertStringToXMLNode() 86 // is a dummy root node: 87 88 std::string str = "..."; 89 XMLNode* xn = XMLNode::convertStringToXMLNode(str); 90 if ( xn == NULL ) 91 { 92 // returned value is null (error) 93 ... 94 } 95 else if ( xn->isEOF() ) 96 { 97 // Root node is a dummy node. 98 for ( int i = 0; i < xn->getNumChildren(); i++ ) 99 { 100 // access to each child node of the dummy node. 101 XMLNode& xnChild = xn->getChild(i); 102 ... 103 } 104 } 105 else 106 { 107 // Root node is NOT a dummy node. 108 ... 109 } 110 @endcode 111 @endif 112 @if java 113 @code{.java} 114 // Checks if the returned XMLNode object is a dummy root node: 115 116 String str = "..."; 117 XMLNode xn = XMLNode.convertStringToXMLNode(str); 118 if ( xn == null ) 119 { 120 // returned value is null (error) 121 ... 122 } 123 else if ( xn.isEOF() ) 124 { 125 // Root node is a dummy node. 126 for ( int i = 0; i < xn.getNumChildren(); i++ ) 127 { 128 // access to each child node of the dummy node. 129 XMLNode xnChild = xn.getChild(i); 130 ... 131 } 132 } 133 else 134 { 135 // Root node is NOT a dummy node. 136 ... 137 } 138 @endcode 139 @endif 140 @if python 141 @code{.py} 142 xn = XMLNode.convertStringToXMLNode("<p></p>") 143 if xn == None: 144 # Do something to handle exceptional situation. 145 146 elif xn.isEOF(): 147 # Node is a dummy node. 148 149 else: 150 # None is not a dummy node. 151 @endcode 152 @endif 153 * 154 */ 155 156 #ifndef XMLNode_h 157 #define XMLNode_h 158 159 #include <sbml/xml/XMLExtern.h> 160 #include <sbml/xml/XMLToken.h> 161 #include <sbml/common/sbmlfwd.h> 162 163 164 #ifdef __cplusplus 165 166 #include <vector> 167 #include <cstdlib> 168 169 LIBSBML_CPP_NAMESPACE_BEGIN 170 171 /** @cond doxygenLibsbmlInternal */ 172 class XMLInputStream; 173 class XMLOutputStream; 174 /** @endcond */ 175 176 177 class LIBLAX_EXTERN XMLNode : public XMLToken 178 { 179 public: 180 181 /** 182 * Creates a new empty XMLNode with no children. 183 */ 184 XMLNode (); 185 186 187 /** 188 * Creates a new XMLNode by copying an XMLToken object. 189 * 190 * @param token XMLToken to be copied to XMLNode. 191 */ 192 XMLNode (const XMLToken& token); 193 194 195 /** 196 * Creates a new start element XMLNode with the given set of attributes and 197 * namespace declarations. 198 * 199 * @param triple XMLTriple. 200 * @param attributes XMLAttributes, the attributes to set. 201 * @param namespaces XMLNamespaces, the namespaces to set. 202 * @param line an unsigned int, the line number (default = 0). 203 * @param column an unsigned int, the column number (default = 0). 204 * 205 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 206 */ 207 XMLNode ( const XMLTriple& triple 208 , const XMLAttributes& attributes 209 , const XMLNamespaces& namespaces 210 , const unsigned int line = 0 211 , const unsigned int column = 0 ); 212 213 214 /** 215 * Creates a start element XMLNode with the given set of attributes. 216 * 217 * @param triple XMLTriple. 218 * @param attributes XMLAttributes, the attributes to set. 219 * @param line an unsigned int, the line number (default = 0). 220 * @param column an unsigned int, the column number (default = 0). 221 * 222 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 223 */ 224 XMLNode ( const XMLTriple& triple 225 , const XMLAttributes& attributes 226 , const unsigned int line = 0 227 , const unsigned int column = 0 ); 228 229 230 /** 231 * Creates an end element XMLNode. 232 * 233 * @param triple XMLTriple. 234 * @param line an unsigned int, the line number (default = 0). 235 * @param column an unsigned int, the column number (default = 0). 236 * 237 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 238 */ 239 XMLNode ( const XMLTriple& triple 240 , const unsigned int line = 0 241 , const unsigned int column = 0 ); 242 243 244 /** 245 * Creates a text XMLNode. 246 * 247 * @param chars a string, the text to be added to the XMLToken. 248 * @param line an unsigned int, the line number (default = 0). 249 * @param column an unsigned int, the column number (default = 0). 250 * 251 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 252 */ 253 XMLNode ( const std::string& chars 254 , const unsigned int line = 0 255 , const unsigned int column = 0 ); 256 257 258 /** @cond doxygenLibsbmlInternal */ 259 /** 260 * Creates a new XMLNode by reading XMLTokens from stream. 261 * 262 * The stream must be positioned on a start element 263 * (<code>stream.peek().isStart() == true</code>) and will be read until 264 * the matching end element is found. 265 * 266 * @param stream XMLInputStream from which XMLNode is to be created. 267 */ 268 XMLNode (XMLInputStream& stream); 269 /** @endcond */ 270 271 272 /** 273 * Destroys this XMLNode. 274 */ 275 virtual ~XMLNode (); 276 277 278 /** 279 * Copy constructor; creates a copy of this XMLNode. 280 * 281 * @param orig the XMLNode instance to copy. 282 */ 283 XMLNode(const XMLNode& orig); 284 285 286 /** 287 * Assignment operator for XMLNode. 288 * 289 * @param rhs the XMLNode object whose values are used as the basis 290 * of the assignment. 291 */ 292 XMLNode& operator=(const XMLNode& rhs); 293 294 295 /** 296 * Creates and returns a deep copy of this XMLNode object. 297 * 298 * @return the (deep) copy of this XMLNode object. 299 */ 300 XMLNode* clone () const; 301 302 303 /** 304 * Adds a copy of @p node as a child of this XMLNode. 305 * 306 * The given @p node is added at the end of the list of children. 307 * 308 * @param node the XMLNode to be added as child. 309 * 310 * @copydetails doc_returns_success_code 311 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 312 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 313 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 314 * 315 * @note The given node is added at the end of the children list. 316 */ 317 int addChild (const XMLNode& node); 318 319 320 /** 321 * Inserts a copy of the given node as the <code>n</code>th child of this 322 * XMLNode. 323 * 324 * If the given index @p n is out of range for this XMLNode instance, 325 * the @p node is added at the end of the list of children. Even in 326 * that situation, this method does not throw an error. 327 * 328 * @param n an integer, the index at which the given node is inserted. 329 * @param node an XMLNode to be inserted as <code>n</code>th child. 330 * 331 * @return a reference to the newly-inserted child @p node. 332 */ 333 XMLNode& insertChild (unsigned int n, const XMLNode& node); 334 335 336 /** 337 * Removes the <code>n</code>th child of this XMLNode and returns the 338 * removed node. 339 * 340 * It is important to keep in mind that a given XMLNode may have more 341 * than one child. Calling this method erases all existing references to 342 * child nodes @em after the given position @p n. If the index @p n is 343 * greater than the number of child nodes in this XMLNode, this method 344 * takes no action (and returns @c NULL). 345 * 346 * @param n an integer, the index of the node to be removed. 347 * 348 * @return the removed child, or @c NULL if @p n is greater than the number 349 * of children in this node. 350 * 351 * @note The caller owns the returned node and is responsible for deleting it. 352 */ 353 XMLNode* removeChild(unsigned int n); 354 355 356 /** 357 * Removes all children from this node. 358 * @copydetails doc_returns_success_code 359 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 360 */ 361 int removeChildren(); 362 363 364 /** 365 * Returns the <code>n</code>th child of this XMLNode. 366 * 367 * If the index @p n is greater than the number of child nodes, 368 * this method returns an empty node. 369 * 370 * @param n an unsigned integer, the index of the node to return. 371 * 372 * @return the <code>n</code>th child of this XMLNode. 373 */ 374 XMLNode& getChild (unsigned int n); 375 376 377 /** 378 * Returns the <code>n</code>th child of this XMLNode. 379 * 380 * If the index @p n is greater than the number of child nodes, 381 * this method returns an empty node. 382 * 383 * @param n an unsigned integer, the index of the node to return. 384 * 385 * @return the <code>n</code>th child of this XMLNode. 386 */ 387 const XMLNode& getChild (unsigned int n) const; 388 389 390 /** 391 * Returns the first child of this XMLNode with the corresponding name. 392 * 393 * If no child with corrsponding name can be found, 394 * this method returns an empty node. 395 * 396 * @param name the name of the node to return. 397 * 398 * @return the first child of this XMLNode with given name. 399 */ 400 XMLNode& getChild (const std::string& name); 401 402 403 /** 404 * Returns the first child of this XMLNode with the corresponding name. 405 * 406 * If no child with corrsponding name can be found, 407 * this method returns an empty node. 408 * 409 * @param name the name of the node to return. 410 * 411 * @return the first child of this XMLNode with given name. 412 */ 413 const XMLNode& getChild (const std::string& name) const; 414 415 416 /** 417 * Return the index of the first child of this XMLNode with the given name. 418 * 419 * @param name a string, the name of the child for which the 420 * index is required. 421 * 422 * @return the index of the first child of this XMLNode with the given 423 * name, or @c -1 if not present. 424 */ 425 int getIndex (const std::string& name) const; 426 427 428 /** 429 * Return a boolean indicating whether this XMLNode has a child with the 430 * given name. 431 * 432 * @param name a string, the name of the child to be checked. 433 * 434 * @return boolean indicating whether this XMLNode has a child with the 435 * given name. 436 */ 437 bool hasChild (const std::string& name) const; 438 439 440 /** 441 * Compare this XMLNode against another XMLNode returning true if both 442 * nodes represent the same XML tree, or false otherwise. 443 * 444 * @param other another XMLNode to compare against. 445 * 446 * @param ignoreURI whether to ignore the namespace URI when doing the 447 * comparison. 448 * 449 * @param ignoreAttributeValues whetehr to ignore attribute values when 450 * doing the comparison. 451 * 452 * @return boolean indicating whether this XMLNode represents the same XML 453 * tree as another. 454 */ 455 bool equals(const XMLNode& other, bool ignoreURI=false, bool ignoreAttributeValues=false) const; 456 457 458 /** 459 * Returns the number of children for this XMLNode. 460 * 461 * @return the number of children for this XMLNode. 462 */ 463 unsigned int getNumChildren () const; 464 465 466 /** @cond doxygenLibsbmlInternal */ 467 /** 468 * Writes this XMLNode and its children to stream. 469 * 470 * @param stream XMLOutputStream, stream to which this XMLNode 471 * is to be written. 472 */ 473 void write (XMLOutputStream& stream) const; 474 475 /** @endcond */ 476 477 /** @cond doxygenLibsbmlInternal */ 478 479 void writeToStream(XMLOutputStream& stream) const; 480 481 /** @endcond */ 482 483 484 /** 485 * Returns a string representation of this XMLNode. 486 * 487 * @return a string derived from this XMLNode. 488 */ 489 std::string toXMLString() const; 490 491 492 /** 493 * Returns a string representation of a given XMLNode. 494 * 495 * @param node the XMLNode to be represented as a string. 496 * 497 * @return a string-form representation of @p node. 498 */ 499 static std::string convertXMLNodeToString(const XMLNode* node); 500 501 502 /** 503 * Returns an XMLNode which is derived from a string containing XML 504 * content. 505 * 506 * The XML namespace must be defined using argument @p xmlns if the 507 * corresponding XML namespace attribute is not part of the string of the 508 * first argument. 509 * 510 * @param xmlstr string to be converted to a XML node. 511 * @param xmlns XMLNamespaces the namespaces to set (default value is @c NULL). 512 * 513 * @note The caller owns the returned XMLNode and is reponsible for 514 * deleting it. The returned XMLNode object is a dummy root (container) 515 * XMLNode if the top-level element in the given XML string is NOT 516 * <code><html></code>, <code><body></code>, 517 * <code><annotation></code>, or <code><notes></code>. In 518 * the dummy root node, each top-level element in the given XML string is 519 * contained as a child XMLNode. XMLToken::isEOF() can be used to 520 * identify if the returned XMLNode object is a dummy node. 521 * 522 * @return a XMLNode which is converted from string @p xmlstr. If the 523 * conversion failed, this method returns @c NULL. 524 * 525 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 526 */ 527 static XMLNode* convertStringToXMLNode(const std::string& xmlstr, 528 const XMLNamespaces* xmlns = NULL); 529 530 531 #ifndef SWIG 532 533 /** @cond doxygenLibsbmlInternal */ 534 /** 535 * Inserts this XMLNode and its children into stream. 536 * 537 * @param stream XMLOutputStream, stream to which the XMLNode 538 * is to be written. 539 * @param node XMLNode, node to be written to stream. 540 * 541 * @return the stream with the node inserted. 542 */ 543 LIBLAX_EXTERN 544 friend 545 XMLOutputStream& operator<< (XMLOutputStream& stream, const XMLNode& node); 546 /** @endcond */ 547 548 #endif /* !SWIG */ 549 550 551 protected: 552 /** @cond doxygenLibsbmlInternal */ 553 std::vector<XMLNode*> mChildren; 554 555 /** @endcond */ 556 }; 557 558 LIBSBML_CPP_NAMESPACE_END 559 560 #endif /* __cplusplus */ 561 562 563 #ifndef SWIG 564 565 LIBSBML_CPP_NAMESPACE_BEGIN 566 BEGIN_C_DECLS 567 568 /** 569 * Creates a new empty XMLNode_t structure with no children 570 * and returns a pointer to it. 571 * 572 * @return pointer to the new XMLNode_t structure. 573 * 574 * @memberof XMLNode_t 575 */ 576 LIBLAX_EXTERN 577 XMLNode_t * 578 XMLNode_create (void); 579 580 581 /** 582 * Creates a new XMLNode_t structure by copying token and returns a pointer 583 * to it. 584 * 585 * @param token XMLToken_t structure to be copied to XMLNode_t structure. 586 * 587 * @return pointer to the new XMLNode_t structure. 588 * 589 * @memberof XMLNode_t 590 */ 591 LIBLAX_EXTERN 592 XMLNode_t * 593 XMLNode_createFromToken (const XMLToken_t *token); 594 595 596 /** 597 * Creates a new start element XMLNode_t structure with XMLTriple_t 598 * and XMLAttributes_t structures set and returns a pointer to it. 599 * 600 * @param triple XMLTriple_t structure to be set. 601 * @param attr XMLAttributes_t structure to be set. 602 * 603 * @return pointer to new XMLNode_t structure. 604 * 605 * @memberof XMLNode_t 606 */ 607 LIBLAX_EXTERN 608 XMLNode_t * 609 XMLNode_createStartElement (const XMLTriple_t *triple, 610 const XMLAttributes_t *attr); 611 612 613 /** 614 * Creates a new start element XMLNode_t structure with XMLTriple_t, 615 * XMLAttributes_t and XMLNamespaces_t structures set and returns a 616 * pointer to it. 617 * 618 * @param triple XMLTriple_t structure to be set. 619 * @param attr XMLAttributes_t structure to be set. 620 * @param ns XMLNamespaces_t structure to be set. 621 * 622 * @return pointer to new XMLNode_t structure. 623 * 624 * @memberof XMLNode_t 625 */ 626 LIBLAX_EXTERN 627 XMLNode_t * 628 XMLNode_createStartElementNS (const XMLTriple_t *triple, 629 const XMLAttributes_t *attr, 630 const XMLNamespaces_t *ns); 631 632 633 /** 634 * Creates a new end element XMLNode_t structure with XMLTriple_t 635 * structure set and returns a pointer to it. 636 * 637 * @param triple XMLTriple_t structure to be set. 638 * 639 * @return pointer to new XMLNode_t structure. 640 * 641 * @memberof XMLNode_t 642 */ 643 LIBLAX_EXTERN 644 XMLNode_t * 645 XMLNode_createEndElement (const XMLTriple_t *triple); 646 647 /** 648 * Creates a text XMLNode_t. Defaults to creating the node with a line number of 0 and a column number of 0. 649 * 650 * @param text the text to be added to the XMLToken_t. 651 * 652 * @memberof XMLNode_t 653 */ 654 LIBLAX_EXTERN 655 XMLNode_t * 656 XMLNode_createTextNode (const char *text); 657 658 659 /** 660 * Creates a deep copy of the given XMLNode_t structure 661 * 662 * @param n the XMLNode_t structure to be copied. 663 * 664 * @return a (deep) copy of the given XMLNode_t structure. 665 * 666 * @memberof XMLNode_t 667 */ 668 LIBLAX_EXTERN 669 XMLNode_t * 670 XMLNode_clone (const XMLNode_t* n); 671 672 673 /** 674 * Destroys this XMLNode_t structure. 675 * 676 * @param node XMLNode_t structure to be freed. 677 * 678 * @memberof XMLNode_t 679 */ 680 LIBLAX_EXTERN 681 void 682 XMLNode_free (XMLNode_t *node); 683 684 685 /** 686 * Adds a copy of child node to this XMLNode_t structure. 687 * 688 * @param node XMLNode_t structure to which child is to be added. 689 * @param child XMLNode_t structure to be added as child. 690 * 691 * @copydetails doc_returns_success_code 692 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 693 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 694 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 695 * 696 * @memberof XMLNode_t 697 */ 698 LIBLAX_EXTERN 699 int 700 XMLNode_addChild (XMLNode_t *node, const XMLNode_t *child); 701 702 703 /** 704 * Inserts a copy of child node to this XMLNode_t structure. 705 * 706 * @param node XMLNode_t structure to which child is to be added. 707 * @param n the index at which the given node is inserted. 708 * @param child XMLNode_t structure to be inserted as nth child. 709 * 710 * @return the newly inserted child in this XMLNode_t. 711 * @c NULL will be returned if the given child is @c NULL. 712 * 713 * @memberof XMLNode_t 714 */ 715 LIBLAX_EXTERN 716 XMLNode_t* 717 XMLNode_insertChild (XMLNode_t *node, unsigned int n, const XMLNode_t *child); 718 719 720 /** 721 * Removes the nth child of this XMLNode_t and returned the removed node. 722 * 723 * @param node XMLNode_t structure to which child is to be removed. 724 * @param n the index of the node to be removed. 725 * 726 * @return the removed child, or @c NULL if the given index is out of range. 727 * 728 * @note This function invalidates all existing references to child nodes 729 * after the position or first. 730 * 731 * @memberof XMLNode_t 732 */ 733 LIBLAX_EXTERN 734 XMLNode_t* 735 XMLNode_removeChild(XMLNode_t *node, unsigned int n); 736 737 738 /** 739 * Removes all children from this node. 740 * 741 * @param node XMLNode_t structure whose children to remove. 742 * 743 * @copydetails doc_returns_success_code 744 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 745 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 746 * 747 * @memberof XMLNode_t 748 */ 749 LIBLAX_EXTERN 750 int 751 XMLNode_removeChildren (XMLNode_t *node); 752 753 754 /** 755 * Returns the text of this element. 756 * 757 * @param node XMLNode_t structure to be queried. 758 * 759 * @return the characters of this XML text. 760 * 761 * @memberof XMLNode_t 762 */ 763 LIBLAX_EXTERN 764 const char * 765 XMLNode_getCharacters (const XMLNode_t *node); 766 767 768 /** 769 * Sets the XMLTripe_t (name, uri and prefix) of this XML element. 770 * Nothing will be done if this XML element is a text node. 771 * 772 * @param node XMLNode_t structure to which the triple to be added. 773 * @param triple an XMLTriple_t, the XML triple to be set to this XML element. 774 * 775 * @copydetails doc_returns_success_code 776 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 777 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 778 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 779 * 780 * @memberof XMLNode_t 781 */ 782 LIBLAX_EXTERN 783 int 784 XMLNode_setTriple(XMLNode_t *node, const XMLTriple_t *triple); 785 786 787 /** 788 * Returns the (unqualified) name of this XML element. 789 * 790 * @param node XMLNode_t structure to be queried. 791 * 792 * @return the (unqualified) name of this XML element. 793 * 794 * @memberof XMLNode_t 795 */ 796 LIBLAX_EXTERN 797 const char * 798 XMLNode_getName (const XMLNode_t *node); 799 800 801 /** 802 * Returns the namespace prefix of this XML element. 803 * 804 * @param node XMLNode_t structure to be queried. 805 * 806 * @return the namespace prefix of this XML element. 807 * 808 * @note If no prefix 809 * exists, an empty string will be return. 810 * 811 * @memberof XMLNode_t 812 */ 813 LIBLAX_EXTERN 814 const char * 815 XMLNode_getPrefix (const XMLNode_t *node); 816 817 818 /** 819 * Returns the namespace URI of this XML element. 820 * 821 * @param node XMLNode_t structure to be queried. 822 * 823 * @return the namespace URI of this XML element. 824 * 825 * @memberof XMLNode_t 826 */ 827 LIBLAX_EXTERN 828 const char * 829 XMLNode_getURI (const XMLNode_t *node); 830 831 832 /** 833 * Returns the nth child of this XMLNode_t structure. 834 * 835 * @param node XMLNode_t structure to be queried. 836 * @param n the index of the node to return. 837 * 838 * @return the nth child of this XMLNode_t structure. 839 * If the index @p n is invalid, @c NULL is returned. 840 * 841 * @memberof XMLNode_t 842 */ 843 LIBLAX_EXTERN 844 const XMLNode_t * 845 XMLNode_getChild (const XMLNode_t *node, const int n); 846 847 848 /** 849 * Returns the (non-const) nth child of this XMLNode_t structure. 850 * 851 * @param node XMLNode_t structure to be queried. 852 * @param n the index of the node to return. 853 * 854 * @return the non-const nth child of this XMLNode_t structure. 855 * 856 * @memberof XMLNode_t 857 */ 858 LIBLAX_EXTERN 859 XMLNode_t * 860 XMLNode_getChildNC (XMLNode_t *node, const unsigned int n); 861 862 /** 863 * Returns the (non-const) the first child of the XMLNode_t structure node with the given name. 864 * 865 * If no child with corrsponding name can be found, 866 * this method returns an empty node. 867 * 868 * @param node XMLNode_t structure to be queried. 869 * @param name the name of the node to return. 870 * 871 * @return the first child of this XMLNode_t with given name. 872 * 873 * @memberof XMLNode_t 874 */ 875 LIBLAX_EXTERN 876 XMLNode_t * 877 XMLNode_getChildForNameNC (XMLNode_t *node, const char* name); 878 879 /** 880 * Returns the first child of the XMLNode_t structure node with the given name. 881 * 882 * If no child with corrsponding name can be found, 883 * this method returns an empty node. 884 * 885 * @param node XMLNode_t structure to be queried. 886 * @param name the name of the node to return. 887 * 888 * @return the first child of this XMLNode_t with given name. 889 * 890 * @memberof XMLNode_t 891 */ 892 LIBLAX_EXTERN 893 const XMLNode_t * 894 XMLNode_getChildForName (const XMLNode_t *node, const char* name); 895 896 /** 897 * Return the index of the first child of the XMLNode_t structure node with the given name. 898 * 899 * @param node XMLNode_t structure to be queried. 900 * @param name a string, the name of the child for which the 901 * index is required. 902 * 903 * @return the index of the first child of node with the given name, or @c -1 if not present. 904 * 905 * @memberof XMLNode_t 906 */ 907 LIBLAX_EXTERN 908 int 909 XMLNode_getIndex (const XMLNode_t *node, const char* name); 910 911 /** 912 \* Return @c 1 (true) or @c 0 (false) indicating whether node has a child with the given name. 913 * 914 * @param node XMLNode_t structure to be queried. 915 * @param name a string, the name of the child to be checked. 916 * 917 * @return @c 1 (true) if this node has a child with the given name @c 0 (false) otherwise. 918 * 919 * @memberof XMLNode_t 920 */ 921 LIBLAX_EXTERN 922 int 923 XMLNode_hasChild (const XMLNode_t *node, const char* name); 924 925 /** 926 * Compare one XMLNode against another XMLNode returning @c 1 (true) if both nodes 927 * represent the same XML tree, or @c 0 (false) otherwise. 928 * 929 * 930 * @param node the original XMLNode_t structure. 931 * @param other another XMLNode_t to compare against. 932 * 933 * @return @c 1 (true) if both nodes 934 * represent the same XML tree, or @c 0 (false) otherwise 935 * 936 * @memberof XMLNode_t 937 */ 938 LIBLAX_EXTERN 939 int 940 XMLNode_equals(const XMLNode_t *node, const XMLNode_t* other); 941 942 /** 943 * Returns the number of children for this XMLNode_t structure. 944 * 945 * @param node XMLNode_t structure to be queried. 946 * 947 * @return the number of children for this XMLNode_t structure. 948 * 949 * @memberof XMLNode_t 950 */ 951 LIBLAX_EXTERN 952 unsigned int 953 XMLNode_getNumChildren (const XMLNode_t *node); 954 955 956 /** 957 * Returns the attributes of this element. 958 * 959 * @param node XMLNode_t structure to be queried. 960 * 961 * @return the XMLAttributes_t of this XML element. 962 * 963 * @memberof XMLNode_t 964 */ 965 LIBLAX_EXTERN 966 const XMLAttributes_t * 967 XMLNode_getAttributes (const XMLNode_t *node); 968 969 970 /** 971 * Sets an XMLAttributes_t to this XMLNode_t. 972 * Nothing will be done if this XMLNode_t is not a start element. 973 * 974 * @param node XMLNode_t structure to which attributes to be set. 975 * @param attributes XMLAttributes to be set to this XMLNode_t. 976 * 977 * @copydetails doc_returns_success_code 978 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 979 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 980 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 981 * 982 * @note This function replaces the existing XMLAttributes_t with the new one. 983 * 984 * @memberof XMLNode_t 985 */ 986 LIBLAX_EXTERN 987 int 988 XMLNode_setAttributes (XMLNode_t *node, const XMLAttributes_t* attributes); 989 990 991 /** 992 * Adds an attribute with the given local name to the attribute set in this XMLNode_t. 993 * (namespace URI and prefix are empty) 994 * Nothing will be done if this XMLNode_t is not a start element. 995 * 996 * @param node XMLNode_t structure to which an attribute to be added. 997 * @param name a string, the local name of the attribute. 998 * @param value a string, the value of the attribute. 999 * 1000 * @copydetails doc_returns_success_code 1001 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1002 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1003 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1004 * 1005 * @note if the local name without namespace URI already exists in the 1006 * attribute set, its value will be replaced. 1007 * 1008 * 1009 * @memberof XMLNode_t 1010 */ 1011 LIBLAX_EXTERN 1012 int 1013 XMLNode_addAttr ( XMLNode_t *node, const char* name, const char* value ); 1014 1015 1016 /** 1017 * Adds an attribute with a prefix and namespace URI to the attribute set 1018 * in this XMLNode_t optionally 1019 * Nothing will be done if this XMLNode_t is not a start element. 1020 * 1021 * @param node XMLNode_t structure to which an attribute to be added. 1022 * @param name a string, the local name of the attribute. 1023 * @param value a string, the value of the attribute. 1024 * @param namespaceURI a string, the namespace URI of the attribute. 1025 * @param prefix a string, the prefix of the namespace. 1026 * 1027 * @copydetails doc_returns_success_code 1028 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1029 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1030 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1031 * 1032 * @note if local name with the same namespace URI already exists in the 1033 * attribute set, its value and prefix will be replaced. 1034 * 1035 * 1036 * @memberof XMLNode_t 1037 */ 1038 LIBLAX_EXTERN 1039 int 1040 XMLNode_addAttrWithNS ( XMLNode_t *node, const char* name 1041 , const char* value 1042 , const char* namespaceURI 1043 , const char* prefix ); 1044 1045 1046 /** 1047 * Adds an attribute with the given XMLTriple/value pair to the attribute set 1048 * in this XMLNode_t. 1049 * Nothing will be done if this XMLNode_t is not a start element. 1050 * 1051 * @note if local name with the same namespace URI already exists in the 1052 * attribute set, its value and prefix will be replaced. 1053 * 1054 * @param node XMLNode_t structure to which an attribute to be added. 1055 * @param triple an XMLTriple_t, the XML triple of the attribute. 1056 * @param value a string, the value of the attribute. 1057 * 1058 * @copydetails doc_returns_success_code 1059 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1060 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1061 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1062 * 1063 * @memberof XMLNode_t 1064 */ 1065 LIBLAX_EXTERN 1066 int 1067 XMLNode_addAttrWithTriple (XMLNode_t *node, const XMLTriple_t *triple, const char* value); 1068 1069 1070 /** 1071 * Removes an attribute with the given index from the attribute set in 1072 * this XMLNode_t. 1073 * Nothing will be done if this XMLNode_t is not a start element. 1074 * 1075 * @param node XMLNode_t structure from which an attribute to be removed. 1076 * @param n an integer the index of the resource to be deleted. 1077 * 1078 * @copydetails doc_returns_success_code 1079 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1080 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1081 * @li @sbmlconstant{LIBSBML_INDEX_EXCEEDS_SIZE, OperationReturnValues_t} 1082 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1083 * 1084 * @memberof XMLNode_t 1085 */ 1086 LIBLAX_EXTERN 1087 int 1088 XMLNode_removeAttr (XMLNode_t *node, int n); 1089 1090 1091 /** 1092 * Removes an attribute with the given local name (without namespace URI) 1093 * from the attribute set in this XMLNode_t. 1094 * Nothing will be done if this XMLNode_t is not a start element. 1095 * 1096 * @param node XMLNode_t structure from which an attribute to be removed. 1097 * @param name a string, the local name of the attribute. 1098 * 1099 * @copydetails doc_returns_success_code 1100 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1101 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1102 * @li @sbmlconstant{LIBSBML_INDEX_EXCEEDS_SIZE, OperationReturnValues_t} 1103 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1104 * 1105 * @memberof XMLNode_t 1106 */ 1107 LIBLAX_EXTERN 1108 int 1109 XMLNode_removeAttrByName (XMLNode_t *node, const char* name); 1110 1111 1112 /** 1113 * Removes an attribute with the given local name and namespace URI from 1114 * the attribute set in this XMLNode_t. 1115 * Nothing will be done if this XMLNode_t is not a start element. 1116 * 1117 * @param node XMLNode_t structure from which an attribute to be removed. 1118 * @param name a string, the local name of the attribute. 1119 * @param uri a string, the namespace URI of the attribute. 1120 * 1121 * @copydetails doc_returns_success_code 1122 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1123 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1124 * @li @sbmlconstant{LIBSBML_INDEX_EXCEEDS_SIZE, OperationReturnValues_t} 1125 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1126 * 1127 * @memberof XMLNode_t 1128 */ 1129 LIBLAX_EXTERN 1130 int 1131 XMLNode_removeAttrByNS (XMLNode_t *node, const char* name, const char* uri); 1132 1133 1134 /** 1135 * Removes an attribute with the given XMLTriple_t from the attribute set 1136 * in this XMLNode_t. 1137 * Nothing will be done if this XMLNode_t is not a start element. 1138 * 1139 * @param node XMLNode_t structure from which an attribute to be removed. 1140 * @param triple an XMLTriple_t, the XML triple of the attribute. 1141 * 1142 * @copydetails doc_returns_success_code 1143 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1144 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1145 * @li @sbmlconstant{LIBSBML_INDEX_EXCEEDS_SIZE, OperationReturnValues_t} 1146 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1147 * 1148 * @memberof XMLNode_t 1149 */ 1150 LIBLAX_EXTERN 1151 int 1152 XMLNode_removeAttrByTriple (XMLNode_t *node, const XMLTriple_t *triple); 1153 1154 1155 /** 1156 * Clears (deletes) all attributes in this XMLNode_t. 1157 * Nothing will be done if this XMLNode_t is not a start element. 1158 * 1159 * @param node XMLNode_t structure from which attributes to be cleared. 1160 * 1161 * @copydetails doc_returns_success_code 1162 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1163 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1164 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1165 * 1166 * @memberof XMLNode_t 1167 */ 1168 LIBLAX_EXTERN 1169 int 1170 XMLNode_clearAttributes(XMLNode_t *node); 1171 1172 1173 /** 1174 * Return the index of an attribute with the given local name and namespace URI. 1175 * 1176 * @param node XMLNode_t structure to be queried. 1177 * @param name a string, the local name of the attribute. 1178 * @param uri a string, the namespace URI of the attribute. 1179 * 1180 * @return the index of an attribute with the given local name and namespace URI, 1181 * or @c -1 if not present. 1182 * 1183 * 1184 * @memberof XMLNode_t 1185 */ 1186 LIBLAX_EXTERN 1187 int 1188 XMLNode_getAttrIndex (const XMLNode_t *node, const char* name, const char* uri); 1189 1190 1191 /** 1192 * Return the index of an attribute with the given XMLTriple_t. 1193 * 1194 * @param node XMLNode_t structure to be queried. 1195 * @param triple an XMLTriple_t, the XML triple of the attribute for which 1196 * the index is required. 1197 * 1198 * @return the index of an attribute with the given XMLTriple_t, or @c -1 if not present. 1199 * 1200 * @memberof XMLNode_t 1201 */ 1202 LIBLAX_EXTERN 1203 int 1204 XMLNode_getAttrIndexByTriple (const XMLNode_t *node, const XMLTriple_t *triple); 1205 1206 1207 /** 1208 * Return the number of attributes in the attributes set. 1209 * 1210 * @param node XMLNode_t structure to be queried. 1211 * 1212 * @return the number of attributes in the attributes set in this XMLNode_t. 1213 * 1214 * @memberof XMLNode_t 1215 */ 1216 LIBLAX_EXTERN 1217 int 1218 XMLNode_getAttributesLength (const XMLNode_t *node); 1219 1220 1221 /** 1222 * Return the local name of an attribute in the attributes set in this 1223 * XMLNode_t (by position). 1224 * 1225 * @param node XMLNode_t structure to be queried. 1226 * @param index an integer, the position of the attribute whose local name 1227 * is required. 1228 * 1229 * @return the local name of an attribute in this list (by position). 1230 * 1231 * @note If index 1232 * is out of range, an empty string will be returned. Use XMLNode_hasAttr() 1233 * to test for the attribute existence. 1234 * 1235 * @memberof XMLNode_t 1236 */ 1237 LIBLAX_EXTERN 1238 char* 1239 XMLNode_getAttrName (const XMLNode_t *node, int index); 1240 1241 1242 /** 1243 * Return the prefix of an attribute in the attribute set in this 1244 * XMLNode (by position). 1245 * 1246 * @param node XMLNode_t structure to be queried. 1247 * @param index an integer, the position of the attribute whose prefix is 1248 * required. 1249 * 1250 * @return the namespace prefix of an attribute in the attribute set 1251 * (by position). 1252 * 1253 * @note If index is out of range, an empty string will be 1254 * returned. Use XMLNode_hasAttr() to test for the attribute existence. 1255 * 1256 * @memberof XMLNode_t 1257 */ 1258 LIBLAX_EXTERN 1259 char* 1260 XMLNode_getAttrPrefix (const XMLNode_t *node, int index); 1261 1262 1263 /** 1264 * Return the prefixed name of an attribute in the attribute set in this 1265 * XMLNode (by position). 1266 * 1267 * @param node XMLNode_t structure to be queried. 1268 * @param index an integer, the position of the attribute whose prefixed 1269 * name is required. 1270 * 1271 * @return the prefixed name of an attribute in the attribute set 1272 * (by position). 1273 * 1274 * @note If index is out of range, an empty string will be 1275 * returned. Use XMLNode_hasAttr() to test for attribute existence. 1276 * 1277 * @memberof XMLNode_t 1278 */ 1279 LIBLAX_EXTERN 1280 char* 1281 XMLNode_getAttrPrefixedName (const XMLNode_t *node, int index); 1282 1283 1284 /** 1285 * Return the namespace URI of an attribute in the attribute set in this 1286 * XMLNode (by position). 1287 * 1288 * @param node XMLNode_t structure to be queried. 1289 * @param index an integer, the position of the attribute whose namespace 1290 * URI is required. 1291 * 1292 * @return the namespace URI of an attribute in the attribute set (by position). 1293 * 1294 * @note If index is out of range, an empty string will be returned. Use 1295 * XMLNode_hasAttr(index) to test for attribute existence. 1296 * 1297 * @memberof XMLNode_t 1298 */ 1299 LIBLAX_EXTERN 1300 char* 1301 XMLNode_getAttrURI (const XMLNode_t *node, int index); 1302 1303 1304 /** 1305 * Return the value of an attribute in the attribute set in this XMLNode_t 1306 * (by position). 1307 * 1308 * @param node XMLNode_t structure to be queried. 1309 * @param index an integer, the position of the attribute whose value is 1310 * required. 1311 * 1312 * @return the value of an attribute in the attribute set (by position). 1313 * 1314 * @note If index 1315 * is out of range, an empty string will be returned. Use XMLNode_hasAttr() 1316 * to test for attribute existence. 1317 * 1318 * @memberof XMLNode_t 1319 */ 1320 LIBLAX_EXTERN 1321 char* 1322 XMLNode_getAttrValue (const XMLNode_t *node, int index); 1323 1324 1325 /** 1326 * Return a value of an attribute with the given local name (without namespace URI). 1327 * 1328 * @param node XMLNode_t structure to be queried. 1329 * @param name a string, the local name of the attribute whose value is required. 1330 * 1331 * @return The attribute value as a string. 1332 * 1333 * @note If an attribute with the given local name (without namespace URI) 1334 * does not exist, an empty string will be returned. 1335 * Use XMLNode_hasAttr() to test for attribute existence. 1336 * 1337 * @memberof XMLNode_t 1338 */ 1339 LIBLAX_EXTERN 1340 char* 1341 XMLNode_getAttrValueByName (const XMLNode_t *node, const char* name); 1342 1343 1344 /** 1345 * Return a value of an attribute with the given local name and namespace URI. 1346 * 1347 * @param node XMLNode_t structure to be queried. 1348 * @param name a string, the local name of the attribute whose value is required. 1349 * @param uri a string, the namespace URI of the attribute. 1350 * 1351 * @return The attribute value as a string. 1352 * 1353 * @note If an attribute with the 1354 * given local name and namespace URI does not exist, an empty string will be 1355 * returned. 1356 * Use XMLNode_hasAttr(name, uri) to test for attribute existence. 1357 * 1358 * @memberof XMLNode_t 1359 */ 1360 LIBLAX_EXTERN 1361 char* 1362 XMLNode_getAttrValueByNS (const XMLNode_t *node, const char* name, const char* uri); 1363 1364 1365 /** 1366 * Return a value of an attribute with the given XMLTriple_t. 1367 * 1368 * @param node XMLNode_t structure to be queried. 1369 * @param triple an XMLTriple_t, the XML triple of the attribute whose 1370 * value is required. 1371 * 1372 * @return The attribute value as a string. 1373 * 1374 * @note If an attribute with the 1375 * given XMLTriple_t does not exist, an empty string will be returned. 1376 * Use XMLNode_hasAttr() to test for attribute existence. 1377 * 1378 * @memberof XMLNode_t 1379 */ 1380 LIBLAX_EXTERN 1381 char* 1382 XMLNode_getAttrValueByTriple (const XMLNode_t *node, const XMLTriple_t *triple); 1383 1384 1385 /** 1386 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1387 * an attribute with the given index exists in the attribute set in this 1388 * XMLNode. 1389 * 1390 * @param node XMLNode_t structure to be queried. 1391 * @param index an integer, the position of the attribute. 1392 * 1393 * @return @c 1 (true) if an attribute with the given index exists in 1394 * the attribute set in this XMLNode_t, @c 0 (false) otherwise. 1395 * 1396 * @memberof XMLNode_t 1397 */ 1398 LIBLAX_EXTERN 1399 int 1400 XMLNode_hasAttr (const XMLNode_t *node, int index); 1401 1402 1403 /** 1404 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1405 * an attribute with the given local name (without namespace URI) 1406 * exists in the attribute set in this XMLNode_t. 1407 * 1408 * @param node XMLNode_t structure to be queried. 1409 * @param name a string, the local name of the attribute. 1410 * 1411 * @return @c 1 (true) if an attribute with the given local name 1412 * (without namespace URI) exists in the attribute set in this XMLNode_t, 1413 * @c 0 (false) otherwise. 1414 * 1415 * @memberof XMLNode_t 1416 */ 1417 LIBLAX_EXTERN 1418 int 1419 XMLNode_hasAttrWithName (const XMLNode_t *node, const char* name); 1420 1421 /** 1422 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1423 * an attribute with the given local name and namespace URI exists 1424 * in the attribute set in this XMLNode_t. 1425 * 1426 * @param node XMLNode_t structure to be queried. 1427 * @param name a string, the local name of the attribute. 1428 * @param uri a string, the namespace URI of the attribute. 1429 * 1430 * @return @c 1 (true) if an attribute with the given local name 1431 * and namespace URI exists in the attribute set in this XMLNode_t, 1432 * @c 0 (false) otherwise. 1433 * 1434 * @memberof XMLNode_t 1435 */ 1436 LIBLAX_EXTERN 1437 int 1438 XMLNode_hasAttrWithNS (const XMLNode_t *node, const char* name, const char* uri); 1439 1440 1441 /** 1442 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1443 * an attribute with the given XML triple exists in the attribute set in 1444 * this XMLNode_t 1445 * 1446 * @param node XMLNode_t structure to be queried. 1447 * @param triple an XMLTriple_t, the XML triple of the attribute. 1448 * 1449 * @return @c 1 (true) if an attribute with the given XML triple exists 1450 * in the attribute set in this XMLNode_t, @c 0 (false) otherwise. 1451 * 1452 * 1453 * @memberof XMLNode_t 1454 */ 1455 LIBLAX_EXTERN 1456 int 1457 XMLNode_hasAttrWithTriple (const XMLNode_t *node, const XMLTriple_t *triple); 1458 1459 1460 /** 1461 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1462 * the attribute set in this XMLNode_t set is empty. 1463 * 1464 * @param node XMLNode_t structure to be queried. 1465 * 1466 * @return @c 1 (true) if the attribute set in this XMLNode_t is empty, 1467 * @c 0 (false) otherwise. 1468 * 1469 * @memberof XMLNode_t 1470 */ 1471 LIBLAX_EXTERN 1472 int 1473 XMLNode_isAttributesEmpty (const XMLNode_t *node); 1474 1475 1476 1477 /** 1478 * Returns the XML namespace declarations for this XML element. 1479 * 1480 * @param node XMLNode_t structure to be queried. 1481 * 1482 * @return the XML namespace declarations for this XML element. 1483 * 1484 * @memberof XMLNode_t 1485 */ 1486 LIBLAX_EXTERN 1487 const XMLNamespaces_t * 1488 XMLNode_getNamespaces (const XMLNode_t *node); 1489 1490 1491 /** 1492 * Sets an XMLnamespaces_t to this XML element. 1493 * Nothing will be done if this XMLNode_t is not a start element. 1494 * 1495 * @param node XMLNode_t structure to be queried. 1496 * @param namespaces XMLNamespaces_t to be set to this XMLNode_t. 1497 * 1498 * @copydetails doc_returns_success_code 1499 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1500 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1501 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1502 * 1503 * @note This function replaces the existing XMLNamespaces_t with the new one. 1504 * 1505 * @memberof XMLNode_t 1506 */ 1507 LIBLAX_EXTERN 1508 int 1509 XMLNode_setNamespaces(XMLNode_t *node, const XMLNamespaces_t* namespaces); 1510 1511 1512 /** 1513 * Appends an XML namespace prefix and URI pair to this XMLNode_t. 1514 * If there is an XML namespace with the given prefix in this XMLNode_t, 1515 * then the existing XML namespace will be overwritten by the new one. 1516 * Nothing will be done if this XMLNode_t is not a start element. 1517 * 1518 * @param node XMLNode_t structure to be queried. 1519 * @param uri a string, the uri for the namespace. 1520 * @param prefix a string, the prefix for the namespace. 1521 * 1522 * @copydetails doc_returns_success_code 1523 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1524 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1525 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1526 * 1527 * @memberof XMLNode_t 1528 */ 1529 LIBLAX_EXTERN 1530 int 1531 XMLNode_addNamespace (XMLNode_t *node, const char* uri, const char* prefix); 1532 1533 1534 /** 1535 * Removes an XML Namespace stored in the given position of the XMLNamespaces_t 1536 * of this XMLNode_t. 1537 * Nothing will be done if this XMLNode_t is not a start element. 1538 * 1539 * @param node XMLNode_t structure to be queried. 1540 * @param index an integer, position of the removed namespace. 1541 * 1542 * @copydetails doc_returns_success_code 1543 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1544 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1545 * @li @sbmlconstant{LIBSBML_INDEX_EXCEEDS_SIZE, OperationReturnValues_t} 1546 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1547 * 1548 * @memberof XMLNode_t 1549 */ 1550 LIBLAX_EXTERN 1551 int 1552 XMLNode_removeNamespace (XMLNode_t *node, int index); 1553 1554 1555 /** 1556 * Removes an XML Namespace with the given prefix. 1557 * Nothing will be done if this XMLNode_t is not a start element. 1558 * 1559 * @param node XMLNode_t structure to be queried. 1560 * @param prefix a string, prefix of the required namespace. 1561 * 1562 * @copydetails doc_returns_success_code 1563 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1564 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1565 * @li @sbmlconstant{LIBSBML_INDEX_EXCEEDS_SIZE, OperationReturnValues_t} 1566 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1567 * 1568 * @memberof XMLNode_t 1569 */ 1570 LIBLAX_EXTERN 1571 int 1572 XMLNode_removeNamespaceByPrefix (XMLNode_t *node, const char* prefix); 1573 1574 1575 /** 1576 * Clears (deletes) all XML namespace declarations in the XMLNamespaces_t 1577 * of this XMLNode_t. 1578 * Nothing will be done if this XMLNode_t is not a start element. 1579 * 1580 * @param node XMLNode_t structure to be queried. 1581 * 1582 * @copydetails doc_returns_success_code 1583 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1584 * @li @sbmlconstant{LIBSBML_INVALID_XML_OPERATION, OperationReturnValues_t} 1585 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1586 * 1587 * @memberof XMLNode_t 1588 */ 1589 LIBLAX_EXTERN 1590 int 1591 XMLNode_clearNamespaces (XMLNode_t *node); 1592 1593 1594 /** 1595 * Look up the index of an XML namespace declaration by URI. 1596 * 1597 * @param node XMLNode_t structure to be queried. 1598 * @param uri a string, uri of the required namespace. 1599 * 1600 * @return the index of the given declaration, or @c -1 if not present. 1601 * 1602 * @memberof XMLNode_t 1603 */ 1604 LIBLAX_EXTERN 1605 int 1606 XMLNode_getNamespaceIndex (const XMLNode_t *node, const char* uri); 1607 1608 1609 /** 1610 * Look up the index of an XML namespace declaration by @p prefix. 1611 * 1612 * @param node XMLNode_t structure to be queried. 1613 * @param prefix a string, prefix of the required namespace. 1614 * 1615 * @return the index of the given declaration, or @c -1 if not present. 1616 * 1617 * @memberof XMLNode_t 1618 */ 1619 LIBLAX_EXTERN 1620 int 1621 XMLNode_getNamespaceIndexByPrefix (const XMLNode_t *node, const char* prefix); 1622 1623 1624 /** 1625 * Returns the number of XML namespaces stored in the XMLNamespaces_t 1626 * of this XMLNode_t. 1627 * 1628 * @param node XMLNode_t structure to be queried. 1629 * 1630 * @return the number of namespaces in this list. 1631 * 1632 * @memberof XMLNode_t 1633 */ 1634 LIBLAX_EXTERN 1635 int 1636 XMLNode_getNamespacesLength (const XMLNode_t *node); 1637 1638 1639 /** 1640 * Look up the prefix of an XML namespace declaration by position. 1641 * 1642 * Callers should use getNamespacesLength() to find out how many 1643 * namespaces are stored in the XMLNamespaces. 1644 * 1645 * @param node XMLNode_t structure to be queried. 1646 * @param index an integer, position of the removed namespace. 1647 * 1648 * @return the prefix of an XML namespace declaration in the XMLNamespaces_t 1649 * (by position). 1650 * 1651 * @note returned char* should be freed with safe_free() by the caller. 1652 * 1653 * @memberof XMLNode_t 1654 */ 1655 LIBLAX_EXTERN 1656 char* 1657 XMLNode_getNamespacePrefix (const XMLNode_t *node, int index); 1658 1659 1660 /** 1661 * Look up the prefix of an XML namespace declaration by its URI. 1662 * 1663 * @param node XMLNode_t structure to be queried. 1664 * @param uri a string, uri of the required namespace. 1665 * 1666 * @return the prefix of an XML namespace declaration given its URI. 1667 * 1668 * @note returned char* should be freed with safe_free() by the caller. 1669 * 1670 * @memberof XMLNode_t 1671 */ 1672 LIBLAX_EXTERN 1673 char* 1674 XMLNode_getNamespacePrefixByURI (const XMLNode_t *node, const char* uri); 1675 1676 1677 /** 1678 * Look up the URI of an XML namespace declaration by its position. 1679 * 1680 * @param node XMLNode_t structure to be queried. 1681 * @param index an integer, position of the removed namespace. 1682 * 1683 * @return the URI of an XML namespace declaration in the XMLNamespaces_t 1684 * (by position). 1685 * 1686 * @note returned char* should be freed with safe_free() by the caller. 1687 * 1688 * @memberof XMLNode_t 1689 */ 1690 LIBLAX_EXTERN 1691 char* 1692 XMLNode_getNamespaceURI (const XMLNode_t *node, int index); 1693 1694 1695 /** 1696 * Look up the URI of an XML namespace declaration by its prefix. 1697 * 1698 * @param node XMLNode_t structure to be queried. 1699 * @param prefix a string, prefix of the required namespace. 1700 * 1701 * @return the URI of an XML namespace declaration given its prefix. 1702 * 1703 * @note returned char* should be freed with safe_free() by the caller. 1704 * 1705 * @memberof XMLNode_t 1706 */ 1707 LIBLAX_EXTERN 1708 char* 1709 XMLNode_getNamespaceURIByPrefix (const XMLNode_t *node, const char* prefix); 1710 1711 1712 /** 1713 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1714 * the XMLNamespaces_t of this XMLNode_t is empty. 1715 * 1716 * @param node XMLNode_t structure to be queried. 1717 * 1718 * @return @c 1 (true) if the XMLNamespaces_t of this XMLNode_t is empty, 1719 * @c 0 (false) otherwise. 1720 * 1721 * @memberof XMLNode_t 1722 */ 1723 LIBLAX_EXTERN 1724 int 1725 XMLNode_isNamespacesEmpty (const XMLNode_t *node); 1726 1727 1728 /** 1729 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1730 * an XML Namespace with the given URI is contained in the XMLNamespaces_t of 1731 * this XMLNode_t. 1732 * 1733 * @param node XMLNode_t structure to be queried. 1734 * @param uri a string, the uri for the namespace. 1735 * 1736 * @return @c 1 (true) if an XML Namespace with the given URI is 1737 * contained in the XMLNamespaces_t of this XMLNode_t, @c 0 (false) otherwise. 1738 * 1739 * @memberof XMLNode_t 1740 */ 1741 LIBLAX_EXTERN 1742 int 1743 XMLNode_hasNamespaceURI(const XMLNode_t *node, const char* uri); 1744 1745 1746 /** 1747 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1748 * an XML Namespace with the given prefix is contained in the XMLNamespaces_t of 1749 * this XMLNode_t. 1750 * 1751 * @param node XMLNode_t structure to be queried. 1752 * @param prefix a string, the prefix for the namespace. 1753 * 1754 * @return @c 1 (true) if an XML Namespace with the given URI is 1755 * contained in the XMLNamespaces_t of this XMLNode_t, @c 0 (false) otherwise. 1756 * 1757 * @memberof XMLNode_t 1758 */ 1759 LIBLAX_EXTERN 1760 int 1761 XMLNode_hasNamespacePrefix(const XMLNode_t *node, const char* prefix); 1762 1763 1764 /** 1765 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1766 * an XML Namespace with the given uri/prefix pair is contained in the 1767 * XMLNamespaces_t of this XMLNode_t. 1768 * 1769 * @param node XMLNode_t structure to be queried. 1770 * @param uri a string, the uri for the namespace. 1771 * @param prefix a string, the prefix for the namespace. 1772 * 1773 * @return @c 1 (true) if an XML Namespace with the given uri/prefix pair is 1774 * contained in the XMLNamespaces_t of this XMLNode_t, @c 0 (false) otherwise. 1775 * 1776 * @memberof XMLNode_t 1777 */ 1778 LIBLAX_EXTERN 1779 int 1780 XMLNode_hasNamespaceNS(const XMLNode_t *node, const char* uri, const char* prefix); 1781 1782 1783 /** 1784 * Returns a string which is converted from a given XMLNode_t. 1785 * 1786 * @param node XMLNode_t to be converted to a string. 1787 * 1788 * @return a string (char*) which is converted from a given XMLNode_t. 1789 * 1790 * @note returned char* should be freed with safe_free() by the caller. 1791 * 1792 * @memberof XMLNode_t 1793 */ 1794 LIBLAX_EXTERN 1795 char * 1796 XMLNode_toXMLString(const XMLNode_t *node); 1797 1798 1799 /** 1800 * Returns a string which is converted from a given XMLNode_t. 1801 * 1802 * @param node XMLNode_t to be converted to a string. 1803 * 1804 * @return a string (char*) which is converted from a given XMLNode_t. 1805 * 1806 * @note returned char* should be freed with safe_free() by the caller. 1807 * 1808 * @memberof XMLNode_t 1809 */ 1810 LIBLAX_EXTERN 1811 const char * 1812 XMLNode_convertXMLNodeToString(const XMLNode_t *node); 1813 1814 1815 /** 1816 * Returns an XMLNode_t pointer which is converted from a given string containing 1817 * XML content. 1818 * 1819 * XMLNamespaces (the second argument) must be given if the corresponding 1820 * xmlns attribute is not included in the string of the first argument. 1821 * 1822 * @param xml string to be converted to a XML node. 1823 * @param xmlns XMLNamespaces_t structure the namespaces to set. 1824 * 1825 * @return pointer to XMLNode_t structure which is converted from a given string. 1826 * 1827 * @memberof XMLNode_t 1828 */ 1829 LIBLAX_EXTERN 1830 XMLNode_t * 1831 XMLNode_convertStringToXMLNode(const char * xml, const XMLNamespaces_t* xmlns); 1832 1833 1834 /** 1835 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1836 * this XMLNode_t structure is an XML element. 1837 * 1838 * @param node XMLNode_t structure to be queried. 1839 * 1840 * @return @c 1 (true) if this XMLNode_t structure is an XML element, @c 0 (false) otherwise. 1841 * 1842 * @memberof XMLNode_t 1843 */ 1844 LIBLAX_EXTERN 1845 int 1846 XMLNode_isElement (const XMLNode_t *node); 1847 1848 1849 /** 1850 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1851 * this XMLNode_t structure is an XML end element. 1852 * 1853 * @param node XMLNode_t structure to be queried. 1854 * 1855 * @return @c 1 (true) if this XMLNode_t structure is an XML end element, @c 0 (false) otherwise. 1856 * 1857 * @memberof XMLNode_t 1858 */ 1859 LIBLAX_EXTERN 1860 int 1861 XMLNode_isEnd (const XMLNode_t *node); 1862 1863 1864 /** 1865 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1866 * this XMLNode_t structure is an XML end element for the given start element. 1867 * 1868 * @param node XMLNode_t structure to be queried. 1869 * @param element XMLNode_t structure, element for which query is made. 1870 * 1871 * @return @c 1 (true) if this XMLNode_t structure is an XML end element for the given 1872 * XMLNode_t structure start element, @c 0 (false) otherwise. 1873 * 1874 * @memberof XMLNode_t 1875 */ 1876 LIBLAX_EXTERN 1877 int 1878 XMLNode_isEndFor (const XMLNode_t *node, const XMLNode_t *element); 1879 1880 1881 /** 1882 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1883 * this XMLNode_t structure is an end of file marker. 1884 * 1885 * @param node XMLNode_t structure to be queried. 1886 * 1887 * @return @c 1 (true) if this XMLNode_t structure is an end of file (input) marker, @c 0 (false) 1888 * otherwise. 1889 * 1890 * @memberof XMLNode_t 1891 */ 1892 LIBLAX_EXTERN 1893 int 1894 XMLNode_isEOF (const XMLNode_t *node); 1895 1896 1897 /** 1898 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1899 * this XMLNode_t structure is an XML start element. 1900 * 1901 * @param node XMLNode_t structure to be queried. 1902 * 1903 * @return @c 1 (true) if this XMLNode_t structure is an XML start element, @c 0 (false) otherwise. 1904 * 1905 * @memberof XMLNode_t 1906 */ 1907 LIBLAX_EXTERN 1908 int 1909 XMLNode_isStart (const XMLNode_t *node); 1910 1911 1912 /** 1913 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1914 * this XMLNode_t structure is an XML text element. 1915 * 1916 * @param node XMLNode_t structure to be queried. 1917 * 1918 * @return @c 1 (true) if this XMLNode_t structure is an XML text element, @c 0 (false) otherwise. 1919 * 1920 * @memberof XMLNode_t 1921 */ 1922 LIBLAX_EXTERN 1923 int 1924 XMLNode_isText (const XMLNode_t *node); 1925 1926 1927 /** 1928 * Declares this XML start element is also an end element. 1929 * 1930 * @param node XMLNode_t structure to be set. 1931 * 1932 * @copydetails doc_returns_success_code 1933 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1934 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 1935 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1936 * 1937 * @memberof XMLNode_t 1938 */ 1939 LIBLAX_EXTERN 1940 int 1941 XMLNode_setEnd (XMLNode_t *node); 1942 1943 1944 /** 1945 * Declares this XMLNode_t structure is an end-of-file (input) marker. 1946 * 1947 * @param node XMLNode_t structure to be set. 1948 * 1949 * @copydetails doc_returns_success_code 1950 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1951 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 1952 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1953 * 1954 * @memberof XMLNode_t 1955 */ 1956 LIBLAX_EXTERN 1957 int 1958 XMLNode_setEOF (XMLNode_t *node); 1959 1960 1961 /** 1962 * Declares this XML start/end element is no longer an end element. 1963 * 1964 * @param node XMLNode_t structure to be set. 1965 * 1966 * @copydetails doc_returns_success_code 1967 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1968 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 1969 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1970 * 1971 * @memberof XMLNode_t 1972 */ 1973 LIBLAX_EXTERN 1974 int 1975 XMLNode_unsetEnd (XMLNode_t *node); 1976 1977 1978 END_C_DECLS 1979 LIBSBML_CPP_NAMESPACE_END 1980 1981 #endif /* !SWIG */ 1982 #endif /* XMLNode_h */ 1983