externals/linux/include/OnixS/FIXEngine/FIX/FieldSet.h

/*
* Copyright Onix Solutions Limited [OnixS]. All rights reserved.
*
* This software owned by Onix Solutions Limited [OnixS] and is protected by copyright law
* and international copyright treaties.
*
* Access to and use of the software is governed by the terms of the applicable OnixS Software
* Services Agreement (the Agreement) and Customer end user license agreements granting
* a non-assignable, non-transferable and non-exclusive license to use the software
* for it's own data processing purposes under the terms defined in the Agreement.
*
* Except as otherwise granted within the terms of the Agreement, copying or reproduction of any part
* of this source code or associated reference material to any other location for further reproduction
* or redistribution, and any amendments to this copyright notice, are expressly prohibited.
*
* Any reproduction or redistribution for sale or hiring of the Software not in accordance with
* the terms of the Agreement is a violation of copyright law.
*/

#pragma once

#include <vector>
#include <iterator>

#include <OnixS/FIXEngine/Compiler.h>
#include <OnixS/FIXEngine/FIX/Tag.h>
#include <OnixS/FIXEngine/FIX/FieldValueRef.h>

namespace OnixS {
namespace FIX {
ONIXS_FIXENGINE_API_DECL(class, Group);
ONIXS_FIXENGINE_API_DECL(class, Message);

/// Field primary attributes (the tag and a reference to a value).
struct ONIXS_FIXENGINE_API Field {
    /// The field tag.
    Tag tag;

    /// The field value reference.
    FieldValueRef value;

    /// Initializes the field which refers to nothing.
    Field()
        : tag(0) {
    }

    /// Initializes all members.
    Field(
        Tag fieldTag,
        const FieldValueRef & fieldValue)
        : tag(fieldTag), value(fieldValue) {
    }
};

/// The ordered collection of fields.
typedef
std::vector<Field>
Fields;

/// Encapsulates primary operations over the collection of FIX
/// fields like a FIX message and a repeating group instance are.
class ONIXS_FIXENGINE_API FieldSet
{
public:
    /// Indicates whether an instance refers to a valid set of fields.
    ///
    /// If the given instance doesn't refer to a valid fields set,
    /// none of other members must be used.
    bool valid() const;

    /// Returns 'true' if the field-set contains the
    /// field with the given tag, otherwise - 'false'.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    bool contain(Tag tag) const;

    /// Returns a reference to the given field value.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    FieldValueRef get(Tag tag) const;

    /// Returns a field value as an OnixS::FIX::Char value.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    Char getChar(Tag tag) const;

    /// Returns a field value as an OnixS::FIX::Int32 value.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    Int32 getInt32(Tag tag) const;

    /// Returns a field value as an OnixS::FIX::UInt32 value.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    UInt32 getUInt32(Tag tag) const;

    /// Returns a field value as an OnixS::FIX::Int64 value.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    Int64 getInt64(Tag tag) const;

    /// Returns a field value as an OnixS::FIX::UInt64 value.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    UInt64 getUInt64(Tag tag) const;

    /// Returns the field value as a floating-point number.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    Double getDouble(Tag tag) const;

    /// Returns the field value as a decimal number.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    Decimal getDecimal(Tag tag) const;

    /// Returns the field value as a decimal number with fixed exponent.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    Decimal getDecimal(Tag tag, Int32 exponent) const;

    /// Returns reference to a read-only text chain.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    StringRef getStringRef(Tag tag) const;

    /// Returns the field value as a timestamp.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// The method tries to determine the timestamp format in runtime.
    /// Therefore, it makes sense to use this method when the timestamp format
    /// is unknown. Otherwise, for better performance, the overloaded method
    /// with the explicit timestamp format parameter should be used.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    Timestamp getTimestamp(Tag tag) const;

    /// Returns the field value as a timestamp of the requested format.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    Timestamp getTimestamp(Tag tag, TimestampFormat::Enum) const;

    /// Returns the field value as a time span.
    ///
    /// @throw std::exception if the conversion is impossible.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    TimeSpan getTimeSpan(Tag tag) const;

    /// Returns a reference to a repeating group if the underlying
    /// field defines the length of the repeating group.
    ///
    /// @param numberOfInstancesTag The Tag number of
    /// the field that defines the number of instances
    /// in this repeating group (the NoXXX field).
    ///
    /// @throw std::exception if no repeating group
    /// is associated with the given field (tag).
    ///
    /// @warning The returned instance remains valid until the field is
    /// modified via any of OnixS::FIX::FieldSet::set members.
    Group getGroup(Tag numberOfInstancesTag) const;

    /// Returns true if the given flag is present
    /// and it equals to "Y", otherwise false.
    ///
    /// @warning Due to performance considerations, doesn't
    /// check whether an instance refers to a valid set of fields.
    /// Use OnixS::FIX::FieldSet::valid() to check whether
    /// an instance is in the valid state.
    bool hasFlag(Tag tag) const;

    /// Assigns the given value to the field.
    ///
    /// Transforms the input value into the text-presentation,
    /// so actually stored value is the text-presentation of the input.
    /// Further, the stored text-presentation may be directly accessed
    /// using the OnixS::FIX::FieldSet::getStringRef() member to avoid
    /// additional memory allocations and copying.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, Int32 value);

    /// Assigns the given value to the field.
    ///
    /// Saves the value being set as it is without transforming
    /// it into the text-presentation. Assigning the field value via
    /// OnixS::FIX::FieldSet::setV members saves not only value
    /// but it's type as well, therefore no parsing is performed
    /// during the subsequent access to the field via get&lt;Type&gt;
    /// member.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & setV(Tag tag, Int32 value);

    /// Assigns the given value to the field.
    ///
    /// Transforms the input value into the text-presentation,
    /// so actually stored value is the text-presentation of the input.
    /// Further, the stored text-presentation may be directly accessed
    /// using the OnixS::FIX::FieldSet::getStringRef() member to avoid
    /// additional memory allocations and copying.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, UInt32 value);

    /// Assigns the given value to the field.
    ///
    /// Saves the value being set as it is without transforming
    /// it into the text-presentation. Assigning the field value via
    /// OnixS::FIX::FieldSet::setV members saves not only value
    /// but it's type as well, therefore no parsing is performed
    /// during the subsequent access to the field via get&lt;Type&gt;
    /// member.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & setV(Tag tag, UInt32 value);

    /// Assigns the given value to the field.
    ///
    /// Transforms the input value into the text-presentation,
    /// so actually stored value is the text-presentation of the input.
    /// Further, the stored text-presentation may be directly accessed
    /// using the OnixS::FIX::FieldSet::getStringRef() member to avoid
    /// additional memory allocations and copying.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, Int64 value);

    /// Assigns the given value to the field.
    ///
    /// Saves the value being set as it is without transforming
    /// it into the text-presentation. Assigning the field value via
    /// OnixS::FIX::FieldSet::setV members saves not only value
    /// but it's type as well, therefore no parsing is performed
    /// during the subsequent access to the field via get&lt;Type&gt;
    /// member.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & setV(Tag tag, Int64 value);

    /// Assigns the given value to the field.
    ///
    /// Transforms the input value into the text-presentation,
    /// so actually stored value is the text-presentation of the input.
    /// Further, the stored text-presentation may be directly accessed
    /// using the OnixS::FIX::FieldSet::getStringRef() member to avoid
    /// additional memory allocations and copying.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, UInt64 value);

    /// Assigns the given value to the field.
    ///
    /// Saves the value being set as it is without transforming
    /// it into the text-presentation. Assigning the field value via
    /// OnixS::FIX::FieldSet::setV members saves not only value
    /// but it's type as well, therefore no parsing is performed
    /// during the subsequent access to the field via get&lt;Type&gt;
    /// member.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & setV(Tag tag, UInt64 value);

    /// Assigns the given value to the field.
    ///
    /// Transforms the input value into the text-presentation,
    /// so actually stored value is the text-presentation of the input.
    /// Further, the stored text-presentation may be directly accessed
    /// using the OnixS::FIX::FieldSet::getStringRef() member to avoid
    /// additional memory allocations and copying.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, Double value, size_t precision = 17);

    /// Assigns the given value to the field,
    /// if the string presentation of the value is greater than
    /// the length it will be truncated, only digit characters
    /// are counted.
    ///
    /// Transforms the input value into the text-presentation,
    /// so actually stored value is the text-presentation of the input.
    /// Further, the stored text-presentation may be directly accessed
    /// using the OnixS::FIX::FieldSet::getStringRef() member to avoid
    /// additional memory allocations and copying.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, Double value, size_t precision, size_t length);

    /// Assigns the given value to the field.
    ///
    /// Saves the value being set as it is without transforming
    /// it into the text-presentation. Assigning the field value via
    /// OnixS::FIX::FieldSet::setV members saves not only value
    /// but it's type as well, therefore no parsing is performed
    /// during the subsequent access to the field via get&lt;Type&gt;
    /// member.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & setV(Tag tag, Double value, size_t precision = 17);

    /// Assigns the given value to the field.
    /// if the string presentation of the value is greater than
    /// the length it will be truncated, only digit characters
    /// are counted.
    ///
    /// Saves the value being set as it is without transforming
    /// it into the text-presentation. Assigning the field value via
    /// OnixS::FIX::FieldSet::setV members saves not only value
    /// but it's type as well, therefore no parsing is performed
    /// during the subsequent access to the field via get&lt;Type&gt;
    /// member.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & setV(Tag tag, Double value, size_t precision, size_t length);

    /// Assigns the given value to the field.
    ///
    /// Transforms the input value into the text-presentation,
    /// so actually stored value is the text-presentation of the input.
    /// Further, the stored text-presentation may be directly accessed
    /// using the OnixS::FIX::FieldSet::getStringRef() member to avoid
    /// additional memory allocations and copying.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, const Decimal & value);

    /// Assigns the given value to the field.
    /// if the string presentation of the value is greater than
    /// the length it will be truncated, only digit characters
    /// are counted.
    ///
    /// Transforms the input value into the text-presentation,
    /// so actually stored value is the text-presentation of the input.
    /// Further, the stored text-presentation may be directly accessed
    /// using the OnixS::FIX::FieldSet::getStringRef() member to avoid
    /// additional memory allocations and copying.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, const Decimal & value, size_t length);

    /// Assigns the given value to the field.
    ///
    /// Saves the value being set as it is without transforming
    /// it into the text-presentation. Assigning the field value via
    /// OnixS::FIX::FieldSet::setV members saves not only value
    /// but it's type as well, therefore no parsing is performed
    /// during the subsequent access to the field via get&lt;Type&gt;
    /// member.
    ///
    /// @return the reference to itself for the method chaining approach..
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & setV(Tag tag, const Decimal & value);

    /// Assigns the given value to the field.
    /// if the string presentation of the value is greater than
    /// the length it will be truncated, only digit characters
    /// are counted.
    ///
    /// Saves the value being set as it is without transforming
    /// it into the text-presentation. Assigning the field value via
    /// OnixS::FIX::FieldSet::setV members saves not only value
    /// but it's type as well, therefore no parsing is performed
    /// during the subsequent access to the field via get&lt;Type&gt;
    /// member.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & setV(Tag tag, const Decimal & value, size_t length);

    /// Assigns the given value to the field.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, char value);

    /// Assigns the given value to the field.
    ///
    /// The stored value represents a copy of the input.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, const std::string & value);

    /// Assigns the given value to the field.
    ///
    /// The stored value represents a copy of the input.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, const char * value);

    /// Assigns the given value to the field.
    ///
    /// The stored value represents a copy of the input.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, const StringRef & value);

    /// Assigns the given value to the field.
    ///
    /// Transforms the input value into the text-presentation,
    /// so actually stored value is the text-presentation of the input.
    /// Further, the stored text-presentation may be directly accessed
    /// using the OnixS::FIX::FieldSet::getStringRef() member to avoid
    /// additional memory allocations and copying.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet &
    set(
        Tag tag,
        const Timestamp & value,
        TimestampFormat::Enum valueFormat =
            TimestampFormat::YYYYMMDDHHMMSSNsec);

    /// Assigns the given value to the field.
    ///
    /// Saves the value being set as it is without transforming
    /// it into the text-presentation. Assigning the field value via
    /// OnixS::FIX::FieldSet::setV members saves not only value
    /// but it's type as well, therefore no parsing is performed
    /// during the subsequent access to the field via get&lt;Type&gt;
    /// member.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet &
    setV(
        Tag tag,
        const Timestamp & value,
        TimestampFormat::Enum valueFormat =
            TimestampFormat::YYYYMMDDHHMMSSNsec);

    /// Assigns the given value to the field.
    ///
    /// Transforms the input value into the text-presentation,
    /// so actually stored value is the text-presentation of the input.
    /// Further, the stored text-presentation may be directly accessed
    /// using the OnixS::FIX::FieldSet::getStringRef() member to avoid
    /// additional memory allocations and copying.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet &
    set(
        Tag tag,
        const TimeSpan & value,
        TimeSpanFormat::Enum valueFormat =
            TimeSpanFormat::HHMMSSNsec);

    /// Assigns the given value to the field.
    ///
    /// Saves the value being set as it is without transforming
    /// it into the text-presentation. Assigning the field value via
    /// OnixS::FIX::FieldSet::setV members saves not only value
    /// but it's type as well, therefore no parsing is performed
    /// during the subsequent access to the field via get&lt;Type&gt;
    /// member.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet &
    setV(
        Tag tag,
        const TimeSpan & value,
        TimeSpanFormat::Enum valueFormat =
            TimeSpanFormat::HHMMSSNsec);

    /// Creates a new repeating group or changes the number
    /// of instances in the existing repeating group.
    ///
    /// @param tag The Tag number of the field that defines
    /// the number of instances in this repeating group (the NoXXX field).
    ///
    /// @param value The number of instances in the repeating group.
    ///
    /// @throw std::exception if the given field doesn't
    /// define the number of repeating group instances.
    Group setGroup(Tag tag, size_t value);

    /// Assigns the flag value ("Y" or "N") to the field.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & setFlag(Tag tag, bool value);

    /// Assigns the value to a field as a copy of another field value.
    ///
    /// @return the reference to itself for the method chaining approach.
    ///
    /// @warning if the field of the given tag is not defined by the
    /// FIX Specification for the given field set (either a message or
    /// a repeating group instance), the function may throw an exception
    /// (behavior is controlled by validation-related parameters
    /// from the Engine's configuration).
    FieldSet & set(Tag tag, const FieldValueRef & value);

    /// Erases an association of the field with its value.
    /// @return 'true' if the field had a valid value before.
    bool erase(Tag tag);

    /// Retrieve tags and values of all non-empty fields belonged to the given @c FieldSet instance.
    /// @param fields The object to receive the @c FieldSet content.
    /// @return The number of fields placed to the @c fields vector.
    size_t fields(Fields & fields) const;

    /// The constant iterator to iterate over all fields in the given FieldSet instance.
    class ONIXS_FIXENGINE_API ConstIterator
    {
    public:

        typedef std::forward_iterator_tag iterator_category;
        typedef Field value_type;
        typedef Field difference_type;
        typedef Field * pointer;
        typedef Field & reference;

        /// Initializes the iterator by a first field from which you need to iterate.
        ConstIterator(const FieldSet *, Tag);

        const Field & operator *() const {
            return currentField_;
        }

        const Field * operator ->() const {
            return &currentField_;
        }

        bool operator == (const ConstIterator &) const;
        bool operator != (const ConstIterator &) const;

        ConstIterator & operator ++();

    private:
        /// The FieldSet instance to iterate.
        const FieldSet * container_;

        /// The current field.
        Field currentField_;
    };

    /// Returns the constant iterator to the first field in the FieldSet instance.
    ConstIterator begin() const;

    /// Returns the constant iterator to the field after the last one in the FieldSet instance.
    ConstIterator end() const;

protected:
    // Policies to control the field access.
    typedef size_t AccessPolicies;

    // The underlying implementation.
    void * impl_;

    // The message to which the given set belongs to.
    const Message * container_;

    // Policies to control the field access.
    AccessPolicies policies_;

    // The uninitialized set.
    FieldSet();

    // The uninitialized set.
    FieldSet(const Message *, void *, AccessPolicies);

    // The clone construction.
    FieldSet(const FieldSet &);

    // The destruction available via descendants.
    ~FieldSet() ONIXS_FIXENGINE_DEFAULT;

    FieldSet & operator = (const FieldSet &);

    // Swaps two instances.
    void swap(FieldSet &);

private:
    friend class Message;
    friend class GroupInstance;
    friend class MessageOperator;
};

inline
bool
FieldSet::contain(Tag tag) const
{
    return get(tag).valid();
}
}
}