001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.10
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 'math' subelement containing a MathML
027 * expression defining the function body.  In SBML Level&nbsp;2 and SBML
028 * Level&nbsp;3 Version&nbsp;1, that 'math' subelement is required;
029 * in SBML Level&nbsp;3 Version&nbsp;2, this restriction was relaxed,
030 * making the 'math' subelement optional.  The content of this element can
031 * only be a MathML 'lambda' element.  The 'lambda' element must begin with
032 * zero or more 'bvar' elements, followed by any other of the elements in
033 * the MathML subset allowed in SBML Level 2 <em>except</em> 'lambda' (i.e., a
034 * 'lambda' element cannot contain another 'lambda' element).  This is the
035 * only place in SBML where a 'lambda' element can be used.  The function
036 * defined by a {@link FunctionDefinition} is only available for use in other
037 * MathML elements that <em>follow</em> the {@link FunctionDefinition} definition in the
038 * model.  (These restrictions prevent recursive and mutually-recursive
039 * functions from being expressed.)
040 <p>
041 * A further restriction on the content of 'math' is that it cannot contain
042 * references to variables other than the variables declared to the
043 * 'lambda' itself.  That is, the contents of MathML 'ci' elements inside
044 * the body of the 'lambda' can only be the variables declared by its
045 * 'bvar' elements, or the identifiers of other {@link FunctionDefinition}
046 * instances in the model.  This means must be written so that all
047 * variables or parameters used in the MathML content are passed to them
048 * via their function parameters.  In SBML Level&nbsp;2, this restriction
049 * applies also to the MathML <code>csymbol</code> elements for <em>time</em> and 
050 * <em>delay</em>; in SBML Level&nbsp;3, it additionally applies to the <code>csymbol</code>
051 * element for <em>avogadro</em>.
052 <p>
053 * In SBML Level&nbsp;3 Version&nbsp;2, if no math element is present in 
054 * the {@link FunctionDefinition}, the function has no mathematical meaning 
055 * defined in SBML Level&nbsp;3 Core. This situation may arise when models 
056 * are incomplete, or when additional meanings are provided by an SBML 
057 * Level&nbsp;3 package.
058 <p>
059 * @note Function definitions (also informally known as user-defined
060 * functions) were introduced in SBML Level 2.  They have purposefully
061 * limited capabilities.  A function cannot reference parameters or other
062 * model quantities outside of itself; values must be passed as parameters
063 * to the function.  Moreover, recursive and mutually-recursive functions
064 * are not permitted.  The purpose of these limitations is to balance power
065 * against complexity of implementation.  With the restrictions as they
066 * are, function definitions could be implemented as textual
067 * substitutions&mdash;they are simply macros.  Software implementations
068 * therefore do not need the full function-definition machinery typically
069 * associated with programming languages.
070 * <br><br>
071 * Another important point to note is {@link FunctionDefinition} does not
072 * have a separate attribute for defining the units of the value returned
073 * by the function.  The units associated with the function's return value,
074 * when the function is called from within MathML expressions elsewhere in
075 * SBML, are simply the overall units of the expression in
076 * {@link FunctionDefinition}'s 'math' subelement when applied to the arguments
077 * supplied in the call to the function.  Ascertaining these units requires
078 * performing dimensional analysis on the expression.  (Readers may wonder
079 * why there is no attribute.  The reason is that having a separate
080 * attribute for declaring the units would not only be redundant, but also
081 * lead to the potential for having conflicting information.  In the case
082 * of a conflict between the declared units and those of the value actually
083 * returned by the function, the only logical resolution rule would be to
084 * assume that the correct units are those of the expression anyway.)
085 */
086
087public class FunctionDefinition extends SBase {
088   private long swigCPtr;
089
090   protected FunctionDefinition(long cPtr, boolean cMemoryOwn)
091   {
092     super(libsbmlJNI.FunctionDefinition_SWIGUpcast(cPtr), cMemoryOwn);
093     swigCPtr = cPtr;
094   }
095
096   protected static long getCPtr(FunctionDefinition obj)
097   {
098     return (obj == null) ? 0 : obj.swigCPtr;
099   }
100
101   protected static long getCPtrAndDisown (FunctionDefinition obj)
102   {
103     long ptr = 0;
104
105     if (obj != null)
106     {
107       ptr             = obj.swigCPtr;
108       obj.swigCMemOwn = false;
109     }
110
111     return ptr;
112   }
113
114  protected void finalize() {
115    delete();
116  }
117
118  public synchronized void delete() {
119    if (swigCPtr != 0) {
120      if (swigCMemOwn) {
121        swigCMemOwn = false;
122        libsbmlJNI.delete_FunctionDefinition(swigCPtr);
123      }
124      swigCPtr = 0;
125    }
126    super.delete();
127  }
128
129  
130/**
131   * Creates a new {@link FunctionDefinition} using the given SBML <code>level</code> and <code>version</code>
132   * values.
133   <p>
134   * @param level a long integer, the SBML Level to assign to this {@link FunctionDefinition}.
135   <p>
136   * @param version a long integer, the SBML Version to assign to this
137   * {@link FunctionDefinition}.
138   <p>
139   * <p>
140 * @throws SBMLConstructorException
141 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid
142 * or if this object is incompatible with the given level and version.
143   <p>
144   * <p>
145 * @note Attempting to add an object to an {@link SBMLDocument} having a different
146 * combination of SBML Level, Version and XML namespaces than the object
147 * itself will result in an error at the time a caller attempts to make the
148 * addition.  A parent object must have compatible Level, Version and XML
149 * namespaces.  (Strictly speaking, a parent may also have more XML
150 * namespaces than a child, but the reverse is not permitted.)  The
151 * restriction is necessary to ensure that an SBML model has a consistent
152 * overall structure.  This requires callers to manage their objects
153 * carefully, but the benefit is increased flexibility in how models can be
154 * created by permitting callers to create objects bottom-up if desired.  In
155 * situations where objects are not yet attached to parents (e.g.,
156 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
157 * libSBML determine such things as whether it is valid to assign a
158 * particular value to an attribute.
159   */ public
160 FunctionDefinition(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
161    this(libsbmlJNI.new_FunctionDefinition__SWIG_0(level, version), true);
162  }
163
164  
165/**
166   * Creates a new {@link FunctionDefinition} using the given {@link SBMLNamespaces} object
167   * <code>sbmlns</code>.
168   <p>
169   * <p>
170 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
171 * information.  It is used to communicate the SBML Level, Version, and (in
172 * Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.  A
173 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
174 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object
175 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 
176   <p>
177   * @param sbmlns an {@link SBMLNamespaces} object.
178   <p>
179   * <p>
180 * @throws SBMLConstructorException
181 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible
182 * with this object.
183   <p>
184   * <p>
185 * @note Attempting to add an object to an {@link SBMLDocument} having a different
186 * combination of SBML Level, Version and XML namespaces than the object
187 * itself will result in an error at the time a caller attempts to make the
188 * addition.  A parent object must have compatible Level, Version and XML
189 * namespaces.  (Strictly speaking, a parent may also have more XML
190 * namespaces than a child, but the reverse is not permitted.)  The
191 * restriction is necessary to ensure that an SBML model has a consistent
192 * overall structure.  This requires callers to manage their objects
193 * carefully, but the benefit is increased flexibility in how models can be
194 * created by permitting callers to create objects bottom-up if desired.  In
195 * situations where objects are not yet attached to parents (e.g.,
196 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
197 * libSBML determine such things as whether it is valid to assign a
198 * particular value to an attribute.
199   */ public
200 FunctionDefinition(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
201    this(libsbmlJNI.new_FunctionDefinition__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
202  }
203
204  
205/**
206   * Copy constructor; creates a copy of this {@link FunctionDefinition}.
207   <p>
208   * @param orig the object to copy.
209   */ public
210 FunctionDefinition(FunctionDefinition orig) throws org.sbml.libsbml.SBMLConstructorException {
211    this(libsbmlJNI.new_FunctionDefinition__SWIG_2(FunctionDefinition.getCPtr(orig), orig), true);
212  }
213
214  
215/**
216   * Creates and returns a deep copy of this {@link FunctionDefinition} object.
217   <p>
218   * @return the (deep) copy of this {@link FunctionDefinition} object.
219   */ public
220 FunctionDefinition cloneObject() {
221    long cPtr = libsbmlJNI.FunctionDefinition_cloneObject(swigCPtr, this);
222    return (cPtr == 0) ? null : new FunctionDefinition(cPtr, true);
223  }
224
225  
226/**
227   * Returns the value of the 'id' attribute of this {@link FunctionDefinition}.
228   <p>
229   * @note Because of the inconsistent behavior of this function with 
230   * respect to assignments and rules, it is now recommended to
231   * use the getIdAttribute() function instead.
232   <p>
233   * <p>
234 * The identifier given by an object's 'id' attribute value
235 * is used to identify the object within the SBML model definition.
236 * Other objects can refer to the component using this identifier.  The
237 * data type of 'id' is always <code>SId</code> or a type derived
238 * from that, such as <code>UnitSId</code>, depending on the object in 
239 * question.  All data types are defined as follows:
240 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'>
241 *   letter .= 'a'..'z','A'..'Z'
242 *   digit  .= '0'..'9'
243 *   idChar .= letter | digit | '_'
244 *   SId    .= ( letter | '_' ) idChar*
245 * </pre>
246 <p>
247 * The characters <code>(</code> and <code>)</code> are used for grouping, the
248 * character <code>*</code> 'zero or more times', and the character
249 * <code>|</code> indicates logical 'or'.  The equality of SBML identifiers is
250 * determined by an exact character sequence match; i.e., comparisons must be
251 * performed in a case-sensitive manner.  This applies to all uses of <code>SId</code>, 
252 * <code>SIdRef</code>, and derived types.
253 <p>
254 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
255 * moved to {@link SBase} directly, instead of being defined individually for many
256 * (but not all) objects.  Libsbml has for a long time provided functions
257 * defined on {@link SBase} itself to get, set, check, and unset those attributes, which 
258 * would fail or otherwise return empty strings if executed on any object 
259 * for which those attributes were not defined.  Now that all {@link SBase} objects 
260 * define those attributes, those functions now succeed for any object with 
261 * the appropriate level and version.
262 <p>
263 * The exception to this rule is that for {@link InitialAssignment}, {@link EventAssignment}, 
264 * {@link AssignmentRule}, and {@link RateRule} objects, the getId() function and the isSetId() 
265 * functions (though not the setId() or unsetId() functions) would instead 
266 * reference the value of the 'variable' attribute (for the rules and event 
267 * assignments) or the 'symbol' attribute (for initial assignments).  
268 * The {@link AlgebraicRule} fell into this category as well, though because it 
269 * contained neither a 'variable' nor a 'symbol' attribute, getId() would 
270 * always return an empty string, and isSetId() would always return <code>false.</code>
271 * For this reason, four new functions are now provided 
272 * (getIdAttribute(), setIdAttribute(String), 
273 * isSetIdAttribute(), and unsetIdAttribute()) that will always
274 * act on the actual 'id' attribute, regardless of the object's type.  The
275 * new functions should be used instead of the old ones unless the old behavior
276 * is somehow necessary.
277 <p>
278 * Regardless of the level and version of the SBML, these functions allow
279 * client applications to use more generalized code in some situations 
280 * (for instance, when manipulating objects that are all known to have 
281 * identifiers).  If the object in question does not posess an 'id' attribute 
282 * according to the SBML specification for the Level and Version in use,
283 * libSBML will not allow the identifier to be set, nor will it read or 
284 * write 'id' attributes for those objects.
285   <p>
286   * @return the id of this {@link FunctionDefinition}.
287   <p>
288   * @see #getIdAttribute()
289   * @see #setIdAttribute(String sid)
290   * @see #isSetIdAttribute()
291   * @see #unsetIdAttribute()
292   */ public
293 String getId() {
294    return libsbmlJNI.FunctionDefinition_getId(swigCPtr, this);
295  }
296
297  
298/**
299   * Returns the value of the 'name' attribute of this {@link FunctionDefinition} object.
300   <p>
301   * <p>
302 * <p>
303 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
304 * moved to {@link SBase} directly, instead of being defined individually for many
305 * (but not all) objects.  Libsbml has for a long time provided functions
306 * defined on {@link SBase} itself to get, set, and unset those attributes, which 
307 * would fail or otherwise return empty strings if executed on any object 
308 * for which those attributes were not defined.  Now that all {@link SBase} objects 
309 * define those attributes, those functions now succeed for any object with 
310 * the appropriate level and version.
311 <p>
312 * The 'name' attribute is
313 * optional and is not intended to be used for cross-referencing purposes
314 * within a model.  Its purpose instead is to provide a human-readable
315 * label for the component.  The data type of 'name' is the type
316 * <code>string</code> defined in XML Schema.  SBML imposes no
317 * restrictions as to the content of 'name' attributes beyond those
318 * restrictions defined by the <code>string</code> type in XML Schema.
319 <p>
320 * The recommended practice for handling 'name' is as follows.  If a
321 * software tool has the capability for displaying the content of 'name'
322 * attributes, it should display this content to the user as a
323 * component's label instead of the component's 'id'.  If the user
324 * interface does not have this capability (e.g., because it cannot
325 * display or use special characters in symbol names), or if the 'name'
326 * attribute is missing on a given component, then the user interface
327 * should display the value of the 'id' attribute instead.  (Script
328 * language interpreters are especially likely to display 'id' instead of
329 * 'name'.)
330 <p>
331 * As a consequence of the above, authors of systems that automatically
332 * generate the values of 'id' attributes should be aware some systems
333 * may display the 'id''s to the user.  Authors therefore may wish to
334 * take some care to have their software create 'id' values that are: (a)
335 * reasonably easy for humans to type and read; and (b) likely to be
336 * meaningful, for example by making the 'id' attribute be an abbreviated
337 * form of the name attribute value.
338 <p>
339 * An additional point worth mentioning is although there are
340 * restrictions on the uniqueness of 'id' values, there are no
341 * restrictions on the uniqueness of 'name' values in a model.  This
342 * allows software applications leeway in assigning component identifiers.
343 <p>
344 * Regardless of the level and version of the SBML, these functions allow
345 * client applications to use more generalized code in some situations 
346 * (for instance, when manipulating objects that are all known to have 
347 * names).  If the object in question does not posess a 'name' attribute 
348 * according to the SBML specification for the Level and Version in use,
349 * libSBML will not allow the name to be set, nor will it read or 
350 * write 'name' attributes for those objects.
351 <p>
352 * @return the name of this SBML object, or the empty string if not set or unsettable.
353 <p>
354 * @see #getIdAttribute()
355 * @see #isSetName()
356 * @see #setName(String sid)
357 * @see #unsetName()
358   */ public
359 String getName() {
360    return libsbmlJNI.FunctionDefinition_getName(swigCPtr, this);
361  }
362
363  
364/**
365   * Get the mathematical formula of this {@link FunctionDefinition}.
366   <p>
367   * @return an {@link ASTNode}, the value of the 'math' subelement of this
368   * {@link FunctionDefinition}, or <code>null</code> if the math is not set.
369   */ public
370 ASTNode getMath() {
371    long cPtr = libsbmlJNI.FunctionDefinition_getMath(swigCPtr, this);
372    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
373  }
374
375  
376/**
377   * Predicate returning <code>true</code> if this
378   * {@link FunctionDefinition}'s 'id' attribute is set.
379   <p>
380   * <p>
381 * @note Because of the inconsistent behavior of this function with 
382 * respect to assignments and rules, it is now recommended to
383 * use the isSetIdAttribute() function instead.
384 <p>
385 * <p>
386 * The identifier given by an object's 'id' attribute value
387 * is used to identify the object within the SBML model definition.
388 * Other objects can refer to the component using this identifier.  The
389 * data type of 'id' is always <code>SId</code> or a type derived
390 * from that, such as <code>UnitSId</code>, depending on the object in 
391 * question.  All data types are defined as follows:
392 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'>
393 *   letter .= 'a'..'z','A'..'Z'
394 *   digit  .= '0'..'9'
395 *   idChar .= letter | digit | '_'
396 *   SId    .= ( letter | '_' ) idChar*
397 * </pre>
398 <p>
399 * The characters <code>(</code> and <code>)</code> are used for grouping, the
400 * character <code>*</code> 'zero or more times', and the character
401 * <code>|</code> indicates logical 'or'.  The equality of SBML identifiers is
402 * determined by an exact character sequence match; i.e., comparisons must be
403 * performed in a case-sensitive manner.  This applies to all uses of <code>SId</code>, 
404 * <code>SIdRef</code>, and derived types.
405 <p>
406 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
407 * moved to {@link SBase} directly, instead of being defined individually for many
408 * (but not all) objects.  Libsbml has for a long time provided functions
409 * defined on {@link SBase} itself to get, set, check, and unset those attributes, which 
410 * would fail or otherwise return empty strings if executed on any object 
411 * for which those attributes were not defined.  Now that all {@link SBase} objects 
412 * define those attributes, those functions now succeed for any object with 
413 * the appropriate level and version.
414 <p>
415 * The exception to this rule is that for {@link InitialAssignment}, {@link EventAssignment}, 
416 * {@link AssignmentRule}, and {@link RateRule} objects, the getId() function and the isSetId() 
417 * functions (though not the setId() or unsetId() functions) would instead 
418 * reference the value of the 'variable' attribute (for the rules and event 
419 * assignments) or the 'symbol' attribute (for initial assignments).  
420 * The {@link AlgebraicRule} fell into this category as well, though because it 
421 * contained neither a 'variable' nor a 'symbol' attribute, getId() would 
422 * always return an empty string, and isSetId() would always return <code>false.</code>
423 * For this reason, four new functions are now provided 
424 * (getIdAttribute(), setIdAttribute(String), 
425 * isSetIdAttribute(), and unsetIdAttribute()) that will always
426 * act on the actual 'id' attribute, regardless of the object's type.  The
427 * new functions should be used instead of the old ones unless the old behavior
428 * is somehow necessary.
429 <p>
430 * Regardless of the level and version of the SBML, these functions allow
431 * client applications to use more generalized code in some situations 
432 * (for instance, when manipulating objects that are all known to have 
433 * identifiers).  If the object in question does not posess an 'id' attribute 
434 * according to the SBML specification for the Level and Version in use,
435 * libSBML will not allow the identifier to be set, nor will it read or 
436 * write 'id' attributes for those objects.
437 <p>
438 * @return <code>true</code> if the 'id' attribute of this SBML object is
439 * set, <code>false</code> otherwise.
440 <p>
441 * @see #getIdAttribute()
442 * @see #setIdAttribute(String sid)
443 * @see #unsetIdAttribute()
444 * @see #isSetIdAttribute()
445   */ public
446 boolean isSetId() {
447    return libsbmlJNI.FunctionDefinition_isSetId(swigCPtr, this);
448  }
449
450  
451/**
452   * Predicate returning <code>true</code> if this
453   * {@link FunctionDefinition}'s 'name' attribute is set.
454   <p>
455   * <p>
456 * <p>
457 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
458 * moved to {@link SBase} directly, instead of being defined individually for many
459 * (but not all) objects.  Libsbml has for a long time provided functions
460 * defined on {@link SBase} itself to get, set, and unset those attributes, which 
461 * would fail or otherwise return empty strings if executed on any object 
462 * for which those attributes were not defined.  Now that all {@link SBase} objects 
463 * define those attributes, those functions now succeed for any object with 
464 * the appropriate level and version.
465 <p>
466 * The 'name' attribute is
467 * optional and is not intended to be used for cross-referencing purposes
468 * within a model.  Its purpose instead is to provide a human-readable
469 * label for the component.  The data type of 'name' is the type
470 * <code>string</code> defined in XML Schema.  SBML imposes no
471 * restrictions as to the content of 'name' attributes beyond those
472 * restrictions defined by the <code>string</code> type in XML Schema.
473 <p>
474 * The recommended practice for handling 'name' is as follows.  If a
475 * software tool has the capability for displaying the content of 'name'
476 * attributes, it should display this content to the user as a
477 * component's label instead of the component's 'id'.  If the user
478 * interface does not have this capability (e.g., because it cannot
479 * display or use special characters in symbol names), or if the 'name'
480 * attribute is missing on a given component, then the user interface
481 * should display the value of the 'id' attribute instead.  (Script
482 * language interpreters are especially likely to display 'id' instead of
483 * 'name'.)
484 <p>
485 * As a consequence of the above, authors of systems that automatically
486 * generate the values of 'id' attributes should be aware some systems
487 * may display the 'id''s to the user.  Authors therefore may wish to
488 * take some care to have their software create 'id' values that are: (a)
489 * reasonably easy for humans to type and read; and (b) likely to be
490 * meaningful, for example by making the 'id' attribute be an abbreviated
491 * form of the name attribute value.
492 <p>
493 * An additional point worth mentioning is although there are
494 * restrictions on the uniqueness of 'id' values, there are no
495 * restrictions on the uniqueness of 'name' values in a model.  This
496 * allows software applications leeway in assigning component identifiers.
497 <p>
498 * Regardless of the level and version of the SBML, these functions allow
499 * client applications to use more generalized code in some situations 
500 * (for instance, when manipulating objects that are all known to have 
501 * names).  If the object in question does not posess a 'name' attribute 
502 * according to the SBML specification for the Level and Version in use,
503 * libSBML will not allow the name to be set, nor will it read or 
504 * write 'name' attributes for those objects.
505 <p>
506 * @return <code>true</code> if the 'name' attribute of this SBML object is
507 * set, <code>false</code> otherwise.
508 <p>
509 * @see #getName()
510 * @see #setName(String sid)
511 * @see #unsetName()
512   */ public
513 boolean isSetName() {
514    return libsbmlJNI.FunctionDefinition_isSetName(swigCPtr, this);
515  }
516
517  
518/**
519   * Predicate returning <code>true</code> if this
520   * {@link FunctionDefinition}'s 'math' subelement contains a value.
521   <p>
522   * @return <code>true</code> if the 'math' for this {@link FunctionDefinition} is set,
523   * <code>false</code> otherwise.
524   */ public
525 boolean isSetMath() {
526    return libsbmlJNI.FunctionDefinition_isSetMath(swigCPtr, this);
527  }
528
529  
530/**
531   * Sets the value of the 'id' attribute of this {@link FunctionDefinition}.
532   <p>
533   * <p>
534 * The string <code>sid</code> is copied.
535 <p>
536 * <p>
537 * The identifier given by an object's 'id' attribute value
538 * is used to identify the object within the SBML model definition.
539 * Other objects can refer to the component using this identifier.  The
540 * data type of 'id' is always <code>SId</code> or a type derived
541 * from that, such as <code>UnitSId</code>, depending on the object in 
542 * question.  All data types are defined as follows:
543 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'>
544 *   letter .= 'a'..'z','A'..'Z'
545 *   digit  .= '0'..'9'
546 *   idChar .= letter | digit | '_'
547 *   SId    .= ( letter | '_' ) idChar*
548 * </pre>
549 <p>
550 * The characters <code>(</code> and <code>)</code> are used for grouping, the
551 * character <code>*</code> 'zero or more times', and the character
552 * <code>|</code> indicates logical 'or'.  The equality of SBML identifiers is
553 * determined by an exact character sequence match; i.e., comparisons must be
554 * performed in a case-sensitive manner.  This applies to all uses of <code>SId</code>, 
555 * <code>SIdRef</code>, and derived types.
556 <p>
557 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
558 * moved to {@link SBase} directly, instead of being defined individually for many
559 * (but not all) objects.  Libsbml has for a long time provided functions
560 * defined on {@link SBase} itself to get, set, check, and unset those attributes, which 
561 * would fail or otherwise return empty strings if executed on any object 
562 * for which those attributes were not defined.  Now that all {@link SBase} objects 
563 * define those attributes, those functions now succeed for any object with 
564 * the appropriate level and version.
565 <p>
566 * The exception to this rule is that for {@link InitialAssignment}, {@link EventAssignment}, 
567 * {@link AssignmentRule}, and {@link RateRule} objects, the getId() function and the isSetId() 
568 * functions (though not the setId() or unsetId() functions) would instead 
569 * reference the value of the 'variable' attribute (for the rules and event 
570 * assignments) or the 'symbol' attribute (for initial assignments).  
571 * The {@link AlgebraicRule} fell into this category as well, though because it 
572 * contained neither a 'variable' nor a 'symbol' attribute, getId() would 
573 * always return an empty string, and isSetId() would always return <code>false.</code>
574 * For this reason, four new functions are now provided 
575 * (getIdAttribute(), setIdAttribute(String), 
576 * isSetIdAttribute(), and unsetIdAttribute()) that will always
577 * act on the actual 'id' attribute, regardless of the object's type.  The
578 * new functions should be used instead of the old ones unless the old behavior
579 * is somehow necessary.
580 <p>
581 * Regardless of the level and version of the SBML, these functions allow
582 * client applications to use more generalized code in some situations 
583 * (for instance, when manipulating objects that are all known to have 
584 * identifiers).  If the object in question does not posess an 'id' attribute 
585 * according to the SBML specification for the Level and Version in use,
586 * libSBML will not allow the identifier to be set, nor will it read or 
587 * write 'id' attributes for those objects.
588 <p>
589 * @param sid the string to use as the identifier of this object.
590 <p>
591 * <p>
592 * @return integer value indicating success/failure of the
593 * function.   The possible values
594 * returned by this function are:
595 * <ul>
596 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
597 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE}
598 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
599 *
600 * </ul> <p>
601 * @see #getIdAttribute()
602 * @see #setIdAttribute(String sid)
603 * @see #isSetIdAttribute()
604 * @see #unsetIdAttribute()
605   */ public
606 int setId(String sid) {
607    return libsbmlJNI.FunctionDefinition_setId(swigCPtr, this, sid);
608  }
609
610  
611/**
612   * Sets the value of the 'name' attribute of this {@link FunctionDefinition}.
613   <p>
614   * <p>
615 * The string in <code>name</code> is copied.
616 <p>
617 * @param name the new name for the SBML object.
618 <p>
619 * <p>
620 * @return integer value indicating success/failure of the
621 * function.   The possible values
622 * returned by this function are:
623 * <ul>
624 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
625 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE}
626 *
627 * </ul>
628   */ public
629 int setName(String name) {
630    return libsbmlJNI.FunctionDefinition_setName(swigCPtr, this, name);
631  }
632
633  
634/**
635   * Sets the 'math' subelement of this {@link FunctionDefinition} to the Abstract
636   * Syntax Tree given in <code>math</code>.
637   <p>
638   * @param math an AST containing the mathematical expression to
639   * be used as the formula for this {@link FunctionDefinition}.
640   <p>
641   * <p>
642 * @return integer value indicating success/failure of the
643 * function.   The possible values
644 * returned by this function are:
645   * <ul>
646   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
647   * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT}
648   * </ul>
649   */ public
650 int setMath(ASTNode math) {
651    return libsbmlJNI.FunctionDefinition_setMath(swigCPtr, this, ASTNode.getCPtr(math), math);
652  }
653
654  
655/**
656   * Unsets the value of the 'name' attribute of this {@link FunctionDefinition}.
657   <p>
658   * <p>
659 * <p>
660 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
661 * moved to {@link SBase} directly, instead of being defined individually for many
662 * (but not all) objects.  Libsbml has for a long time provided functions
663 * defined on {@link SBase} itself to get, set, and unset those attributes, which 
664 * would fail or otherwise return empty strings if executed on any object 
665 * for which those attributes were not defined.  Now that all {@link SBase} objects 
666 * define those attributes, those functions now succeed for any object with 
667 * the appropriate level and version.
668 <p>
669 * The 'name' attribute is
670 * optional and is not intended to be used for cross-referencing purposes
671 * within a model.  Its purpose instead is to provide a human-readable
672 * label for the component.  The data type of 'name' is the type
673 * <code>string</code> defined in XML Schema.  SBML imposes no
674 * restrictions as to the content of 'name' attributes beyond those
675 * restrictions defined by the <code>string</code> type in XML Schema.
676 <p>
677 * The recommended practice for handling 'name' is as follows.  If a
678 * software tool has the capability for displaying the content of 'name'
679 * attributes, it should display this content to the user as a
680 * component's label instead of the component's 'id'.  If the user
681 * interface does not have this capability (e.g., because it cannot
682 * display or use special characters in symbol names), or if the 'name'
683 * attribute is missing on a given component, then the user interface
684 * should display the value of the 'id' attribute instead.  (Script
685 * language interpreters are especially likely to display 'id' instead of
686 * 'name'.)
687 <p>
688 * As a consequence of the above, authors of systems that automatically
689 * generate the values of 'id' attributes should be aware some systems
690 * may display the 'id''s to the user.  Authors therefore may wish to
691 * take some care to have their software create 'id' values that are: (a)
692 * reasonably easy for humans to type and read; and (b) likely to be
693 * meaningful, for example by making the 'id' attribute be an abbreviated
694 * form of the name attribute value.
695 <p>
696 * An additional point worth mentioning is although there are
697 * restrictions on the uniqueness of 'id' values, there are no
698 * restrictions on the uniqueness of 'name' values in a model.  This
699 * allows software applications leeway in assigning component identifiers.
700 <p>
701 * Regardless of the level and version of the SBML, these functions allow
702 * client applications to use more generalized code in some situations 
703 * (for instance, when manipulating objects that are all known to have 
704 * names).  If the object in question does not posess a 'name' attribute 
705 * according to the SBML specification for the Level and Version in use,
706 * libSBML will not allow the name to be set, nor will it read or 
707 * write 'name' attributes for those objects.
708 <p>
709 * <p>
710 * @return integer value indicating success/failure of the
711 * function.   The possible values
712 * returned by this function are:
713 * <ul>
714 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
715 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
716 *
717 * </ul> <p>
718 * @see #getName()
719 * @see #setName(String sid)
720 * @see #isSetName()
721   */ public
722 int unsetName() {
723    return libsbmlJNI.FunctionDefinition_unsetName(swigCPtr, this);
724  }
725
726  
727/**
728   * Get the <code>n</code>th argument to this function.
729   <p>
730   * Callers should first find out the number of arguments to the function
731   * by calling getNumArguments().
732   <p>
733   * @param n an integer index for the argument sought.
734   <p>
735   * @return the nth argument (bound variable) passed to this
736   * {@link FunctionDefinition}.
737   <p>
738   * @see #getNumArguments()
739   */ public
740 ASTNode getArgument(long n) {
741    long cPtr = libsbmlJNI.FunctionDefinition_getArgument__SWIG_0(swigCPtr, this, n);
742    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
743  }
744
745  
746/**
747   * Get the argument named <code>name</code> to this {@link FunctionDefinition}.
748   <p>
749   * @param name the exact name (case-sensitive) of the sought-after
750   * argument.
751   <p>
752   * @return the argument (bound variable) having the given name, or <code>null</code> if
753   * no such argument exists.
754   */ public
755 ASTNode getArgument(String name) {
756    long cPtr = libsbmlJNI.FunctionDefinition_getArgument__SWIG_1(swigCPtr, this, name);
757    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
758  }
759
760  
761/**
762   * Get the mathematical expression that is the body of this
763   * {@link FunctionDefinition} object.
764   <p>
765   * @return the body of this {@link FunctionDefinition} as an Abstract Syntax
766   * Tree, or <code>null</code> if no body is defined.
767   */ public
768 ASTNode getBody() {
769    long cPtr = libsbmlJNI.FunctionDefinition_getBody__SWIG_0(swigCPtr, this);
770    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
771  }
772
773  
774/**
775   * Predicate returning <code>true</code> if the body of this
776   * {@link FunctionDefinition} has set.
777   <p>
778   * @return <code>true</code> if the body of this {@link FunctionDefinition} is 
779   * set, <code>false</code> otherwise.
780   */ public
781 boolean isSetBody() {
782    return libsbmlJNI.FunctionDefinition_isSetBody(swigCPtr, this);
783  }
784
785  
786/**
787   * Get the number of arguments (bound variables) taken by this
788   * {@link FunctionDefinition}.
789   <p>
790   * @return the number of arguments (bound variables) that must be passed
791   * to this {@link FunctionDefinition}.
792   */ public
793 long getNumArguments() {
794    return libsbmlJNI.FunctionDefinition_getNumArguments(swigCPtr, this);
795  }
796
797  
798/**
799   * Returns the libSBML type code for this SBML object.
800   <p>
801   * <p>
802 * LibSBML attaches an identifying code to every kind of SBML object.  These
803 * are integer constants known as <em>SBML type codes</em>.  The names of all
804 * the codes begin with the characters <code>SBML_</code>.
805 * In the Java language interface for libSBML, the
806 * type codes are defined as static integer constants in the interface class
807 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
808 * package plug-ins may use overlapping type codes; to identify the package
809 * to which a given object belongs, call the <code>getPackageName()</code>
810 * method on the object.
811   <p>
812   * @return the SBML type code for this object:
813   * {@link libsbmlConstants#SBML_FUNCTION_DEFINITION SBML_FUNCTION_DEFINITION} (default).
814   <p>
815   * <p>
816 * @warning <span class='warning'>The specific integer values of the possible
817 * type codes may be reused by different libSBML plug-ins for SBML Level&nbsp;3.
818 * packages,  To fully identify the correct code, <strong>it is necessary to
819 * invoke both getTypeCode() and getPackageName()</strong>.</span>
820   <p>
821   * @see #getElementName()
822   * @see #getPackageName()
823   */ public
824 int getTypeCode() {
825    return libsbmlJNI.FunctionDefinition_getTypeCode(swigCPtr, this);
826  }
827
828  
829/**
830   * Returns the XML element name of this object, which for
831   * {@link FunctionDefinition}, is always <code>'functionDefinition'.</code>
832   <p>
833   * @return the name of this element, i.e., <code>'functionDefinition'.</code>
834   */ public
835 String getElementName() {
836    return libsbmlJNI.FunctionDefinition_getElementName(swigCPtr, this);
837  }
838
839  
840/**
841   * Predicate returning <code>true</code> if
842   * all the required attributes for this {@link FunctionDefinition} object
843   * have been set.
844   <p>
845   * The required attributes for a {@link FunctionDefinition} object are:
846   * <ul>
847   * <li> 'id'
848   *
849   * </ul> <p>
850   * @return <code>true</code> if the required attributes have been set, <code>false</code>
851   * otherwise.
852   */ public
853 boolean hasRequiredAttributes() {
854    return libsbmlJNI.FunctionDefinition_hasRequiredAttributes(swigCPtr, this);
855  }
856
857  
858/**
859   * Predicate returning <code>true</code> if
860   * all the required elements for this {@link FunctionDefinition} object
861   * have been set.
862   <p>
863   * @note The required elements for a {@link FunctionDefinition} object are:
864   * <ul>
865   * <li> 'math' inSBML Level&nbsp;2 and Level&nbsp;3 Version&nbsp;1.  
866   *     (In SBML Level&nbsp;3 Version&nbsp;2+, it is no longer required.)
867   *
868   * </ul> <p>
869   * @return a boolean value indicating whether all the required
870   * elements for this object have been defined.
871   */ public
872 boolean hasRequiredElements() {
873    return libsbmlJNI.FunctionDefinition_hasRequiredElements(swigCPtr, this);
874  }
875
876  
877/**
878   * Renames all the <code>UnitSIdRef</code> attributes on this element.
879   <p>
880   * <p>
881 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>.  In
882 * SBML Level&nbsp;3, an explicit data type called <code>UnitSIdRef</code> was
883 * introduced for attribute values that refer to <code>UnitSId</code> values; in
884 * previous Levels of SBML, this data type did not exist and attributes were
885 * simply described to as 'referring to a unit identifier', but the effective
886 * data type was the same as <code>UnitSIdRef</code> in Level&nbsp;3.  These and
887 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all
888 * Levels of SBML, even if the corresponding SBML specification did not
889 * explicitly name the data type.
890   <p>
891   * This method works by looking at all unit identifier attribute values
892   * (including, if appropriate, inside mathematical formulas), comparing the
893   * unit identifiers to the value of <code>oldid</code>.  If any matches are found,
894   * the matching identifiers are replaced with <code>newid</code>.  The method does
895   * <em>not</em> descend into child elements.
896   <p>
897   * @param oldid the old identifier.
898   * @param newid the new identifier.
899   */ public
900 void renameUnitSIdRefs(String oldid, String newid) {
901    libsbmlJNI.FunctionDefinition_renameUnitSIdRefs(swigCPtr, this, oldid, newid);
902  }
903
904}