001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 2.0.11 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 * 013 * Implementation of SBML's FunctionDefinition construct. 014 * <p> 015 * The {@link FunctionDefinition} structure associates an identifier with a 016 * function definition. This identifier can then be used as the function 017 * called in subsequent MathML content elsewhere in an SBML model. 018 * <p> 019 * {@link FunctionDefinition} has one required attribute, 'id', to give the 020 * function a unique identifier by which other parts of an SBML model 021 * definition can refer to it. A {@link FunctionDefinition} instance can also have 022 * an optional 'name' attribute of type <code>string.</code> Identifiers and names 023 * must be used according to the guidelines described in the SBML 024 * specification (e.g., Section 3.3 in the Level 2 Version 4 025 * specification). 026 * <p> 027 * {@link FunctionDefinition} has a required 'math' subelement containing a MathML 028 * expression defining the function body. The content of this element can 029 * only be a MathML 'lambda' element. The 'lambda' element must begin with 030 * zero or more 'bvar' elements, followed by any other of the elements in 031 * the MathML subset allowed in SBML Level 2 <em>except</em> 'lambda' (i.e., a 032 * 'lambda' element cannot contain another 'lambda' element). This is the 033 * only place in SBML where a 'lambda' element can be used. The function 034 * defined by a {@link FunctionDefinition} is only available for use in other 035 * MathML elements that <em>follow</em> the {@link FunctionDefinition} definition in the 036 * model. (These restrictions prevent recursive and mutually-recursive 037 * functions from being expressed.) 038 * <p> 039 * A further restriction on the content of 'math' is that it cannot contain 040 * references to variables other than the variables declared to the 041 * 'lambda' itself. That is, the contents of MathML 'ci' elements inside 042 * the body of the 'lambda' can only be the variables declared by its 043 * 'bvar' elements, or the identifiers of other {@link FunctionDefinition} 044 * instances in the model. This means must be written so that all 045 * variables or parameters used in the MathML content are passed to them 046 * via their function parameters. In SBML Level 2, this restriction 047 * applies also to the MathML <code>csymbol</code> elements for <em>time</em> and 048 * <em>delay</em>; in SBML Level 3, it additionally applies to the <code>csymbol</code> 049 * element for <em>avogadro</em>. 050 * <p> 051 * @note Function definitions (also informally known as user-defined 052 * functions) were introduced in SBML Level 2. They have purposefully 053 * limited capabilities. A function cannot reference parameters or other 054 * model quantities outside of itself; values must be passed as parameters 055 * to the function. Moreover, recursive and mutually-recursive functions 056 * are not permitted. The purpose of these limitations is to balance power 057 * against complexity of implementation. With the restrictions as they 058 * are, function definitions could be implemented as textual 059 * substitutions—they are simply macros. Software implementations 060 * therefore do not need the full function-definition machinery typically 061 * associated with programming languages. 062 * <br><br> 063 * Another important point to note is {@link FunctionDefinition} does not 064 * have a separate attribute for defining the units of the value returned 065 * by the function. The units associated with the function's return value, 066 * when the function is called from within MathML expressions elsewhere in 067 * SBML, are simply the overall units of the expression in 068 * {@link FunctionDefinition}'s 'math' subelement when applied to the arguments 069 * supplied in the call to the function. Ascertaining these units requires 070 * performing dimensional analysis on the expression. (Readers may wonder 071 * why there is no attribute. The reason is that having a separate 072 * attribute for declaring the units would not only be redundant, but also 073 * lead to the potential for having conflicting information. In the case 074 * of a conflict between the declared units and those of the value actually 075 * returned by the function, the only logical resolution rule would be to 076 * assume that the correct units are those of the expression anyway.) 077 * <p> 078 * <!---------------------------------------------------------------------- --> 079 * <p> 080 */ 081 082public class FunctionDefinition extends SBase { 083 private long swigCPtr; 084 085 protected FunctionDefinition(long cPtr, boolean cMemoryOwn) 086 { 087 super(libsbmlJNI.FunctionDefinition_SWIGUpcast(cPtr), cMemoryOwn); 088 swigCPtr = cPtr; 089 } 090 091 protected static long getCPtr(FunctionDefinition obj) 092 { 093 return (obj == null) ? 0 : obj.swigCPtr; 094 } 095 096 protected static long getCPtrAndDisown (FunctionDefinition obj) 097 { 098 long ptr = 0; 099 100 if (obj != null) 101 { 102 ptr = obj.swigCPtr; 103 obj.swigCMemOwn = false; 104 } 105 106 return ptr; 107 } 108 109 protected void finalize() { 110 delete(); 111 } 112 113 public synchronized void delete() { 114 if (swigCPtr != 0) { 115 if (swigCMemOwn) { 116 swigCMemOwn = false; 117 libsbmlJNI.delete_FunctionDefinition(swigCPtr); 118 } 119 swigCPtr = 0; 120 } 121 super.delete(); 122 } 123 124 125/** 126 * Creates a new {@link FunctionDefinition} using the given SBML <code>level</code> and <code>version</code> 127 * values. 128 * <p> 129 * @param level a long integer, the SBML Level to assign to this {@link FunctionDefinition} 130 * <p> 131 * @param version a long integer, the SBML Version to assign to this 132 * {@link FunctionDefinition} 133 * <p> 134 * @throws SBMLConstructorException 135 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 136 * of SBML object, are either invalid or mismatched with respect to the 137 * parent {@link SBMLDocument} object. 138 * <p> 139 * @note Upon the addition of a {@link FunctionDefinition} object to an 140 * {@link SBMLDocument} (e.g., using {@link Model#addFunctionDefinition(FunctionDefinition f)}), the SBML 141 * Level, SBML Version and XML namespace of the document 142 * <em>override</em> the values used when creating the {@link FunctionDefinition} object 143 * via this constructor. This is necessary to ensure that an SBML 144 * document is a consistent structure. Nevertheless, the ability to 145 * supply the values at the time of creation of a {@link FunctionDefinition} is 146 * an important aid to producing valid SBML. Knowledge of the intented 147 * SBML Level and Version determine whether it is valid to assign a 148 * particular value to an attribute, or whether it is valid to add an 149 * object to an existing {@link SBMLDocument}. 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 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 161 * information. It is used to communicate the SBML Level, Version, and 162 * (in Level 3) packages used in addition to SBML Level 3 Core. 163 * A common approach to using this class constructor is to create an 164 * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to 165 * object constructors such as this one when needed. 166 * <p> 167 * @param sbmlns an {@link SBMLNamespaces} object. 168 * <p> 169 * @throws SBMLConstructorException 170 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 171 * of SBML object, are either invalid or mismatched with respect to the 172 * parent {@link SBMLDocument} object. 173 * <p> 174 * @note Upon the addition of a {@link FunctionDefinition} object to an 175 * {@link SBMLDocument} (e.g., using {@link Model#addFunctionDefinition(FunctionDefinition f)}), the SBML 176 * XML namespace of the document <em>overrides</em> the value used when 177 * creating the {@link FunctionDefinition} object via this constructor. This is 178 * necessary to ensure that an SBML document is a consistent structure. 179 * Nevertheless, the ability to supply the values at the time of creation 180 * of a {@link FunctionDefinition} is an important aid to producing valid SBML. 181 * Knowledge of the intented SBML Level and Version determine whether it 182 * is valid to assign a particular value to an attribute, or whether it 183 * is valid to add an object to an existing {@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. Note that SBML has strict requirements 286 * for the syntax of identifiers. The following is a summary of the definition of the SBML identifier type 287<code>SId</code>, which defines the permitted syntax of identifiers. We 288express the syntax using an extended form of BNF notation: 289<pre style='margin-left: 2em; border: none; font-weight: bold; font-size: 13px; color: black'> 290letter .= 'a'..'z','A'..'Z' 291digit .= '0'..'9' 292idChar .= letter | digit | '_' 293SId .= ( letter | '_' ) idChar* 294</pre> 295The characters <code>(</code> and <code>)</code> are used for grouping, the 296character <code>*</code> 'zero or more times', and the character 297<code>|</code> indicates logical 'or'. The equality of SBML identifiers is 298determined by an exact character sequence match; i.e., comparisons must be 299performed in a case-sensitive manner. In addition, there are a few 300conditions for the uniqueness of identifiers in an SBML model. Please 301consult the SBML specifications for the exact formulations. 302<p> 303 304 * <p> 305 * @param sid the string to use as the identifier of this {@link FunctionDefinition} 306 * <p> 307 * @return integer value indicating success/failure of the 308 * function. The possible values 309 * returned by this function are: 310 * <ul> 311 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 312 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 313 * </ul> 314 */ public 315 int setId(String sid) { 316 return libsbmlJNI.FunctionDefinition_setId(swigCPtr, this, sid); 317 } 318 319 320/** 321 * Sets the value of the 'name' attribute of this {@link FunctionDefinition}. 322 * <p> 323 * The string in <code>name</code> is copied. 324 * <p> 325 * @param name the new name for the {@link FunctionDefinition} 326 * <p> 327 * @return integer value indicating success/failure of the 328 * function. The possible values 329 * returned by this function are: 330 * <ul> 331 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 332 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 333 * </ul> 334 */ public 335 int setName(String name) { 336 return libsbmlJNI.FunctionDefinition_setName(swigCPtr, this, name); 337 } 338 339 340/** 341 * Sets the 'math' subelement of this {@link FunctionDefinition} to the Abstract 342 * Syntax Tree given in <code>math</code>. 343 * <p> 344 * @param math an AST containing the mathematical expression to 345 * be used as the formula for this {@link FunctionDefinition}. 346 * <p> 347 * @return integer value indicating success/failure of the 348 * function. The possible values 349 * returned by this function are: 350 * <ul> 351 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 352 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 353 * </ul> 354 */ public 355 int setMath(ASTNode math) { 356 return libsbmlJNI.FunctionDefinition_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 357 } 358 359 360/** 361 * Unsets the value of the 'name' attribute of this {@link FunctionDefinition}. 362 * <p> 363 * @return integer value indicating success/failure of the 364 * function. The possible values 365 * returned by this function are: 366 * <ul> 367 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 368 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 369 * </ul> 370 */ public 371 int unsetName() { 372 return libsbmlJNI.FunctionDefinition_unsetName(swigCPtr, this); 373 } 374 375 376/** 377 * Get the <code>n</code>th argument to this function. 378 * <p> 379 * Callers should first find out the number of arguments to the function 380 * by calling getNumArguments(). 381 * <p> 382 * @param n an integer index for the argument sought. 383 * <p> 384 * @return the nth argument (bound variable) passed to this 385 * {@link FunctionDefinition}. 386 * <p> 387 * @see #getNumArguments() 388 */ public 389 ASTNode getArgument(long n) { 390 long cPtr = libsbmlJNI.FunctionDefinition_getArgument__SWIG_0(swigCPtr, this, n); 391 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 392 } 393 394 395/** 396 * Get the argument named <code>name</code> to this {@link FunctionDefinition}. 397 * <p> 398 * @param name the exact name (case-sensitive) of the sought-after 399 * argument 400 * <p> 401 * @return the argument (bound variable) having the given name, or <code>null</code> if 402 * no such argument exists. 403 */ public 404 ASTNode getArgument(String name) { 405 long cPtr = libsbmlJNI.FunctionDefinition_getArgument__SWIG_1(swigCPtr, this, name); 406 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 407 } 408 409 410/** 411 * Get the mathematical expression that is the body of this 412 * {@link FunctionDefinition} object. 413 * <p> 414 * @return the body of this {@link FunctionDefinition} as an Abstract Syntax 415 * Tree, or <code>null</code> if no body is defined. 416 */ public 417 ASTNode getBody() { 418 long cPtr = libsbmlJNI.FunctionDefinition_getBody__SWIG_0(swigCPtr, this); 419 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 420 } 421 422 423/** 424 * Predicate returning <code>true</code> if the body of this 425 * {@link FunctionDefinition} has set. 426 * <p> 427 * @return <code>true</code> if the body of this {@link FunctionDefinition} is 428 * set, <code>false</code> otherwise. 429 */ public 430 boolean isSetBody() { 431 return libsbmlJNI.FunctionDefinition_isSetBody(swigCPtr, this); 432 } 433 434 435/** 436 * Get the number of arguments (bound variables) taken by this 437 * {@link FunctionDefinition}. 438 * <p> 439 * @return the number of arguments (bound variables) that must be passed 440 * to this {@link FunctionDefinition}. 441 */ public 442 long getNumArguments() { 443 return libsbmlJNI.FunctionDefinition_getNumArguments(swigCPtr, this); 444 } 445 446 447/** 448 * Returns the libSBML type code for this SBML object. 449 * <p> 450 * LibSBML attaches an identifying code to every 451 * kind of SBML object. These are known as <em>SBML type codes</em>. In 452 * other languages, the set of type codes is stored in an enumeration; in 453 * the Java language interface for libSBML, the type codes are defined as 454 * static integer constants in the interface class {@link 455 * libsbmlConstants}. The names of the type codes all begin with the 456 * characters <code>SBML_.</code> 457 * <p> 458 * @return the SBML type code for this object, or {@link libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} (default). 459 * <p> 460 * @see #getElementName() 461 */ public 462 int getTypeCode() { 463 return libsbmlJNI.FunctionDefinition_getTypeCode(swigCPtr, this); 464 } 465 466 467/** 468 * Returns the XML element name of this object, which for 469 * {@link FunctionDefinition}, is always <code>'functionDefinition'.</code> 470 * <p> 471 * @return the name of this element, i.e., <code>'functionDefinition'.</code> 472 */ public 473 String getElementName() { 474 return libsbmlJNI.FunctionDefinition_getElementName(swigCPtr, this); 475 } 476 477 478/** 479 * Predicate returning <code>true</code> if 480 * all the required attributes for this {@link FunctionDefinition} object 481 * have been set. 482 * <p> 483 * @note The required attributes for a {@link FunctionDefinition} object are: 484 * <ul> 485 * <li> 'id' 486 * </ul> 487 * <p> 488 * @return a boolean value indicating whether all the required 489 * attributes for this object have been defined. 490 */ public 491 boolean hasRequiredAttributes() { 492 return libsbmlJNI.FunctionDefinition_hasRequiredAttributes(swigCPtr, this); 493 } 494 495 496/** 497 * Predicate returning <code>true</code> if 498 * all the required elements for this {@link FunctionDefinition} object 499 * have been set. 500 * <p> 501 * @note The required elements for a {@link FunctionDefinition} object are: 502 * <ul> 503 * <li> 'math' 504 * </ul> 505 * <p> 506 * @return a boolean value indicating whether all the required 507 * elements for this object have been defined. 508 */ public 509 boolean hasRequiredElements() { 510 return libsbmlJNI.FunctionDefinition_hasRequiredElements(swigCPtr, this); 511 } 512 513 514/** 515 * Renames all the UnitSIdRef attributes on this element 516 */ public 517 void renameUnitSIdRefs(String oldid, String newid) { 518 libsbmlJNI.FunctionDefinition_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 519 } 520 521}