001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.8
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&nbsp;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&nbsp;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&mdash;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&nbsp;3) packages used in addition to SBML Level&nbsp;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&nbsp;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 Level&nbsp;3 package plug-ins.
476 * Thus, to identifiy the correct code, <strong>it is necessary to invoke
477 * 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&nbsp;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&nbsp;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}