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&nbsp;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&nbsp;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&mdash;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&nbsp;3) packages used in addition to SBML Level&nbsp;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}