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 required 'math' subelement containing a MathML 027 * expression defining the function body. The content of this element can 028 * only be a MathML 'lambda' element. The 'lambda' element must begin with 029 * zero or more 'bvar' elements, followed by any other of the elements in 030 * the MathML subset allowed in SBML Level 2 <em>except</em> 'lambda' (i.e., a 031 * 'lambda' element cannot contain another 'lambda' element). This is the 032 * only place in SBML where a 'lambda' element can be used. The function 033 * defined by a {@link FunctionDefinition} is only available for use in other 034 * MathML elements that <em>follow</em> the {@link FunctionDefinition} definition in the 035 * model. (These restrictions prevent recursive and mutually-recursive 036 * functions from being expressed.) 037 <p> 038 * A further restriction on the content of 'math' is that it cannot contain 039 * references to variables other than the variables declared to the 040 * 'lambda' itself. That is, the contents of MathML 'ci' elements inside 041 * the body of the 'lambda' can only be the variables declared by its 042 * 'bvar' elements, or the identifiers of other {@link FunctionDefinition} 043 * instances in the model. This means must be written so that all 044 * variables or parameters used in the MathML content are passed to them 045 * via their function parameters. In SBML Level 2, this restriction 046 * applies also to the MathML <code>csymbol</code> elements for <em>time</em> and 047 * <em>delay</em>; in SBML Level 3, it additionally applies to the <code>csymbol</code> 048 * element for <em>avogadro</em>. 049 <p> 050 * @note Function definitions (also informally known as user-defined 051 * functions) were introduced in SBML Level 2. They have purposefully 052 * limited capabilities. A function cannot reference parameters or other 053 * model quantities outside of itself; values must be passed as parameters 054 * to the function. Moreover, recursive and mutually-recursive functions 055 * are not permitted. The purpose of these limitations is to balance power 056 * against complexity of implementation. With the restrictions as they 057 * are, function definitions could be implemented as textual 058 * substitutions—they are simply macros. Software implementations 059 * therefore do not need the full function-definition machinery typically 060 * associated with programming languages. 061 * <br><br> 062 * Another important point to note is {@link FunctionDefinition} does not 063 * have a separate attribute for defining the units of the value returned 064 * by the function. The units associated with the function's return value, 065 * when the function is called from within MathML expressions elsewhere in 066 * SBML, are simply the overall units of the expression in 067 * {@link FunctionDefinition}'s 'math' subelement when applied to the arguments 068 * supplied in the call to the function. Ascertaining these units requires 069 * performing dimensional analysis on the expression. (Readers may wonder 070 * why there is no attribute. The reason is that having a separate 071 * attribute for declaring the units would not only be redundant, but also 072 * lead to the potential for having conflicting information. In the case 073 * of a conflict between the declared units and those of the value actually 074 * returned by the function, the only logical resolution rule would be to 075 * assume that the correct units are those of the expression anyway.) 076 */ 077 078public class FunctionDefinition extends SBase { 079 private long swigCPtr; 080 081 protected FunctionDefinition(long cPtr, boolean cMemoryOwn) 082 { 083 super(libsbmlJNI.FunctionDefinition_SWIGUpcast(cPtr), cMemoryOwn); 084 swigCPtr = cPtr; 085 } 086 087 protected static long getCPtr(FunctionDefinition obj) 088 { 089 return (obj == null) ? 0 : obj.swigCPtr; 090 } 091 092 protected static long getCPtrAndDisown (FunctionDefinition obj) 093 { 094 long ptr = 0; 095 096 if (obj != null) 097 { 098 ptr = obj.swigCPtr; 099 obj.swigCMemOwn = false; 100 } 101 102 return ptr; 103 } 104 105 protected void finalize() { 106 delete(); 107 } 108 109 public synchronized void delete() { 110 if (swigCPtr != 0) { 111 if (swigCMemOwn) { 112 swigCMemOwn = false; 113 libsbmlJNI.delete_FunctionDefinition(swigCPtr); 114 } 115 swigCPtr = 0; 116 } 117 super.delete(); 118 } 119 120 121/** 122 * Creates a new {@link FunctionDefinition} using the given SBML <code>level</code> and <code>version</code> 123 * values. 124 <p> 125 * @param level a long integer, the SBML Level to assign to this {@link FunctionDefinition} 126 <p> 127 * @param version a long integer, the SBML Version to assign to this 128 * {@link FunctionDefinition} 129 <p> 130 * <p> 131 * @throws SBMLConstructorException 132 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid 133 * or if this object is incompatible with the given level and version. 134 <p> 135 * <p> 136 * @note Attempting to add an object to an {@link SBMLDocument} having a different 137 * combination of SBML Level, Version and XML namespaces than the object 138 * itself will result in an error at the time a caller attempts to make the 139 * addition. A parent object must have compatible Level, Version and XML 140 * namespaces. (Strictly speaking, a parent may also have more XML 141 * namespaces than a child, but the reverse is not permitted.) The 142 * restriction is necessary to ensure that an SBML model has a consistent 143 * overall structure. This requires callers to manage their objects 144 * carefully, but the benefit is increased flexibility in how models can be 145 * created by permitting callers to create objects bottom-up if desired. In 146 * situations where objects are not yet attached to parents (e.g., 147 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 148 * libSBML determine such things as whether it is valid to assign a 149 * particular value to an attribute. 150 */ public 151 FunctionDefinition(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 152 this(libsbmlJNI.new_FunctionDefinition__SWIG_0(level, version), true); 153 } 154 155 156/** 157 * Creates a new {@link FunctionDefinition} using the given {@link SBMLNamespaces} object 158 * <code>sbmlns</code>. 159 <p> 160 * <p> 161 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 162 * information. It is used to communicate the SBML Level, Version, and (in 163 * Level 3) packages used in addition to SBML Level 3 Core. A 164 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 165 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object 166 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 167 <p> 168 * @param sbmlns an {@link SBMLNamespaces} object. 169 <p> 170 * <p> 171 * @throws SBMLConstructorException 172 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible 173 * with this object. 174 <p> 175 * <p> 176 * @note Attempting to add an object to an {@link SBMLDocument} having a different 177 * combination of SBML Level, Version and XML namespaces than the object 178 * itself will result in an error at the time a caller attempts to make the 179 * addition. A parent object must have compatible Level, Version and XML 180 * namespaces. (Strictly speaking, a parent may also have more XML 181 * namespaces than a child, but the reverse is not permitted.) The 182 * restriction is necessary to ensure that an SBML model has a consistent 183 * overall structure. This requires callers to manage their objects 184 * carefully, but the benefit is increased flexibility in how models can be 185 * created by permitting callers to create objects bottom-up if desired. In 186 * situations where objects are not yet attached to parents (e.g., 187 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 188 * libSBML determine such things as whether it is valid to assign a 189 * particular value to an attribute. 190 */ public 191 FunctionDefinition(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 192 this(libsbmlJNI.new_FunctionDefinition__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 193 } 194 195 196/** 197 * Copy constructor; creates a copy of this {@link FunctionDefinition}. 198 <p> 199 * @param orig the object to copy. 200 */ public 201 FunctionDefinition(FunctionDefinition orig) throws org.sbml.libsbml.SBMLConstructorException { 202 this(libsbmlJNI.new_FunctionDefinition__SWIG_2(FunctionDefinition.getCPtr(orig), orig), true); 203 } 204 205 206/** 207 * Creates and returns a deep copy of this {@link FunctionDefinition} object. 208 <p> 209 * @return the (deep) copy of this {@link FunctionDefinition} object. 210 */ public 211 FunctionDefinition cloneObject() { 212 long cPtr = libsbmlJNI.FunctionDefinition_cloneObject(swigCPtr, this); 213 return (cPtr == 0) ? null : new FunctionDefinition(cPtr, true); 214 } 215 216 217/** 218 * Returns the value of the 'id' attribute of this {@link FunctionDefinition}. 219 <p> 220 * @return the id of this {@link FunctionDefinition}. 221 */ public 222 String getId() { 223 return libsbmlJNI.FunctionDefinition_getId(swigCPtr, this); 224 } 225 226 227/** 228 * Returns the value of the 'name' attribute of this {@link FunctionDefinition}. 229 <p> 230 * @return the name of this {@link FunctionDefinition}. 231 */ public 232 String getName() { 233 return libsbmlJNI.FunctionDefinition_getName(swigCPtr, this); 234 } 235 236 237/** 238 * Get the mathematical formula of this {@link FunctionDefinition}. 239 <p> 240 * @return an {@link ASTNode}, the value of the 'math' subelement of this 241 * {@link FunctionDefinition} 242 */ public 243 ASTNode getMath() { 244 long cPtr = libsbmlJNI.FunctionDefinition_getMath(swigCPtr, this); 245 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 246 } 247 248 249/** 250 * Predicate returning <code>true</code> if this 251 * {@link FunctionDefinition}'s 'id' attribute is set. 252 <p> 253 * @return <code>true</code> if the 'id' attribute of this {@link FunctionDefinition} is 254 * set, <code>false</code> otherwise. 255 */ public 256 boolean isSetId() { 257 return libsbmlJNI.FunctionDefinition_isSetId(swigCPtr, this); 258 } 259 260 261/** 262 * Predicate returning <code>true</code> if this 263 * {@link FunctionDefinition}'s 'name' attribute is set. 264 <p> 265 * @return <code>true</code> if the 'name' attribute of this {@link FunctionDefinition} is 266 * set, <code>false</code> otherwise. 267 */ public 268 boolean isSetName() { 269 return libsbmlJNI.FunctionDefinition_isSetName(swigCPtr, this); 270 } 271 272 273/** 274 * Predicate returning <code>true</code> if this 275 * {@link FunctionDefinition}'s 'math' subelement contains a value. 276 <p> 277 * @return <code>true</code> if the 'math' for this {@link FunctionDefinition} is set, 278 * <code>false</code> otherwise. 279 */ public 280 boolean isSetMath() { 281 return libsbmlJNI.FunctionDefinition_isSetMath(swigCPtr, this); 282 } 283 284 285/** 286 * Sets the value of the 'id' attribute of this {@link FunctionDefinition}. 287 <p> 288 * The string <code>sid</code> is copied. 289 <p> 290 * <p> 291 * SBML has strict requirements for the syntax of identifiers, that is, the 292 * values of the 'id' attribute present on most types of SBML objects. 293 * The following is a summary of the definition of the SBML identifier type 294 * <code>SId</code>, which defines the permitted syntax of identifiers. We 295 * express the syntax using an extended form of BNF notation: 296 * <pre style='margin-left: 2em; border: none; font-weight: bold; font-size: 13px; color: black'> 297 * letter .= 'a'..'z','A'..'Z' 298 * digit .= '0'..'9' 299 * idChar .= letter | digit | '_' 300 * SId .= ( letter | '_' ) idChar*</pre> 301 * The characters <code>(</code> and <code>)</code> are used for grouping, the 302 * character <code>*</code> 'zero or more times', and the character 303 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers is 304 * determined by an exact character sequence match; i.e., comparisons must be 305 * performed in a case-sensitive manner. In addition, there are a few 306 * conditions for the uniqueness of identifiers in an SBML model. Please 307 * consult the SBML specifications for the exact details of the uniqueness 308 * requirements. 309 <p> 310 * @param sid the string to use as the identifier of this {@link FunctionDefinition} 311 <p> 312 * <p> 313 * @return integer value indicating success/failure of the 314 * function. The possible values 315 * returned by this function are: 316 * <ul> 317 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 318 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 319 * </ul> 320 */ public 321 int setId(String sid) { 322 return libsbmlJNI.FunctionDefinition_setId(swigCPtr, this, sid); 323 } 324 325 326/** 327 * Sets the value of the 'name' attribute of this {@link FunctionDefinition}. 328 <p> 329 * The string in <code>name</code> is copied. 330 <p> 331 * @param name the new name for the {@link FunctionDefinition} 332 <p> 333 * <p> 334 * @return integer value indicating success/failure of the 335 * function. The possible values 336 * returned by this function are: 337 * <ul> 338 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 339 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 340 * </ul> 341 */ public 342 int setName(String name) { 343 return libsbmlJNI.FunctionDefinition_setName(swigCPtr, this, name); 344 } 345 346 347/** 348 * Sets the 'math' subelement of this {@link FunctionDefinition} to the Abstract 349 * Syntax Tree given in <code>math</code>. 350 <p> 351 * @param math an AST containing the mathematical expression to 352 * be used as the formula for this {@link FunctionDefinition}. 353 <p> 354 * <p> 355 * @return integer value indicating success/failure of the 356 * function. The possible values 357 * returned by this function are: 358 * <ul> 359 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 360 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 361 * </ul> 362 */ public 363 int setMath(ASTNode math) { 364 return libsbmlJNI.FunctionDefinition_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 365 } 366 367 368/** 369 * Unsets the value of the 'name' attribute of this {@link FunctionDefinition}. 370 <p> 371 * <p> 372 * @return integer value indicating success/failure of the 373 * function. The possible values 374 * returned by this function are: 375 * <ul> 376 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 377 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 378 * </ul> 379 */ public 380 int unsetName() { 381 return libsbmlJNI.FunctionDefinition_unsetName(swigCPtr, this); 382 } 383 384 385/** 386 * Get the <code>n</code>th argument to this function. 387 <p> 388 * Callers should first find out the number of arguments to the function 389 * by calling getNumArguments(). 390 <p> 391 * @param n an integer index for the argument sought. 392 <p> 393 * @return the nth argument (bound variable) passed to this 394 * {@link FunctionDefinition}. 395 <p> 396 * @see #getNumArguments() 397 */ public 398 ASTNode getArgument(long n) { 399 long cPtr = libsbmlJNI.FunctionDefinition_getArgument__SWIG_0(swigCPtr, this, n); 400 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 401 } 402 403 404/** 405 * Get the argument named <code>name</code> to this {@link FunctionDefinition}. 406 <p> 407 * @param name the exact name (case-sensitive) of the sought-after 408 * argument 409 <p> 410 * @return the argument (bound variable) having the given name, or <code>null</code> if 411 * no such argument exists. 412 */ public 413 ASTNode getArgument(String name) { 414 long cPtr = libsbmlJNI.FunctionDefinition_getArgument__SWIG_1(swigCPtr, this, name); 415 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 416 } 417 418 419/** 420 * Get the mathematical expression that is the body of this 421 * {@link FunctionDefinition} object. 422 <p> 423 * @return the body of this {@link FunctionDefinition} as an Abstract Syntax 424 * Tree, or <code>null</code> if no body is defined. 425 */ public 426 ASTNode getBody() { 427 long cPtr = libsbmlJNI.FunctionDefinition_getBody__SWIG_0(swigCPtr, this); 428 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 429 } 430 431 432/** 433 * Predicate returning <code>true</code> if the body of this 434 * {@link FunctionDefinition} has set. 435 <p> 436 * @return <code>true</code> if the body of this {@link FunctionDefinition} is 437 * set, <code>false</code> otherwise. 438 */ public 439 boolean isSetBody() { 440 return libsbmlJNI.FunctionDefinition_isSetBody(swigCPtr, this); 441 } 442 443 444/** 445 * Get the number of arguments (bound variables) taken by this 446 * {@link FunctionDefinition}. 447 <p> 448 * @return the number of arguments (bound variables) that must be passed 449 * to this {@link FunctionDefinition}. 450 */ public 451 long getNumArguments() { 452 return libsbmlJNI.FunctionDefinition_getNumArguments(swigCPtr, this); 453 } 454 455 456/** 457 * Returns the libSBML type code for this SBML object. 458 <p> 459 * <p> 460 * LibSBML attaches an identifying code to every kind of SBML object. These 461 * are integer constants known as <em>SBML type codes</em>. The names of all 462 * the codes begin with the characters <code>SBML_</code>. 463 * In the Java language interface for libSBML, the 464 * type codes are defined as static integer constants in the interface class 465 * {@link libsbmlConstants}. Note that different Level 3 466 * package plug-ins may use overlapping type codes; to identify the package 467 * to which a given object belongs, call the <code>getPackageName()</code> 468 * method on the object. 469 <p> 470 * @return the SBML type code for this object: 471 * {@link libsbmlConstants#SBML_FUNCTION_DEFINITION SBML_FUNCTION_DEFINITION} (default). 472 <p> 473 * <p> 474 * @warning <span class='warning'>The specific integer values of the possible 475 * type codes may be reused by different libSBML plug-ins for SBML Level 3. 476 * packages, To fully identify the correct code, <strong>it is necessary to 477 * invoke both getTypeCode() and getPackageName()</strong>.</span> 478 <p> 479 * @see #getElementName() 480 * @see #getPackageName() 481 */ public 482 int getTypeCode() { 483 return libsbmlJNI.FunctionDefinition_getTypeCode(swigCPtr, this); 484 } 485 486 487/** 488 * Returns the XML element name of this object, which for 489 * {@link FunctionDefinition}, is always <code>'functionDefinition'.</code> 490 <p> 491 * @return the name of this element, i.e., <code>'functionDefinition'.</code> 492 */ public 493 String getElementName() { 494 return libsbmlJNI.FunctionDefinition_getElementName(swigCPtr, this); 495 } 496 497 498/** 499 * Predicate returning <code>true</code> if 500 * all the required attributes for this {@link FunctionDefinition} object 501 * have been set. 502 <p> 503 * The required attributes for a {@link FunctionDefinition} object are: 504 * <ul> 505 * <li> 'id' 506 * 507 * </ul> <p> 508 * @return <code>true</code> if the required attributes have been set, <code>false</code> 509 * otherwise. 510 */ public 511 boolean hasRequiredAttributes() { 512 return libsbmlJNI.FunctionDefinition_hasRequiredAttributes(swigCPtr, this); 513 } 514 515 516/** 517 * Predicate returning <code>true</code> if 518 * all the required elements for this {@link FunctionDefinition} object 519 * have been set. 520 <p> 521 * @note The required elements for a {@link FunctionDefinition} object are: 522 * <ul> 523 * <li> 'math' 524 * 525 * </ul> <p> 526 * @return a boolean value indicating whether all the required 527 * elements for this object have been defined. 528 */ public 529 boolean hasRequiredElements() { 530 return libsbmlJNI.FunctionDefinition_hasRequiredElements(swigCPtr, this); 531 } 532 533 534/** 535 * Renames all the <code>UnitSIdRef</code> attributes on this element. 536 <p> 537 * <p> 538 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>. In 539 * SBML Level 3, an explicit data type called <code>UnitSIdRef</code> was 540 * introduced for attribute values that refer to <code>UnitSId</code> values; in 541 * previous Levels of SBML, this data type did not exist and attributes were 542 * simply described to as 'referring to a unit identifier', but the effective 543 * data type was the same as <code>UnitSIdRef</code> in Level 3. These and 544 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all 545 * Levels of SBML, even if the corresponding SBML specification did not 546 * explicitly name the data type. 547 <p> 548 * This method works by looking at all unit identifier attribute values 549 * (including, if appropriate, inside mathematical formulas), comparing the 550 * unit identifiers to the value of <code>oldid</code>. If any matches are found, 551 * the matching identifiers are replaced with <code>newid</code>. The method does 552 * <em>not</em> descend into child elements. 553 <p> 554 * @param oldid the old identifier 555 * @param newid the new identifier 556 */ public 557 void renameUnitSIdRefs(String oldid, String newid) { 558 libsbmlJNI.FunctionDefinition_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 559 } 560 561}