| <large>libXpertMassCore and libXpertMassGui Developer Documentation</large>

- libXpertMassCore
- Formula

# MsXpS::libXpertMassCore::Formula Class

class MsXpS::libXpertMassCore::Formula

The Formula class provides sophisticated abstractions to work with formulas. More...

Header: | `#include <MsXpS/libXpertMassCore/Formula.hpp>`
Inherits: | QObject

- List of all members, including inherited members
- Formula is part of Polymer chemistry building blocks.

## Public Types

enum class | SplitResult { NOT_SET, FAILURE, HAS_PLUS_COMPONENT, HAS_MINUS_COMPONENT, HAS_BOTH_COMPONENTS }

## Properties

- actionFormula : QString
- isValid : const bool
- title : QString

## Public Functions

| Formula(QObject *parent = nullptr)
| Formula(const QString &formula_string, QObject *parent = nullptr)
| Formula(const QDomElement &element, int version = 1, QObject *parent = nullptr)
| Formula(const MsXpS::libXpertMassCore::Formula &other, QObject *parent = nullptr)
virtual | ~Formula()
std::size_t | accountFormula(const QString &formula_string, MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double times, bool &ok)
MsXpS::libXpertMassCore::Formula & | accountMasses(bool &ok, MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double &mono, double &avg, double times = 1)
double | accountSymbolCountPair(const QString &symbol, double count = 1)
double | accountSymbolCountPair(std::map<QString, double> &symbol_count_map, const QString &symbol, double count = 1) const
bool | accountSymbolCounts(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, int times)
QChar | actions() const
bool | appendActionFormula(const QString &action_formula)
bool | checkSyntax() const
void | clear()
MsXpS::libXpertMassCore::Formula * | clone(const MsXpS::libXpertMassCore::Formula &other, QObject *parent = nullptr)
QString | elementalComposition(std::vector<std::pair<QString, double>> *symbol_count_pairs_p = nullptr) const
QString | extractTitle() const
QString | formatXmlFormulaElement(int offset, const QString &indent = Utils::xmlIndentationToken)
QString | getActionFormula(bool with_title = false) const
QString | getMinusFormula() const
QString | getPlusFormula() const
const std::map<QString, double> & | getSymbolCountMapCstRef() const
QString | getTitle() const
bool | hasNetMinusPart()
MsXpS::libXpertMassCore::Formula & | initialize(const MsXpS::libXpertMassCore::Formula &other)
virtual bool | isValid() const
int | removeSpaces()
QString | removeTitle()
bool | renderXmlFormulaElement(const QDomElement &element, int version = 1)
void | roundIndices()
void | setActionFormula(const MsXpS::libXpertMassCore::Formula &formula)
void | setActionFormula(const QString &formula)
void | setTitle(const QString &title)
MsXpS::libXpertMassCore::Formula::SplitResult | splitActionParts(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double times = 1, bool store = false, bool reset = false)
MsXpS::libXpertMassCore::Formula::SplitResult | splitActionParts(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, QString &plus_formula, QString &minus_formula, std::map<QString, double> &symbol_count_map, double times = 1, bool store = false, bool reset = false) const
double | symbolCount(const QString &symbol) const
double | totalAtoms() const
double | totalIsotopes(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp) const
virtual bool | validate(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, MsXpS::libXpertMassCore::ErrorList *error_list_p) const
virtual bool | validate(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, bool store, bool reset, MsXpS::libXpertMassCore::ErrorList *error_list_p)
virtual bool | operator!=(const MsXpS::libXpertMassCore::Formula &other) const
virtual MsXpS::libXpertMassCore::Formula & | operator=(const MsXpS::libXpertMassCore::Formula &other)
virtual bool | operator==(const MsXpS::libXpertMassCore::Formula &other) const

## Signals

void | actionFormulaChanged()
void | titleChanged()
void | validChanged()

## Static Public Members

MsXpS::libXpertMassCore::Formula & | accountMasses(MsXpS::libXpertMassCore::Formula &formula, bool &ok, MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double &mono, double &avg, double times = 1)
QChar | actions(const QString &formula)
bool | checkSyntax(const QString &formula_string)

## Protected Variables

QString | m_actionFormula
bool | m_isValid
QString | m_minusFormula
QString | m_plusFormula
std::map<QString, double> | m_symbolCountMap
QString | m_title

## Detailed Description

There are two peculiarities with this Formula implementation:

- The Actionformula
- The Title

The action-formula: the main textual element in this Formula class is the action-formula (member m_actionFormula). A formula is the description of the atomic composition of a compound. For example, the string C2H6 is a formula.

While the previous C2H6 example describes a static chemical object, a Formula can also describe a dynamic chemical event, like a reaction, by describing what chemical entities are gained by the molecule during the chemical reaction (entering group notion, the "plus" component of the action-formula) and what chemical entities are lost by the molecule (leaving group notion, the "minus" component).

For example, an acetylation reaction can be described by the loss of H2O with gain of CH3COOH. The net chemical gain on the molecule will be CH3CO. In this example, one would thus define an action-formula in the following way: -H2O+CH3COOH. The "minus" formula associated with the '-' action accounts for the leaving group of the reaction, while the "plus" formula associated with the '+' action accounts for the entering group of the reaction. Note that there is no limitation on the amount of such actions, as one could have an action-formula like this -H+CO2-H2O+C2H6.

An action-formula does not need to have any action sign (+ or -), and if it has no sign, the action-formula is a plus-signed formula by default, which is what the reader would expect for a standard formula.

The title: the action-formula may be documented with a title: a prefix text enclosed in double quotes, like the following:

`"Decomposed adenine" C5H4N5 +H`.

This documentation element is called the title. Note that the presence of a title in a formula does not change anything to its workings as long as the title is effectively enclosed in double quotes. The title is by no means required for an action-formula to work correctly. It is, however, highly recommended in a number of situations where the user wants to easily document the reaction the action-formula is describing, like when setting an action-formula for a Modif instance, for example, or when defining the chemical macros for use in the XpertCalc module of MassXpert.

An action-formula behaves exactly the same as a simple formula from an end user perspective. Behind the scenes, Formula methods are called to separate all the '+'-associated formulas from all the '-'-associated formulas so that masses are correctly associated to each "leaving" or "entering" chemical groups. Formulas that are '-'-associated are stored in the so-called "minus formula", while '+'-associated ones are stored in the "plus formula". Note that all the formulas in Formula are QString objects.

Note: All the chemical action-formula elements that together form the entering group (that is the '+'-associated formulas) and all the chemical elements that together form the leaving group (that is the '-'-associated formulas) belong to two different sets of action-formula compoments: the sub-formulas.

Upon parsing of the action-formula, the m_minusFormula and the m_plusFormula members are populated with formulas. For the -H+CO2-H2O+C2H6 action-formula, the two "sub-formulas" would be extracted from it:

- The "minus sub-formula" would contain "HH2O"
- The "plus sub-formula" would contain "CO2C2H6"

Both of these sub-formulas are used to compute the actual net formula and the resulting net mass of the action-formula.

A Formula is isotopic-abundance-agnostic by itself and does not require any kind of isotopic data to be created. However, a Formula always needs an isotopic data set (IsotopicData) to perform validation and mass calculations. The validation of the action-formula requires an isotopic data set because this is where chemical element symbols are defined along with the corresponding isotopic mass/abundance pairs for it. For the same reason, the calculation of the mass corresponding to a Formula requires an isotopic data set.

Note: A Formula is considered invalid (m_isValid is false) at construction time and during all of its operations until the actual validation has been performed against isotopic data.

Only when all the relevant data have been set and the Formula is validated explicitely (validate()), the user of the Formula gets to know it is valid or not.

Note: One feature of interest of Formula is the fact that the elemental composition supports double atom indices, not only integer values. This is of use when working with Averagine.

## Member Type Documentation

### enum class Formula::SplitResult

This enum type specifies the result of an action-formula parsing process:

Constant | Value | Description
--- | --- | ---
`MsXpS::libXpertMassCore::Formula::SplitResult::NOT_SET` | `0x0000` | The value was not set
`MsXpS::libXpertMassCore::Formula::SplitResult::FAILURE` | `1 << 0` | The splitting work failed
`MsXpS::libXpertMassCore::Formula::SplitResult::HAS_PLUS_COMPONENT` | `1 << 1` | The action-formula has a plus component
`MsXpS::libXpertMassCore::Formula::SplitResult::HAS_MINUS_COMPONENT` | `1 << 2` | The action-formula has a minus component
`MsXpS::libXpertMassCore::Formula::SplitResult::HAS_BOTH_COMPONENTS` | `(HAS_PLUS_COMPONENT | HAS_MINUS_COMPONENT)` | The action-formula has both plus and minus components

## Property Documentation

### actionFormula : QString

String representing the action-formula.

Access functions:

QString | getActionFormula(bool with_title = false) const | [see note below]
void | setActionFormula(const QString &formula) | [see note below]
void | setActionFormula(const MsXpS::libXpertMassCore::Formula &formula) | [see note below]

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Notifier signal:

void | actionFormulaChanged()

### `[read-only]` isValid : const bool

This property holds the status of the formula.

Access functions:

virtual bool | isValid() const

Notifier signal:

void | validChanged()

### title : QString

String representing the title of the action-formula.

The title is the descriptive string in double quotes that is associated to a formula, like this:

`"Acetylation"-H2O+CH3COOH`

Access functions:

QString | getTitle() const | [see note below]
void | setTitle(const QString &title) | [see note below]

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Notifier signal:

void | titleChanged()

## Member Function Documentation

### `[explicit invokable]` Formula::Formula(QObject *parent = nullptr)

Constructs an uninitialized Formula instance, with parentship set to parent.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[explicit invokable]` Formula::Formula(const QString &formula_string, QObject *parent = nullptr)

Constructs a formula initialized with the formula_string action-formula string, with parentship set to parent.

formula_string does not need to be an action-formula, but it might be an action-formula. This formula gets copied into the m_actionFormula without any processing afterwards.

formula_string might hold a title, as detailed in the Formula class description.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also getTitle(), extractTitle(), and removeTitle().

### `[explicit]` Formula::Formula(const QDomElement &element, int version = 1, QObject *parent = nullptr)

Constructs a Formula instance using the XML element according to the version, with parentship set to parent.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

See also renderXmlFormulaElement().

### `[explicit]` Formula::Formula(const MsXpS::libXpertMassCore::Formula &other, QObject *parent = nullptr)

Constructs a Formula as a copy of other, setting parentship to parent.

The copy is deep with all the data copied from other to this Formula instance. There is no processing afterwards.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

### `[virtual noexcept]` Formula::~Formula()

Destructs this Formula.

### std::size_t Formula::accountFormula(const QString &formula_string, MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double times, bool &ok)

Accounts formula_string into this Formula using isotopic_data_csp as reference isotopic data with times as a compounding factor. The result of the operation is set to ok.

formula_string is converted into a temporary Formula instance and processed according to these steps:

- First validate() is called on the temporary Formula, with storage of the symbol/count data;
- The symbol/count data thus generated is used to update the member m_symbolCountMap map.
- The m_actionFormula is set to the result of elementalComposition().

Returns the size of the member m_symbolCountMap symbol/count map.

### MsXpS::libXpertMassCore::Formula &Formula::accountMasses(bool &ok, MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double &mono, double &avg, double times = 1)

Accounts this formula's monoisotopic and average masses into mono and avg, using times as a compounding factor.

The masses corresponding to the member m_actionFormula are calculated first and then the mono and avg parameters are updated by incrementing their value with the calculated values. This incrementation might be compounded by the times factor.

The masses of the member m_actionFormula are computed using data from isotopic_data_csp.

Sets ok to false if the calculation failed, to true otherwise.

Returns a reference to this Formula instance.

See also splitActionParts().

### `[static]` MsXpS::libXpertMassCore::Formula &Formula::accountMasses(MsXpS::libXpertMassCore::Formula &formula, bool &ok, MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double &mono, double &avg, double times = 1)

Accounts formula monoisotopic and average masses into mono and avg, using times as a compounding factor.

The masses corresponding to the formula are first calculated using isotopic_data_csp and then the mono and avg parameters are updated by incrementing their value with the calculated values. This incrementation might be compounded by that times factor.

Sets ok to false if the calculation failed, to true otherwise.

Returns a reference to this Formula instance.

See also splitActionParts().

### double Formula::accountSymbolCountPair(const QString &symbol, double count = 1)

Accounts for symbol and corresponding count in the member map.

The m_symbolCountMap relates each atom (chemical element) symbol with its occurrence count as encountered while parsing the member action-formula.

If the symbol was not encountered yet, a new key/value pair is created. Otherwise, the count value is updated.

Returns the new count status for symbol.

### double Formula::accountSymbolCountPair(std::map<QString, double> &symbol_count_map, const QString &symbol, double count = 1) const

Accounts for symbol and corresponding count in the symbol_count_map map.

symbol_count_map relates each atom (chemical element symbol) with its occurrence count.

If the symbol was not encountered yet, a new symbol/count pair is created. Otherwise, the pair's count value is updated with count.

Returns the updated count value for symbol.

### bool Formula::accountSymbolCounts(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, int times)

Accounts this Formula's action-formula (m_actionFormula) in the member m_symbolCountMap symbol/count container.

Calls splitActionParts() to actually parse m_actionFormula and account its components to m_symbolCountMap. The accounting of the symbol/count pair can be compounded by the times factor.

While splitting the plus and minus sub-formulas of the m_actionFormula, their validity is checked against the reference isotopic data isotopic_data_csp.

This function is used when sequentially accounting many different formulas into the symbol/count map: the member m_actionFormula is set to a new formula string and this function is called again without resetting the symbol/count map, effectively adding formulas onto formulas sequentially.

Returns true if no error was encountered, false otherwise.

See also splitActionParts().

### `[invokable]` QChar Formula::actions() const

Calls actions(const QString &formula) on this Formula's member m_actionFormula. Returns '+' if it only contains "plus" elements or '-' if at least one "minus" element was found.

If m_actionFormula contains no sign at all, then it is considered to contain only '+' elements and the function returns '+'. If at least one element is found associated to a '-', then the "minus" action prevails and the function returns '-'.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also actions(const QString &formula) and splitActionParts().

### `[static invokable]` QChar Formula::actions(const QString &formula)

Returns '+' if formula only contains "plus" elements or '-' if at least one "minus" element was found.

If formula contains no sign at all, then it is considered to contain only '+' elements and the function returns '+'. If at least one element is found associated to a '-', then the "minus" action prevails and the function returns '-'.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also actions() and splitActionParts().

### `[invokable]` bool Formula::appendActionFormula(const QString &action_formula)

Appends action_formula to this Formula's member m_actionFormula.

The action_formula string is first stripped of its whitespace with QString::simplified(). Then it is appended to m_actionFormula only if:

- It is not empty (if empty the function does nothing and returns false)
- It passes the checkSyntax() test (if not, the function does nothing and returns false)

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

The function returns false if nothing was changed and true if something was actually appended to m_actionFormula.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[invokable]` bool Formula::checkSyntax() const

Returns true if the member action-formula is syntactically valid, false otherwise.

The formula is first stripped of its title (if any), then all the spaces are removed.

MsXpS::libXpertMassCore::Formula::subFormulaRegExp is then used to extract each "plus" and / or "minus" component while checking its syntactic validity.

Note: The syntax checking code does not verify that the action-formula is chemically valid, that is, the "Cz4" symbol / count pair would check even if the Cz chemical element does not exist.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also checkSyntax(const QString &formula_string).

### `[static invokable]` bool Formula::checkSyntax(const QString &formula_string)

Returns true if the formula_string action-formula is syntactically valid, false otherwise.

The formula is first stripped of its title (if any), then all the spaces are removed.

MsXpS::libXpertMassCore::Utils::subFormulaRegExp is then used to extract the "plus" and "minus" sub-formulas while checking their syntactic validity.

Note: The formula syntax check is purely syntactical and cannot be chemical because there are no IsotopicData to challenge its chemical validity with. This means, for example, that "Cz4" would check positively, although chemically this is not a valid formula because the Cz chemical element does not exist.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also validate().

### void Formula::clear()

Clears all the formula member data and set m_isValid to false.

### `[invokable]` MsXpS::libXpertMassCore::Formula *Formula::clone(const MsXpS::libXpertMassCore::Formula &other, QObject *parent = nullptr)

Returns a new heap-allocated Formula that is initialized using other, setting parentship to parent.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[invokable]` QString Formula::elementalComposition(std::vector<std::pair<QString, double>> *symbol_count_pairs_p = nullptr) const

Returns a formula matching the contents of the member m_symbolCountMap symbol/count map.

The returned formula is formatted according to the IUPAC convention about the ordering of the chemical elements: CxxHxxNxxOxxSxxPxx.

The "plus" sub-formula components are output first and the "minus" sub-formula ones after.

If symbol_count_pairs_p is not nullptr, each symbol/count pair is added to it.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[invokable]` QString Formula::extractTitle() const

Returns the title from the member action-formula.

The title of a formula is the string, enclosed in double quotes, that is located in front of the actual chemical action-formula. This function removes that title string from the member action-formula using a QRegularExpression.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[invokable]` QString Formula::formatXmlFormulaElement(int offset, const QString &indent = Utils::xmlIndentationToken)

Returns a string containing a Formula XML element documenting this Formula instance.

offset and indent define the formatting of the XML element.

A typical XML element looks like this:

    <formula>-H2O+CH3COOH</formula>

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also renderXmlFormulaElement().

### `[invokable]` QString Formula::getActionFormula(bool with_title = false) const

Returns the member m_actionFormula action-formula, along with the title if with_title is true.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Note: Getter function for property actionFormula.

### `[invokable]` QString Formula::getMinusFormula() const

Returns the m_minusFormula formula.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[invokable]` QString Formula::getPlusFormula() const

Returns the m_plusFormula formula.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### const std::map<QString, double> &Formula::getSymbolCountMapCstRef() const

Returns a const reference to the member m_symbolCountMap.

### `[invokable]` QString Formula::getTitle() const

Returns the "title" leading component of a formula.

A fully selfdescribed formula might look like this:

"Acetylation"+CH3COOH-H2O

The first string between quotes is called the title.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Note: Getter function for property title.

### `[invokable]` bool Formula::hasNetMinusPart()

Returns true if the member m_minusFormula is not empty, false otherwise.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[invokable]` MsXpS::libXpertMassCore::Formula &Formula::initialize(const MsXpS::libXpertMassCore::Formula &other)

Assigns other to this Formula instance and returns a reference to this instance.

Parentship is not modified.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[virtual]` bool Formula::isValid() const

Returns the status of the formula, that is, the result of validate().

Note: Getter function for property isValid.

### int Formula::removeSpaces()

Removes all the space characters from the member action-formula.

Spaces can be placed anywhere in formula for more readability. However, it might be required that these character spaces be removed. This function does just this, using a QRegularExpression.

Note: The Formula title is not stored in the action-formula member m_actionFormula (but in m_title) and the spaces it contains are not touched.

Returns the number of removed characters.

### `[invokable]` QString Formula::removeTitle()

Removes the title from m_actionFormula and returns it.

The title of a formula is the string, enclosed in double quotes, that is located in front of the actual chemical action-formula. This function removes that title string from the member action-formula using a QRegularExpression.

The caller may use the returned title string to set it to m_title.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also Formula::extractTitle() and Formula::setTitle().

### bool Formula::renderXmlFormulaElement(const QDomElement &element, int version = 1)

Parses a Formula XML element according to version and sets the data to the member m_actionFormula, checking it syntax.

Returns true if the XML element parsing was without error and if the syntax check was successful, false otherwise.

See also checkSyntax() and formatXmlFormulaElement().

### void Formula::roundIndices()

Converts this Formula instance's atomic symbol indices to integers.

This function returns immediately if a call to isValid() returns false.

### `[invokable]` void Formula::setActionFormula(const MsXpS::libXpertMassCore::Formula &formula)

Copies formula's action-formula to the member m_actionFormula of this Formula instance.

No other processing is performed afterwards.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Note: Setter function for property actionFormula.

### `[invokable]` void Formula::setActionFormula(const QString &formula)

Copies formula to the member m_actionFormula of this Formula instance.

No other processing is performed afterwards.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Note: Setter function for property actionFormula.

### `[invokable]` void Formula::setTitle(const QString &title)

Sets the title leading component of a formula to title.

A fully self-described formula might look like this:

"Acetylation" +CH3COOH-H2O

The first string between double quotes is called the title.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Note: Setter function for property title.

### MsXpS::libXpertMassCore::Formula::SplitResult Formula::splitActionParts(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, double times = 1, bool store = false, bool reset = false)

Tells the "plus" ('+') and "minus" ('-') sub-formulas in the member action-formula.

Parses the m_actionFormula action-formula and separates all the minus components of that action-formula from all the plus components. The different sub-formulas are set to their corresponding member (m_minusFormula and m_plusFormula).

This function delegate its work to the other splitActionParts() passing m_plusFormula, m_minusFormula, and m_symbolCountMap as parameters such that this function modifies the contents of this Formula instance.

In all the computations above, reference isotopic data are accessed at isotopic_data_csp. If times is not 1, then that value is used to compound the results of the computations. If store is true, then the results of the computations are stored in this object. If reset is true, then the intermediate computation values and objects are reset.

Returns a Formula::SplitResult result documenting the outcome of the operation.

### MsXpS::libXpertMassCore::Formula::SplitResult Formula::splitActionParts(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, QString &plus_formula, QString &minus_formula, std::map<QString, double> &symbol_count_map, double times = 1, bool store = false, bool reset = false) const

Tells the "plus" ('+') and "minus" ('-') sub-formulas in the member action-formula.

Parses the m_actionFormula action-formula and separates all the minus components of that action-formula from all the plus components. The two sub-fomulas are set to plus_formula and minus_formula.

At the end of the split work, each sub-formula (plus_formula and minus_formula) is actually parsed for validity, using the isotopic_data_csp IsotopicData as reference.

If times is not 1, then the accounting of the plus/minus sub-formulas is compounded by this factor.

If store is true, the symbol/count data obtained while parsing of the plus/minus sub-formulas are stored in symbol_count_map.

If reset is true, the symbol/count data in symbol_count_map are reset before the parsing operation. Setting this parameter to false may be useful if the caller needs to "accumulate" the sequential accounting of multiple formulas.

The parsing of the action-formula is performed by performing its deconstruction using Utils::subFormulaRegExp.

Returns a SplitResult value detailing the outcome of the operation.

Because this function does not modify member data, only writing results to the passed variables, it is declared const.

If this function completes successfully, then that validates it successfully (syntax ok, and symbols known to the reference isotopic data), and m_isValid is set to true, otherwise m_isValid is set to false.

### double Formula::symbolCount(const QString &symbol) const

Returns the count value associated with key symbol in the member m_symbolCountMap symbol/count member map.

### double Formula::totalAtoms() const

Returns the total count of symbols (atoms) in this formula.

The determination is performed by summing up all the count values for all the symbols in the member m_symbolCountMap symbol/count pairs map.

### double Formula::totalIsotopes(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp) const

Returns the total count of isotopes in this formula using isotopic_data_csp as the reference isotopic data.

The determination is performed by summing up all the isotope counts for all the symbols keys in the member symbol / count map m_symbolCountMap.

### `[virtual]` bool Formula::validate(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Returns true if the formula validates successfully, false otherwise.

The validation uses the isotopic_data_csp reference data (that cannot be nullptr) and involves:

- Checking that the member action-formula is not empty and has a proper syntax. Returns false otherwise;
- Splitting the action-formula into plus and a minus sub-formulas using splitActionParts()). If that step fails, returns false;
- Verifying that both the plus and the minus formulas are not empty. Returns false otherwise.

If errors are encountered, meaningful messages are stored in error_list_p (is not nullptr and that is not cleared).

Note: This function is declared const because it does not modify this Formula instance.

If the validation is successful, m_isValid is set to true, otherwise it is set to false.

See also validate(IsotopicDataCstSPtr isotopic_data_csp, bool store, bool reset, ErrorList *error_list_p).

### `[virtual]` bool Formula::validate(MsXpS::libXpertMassCore::IsotopicDataCstSPtr isotopic_data_csp, bool store, bool reset, MsXpS::libXpertMassCore::ErrorList *error_list_p)

Returns true if the formula validates successfully, false otherwise.

The validation uses the isotopic_data_csp reference data (that cannot be nullptr) and involves:

- Checking that the member action-formula is not empty and has a proper syntax. Returns false otherwise;
- Splitting the action-formula into plus and a minus sub-formulas using splitActionParts()). If that step fails, returns false;
- Verifying that both the plus and the minus formulas are not empty. Returns false otherwise.

If errors are encountered, meaningful messages are stored in error_list_p (is not nullptr and that is not cleared).

Member data are updated during the operations.

If the validation is successful, m_isValid is set to true, otherwise it is set to false.

See also validate(IsotopicDataCstSPtr isotopic_data_csp, ErrorList *error_list_p) const.

### `[virtual]` bool Formula::operator!=(const MsXpS::libXpertMassCore::Formula &other) const

Returns true if this Formula and other are different, false otherwise.

Returns the negated result of operator==().

See also operator==().

### `[virtual]` MsXpS::libXpertMassCore::Formula &Formula::operator=(const MsXpS::libXpertMassCore::Formula &other)

Assigns other to this Formula instance and returns a reference to this instance.

The copy is deep with all the data from other being copied into this formula.

Because no validation is performed with reference isotopic data, the m_isValid validity status of the Formula is false.

### `[virtual]` bool Formula::operator==(const MsXpS::libXpertMassCore::Formula &other) const

Returns true if this Formula and other are identical, false otherwise.

The comparison is only performed on the title and action-formula, not on any other member data that actually derive from the processing of the action-formula.

See also operator!=().

## Member Variable Documentation

### QString Formula::m_actionFormula

String representing the action-formula.

### bool Formula::m_isValid

This variable holds the status of the formula.

### QString Formula::m_minusFormula

String representing the "minus" component of the main m_minusFormula.

This member datum is set upon parsing of m_actionFormula.

### QString Formula::m_plusFormula

String representing the "plus" component of the main m_actionFormula.

This member datum is set upon parsing of m_actionFormula.

### std::map<QString, double> Formula::m_symbolCountMap

Map relating the symbols (as keys) found in the formula and their counts (atoms, in fact, as values).

Note that the count value type is double, which allows for interesting things to be done with Formula. Also, the count value might be negative if the net mass of an action-formula is negative.

See also Formula::splitActionParts().

### QString Formula::m_title

String representing the title of the action-formula.

The title is the descriptive string in double quotes that is associated to a formula, like this:

`"Acetylation"-H2O+CH3COOH`