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> –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> –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 2 and SBML Level 3 Version 1, if the {@link ListOfUnits} 067 * was present, it must have one or more {@link Unit} definitions. In SBML 068 * Level 3 Version 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 <listOfUnitDefinitions> 079 <unitDefinition id='mmls'> 080 <listOfUnits> 081 <unit kind='mole' scale='-3'/> 082 <unit kind='litre' exponent='-1'/> 083 <unit kind='second' exponent='-1'/> 084 </listOfUnits> 085 </unitDefinition> 086 </listOfUnitDefinitions> 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 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 2 Version 4, the exception being that Level 2 does 126 * not define <code>avogadro.</code> SBML Level 2 Version 1 (and <em>only</em> 127 * this Level+Version combination) provides an additional predefined unit 128 * name, <code>Celsius</code>, not available in Level 3. Finally, SBML 129 * Level 1 Versions 2–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 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 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 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 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 2 Version 2, {@link Unit} no longer has the 184 * attribute called 'offset' introduced in SBML Level 2 185 * Version 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 2 Version 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 2 Version 2, Version 3 and Version 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 <functionDefinition id='Fahrenheit_to_kelvin'> 223 <math xmlns='http://www.w3.org/1998/Math/MathML'> 224 <lambda> 225 <bvar><ci> temp_in_fahrenheit </ci></bvar> 226 <apply> 227 <divide/> 228 <apply> 229 <plus/> 230 <ci> temp_in_fahrenheit </ci> 231 <cn> 459.67 </cn> 232 </apply> 233 <cn> 1.8 </cn> 234 </apply> 235 </lambda> 236 </math> 237 </functionDefinition> 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 3) packages used in addition to SBML Level 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 3 Version 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 3 Version 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 3 Version 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 3 Version 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 3 Version 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 3 Version 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 2 Version 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 2 Version 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 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 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 <unitDefinition> 1262 <listOfUnits> 1263 <unit kind='metre' exponent='1'/> 1264 <unit kind='metre' exponent='2'/> 1265 </listOfUnits> 1266 <unitDefinition> 1267 </pre> 1268 * will be simplified to 1269 * <pre class='fragment'> 1270 <unitDefinition> 1271 <listOfUnits> 1272 <unit kind='metre' exponent='3'/> 1273 </listOfUnits> 1274 <unitDefinition> 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 <unitDefinition> 1423 <listOfUnits> 1424 <unit kind='metre' exponent='1'/> 1425 <unit kind='second' exponent='-2'/> 1426 </listOfUnits> 1427 <unitDefinition> 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 <unitDefinition> 1458 <listOfUnits> 1459 <unit kind='metre' exponent='1'/> 1460 <unit kind='second' exponent='-2'/> 1461 </listOfUnits> 1462 <unitDefinition> 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 2 only, optional in Level 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}