SettingGroup.h

Go to the documentation of this file.

// 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 <OnixS/CME/MDH/String.h>

ONIXS_CMEMDH_NAMESPACE_BEGIN

ONIXS_CMEMDH_LTWT_CLASS_DECL(SettingGroup);

/// Represents a service controlling change/update
/// operations for the collections of settings.
struct ONIXS_CMEMDH_LTWT SettingChangeController
{
    /// Begins the setting change operation.
    ///
    /// May throw an exception if change is not possible
    /// for the moment or is prohibited for a setting or
    /// a group to which the setting being updated belongs.
    virtual void beginChange(const SettingGroup&, const Char*) = 0;

    /// Accomplishes the setting change operation.
    ///
    /// The given member must be invoked after
    /// successful invocation of the 'beginChange'
    /// member and before any other setting change.
    virtual void endChange() = 0;
};

// Default attributes and functionality.
struct ONIXS_CMEMDH_LTWT TrivialChangeController : SettingChangeController
{
    /// Implements base class interface.
    void beginChange(const SettingGroup&, const Char*) ONIXS_CMEMDH_OVERRIDE {}

    /// Implements base class interface.
    void endChange() ONIXS_CMEMDH_OVERRIDE {}

    /// Returns instance of the
    /// trivial assignment controller.
    ONIXS_CMEMDH_LTWT_EXPORTED
    static SettingChangeController& self();
};

/// Scope guard to update setting in the safe way.
class ONIXS_CMEMDH_LTWT SettingChangeGuard
{
public:
    /// Initializes the guard for the given setting update.
    SettingChangeGuard(SettingChangeController& controller, const SettingGroup& group, const Char* details)
        : controller_(controller)
    {
        controller_.beginChange(group, details);
    }

    /// Accomplishes setting update.
    ~SettingChangeGuard()
    {
        controller_.endChange();
    }

private:
    SettingChangeController& controller_;

    SettingChangeGuard(const SettingChangeGuard&);

    SettingChangeGuard& operator=(const SettingChangeGuard&);
};

/// Base services for settings grouped by a certain criteria.
class ONIXS_CMEMDH_LTWT SettingGroup
{
public:
    /// Initializes the group of settings
    /// with the given validation services.
    SettingGroup(SettingChangeController* controller = ONIXS_CMEMDH_NULLPTR)
        : controller_(controller ? *controller : TrivialChangeController::self())
    {
    }

    /// Does actually nothing.
    ~SettingGroup() {}

    /// Guarded assignment of the given
    /// value to the given variable.
    template <class Assignee, class Value>
    void controlAssignment(const Char* description, Assignee& assignee, Value value) const
    {
        const SettingChangeGuard guard(controller_, *this, description);
        {
            assignee = value;
        }
    }

    /// Guarded invoke of the given routine which assumes
    /// complex change or update for the given object.
    template <class Changeable>
    void controlChange(const Char* description, void (Changeable::*change)(), Changeable& changeable) const
    {
        const SettingChangeGuard guard(controller_, *this, description);
        {
            (changeable.*change)();
        }
    }

    /// Guarded invoke of the given routine which assumes
    /// complex change or update for the given object.
    template <class Change, class Changeable, class Arg>
    void controlChange(const Char* description, Change change, Changeable& changeable, const Arg& arg) const
    {
        const SettingChangeGuard guard(controller_, *this, description);
        {
            (changeable.*change)(arg);
        }
    }

    /// Guarded invoke of the given routine which assumes
    /// complex change or update for the given object.
    template <class Change, class Changeable, class Arg1, class Arg2>
    void
    controlChange(const Char* description, Change change, Changeable& changeable, const Arg1& arg1, const Arg2& arg2)
        const
    {
        const SettingChangeGuard guard(controller_, *this, description);
        {
            (changeable.*change)(arg1, arg2);
        }
    }

    /// Returns an instance
    /// representing a null group.
    ONIXS_CMEMDH_LTWT_EXPORTED
    static const SettingGroup& null();

private:
    // Controller for the given group of settings.
    SettingChangeController& controller_;

    SettingGroup(const SettingGroup&);

    SettingGroup& operator=(const SettingGroup&);
};

/// Checks the two groups for equality.
inline bool operator==(const SettingGroup& left, const SettingGroup& right)
{
    return (&left == &right);
}

/// Checks the two groups for inequality.
inline bool operator!=(const SettingGroup& left, const SettingGroup& right)
{
    return (&left != &right);
}

// Pre-defined collections.

/// Represents a setting which is a list of values.
template <class Type, class Container = std::vector<Type> >
class ListSetting
{
public:
    /// Alias for the type representing the list item.
    typedef Type Item;

    /// Internal container used to store items.
    typedef Container Items;

    /// Type in which items are counted.
    typedef typename Items::size_type Size;

    /// Constant iterator over the items.
    typedef typename Items::const_iterator Iterator;

    /// Initializes the instance belonging
    /// to the given group of settings.
    explicit ListSetting(const SettingGroup* group = ONIXS_CMEMDH_NULLPTR)
        : group_(group ? *group : SettingGroup::null())
    {
    }

    /// Initializes as a copy the other instance.
    ListSetting(const ListSetting& other)
        : group_(SettingGroup::null())
        , items_(other.items_)
    {
    }

    /// Initializes as copy of the given range of items.
    template <class InputIterator>
    ListSetting(InputIterator first, InputIterator last)
        : group_(SettingGroup::null())
        , items_(first, last)
    {
    }

    /// Implicit conversion into the container keeping items.
    operator const Items&() const
    {
        return items_;
    }

    /// Indicates whether the list is an empty one.
    bool empty() const
    {
        return items_.empty();
    }

    /// Returns number of items in the given list.
    Size size() const
    {
        return items_.size();
    }

    /// Returns iterator pointing to the beginning of the list.
    Iterator begin() const
    {
        return items_.begin();
    }

    /// Returns iterator pointing to the item beyond the last one.
    Iterator end() const
    {
        return items_.end();
    }

    /// Provides access to the items by its index.
    const Item& operator[](Size index) const
    {
        return items_[index];
    }

    /// Performs managed initialization of the
    /// list using the given functional object.
    template <class Initializer>
    void initialize(Initializer initializer)
    {
        group_.controlChange("Initialize List", &ListSetting::initNoControl<Initializer>, *this, initializer);
    }

    /// Appends the given item to the tail of the list.
    void push_back(const Item& item)
    {
        group_.controlChange(
            "Append an Item", static_cast<void (Items::*)(const Item&)>(&Items::push_back), items_, item
        );
    }

    /// Removes all items from the list.
    ///
    /// Iterators and references related
    /// to the given list are invalidated.
    void clear()
    {
        group_.controlChange("Clear the List", &Items::clear, items_);
    }

    /// Re-initialize the list as a copy of the other one.
    ListSetting& operator=(const ListSetting& other)
    {
        group_.controlChange("Assign List", &ListSetting::assignNoControl, *this, other);

        return *this;
    }

    /// Re-initialize the list as a copy of the given range.
    template <class InputIterator>
    ListSetting& assign(InputIterator first, InputIterator last)
    {
        group_.controlChange("Assign List", &Items::assign, items_, first, last);

        return *this;
    }

    /// Unmanaged assignment of the list.
    ///
    /// The given member must be used when the given
    /// instance is part of the other managed collection.
    /// It's not supposed to be invoked when the instance
    /// is manipulated in ordinary way.
    ListSetting& assignNoControl(const ListSetting& other)
    {
        items_ = other.items_;

        return *this;
    }

private:
    const SettingGroup& group_;

    Container items_;

    template <class Initializer>
    void initNoControl(Initializer initializer)
    {
        items_.clear();

        initializer(items_);
    }
};

/// Serializes the given list setting
/// into a string/text presentation.
template <class Type>
void toStr(std::string& str, const ListSetting<Type>& list, Char delimiter = ',')
{
    const typename ListSetting<Type>::Iterator endOfList = list.end();

    typename ListSetting<Type>::Iterator item = list.begin();

    while (true)
    {
        toStr(str, *item);

        if (++item == endOfList)
        {
            break;
        }

        str += delimiter;
    }
}

ONIXS_CMEMDH_NAMESPACE_END