001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.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 *  A definition of a unit used in an SBML model.
013 <p>
014 * Units of measurement may be supplied in a number of contexts in an SBML
015 * model.  The SBML unit definition facility uses two classes of objects,
016 * {@link UnitDefinition} and {@link Unit}.  The approach to defining units in SBML is
017 * compositional; for example, <em>meter second<sup> &ndash;2</sup></em> is
018 * constructed by combining a {@link Unit} object representing <em>meter</em> with
019 * another {@link Unit} object representing <em>second<sup> &ndash;2</sup></em>.
020 * The combination is wrapped inside a {@link UnitDefinition}, which provides for
021 * assigning an identifier and optional name to the combination.  The
022 * identifier can then be referenced from elsewhere in a model.  Thus, the
023 * {@link UnitDefinition} class is the container, and {@link Unit} instances are placed
024 * inside {@link UnitDefinition} instances.
025 <p>
026 * Two points are worth discussing in the context of SBML units.  First,
027 * unit declarations in SBML models are <em>optional</em>.  The consequence of
028 * this is that a model must be numerically self-consistent independently
029 * of unit declarations, for the benefit of software tools that cannot
030 * interpret or manipulate units.  {@link Unit} declarations in SBML are thus more
031 * akin to a type of annotation; they can indicate intentions, and can be
032 * used by model readers for checking the consistency of the model,
033 * labeling simulation output, etc., but any transformations of values
034 * implied by different units must be incorporated <em>explicitly</em> into a
035 * model.
036 <p>
037 * Second, the vast majority of situations that require new SBML unit
038 * definitions involve simple multiplicative combinations of base units and
039 * factors.  An example is <em>moles per litre per second</em>.  What
040 * distinguishes these sorts of unit definitions from more complex ones is
041 * that they may be expressed without the use of an additive offset from a
042 * zero point.  The use of offsets complicates all unit definition systems,
043 * yet in the domain of SBML, the real-life cases requiring offsets are few
044 * (and in fact, to the best of our knowledge, only involve temperature).
045 * Consequently, the SBML unit system has been consciously designed to
046 * simplify implementation of unit support for the most common cases in
047 * systems biology.  The cost of this simplification is to require units
048 * with offsets to be handled explicitly by the modeler.
049 <p>
050 * <h2>Summary of the {@link UnitDefinition} construct</h2>
051 <p>
052 * {@link UnitDefinition} has two attributes and one subelement.  The two
053 * attributes are 'id' and 'name', and the subelement is {@link ListOfUnits}.
054 <p>
055 * The required attribute 'id' and optional attribute 'name' are both
056 * strings.  The 'id' attribute is used to give the defined unit a unique
057 * identifier by which other parts of an SBML model definition can refer to
058 * it.  The 'name' attribute is intended to be used for giving the unit
059 * definition an optional human-readable name.  Please see the <a
060 * href='#unitdef-id'>next section</a> for information about the values
061 * permitted for 'id'.
062 <p>
063 * A {@link UnitDefinition} may contain exactly one {@link ListOfUnits}, and this list
064 * may contain one or more {@link Unit} definitions; see the definitions of these
065 * other object classes for more information about them.  In SBML 
066 * Level&nbsp;2 and SBML Level&nbsp;3 Version&nbsp;1, if the {@link ListOfUnits}
067 * was present, it must have one or more {@link Unit} definitions.  In SBML
068 * Level&nbsp;3 Version&nbsp;2, this restriction was relaxed, and 
069 * a {@link ListOfUnits} was allowed to be empty.  In either case, if a
070 * {@link UnitDefinition} had no child {@link Unit} elements, the unit was considered
071 * to be undefined.
072 <p>
073 * The following
074 * example illustrates a complete unit definition (when written in XML)
075 * when all the pieces are combined together.  This defines 'mmls'
076 * to be millimoles per litre per second.
077 * <pre class='fragment'>
078 &lt;listOfUnitDefinitions&gt;
079     &lt;unitDefinition id='mmls'&gt;
080         &lt;listOfUnits&gt;
081             &lt;unit kind='mole'   scale='-3'/&gt;
082             &lt;unit kind='litre'  exponent='-1'/&gt;
083             &lt;unit kind='second' exponent='-1'/&gt;
084         &lt;/listOfUnits&gt;
085     &lt;/unitDefinition&gt;
086 &lt;/listOfUnitDefinitions&gt;
087 </pre>
088 <p>
089 * <h2>Special considerations for {@link Unit} object identifiers</h2>
090 <p>
091 * The attribute 'id' in {@link UnitDefinition} cannot be given simply any value,
092 * and the precise details of the values permitted differ slightly between
093 * Levels of SBML:
094 * <ul>
095 <p>
096 * <li> The 'id' of a {@link UnitDefinition} must <em>not</em> contain a value from the
097 * list of SBML's predefined base unit names (i.e., the strings <code>gram</code>,
098 * <code>litre</code>, etc.).  In SBML Level&nbsp;3, this list consists of the
099 * following:
100 <p>
101 * <p>
102<table border='0' class='centered text-table width80 normal-font code'
103       style='border: none !important'>
104<tr>
105<td>ampere</td><td>farad</td><td>joule</td><td>lux</td><td>radian</td><td>volt</td>
106</tr>
107<tr>
108<td>avogadro</td><td>gram</td><td>katal</td><td>metre</td><td>second</td><td>watt</td>
109</tr>
110<tr>
111<td>becquerel</td><td>gray</td><td>kelvin</td><td>mole</td><td>siemens</td><td>weber</td>
112</tr>
113<tr>
114<td>candela</td><td>henry</td><td>kilogram</td><td>newton</td><td>sievert</td>
115</tr>
116<tr>
117<td>coulomb</td><td>hertz</td><td>litre</td><td>ohm</td><td>steradian</td>
118</tr>
119<tr>
120<td>dimensionless</td><td>item</td><td>lumen</td><td>pascal</td><td>tesla</td>
121</tr>
122</table>
123 <p>
124 * This list of predefined base units is nearly identical in SBML
125 * Level&nbsp;2 Version&nbsp;4, the exception being that Level&nbsp;2 does
126 * not define <code>avogadro.</code>  SBML Level&nbsp;2 Version&nbsp;1 (and <em>only</em>
127 * this Level+Version combination) provides an additional predefined unit
128 * name, <code>Celsius</code>, not available in Level&nbsp;3.  Finally, SBML
129 * Level&nbsp;1 Versions&nbsp;2&ndash;3 provide two more additional
130 * predefined unit names, <code>meter</code> and <code>liter.</code>  This is explained in
131 * somewhat greater detail in the description of the {@link Unit} class.
132 <p>
133 * <ul>
134 * <li> In SBML Level&nbsp;2 (all Versions), there is an additional set of
135 * reserved identifiers: <code>substance</code>, <code>volume</code>, <code>area</code>, <code>length</code>, and
136 * <code>time.</code>  Using one of these values for the attribute 'id' of a
137 * {@link UnitDefinition} has the effect of redefining the model-wide default units
138 * for the corresponding quantities.  The list of special unit names in
139 * SBML Level&nbsp;2 is given in the table below:
140 * </ul>
141 <p>
142 *   <table border="0" class="centered text-table width80 normal-font alt-row-colors">
143 <tr>
144     <th align="left">Identifier</th>
145     <th align="left">Possible scalable units</th>
146     <th align="left">Default units</th>
147 </tr>
148<tr><td><code>substance</code></td><td>mole, item, gram, kilogram, dimensionless</td><td>mole</td></tr>
149<tr><td><code>volume</code></td><td>litre, cubic metre, dimensionless</td><td>litre</td></tr>
150<tr><td><code>area</code></td><td>square metre, dimensionless</td><td>square metre</td></tr>
151<tr><td><code>length</code></td><td>metre, dimensionless</td><td>metre</td></tr>
152<tr><td><code>time</code></td><td>second, dimensionless</td><td>second</td></tr>
153</table>
154
155
156 <p>
157 * Also, SBML Level&nbsp;2 imposes two limitations on redefining the
158 * predefined unit <code>substance</code>, <code>volume</code>, <code>area</code>, <code>length</code>, and
159 * <code>time:</code> (1) The {@link UnitDefinition} of a predefined SBML unit can only contain
160 * a single {@link Unit} object within it.  (2) The value of the 'kind' attribute
161 * in a {@link Unit} instance must be drawn from one of the values in the second
162 * column of the table above.
163 <p>
164 * The special unit names <code>substance</code>, <code>volume</code>, <code>area</code>, <code>length</code>, and
165 * <code>time</code> are not defined by SBML Level&nbsp;3, which uses a different
166 * approach to setting model-wide inherited units.
167 <p>
168 * <h2>Further comments about SBML's unit definition system</h2>
169 <p>
170 * The vast majority of modeling situations requiring new SBML unit
171 * definitions involve simple multiplicative combinations of base units and
172 * factors.  An example of this might be <em>moles per litre per
173 * second</em>.  What distinguishes these sorts of simpler unit definitions
174 * from more complex ones is that they may be expressed without the use of
175 * an additive offset from a zero point.  The use of offsets complicates
176 * all unit definition systems, yet in the domain of SBML the real-life
177 * cases requiring offsets are few (and in fact, to the best of our
178 * knowledge, only involve temperature).  Consequently, the SBML unit
179 * system has been consciously designed in a way that attempts to simplify
180 * implementation of unit support for the most common cases in systems
181 * biology.
182 <p>
183 * As of SBML Level&nbsp;2 Version&nbsp;2, {@link Unit} no longer has the
184 * attribute called 'offset' introduced in SBML Level&nbsp;2
185 * Version&nbsp;1.  It turned out that the general case involving units
186 * with offsets was incorrectly defined, and few (if any) developers even
187 * attempted to support offset-based units in their software.  In the
188 * development of Level&nbsp;2 Version&nbsp;2, a consensus among SBML
189 * developers emerged that a fully generalized unit scheme is <em>so</em>
190 * confusing and complicated that it actually <em>impedes</em> interoperability.
191 * SBML Level&nbsp;2 Version&nbsp;2, Version&nbsp;3 and Version&nbsp;4 acknowledge this
192 * reality by reducing and simplifying the unit system, specifically by
193 * removing the 'offset' attribute on {@link Unit} and <code>Celsius</code> as a pre-defined
194 * unit.
195 <p>
196 * The following guidelines suggest methods for handling units that do
197 * require the use of zero offsets for their definitions:
198 * <ul>
199 * <li> <em>Handling Celsius</em>.  A model in which certain quantities are
200 *   temperatures measured in degrees Celsius can be converted
201 *   straightforwardly to a model in which those temperatures are in
202 *   kelvin.  A software tool could do this by performing a straightforward
203 *   substitution using the following relationship: <em>T<sub> kelvin</sub> =
204 *   T<sub>Celsius</sub> + 273.15</em>.  In every mathematical formula of the
205 *   model where a quantity (call it <em>x</em>) in degrees Celsius appears,
206 *   replace <em>x</em> with <em>x<sub>k</sub>+ 273.15</em>, where
207 *   <em>x<sub>k</sub></em> is now in kelvin.  An alternative approach would 
208 *   be to use a {@link FunctionDefinition} object to define a function encapsulating this
209 *   relationship above and then using that in the rest of the model as
210 *   needed.  Since Celsius is a commonly-used unit, software tools could
211 *   help users by providing users with the ability to express temperatures
212 *   in Celsius in the tools' interfaces, and making substitutions
213 *   automatically when writing out the SBML.
214 <p>
215 * <li> <em>Other units requiring offsets</em>.  One approach to handling
216 *   other kinds of units is to use a {@link FunctionDefinition} to define a function
217 *   encapsulating the necessary mathematical relationship, then
218 *   substituting a call to this function wherever the original quantity
219 *   appeared in the model.  For example, here is a possible definition for
220 *   converting Fahrenheit to Celsius degrees:
221 *   <pre class='fragment'>
222 &lt;functionDefinition id='Fahrenheit_to_kelvin'&gt;
223     &lt;math xmlns='http://www.w3.org/1998/Math/MathML'&gt;
224         &lt;lambda&gt;
225             &lt;bvar&gt;&lt;ci&gt; temp_in_fahrenheit &lt;/ci&gt;&lt;/bvar&gt;
226             &lt;apply&gt;
227                 &lt;divide/&gt;
228                 &lt;apply&gt;
229                     &lt;plus/&gt;
230                     &lt;ci&gt; temp_in_fahrenheit &lt;/ci&gt;
231                     &lt;cn&gt; 459.67 &lt;/cn&gt;
232                 &lt;/apply&gt;
233                 &lt;cn&gt; 1.8 &lt;/cn&gt;
234             &lt;/apply&gt;
235         &lt;/lambda&gt;
236     &lt;/math&gt;
237 &lt;/functionDefinition&gt;
238 </pre>
239 <p>
240 * <li> An alternative approach not requiring the use of function definitions
241 *   is to use an {@link AssignmentRule} for each variable in Fahrenheit units.
242 *   The {@link AssignmentRule} could compute the conversion from Fahrenheit to
243 *   (say) kelvin, assign its value to a variable (in Kelvin units), and
244 *   then that variable could be used elsewhere in the model.
245 <p>
246 * <li> Still another approach is to rewrite the mathematical formulas of a
247 *   model to directly incorporate the conversion formula wherever the
248 *   original quantity appeared.
249 * </ul>
250 <p>
251 * Please consult the SBML specifications for more information about this
252 * and other issues involving units.
253 */
254
255public class UnitDefinition extends SBase {
256   private long swigCPtr;
257
258   protected UnitDefinition(long cPtr, boolean cMemoryOwn)
259   {
260     super(libsbmlJNI.UnitDefinition_SWIGUpcast(cPtr), cMemoryOwn);
261     swigCPtr = cPtr;
262   }
263
264   protected static long getCPtr(UnitDefinition obj)
265   {
266     return (obj == null) ? 0 : obj.swigCPtr;
267   }
268
269   protected static long getCPtrAndDisown (UnitDefinition obj)
270   {
271     long ptr = 0;
272
273     if (obj != null)
274     {
275       ptr             = obj.swigCPtr;
276       obj.swigCMemOwn = false;
277     }
278
279     return ptr;
280   }
281
282  protected void finalize() {
283    delete();
284  }
285
286  public synchronized void delete() {
287    if (swigCPtr != 0) {
288      if (swigCMemOwn) {
289        swigCMemOwn = false;
290        libsbmlJNI.delete_UnitDefinition(swigCPtr);
291      }
292      swigCPtr = 0;
293    }
294    super.delete();
295  }
296
297  
298/**
299   * Creates a new {@link UnitDefinition} using the given SBML <code>level</code> and <code>version</code>
300   * values.
301   <p>
302   * @param level a long integer, the SBML Level to assign to this {@link UnitDefinition}.
303   <p>
304   * @param version a long integer, the SBML Version to assign to this
305   * {@link UnitDefinition}.
306   <p>
307   * <p>
308 * @throws SBMLConstructorException
309 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid
310 * or if this object is incompatible with the given level and version.
311   <p>
312   * <p>
313 * @note Attempting to add an object to an {@link SBMLDocument} having a different
314 * combination of SBML Level, Version and XML namespaces than the object
315 * itself will result in an error at the time a caller attempts to make the
316 * addition.  A parent object must have compatible Level, Version and XML
317 * namespaces.  (Strictly speaking, a parent may also have more XML
318 * namespaces than a child, but the reverse is not permitted.)  The
319 * restriction is necessary to ensure that an SBML model has a consistent
320 * overall structure.  This requires callers to manage their objects
321 * carefully, but the benefit is increased flexibility in how models can be
322 * created by permitting callers to create objects bottom-up if desired.  In
323 * situations where objects are not yet attached to parents (e.g.,
324 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
325 * libSBML determine such things as whether it is valid to assign a
326 * particular value to an attribute.
327   */ public
328 UnitDefinition(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
329    this(libsbmlJNI.new_UnitDefinition__SWIG_0(level, version), true);
330  }
331
332  
333/**
334   * Creates a new {@link UnitDefinition} using the given {@link SBMLNamespaces} object
335   * <code>sbmlns</code>.
336   <p>
337   * <p>
338 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
339 * information.  It is used to communicate the SBML Level, Version, and (in
340 * Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.  A
341 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
342 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object
343 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 
344   <p>
345   * @param sbmlns an {@link SBMLNamespaces} object.
346   <p>
347   * <p>
348 * @throws SBMLConstructorException
349 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible
350 * with this object.
351   <p>
352   * <p>
353 * @note Attempting to add an object to an {@link SBMLDocument} having a different
354 * combination of SBML Level, Version and XML namespaces than the object
355 * itself will result in an error at the time a caller attempts to make the
356 * addition.  A parent object must have compatible Level, Version and XML
357 * namespaces.  (Strictly speaking, a parent may also have more XML
358 * namespaces than a child, but the reverse is not permitted.)  The
359 * restriction is necessary to ensure that an SBML model has a consistent
360 * overall structure.  This requires callers to manage their objects
361 * carefully, but the benefit is increased flexibility in how models can be
362 * created by permitting callers to create objects bottom-up if desired.  In
363 * situations where objects are not yet attached to parents (e.g.,
364 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
365 * libSBML determine such things as whether it is valid to assign a
366 * particular value to an attribute.
367   */ public
368 UnitDefinition(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
369    this(libsbmlJNI.new_UnitDefinition__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
370  }
371
372  
373/**
374   * Copy constructor; creates a copy of this {@link UnitDefinition}.
375   <p>
376   * @param orig the object to copy.
377   */ public
378 UnitDefinition(UnitDefinition orig) throws org.sbml.libsbml.SBMLConstructorException {
379    this(libsbmlJNI.new_UnitDefinition__SWIG_2(UnitDefinition.getCPtr(orig), orig), true);
380  }
381
382  
383/**
384   * Creates and returns a deep copy of this {@link UnitDefinition} object.
385   <p>
386   * @return the (deep) copy of this {@link UnitDefinition} object.
387   */ public
388 UnitDefinition cloneObject() {
389    long cPtr = libsbmlJNI.UnitDefinition_cloneObject(swigCPtr, this);
390    return (cPtr == 0) ? null : new UnitDefinition(cPtr, true);
391  }
392
393  
394/**
395   * Returns the first child element found that has the given <code>id</code> in the
396   * model-wide SId namespace, or <code>null</code> if no such object is found.
397   <p>
398   * @param id string representing the id of the object to find.
399   <p>
400   * @return pointer to the first element found with the given <code>id</code>.
401   */ public
402 SBase getElementBySId(String id) {
403  return libsbml.DowncastSBase(libsbmlJNI.UnitDefinition_getElementBySId(swigCPtr, this, id), false);
404}
405
406  
407/**
408   * Returns the first child element it can find with the given <code>metaid</code>, or
409   * <code>null</code> if no such object is found.
410   <p>
411   * @param metaid string representing the metaid of the object to find.
412   <p>
413   * @return pointer to the first element found with the given <code>metaid</code>.
414   */ public
415 SBase getElementByMetaId(String metaid) {
416  return libsbml.DowncastSBase(libsbmlJNI.UnitDefinition_getElementByMetaId(swigCPtr, this, metaid), false);
417}
418
419  
420/**
421   * Returns the value of the 'id' attribute of this {@link UnitDefinition}.
422   <p>
423   * @note Because of the inconsistent behavior of this function with 
424   * respect to assignments and rules, it is now recommended to
425   * use the getIdAttribute() function instead.
426   <p>
427   * <p>
428 * The identifier given by an object's 'id' attribute value
429 * is used to identify the object within the SBML model definition.
430 * Other objects can refer to the component using this identifier.  The
431 * data type of 'id' is always <code>SId</code> or a type derived
432 * from that, such as <code>UnitSId</code>, depending on the object in 
433 * question.  All data types are defined as follows:
434 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'>
435 *   letter .= 'a'..'z','A'..'Z'
436 *   digit  .= '0'..'9'
437 *   idChar .= letter | digit | '_'
438 *   SId    .= ( letter | '_' ) idChar*
439 * </pre>
440 <p>
441 * The characters <code>(</code> and <code>)</code> are used for grouping, the
442 * character <code>*</code> 'zero or more times', and the character
443 * <code>|</code> indicates logical 'or'.  The equality of SBML identifiers is
444 * determined by an exact character sequence match; i.e., comparisons must be
445 * performed in a case-sensitive manner.  This applies to all uses of <code>SId</code>, 
446 * <code>SIdRef</code>, and derived types.
447 <p>
448 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
449 * moved to {@link SBase} directly, instead of being defined individually for many
450 * (but not all) objects.  Libsbml has for a long time provided functions
451 * defined on {@link SBase} itself to get, set, check, and unset those attributes, which 
452 * would fail or otherwise return empty strings if executed on any object 
453 * for which those attributes were not defined.  Now that all {@link SBase} objects 
454 * define those attributes, those functions now succeed for any object with 
455 * the appropriate level and version.
456 <p>
457 * The exception to this rule is that for {@link InitialAssignment}, {@link EventAssignment}, 
458 * {@link AssignmentRule}, and {@link RateRule} objects, the getId() function and the isSetId() 
459 * functions (though not the setId() or unsetId() functions) would instead 
460 * reference the value of the 'variable' attribute (for the rules and event 
461 * assignments) or the 'symbol' attribute (for initial assignments).  
462 * The {@link AlgebraicRule} fell into this category as well, though because it 
463 * contained neither a 'variable' nor a 'symbol' attribute, getId() would 
464 * always return an empty string, and isSetId() would always return <code>false.</code>
465 * For this reason, four new functions are now provided 
466 * (getIdAttribute(), setIdAttribute(String), 
467 * isSetIdAttribute(), and unsetIdAttribute()) that will always
468 * act on the actual 'id' attribute, regardless of the object's type.  The
469 * new functions should be used instead of the old ones unless the old behavior
470 * is somehow necessary.
471 <p>
472 * Regardless of the level and version of the SBML, these functions allow
473 * client applications to use more generalized code in some situations 
474 * (for instance, when manipulating objects that are all known to have 
475 * identifiers).  If the object in question does not posess an 'id' attribute 
476 * according to the SBML specification for the Level and Version in use,
477 * libSBML will not allow the identifier to be set, nor will it read or 
478 * write 'id' attributes for those objects.
479   <p>
480   * @return the id of this {@link UnitDefinition}.
481   <p>
482   * @see #getIdAttribute()
483   * @see #setIdAttribute(String sid)
484   * @see #isSetIdAttribute()
485   * @see #unsetIdAttribute()
486   */ public
487 String getId() {
488    return libsbmlJNI.UnitDefinition_getId(swigCPtr, this);
489  }
490
491  
492/**
493   * Returns the value of the 'name' attribute of this {@link UnitDefinition} object.
494   <p>
495   * <p>
496 * <p>
497 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
498 * moved to {@link SBase} directly, instead of being defined individually for many
499 * (but not all) objects.  Libsbml has for a long time provided functions
500 * defined on {@link SBase} itself to get, set, and unset those attributes, which 
501 * would fail or otherwise return empty strings if executed on any object 
502 * for which those attributes were not defined.  Now that all {@link SBase} objects 
503 * define those attributes, those functions now succeed for any object with 
504 * the appropriate level and version.
505 <p>
506 * The 'name' attribute is
507 * optional and is not intended to be used for cross-referencing purposes
508 * within a model.  Its purpose instead is to provide a human-readable
509 * label for the component.  The data type of 'name' is the type
510 * <code>string</code> defined in XML Schema.  SBML imposes no
511 * restrictions as to the content of 'name' attributes beyond those
512 * restrictions defined by the <code>string</code> type in XML Schema.
513 <p>
514 * The recommended practice for handling 'name' is as follows.  If a
515 * software tool has the capability for displaying the content of 'name'
516 * attributes, it should display this content to the user as a
517 * component's label instead of the component's 'id'.  If the user
518 * interface does not have this capability (e.g., because it cannot
519 * display or use special characters in symbol names), or if the 'name'
520 * attribute is missing on a given component, then the user interface
521 * should display the value of the 'id' attribute instead.  (Script
522 * language interpreters are especially likely to display 'id' instead of
523 * 'name'.)
524 <p>
525 * As a consequence of the above, authors of systems that automatically
526 * generate the values of 'id' attributes should be aware some systems
527 * may display the 'id''s to the user.  Authors therefore may wish to
528 * take some care to have their software create 'id' values that are: (a)
529 * reasonably easy for humans to type and read; and (b) likely to be
530 * meaningful, for example by making the 'id' attribute be an abbreviated
531 * form of the name attribute value.
532 <p>
533 * An additional point worth mentioning is although there are
534 * restrictions on the uniqueness of 'id' values, there are no
535 * restrictions on the uniqueness of 'name' values in a model.  This
536 * allows software applications leeway in assigning component identifiers.
537 <p>
538 * Regardless of the level and version of the SBML, these functions allow
539 * client applications to use more generalized code in some situations 
540 * (for instance, when manipulating objects that are all known to have 
541 * names).  If the object in question does not posess a 'name' attribute 
542 * according to the SBML specification for the Level and Version in use,
543 * libSBML will not allow the name to be set, nor will it read or 
544 * write 'name' attributes for those objects.
545 <p>
546 * @return the name of this SBML object, or the empty string if not set or unsettable.
547 <p>
548 * @see #getIdAttribute()
549 * @see #isSetName()
550 * @see #setName(String sid)
551 * @see #unsetName()
552   */ public
553 String getName() {
554    return libsbmlJNI.UnitDefinition_getName(swigCPtr, this);
555  }
556
557  
558/**
559   * Predicate returning <code>true</code> if this
560   * {@link UnitDefinition}'s 'id' attribute is set.
561   <p>
562   * <p>
563 * @note Because of the inconsistent behavior of this function with 
564 * respect to assignments and rules, it is now recommended to
565 * use the isSetIdAttribute() function instead.
566 <p>
567 * <p>
568 * The identifier given by an object's 'id' attribute value
569 * is used to identify the object within the SBML model definition.
570 * Other objects can refer to the component using this identifier.  The
571 * data type of 'id' is always <code>SId</code> or a type derived
572 * from that, such as <code>UnitSId</code>, depending on the object in 
573 * question.  All data types are defined as follows:
574 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'>
575 *   letter .= 'a'..'z','A'..'Z'
576 *   digit  .= '0'..'9'
577 *   idChar .= letter | digit | '_'
578 *   SId    .= ( letter | '_' ) idChar*
579 * </pre>
580 <p>
581 * The characters <code>(</code> and <code>)</code> are used for grouping, the
582 * character <code>*</code> 'zero or more times', and the character
583 * <code>|</code> indicates logical 'or'.  The equality of SBML identifiers is
584 * determined by an exact character sequence match; i.e., comparisons must be
585 * performed in a case-sensitive manner.  This applies to all uses of <code>SId</code>, 
586 * <code>SIdRef</code>, and derived types.
587 <p>
588 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
589 * moved to {@link SBase} directly, instead of being defined individually for many
590 * (but not all) objects.  Libsbml has for a long time provided functions
591 * defined on {@link SBase} itself to get, set, check, and unset those attributes, which 
592 * would fail or otherwise return empty strings if executed on any object 
593 * for which those attributes were not defined.  Now that all {@link SBase} objects 
594 * define those attributes, those functions now succeed for any object with 
595 * the appropriate level and version.
596 <p>
597 * The exception to this rule is that for {@link InitialAssignment}, {@link EventAssignment}, 
598 * {@link AssignmentRule}, and {@link RateRule} objects, the getId() function and the isSetId() 
599 * functions (though not the setId() or unsetId() functions) would instead 
600 * reference the value of the 'variable' attribute (for the rules and event 
601 * assignments) or the 'symbol' attribute (for initial assignments).  
602 * The {@link AlgebraicRule} fell into this category as well, though because it 
603 * contained neither a 'variable' nor a 'symbol' attribute, getId() would 
604 * always return an empty string, and isSetId() would always return <code>false.</code>
605 * For this reason, four new functions are now provided 
606 * (getIdAttribute(), setIdAttribute(String), 
607 * isSetIdAttribute(), and unsetIdAttribute()) that will always
608 * act on the actual 'id' attribute, regardless of the object's type.  The
609 * new functions should be used instead of the old ones unless the old behavior
610 * is somehow necessary.
611 <p>
612 * Regardless of the level and version of the SBML, these functions allow
613 * client applications to use more generalized code in some situations 
614 * (for instance, when manipulating objects that are all known to have 
615 * identifiers).  If the object in question does not posess an 'id' attribute 
616 * according to the SBML specification for the Level and Version in use,
617 * libSBML will not allow the identifier to be set, nor will it read or 
618 * write 'id' attributes for those objects.
619 <p>
620 * @return <code>true</code> if the 'id' attribute of this SBML object is
621 * set, <code>false</code> otherwise.
622 <p>
623 * @see #getIdAttribute()
624 * @see #setIdAttribute(String sid)
625 * @see #unsetIdAttribute()
626 * @see #isSetIdAttribute()
627   */ public
628 boolean isSetId() {
629    return libsbmlJNI.UnitDefinition_isSetId(swigCPtr, this);
630  }
631
632  
633/**
634   * Predicate returning <code>true</code> if this
635   * {@link UnitDefinition}'s 'name' attribute is set.
636   <p>
637   * <p>
638 * <p>
639 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
640 * moved to {@link SBase} directly, instead of being defined individually for many
641 * (but not all) objects.  Libsbml has for a long time provided functions
642 * defined on {@link SBase} itself to get, set, and unset those attributes, which 
643 * would fail or otherwise return empty strings if executed on any object 
644 * for which those attributes were not defined.  Now that all {@link SBase} objects 
645 * define those attributes, those functions now succeed for any object with 
646 * the appropriate level and version.
647 <p>
648 * The 'name' attribute is
649 * optional and is not intended to be used for cross-referencing purposes
650 * within a model.  Its purpose instead is to provide a human-readable
651 * label for the component.  The data type of 'name' is the type
652 * <code>string</code> defined in XML Schema.  SBML imposes no
653 * restrictions as to the content of 'name' attributes beyond those
654 * restrictions defined by the <code>string</code> type in XML Schema.
655 <p>
656 * The recommended practice for handling 'name' is as follows.  If a
657 * software tool has the capability for displaying the content of 'name'
658 * attributes, it should display this content to the user as a
659 * component's label instead of the component's 'id'.  If the user
660 * interface does not have this capability (e.g., because it cannot
661 * display or use special characters in symbol names), or if the 'name'
662 * attribute is missing on a given component, then the user interface
663 * should display the value of the 'id' attribute instead.  (Script
664 * language interpreters are especially likely to display 'id' instead of
665 * 'name'.)
666 <p>
667 * As a consequence of the above, authors of systems that automatically
668 * generate the values of 'id' attributes should be aware some systems
669 * may display the 'id''s to the user.  Authors therefore may wish to
670 * take some care to have their software create 'id' values that are: (a)
671 * reasonably easy for humans to type and read; and (b) likely to be
672 * meaningful, for example by making the 'id' attribute be an abbreviated
673 * form of the name attribute value.
674 <p>
675 * An additional point worth mentioning is although there are
676 * restrictions on the uniqueness of 'id' values, there are no
677 * restrictions on the uniqueness of 'name' values in a model.  This
678 * allows software applications leeway in assigning component identifiers.
679 <p>
680 * Regardless of the level and version of the SBML, these functions allow
681 * client applications to use more generalized code in some situations 
682 * (for instance, when manipulating objects that are all known to have 
683 * names).  If the object in question does not posess a 'name' attribute 
684 * according to the SBML specification for the Level and Version in use,
685 * libSBML will not allow the name to be set, nor will it read or 
686 * write 'name' attributes for those objects.
687 <p>
688 * @return <code>true</code> if the 'name' attribute of this SBML object is
689 * set, <code>false</code> otherwise.
690 <p>
691 * @see #getName()
692 * @see #setName(String sid)
693 * @see #unsetName()
694   */ public
695 boolean isSetName() {
696    return libsbmlJNI.UnitDefinition_isSetName(swigCPtr, this);
697  }
698
699  
700/**
701   * Sets the value of the 'id' attribute of this {@link UnitDefinition}.
702   <p>
703   * <p>
704 * The string <code>sid</code> is copied.
705 <p>
706 * <p>
707 * The identifier given by an object's 'id' attribute value
708 * is used to identify the object within the SBML model definition.
709 * Other objects can refer to the component using this identifier.  The
710 * data type of 'id' is always <code>SId</code> or a type derived
711 * from that, such as <code>UnitSId</code>, depending on the object in 
712 * question.  All data types are defined as follows:
713 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'>
714 *   letter .= 'a'..'z','A'..'Z'
715 *   digit  .= '0'..'9'
716 *   idChar .= letter | digit | '_'
717 *   SId    .= ( letter | '_' ) idChar*
718 * </pre>
719 <p>
720 * The characters <code>(</code> and <code>)</code> are used for grouping, the
721 * character <code>*</code> 'zero or more times', and the character
722 * <code>|</code> indicates logical 'or'.  The equality of SBML identifiers is
723 * determined by an exact character sequence match; i.e., comparisons must be
724 * performed in a case-sensitive manner.  This applies to all uses of <code>SId</code>, 
725 * <code>SIdRef</code>, and derived types.
726 <p>
727 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
728 * moved to {@link SBase} directly, instead of being defined individually for many
729 * (but not all) objects.  Libsbml has for a long time provided functions
730 * defined on {@link SBase} itself to get, set, check, and unset those attributes, which 
731 * would fail or otherwise return empty strings if executed on any object 
732 * for which those attributes were not defined.  Now that all {@link SBase} objects 
733 * define those attributes, those functions now succeed for any object with 
734 * the appropriate level and version.
735 <p>
736 * The exception to this rule is that for {@link InitialAssignment}, {@link EventAssignment}, 
737 * {@link AssignmentRule}, and {@link RateRule} objects, the getId() function and the isSetId() 
738 * functions (though not the setId() or unsetId() functions) would instead 
739 * reference the value of the 'variable' attribute (for the rules and event 
740 * assignments) or the 'symbol' attribute (for initial assignments).  
741 * The {@link AlgebraicRule} fell into this category as well, though because it 
742 * contained neither a 'variable' nor a 'symbol' attribute, getId() would 
743 * always return an empty string, and isSetId() would always return <code>false.</code>
744 * For this reason, four new functions are now provided 
745 * (getIdAttribute(), setIdAttribute(String), 
746 * isSetIdAttribute(), and unsetIdAttribute()) that will always
747 * act on the actual 'id' attribute, regardless of the object's type.  The
748 * new functions should be used instead of the old ones unless the old behavior
749 * is somehow necessary.
750 <p>
751 * Regardless of the level and version of the SBML, these functions allow
752 * client applications to use more generalized code in some situations 
753 * (for instance, when manipulating objects that are all known to have 
754 * identifiers).  If the object in question does not posess an 'id' attribute 
755 * according to the SBML specification for the Level and Version in use,
756 * libSBML will not allow the identifier to be set, nor will it read or 
757 * write 'id' attributes for those objects.
758 <p>
759 * @param sid the string to use as the identifier of this object.
760 <p>
761 * <p>
762 * @return integer value indicating success/failure of the
763 * function.   The possible values
764 * returned by this function are:
765 * <ul>
766 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
767 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE}
768 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE}
769 *
770 * </ul> <p>
771 * @see #getIdAttribute()
772 * @see #setIdAttribute(String sid)
773 * @see #isSetIdAttribute()
774 * @see #unsetIdAttribute()
775   */ public
776 int setId(String sid) {
777    return libsbmlJNI.UnitDefinition_setId(swigCPtr, this, sid);
778  }
779
780  
781/**
782   * Sets the value of the 'name' attribute of this {@link UnitDefinition}.
783   <p>
784   * <p>
785 * The string in <code>name</code> is copied.
786 <p>
787 * @param name the new name for the SBML object.
788 <p>
789 * <p>
790 * @return integer value indicating success/failure of the
791 * function.   The possible values
792 * returned by this function are:
793 * <ul>
794 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
795 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE}
796 *
797 * </ul>
798   */ public
799 int setName(String name) {
800    return libsbmlJNI.UnitDefinition_setName(swigCPtr, this, name);
801  }
802
803  
804/**
805   * Unsets the value of the 'name' attribute of this {@link UnitDefinition}.
806   <p>
807   * <p>
808 * <p>
809 * In SBML Level&nbsp;3 Version&nbsp;2, the 'id' and 'name' attributes were
810 * moved to {@link SBase} directly, instead of being defined individually for many
811 * (but not all) objects.  Libsbml has for a long time provided functions
812 * defined on {@link SBase} itself to get, set, and unset those attributes, which 
813 * would fail or otherwise return empty strings if executed on any object 
814 * for which those attributes were not defined.  Now that all {@link SBase} objects 
815 * define those attributes, those functions now succeed for any object with 
816 * the appropriate level and version.
817 <p>
818 * The 'name' attribute is
819 * optional and is not intended to be used for cross-referencing purposes
820 * within a model.  Its purpose instead is to provide a human-readable
821 * label for the component.  The data type of 'name' is the type
822 * <code>string</code> defined in XML Schema.  SBML imposes no
823 * restrictions as to the content of 'name' attributes beyond those
824 * restrictions defined by the <code>string</code> type in XML Schema.
825 <p>
826 * The recommended practice for handling 'name' is as follows.  If a
827 * software tool has the capability for displaying the content of 'name'
828 * attributes, it should display this content to the user as a
829 * component's label instead of the component's 'id'.  If the user
830 * interface does not have this capability (e.g., because it cannot
831 * display or use special characters in symbol names), or if the 'name'
832 * attribute is missing on a given component, then the user interface
833 * should display the value of the 'id' attribute instead.  (Script
834 * language interpreters are especially likely to display 'id' instead of
835 * 'name'.)
836 <p>
837 * As a consequence of the above, authors of systems that automatically
838 * generate the values of 'id' attributes should be aware some systems
839 * may display the 'id''s to the user.  Authors therefore may wish to
840 * take some care to have their software create 'id' values that are: (a)
841 * reasonably easy for humans to type and read; and (b) likely to be
842 * meaningful, for example by making the 'id' attribute be an abbreviated
843 * form of the name attribute value.
844 <p>
845 * An additional point worth mentioning is although there are
846 * restrictions on the uniqueness of 'id' values, there are no
847 * restrictions on the uniqueness of 'name' values in a model.  This
848 * allows software applications leeway in assigning component identifiers.
849 <p>
850 * Regardless of the level and version of the SBML, these functions allow
851 * client applications to use more generalized code in some situations 
852 * (for instance, when manipulating objects that are all known to have 
853 * names).  If the object in question does not posess a 'name' attribute 
854 * according to the SBML specification for the Level and Version in use,
855 * libSBML will not allow the name to be set, nor will it read or 
856 * write 'name' attributes for those objects.
857 <p>
858 * <p>
859 * @return integer value indicating success/failure of the
860 * function.   The possible values
861 * returned by this function are:
862 * <ul>
863 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
864 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
865 *
866 * </ul> <p>
867 * @see #getName()
868 * @see #setName(String sid)
869 * @see #isSetName()
870   */ public
871 int unsetName() {
872    return libsbmlJNI.UnitDefinition_unsetName(swigCPtr, this);
873  }
874
875  
876/**
877   * Convenience function for testing if a given unit definition is a
878   * variant of the predefined unit identifier <code>'area'.</code>
879   <p>
880   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
881   * unit <code>area</code>, meaning square metres with only arbitrary variations
882   * in scale or multiplier values; <code>false</code> otherwise.
883   */ public
884 boolean isVariantOfArea(boolean relaxed) {
885    return libsbmlJNI.UnitDefinition_isVariantOfArea__SWIG_0(swigCPtr, this, relaxed);
886  }
887
888  
889/**
890   * Convenience function for testing if a given unit definition is a
891   * variant of the predefined unit identifier <code>'area'.</code>
892   <p>
893   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
894   * unit <code>area</code>, meaning square metres with only arbitrary variations
895   * in scale or multiplier values; <code>false</code> otherwise.
896   */ public
897 boolean isVariantOfArea() {
898    return libsbmlJNI.UnitDefinition_isVariantOfArea__SWIG_1(swigCPtr, this);
899  }
900
901  
902/**
903   * Convenience function for testing if a given unit definition is a
904   * variant of the predefined unit identifier <code>'length'.</code>
905   <p>
906   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
907   * unit <code>length</code>, meaning metres with only arbitrary variations in scale
908   * or multiplier values; <code>false</code> otherwise.
909   */ public
910 boolean isVariantOfLength(boolean relaxed) {
911    return libsbmlJNI.UnitDefinition_isVariantOfLength__SWIG_0(swigCPtr, this, relaxed);
912  }
913
914  
915/**
916   * Convenience function for testing if a given unit definition is a
917   * variant of the predefined unit identifier <code>'length'.</code>
918   <p>
919   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
920   * unit <code>length</code>, meaning metres with only arbitrary variations in scale
921   * or multiplier values; <code>false</code> otherwise.
922   */ public
923 boolean isVariantOfLength() {
924    return libsbmlJNI.UnitDefinition_isVariantOfLength__SWIG_1(swigCPtr, this);
925  }
926
927  
928/**
929   * Convenience function for testing if a given unit definition is a
930   * variant of the predefined unit identifier <code>'substance'.</code>
931   <p>
932   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
933   * unit <code>substance</code>, meaning moles or items (and grams or kilograms from
934   * SBML Level&nbsp;2 Version&nbsp;2 onwards) with only arbitrary variations
935   * in scale or multiplier values; <code>false</code> otherwise.
936   */ public
937 boolean isVariantOfSubstance(boolean relaxed) {
938    return libsbmlJNI.UnitDefinition_isVariantOfSubstance__SWIG_0(swigCPtr, this, relaxed);
939  }
940
941  
942/**
943   * Convenience function for testing if a given unit definition is a
944   * variant of the predefined unit identifier <code>'substance'.</code>
945   <p>
946   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
947   * unit <code>substance</code>, meaning moles or items (and grams or kilograms from
948   * SBML Level&nbsp;2 Version&nbsp;2 onwards) with only arbitrary variations
949   * in scale or multiplier values; <code>false</code> otherwise.
950   */ public
951 boolean isVariantOfSubstance() {
952    return libsbmlJNI.UnitDefinition_isVariantOfSubstance__SWIG_1(swigCPtr, this);
953  }
954
955  
956/**
957   * Convenience function for testing if a given unit definition is a
958   * variant of the predefined unit identifier <code>'time'.</code>
959   <p>
960   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
961   * unit <code>time</code>, meaning seconds with only arbitrary variations in scale or
962   * multiplier values; <code>false</code> otherwise.
963   */ public
964 boolean isVariantOfTime(boolean relaxed) {
965    return libsbmlJNI.UnitDefinition_isVariantOfTime__SWIG_0(swigCPtr, this, relaxed);
966  }
967
968  
969/**
970   * Convenience function for testing if a given unit definition is a
971   * variant of the predefined unit identifier <code>'time'.</code>
972   <p>
973   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
974   * unit <code>time</code>, meaning seconds with only arbitrary variations in scale or
975   * multiplier values; <code>false</code> otherwise.
976   */ public
977 boolean isVariantOfTime() {
978    return libsbmlJNI.UnitDefinition_isVariantOfTime__SWIG_1(swigCPtr, this);
979  }
980
981  
982/**
983   * Convenience function for testing if a given unit definition is a
984   * variant of the predefined unit identifier <code>'volume'.</code>
985   <p>
986   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
987   * unit <code>volume</code>, meaning litre or cubic metre with only arbitrary
988   * variations in scale or multiplier values; <code>false</code> otherwise.
989   */ public
990 boolean isVariantOfVolume(boolean relaxed) {
991    return libsbmlJNI.UnitDefinition_isVariantOfVolume__SWIG_0(swigCPtr, this, relaxed);
992  }
993
994  
995/**
996   * Convenience function for testing if a given unit definition is a
997   * variant of the predefined unit identifier <code>'volume'.</code>
998   <p>
999   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
1000   * unit <code>volume</code>, meaning litre or cubic metre with only arbitrary
1001   * variations in scale or multiplier values; <code>false</code> otherwise.
1002   */ public
1003 boolean isVariantOfVolume() {
1004    return libsbmlJNI.UnitDefinition_isVariantOfVolume__SWIG_1(swigCPtr, this);
1005  }
1006
1007  
1008/**
1009   * Convenience function for testing if a given unit definition is a
1010   * variant of the unit <code>'dimensionless'.</code>
1011   <p>
1012   * @return <code>true</code> if this {@link UnitDefinition} is a variant of
1013   * <code>dimensionless</code>, meaning dimensionless with only arbitrary variations in
1014   * scale or multiplier values; <code>false</code> otherwise.
1015   */ public
1016 boolean isVariantOfDimensionless(boolean relaxed) {
1017    return libsbmlJNI.UnitDefinition_isVariantOfDimensionless__SWIG_0(swigCPtr, this, relaxed);
1018  }
1019
1020  
1021/**
1022   * Convenience function for testing if a given unit definition is a
1023   * variant of the unit <code>'dimensionless'.</code>
1024   <p>
1025   * @return <code>true</code> if this {@link UnitDefinition} is a variant of
1026   * <code>dimensionless</code>, meaning dimensionless with only arbitrary variations in
1027   * scale or multiplier values; <code>false</code> otherwise.
1028   */ public
1029 boolean isVariantOfDimensionless() {
1030    return libsbmlJNI.UnitDefinition_isVariantOfDimensionless__SWIG_1(swigCPtr, this);
1031  }
1032
1033  
1034/**
1035   * Convenience function for testing if a given unit definition is a
1036   * variant of the predefined unit identifier <code>'mass'.</code>
1037   <p>
1038   * @return <code>true</code> if this {@link UnitDefinition} is a variant of mass units,
1039   * meaning gram or kilogram with only arbitrary variations in scale or
1040   * multiplier values; <code>false</code> otherwise.
1041   */ public
1042 boolean isVariantOfMass(boolean relaxed) {
1043    return libsbmlJNI.UnitDefinition_isVariantOfMass__SWIG_0(swigCPtr, this, relaxed);
1044  }
1045
1046  
1047/**
1048   * Convenience function for testing if a given unit definition is a
1049   * variant of the predefined unit identifier <code>'mass'.</code>
1050   <p>
1051   * @return <code>true</code> if this {@link UnitDefinition} is a variant of mass units,
1052   * meaning gram or kilogram with only arbitrary variations in scale or
1053   * multiplier values; <code>false</code> otherwise.
1054   */ public
1055 boolean isVariantOfMass() {
1056    return libsbmlJNI.UnitDefinition_isVariantOfMass__SWIG_1(swigCPtr, this);
1057  }
1058
1059  
1060/**
1061   * Convenience function for testing if a given unit definition is a
1062   * variant of the predefined unit <code>'substance'</code> divided by the predefined
1063   * unit <code>'time'.</code>
1064   <p>
1065   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
1066   * unit <code>substance</code> per predefined unit <code>time</code>, meaning it contains two
1067   * units one of which is a variant of substance and the other is a
1068   * variant of time which an exponent of -1; <code>false</code> otherwise.
1069   */ public
1070 boolean isVariantOfSubstancePerTime(boolean relaxed) {
1071    return libsbmlJNI.UnitDefinition_isVariantOfSubstancePerTime__SWIG_0(swigCPtr, this, relaxed);
1072  }
1073
1074  
1075/**
1076   * Convenience function for testing if a given unit definition is a
1077   * variant of the predefined unit <code>'substance'</code> divided by the predefined
1078   * unit <code>'time'.</code>
1079   <p>
1080   * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined
1081   * unit <code>substance</code> per predefined unit <code>time</code>, meaning it contains two
1082   * units one of which is a variant of substance and the other is a
1083   * variant of time which an exponent of -1; <code>false</code> otherwise.
1084   */ public
1085 boolean isVariantOfSubstancePerTime() {
1086    return libsbmlJNI.UnitDefinition_isVariantOfSubstancePerTime__SWIG_1(swigCPtr, this);
1087  }
1088
1089  
1090/**
1091   * Adds a copy of the given {@link Unit} to this {@link UnitDefinition}.
1092   <p>
1093   * @param u the {@link Unit} instance to add to this {@link UnitDefinition}.
1094   <p>
1095   * <p>
1096 * @return integer value indicating success/failure of the
1097 * function.   The possible values
1098 * returned by this function are:
1099   * <ul>
1100   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS}
1101   * <li> {@link libsbmlConstants#LIBSBML_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH}
1102   * <li> {@link libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH}
1103   * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT}
1104   * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED}
1105   *
1106   * </ul> <p>
1107   * <p>
1108 * @note This method should be used with some caution.  The fact that this
1109 * method <em>copies</em> the object passed to it means that the caller will be
1110 * left holding a physically different object instance than the one contained
1111 * inside this object.  Changes made to the original object instance (such as
1112 * resetting attribute values) will <em>not affect the instance in this
1113 * object</em>.  In addition, the caller should make sure to free the
1114 * original object if it is no longer being used, or else a memory leak will
1115 * result.  Please see other methods on this class (particularly a
1116 * corresponding method whose name begins with the word <code>create</code>)
1117 * for alternatives that do not lead to these issues. 
1118   <p>
1119   * @see #createUnit()
1120   */ public
1121 int addUnit(Unit u) {
1122    return libsbmlJNI.UnitDefinition_addUnit(swigCPtr, this, Unit.getCPtr(u), u);
1123  }
1124
1125  
1126/**
1127   * Creates a new and empty {@link Unit}, adds it to this {@link UnitDefinition}'s list of
1128   * units, and returns it.
1129   <p>
1130   * @return a newly constructed (and empty) {@link Unit} instance.
1131   <p>
1132   * @note It is worth emphasizing that the attribute 'kind' value of a
1133   * {@link Unit} is a required attribute for a valid {@link Unit} definition.  The
1134   * createUnit() method does not assign a valid kind to the constructed
1135   * unit (instead, it sets the 'kind' to {@link libsbmlConstants#UNIT_KIND_INVALID UNIT_KIND_INVALID}).
1136   * Callers are cautioned to set the newly-constructed {@link Unit}'s kind using
1137   * {@link Unit#setKind(int)} soon after calling this method.
1138   <p>
1139   * @see #addUnit(Unit u)
1140   */ public
1141 Unit createUnit() {
1142    long cPtr = libsbmlJNI.UnitDefinition_createUnit(swigCPtr, this);
1143    return (cPtr == 0) ? null : new Unit(cPtr, false);
1144  }
1145
1146  
1147/**
1148   * Returns the list of Units for this {@link UnitDefinition} instance.
1149   * @return the {@link ListOfUnits} value for this {@link UnitDefinition}.
1150   */ public
1151 ListOfUnits getListOfUnits() {
1152    long cPtr = libsbmlJNI.UnitDefinition_getListOfUnits__SWIG_0(swigCPtr, this);
1153    return (cPtr == 0) ? null : new ListOfUnits(cPtr, false);
1154  }
1155
1156  
1157/**
1158   * Returns a specific {@link Unit} instance belonging to this {@link UnitDefinition}.
1159   <p>
1160   * @param n an integer, the index of the {@link Unit} to be returned.
1161   <p>
1162   * @return the nth {@link Unit} of this {@link UnitDefinition}.
1163   <p>
1164   * @see #getNumUnits()
1165   */ public
1166 Unit getUnit(long n) {
1167    long cPtr = libsbmlJNI.UnitDefinition_getUnit__SWIG_0(swigCPtr, this, n);
1168    return (cPtr == 0) ? null : new Unit(cPtr, false);
1169  }
1170
1171  
1172/**
1173   * Returns the number of {@link Unit} objects contained within this
1174   * {@link UnitDefinition}.
1175   <p>
1176   * @return an integer representing the number of Units in this
1177   * {@link UnitDefinition}.
1178   */ public
1179 long getNumUnits() {
1180    return libsbmlJNI.UnitDefinition_getNumUnits(swigCPtr, this);
1181  }
1182
1183  
1184/**
1185   * Removes the nth {@link Unit} object from this {@link UnitDefinition} object and
1186   * returns a pointer to it.
1187   <p>
1188   * The caller owns the returned object and is responsible for deleting it.
1189   <p>
1190   * @param n the index of the {@link Unit} object to remove.
1191   <p>
1192   * @return the {@link Unit} object removed, or <code>null</code> if the given index 
1193   * is out of range.
1194   */ public
1195 Unit removeUnit(long n) {
1196    long cPtr = libsbmlJNI.UnitDefinition_removeUnit(swigCPtr, this, n);
1197    return (cPtr == 0) ? null : new Unit(cPtr, true);
1198  }
1199
1200  public void connectToChild() {
1201    libsbmlJNI.UnitDefinition_connectToChild(swigCPtr, this);
1202  }
1203
1204  
1205/** * @internal */ public
1206 void enablePackageInternal(String pkgURI, String pkgPrefix, boolean flag) {
1207    libsbmlJNI.UnitDefinition_enablePackageInternal(swigCPtr, this, pkgURI, pkgPrefix, flag);
1208  }
1209
1210  
1211/**
1212   * Returns the libSBML type code for this object instance.
1213   <p>
1214   * <p>
1215 * LibSBML attaches an identifying code to every kind of SBML object.  These
1216 * are integer constants known as <em>SBML type codes</em>.  The names of all
1217 * the codes begin with the characters <code>SBML_</code>.
1218 * In the Java language interface for libSBML, the
1219 * type codes are defined as static integer constants in the interface class
1220 * {@link libsbmlConstants}.    Note that different Level&nbsp;3
1221 * package plug-ins may use overlapping type codes; to identify the package
1222 * to which a given object belongs, call the 
1223 * <code>{@link SBase#getPackageName()}
1224 * </code>
1225 * method on the object.
1226   <p>
1227   * @return the SBML type code for this object:
1228   * {@link libsbmlConstants#SBML_UNIT_DEFINITION SBML_UNIT_DEFINITION} (default).
1229   <p>
1230   * <p>
1231 * @warning <span class='warning'>The specific integer values of the possible
1232 * type codes may be reused by different libSBML plug-ins for SBML Level&nbsp;3.
1233 * packages,  To fully identify the correct code, <strong>it is necessary to
1234 * invoke both getTypeCode() and getPackageName()</strong>.</span>
1235   <p>
1236   * @see #getPackageName()
1237   * @see #getElementName()
1238   */ public
1239 int getTypeCode() {
1240    return libsbmlJNI.UnitDefinition_getTypeCode(swigCPtr, this);
1241  }
1242
1243  
1244/**
1245   * Returns the XML element name of this object, which for {@link UnitDefinition},
1246   * is always <code>'unitDefinition'.</code>
1247   <p>
1248   * @return the name of this element, i.e., <code>'unitDefinition'.</code>
1249   */ public
1250 String getElementName() {
1251    return libsbmlJNI.UnitDefinition_getElementName(swigCPtr, this);
1252  }
1253
1254  
1255/**
1256   * Simplifies the {@link UnitDefinition} such that any given kind of {@link Unit} object
1257   * occurs only once in the {@link ListOfUnits}.
1258   <p>
1259   * For example, the following definition,
1260   * <pre class='fragment'>
1261 &lt;unitDefinition&gt;
1262  &lt;listOfUnits&gt;
1263    &lt;unit kind='metre' exponent='1'/&gt;
1264    &lt;unit kind='metre' exponent='2'/&gt;
1265  &lt;/listOfUnits&gt;
1266 &lt;unitDefinition&gt;
1267 </pre>
1268   * will be simplified to 
1269   * <pre class='fragment'>
1270 &lt;unitDefinition&gt;
1271   &lt;listOfUnits&gt;
1272     &lt;unit kind='metre' exponent='3'/&gt;
1273   &lt;/listOfUnits&gt;
1274 &lt;unitDefinition&gt;
1275 </pre>
1276   <p>
1277   * @param ud the {@link UnitDefinition} object to be simplified.
1278   <p>
1279   * 
1280   */ public
1281 static void simplify(UnitDefinition ud) {
1282    libsbmlJNI.UnitDefinition_simplify(UnitDefinition.getCPtr(ud), ud);
1283  }
1284
1285  
1286/**
1287   * Alphabetically orders the {@link Unit} objects within the {@link ListOfUnits} of a
1288   * {@link UnitDefinition}.
1289   <p>
1290   * @param ud the {@link UnitDefinition} object whose units are to be reordered.
1291   <p>
1292   * 
1293   */ public
1294 static void reorder(UnitDefinition ud) {
1295    libsbmlJNI.UnitDefinition_reorder(UnitDefinition.getCPtr(ud), ud);
1296  }
1297
1298  
1299/**
1300   * Convert a given {@link UnitDefinition} into a new {@link UnitDefinition} object
1301   * that uses SI units.
1302   <p>
1303   * @param ud the {@link UnitDefinition} object to convert to SI.
1304   <p>
1305   * @return a new {@link UnitDefinition} object representing the results of the
1306   * conversion.
1307   <p>
1308   * 
1309   */ public
1310 static UnitDefinition convertToSI(UnitDefinition ud) {
1311    long cPtr = libsbmlJNI.UnitDefinition_convertToSI(UnitDefinition.getCPtr(ud), ud);
1312    return (cPtr == 0) ? null : new UnitDefinition(cPtr, true);
1313  }
1314
1315  
1316/**
1317   * Predicate returning <code>true</code> if two
1318   * {@link UnitDefinition} objects are identical.
1319   <p>
1320   * For the purposes of performing this comparison, two {@link UnitDefinition}
1321   * objects are considered identical when they contain identical lists of
1322   * {@link Unit} objects.  Pairs of {@link Unit} objects in the lists are in turn
1323   * considered identical if they satisfy the predicate
1324   * {@link Unit#areIdentical(Unit, Unit)}.
1325   * The predicate compares every attribute of the
1326   * {@link Unit} objects.
1327   <p>
1328   * @param ud1 the first {@link UnitDefinition} object to compare.
1329   * @param ud2 the second {@link UnitDefinition} object to compare.
1330   <p>
1331   * @return <code>true</code> if all the {@link Unit} objects in <code>ud1</code> are identical to the
1332   * {@link Unit} objects of <code>ud2</code>, <code>false</code> otherwise.
1333   <p>
1334   * 
1335   <p>
1336   * @see UnitDefinition#areEquivalent(UnitDefinition  ud1, UnitDefinition  ud2)
1337   * @see Unit#areIdentical(Unit  unit1, Unit  unit2)
1338   */ public
1339 static boolean areIdentical(UnitDefinition ud1, UnitDefinition ud2) {
1340    return libsbmlJNI.UnitDefinition_areIdentical(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2);
1341  }
1342
1343  
1344/**
1345   * Predicate returning <code>true</code> if two
1346   * {@link UnitDefinition} objects are equivalent.
1347   <p>
1348   * For the purposes of performing this comparison, two {@link UnitDefinition}
1349   * objects are considered equivalent when they contain <em>equivalent</em>
1350   * list of {@link Unit} objects.  {@link Unit} objects are in turn considered equivalent
1351   * if they satisfy the predicate
1352   * {@link Unit#areEquivalent(Unit, Unit)}.
1353   * The predicate tests a subset of the objects's attributes.
1354   <p>
1355   * @param ud1 the first {@link UnitDefinition} object to compare.
1356   <p>
1357   * @param ud2 the second {@link UnitDefinition} object to compare.
1358   <p>
1359   * @return <code>true</code> if all the {@link Unit} objects in <code>ud1</code> are equivalent
1360   * to the {@link Unit} objects in <code>ud2</code>, <code>false</code> otherwise.
1361   <p>
1362   * 
1363   <p>
1364   * @see UnitDefinition#areIdentical(UnitDefinition  ud1, UnitDefinition  ud2)
1365   * @see Unit#areEquivalent(Unit  unit1, Unit  unit2)
1366   */ public
1367 static boolean areEquivalent(UnitDefinition ud1, UnitDefinition ud2) {
1368    return libsbmlJNI.UnitDefinition_areEquivalent(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2);
1369  }
1370
1371  
1372/**
1373   * Combines two {@link UnitDefinition} objects into a single {@link UnitDefinition}.
1374   <p>
1375   * This takes {@link UnitDefinition} objects <code>ud1</code> and <code>ud2</code>, and creates a
1376   * {@link UnitDefinition} object that expresses the product of the units of 
1377   * <code>ud1</code> and <code>ud2</code>.
1378   <p>
1379   * @param ud1 the first {@link UnitDefinition} object.
1380   * @param ud2 the second {@link UnitDefinition} object.
1381   <p>
1382   * @return a {@link UnitDefinition} which represents the product of the 
1383   * units of the two argument UnitDefinitions.
1384   <p>
1385   * 
1386   */ public
1387 static UnitDefinition combine(UnitDefinition ud1, UnitDefinition ud2) {
1388    long cPtr = libsbmlJNI.UnitDefinition_combine(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2);
1389    return (cPtr == 0) ? null : new UnitDefinition(cPtr, true);
1390  }
1391
1392  
1393/**
1394   * Combines two {@link UnitDefinition} objects into a single {@link UnitDefinition} as
1395   * a division.
1396   <p>
1397   * This takes {@link UnitDefinition} objects <code>ud1</code> and <code>ud2</code>, and creates a
1398   * {@link UnitDefinition} object that expresses the division of the units of 
1399   * <code>ud1</code> and <code>ud2</code>.
1400   <p>
1401   * @param ud1 the first {@link UnitDefinition} object.
1402   * @param ud2 the second {@link UnitDefinition} object.
1403   <p>
1404   * @return a {@link UnitDefinition} which represents the division of the 
1405   * units of the two argument UnitDefinitions.
1406   <p>
1407   * 
1408   */ public
1409 static UnitDefinition divide(UnitDefinition ud1, UnitDefinition ud2) {
1410    long cPtr = libsbmlJNI.UnitDefinition_divide(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2);
1411    return (cPtr == 0) ? null : new UnitDefinition(cPtr, false);
1412  }
1413
1414  
1415/**
1416   * Expresses the given definition in a plain-text form.
1417   <p>
1418   * For example,
1419   * {@link UnitDefinition#printUnits(UnitDefinition)}
1420   * applied to
1421   * <pre class='fragment'>
1422 &lt;unitDefinition&gt;
1423  &lt;listOfUnits&gt;
1424    &lt;unit kind='metre' exponent='1'/&gt;
1425    &lt;unit kind='second' exponent='-2'/&gt;
1426  &lt;/listOfUnits&gt;
1427 &lt;unitDefinition&gt;
1428 </pre>
1429   * will return the string <code>'metre (exponent = 1, multiplier = 1,
1430   * scale = 0) second (exponent = -2, multiplier = 1, scale = 0)'</code>
1431   * or, if the optional parameter <code>compact</code> is given the value <code>true</code>,
1432   * the string <code>'(1 metre)^1 (1 second)^-2'</code>.  This method may
1433   * be useful for printing unit information to human users, or in
1434   * debugging software, or other situations.
1435   <p>
1436   * @param ud the {@link UnitDefinition} object.
1437   * @param compact boolean indicating whether the compact form
1438   * should be used (defaults to false).
1439   <p>
1440   * @return a string expressing the unit definition defined by the given
1441   * {@link UnitDefinition} object <code>ud</code>.
1442   <p>
1443   * 
1444   */ public
1445 static String printUnits(UnitDefinition ud, boolean compact) {
1446    return libsbmlJNI.UnitDefinition_printUnits__SWIG_0(UnitDefinition.getCPtr(ud), ud, compact);
1447  }
1448
1449  
1450/**
1451   * Expresses the given definition in a plain-text form.
1452   <p>
1453   * For example,
1454   * {@link UnitDefinition#printUnits(UnitDefinition)}
1455   * applied to
1456   * <pre class='fragment'>
1457 &lt;unitDefinition&gt;
1458  &lt;listOfUnits&gt;
1459    &lt;unit kind='metre' exponent='1'/&gt;
1460    &lt;unit kind='second' exponent='-2'/&gt;
1461  &lt;/listOfUnits&gt;
1462 &lt;unitDefinition&gt;
1463 </pre>
1464   * will return the string <code>'metre (exponent = 1, multiplier = 1,
1465   * scale = 0) second (exponent = -2, multiplier = 1, scale = 0)'</code>
1466   * or, if the optional parameter <code>compact</code> is given the value <code>true</code>,
1467   * the string <code>'(1 metre)^1 (1 second)^-2'</code>.  This method may
1468   * be useful for printing unit information to human users, or in
1469   * debugging software, or other situations.
1470   <p>
1471   * @param ud the {@link UnitDefinition} object.
1472   * @param compact boolean indicating whether the compact form
1473   * should be used (defaults to false).
1474   <p>
1475   * @return a string expressing the unit definition defined by the given
1476   * {@link UnitDefinition} object <code>ud</code>.
1477   <p>
1478   * 
1479   */ public
1480 static String printUnits(UnitDefinition ud) {
1481    return libsbmlJNI.UnitDefinition_printUnits__SWIG_1(UnitDefinition.getCPtr(ud), ud);
1482  }
1483
1484  
1485/**
1486   * Predicate returning <code>true</code> if
1487   * all the required attributes for this {@link UnitDefinition} object
1488   * have been set.
1489   <p>
1490   * The required attributes for a {@link UnitDefinition} object are:
1491   * <ul>
1492   * <li> 'id'
1493   *
1494   * </ul> <p>
1495   * @return <code>true</code> if the required attributes have been set, <code>false</code>
1496   * otherwise.
1497   */ public
1498 boolean hasRequiredAttributes() {
1499    return libsbmlJNI.UnitDefinition_hasRequiredAttributes(swigCPtr, this);
1500  }
1501
1502  
1503/**
1504   * Predicate returning <code>true</code> if
1505   * all the required elements for this {@link UnitDefinition} object
1506   * have been set.
1507   <p>
1508   * @note The required elements for a {@link Constraint} object are:
1509   * <ul>
1510   * <li> 'listOfUnits' (required in SBML Level&nbsp;2 only, optional in Level&nbsp;3)
1511   *
1512   * </ul> <p>
1513   * @return a boolean value indicating whether all the required
1514   * elements for this object have been defined.
1515   */ public
1516 boolean hasRequiredElements() {
1517    return libsbmlJNI.UnitDefinition_hasRequiredElements(swigCPtr, this);
1518  }
1519
1520}