001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 2.0.12 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 * Implementation of SBML's FunctionDefinition construct. 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 * @throws SBMLConstructorException 131 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 132 * of SBML object, are either invalid or mismatched with respect to the 133 * parent {@link SBMLDocument} object. 134 <p> 135 * <p> 136 * @note Upon the addition of a {@link FunctionDefinition} object to an {@link SBMLDocument} 137 * (e.g., using {@link Model#addFunctionDefinition(FunctionDefinition 138 * f)}), the SBML Level, SBML Version and XML namespace of the document 139 * <em>override</em> the values used when creating the {@link FunctionDefinition} object 140 * via this constructor. This is necessary to ensure that an SBML document 141 * is a consistent structure. Nevertheless, the ability to supply the values 142 * at the time of creation of a {@link FunctionDefinition} is an important aid to 143 * producing valid SBML. Knowledge of the intented SBML Level and Version 144 * determine whether it is valid to assign a particular value to an 145 * attribute, or whether it is valid to add an object to an existing 146 * {@link SBMLDocument}. 147 */ public 148 FunctionDefinition(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 149 this(libsbmlJNI.new_FunctionDefinition__SWIG_0(level, version), true); 150 } 151 152 153/** 154 * Creates a new {@link FunctionDefinition} using the given {@link SBMLNamespaces} object 155 * <code>sbmlns</code>. 156 <p> 157 * <p> 158 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 159 * information. It is used to communicate the SBML Level, Version, and (in 160 * Level 3) packages used in addition to SBML Level 3 Core. A 161 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 162 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object 163 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 164 <p> 165 * @param sbmlns an {@link SBMLNamespaces} object. 166 <p> 167 * @throws SBMLConstructorException 168 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 169 * of SBML object, are either invalid or mismatched with respect to the 170 * parent {@link SBMLDocument} object. 171 <p> 172 * <p> 173 * @note Upon the addition of a {@link FunctionDefinition} object to an {@link SBMLDocument} 174 * (e.g., using {@link Model#addFunctionDefinition(FunctionDefinition 175 * f)}), the SBML Level, SBML Version and XML namespace of the document 176 * <em>override</em> the values used when creating the {@link FunctionDefinition} object 177 * via this constructor. This is necessary to ensure that an SBML document 178 * is a consistent structure. Nevertheless, the ability to supply the values 179 * at the time of creation of a {@link FunctionDefinition} is an important aid to 180 * producing valid SBML. Knowledge of the intented SBML Level and Version 181 * determine whether it is valid to assign a particular value to an 182 * attribute, or whether it is valid to add an object to an existing 183 * {@link SBMLDocument}. 184 */ public 185 FunctionDefinition(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 186 this(libsbmlJNI.new_FunctionDefinition__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 187 } 188 189 190/** 191 * Copy constructor; creates a copy of this {@link FunctionDefinition}. 192 <p> 193 * @param orig the object to copy. 194 <p> 195 * @throws SBMLConstructorException 196 * Thrown if the argument <code>orig</code> is <code>null.</code> 197 */ public 198 FunctionDefinition(FunctionDefinition orig) throws org.sbml.libsbml.SBMLConstructorException { 199 this(libsbmlJNI.new_FunctionDefinition__SWIG_2(FunctionDefinition.getCPtr(orig), orig), true); 200 } 201 202 203/** 204 * Creates and returns a deep copy of this {@link FunctionDefinition}. 205 <p> 206 * @return a (deep) copy of this {@link FunctionDefinition}. 207 */ public 208 FunctionDefinition cloneObject() { 209 long cPtr = libsbmlJNI.FunctionDefinition_cloneObject(swigCPtr, this); 210 return (cPtr == 0) ? null : new FunctionDefinition(cPtr, true); 211 } 212 213 214/** 215 * Returns the value of the 'id' attribute of this {@link FunctionDefinition}. 216 <p> 217 * @return the id of this {@link FunctionDefinition}. 218 */ public 219 String getId() { 220 return libsbmlJNI.FunctionDefinition_getId(swigCPtr, this); 221 } 222 223 224/** 225 * Returns the value of the 'name' attribute of this {@link FunctionDefinition}. 226 <p> 227 * @return the name of this {@link FunctionDefinition}. 228 */ public 229 String getName() { 230 return libsbmlJNI.FunctionDefinition_getName(swigCPtr, this); 231 } 232 233 234/** 235 * Get the mathematical formula of this {@link FunctionDefinition}. 236 <p> 237 * @return an {@link ASTNode}, the value of the 'math' subelement of this 238 * {@link FunctionDefinition} 239 */ public 240 ASTNode getMath() { 241 long cPtr = libsbmlJNI.FunctionDefinition_getMath(swigCPtr, this); 242 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 243 } 244 245 246/** 247 * Predicate returning <code>true</code> if this 248 * {@link FunctionDefinition}'s 'id' attribute is set. 249 <p> 250 * @return <code>true</code> if the 'id' attribute of this {@link FunctionDefinition} is 251 * set, <code>false</code> otherwise. 252 */ public 253 boolean isSetId() { 254 return libsbmlJNI.FunctionDefinition_isSetId(swigCPtr, this); 255 } 256 257 258/** 259 * Predicate returning <code>true</code> if this 260 * {@link FunctionDefinition}'s 'name' attribute is set. 261 <p> 262 * @return <code>true</code> if the 'name' attribute of this {@link FunctionDefinition} is 263 * set, <code>false</code> otherwise. 264 */ public 265 boolean isSetName() { 266 return libsbmlJNI.FunctionDefinition_isSetName(swigCPtr, this); 267 } 268 269 270/** 271 * Predicate returning <code>true</code> if this 272 * {@link FunctionDefinition}'s 'math' subelement contains a value. 273 <p> 274 * @return <code>true</code> if the 'math' for this {@link FunctionDefinition} is set, 275 * <code>false</code> otherwise. 276 */ public 277 boolean isSetMath() { 278 return libsbmlJNI.FunctionDefinition_isSetMath(swigCPtr, this); 279 } 280 281 282/** 283 * Sets the value of the 'id' attribute of this {@link FunctionDefinition}. 284 <p> 285 * The string <code>sid</code> is copied. 286 <p> 287 * <p> 288 * SBML has strict requirements for the syntax of identifiers, that is, the 289 * values of the 'id' attribute present on most types of SBML objects. 290 * The following is a summary of the definition of the SBML identifier type 291 * <code>SId</code>, which defines the permitted syntax of identifiers. We 292 * express the syntax using an extended form of BNF notation: 293 * <pre style='margin-left: 2em; border: none; font-weight: bold; font-size: 13px; color: black'> 294 * letter .= 'a'..'z','A'..'Z' 295 * digit .= '0'..'9' 296 * idChar .= letter | digit | '_' 297 * SId .= ( letter | '_' ) idChar* 298 * </pre> 299 * The characters <code>(</code> and <code>)</code> are used for grouping, the 300 * character <code>*</code> 'zero or more times', and the character 301 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers is 302 * determined by an exact character sequence match; i.e., comparisons must be 303 * performed in a case-sensitive manner. In addition, there are a few 304 * conditions for the uniqueness of identifiers in an SBML model. Please 305 * consult the SBML specifications for the exact details of the uniqueness 306 * requirements. 307 <p> 308 * @param sid the string to use as the identifier of this {@link FunctionDefinition} 309 <p> 310 * @return integer value indicating success/failure of the 311 * function. The possible values 312 * returned by this function are: 313 * <ul> 314 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 315 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 316 * </ul> 317 */ public 318 int setId(String sid) { 319 return libsbmlJNI.FunctionDefinition_setId(swigCPtr, this, sid); 320 } 321 322 323/** 324 * Sets the value of the 'name' attribute of this {@link FunctionDefinition}. 325 <p> 326 * The string in <code>name</code> is copied. 327 <p> 328 * @param name the new name for the {@link FunctionDefinition} 329 <p> 330 * @return integer value indicating success/failure of the 331 * function. The possible values 332 * returned by this function are: 333 * <ul> 334 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 335 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 336 * </ul> 337 */ public 338 int setName(String name) { 339 return libsbmlJNI.FunctionDefinition_setName(swigCPtr, this, name); 340 } 341 342 343/** 344 * Sets the 'math' subelement of this {@link FunctionDefinition} to the Abstract 345 * Syntax Tree given in <code>math</code>. 346 <p> 347 * @param math an AST containing the mathematical expression to 348 * be used as the formula for this {@link FunctionDefinition}. 349 <p> 350 * @return integer value indicating success/failure of the 351 * function. The possible values 352 * returned by this function are: 353 * <ul> 354 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 355 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 356 * </ul> 357 */ public 358 int setMath(ASTNode math) { 359 return libsbmlJNI.FunctionDefinition_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 360 } 361 362 363/** 364 * Unsets the value of the 'name' attribute of this {@link FunctionDefinition}. 365 <p> 366 * @return integer value indicating success/failure of the 367 * function. The possible values 368 * returned by this function are: 369 * <ul> 370 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 371 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 372 * </ul> 373 */ public 374 int unsetName() { 375 return libsbmlJNI.FunctionDefinition_unsetName(swigCPtr, this); 376 } 377 378 379/** 380 * Get the <code>n</code>th argument to this function. 381 <p> 382 * Callers should first find out the number of arguments to the function 383 * by calling getNumArguments(). 384 <p> 385 * @param n an integer index for the argument sought. 386 <p> 387 * @return the nth argument (bound variable) passed to this 388 * {@link FunctionDefinition}. 389 <p> 390 * @see #getNumArguments() 391 */ public 392 ASTNode getArgument(long n) { 393 long cPtr = libsbmlJNI.FunctionDefinition_getArgument__SWIG_0(swigCPtr, this, n); 394 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 395 } 396 397 398/** 399 * Get the argument named <code>name</code> to this {@link FunctionDefinition}. 400 <p> 401 * @param name the exact name (case-sensitive) of the sought-after 402 * argument 403 <p> 404 * @return the argument (bound variable) having the given name, or <code>null</code> if 405 * no such argument exists. 406 */ public 407 ASTNode getArgument(String name) { 408 long cPtr = libsbmlJNI.FunctionDefinition_getArgument__SWIG_1(swigCPtr, this, name); 409 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 410 } 411 412 413/** 414 * Get the mathematical expression that is the body of this 415 * {@link FunctionDefinition} object. 416 <p> 417 * @return the body of this {@link FunctionDefinition} as an Abstract Syntax 418 * Tree, or <code>null</code> if no body is defined. 419 */ public 420 ASTNode getBody() { 421 long cPtr = libsbmlJNI.FunctionDefinition_getBody__SWIG_0(swigCPtr, this); 422 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 423 } 424 425 426/** 427 * Predicate returning <code>true</code> if the body of this 428 * {@link FunctionDefinition} has set. 429 <p> 430 * @return <code>true</code> if the body of this {@link FunctionDefinition} is 431 * set, <code>false</code> otherwise. 432 */ public 433 boolean isSetBody() { 434 return libsbmlJNI.FunctionDefinition_isSetBody(swigCPtr, this); 435 } 436 437 438/** 439 * Get the number of arguments (bound variables) taken by this 440 * {@link FunctionDefinition}. 441 <p> 442 * @return the number of arguments (bound variables) that must be passed 443 * to this {@link FunctionDefinition}. 444 */ public 445 long getNumArguments() { 446 return libsbmlJNI.FunctionDefinition_getNumArguments(swigCPtr, this); 447 } 448 449 450/** 451 * Returns the libSBML type code for this SBML object. 452 <p> 453 * <p> 454 * LibSBML attaches an identifying code to every kind of SBML object. These 455 * are integer constants known as <em>SBML type codes</em>. The names of all 456 * the codes begin with the characters “<code>SBML_</code>”. 457 * In the Java language interface for libSBML, the 458 * type codes are defined as static integer constants in the interface class 459 * {@link libsbmlConstants}. Note that different Level 3 460 * package plug-ins may use overlapping type codes; to identify the package 461 * to which a given object belongs, call the <code>getPackageName()</code> 462 * method on the object. 463 <p> 464 * @return the SBML type code for this object: 465 * {@link libsbmlConstants#SBML_FUNCTION_DEFINITION SBML_FUNCTION_DEFINITION} (default). 466 <p> 467 * <p> 468 * @warning <span class='warning'>The specific integer values of the possible 469 * type codes may be reused by different Level 3 package plug-ins. 470 * Thus, to identifiy the correct code, <strong>it is necessary to invoke 471 * both getTypeCode() and getPackageName()</strong>.</span> 472 <p> 473 * @see #getElementName() 474 * @see #getPackageName() 475 */ public 476 int getTypeCode() { 477 return libsbmlJNI.FunctionDefinition_getTypeCode(swigCPtr, this); 478 } 479 480 481/** 482 * Returns the XML element name of this object, which for 483 * {@link FunctionDefinition}, is always <code>'functionDefinition'.</code> 484 <p> 485 * @return the name of this element, i.e., <code>'functionDefinition'.</code> 486 */ public 487 String getElementName() { 488 return libsbmlJNI.FunctionDefinition_getElementName(swigCPtr, this); 489 } 490 491 492/** 493 * Predicate returning <code>true</code> if 494 * all the required attributes for this {@link FunctionDefinition} object 495 * have been set. 496 <p> 497 * @note The required attributes for a {@link FunctionDefinition} object are: 498 * <ul> 499 * <li> 'id' 500 * 501 * </ul> <p> 502 * @return a boolean value indicating whether all the required 503 * attributes for this object have been defined. 504 */ public 505 boolean hasRequiredAttributes() { 506 return libsbmlJNI.FunctionDefinition_hasRequiredAttributes(swigCPtr, this); 507 } 508 509 510/** 511 * Predicate returning <code>true</code> if 512 * all the required elements for this {@link FunctionDefinition} object 513 * have been set. 514 <p> 515 * @note The required elements for a {@link FunctionDefinition} object are: 516 * <ul> 517 * <li> 'math' 518 * 519 * </ul> <p> 520 * @return a boolean value indicating whether all the required 521 * elements for this object have been defined. 522 */ public 523 boolean hasRequiredElements() { 524 return libsbmlJNI.FunctionDefinition_hasRequiredElements(swigCPtr, this); 525 } 526 527 528/** 529 * Renames all the <code>UnitSIdRef</code> attributes on this element. 530 <p> 531 * <p> 532 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>. In 533 * SBML Level 3, an explicit data type called <code>UnitSIdRef</code> was 534 * introduced for attribute values that refer to <code>UnitSId</code> values; in 535 * previous Levels of SBML, this data type did not exist and attributes were 536 * simply described to as 'referring to a unit identifier', but the effective 537 * data type was the same as <code>UnitSIdRef</code> in Level 3. These and 538 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all 539 * Levels of SBML, even if the corresponding SBML specification did not 540 * explicitly name the data type. 541 <p> 542 * This method works by looking at all unit identifier attribute values 543 * (including, if appropriate, inside mathematical formulas), comparing the 544 * unit identifiers to the value of <code>oldid</code>. If any matches are found, 545 * the matching identifiers are replaced with <code>newid</code>. The method does 546 * <em>not</em> descend into child elements. 547 <p> 548 * @param oldid the old identifier 549 * @param newid the new identifier 550 */ public 551 void renameUnitSIdRefs(String oldid, String newid) { 552 libsbmlJNI.FunctionDefinition_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 553 } 554 555}