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

- libXpertMassCore
- CrossLink

# MsXpS::libXpertMassCore::CrossLink Class

class MsXpS::libXpertMassCore::CrossLink

The CrossLink class provides abstractions to work with a cross-link entity between Monomer instances. More...

Header: | `#include <CrossLink.hpp>`

- List of all members, including inherited members
- CrossLink is part of Aqueous chemical reactions.

## Public Functions

| CrossLink()
| CrossLink(MsXpS::libXpertMassCore::CrossLinkerCstSPtr cross_linker_csp, MsXpS::libXpertMassCore::PolymerCstQSPtr polymer_cqsp = nullptr, const QString &comment = QString())
| CrossLink(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, MsXpS::libXpertMassCore::PolymerCstQSPtr polymer_cqsp = nullptr, const QString &name = QString(), const QString &formula = QString(), const QString &comment = QString())
| CrossLink(const MsXpS::libXpertMassCore::CrossLink &other)
| ~CrossLink()
const MsXpS::libXpertMassCore::CrossLink & | accountMasses(double &mono, double &avg, int times = 1) const
QString | appendMonomer(MsXpS::libXpertMassCore::MonomerCstSPtr monomer_csp)
bool | calculateMasses(const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp, double &mono, double &avg) const
std::vector<std::size_t> | continuumOfLocationsOfInclusiveSequenceMonomers(MsXpS::libXpertMassCore::Enums::LocationType location_type) const
QString | continuumOfLocationsOfInclusiveSequenceMonomersAsText(MsXpS::libXpertMassCore::Enums::LocationType location_type) const
std::size_t | fillInMonomers(QString monomer_indices_text, bool &ok)
QString | formatContainerOfMonomerLocationsAsText(const std::vector<std::size_t> &locations) const
std::vector<QString> | getAllMonomerUuids() const
const QString & | getComment() const
const MsXpS::libXpertMassCore::CrossLinkerCstSPtr | getCrossLinkerCstSPtr() const
QString | getCrossLinkerName() const
MsXpS::libXpertMassCore::MonomerCstSPtr | getFirstMonomer() const
double | getMass(MsXpS::libXpertMassCore::Enums::MassType mass_type) const
MsXpS::libXpertMassCore::MonomerCstSPtr | getMonomerAt(std::size_t index)
MsXpS::libXpertMassCore::MonomerCstSPtr | getMonomerForUuid(const QString &uuid) const
const std::vector<MsXpS::libXpertMassCore::MonomerCstSPtr> & | getMonomersCstRef() const
std::vector<MsXpS::libXpertMassCore::MonomerCstSPtr> & | getMonomersRef()
MsXpS::libXpertMassCore::PolymerCstQSPtr | getPolymerCstSPtr() const
QString | getUuidForMonomer(const MsXpS::libXpertMassCore::MonomerCstSPtr &monomer_csp) const
bool | hasMonomer(const MsXpS::libXpertMassCore::MonomerCstSPtr &monomer_csp) const
bool | hasUuid(const MsXpS::libXpertMassCore::MonomerCstSPtr &monomer_csp) const
MsXpS::libXpertMassCore::Enums::CrossLinkEncompassed | isEncompassedByIndexRange(std::size_t start, std::size_t end, std::size_t &in_count, std::size_t &out_count) const
MsXpS::libXpertMassCore::Enums::CrossLinkEncompassed | isEncompassedByIndexRangeCollection(const MsXpS::libXpertMassCore::IndexRangeCollection &index_ranges, std::size_t &in_count, std::size_t &out_count) const
bool | isValid() const
std::vector<std::size_t> | locationsOfInvolvedSequenceMonomers(MsXpS::libXpertMassCore::Enums::LocationType location_type) const
QString | locationsOfInvolvedSequenceMonomersAsText(MsXpS::libXpertMassCore::Enums::LocationType location_type) const
std::vector<std::size_t> | locationsOfOnlyExtremeSequenceMonomers(MsXpS::libXpertMassCore::Enums::LocationType location_type) const
QString | locationsOfOnlyExtremeSequenceMonomersAsText(MsXpS::libXpertMassCore::Enums::LocationType location_type) const
std::size_t | monomerIndex(MsXpS::libXpertMassCore::MonomerCstRPtr monomer_crp, bool &ok) const
std::size_t | monomerIndex(MsXpS::libXpertMassCore::MonomerCstSPtr monomer_csp, bool &ok) const
QString | prepareResultsTxtString()
bool | removeMonomerAt(std::size_t index)
void | setComment(const QString &comment)
QString | storeMonomer(const MsXpS::libXpertMassCore::MonomerCstSPtr &monomer_csp)
QString | toString() const
bool | validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const
bool | operator!=(const MsXpS::libXpertMassCore::CrossLink &other) const
MsXpS::libXpertMassCore::CrossLink & | operator=(const MsXpS::libXpertMassCore::CrossLink &other)
bool | operator==(const MsXpS::libXpertMassCore::CrossLink &other) const

## Protected Variables

QString | m_comment
std::vector<MsXpS::libXpertMassCore::MonomerCstSPtr> | m_monomers
MsXpS::libXpertMassCore::CrossLinkerCstSPtr | mcsp_crossLinker
MsXpS::libXpertMassCore::PolymerCstQSPtr | mcsp_polymer

## Related Non-Members

| CrossLinkCstSPtr
| CrossLinkCstWPtr
| CrossLinkSPtr
| CrossLinkWPtr
| UuidCrossLinkCstWPtrPair
| UuidCrossLinkWPtrPair

## Detailed Description

The notion of a cross-link is that it is a chemical reaction that involves at least two monomers in a Polymer or in an Oligomer sequence.

Polymer sequences might contain more than one CrossLink and these are stored in a container.

## Member Function Documentation

### CrossLink::CrossLink()

Constructs a totally empty CrossLink instance

### CrossLink::CrossLink(MsXpS::libXpertMassCore::CrossLinkerCstSPtr cross_linker_csp, MsXpS::libXpertMassCore::PolymerCstQSPtr polymer_cqsp = nullptr, const QString &comment = QString())

Constructs a CrossLink instance

- cross_linker_csp: CrossLinker instance used to initialize this CrossLink.
- polymer_cqsp: the Polymer instance in which this CrossLink was formed
- comment: a comment that might be associated to this CrossLink

Note: Providing a nullptr for polymer_cqsp is fatal.

### CrossLink::CrossLink(MsXpS::libXpertMassCore::PolChemDefCstSPtr pol_chem_def_csp, MsXpS::libXpertMassCore::PolymerCstQSPtr polymer_cqsp = nullptr, const QString &name = QString(), const QString &formula = QString(), const QString &comment = QString())

Constructs a CrossLink instance

- pol_chem_def_csp: the polymer chemistry definition (PolChemDef).
- polymer_cqsp: the Polymer instance in which this CrossLink was formed.
- name: the name of this CrossLink instance.
- formula: the Formula that describes the reaction that is the basis of the chemical reaction leading to the formation of this CrossLink.
- comment: a comment that might be associated to this CrossLink.

Note: Providing a nullptr for polymer_cqsp is fatal.

### CrossLink::CrossLink(const MsXpS::libXpertMassCore::CrossLink &other)

Constructs a CrossLink instance as a copy of other.

### `[noexcept]` CrossLink::~CrossLink()

Destructs this CrossLink instance.

No entity needs to be destructed, since the Monomer instances in the list are not owned by this CrossLinker instance.

### const MsXpS::libXpertMassCore::CrossLink &CrossLink::accountMasses(double &mono, double &avg, int times = 1) const

Adds this CrossLinker's member masses to mono and avg, as compounded by the times factor.

Returns a reference to this CrossLink.

### QString CrossLink::appendMonomer(MsXpS::libXpertMassCore::MonomerCstSPtr monomer_csp)

Adds monomer_csp to the member container of Monomer instances and returns the matching QUuid value string.

### bool CrossLink::calculateMasses(const MsXpS::libXpertMassCore::IsotopicDataCstSPtr &isotopic_data_csp, double &mono, double &avg) const

Calculates the mass of the CrossLink as the mass of the CrossLinker.

Sets the calculated masses to mono and avg. If isotopic_data_csp, these reference data are used for the calculation, otherwise those in the PolChemDef referenced by the CrossLinker are used.

Returns true if the calculation could proceed without error.

### std::vector<std::size_t> CrossLink::continuumOfLocationsOfInclusiveSequenceMonomers(MsXpS::libXpertMassCore::Enums::LocationType location_type) const

Returns a container with all the locations of the Monomer instances involved in this CrossLink.

If location_type is Enums::LocationType::INDEX, the locations are numbered as indices. If location_type is Enums::LocationType::POSITION, the locations are numbered as positions (that is, index + 1).

For example, if the cross-link involves Monomer instances at indices 20, 45, 89, then the indices are this continuum of indices: {20;21;22;...;87;88;89}.

### QString CrossLink::continuumOfLocationsOfInclusiveSequenceMonomersAsText(MsXpS::libXpertMassCore::Enums::LocationType location_type) const

Returns a string containing a ';'-separated list of the locations of all the Monomer instances involved in this CrossLink.

If location_type is Enums::LocationType::INDEX, indices are formatted. If location_type is Enums::LocationType::POSITION, positions are formatted (that is, indices + 1).

For example, if the cross-link involves Monomer instances at indices 20, 45, 89, then the indices are this continuum of indices: "20;21;22;...;87;88;89".

### std::size_t CrossLink::fillInMonomers(QString monomer_indices_text, bool &ok)

Sets in the Monomer container, the Monomer instances occurring at the indices listed in monomer_indices_text.

monomer_indices_text contains a list of Monomer instance indices separated by ';' characters. The corresponding monomers (MonomerSPtr) found in the member Polymer's Sequence object are copied to the member list of Monomer instances as MonomerCstSPtr using the UuidMonomerCstWPtrPair-based logic. This process effectively documents a CrossLink in that member Polymer's Sequence.

If the process is successful, ok is set to true, otherwise it is set to false.

Returns the new size of the member container of Monomer instances.

### QString CrossLink::formatContainerOfMonomerLocationsAsText(const std::vector<std::size_t> &locations) const

Crafts and returns a string in the form ";<location>;<location>;" corresponding to the values stored in the locations container.

This function is used to format either Monomer indices or Monomer positions, which is why it has the neutral "locations" term in its name.

If the container is empty, an empty string is returned.

See also continuumOfLocationsOfInclusiveSequenceMonomers(), locationsOfOnlyExtremeSequenceMonomers(), and locationsOfOnlyExtremeSequenceMonomersAsText().

### std::vector<QString> CrossLink::getAllMonomerUuids() const

Returns a container of QString instances that correspond to the UUID strings that identify all the Monomer instances involved in this CrossLink.

If no Monomer is found, an empty container is returned.

### const QString &CrossLink::getComment() const

Returns the comment.

### const MsXpS::libXpertMassCore::CrossLinkerCstSPtr CrossLink::getCrossLinkerCstSPtr() const

Returns the member CrossLinker.

### QString CrossLink::getCrossLinkerName() const

Returns the name of the member CrossLinker.

### MsXpS::libXpertMassCore::MonomerCstSPtr CrossLink::getFirstMonomer() const

Returns the first Monomer instance in the member container of monomers. If the container is empty; returns nullptr.

### double CrossLink::getMass(MsXpS::libXpertMassCore::Enums::MassType mass_type) const

Returns the CrossLinker's mass of the type defined by mass_type.

### MsXpS::libXpertMassCore::MonomerCstSPtr CrossLink::getMonomerAt(std::size_t index)

Returns the Monomer at index in the member container of Monomer instances.

index cannot be out of bounds.

### MsXpS::libXpertMassCore::MonomerCstSPtr CrossLink::getMonomerForUuid(const QString &uuid) const

Returns the Monomer instance pointer in the member container that is associated to the uuid Uuid string.

If no such Monomer instance pointer is found, nullptr is returned.

### const std::vector<MsXpS::libXpertMassCore::MonomerCstSPtr> &CrossLink::getMonomersCstRef() const

Returns a const reference to the Monomer container.

### std::vector<MsXpS::libXpertMassCore::MonomerCstSPtr> &CrossLink::getMonomersRef()

Returns a reference to the Monomer container.

### MsXpS::libXpertMassCore::PolymerCstQSPtr CrossLink::getPolymerCstSPtr() const

Returns the Polymer instance in which this CrossLink has been formed.

### QString CrossLink::getUuidForMonomer(const MsXpS::libXpertMassCore::MonomerCstSPtr &monomer_csp) const

Returns the UUID string identifying monomer_csp in the member container.

If no such Monomer is found, an empty string is returned.

### bool CrossLink::hasMonomer(const MsXpS::libXpertMassCore::MonomerCstSPtr &monomer_csp) const

Returns true if monomer_csp was found in the member container of Monomer instances, false otherwise.

### bool CrossLink::hasUuid(const MsXpS::libXpertMassCore::MonomerCstSPtr &monomer_csp) const

Returns true if monomer_csp was found in the member container of Uuid-Monomer pairs, false otherwise.

### MsXpS::libXpertMassCore::Enums::CrossLinkEncompassed CrossLink::isEncompassedByIndexRange(std::size_t start, std::size_t end, std::size_t &in_count, std::size_t &out_count) const

Tells if this CrossLink instance is encompassed (partially or fully) or not at all by the Polymer sequence region defined by the [start - end ] Monomer index range.

In other words, this function tells if a given set of Monomers are involved in this CrossLink.

The count of monomers involved in this cross-link that:

- Are contained in the range is stored in in_count.
- Are not contained in the range is stored in out_count.

If all the monomers are listed as in_count, then this CrossLink is fully encompassed by the Polymer sequence region defined by the [start - end ] Monomer index range and Enums::CrossLinkEncompassed::FULLY is returned.

If all the monomers are listed as out_count, then this CrossLink is not at all encompassed by the Polymer sequence region and Enums::CrossLinkEncompassed::NOT is returned.

If both kinds of monomers were found, then Enums::CrossLinkEncompassed::PARTIALLY is returned.

### MsXpS::libXpertMassCore::Enums::CrossLinkEncompassed CrossLink::isEncompassedByIndexRangeCollection(const MsXpS::libXpertMassCore::IndexRangeCollection &index_ranges, std::size_t &in_count, std::size_t &out_count) const

Tells if this CrossLink instance is encompassed (partially or fully) or not at all by various IndexRange instances in the index_ranges IndexRangeCollection.

In other words, this function tells if a given set of Monomers are involved in this CrossLink. For examle, when index_ranges contains a single index range that resolves to a single Monomer index in the Sequence, this function simply says if the CrossLink involves that monomer.

The count of monomers involved in this cross-link that:

- Are contained in the regions defined in index_ranges is stored in in_count.
- Are not contained in the range is stored in out_count.

If all the monomers are listed as in_count, then this CrossLink is fully encompassed by the Polymer sequence regions defined in index_ranges and Enums::CrossLinkEncompassed::FULLY is returned.

If all the monomers are listed as out_count, then this CrossLink is not at all encompassed by the Polymer sequence region and Enums::CrossLinkEncompassed::NOT is returned.

If both kinds of monomers were found, then Enums::CrossLinkEncompassed::PARTIALLY is returned.

### bool CrossLink::isValid() const

Returns the validity status of the CrossLink.

### std::vector<std::size_t> CrossLink::locationsOfInvolvedSequenceMonomers(MsXpS::libXpertMassCore::Enums::LocationType location_type) const

Returns a container with the locations of the Monomer instances involved in this CrossLink.

If location_type is Enums::LocationType::INDEX, the locations are numbered as indices. If location_type is Enums::LocationType::POSITION, the locations are numbered as positions (that is, index + 1).

For example, if the cross-link involves Monomer instances at indices 20, 45, 89, then the returned indices are: {20;45;89}.

### QString CrossLink::locationsOfInvolvedSequenceMonomersAsText(MsXpS::libXpertMassCore::Enums::LocationType location_type) const

Returns a string containing a ';'-separated list of the locations of the Monomer instances involved in this CrossLink.

If location_type is Enums::LocationType::INDEX, indices are formatted. If location_type is Enums::LocationType::POSITION, positions are formatted (that is, indices + 1).

For example, if the cross-link involves Monomer instances at indices 20, 45, 89, then the returned indices are: "20;45;89".

### std::vector<std::size_t> CrossLink::locationsOfOnlyExtremeSequenceMonomers(MsXpS::libXpertMassCore::Enums::LocationType location_type) const

Returns a container with the locations of the two extreme Monomer instances involved in this CrossLink.

If location_type is Enums::LocationType::INDEX, the locations are numbered as indices. If location_type is Enums::LocationType::POSITION, the locations are numbered as positions (that is, index + 1).

For example, if the cross-link involves Monomer instances at indices 20, 45, 89, then the indices are this range of indices: [20–89].

### QString CrossLink::locationsOfOnlyExtremeSequenceMonomersAsText(MsXpS::libXpertMassCore::Enums::LocationType location_type) const

Returns a string containing a ';'-separated list of the locations of the two extreme Monomer instances involved in this CrossLink.

If location_type is Enums::LocationType::INDEX, indices are formatted. If location_type is Enums::LocationType::POSITION, positions are formatted (that is, indices + 1).

For example, if the cross-link involves Monomer instances at indices 20, 45, 89, then the indices are this range of indices: "20;89".

### std::size_t CrossLink::monomerIndex(MsXpS::libXpertMassCore::MonomerCstRPtr monomer_crp, bool &ok) const

Returns the index of monomer_crp as found in the container of Monomer instances.

monomer_crp is typically a Monomer found in the member Polymer for which this function establishes if it is involved in this CrossLink.

If monomer_crp is not found, ok is set to false and 0 is returned, otherwise ok is set to true and the index of the found Monomer is returned.

### std::size_t CrossLink::monomerIndex(MsXpS::libXpertMassCore::MonomerCstSPtr monomer_csp, bool &ok) const

Returns the index of monomer_csp as found in the member container of Monomer instances.

monomer_csp is typically a Monomer found in the member Polymer for which this function establishes if it is involved in this CrossLink.

If monomer_csp is not found, ok is set to false and 0 is returned, otherwise ok is set to true and the index of the found Monomer is returned.

### QString CrossLink::prepareResultsTxtString()

Returns an allocated string describing this CrossLink instance.

### bool CrossLink::removeMonomerAt(std::size_t index)

Removes the Monomer at index in the member container of Monomer instances.

index cannot be out of bounds.

Returns true if a Monomer was indeed removed, false otherwise.

### void CrossLink::setComment(const QString &comment)

Sets the comment.

### QString CrossLink::storeMonomer(const MsXpS::libXpertMassCore::MonomerCstSPtr &monomer_csp)

Stores the Monomer instance monomer_csp pointer in the member container.

The monomer_csp is stored as is, without duplication.

Returns the Uuid string associated to the stored Monomer.

### QString CrossLink::toString() const

Returns a text string describing this CrossLink instance.

### bool CrossLink::validate(MsXpS::libXpertMassCore::ErrorList *error_list_p) const

Returns true if this CrossLink instance validates successfully, false otherwise.

The validation is successful if:

- The count of Monomer instances listed in the member list is > 1.
- The member Polymer instance exists.
- The count of Monomer instances listed in the member list is equal to the number of Modif instance in the CrossLinker base class.
- If the list of Modif instances in the CrossLinker base class is not empty, there must be a colinearity between the order in which these instances are listed and the order in which the Monomer instances are listed in the member list. The monomer instance must be a target of the modification.

Errors are reported as messages in error_list_p.

### bool CrossLink::operator!=(const MsXpS::libXpertMassCore::CrossLink &other) const

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

Returns the negated result of operator==(other);

### MsXpS::libXpertMassCore::CrossLink &CrossLink::operator=(const MsXpS::libXpertMassCore::CrossLink &other)

Assigns other to this CrossLink instance.

After having set the member data, this CrossLink instance is validated and the result is set to m_isValid.

Returns a reference to this CrossLink instance.

### bool CrossLink::operator==(const MsXpS::libXpertMassCore::CrossLink &other) const

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

The monomers are compared deeply (non on the basis of the pointer value).

## Member Variable Documentation

### QString CrossLink::m_comment

This variable holds the comment that might be associated to this CrossLink.

### std::vector<MsXpS::libXpertMassCore::MonomerCstSPtr> CrossLink::m_monomers

This variable holds the container of Monomer instances that are involved in the formation of this CrossLink.

The Monomer pointers stored in the m_monomers member are MonomerCstSPtr that point to MonomerSPtr items stored in the Polymer's Sequence's vector of of MonomerSPtr (authorized implicit to-const cast).

Because it is not possible to perform the to-non-const back-cast, when needed to access the Sequence's MonomerSPtr, the search is performed by providing the Monomer raw pointer managed by the MonomerSPtr in m_monomers.

The reason why the CrossLink stores the involved Monomer instances as pointers to these very Monomer instances in the polymer sequence is that in this way, even if the sequence is edited, the cross-link does not loose the relation to the monomers. The only way that the sequence editing modifies a CrossLink instance is by removing at least one Monomer instance involved in the CrossLink. If that occurs, the CrossLink is informed and it is destructed.

### MsXpS::libXpertMassCore::CrossLinkerCstSPtr CrossLink::mcsp_crossLinker

This variable holds the CrossLinker instance defining the chemistry of this CrossLink.

### MsXpS::libXpertMassCore::PolymerCstQSPtr CrossLink::mcsp_polymer

This variable holds the Polymer instance of which this CrossLink is part.

## Related Non-Members

### CrossLinkCstSPtr

Synonym for std::shared_ptr<const CrossLink>.

### CrossLinkCstWPtr

Synonym for std::weak_ptr<const CrossLink>.

### CrossLinkSPtr

Synonym for std::shared_ptr<CrossLink>.

### CrossLinkWPtr

Synonym for std::weak_ptr<CrossLink>.

### `[alias]` UuidCrossLinkCstWPtrPair

Synonym for std::pair<QString, CrossLinkCstWPtr>.

### `[alias]` UuidCrossLinkWPtrPair

Synonym for std::pair<QString, CrossLinkWPtr>.

These pairs are used to store a unique identifier (Uuid) string related to a std::shared_ptr<CrossLink> type. This kind of pair is used in a container in the Polymer class. The fact that the std::shared_ptr is converted to a std::weak_ptr is interesting because the item in the pair will not increase the reference count.