IpRegOptions.hpp

Go to the documentation of this file.

// Copyright (C) 2004, 2006 International Business Machines and others.
// All Rights Reserved.
// This code is published under the Common Public License.
//
// $Id: IpRegOptions.hpp 759 2006-07-07 03:07:08Z andreasw $
//
// Authors:  Carl Laird, Andreas Waechter     IBM    2005-06-18

#ifndef __IPREGOPTIONS_HPP__
#define __IPREGOPTIONS_HPP__

#include "IpUtils.hpp"
#include "IpReferenced.hpp"
#include "IpException.hpp"
#include "IpSmartPtr.hpp"

#include <map>

namespace Ipopt
{

  enum RegisteredOptionType
  {
    OT_Number,
    OT_Integer,
    OT_String,
    OT_Unknown
  };

  class RegisteredOption : public ReferencedObject
  {
  public:
    RegisteredOption()
        :
        type_(OT_Unknown),
        has_lower_(false),
        has_upper_(false),
        counter_(0)
    {}

    RegisteredOption(const std::string& name,
                     const std::string& short_description,
                     const std::string& long_description,
                     const std::string& registering_category)
        :
        name_(name),
        short_description_(short_description),
        long_description_(long_description),
        registering_category_(registering_category),
        type_(OT_Unknown),
        has_lower_(false),
        has_upper_(false),
        counter_(next_counter_++)
    {}

    RegisteredOption(const RegisteredOption& copy)
        :
        name_(copy.name_),
        short_description_(copy.short_description_),
        long_description_(copy.long_description_),
        registering_category_(copy.registering_category_),
        type_(copy.type_),
        has_lower_(copy.has_lower_),
        lower_(copy.lower_),
        has_upper_(copy.has_upper_),
        upper_(copy.upper_),
        valid_strings_(copy.valid_strings_),
        counter_(copy.counter_)
    {}

    virtual ~RegisteredOption()
    {}

    DECLARE_STD_EXCEPTION(ERROR_CONVERTING_STRING_TO_ENUM);

    const std::string& Name() const
    {
      return name_;
    }
    void SetName(const std::string& name)
    {
      name_ = name;
    }
    const std::string& ShortDescription() const
    {
      return short_description_;
    }
    const std::string& LongDescription() const
    {
      return long_description_;
    }
    void SetShortDescription(const std::string& short_description)
    {
      short_description_ = short_description;
    }
    void SetLongDescription(const std::string& long_description)
    {
      long_description_ = long_description;
    }
    const std::string& RegisteringCategory() const
    {
      return registering_category_;
    }
    void SetRegisteringCategory(const std::string& registering_category)
    {
      registering_category_ = registering_category;
    }
    const RegisteredOptionType& Type() const
    {
      return type_;
    }
    void SetType(const RegisteredOptionType& type)
    {
      type_ = type;
    }
    Index Counter() const
    {
      return counter_;
    }

    const bool& HasLower() const
    {
      DBG_ASSERT(type_ == OT_Number || type_ == OT_Integer);
      return has_lower_;
    }
    const bool& LowerStrict() const
    {
      DBG_ASSERT(type_ == OT_Number && has_lower_ == true);
      return lower_strict_;
    }
    Number LowerNumber() const
    {
      DBG_ASSERT(has_lower_ == true && type_ == OT_Number);
      return lower_;
    }
    void SetLowerNumber(const Number& lower, const bool& strict)
    {
      DBG_ASSERT(type_ == OT_Number);
      lower_ = lower;
      lower_strict_ = strict, has_lower_ = true;
    }
    Index LowerInteger() const
    {
      DBG_ASSERT(has_lower_ == true && type_ == OT_Integer);
      return (Index)lower_;
    }
    void SetLowerInteger(const Index& lower)
    {
      DBG_ASSERT(type_ == OT_Integer);
      lower_ = (Number)lower;
      has_lower_ = true;
    }
    const bool& HasUpper() const
    {
      DBG_ASSERT(type_ == OT_Number || type_ == OT_Integer);
      return has_upper_;
    }
    const bool& UpperStrict() const
    {
      DBG_ASSERT(type_ == OT_Number && has_upper_ == true);
      return upper_strict_;
    }
    Number UpperNumber()
    {
      DBG_ASSERT(has_upper_ == true && type_ == OT_Number);
      return upper_;
    }
    void SetUpperNumber(const Number& upper, const bool& strict)
    {
      DBG_ASSERT(type_ == OT_Number);
      upper_ = upper;
      upper_strict_ = strict;
      has_upper_ = true;
    }
    Index UpperInteger() const
    {
      DBG_ASSERT(has_upper_ == true && type_ == OT_Integer);
      return (Index)upper_;
    }
    void SetUpperInteger(const Index& upper)
    {
      DBG_ASSERT(type_ == OT_Integer);
      upper_ = (Number)upper;
      has_upper_ = true;
    }
    void AddValidStringSetting(const std::string value,
                               const std::string description)
    {
      DBG_ASSERT(type_ == OT_String);
      valid_strings_.push_back(string_entry(value, description));
    }
    Number DefaultNumber() const
    {
      DBG_ASSERT(type_ == OT_Number);
      return default_number_;
    }
    void SetDefaultNumber(const Number& default_value)
    {
      DBG_ASSERT(type_ == OT_Number);
      default_number_ = default_value;
    }
    Index DefaultInteger() const
    {
      DBG_ASSERT(type_ == OT_Integer);
      return (Index)default_number_;
    }
    void SetDefaultInteger(const Index& default_value)
    {
      DBG_ASSERT(type_ == OT_Integer);
      default_number_ = (Number)default_value;
    }
    std::string DefaultString() const
    {
      DBG_ASSERT(type_ == OT_String);
      return default_string_;
    }
    Index DefaultStringAsEnum() const
    {
      DBG_ASSERT(type_ == OT_String);
      return MapStringSettingToEnum(default_string_);
    }
    void SetDefaultString(const std::string& default_value)
    {
      DBG_ASSERT(type_ == OT_String);
      default_string_ = default_value;
    }
    bool IsValidNumberSetting(const Number& value) const
    {
      DBG_ASSERT(type_ == OT_Number);
      if (has_lower_ && ((lower_strict_ == true && value <= lower_) ||
                         (lower_strict_ == false && value < lower_))) {
        return false;
      }
      if (has_upper_ && ((upper_strict_ == true && value >= upper_) ||
                         (upper_strict_ == false && value > upper_))) {
        return false;
      }
      return true;
    }
    bool IsValidIntegerSetting(const Index& value) const
    {
      DBG_ASSERT(type_ == OT_Integer);
      if (has_lower_ && value < lower_) {
        return false;
      }
      if (has_upper_ && value > upper_) {
        return false;
      }
      return true;
    }
    bool IsValidStringSetting(const std::string& value) const;

    std::string MapStringSetting(const std::string& value) const;

    Index MapStringSettingToEnum(const std::string& value) const;

    void OutputDescription(const Journalist& jnlst) const;
    void OutputShortDescription(const Journalist& jnlst) const;
    void OutputLatexDescription(const Journalist& jnlst) const;

  private:
    std::string name_;
    std::string short_description_;
    std::string long_description_;
    std::string registering_category_;
    RegisteredOptionType type_;

    bool has_lower_;
    bool lower_strict_;
    Number lower_;
    bool has_upper_;
    bool upper_strict_;
    Number upper_;
    Number default_number_;

    void MakeValidLatexString(std::string source, std::string& dest) const;
    std::string MakeValidLatexNumber(Number value) const;

    bool string_equal_insensitive(const std::string& s1,
                                  const std::string& s2) const;

    class string_entry
    {
    public:
      string_entry(const std::string& value, const std::string& description)
          : value_(value), description_(description)
      {}
      std::string value_;
      std::string description_;
    };

    std::vector<string_entry> valid_strings_;
    std::string default_string_;

    const Index counter_;

    static Index next_counter_;
  };

  class RegisteredOptions : public ReferencedObject
  {
  public:
    RegisteredOptions()
        :
        current_registering_category_("Uncategorized")
    {}

    ~RegisteredOptions()
    {}

    DECLARE_STD_EXCEPTION(OPTION_ALREADY_REGISTERED);

    void SetRegisteringCategory(const std::string& registering_category)
    {
      current_registering_category_ = registering_category;
    }

    std::string RegisteringCategory()
    {
      return current_registering_category_;
    }

    void AddNumberOption(const std::string& name,
                         const std::string& short_description,
                         Number default_value,
                         const std::string& long_description="");
    void AddLowerBoundedNumberOption(const std::string& name,
                                     const std::string& short_description,
                                     Number lower, bool strict,
                                     Number default_value,
                                     const std::string& long_description="");
    void AddUpperBoundedNumberOption(const std::string& name,
                                     const std::string& short_description,
                                     Number upper, bool strict,
                                     Number default_value,
                                     const std::string& long_description="");
    void AddBoundedNumberOption(const std::string& name,
                                const std::string& short_description,
                                Number lower, bool lower_strict,
                                Number upper, bool upper_strict,
                                Number default_value,
                                const std::string& long_description="");
    void AddIntegerOption(const std::string& name,
                          const std::string& short_description,
                          Index default_value,
                          const std::string& long_description="");
    void AddLowerBoundedIntegerOption(const std::string& name,
                                      const std::string& short_description,
                                      Index lower, Index default_value,
                                      const std::string& long_description="");
    void AddUpperBoundedIntegerOption(const std::string& name,
                                      const std::string& short_description,
                                      Index upper, Index default_value,
                                      const std::string& long_description="");
    void AddBoundedIntegerOption(const std::string& name,
                                 const std::string& short_description,
                                 Index lower, Index upper,
                                 Index default_value,
                                 const std::string& long_description="");

    void AddStringOption(const std::string& name,
                         const std::string& short_description,
                         const std::string& default_value,
                         const std::vector<std::string>& settings,
                         const std::vector<std::string>& descriptions,
                         const std::string& long_description="");
    void AddStringOption1(const std::string& name,
                          const std::string& short_description,
                          const std::string& default_value,
                          const std::string& setting1,
                          const std::string& description1,
                          const std::string& long_description="");
    void AddStringOption2(const std::string& name,
                          const std::string& short_description,
                          const std::string& default_value,
                          const std::string& setting1,
                          const std::string& description1,
                          const std::string& setting2,
                          const std::string& description2,
                          const std::string& long_description="");
    void AddStringOption3(const std::string& name,
                          const std::string& short_description,
                          const std::string& default_value,
                          const std::string& setting1,
                          const std::string& description1,
                          const std::string& setting2,
                          const std::string& description2,
                          const std::string& setting3,
                          const std::string& description3,
                          const std::string& long_description="");
    void AddStringOption4(const std::string& name,
                          const std::string& short_description,
                          const std::string& default_value,
                          const std::string& setting1,
                          const std::string& description1,
                          const std::string& setting2,
                          const std::string& description2,
                          const std::string& setting3,
                          const std::string& description3,
                          const std::string& setting4,
                          const std::string& description4,
                          const std::string& long_description="");
    void AddStringOption5(const std::string& name,
                          const std::string& short_description,
                          const std::string& default_value,
                          const std::string& setting1,
                          const std::string& description1,
                          const std::string& setting2,
                          const std::string& description2,
                          const std::string& setting3,
                          const std::string& description3,
                          const std::string& setting4,
                          const std::string& description4,
                          const std::string& setting5,
                          const std::string& description5,
                          const std::string& long_description="");
    void AddStringOption6(const std::string& name,
                          const std::string& short_description,
                          const std::string& default_value,
                          const std::string& setting1,
                          const std::string& description1,
                          const std::string& setting2,
                          const std::string& description2,
                          const std::string& setting3,
                          const std::string& description3,
                          const std::string& setting4,
                          const std::string& description4,
                          const std::string& setting5,
                          const std::string& description5,
                          const std::string& setting6,
                          const std::string& description6,
                          const std::string& long_description="");
    void AddStringOption7(const std::string& name,
                          const std::string& short_description,
                          const std::string& default_value,
                          const std::string& setting1,
                          const std::string& description1,
                          const std::string& setting2,
                          const std::string& description2,
                          const std::string& setting3,
                          const std::string& description3,
                          const std::string& setting4,
                          const std::string& description4,
                          const std::string& setting5,
                          const std::string& description5,
                          const std::string& setting6,
                          const std::string& description6,
                          const std::string& setting7,
                          const std::string& description7,
                          const std::string& long_description="");

    SmartPtr<const RegisteredOption> GetOption(const std::string& name);

    void OutputOptionDocumentation(const Journalist& jnlst, std::list<std::string>& categories);

    void OutputLatexOptionDocumentation(const Journalist& jnlst, std::list<std::string>& categories);

  private:
    std::string current_registering_category_;
    std::map<std::string, SmartPtr<RegisteredOption> > registered_options_;
  };
} // namespace Ipopt

#endif