1 /** 2 * @file Parameter.h 3 * @brief Definitions of Parameter and ListOfParameters. 4 * @author Ben Bornstein 5 * 6 * <!-------------------------------------------------------------------------- 7 * This file is part of libSBML. Please visit http://sbml.org for more 8 * information about SBML, and the latest version of libSBML. 9 * 10 * Copyright (C) 2020 jointly by the following organizations: 11 * 1. California Institute of Technology, Pasadena, CA, USA 12 * 2. University of Heidelberg, Heidelberg, Germany 13 * 3. University College London, London, UK 14 * 15 * Copyright (C) 2019 jointly by the following organizations: 16 * 1. California Institute of Technology, Pasadena, CA, USA 17 * 2. University of Heidelberg, Heidelberg, Germany 18 * 19 * Copyright (C) 2013-2018 jointly by the following organizations: 20 * 1. California Institute of Technology, Pasadena, CA, USA 21 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 22 * 3. University of Heidelberg, Heidelberg, Germany 23 * 24 * Copyright (C) 2009-2013 jointly by the following organizations: 25 * 1. California Institute of Technology, Pasadena, CA, USA 26 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 27 * 28 * Copyright (C) 2006-2008 by the California Institute of Technology, 29 * Pasadena, CA, USA 30 * 31 * Copyright (C) 2002-2005 jointly by the following organizations: 32 * 1. California Institute of Technology, Pasadena, CA, USA 33 * 2. Japan Science and Technology Agency, Japan 34 * 35 * This library is free software; you can redistribute it and/or modify it 36 * under the terms of the GNU Lesser General Public License as published by 37 * the Free Software Foundation. A copy of the license agreement is provided 38 * in the file named "LICENSE.txt" included with this software distribution and 39 * also available online as http://sbml.org/software/libsbml/license.html 40 * ------------------------------------------------------------------------ --> 41 * 42 * @class Parameter. 43 * @sbmlbrief{core} An SBML parameter: a named symbol with a value. 44 * 45 * A Parameter is used in SBML to define a symbol associated with a value; 46 * this symbol can then be used in mathematical formulas in a model. By 47 * default, parameters have constant value for the duration of a 48 * simulation, and for this reason are called @em parameters instead of @em 49 * variables in SBML, although it is crucial to understand that <em>SBML 50 * parameters represent both concepts</em>. Whether a given SBML 51 * parameter is intended to be constant or variable is indicated by the 52 * value of its "constant" attribute. 53 * 54 * SBML's Parameter has a required attribute, "id", that gives the 55 * parameter a unique identifier by which other parts of an SBML model 56 * definition can refer to it. A parameter can also have an optional 57 * "name" attribute of type @c string. Identifiers and names must be used 58 * according to the guidelines described in the SBML specifications. 59 * 60 * The optional attribute "value" determines the value (of type @c double) 61 * assigned to the parameter. A missing value for "value" implies that 62 * the value either is unknown, or to be obtained from an external source, 63 * or determined by an initial assignment. The unit of measurement 64 * associated with the value of the parameter can be specified using the 65 * optional attribute "units". Here we only mention briefly some notable 66 * points about the possible unit choices, but readers are urged to consult 67 * the SBML specification documents for more information: 68 * <ul> 69 * 70 * <li> In SBML Level 3, there are no constraints on the units that 71 * can be assigned to parameters in a model; there are also no units to 72 * inherit from the enclosing Model object (unlike the case for, e.g., 73 * Species and Compartment). 74 * 75 * <li> In SBML Level 2, the value assigned to the parameter's "units" 76 * attribute must be chosen from one of the following possibilities: one of 77 * the base unit identifiers defined in SBML; one of the built-in unit 78 * identifiers @c "substance", @c "time", @c "volume", @c "area" or 79 * @c "length"; or the identifier of a new unit defined in the list of unit 80 * definitions in the enclosing Model structure. There are no constraints 81 * on the units that can be chosen from these sets. There are no default 82 * units for parameters. 83 * </ul> 84 * 85 * The Parameter structure has another boolean attribute named "constant" 86 * that is used to indicate whether the parameter's value can vary during a 87 * simulation. (In SBML Level 3, the attribute is mandatory and must 88 * be given a value; in SBML Levels below Level 3, the attribute is 89 * optional.) A value of @c true indicates the parameter's value cannot be 90 * changed by any construct except InitialAssignment. Conversely, if the 91 * value of "constant" is @c false, other constructs in SBML, such as rules 92 * and events, can change the value of the parameter. 93 * 94 * SBML Level 3 uses a separate object class, LocalParameter, for 95 * parameters that are local to a Reaction's KineticLaw. In Levels prior 96 * to SBML Level 3, the Parameter class is used both for definitions 97 * of global parameters, as well as reaction-local parameters stored in a 98 * list within KineticLaw objects. Parameter objects that are local to a 99 * reaction (that is, those defined within the KineticLaw structure of a 100 * Reaction) cannot be changed by rules and therefore are <em>implicitly 101 * always constant</em>; consequently, in SBML Level 2, parameter 102 * definitions within Reaction structures should @em not have their 103 * "constant" attribute set to @c false. 104 * 105 * What if a global parameter has its "constant" attribute set to @c false, 106 * but the model does not contain any rules, events or other constructs 107 * that ever change its value over time? Although the model may be 108 * suspect, this situation is not strictly an error. A value of @c false 109 * for "constant" only indicates that a parameter @em can change value, not 110 * that it @em must. 111 * 112 * As with all other major SBML components, Parameter is derived from 113 * SBase, and the methods defined on SBase are available on Parameter. 114 * 115 * @note The use of the term @em parameter in SBML sometimes leads to 116 * confusion among readers who have a particular notion of what something 117 * called "parameter" should be. It has been the source of heated debate, 118 * but despite this, no one has yet found an adequate replacement term that 119 * does not have different connotations to different people and hence leads 120 * to confusion among @em some subset of users. Perhaps it would have been 121 * better to have two constructs, one called @em constants and the other 122 * called @em variables. The current approach in SBML is simply more 123 * parsimonious, using a single Parameter construct with the boolean flag 124 * "constant" indicating which flavor it is. In any case, readers are 125 * implored to look past their particular definition of a @em parameter and 126 * simply view SBML's Parameter as a single mechanism for defining both 127 * constants and (additional) variables in a model. (We write @em 128 * additional because the species in a model are usually considered to be 129 * the central variables.) After all, software tools are not required to 130 * expose to users the actual names of particular SBML constructs, and 131 * thus tools can present to their users whatever terms their designers 132 * feel best matches their target audience. 133 * 134 * In SBML Level 3 Version 2, many restrictions were lifted 135 * requiring only Boolean values in Boolean contexts, and numeric 136 * values in numeric contexts. This means that a Parameter may now 137 * be used as a Boolean, despite canonically having a numeric value. 138 * To be consistent, one should always assign it a value of @c true 139 * or @c false, and use it in Boolean contexts exclusively. It would 140 * be appropriate to give it an SBO value of 602 ('Logical parameter') 141 * if one chooses to do this. 142 * 143 * @see ListOfParameters 144 * 145 * 146 * <!-- ------------------------------------------------------------------- --> 147 * @class ListOfParameters 148 * @sbmlbrief{core} A list of Parameter objects. 149 * 150 * @copydetails doc_what_is_listof 151 */ 152 153 /** 154 * <!-- ~ ~ ~ ~ ~ Start of common documentation strings ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ 155 * The following text is used as common documentation blocks copied multiple 156 * times elsewhere in this file. The use of @class is a hack needed because 157 * Doxygen's @copydetails command has limited functionality. Symbols 158 * beginning with "doc_" are marked as ignored in our Doxygen configuration. 159 * ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ --> 160 * 161 * @class doc_note_parameter_about_constant 162 * 163 * @note Readers who view the documentation for LocalParameter may be 164 * confused about the presence of this method. LibSBML derives 165 * LocalParameter from Parameter; however, this does not precisely match 166 * the object hierarchy defined by SBML Level 3, where 167 * LocalParameter is derived directly from SBase and not Parameter. We 168 * believe this arrangement makes it easier for libSBML users to program 169 * applications that work with both SBML Level 2 and SBML 170 * Level 3, but programmers should also keep in mind this difference 171 * exists. A side-effect of libSBML's scheme is that certain methods on 172 * LocalParameter that are inherited from Parameter do not actually have 173 * relevance to LocalParameter objects. An example of this is the 174 * methods pertaining to Parameter's attribute "constant" (i.e., 175 * isSetConstant(), setConstant(), and getConstant()). 176 * 177 */ 178 179 #ifndef Parameter_h 180 #define Parameter_h 181 182 183 #include <sbml/common/extern.h> 184 #include <sbml/common/sbmlfwd.h> 185 186 #include <sbml/SBase.h> 187 #include <sbml/ListOf.h> 188 189 190 #ifdef __cplusplus 191 192 193 #include <string> 194 195 LIBSBML_CPP_NAMESPACE_BEGIN 196 197 class SBMLVisitor; 198 class UnitFormulaFormatter; 199 200 201 class LIBSBML_EXTERN Parameter : public SBase 202 { 203 public: 204 205 /** 206 * Creates a new Parameter using the given SBML @p level and @p version 207 * values. 208 * 209 * @param level an unsigned int, the SBML Level to assign to this Parameter. 210 * 211 * @param version an unsigned int, the SBML Version to assign to this 212 * Parameter. 213 * 214 * @copydetails doc_throw_exception_lv 215 * 216 * @copydetails doc_note_setting_lv 217 */ 218 Parameter (unsigned int level, unsigned int version); 219 220 221 /** 222 * Creates a new Parameter using the given SBMLNamespaces object 223 * @p sbmlns. 224 * 225 * @copydetails doc_what_are_sbmlnamespaces 226 * 227 * It is worth emphasizing that although this constructor does not take 228 * an identifier argument, in SBML Level 2 and beyond, the "id" 229 * (identifier) attribute of a Parameter is required to have a value. 230 * Thus, callers are cautioned to assign a value after calling this 231 * constructor if no identifier is provided as an argument. Setting the 232 * identifier can be accomplished using the method 233 * @if java setId(String id)@else setId()@endif. 234 * 235 * @param sbmlns an SBMLNamespaces object. 236 * 237 * @copydetails doc_throw_exception_namespace 238 * 239 * @copydetails doc_note_setting_lv 240 */ 241 Parameter (SBMLNamespaces* sbmlns); 242 243 244 /** 245 * Destroys this Parameter. 246 */ 247 virtual ~Parameter (); 248 249 250 /** 251 * Copy constructor; creates a copy of a Parameter. 252 * 253 * @param orig the Parameter instance to copy. 254 */ 255 Parameter(const Parameter& orig); 256 257 258 /** 259 * Assignment operator for Parameter. 260 * 261 * @param rhs the object whose values are used as the basis of the 262 * assignment. 263 */ 264 Parameter& operator=(const Parameter& rhs); 265 266 267 /** @cond doxygenLibsbmlInternal */ 268 /** 269 * Accepts the given SBMLVisitor for this instance of Parameter. 270 * 271 * @param v the SBMLVisitor instance to be used. 272 * 273 * @return the result of calling <code>v.visit()</code>, indicating 274 * whether the Visitor would like to visit the next Parameter object in 275 * the list of parameters within which @em the present object is 276 * embedded. 277 */ 278 virtual bool accept (SBMLVisitor& v) const; 279 /** @endcond */ 280 281 282 /** 283 * Creates and returns a deep copy of this Parameter object. 284 * 285 * @return the (deep) copy of this Parameter object. 286 */ 287 virtual Parameter* clone () const; 288 289 290 /** 291 * Initializes the fields of this Parameter object to "typical" defaults 292 * values. 293 * 294 * The SBML Parameter component has slightly different aspects and 295 * default attribute values in different SBML Levels and Versions. Many 296 * SBML object classes defined by libSBML have an initDefaults() method 297 * to set the values to certain common defaults, based mostly on what 298 * they are in SBML Level 2. In the case of Parameter, this method 299 * only sets the value of the "constant" attribute to @c true. 300 * 301 * @see getConstant() 302 * @see isSetConstant() 303 * @see setConstant(@if java boolean@endif) 304 */ 305 void initDefaults (); 306 307 308 /** 309 * Returns the value of the "id" attribute of this Parameter. 310 * 311 * @note Because of the inconsistent behavior of this function with 312 * respect to assignments and rules, it is now recommended to 313 * use the getIdAttribute() function instead. 314 * 315 * @copydetails doc_id_attribute 316 * 317 * @return the id of this Parameter. 318 * 319 * @see getIdAttribute() 320 * @see setIdAttribute(const std::string& sid) 321 * @see isSetIdAttribute() 322 * @see unsetIdAttribute() 323 */ 324 virtual const std::string& getId () const; 325 326 327 /** 328 * Returns the value of the "name" attribute of this Parameter object. 329 * 330 * @copydetails doc_get_name 331 */ 332 virtual const std::string& getName () const; 333 334 335 /** 336 * Returns the numerical value of this Parameter. 337 * 338 * @return the value of the "value" attribute of this Parameter, as a 339 * number of type @c double. 340 * 341 * @note <b>It is crucial</b> that callers not blindly call 342 * Parameter::getValue() without first using Parameter::isSetValue() to 343 * determine whether a value has ever been set. Otherwise, the value 344 * return by Parameter::getValue() may not actually represent a value 345 * assigned to the parameter. The reason is simply that the data type 346 * @c double in a program always has @em some value. A separate test is 347 * needed to determine whether the value is a true model value, or 348 * uninitialized data in a computer's memory location. 349 * 350 * @see isSetValue() 351 * @see setValue(double value) 352 * @see getUnits() 353 */ 354 double getValue () const; 355 356 357 /** 358 * Returns the units defined for this Parameter. 359 * 360 * The value of an SBML parameter's "units" attribute establishes the 361 * unit of measurement associated with the parameter's value. 362 * 363 * @return the value of the "units" attribute of this Parameter, as a 364 * string. An empty string indicates that no units have been assigned. 365 * 366 * @copydetails doc_note_unassigned_unit_are_not_a_default 367 * 368 * @see isSetUnits() 369 * @see setUnits(@if java String@endif) 370 * @see getValue() 371 */ 372 const std::string& getUnits () const; 373 374 375 /** 376 * Returns the value of the "constant" attribute of this Parameter instance. 377 * 378 * @return @c true if this Parameter is declared as being constant, 379 * @c false otherwise. 380 * 381 * @copydetails doc_note_parameter_about_constant 382 * 383 * @see isSetConstant() 384 * @see setConstant(@if java boolean@endif) 385 */ 386 virtual bool getConstant () const; 387 388 389 /** 390 * Predicate returning @c true if this 391 * Parameter's "id" attribute is set. 392 * 393 * @copydetails doc_isset_id 394 */ 395 virtual bool isSetId () const; 396 397 398 /** 399 * Predicate returning @c true if this 400 * Parameter's "name" attribute is set. 401 * 402 * @copydetails doc_isset_name 403 */ 404 virtual bool isSetName () const; 405 406 407 /** 408 * Predicate returning @c true if the 409 * "value" attribute of this Parameter is set. 410 * 411 * In SBML definitions after SBML Level 1 Version 1, 412 * parameter values are optional and have no defaults. If a model read 413 * from a file does not contain a setting for the "value" attribute of a 414 * parameter, its value is considered unset; it does not default to any 415 * particular value. Similarly, when a Parameter object is created in 416 * libSBML, it has no value until given a value. The 417 * Parameter::isSetValue() method allows calling applications to 418 * determine whether a given parameter's value has ever been set. 419 * 420 * In SBML Level 1 Version 1, parameters are required to have 421 * values and therefore, the value of a Parameter <b>should always be 422 * set</b>. In Level 1 Version 2 and beyond, the value is 423 * optional and as such, the "value" attribute may or may not be set. 424 * 425 * @return @c true if the value of this Parameter is set, 426 * @c false otherwise. 427 * 428 * @see getValue() 429 * @see setValue(double value) 430 */ 431 bool isSetValue () const; 432 433 434 /** 435 * Predicate returning @c true if the 436 * "units" attribute of this Parameter is set. 437 * 438 * @return @c true if the "units" attribute of this Parameter is 439 * set, @c false otherwise. 440 * 441 * @copydetails doc_note_unassigned_unit_are_not_a_default 442 */ 443 bool isSetUnits () const; 444 445 446 /** 447 * Predicate returning @c true if the 448 * "constant" attribute of this Parameter is set. 449 * 450 * @return @c true if the "constant" attribute of this Parameter is 451 * set, @c false otherwise. 452 * 453 * @copydetails doc_note_parameter_about_constant 454 * 455 * @see getConstant() 456 * @see setConstant(@if java boolean@endif) 457 */ 458 virtual bool isSetConstant () const; 459 460 461 /** 462 * Sets the value of the "id" attribute of this Parameter. 463 * 464 * @copydetails doc_set_id 465 */ 466 virtual int setId(const std::string& sid); 467 468 469 /** 470 * Sets the value of the "name" attribute of this Parameter. 471 * 472 * The string in @p name is copied. 473 * 474 * @param name the new name for the Parameter. 475 * 476 * @copydetails doc_returns_success_code 477 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 478 * @li @sbmlconstant{LIBSBML_INVALID_ATTRIBUTE_VALUE, OperationReturnValues_t} 479 */ 480 int setName (const std::string& name); 481 482 483 /** 484 * Sets the "value" attribute of this Parameter to the given @c double 485 * value and marks the attribute as set. 486 * 487 * @param value a @c double, the value to assign. 488 * 489 * @copydetails doc_returns_success_code 490 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 491 */ 492 int setValue (double value); 493 494 495 /** 496 * Sets the "units" attribute of this Parameter to a copy of the given 497 * units identifier @p units. 498 * 499 * @param units a string, the identifier of the units to assign to this 500 * Parameter instance. 501 * 502 * @copydetails doc_returns_success_code 503 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 504 * @li @sbmlconstant{LIBSBML_INVALID_ATTRIBUTE_VALUE, OperationReturnValues_t} 505 */ 506 int setUnits (const std::string& units); 507 508 509 /** 510 * Sets the "constant" attribute of this Parameter to the given boolean 511 * @p flag. 512 * 513 * @param flag a boolean, the value for the "constant" attribute of this 514 * Parameter instance. 515 * 516 * @copydetails doc_returns_success_code 517 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 518 * @li @sbmlconstant{LIBSBML_UNEXPECTED_ATTRIBUTE, OperationReturnValues_t} 519 * 520 * @copydetails doc_note_parameter_about_constant 521 * 522 * @see getConstant() 523 * @see isSetConstant() 524 */ 525 virtual int setConstant (bool flag); 526 527 528 /** 529 * Unsets the value of the "name" attribute of this Parameter. 530 * 531 * @copydetails doc_unset_name 532 */ 533 virtual int unsetName (); 534 535 536 /** 537 * Unsets the value of the "constant" attribute of this Parameter object. 538 * 539 * @copydetails doc_returns_success_code 540 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 541 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 542 * 543 * @see isSetConstant() 544 * @see setConstant(@if java boolean@endif) 545 * @see getConstant() 546 */ 547 int unsetConstant (); 548 549 550 /** 551 * Unsets the "value" attribute of this Parameter instance. 552 * 553 * @copydetails doc_returns_one_success_code 554 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 555 * 556 * In SBML Level 1 Version 1, parameters are required to have 557 * values and therefore, the value of a Parameter <b>should always be 558 * set</b>. In SBML Level 1 Version 2 and beyond, the value 559 * is optional and as such, the "value" attribute may or may not be set. 560 */ 561 int unsetValue (); 562 563 564 /** 565 * Unsets the "units" attribute of this Parameter instance. 566 * 567 * @copydetails doc_returns_success_code 568 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 569 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 570 */ 571 int unsetUnits (); 572 573 574 /** 575 * Constructs and returns a UnitDefinition that corresponds to the units 576 * of this Parameter's value. 577 * 578 * Parameters in SBML have an attribute ("units") for declaring the units 579 * of measurement intended for the parameter's value. <b>No defaults are 580 * defined</b> by SBML in the absence of a definition for "units". This 581 * method returns a UnitDefinition object based on the units declared for 582 * this Parameter using its "units" attribute, or it returns @c NULL if 583 * no units have been declared. 584 * 585 * Note that unit declarations for Parameter objects are specified in 586 * terms of the @em identifier of a unit (e.g., using setUnits()), but 587 * @em this method returns a UnitDefinition object, not a unit 588 * identifier. It does this by constructing an appropriate 589 * UnitDefinition.For SBML Level 2 models, it will do this even when 590 * the value of the "units" attribute is one of the special SBML 591 * Level 2 unit identifiers @c "substance", @c "volume", @c "area", 592 * @c "length" or @c "time". Callers may find this useful in conjunction 593 * with the helper methods provided by the UnitDefinition class for 594 * comparing different UnitDefinition objects. 595 * 596 * @return a UnitDefinition that expresses the units of this 597 * Parameter, or @c NULL if one cannot be constructed. 598 * 599 * @note The libSBML system for unit analysis depends on the model as a 600 * whole. In cases where the Parameter object has not yet been added to 601 * a model, or the model itself is incomplete, unit analysis is not 602 * possible, and consequently this method will return @c NULL. 603 * 604 * @see isSetUnits() 605 */ 606 UnitDefinition * getDerivedUnitDefinition(); 607 608 609 /** 610 * Constructs and returns a UnitDefinition that corresponds to the units 611 * of this Parameter's value. 612 * 613 * Parameters in SBML have an attribute ("units") for declaring the units 614 * of measurement intended for the parameter's value. <b>No defaults are 615 * defined</b> by SBML in the absence of a definition for "units". This 616 * method returns a UnitDefinition object based on the units declared for 617 * this Parameter using its "units" attribute, or it returns @c NULL if 618 * no units have been declared. 619 * 620 * Note that unit declarations for Parameter objects are specified in 621 * terms of the @em identifier of a unit (e.g., using setUnits()), but 622 * @em this method returns a UnitDefinition object, not a unit 623 * identifier. It does this by constructing an appropriate 624 * UnitDefinition. For SBML Level 2 models, it will do this even 625 * when the value of the "units" attribute is one of the predefined SBML 626 * units @c "substance", @c "volume", @c "area", @c "length" or 627 * @c "time". Callers may find this useful in conjunction with the helper 628 * methods provided by the UnitDefinition class for comparing different 629 * UnitDefinition objects. 630 * 631 * @return a UnitDefinition that expresses the units of this 632 * Parameter, or @c NULL if one cannot be constructed. 633 * 634 * @note The libSBML system for unit analysis depends on the model as a 635 * whole. In cases where the Parameter object has not yet been added to 636 * a model, or the model itself is incomplete, unit analysis is not 637 * possible, and consequently this method will return @c NULL. 638 * 639 * @see isSetUnits() 640 */ 641 const UnitDefinition * getDerivedUnitDefinition() const; 642 643 644 /** 645 * Returns the libSBML type code for this SBML object. 646 * 647 * @copydetails doc_what_are_typecodes 648 * 649 * @return the SBML type code for this object: 650 * @sbmlconstant{SBML_PARAMETER, SBMLTypeCode_t} (default). 651 * 652 * @copydetails doc_warning_typecodes_not_unique 653 * 654 * @see getElementName() 655 * @see getPackageName() 656 */ 657 virtual int getTypeCode () const; 658 659 660 /** 661 * Returns the XML element name of this object, which for Parameter, is 662 * always @c "parameter". 663 * 664 * @return the name of this element, i.e., @c "parameter". 665 */ 666 virtual const std::string& getElementName () const; 667 668 669 /** @cond doxygenLibsbmlInternal */ 670 /** 671 * Subclasses should override this method to write out their contained 672 * SBML objects as XML elements. Be sure to call your parent's 673 * implementation of this method as well. 674 */ 675 virtual void writeElements (XMLOutputStream& stream) const; 676 /** @endcond */ 677 678 679 /** 680 * Predicate returning @c true if 681 * all the required attributes for this Parameter object 682 * have been set. 683 * 684 * The required attributes for a Parameter object are: 685 * @li "id" (or "name" in SBML Level 1) 686 * @li "value" (required in Level 1, optional otherwise) 687 * 688 * @return @c true if the required attributes have been set, @c false 689 * otherwise. 690 */ 691 virtual bool hasRequiredAttributes() const ; 692 693 694 /** 695 * Renames all the @c UnitSIdRef attributes on this element. 696 * 697 * @copydetails doc_what_is_unitsidref 698 * 699 * This method works by looking at all unit identifier attribute values 700 * (including, if appropriate, inside mathematical formulas), comparing the 701 * unit identifiers to the value of @p oldid. If any matches are found, 702 * the matching identifiers are replaced with @p newid. The method does 703 * @em not descend into child elements. 704 * 705 * @param oldid the old identifier. 706 * @param newid the new identifier. 707 */ 708 virtual void renameUnitSIdRefs(const std::string& oldid, const std::string& newid); 709 710 711 /** @cond doxygenLibsbmlInternal */ 712 /* set a flag to indicate that a parameter should 713 * calculate its units from math */ 714 virtual void setCalculatingUnits(bool calculatingUnits); 715 716 /** @endcond */ 717 718 719 720 721 722 723 #ifndef SWIG 724 725 726 727 /** @cond doxygenLibsbmlInternal */ 728 729 /** 730 * Returns the value of the "attributeName" attribute of this Parameter. 731 * 732 * @param attributeName, the name of the attribute to retrieve. 733 * 734 * @param value, the address of the value to record. 735 * 736 * @copydetails doc_returns_success_code 737 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 738 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 739 */ 740 virtual int getAttribute(const std::string& attributeName, bool& value) 741 const; 742 743 /** @endcond */ 744 745 746 747 /** @cond doxygenLibsbmlInternal */ 748 749 /** 750 * Returns the value of the "attributeName" attribute of this Parameter. 751 * 752 * @param attributeName, the name of the attribute to retrieve. 753 * 754 * @param value, the address of the value to record. 755 * 756 * @copydetails doc_returns_success_code 757 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 758 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 759 */ 760 virtual int getAttribute(const std::string& attributeName, int& value) const; 761 762 /** @endcond */ 763 764 765 766 /** @cond doxygenLibsbmlInternal */ 767 768 /** 769 * Returns the value of the "attributeName" attribute of this Parameter. 770 * 771 * @param attributeName, the name of the attribute to retrieve. 772 * 773 * @param value, the address of the value to record. 774 * 775 * @copydetails doc_returns_success_code 776 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 777 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 778 */ 779 virtual int getAttribute(const std::string& attributeName, 780 double& value) const; 781 782 /** @endcond */ 783 784 785 786 /** @cond doxygenLibsbmlInternal */ 787 788 /** 789 * Returns the value of the "attributeName" attribute of this Parameter. 790 * 791 * @param attributeName, the name of the attribute to retrieve. 792 * 793 * @param value, the address of the value to record. 794 * 795 * @copydetails doc_returns_success_code 796 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 797 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 798 */ 799 virtual int getAttribute(const std::string& attributeName, 800 unsigned int& value) const; 801 802 /** @endcond */ 803 804 805 806 /** @cond doxygenLibsbmlInternal */ 807 808 /** 809 * Returns the value of the "attributeName" attribute of this Parameter. 810 * 811 * @param attributeName, the name of the attribute to retrieve. 812 * 813 * @param value, the address of the value to record. 814 * 815 * @copydetails doc_returns_success_code 816 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 817 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 818 */ 819 virtual int getAttribute(const std::string& attributeName, 820 std::string& value) const; 821 822 /** @endcond */ 823 824 825 826 /** @cond doxygenLibsbmlInternal */ 827 828 /** 829 * Returns the value of the "attributeName" attribute of this Parameter. 830 * 831 * @param attributeName, the name of the attribute to retrieve. 832 * 833 * @param value, the address of the value to record. 834 * 835 * @copydetails doc_returns_success_code 836 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 837 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 838 */ 839 //virtual int getAttribute(const std::string& attributeName, 840 // const char* value) const; 841 842 /** @endcond */ 843 844 845 846 /** @cond doxygenLibsbmlInternal */ 847 848 /** 849 * Predicate returning @c true if this Parameter's attribute "attributeName" 850 * is set. 851 * 852 * @param attributeName, the name of the attribute to query. 853 * 854 * @return @c true if this Parameter's attribute "attributeName" has been 855 * set, otherwise @c false is returned. 856 */ 857 virtual bool isSetAttribute(const std::string& attributeName) const; 858 859 /** @endcond */ 860 861 862 863 /** @cond doxygenLibsbmlInternal */ 864 865 /** 866 * Sets the value of the "attributeName" attribute of this Parameter. 867 * 868 * @param attributeName, the name of the attribute to set. 869 * 870 * @param value, the value of the attribute to set. 871 * 872 * @copydetails doc_returns_success_code 873 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 874 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 875 */ 876 virtual int setAttribute(const std::string& attributeName, bool value); 877 878 /** @endcond */ 879 880 881 882 /** @cond doxygenLibsbmlInternal */ 883 884 /** 885 * Sets the value of the "attributeName" attribute of this Parameter. 886 * 887 * @param attributeName, the name of the attribute to set. 888 * 889 * @param value, the value of the attribute to set. 890 * 891 * @copydetails doc_returns_success_code 892 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 893 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 894 */ 895 virtual int setAttribute(const std::string& attributeName, int value); 896 897 /** @endcond */ 898 899 900 901 /** @cond doxygenLibsbmlInternal */ 902 903 /** 904 * Sets the value of the "attributeName" attribute of this Parameter. 905 * 906 * @param attributeName, the name of the attribute to set. 907 * 908 * @param value, the value of the attribute to set. 909 * 910 * @copydetails doc_returns_success_code 911 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 912 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 913 */ 914 virtual int setAttribute(const std::string& attributeName, double value); 915 916 /** @endcond */ 917 918 919 920 /** @cond doxygenLibsbmlInternal */ 921 922 /** 923 * Sets the value of the "attributeName" attribute of this Parameter. 924 * 925 * @param attributeName, the name of the attribute to set. 926 * 927 * @param value, the value of the attribute to set. 928 * 929 * @copydetails doc_returns_success_code 930 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 931 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 932 */ 933 virtual int setAttribute(const std::string& attributeName, 934 unsigned int value); 935 936 /** @endcond */ 937 938 939 940 /** @cond doxygenLibsbmlInternal */ 941 942 /** 943 * Sets the value of the "attributeName" attribute of this Parameter. 944 * 945 * @param attributeName, the name of the attribute to set. 946 * 947 * @param value, the value of the attribute to set. 948 * 949 * @copydetails doc_returns_success_code 950 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 951 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 952 */ 953 virtual int setAttribute(const std::string& attributeName, 954 const std::string& value); 955 956 /** @endcond */ 957 958 959 960 /** @cond doxygenLibsbmlInternal */ 961 962 /** 963 * Sets the value of the "attributeName" attribute of this Parameter. 964 * 965 * @param attributeName, the name of the attribute to set. 966 * 967 * @param value, the value of the attribute to set. 968 * 969 * @copydetails doc_returns_success_code 970 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 971 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 972 */ 973 //virtual int setAttribute(const std::string& attributeName, const char* 974 // value); 975 976 /** @endcond */ 977 978 979 980 /** @cond doxygenLibsbmlInternal */ 981 982 /** 983 * Unsets the value of the "attributeName" attribute of this Parameter. 984 * 985 * @param attributeName, the name of the attribute to query. 986 * 987 * @copydetails doc_returns_success_code 988 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 989 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 990 */ 991 virtual int unsetAttribute(const std::string& attributeName); 992 993 /** @endcond */ 994 995 996 /** @cond doxygenLibsbmlInternal */ 997 bool isExplicitlySetConstant() const; 998 /** @endcond */ 999 1000 1001 1002 #endif /* !SWIG */ 1003 1004 1005 protected: 1006 /** @cond doxygenLibsbmlInternal */ 1007 Parameter (SBMLNamespaces* sbmlns, bool isLocal); 1008 1009 /** 1010 * Subclasses should override this method to get the list of 1011 * expected attributes. 1012 * This function is invoked from corresponding readAttributes() 1013 * function. 1014 */ 1015 virtual void addExpectedAttributes(ExpectedAttributes& attributes); 1016 1017 /** 1018 * Subclasses should override this method to read values from the given 1019 * XMLAttributes set into their specific fields. Be sure to call your 1020 * parent's implementation of this method as well. 1021 */ 1022 virtual void readAttributes (const XMLAttributes& attributes, 1023 const ExpectedAttributes& expectedAttributes); 1024 1025 void readL1Attributes (const XMLAttributes& attributes); 1026 1027 void readL2Attributes (const XMLAttributes& attributes); 1028 1029 void readL3Attributes (const XMLAttributes& attributes); 1030 1031 1032 /** 1033 * Subclasses should override this method to write their XML attributes 1034 * to the XMLOutputStream. Be sure to call your parent's implementation 1035 * of this method as well. 1036 */ 1037 virtual void writeAttributes (XMLOutputStream& stream) const; 1038 1039 //std::string mId; 1040 //std::string mName; 1041 double mValue; 1042 std::string mUnits; 1043 bool mConstant; 1044 1045 bool mIsSetValue; 1046 bool mIsSetConstant; 1047 1048 bool mExplicitlySetConstant; 1049 1050 /* the validator classes need to be friends to access the 1051 * protected constructor that takes no arguments 1052 */ 1053 friend class Validator; 1054 friend class ConsistencyValidator; 1055 friend class IdentifierConsistencyValidator; 1056 friend class InternalConsistencyValidator; 1057 friend class L1CompatibilityValidator; 1058 friend class L2v1CompatibilityValidator; 1059 friend class L2v2CompatibilityValidator; 1060 friend class L2v3CompatibilityValidator; 1061 friend class L2v4CompatibilityValidator; 1062 friend class MathMLConsistencyValidator; 1063 friend class ModelingPracticeValidator; 1064 friend class OverdeterminedValidator; 1065 friend class SBOConsistencyValidator; 1066 friend class UnitConsistencyValidator; 1067 1068 /** @endcond */ 1069 1070 1071 private: 1072 1073 /** @cond doxygenLibsbmlInternal */ 1074 1075 UnitDefinition * inferUnits(Model* m, bool globalParameter); 1076 1077 UnitDefinition * inferUnitsFromAssignments(UnitFormulaFormatter *uff, 1078 Model *m); 1079 1080 UnitDefinition * inferUnitsFromRules(UnitFormulaFormatter *uff, 1081 Model *m); 1082 1083 UnitDefinition * inferUnitsFromReactions(UnitFormulaFormatter *uff, 1084 Model *m); 1085 1086 UnitDefinition * inferUnitsFromEvents(UnitFormulaFormatter *uff, 1087 Model *m); 1088 1089 UnitDefinition * inferUnitsFromEvent(Event * e, UnitFormulaFormatter *uff, 1090 Model *m); 1091 1092 UnitDefinition * inferUnitsFromKineticLaw(KineticLaw* kl, 1093 UnitFormulaFormatter *uff, Model *m); 1094 1095 /** @endcond */ 1096 1097 /** @cond doxygenLibsbmlInternal */ 1098 /* flag to indicate that a parameter should calculate its units from math */ 1099 bool getCalculatingUnits() const; 1100 1101 bool mCalculatingUnits; 1102 1103 /** @endcond */ 1104 1105 }; 1106 1107 1108 class LIBSBML_EXTERN ListOfParameters : public ListOf 1109 { 1110 public: 1111 1112 /** 1113 * Creates a new ListOfParameters object. 1114 * 1115 * The object is constructed such that it is valid for the given SBML 1116 * Level and Version combination. 1117 * 1118 * @param level the SBML Level. 1119 * 1120 * @param version the Version within the SBML Level. 1121 * 1122 * @copydetails doc_throw_exception_lv 1123 * 1124 * @copydetails doc_note_setting_lv 1125 */ 1126 ListOfParameters (unsigned int level, unsigned int version); 1127 1128 1129 /** 1130 * Creates a new ListOfParameters object. 1131 * 1132 * The object is constructed such that it is valid for the SBML Level and 1133 * Version combination determined by the SBMLNamespaces object in @p 1134 * sbmlns. 1135 * 1136 * @param sbmlns an SBMLNamespaces object that is used to determine the 1137 * characteristics of the ListOfParameters object to be created. 1138 * 1139 * @copydetails doc_throw_exception_namespace 1140 * 1141 * @copydetails doc_note_setting_lv 1142 */ 1143 ListOfParameters (SBMLNamespaces* sbmlns); 1144 1145 1146 /** 1147 * Creates and returns a deep copy of this ListOfParameters object. 1148 * 1149 * @return the (deep) copy of this ListOfParameters object. 1150 */ 1151 virtual ListOfParameters* clone () const; 1152 1153 1154 /** 1155 * Returns the libSBML type code for the objects contained in this ListOf 1156 * (i.e., Parameter objects, if the list is non-empty). 1157 * 1158 * @copydetails doc_what_are_typecodes 1159 * 1160 * @return the SBML type code for this objects contained in this list: 1161 * @sbmlconstant{SBML_PARAMETER, SBMLTypeCode_t} (default). 1162 * 1163 * @see getElementName() 1164 * @see getPackageName() 1165 */ 1166 virtual int getItemTypeCode () const; 1167 1168 1169 /** 1170 * Returns the XML element name of this object. 1171 * 1172 * For ListOfParameters, the XML element name is @c "listOfParameters". 1173 * 1174 * @return the name of this element, i.e., @c "listOfParameters". 1175 */ 1176 virtual const std::string& getElementName () const; 1177 1178 1179 /** 1180 * Returns the Parameter object located at position @p n within this 1181 * ListOfParameters instance. 1182 * 1183 * @param n the index number of the Parameter to get. 1184 * 1185 * @return the nth Parameter in this ListOfParameters. If the index @p n 1186 * is out of bounds for the length of the list, then @c NULL is returned. 1187 * 1188 * @see size() 1189 * @see get(const std::string& sid) 1190 */ 1191 virtual Parameter * get(unsigned int n); 1192 1193 1194 /** 1195 * Returns the Parameter object located at position @p n within this 1196 * ListOfParameters instance. 1197 * 1198 * @param n the index number of the Parameter to get. 1199 * 1200 * @return the nth Parameter in this ListOfParameters. If the index @p n 1201 * is out of bounds for the length of the list, then @c NULL is returned. 1202 * 1203 * @see size() 1204 * @see get(const std::string& sid) 1205 */ 1206 virtual const Parameter * get(unsigned int n) const; 1207 1208 1209 /** 1210 * Returns the first Parameter object matching the given identifier. 1211 * 1212 * @param sid a string, the identifier of the Parameter to get. 1213 * 1214 * @return the Parameter object found. The caller owns the returned 1215 * object and is responsible for deleting it. If none of the items have 1216 * an identifier matching @p sid, then @c NULL is returned. 1217 * 1218 * @see get(unsigned int n) 1219 * @see size() 1220 */ 1221 virtual Parameter* get (const std::string& sid); 1222 1223 1224 /** 1225 * Returns the first Parameter object matching the given identifier. 1226 * 1227 * @param sid a string representing the identifier of the Parameter to 1228 * get. 1229 * 1230 * @return the Parameter object found. The caller owns the returned 1231 * object and is responsible for deleting it. If none of the items have 1232 * an identifier matching @p sid, then @c NULL is returned. 1233 * 1234 * @see get(unsigned int n) 1235 * @see size() 1236 */ 1237 virtual const Parameter* get (const std::string& sid) const; 1238 1239 1240 /** 1241 * Removes the nth item from this ListOfParameters, and returns a pointer 1242 * to it. 1243 * 1244 * @param n the index of the item to remove. 1245 * 1246 * @return the item removed. The caller owns the returned object and is 1247 * responsible for deleting it. If the index number @p n is out of 1248 * bounds for the length of the list, then @c NULL is returned. 1249 * 1250 * @see size() 1251 */ 1252 virtual Parameter* remove (unsigned int n); 1253 1254 1255 /** 1256 * Removes the first Parameter object in this ListOfParameters 1257 * matching the given identifier, and returns a pointer to it. 1258 * 1259 * @param sid the identifier of the item to remove. 1260 * 1261 * @return the item removed. The caller owns the returned object and is 1262 * responsible for deleting it. If none of the items have an identifier 1263 * matching @p sid, then @c NULL is returned. 1264 */ 1265 virtual Parameter* remove (const std::string& sid); 1266 1267 1268 /** @cond doxygenLibsbmlInternal */ 1269 /** 1270 * Returns the ordinal position of this element in the containing object 1271 * (which in this case is the Model object). 1272 * 1273 * The ordering of elements in the XML form of SBML is generally fixed 1274 * for most components in SBML. So, for example, the ListOfParameters 1275 * in a model is (in SBML Level 2 Version 4) the seventh 1276 * ListOf___. (However, it differs for different Levels and Versions of 1277 * SBML.) 1278 * 1279 * @return the ordinal position of the element with respect to its 1280 * siblings, or @c -1 (default) to indicate the position is not significant. 1281 */ 1282 virtual int getElementPosition () const; 1283 1284 /** @endcond */ 1285 1286 1287 protected: 1288 /** @cond doxygenLibsbmlInternal */ 1289 /** 1290 * Create a ListOfParameters object corresponding to the next token in 1291 * the XML input stream. 1292 * 1293 * @return the SBML object corresponding to next XMLToken in the 1294 * XMLInputStream, or @c NULL if the token was not recognized. 1295 */ 1296 virtual SBase* createObject (XMLInputStream& stream); 1297 1298 /** @endcond */ 1299 1300 }; 1301 1302 LIBSBML_CPP_NAMESPACE_END 1303 1304 #endif /* __cplusplus */ 1305 1306 1307 #ifndef SWIG 1308 1309 LIBSBML_CPP_NAMESPACE_BEGIN 1310 BEGIN_C_DECLS 1311 1312 /** 1313 * Creates a new Parameter_t structure using the given SBML @p level 1314 * and @p version values. 1315 * 1316 * @param level an unsigned int, the SBML Level to assign to this 1317 * Parameter_t. 1318 * 1319 * @param version an unsigned int, the SBML Version to assign to this 1320 * Parameter_t. 1321 * 1322 * @return a pointer to the newly created Parameter_t structure. 1323 * 1324 * @copydetails doc_note_setting_lv 1325 * 1326 * @memberof Parameter_t 1327 */ 1328 LIBSBML_EXTERN 1329 Parameter_t * 1330 Parameter_create (unsigned int level, unsigned int version); 1331 1332 1333 /** 1334 * Creates a new Parameter_t structure using the given 1335 * SBMLNamespaces_t structure. 1336 * 1337 * @param sbmlns SBMLNamespaces_t, a pointer to an SBMLNamespaces_t structure 1338 * to assign to this Parameter_t. 1339 * 1340 * @return a pointer to the newly created Parameter_t structure. 1341 * 1342 * @copydetails doc_note_setting_lv 1343 * 1344 * @memberof Parameter_t 1345 */ 1346 LIBSBML_EXTERN 1347 Parameter_t * 1348 Parameter_createWithNS (SBMLNamespaces_t *sbmlns); 1349 1350 1351 /** 1352 * Frees the given Parameter_t structure. 1353 * 1354 * @param p the Parameter_t structure to be freed. 1355 * 1356 * @memberof Parameter_t 1357 */ 1358 LIBSBML_EXTERN 1359 void 1360 Parameter_free (Parameter_t *p); 1361 1362 1363 /** 1364 * Creates a deep copy of the given Parameter_t structure 1365 * 1366 * @param p the Parameter_t structure to be copied. 1367 * 1368 * @return a (deep) copy of the given Parameter_t structure. 1369 * 1370 * @memberof Parameter_t 1371 */ 1372 LIBSBML_EXTERN 1373 Parameter_t * 1374 Parameter_clone (const Parameter_t *p); 1375 1376 1377 /** 1378 * Initializes the attributes of this Parameter_t structure to their defaults. 1379 * 1380 * The exact results depends on the %SBML Level and Version in use. The 1381 * cases are currently the following: 1382 * 1383 * @li (%SBML Level 2 only) constant = @c true 1384 * 1385 * @param p the Parameter_t structure to initialize. 1386 * 1387 * @memberof Parameter_t 1388 */ 1389 LIBSBML_EXTERN 1390 void 1391 Parameter_initDefaults (Parameter_t *p); 1392 1393 1394 /** 1395 * Returns a list of XMLNamespaces_t associated with this Parameter_t 1396 * structure. 1397 * 1398 * @param p the Parameter_t structure. 1399 * 1400 * @return pointer to the XMLNamespaces_t structure associated with 1401 * this structure 1402 * 1403 * @memberof Parameter_t 1404 */ 1405 LIBSBML_EXTERN 1406 const XMLNamespaces_t * 1407 Parameter_getNamespaces(Parameter_t *p); 1408 1409 1410 /** 1411 * Takes a Parameter_t structure and returns its identifier. 1412 * 1413 * @param p the Parameter_t structure whose identifier is sought. 1414 * 1415 * @return the identifier of this Parameter_t, as a pointer to a string. 1416 * 1417 * @memberof Parameter_t 1418 */ 1419 LIBSBML_EXTERN 1420 const char * 1421 Parameter_getId (const Parameter_t *p); 1422 1423 1424 /** 1425 * Takes a Parameter_t structure and returns its name. 1426 * 1427 * @param p the Parameter_t whose name is sought. 1428 * 1429 * @return the name of this Parameter_t, as a pointer to a string. 1430 * 1431 * @memberof Parameter_t 1432 */ 1433 LIBSBML_EXTERN 1434 const char * 1435 Parameter_getName (const Parameter_t *p); 1436 1437 1438 /** 1439 * Takes a Parameter_t structure and returns its value. 1440 * 1441 * @param p the Parameter_t whose value is sought. 1442 * 1443 * @return the value assigned to this Parameter_t structure, as a @c double. 1444 * 1445 * @memberof Parameter_t 1446 */ 1447 LIBSBML_EXTERN 1448 double 1449 Parameter_getValue (const Parameter_t *p); 1450 1451 1452 /** 1453 * Takes a Parameter_t structure and returns its units. 1454 * 1455 * @param p the Parameter_t whose units are sought. 1456 * 1457 * @return the units assigned to this Parameter_t structure, as a pointer 1458 * to a string. 1459 * 1460 * @memberof Parameter_t 1461 */ 1462 LIBSBML_EXTERN 1463 const char * 1464 Parameter_getUnits (const Parameter_t *p); 1465 1466 1467 /** 1468 * Takes a Parameter_t structure and returns @c 1 (true) or @c 0 (false), depending 1469 * on the value of the parameter's "constant" attribute. 1470 * 1471 * @param p the Parameter_t whose constant value is sought. 1472 * 1473 * @return the value of the "constant" attribute, with @c nonzero meaning 1474 * true and @c zero meaning false. 1475 * 1476 * @memberof Parameter_t 1477 */ 1478 LIBSBML_EXTERN 1479 int 1480 Parameter_getConstant (const Parameter_t *p); 1481 1482 1483 /** 1484 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether the given 1485 * Parameter_t structure's identifier is set. 1486 * 1487 * @param p the Parameter_t structure to query. 1488 * 1489 * @return @c 1 (true) if the "id" attribute of the given 1490 * Parameter_t structure is set, @c 0 (false) otherwise. 1491 * 1492 * @memberof Parameter_t 1493 */ 1494 LIBSBML_EXTERN 1495 int 1496 Parameter_isSetId (const Parameter_t *p); 1497 1498 1499 /** 1500 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether the given 1501 * Parameter_t structure's name is set. 1502 * 1503 * @param p the Parameter_t structure to query. 1504 * 1505 * @return @c 1 (true) if the "name" attribute of the given 1506 * Parameter_t structure is set, @c 0 (false) otherwise. 1507 * 1508 * @memberof Parameter_t 1509 */ 1510 LIBSBML_EXTERN 1511 int 1512 Parameter_isSetName (const Parameter_t *p); 1513 1514 1515 /** 1516 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether the given 1517 * Parameter_t structure's value is set. 1518 * 1519 * @param p the Parameter_t structure to query. 1520 * 1521 * @return @c 1 (true) if the "value" attribute of the given 1522 * Parameter_t structure is set, @c 0 (false) otherwise. 1523 * 1524 * @note In SBML Level 1 Version 1, a Parameter_t value is required and 1525 * therefore <em>should always be set</em>. In Level 1 Version 2 and 1526 * later, the value is optional, and as such, may or may not be set. 1527 * 1528 * @memberof Parameter_t 1529 */ 1530 LIBSBML_EXTERN 1531 int 1532 Parameter_isSetValue (const Parameter_t *p); 1533 1534 1535 /** 1536 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether the given 1537 * Parameter_t structure's units have been set. 1538 * 1539 * @param p the Parameter_t structure to query. 1540 * 1541 * @return @c 1 (true) if the "units" attribute of the given 1542 * Parameter_t structure is set, @c 0 (false) otherwise. 1543 * 1544 * @memberof Parameter_t 1545 */ 1546 LIBSBML_EXTERN 1547 int 1548 Parameter_isSetUnits (const Parameter_t *p); 1549 1550 1551 /** 1552 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether the given 1553 * Parameter_t structure's constant attribute have been set. 1554 * 1555 * @param p the Parameter_t structure to query. 1556 * 1557 * @return @c 1 (true) if the "constant" attribute of the given 1558 * Parameter_t structure is set, @c 0 (false) otherwise. 1559 * 1560 * @memberof Parameter_t 1561 */ 1562 LIBSBML_EXTERN 1563 int 1564 Parameter_isSetConstant (const Parameter_t *p); 1565 1566 1567 /** 1568 * Assigns the identifier of a Parameter_t structure. 1569 * 1570 * This makes a copy of the string passed in the parameter @p sid. 1571 * 1572 * @param p the Parameter_t structure to set. 1573 * @param sid the string to use as the identifier. 1574 * 1575 * @copydetails doc_returns_success_code 1576 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1577 * @li @sbmlconstant{LIBSBML_INVALID_ATTRIBUTE_VALUE, OperationReturnValues_t} 1578 * 1579 * @note Using this function with an @p sid of NULL is equivalent to 1580 * unsetting the "id" attribute. 1581 * 1582 * @memberof Parameter_t 1583 */ 1584 LIBSBML_EXTERN 1585 int 1586 Parameter_setId (Parameter_t *p, const char *sid); 1587 1588 1589 /** 1590 * Assign the name of a Parameter_t structure. 1591 * 1592 * This makes a copy of the string passed in as the argument @p name. 1593 * 1594 * @param p the Parameter_t structure to set. 1595 * @param name the string to use as the name. 1596 * 1597 * @copydetails doc_returns_success_code 1598 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1599 * @li @sbmlconstant{LIBSBML_INVALID_ATTRIBUTE_VALUE, OperationReturnValues_t} 1600 * 1601 * @note Using this function with the name set to NULL is equivalent to 1602 * unsetting the "name" attribute. 1603 * 1604 * @memberof Parameter_t 1605 */ 1606 LIBSBML_EXTERN 1607 int 1608 Parameter_setName (Parameter_t *p, const char *name); 1609 1610 1611 /** 1612 * Assign the value of a Parameter_t structure. 1613 * 1614 * @param p the Parameter_t structure to set. 1615 * @param value the @c double value to use. 1616 * 1617 * @copydetails doc_returns_success_code 1618 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1619 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1620 * 1621 * @memberof Parameter_t 1622 */ 1623 LIBSBML_EXTERN 1624 int 1625 Parameter_setValue (Parameter_t *p, double value); 1626 1627 1628 /** 1629 * Assign the units of a Parameter_t structure. 1630 * 1631 * This makes a copy of the string passed in as the argument @p units. 1632 * 1633 * @param p the Parameter_t structure to set. 1634 * @param units the string to use as the identifier of the units to assign. 1635 * 1636 * @copydetails doc_returns_success_code 1637 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1638 * @li @sbmlconstant{LIBSBML_INVALID_ATTRIBUTE_VALUE, OperationReturnValues_t} 1639 * 1640 * @note Using this function with units set to NULL is equivalent to 1641 * unsetting the "units" attribute. 1642 * 1643 * @memberof Parameter_t 1644 */ 1645 LIBSBML_EXTERN 1646 int 1647 Parameter_setUnits (Parameter_t *p, const char *units); 1648 1649 1650 /** 1651 * Assign the "constant" attribute of a Parameter_t structure. 1652 * 1653 * @param p the Parameter_t structure to set. 1654 * @param value the value to assign as the "constant" attribute 1655 * of the parameter, either @c zero for false or @c nonzero for true. 1656 * 1657 * @copydetails doc_returns_success_code 1658 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1659 * @li @sbmlconstant{LIBSBML_UNEXPECTED_ATTRIBUTE, OperationReturnValues_t} 1660 * 1661 * @memberof Parameter_t 1662 */ 1663 LIBSBML_EXTERN 1664 int 1665 Parameter_setConstant (Parameter_t *p, int value); 1666 1667 1668 /** 1669 * Unsets the name of this Parameter_t structure. 1670 * 1671 * @param p the Parameter_t structure whose name is to be unset. 1672 * 1673 * @copydetails doc_returns_success_code 1674 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1675 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 1676 * 1677 * @memberof Parameter_t 1678 */ 1679 LIBSBML_EXTERN 1680 int 1681 Parameter_unsetName (Parameter_t *p); 1682 1683 1684 /** 1685 * Unsets the value of the "constant" attribute of the given Parameter_t 1686 * structure. 1687 * 1688 * @param c the Parameter_t structure. 1689 * 1690 * @copydetails doc_returns_success_code 1691 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1692 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 1693 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1694 * 1695 * @memberof Parameter_t 1696 */ 1697 LIBSBML_EXTERN 1698 int 1699 Parameter_unsetConstant (Parameter_t *c); 1700 1701 1702 /** 1703 * Unsets the value of this Parameter_t structure. 1704 * 1705 * In SBML Level 1 Version 1, a parameter is required to have a value and 1706 * therefore this attribute <em>should always be set</em>. In Level 1 1707 * Version 2 and beyond, a value is optional, and as such, may or may not be 1708 * set. 1709 * 1710 * @param p the Parameter_t structure whose value is to be unset. 1711 * 1712 * @copydetails doc_returns_success_code 1713 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1714 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1715 * 1716 * @memberof Parameter_t 1717 */ 1718 LIBSBML_EXTERN 1719 int 1720 Parameter_unsetValue (Parameter_t *p); 1721 1722 1723 /** 1724 * Unsets the units of this Parameter_t structure. 1725 * 1726 * @param p the Parameter_t structure whose units are to be unset. 1727 * 1728 * @copydetails doc_returns_success_code 1729 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1730 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 1731 * 1732 * @memberof Parameter_t 1733 */ 1734 LIBSBML_EXTERN 1735 int 1736 Parameter_unsetUnits (Parameter_t *p); 1737 1738 1739 /** 1740 * Constructs and returns a UnitDefinition_t structure that expresses 1741 * the units of this Parameter_t structure. 1742 * 1743 * @param p the Parameter_t structure whose units are to be returned. 1744 * 1745 * @return a UnitDefinition_t structure that expresses the units 1746 * of this Parameter_t strucuture. 1747 * 1748 * @note This function returns the units of the Parameter_t expressed 1749 * as a UnitDefinition_t. The units may be those explicitly declared. 1750 * In the case where no units have been declared, @c NULL is returned. 1751 * 1752 * @memberof Parameter_t 1753 */ 1754 LIBSBML_EXTERN 1755 UnitDefinition_t * 1756 Parameter_getDerivedUnitDefinition(Parameter_t *p); 1757 1758 1759 /** 1760 * Predicate returning @c 1 (true) or @c 0 (false) depending on whether 1761 * all the required attributes for this Parameter_t structure 1762 * have been set. 1763 * 1764 * The required attributes for a Parameter_t structure are: 1765 * @li id (name in L1) 1766 * @li constant (in L3 only) 1767 * 1768 * @param p the Parameter_t structure to check. 1769 * 1770 * @return @c 1 (true) if all the required 1771 * attributes for this structure have been defined, @c 0 (false) otherwise. 1772 * 1773 * @memberof Parameter_t 1774 */ 1775 LIBSBML_EXTERN 1776 int 1777 Parameter_hasRequiredAttributes (Parameter_t *p); 1778 1779 1780 /** 1781 * Returns the Parameter_t structure having a given identifier. 1782 * 1783 * @param lo the ListOfParameters_t structure to search. 1784 * @param sid the "id" attribute value being sought. 1785 * 1786 * @return item in the @p lo ListOfParameters with the given @p sid or a 1787 * null pointer if no such item exists. 1788 * 1789 * @see ListOf_t 1790 * 1791 * @memberof ListOfParameters_t 1792 */ 1793 LIBSBML_EXTERN 1794 Parameter_t * 1795 ListOfParameters_getById (ListOf_t *lo, const char *sid); 1796 1797 1798 /** 1799 * Removes a Parameter_t structure based on its identifier. 1800 * 1801 * The caller owns the returned item and is responsible for deleting it. 1802 * 1803 * @param lo the list of Parameter_t structures to search. 1804 * @param sid the "id" attribute value of the structure to remove. 1805 * 1806 * @return The Parameter_t structure removed, or a null pointer if no such 1807 * item exists in @p lo. 1808 * 1809 * @see ListOf_t 1810 * 1811 * @memberof ListOfParameters_t 1812 */ 1813 LIBSBML_EXTERN 1814 Parameter_t * 1815 ListOfParameters_removeById (ListOf_t *lo, const char *sid); 1816 1817 1818 END_C_DECLS 1819 LIBSBML_CPP_NAMESPACE_END 1820 1821 #endif /* !SWIG */ 1822 #endif /* Parameter_h */ 1823 1824