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&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   * @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&nbsp;3) packages used in addition to SBML Level&nbsp;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 &ldquo;<code>SBML_</code>&rdquo;. 
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&nbsp;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&nbsp;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&nbsp;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&nbsp;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}