001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.0.10 004 * 005 * Do not make changes to this file unless you know what you are doing--modify 006 * the SWIG interface file instead. 007 * ----------------------------------------------------------------------------- */ 008 009package org.sbml.libsbml; 010 011/** 012 * A user-defined function in an SBML model. 013 <p> 014 * The {@link FunctionDefinition} structure associates an identifier with a 015 * function definition. This identifier can then be used as the function 016 * called in subsequent MathML content elsewhere in an SBML model. 017 <p> 018 * {@link FunctionDefinition} has one required attribute, 'id', to give the 019 * function a unique identifier by which other parts of an SBML model 020 * definition can refer to it. A {@link FunctionDefinition} instance can also have 021 * an optional 'name' attribute of type <code>string.</code> Identifiers and names 022 * must be used according to the guidelines described in the SBML 023 * specification (e.g., Section 3.3 in the Level 2 Version 4 024 * specification). 025 <p> 026 * {@link FunctionDefinition} has a 'math' subelement containing a MathML 027 * expression defining the function body. In SBML Level 2 and SBML 028 * Level 3 Version 1, that 'math' subelement is required; 029 * in SBML Level 3 Version 2, this restriction was relaxed, 030 * making the 'math' subelement optional. The content of this element can 031 * only be a MathML 'lambda' element. The 'lambda' element must begin with 032 * zero or more 'bvar' elements, followed by any other of the elements in 033 * the MathML subset allowed in SBML Level 2 <em>except</em> 'lambda' (i.e., a 034 * 'lambda' element cannot contain another 'lambda' element). This is the 035 * only place in SBML where a 'lambda' element can be used. The function 036 * defined by a {@link FunctionDefinition} is only available for use in other 037 * MathML elements that <em>follow</em> the {@link FunctionDefinition} definition in the 038 * model. (These restrictions prevent recursive and mutually-recursive 039 * functions from being expressed.) 040 <p> 041 * A further restriction on the content of 'math' is that it cannot contain 042 * references to variables other than the variables declared to the 043 * 'lambda' itself. That is, the contents of MathML 'ci' elements inside 044 * the body of the 'lambda' can only be the variables declared by its 045 * 'bvar' elements, or the identifiers of other {@link FunctionDefinition} 046 * instances in the model. This means must be written so that all 047 * variables or parameters used in the MathML content are passed to them 048 * via their function parameters. In SBML Level 2, this restriction 049 * applies also to the MathML <code>csymbol</code> elements for <em>time</em> and 050 * <em>delay</em>; in SBML Level 3, it additionally applies to the <code>csymbol</code> 051 * element for <em>avogadro</em>. 052 <p> 053 * In SBML Level 3 Version 2, if no math element is present in 054 * the {@link FunctionDefinition}, the function has no mathematical meaning 055 * defined in SBML Level 3 Core. This situation may arise when models 056 * are incomplete, or when additional meanings are provided by an SBML 057 * Level 3 package. 058 <p> 059 * @note Function definitions (also informally known as user-defined 060 * functions) were introduced in SBML Level 2. They have purposefully 061 * limited capabilities. A function cannot reference parameters or other 062 * model quantities outside of itself; values must be passed as parameters 063 * to the function. Moreover, recursive and mutually-recursive functions 064 * are not permitted. The purpose of these limitations is to balance power 065 * against complexity of implementation. With the restrictions as they 066 * are, function definitions could be implemented as textual 067 * substitutions—they are simply macros. Software implementations 068 * therefore do not need the full function-definition machinery typically 069 * associated with programming languages. 070 * <br><br> 071 * Another important point to note is {@link FunctionDefinition} does not 072 * have a separate attribute for defining the units of the value returned 073 * by the function. The units associated with the function's return value, 074 * when the function is called from within MathML expressions elsewhere in 075 * SBML, are simply the overall units of the expression in 076 * {@link FunctionDefinition}'s 'math' subelement when applied to the arguments 077 * supplied in the call to the function. Ascertaining these units requires 078 * performing dimensional analysis on the expression. (Readers may wonder 079 * why there is no attribute. The reason is that having a separate 080 * attribute for declaring the units would not only be redundant, but also 081 * lead to the potential for having conflicting information. In the case 082 * of a conflict between the declared units and those of the value actually 083 * returned by the function, the only logical resolution rule would be to 084 * assume that the correct units are those of the expression anyway.) 085 */ 086 087public class FunctionDefinition extends SBase { 088 private long swigCPtr; 089 090 protected FunctionDefinition(long cPtr, boolean cMemoryOwn) 091 { 092 super(libsbmlJNI.FunctionDefinition_SWIGUpcast(cPtr), cMemoryOwn); 093 swigCPtr = cPtr; 094 } 095 096 protected static long getCPtr(FunctionDefinition obj) 097 { 098 return (obj == null) ? 0 : obj.swigCPtr; 099 } 100 101 protected static long getCPtrAndDisown (FunctionDefinition obj) 102 { 103 long ptr = 0; 104 105 if (obj != null) 106 { 107 ptr = obj.swigCPtr; 108 obj.swigCMemOwn = false; 109 } 110 111 return ptr; 112 } 113 114 protected void finalize() { 115 delete(); 116 } 117 118 public synchronized void delete() { 119 if (swigCPtr != 0) { 120 if (swigCMemOwn) { 121 swigCMemOwn = false; 122 libsbmlJNI.delete_FunctionDefinition(swigCPtr); 123 } 124 swigCPtr = 0; 125 } 126 super.delete(); 127 } 128 129 130/** 131 * Creates a new {@link FunctionDefinition} using the given SBML <code>level</code> and <code>version</code> 132 * values. 133 <p> 134 * @param level a long integer, the SBML Level to assign to this {@link FunctionDefinition}. 135 <p> 136 * @param version a long integer, the SBML Version to assign to this 137 * {@link FunctionDefinition}. 138 <p> 139 * <p> 140 * @throws SBMLConstructorException 141 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid 142 * or if this object is incompatible with the given level and version. 143 <p> 144 * <p> 145 * @note Attempting to add an object to an {@link SBMLDocument} having a different 146 * combination of SBML Level, Version and XML namespaces than the object 147 * itself will result in an error at the time a caller attempts to make the 148 * addition. A parent object must have compatible Level, Version and XML 149 * namespaces. (Strictly speaking, a parent may also have more XML 150 * namespaces than a child, but the reverse is not permitted.) The 151 * restriction is necessary to ensure that an SBML model has a consistent 152 * overall structure. This requires callers to manage their objects 153 * carefully, but the benefit is increased flexibility in how models can be 154 * created by permitting callers to create objects bottom-up if desired. In 155 * situations where objects are not yet attached to parents (e.g., 156 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 157 * libSBML determine such things as whether it is valid to assign a 158 * particular value to an attribute. 159 */ public 160 FunctionDefinition(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 161 this(libsbmlJNI.new_FunctionDefinition__SWIG_0(level, version), true); 162 } 163 164 165/** 166 * Creates a new {@link FunctionDefinition} using the given {@link SBMLNamespaces} object 167 * <code>sbmlns</code>. 168 <p> 169 * <p> 170 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 171 * information. It is used to communicate the SBML Level, Version, and (in 172 * Level 3) packages used in addition to SBML Level 3 Core. A 173 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 174 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object 175 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 176 <p> 177 * @param sbmlns an {@link SBMLNamespaces} object. 178 <p> 179 * <p> 180 * @throws SBMLConstructorException 181 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible 182 * with this object. 183 <p> 184 * <p> 185 * @note Attempting to add an object to an {@link SBMLDocument} having a different 186 * combination of SBML Level, Version and XML namespaces than the object 187 * itself will result in an error at the time a caller attempts to make the 188 * addition. A parent object must have compatible Level, Version and XML 189 * namespaces. (Strictly speaking, a parent may also have more XML 190 * namespaces than a child, but the reverse is not permitted.) The 191 * restriction is necessary to ensure that an SBML model has a consistent 192 * overall structure. This requires callers to manage their objects 193 * carefully, but the benefit is increased flexibility in how models can be 194 * created by permitting callers to create objects bottom-up if desired. In 195 * situations where objects are not yet attached to parents (e.g., 196 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 197 * libSBML determine such things as whether it is valid to assign a 198 * particular value to an attribute. 199 */ public 200 FunctionDefinition(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 201 this(libsbmlJNI.new_FunctionDefinition__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 202 } 203 204 205/** 206 * Copy constructor; creates a copy of this {@link FunctionDefinition}. 207 <p> 208 * @param orig the object to copy. 209 */ public 210 FunctionDefinition(FunctionDefinition orig) throws org.sbml.libsbml.SBMLConstructorException { 211 this(libsbmlJNI.new_FunctionDefinition__SWIG_2(FunctionDefinition.getCPtr(orig), orig), true); 212 } 213 214 215/** 216 * Creates and returns a deep copy of this {@link FunctionDefinition} object. 217 <p> 218 * @return the (deep) copy of this {@link FunctionDefinition} object. 219 */ public 220 FunctionDefinition cloneObject() { 221 long cPtr = libsbmlJNI.FunctionDefinition_cloneObject(swigCPtr, this); 222 return (cPtr == 0) ? null : new FunctionDefinition(cPtr, true); 223 } 224 225 226/** 227 * Returns the value of the 'id' attribute of this {@link FunctionDefinition}. 228 <p> 229 * @note Because of the inconsistent behavior of this function with 230 * respect to assignments and rules, it is now recommended to 231 * use the getIdAttribute() function instead. 232 <p> 233 * <p> 234 * The identifier given by an object's 'id' attribute value 235 * is used to identify the object within the SBML model definition. 236 * Other objects can refer to the component using this identifier. The 237 * data type of 'id' is always <code>SId</code> or a type derived 238 * from that, such as <code>UnitSId</code>, depending on the object in 239 * question. All data types are defined as follows: 240 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'> 241 * letter .= 'a'..'z','A'..'Z' 242 * digit .= '0'..'9' 243 * idChar .= letter | digit | '_' 244 * SId .= ( letter | '_' ) idChar* 245 * </pre> 246 <p> 247 * The characters <code>(</code> and <code>)</code> are used for grouping, the 248 * character <code>*</code> 'zero or more times', and the character 249 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers is 250 * determined by an exact character sequence match; i.e., comparisons must be 251 * performed in a case-sensitive manner. This applies to all uses of <code>SId</code>, 252 * <code>SIdRef</code>, and derived types. 253 <p> 254 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 255 * moved to {@link SBase} directly, instead of being defined individually for many 256 * (but not all) objects. Libsbml has for a long time provided functions 257 * defined on {@link SBase} itself to get, set, check, and unset those attributes, which 258 * would fail or otherwise return empty strings if executed on any object 259 * for which those attributes were not defined. Now that all {@link SBase} objects 260 * define those attributes, those functions now succeed for any object with 261 * the appropriate level and version. 262 <p> 263 * The exception to this rule is that for {@link InitialAssignment}, {@link EventAssignment}, 264 * {@link AssignmentRule}, and {@link RateRule} objects, the getId() function and the isSetId() 265 * functions (though not the setId() or unsetId() functions) would instead 266 * reference the value of the 'variable' attribute (for the rules and event 267 * assignments) or the 'symbol' attribute (for initial assignments). 268 * The {@link AlgebraicRule} fell into this category as well, though because it 269 * contained neither a 'variable' nor a 'symbol' attribute, getId() would 270 * always return an empty string, and isSetId() would always return <code>false.</code> 271 * For this reason, four new functions are now provided 272 * (getIdAttribute(), setIdAttribute(String), 273 * isSetIdAttribute(), and unsetIdAttribute()) that will always 274 * act on the actual 'id' attribute, regardless of the object's type. The 275 * new functions should be used instead of the old ones unless the old behavior 276 * is somehow necessary. 277 <p> 278 * Regardless of the level and version of the SBML, these functions allow 279 * client applications to use more generalized code in some situations 280 * (for instance, when manipulating objects that are all known to have 281 * identifiers). If the object in question does not posess an 'id' attribute 282 * according to the SBML specification for the Level and Version in use, 283 * libSBML will not allow the identifier to be set, nor will it read or 284 * write 'id' attributes for those objects. 285 <p> 286 * @return the id of this {@link FunctionDefinition}. 287 <p> 288 * @see #getIdAttribute() 289 * @see #setIdAttribute(String sid) 290 * @see #isSetIdAttribute() 291 * @see #unsetIdAttribute() 292 */ public 293 String getId() { 294 return libsbmlJNI.FunctionDefinition_getId(swigCPtr, this); 295 } 296 297 298/** 299 * Returns the value of the 'name' attribute of this {@link FunctionDefinition} object. 300 <p> 301 * <p> 302 * <p> 303 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 304 * moved to {@link SBase} directly, instead of being defined individually for many 305 * (but not all) objects. Libsbml has for a long time provided functions 306 * defined on {@link SBase} itself to get, set, and unset those attributes, which 307 * would fail or otherwise return empty strings if executed on any object 308 * for which those attributes were not defined. Now that all {@link SBase} objects 309 * define those attributes, those functions now succeed for any object with 310 * the appropriate level and version. 311 <p> 312 * The 'name' attribute is 313 * optional and is not intended to be used for cross-referencing purposes 314 * within a model. Its purpose instead is to provide a human-readable 315 * label for the component. The data type of 'name' is the type 316 * <code>string</code> defined in XML Schema. SBML imposes no 317 * restrictions as to the content of 'name' attributes beyond those 318 * restrictions defined by the <code>string</code> type in XML Schema. 319 <p> 320 * The recommended practice for handling 'name' is as follows. If a 321 * software tool has the capability for displaying the content of 'name' 322 * attributes, it should display this content to the user as a 323 * component's label instead of the component's 'id'. If the user 324 * interface does not have this capability (e.g., because it cannot 325 * display or use special characters in symbol names), or if the 'name' 326 * attribute is missing on a given component, then the user interface 327 * should display the value of the 'id' attribute instead. (Script 328 * language interpreters are especially likely to display 'id' instead of 329 * 'name'.) 330 <p> 331 * As a consequence of the above, authors of systems that automatically 332 * generate the values of 'id' attributes should be aware some systems 333 * may display the 'id''s to the user. Authors therefore may wish to 334 * take some care to have their software create 'id' values that are: (a) 335 * reasonably easy for humans to type and read; and (b) likely to be 336 * meaningful, for example by making the 'id' attribute be an abbreviated 337 * form of the name attribute value. 338 <p> 339 * An additional point worth mentioning is although there are 340 * restrictions on the uniqueness of 'id' values, there are no 341 * restrictions on the uniqueness of 'name' values in a model. This 342 * allows software applications leeway in assigning component identifiers. 343 <p> 344 * Regardless of the level and version of the SBML, these functions allow 345 * client applications to use more generalized code in some situations 346 * (for instance, when manipulating objects that are all known to have 347 * names). If the object in question does not posess a 'name' attribute 348 * according to the SBML specification for the Level and Version in use, 349 * libSBML will not allow the name to be set, nor will it read or 350 * write 'name' attributes for those objects. 351 <p> 352 * @return the name of this SBML object, or the empty string if not set or unsettable. 353 <p> 354 * @see #getIdAttribute() 355 * @see #isSetName() 356 * @see #setName(String sid) 357 * @see #unsetName() 358 */ public 359 String getName() { 360 return libsbmlJNI.FunctionDefinition_getName(swigCPtr, this); 361 } 362 363 364/** 365 * Get the mathematical formula of this {@link FunctionDefinition}. 366 <p> 367 * @return an {@link ASTNode}, the value of the 'math' subelement of this 368 * {@link FunctionDefinition}, or <code>null</code> if the math is not set. 369 */ public 370 ASTNode getMath() { 371 long cPtr = libsbmlJNI.FunctionDefinition_getMath(swigCPtr, this); 372 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 373 } 374 375 376/** 377 * Predicate returning <code>true</code> if this 378 * {@link FunctionDefinition}'s 'id' attribute is set. 379 <p> 380 * <p> 381 * @note Because of the inconsistent behavior of this function with 382 * respect to assignments and rules, it is now recommended to 383 * use the isSetIdAttribute() function instead. 384 <p> 385 * <p> 386 * The identifier given by an object's 'id' attribute value 387 * is used to identify the object within the SBML model definition. 388 * Other objects can refer to the component using this identifier. The 389 * data type of 'id' is always <code>SId</code> or a type derived 390 * from that, such as <code>UnitSId</code>, depending on the object in 391 * question. All data types are defined as follows: 392 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'> 393 * letter .= 'a'..'z','A'..'Z' 394 * digit .= '0'..'9' 395 * idChar .= letter | digit | '_' 396 * SId .= ( letter | '_' ) idChar* 397 * </pre> 398 <p> 399 * The characters <code>(</code> and <code>)</code> are used for grouping, the 400 * character <code>*</code> 'zero or more times', and the character 401 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers is 402 * determined by an exact character sequence match; i.e., comparisons must be 403 * performed in a case-sensitive manner. This applies to all uses of <code>SId</code>, 404 * <code>SIdRef</code>, and derived types. 405 <p> 406 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 407 * moved to {@link SBase} directly, instead of being defined individually for many 408 * (but not all) objects. Libsbml has for a long time provided functions 409 * defined on {@link SBase} itself to get, set, check, and unset those attributes, which 410 * would fail or otherwise return empty strings if executed on any object 411 * for which those attributes were not defined. Now that all {@link SBase} objects 412 * define those attributes, those functions now succeed for any object with 413 * the appropriate level and version. 414 <p> 415 * The exception to this rule is that for {@link InitialAssignment}, {@link EventAssignment}, 416 * {@link AssignmentRule}, and {@link RateRule} objects, the getId() function and the isSetId() 417 * functions (though not the setId() or unsetId() functions) would instead 418 * reference the value of the 'variable' attribute (for the rules and event 419 * assignments) or the 'symbol' attribute (for initial assignments). 420 * The {@link AlgebraicRule} fell into this category as well, though because it 421 * contained neither a 'variable' nor a 'symbol' attribute, getId() would 422 * always return an empty string, and isSetId() would always return <code>false.</code> 423 * For this reason, four new functions are now provided 424 * (getIdAttribute(), setIdAttribute(String), 425 * isSetIdAttribute(), and unsetIdAttribute()) that will always 426 * act on the actual 'id' attribute, regardless of the object's type. The 427 * new functions should be used instead of the old ones unless the old behavior 428 * is somehow necessary. 429 <p> 430 * Regardless of the level and version of the SBML, these functions allow 431 * client applications to use more generalized code in some situations 432 * (for instance, when manipulating objects that are all known to have 433 * identifiers). If the object in question does not posess an 'id' attribute 434 * according to the SBML specification for the Level and Version in use, 435 * libSBML will not allow the identifier to be set, nor will it read or 436 * write 'id' attributes for those objects. 437 <p> 438 * @return <code>true</code> if the 'id' attribute of this SBML object is 439 * set, <code>false</code> otherwise. 440 <p> 441 * @see #getIdAttribute() 442 * @see #setIdAttribute(String sid) 443 * @see #unsetIdAttribute() 444 * @see #isSetIdAttribute() 445 */ public 446 boolean isSetId() { 447 return libsbmlJNI.FunctionDefinition_isSetId(swigCPtr, this); 448 } 449 450 451/** 452 * Predicate returning <code>true</code> if this 453 * {@link FunctionDefinition}'s 'name' attribute is set. 454 <p> 455 * <p> 456 * <p> 457 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 458 * moved to {@link SBase} directly, instead of being defined individually for many 459 * (but not all) objects. Libsbml has for a long time provided functions 460 * defined on {@link SBase} itself to get, set, and unset those attributes, which 461 * would fail or otherwise return empty strings if executed on any object 462 * for which those attributes were not defined. Now that all {@link SBase} objects 463 * define those attributes, those functions now succeed for any object with 464 * the appropriate level and version. 465 <p> 466 * The 'name' attribute is 467 * optional and is not intended to be used for cross-referencing purposes 468 * within a model. Its purpose instead is to provide a human-readable 469 * label for the component. The data type of 'name' is the type 470 * <code>string</code> defined in XML Schema. SBML imposes no 471 * restrictions as to the content of 'name' attributes beyond those 472 * restrictions defined by the <code>string</code> type in XML Schema. 473 <p> 474 * The recommended practice for handling 'name' is as follows. If a 475 * software tool has the capability for displaying the content of 'name' 476 * attributes, it should display this content to the user as a 477 * component's label instead of the component's 'id'. If the user 478 * interface does not have this capability (e.g., because it cannot 479 * display or use special characters in symbol names), or if the 'name' 480 * attribute is missing on a given component, then the user interface 481 * should display the value of the 'id' attribute instead. (Script 482 * language interpreters are especially likely to display 'id' instead of 483 * 'name'.) 484 <p> 485 * As a consequence of the above, authors of systems that automatically 486 * generate the values of 'id' attributes should be aware some systems 487 * may display the 'id''s to the user. Authors therefore may wish to 488 * take some care to have their software create 'id' values that are: (a) 489 * reasonably easy for humans to type and read; and (b) likely to be 490 * meaningful, for example by making the 'id' attribute be an abbreviated 491 * form of the name attribute value. 492 <p> 493 * An additional point worth mentioning is although there are 494 * restrictions on the uniqueness of 'id' values, there are no 495 * restrictions on the uniqueness of 'name' values in a model. This 496 * allows software applications leeway in assigning component identifiers. 497 <p> 498 * Regardless of the level and version of the SBML, these functions allow 499 * client applications to use more generalized code in some situations 500 * (for instance, when manipulating objects that are all known to have 501 * names). If the object in question does not posess a 'name' attribute 502 * according to the SBML specification for the Level and Version in use, 503 * libSBML will not allow the name to be set, nor will it read or 504 * write 'name' attributes for those objects. 505 <p> 506 * @return <code>true</code> if the 'name' attribute of this SBML object is 507 * set, <code>false</code> otherwise. 508 <p> 509 * @see #getName() 510 * @see #setName(String sid) 511 * @see #unsetName() 512 */ public 513 boolean isSetName() { 514 return libsbmlJNI.FunctionDefinition_isSetName(swigCPtr, this); 515 } 516 517 518/** 519 * Predicate returning <code>true</code> if this 520 * {@link FunctionDefinition}'s 'math' subelement contains a value. 521 <p> 522 * @return <code>true</code> if the 'math' for this {@link FunctionDefinition} is set, 523 * <code>false</code> otherwise. 524 */ public 525 boolean isSetMath() { 526 return libsbmlJNI.FunctionDefinition_isSetMath(swigCPtr, this); 527 } 528 529 530/** 531 * Sets the value of the 'id' attribute of this {@link FunctionDefinition}. 532 <p> 533 * <p> 534 * The string <code>sid</code> is copied. 535 <p> 536 * <p> 537 * The identifier given by an object's 'id' attribute value 538 * is used to identify the object within the SBML model definition. 539 * Other objects can refer to the component using this identifier. The 540 * data type of 'id' is always <code>SId</code> or a type derived 541 * from that, such as <code>UnitSId</code>, depending on the object in 542 * question. All data types are defined as follows: 543 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'> 544 * letter .= 'a'..'z','A'..'Z' 545 * digit .= '0'..'9' 546 * idChar .= letter | digit | '_' 547 * SId .= ( letter | '_' ) idChar* 548 * </pre> 549 <p> 550 * The characters <code>(</code> and <code>)</code> are used for grouping, the 551 * character <code>*</code> 'zero or more times', and the character 552 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers is 553 * determined by an exact character sequence match; i.e., comparisons must be 554 * performed in a case-sensitive manner. This applies to all uses of <code>SId</code>, 555 * <code>SIdRef</code>, and derived types. 556 <p> 557 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 558 * moved to {@link SBase} directly, instead of being defined individually for many 559 * (but not all) objects. Libsbml has for a long time provided functions 560 * defined on {@link SBase} itself to get, set, check, and unset those attributes, which 561 * would fail or otherwise return empty strings if executed on any object 562 * for which those attributes were not defined. Now that all {@link SBase} objects 563 * define those attributes, those functions now succeed for any object with 564 * the appropriate level and version. 565 <p> 566 * The exception to this rule is that for {@link InitialAssignment}, {@link EventAssignment}, 567 * {@link AssignmentRule}, and {@link RateRule} objects, the getId() function and the isSetId() 568 * functions (though not the setId() or unsetId() functions) would instead 569 * reference the value of the 'variable' attribute (for the rules and event 570 * assignments) or the 'symbol' attribute (for initial assignments). 571 * The {@link AlgebraicRule} fell into this category as well, though because it 572 * contained neither a 'variable' nor a 'symbol' attribute, getId() would 573 * always return an empty string, and isSetId() would always return <code>false.</code> 574 * For this reason, four new functions are now provided 575 * (getIdAttribute(), setIdAttribute(String), 576 * isSetIdAttribute(), and unsetIdAttribute()) that will always 577 * act on the actual 'id' attribute, regardless of the object's type. The 578 * new functions should be used instead of the old ones unless the old behavior 579 * is somehow necessary. 580 <p> 581 * Regardless of the level and version of the SBML, these functions allow 582 * client applications to use more generalized code in some situations 583 * (for instance, when manipulating objects that are all known to have 584 * identifiers). If the object in question does not posess an 'id' attribute 585 * according to the SBML specification for the Level and Version in use, 586 * libSBML will not allow the identifier to be set, nor will it read or 587 * write 'id' attributes for those objects. 588 <p> 589 * @param sid the string to use as the identifier of this object. 590 <p> 591 * <p> 592 * @return integer value indicating success/failure of the 593 * function. The possible values 594 * returned by this function are: 595 * <ul> 596 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 597 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 598 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 599 * 600 * </ul> <p> 601 * @see #getIdAttribute() 602 * @see #setIdAttribute(String sid) 603 * @see #isSetIdAttribute() 604 * @see #unsetIdAttribute() 605 */ public 606 int setId(String sid) { 607 return libsbmlJNI.FunctionDefinition_setId(swigCPtr, this, sid); 608 } 609 610 611/** 612 * Sets the value of the 'name' attribute of this {@link FunctionDefinition}. 613 <p> 614 * <p> 615 * The string in <code>name</code> is copied. 616 <p> 617 * @param name the new name for the SBML object. 618 <p> 619 * <p> 620 * @return integer value indicating success/failure of the 621 * function. The possible values 622 * returned by this function are: 623 * <ul> 624 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 625 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 626 * 627 * </ul> 628 */ public 629 int setName(String name) { 630 return libsbmlJNI.FunctionDefinition_setName(swigCPtr, this, name); 631 } 632 633 634/** 635 * Sets the 'math' subelement of this {@link FunctionDefinition} to the Abstract 636 * Syntax Tree given in <code>math</code>. 637 <p> 638 * @param math an AST containing the mathematical expression to 639 * be used as the formula for this {@link FunctionDefinition}. 640 <p> 641 * <p> 642 * @return integer value indicating success/failure of the 643 * function. The possible values 644 * returned by this function are: 645 * <ul> 646 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 647 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 648 * </ul> 649 */ public 650 int setMath(ASTNode math) { 651 return libsbmlJNI.FunctionDefinition_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 652 } 653 654 655/** 656 * Unsets the value of the 'name' attribute of this {@link FunctionDefinition}. 657 <p> 658 * <p> 659 * <p> 660 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 661 * moved to {@link SBase} directly, instead of being defined individually for many 662 * (but not all) objects. Libsbml has for a long time provided functions 663 * defined on {@link SBase} itself to get, set, and unset those attributes, which 664 * would fail or otherwise return empty strings if executed on any object 665 * for which those attributes were not defined. Now that all {@link SBase} objects 666 * define those attributes, those functions now succeed for any object with 667 * the appropriate level and version. 668 <p> 669 * The 'name' attribute is 670 * optional and is not intended to be used for cross-referencing purposes 671 * within a model. Its purpose instead is to provide a human-readable 672 * label for the component. The data type of 'name' is the type 673 * <code>string</code> defined in XML Schema. SBML imposes no 674 * restrictions as to the content of 'name' attributes beyond those 675 * restrictions defined by the <code>string</code> type in XML Schema. 676 <p> 677 * The recommended practice for handling 'name' is as follows. If a 678 * software tool has the capability for displaying the content of 'name' 679 * attributes, it should display this content to the user as a 680 * component's label instead of the component's 'id'. If the user 681 * interface does not have this capability (e.g., because it cannot 682 * display or use special characters in symbol names), or if the 'name' 683 * attribute is missing on a given component, then the user interface 684 * should display the value of the 'id' attribute instead. (Script 685 * language interpreters are especially likely to display 'id' instead of 686 * 'name'.) 687 <p> 688 * As a consequence of the above, authors of systems that automatically 689 * generate the values of 'id' attributes should be aware some systems 690 * may display the 'id''s to the user. Authors therefore may wish to 691 * take some care to have their software create 'id' values that are: (a) 692 * reasonably easy for humans to type and read; and (b) likely to be 693 * meaningful, for example by making the 'id' attribute be an abbreviated 694 * form of the name attribute value. 695 <p> 696 * An additional point worth mentioning is although there are 697 * restrictions on the uniqueness of 'id' values, there are no 698 * restrictions on the uniqueness of 'name' values in a model. This 699 * allows software applications leeway in assigning component identifiers. 700 <p> 701 * Regardless of the level and version of the SBML, these functions allow 702 * client applications to use more generalized code in some situations 703 * (for instance, when manipulating objects that are all known to have 704 * names). If the object in question does not posess a 'name' attribute 705 * according to the SBML specification for the Level and Version in use, 706 * libSBML will not allow the name to be set, nor will it read or 707 * write 'name' attributes for those objects. 708 <p> 709 * <p> 710 * @return integer value indicating success/failure of the 711 * function. The possible values 712 * returned by this function are: 713 * <ul> 714 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 715 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 716 * 717 * </ul> <p> 718 * @see #getName() 719 * @see #setName(String sid) 720 * @see #isSetName() 721 */ public 722 int unsetName() { 723 return libsbmlJNI.FunctionDefinition_unsetName(swigCPtr, this); 724 } 725 726 727/** 728 * Get the <code>n</code>th argument to this function. 729 <p> 730 * Callers should first find out the number of arguments to the function 731 * by calling getNumArguments(). 732 <p> 733 * @param n an integer index for the argument sought. 734 <p> 735 * @return the nth argument (bound variable) passed to this 736 * {@link FunctionDefinition}. 737 <p> 738 * @see #getNumArguments() 739 */ public 740 ASTNode getArgument(long n) { 741 long cPtr = libsbmlJNI.FunctionDefinition_getArgument__SWIG_0(swigCPtr, this, n); 742 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 743 } 744 745 746/** 747 * Get the argument named <code>name</code> to this {@link FunctionDefinition}. 748 <p> 749 * @param name the exact name (case-sensitive) of the sought-after 750 * argument. 751 <p> 752 * @return the argument (bound variable) having the given name, or <code>null</code> if 753 * no such argument exists. 754 */ public 755 ASTNode getArgument(String name) { 756 long cPtr = libsbmlJNI.FunctionDefinition_getArgument__SWIG_1(swigCPtr, this, name); 757 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 758 } 759 760 761/** 762 * Get the mathematical expression that is the body of this 763 * {@link FunctionDefinition} object. 764 <p> 765 * @return the body of this {@link FunctionDefinition} as an Abstract Syntax 766 * Tree, or <code>null</code> if no body is defined. 767 */ public 768 ASTNode getBody() { 769 long cPtr = libsbmlJNI.FunctionDefinition_getBody__SWIG_0(swigCPtr, this); 770 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 771 } 772 773 774/** 775 * Predicate returning <code>true</code> if the body of this 776 * {@link FunctionDefinition} has set. 777 <p> 778 * @return <code>true</code> if the body of this {@link FunctionDefinition} is 779 * set, <code>false</code> otherwise. 780 */ public 781 boolean isSetBody() { 782 return libsbmlJNI.FunctionDefinition_isSetBody(swigCPtr, this); 783 } 784 785 786/** 787 * Get the number of arguments (bound variables) taken by this 788 * {@link FunctionDefinition}. 789 <p> 790 * @return the number of arguments (bound variables) that must be passed 791 * to this {@link FunctionDefinition}. 792 */ public 793 long getNumArguments() { 794 return libsbmlJNI.FunctionDefinition_getNumArguments(swigCPtr, this); 795 } 796 797 798/** 799 * Returns the libSBML type code for this SBML object. 800 <p> 801 * <p> 802 * LibSBML attaches an identifying code to every kind of SBML object. These 803 * are integer constants known as <em>SBML type codes</em>. The names of all 804 * the codes begin with the characters <code>SBML_</code>. 805 * In the Java language interface for libSBML, the 806 * type codes are defined as static integer constants in the interface class 807 * {@link libsbmlConstants}. Note that different Level 3 808 * package plug-ins may use overlapping type codes; to identify the package 809 * to which a given object belongs, call the <code>getPackageName()</code> 810 * method on the object. 811 <p> 812 * @return the SBML type code for this object: 813 * {@link libsbmlConstants#SBML_FUNCTION_DEFINITION SBML_FUNCTION_DEFINITION} (default). 814 <p> 815 * <p> 816 * @warning <span class='warning'>The specific integer values of the possible 817 * type codes may be reused by different libSBML plug-ins for SBML Level 3. 818 * packages, To fully identify the correct code, <strong>it is necessary to 819 * invoke both getTypeCode() and getPackageName()</strong>.</span> 820 <p> 821 * @see #getElementName() 822 * @see #getPackageName() 823 */ public 824 int getTypeCode() { 825 return libsbmlJNI.FunctionDefinition_getTypeCode(swigCPtr, this); 826 } 827 828 829/** 830 * Returns the XML element name of this object, which for 831 * {@link FunctionDefinition}, is always <code>'functionDefinition'.</code> 832 <p> 833 * @return the name of this element, i.e., <code>'functionDefinition'.</code> 834 */ public 835 String getElementName() { 836 return libsbmlJNI.FunctionDefinition_getElementName(swigCPtr, this); 837 } 838 839 840/** 841 * Predicate returning <code>true</code> if 842 * all the required attributes for this {@link FunctionDefinition} object 843 * have been set. 844 <p> 845 * The required attributes for a {@link FunctionDefinition} object are: 846 * <ul> 847 * <li> 'id' 848 * 849 * </ul> <p> 850 * @return <code>true</code> if the required attributes have been set, <code>false</code> 851 * otherwise. 852 */ public 853 boolean hasRequiredAttributes() { 854 return libsbmlJNI.FunctionDefinition_hasRequiredAttributes(swigCPtr, this); 855 } 856 857 858/** 859 * Predicate returning <code>true</code> if 860 * all the required elements for this {@link FunctionDefinition} object 861 * have been set. 862 <p> 863 * @note The required elements for a {@link FunctionDefinition} object are: 864 * <ul> 865 * <li> 'math' inSBML Level 2 and Level 3 Version 1. 866 * (In SBML Level 3 Version 2+, it is no longer required.) 867 * 868 * </ul> <p> 869 * @return a boolean value indicating whether all the required 870 * elements for this object have been defined. 871 */ public 872 boolean hasRequiredElements() { 873 return libsbmlJNI.FunctionDefinition_hasRequiredElements(swigCPtr, this); 874 } 875 876 877/** 878 * Renames all the <code>UnitSIdRef</code> attributes on this element. 879 <p> 880 * <p> 881 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>. In 882 * SBML Level 3, an explicit data type called <code>UnitSIdRef</code> was 883 * introduced for attribute values that refer to <code>UnitSId</code> values; in 884 * previous Levels of SBML, this data type did not exist and attributes were 885 * simply described to as 'referring to a unit identifier', but the effective 886 * data type was the same as <code>UnitSIdRef</code> in Level 3. These and 887 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all 888 * Levels of SBML, even if the corresponding SBML specification did not 889 * explicitly name the data type. 890 <p> 891 * This method works by looking at all unit identifier attribute values 892 * (including, if appropriate, inside mathematical formulas), comparing the 893 * unit identifiers to the value of <code>oldid</code>. If any matches are found, 894 * the matching identifiers are replaced with <code>newid</code>. The method does 895 * <em>not</em> descend into child elements. 896 <p> 897 * @param oldid the old identifier. 898 * @param newid the new identifier. 899 */ public 900 void renameUnitSIdRefs(String oldid, String newid) { 901 libsbmlJNI.FunctionDefinition_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 902 } 903 904}