Loading...
Searching...
No Matches
doc_set_id Class Reference

## Detailed Description

  The string `sid` is copied.

  The identifier given by an object's "id" attribute value is used to identify the object within the SBML model definition. Other objects can refer to the component using this identifier. The data type of "id" is always `SId` or a type derived from that, such as `UnitSId`, depending on the object in question. All data types are defined as follows:

           letter ::= 'a'..'z','A'..'Z'
           digit  ::= '0'..'9'
           idChar ::= letter | digit | '_'
           SId    ::= ( letter | '_' ) idChar*

  The characters `(` and `)` are used for grouping, the character `*` "zero or more times", and the character `|` indicates logical "or". The equality of SBML identifiers is determined by an exact character sequence match; i.e., comparisons must be performed in a case-sensitive manner. This applies to all uses of `SId`, `SIdRef`, and derived types.

Users need to be aware of some important API issues that are the result of the history of SBML and libSBML. Prior to SBML Level 3 Version 2, SBML defined "id" and "name" attributes on only a subset of SBML objects. To simplify the work of programmers, libSBML's API provided get, set, check, and unset on the SBase object class itself instead of on individual subobject classes. This made the get/set/etc. methods uniformly available on all objects in the libSBML API. LibSBML simply returned empty strings or otherwise did not act when the methods were applied to SBML objects that were not defined by the SBML specification to have "id" or "name" attributes. Additional complications arose with the rule and assignment objects: InitialAssignment, EventAssignment, AssignmentRule, and RateRule. In early versions of SBML, the rule object hierarchy was different, and in addition, then as now, they possess different attributes: "variable" (for the rules and event assignments), "symbol" (for initial assignments), or neither (for algebraic rules). Prior to SBML Level 3 Version 2, getId() would always return an empty string, and isSetId() would always return `false` for objects of these classes.

With the addition of "id" and "name" attributes on SBase in Level 3 Version 2, it became necessary to introduce a new way to interact with the attributes more consistently in libSBML to avoid breaking backward compatibility in the behavior of the original "id" methods. For this reason, libSBML provides four functions (getIdAttribute(), setIdAttribute( ), isSetIdAttribute(), and unsetIdAttribute()) that always act on the actual "id" attribute inherited from SBase, regardless of the object's type. These new methods should be used instead of the older getId()/setId()/etc. methods unless the old behavior is somehow necessary. Regardless of the Level and Version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an "id" attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write "id" attributes for those objects.

Parameters

  sid | the string to use as the identifier of this object.

Returns
  integer value indicating success/failure of the function. The possible values returned by this function are:
  - LIBSBML_OPERATION_SUCCESS
  - LIBSBML_INVALID_ATTRIBUTE_VALUE
  - LIBSBML_UNEXPECTED_ATTRIBUTE

See also
  getIdAttribute()
  setIdAttribute(const std::string& sid)
  isSetIdAttribute()
  unsetIdAttribute()