Teuchos_StandardParameterEntryValidators.hpp

// @HEADER
// ***********************************************************************
//
//                    Teuchos: Common Tools Package
//                 Copyright (2004) Sandia Corporation
//
// Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
// license for use of this work by or on behalf of the U.S. Government.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
//
// 3. Neither the name of the Corporation nor the names of the
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Questions? Contact Michael A. Heroux (maherou@sandia.gov)
//
// ***********************************************************************
// @HEADER

#ifndef TEUCHOS_STANDARD_PARAMETER_ENTRY_VALIDATORS_H
#define TEUCHOS_STANDARD_PARAMETER_ENTRY_VALIDATORS_H

#include "Teuchos_ParameterEntryValidator.hpp"
#include "Teuchos_ParameterList.hpp"
#include "Teuchos_ParameterListExceptions.hpp"
#include "Teuchos_VerbosityLevel.hpp"
#include "Teuchos_TwoDArray.hpp"
#include "Teuchos_Assert.hpp"
#include "Teuchos_StrUtils.hpp"
#include "Teuchos_TypeNameTraits.hpp"
#include "Teuchos_DummyObjectGetter.hpp"

namespace Teuchos {


template<class IntegralType>
class StringToIntegralParameterEntryValidator : public ParameterEntryValidator {
public:

  StringToIntegralParameterEntryValidator(
    ArrayView<const std::string> const& strings,
    std::string const& defaultParameterName
    );

  StringToIntegralParameterEntryValidator(
    ArrayView<const std::string> const& strings,
    ArrayView<const IntegralType> const& integralValues,
    std::string const& defaultParameterName
    );

  StringToIntegralParameterEntryValidator(
    ArrayView<const std::string> const& strings,
    ArrayView<const std::string> const& stringsDocs,
    ArrayView<const IntegralType> const& integralValues,
    std::string const& defaultParameterName
    );



  IntegralType getIntegralValue(
    const std::string &str, const std::string &paramName = "",
    const std::string &sublistName = ""
    ) const;

  IntegralType getIntegralValue(
    const ParameterEntry &entry, const std::string &paramName = "",
    const std::string &sublistName = "", const bool activeQuery = true
    ) const;

  std::string getStringValue(
    const ParameterEntry &entry, const std::string &paramName = "",
    const std::string &sublistName = "", const bool activeQuery = true
    ) const;

  IntegralType getIntegralValue(
    ParameterList &paramList, const std::string &paramName,
    const std::string &defaultValue
    ) const;

  std::string getStringValue(
    ParameterList &paramList, const std::string &paramName,
    const std::string &defaultValue
    ) const;

  ValidStringsList getStringDocs() const;

  const std::string& getDefaultParameterName() const;

  std::string validateString(
    const std::string &str, const std::string &paramName = "",
    const std::string &sublistName = ""
    ) const;



  const std::string getXMLTypeName() const;

  void printDoc(
    std::string const& docString,
    std::ostream & out
    ) const;

  ValidStringsList
  validStringValues() const;

  void validate(
    ParameterEntry const& entry,
    std::string const& paramName,
    std::string const& sublistName
    ) const;


private:

  typedef std::map<std::string,IntegralType> map_t;
  std::string defaultParameterName_;
  std::string validValues_;
  ValidStringsList validStringValues_;
  ValidStringsList validStringValuesDocs_;
  map_t map_;

  void setValidValues(
    ArrayView<const std::string> const& strings,
    ArrayView<const std::string> const* stringsDocs = NULL
    );

  // Not defined and not to be called.
  StringToIntegralParameterEntryValidator();

};


template<class IntegralType>
RCP<StringToIntegralParameterEntryValidator<IntegralType> >
stringToIntegralParameterEntryValidator(
  ArrayView<const std::string> const& strings,
  std::string const& defaultParameterName
  );


template<class IntegralType>
RCP<StringToIntegralParameterEntryValidator<IntegralType> >
stringToIntegralParameterEntryValidator(
  ArrayView<const std::string> const& strings,
  ArrayView<const IntegralType> const& integralValues,
  std::string const& defaultParameterName
  );


template<class IntegralType>
RCP<StringToIntegralParameterEntryValidator<IntegralType> >
stringToIntegralParameterEntryValidator(
  ArrayView<const std::string> const& strings,
  ArrayView<const std::string> const& stringsDocs,
  ArrayView<const IntegralType> const& integralValues,
  std::string const& defaultParameterName
  );

template<class IntegralType>
void setStringToIntegralParameter(
  std::string const& paramName,
  std::string const& defaultValue,
  std::string const& docString,
  ArrayView<const std::string> const& strings,
  ParameterList * paramList
  );


template<class IntegralType>
void setStringToIntegralParameter(
  std::string const& paramName,
  std::string const& defaultValue,
  std::string const& docString,
  ArrayView<const std::string> const& strings,
  ArrayView<const IntegralType> const& integralValues,
  ParameterList * paramList
  );


template<class IntegralType>
void setStringToIntegralParameter(
  std::string const& paramName,
  std::string const& defaultValue,
  std::string const& docString,
  ArrayView<const std::string> const& strings,
  ArrayView<const std::string> const& stringsDocs,
  ArrayView<const IntegralType> const& integralValues,
  ParameterList * paramList
  );


template<class IntegralType>
IntegralType getIntegralValue(
  ParameterList const& paramList, std::string const& paramName
  );


template<class IntegralType>
std::string getStringValue(
  ParameterList const& paramList, std::string const& paramName
  );


template<class IntegralType>
RCP<const StringToIntegralParameterEntryValidator<IntegralType> >
getStringToIntegralParameterEntryValidator(
  ParameterEntry const& entry, ParameterList const& paramList,
  std::string const& paramName
  );


std::string getVerbosityLevelParameterValueName(
  const EVerbosityLevel verbLevel
  );


RCP<StringToIntegralParameterEntryValidator<EVerbosityLevel> >
verbosityLevelParameterEntryValidator(std::string const& defaultParameterName);

template<class IntegralType>
class DummyObjectGetter<StringToIntegralParameterEntryValidator<IntegralType> >{

public:


  static RCP<StringToIntegralParameterEntryValidator<IntegralType> >
    getDummyObject();

};

template<class IntegralType>
RCP<StringToIntegralParameterEntryValidator<IntegralType> >
  DummyObjectGetter<StringToIntegralParameterEntryValidator<IntegralType> >::getDummyObject()
{
  return stringToIntegralParameterEntryValidator<IntegralType>(
    tuple<std::string>(""), tuple<std::string>(""),
    tuple<IntegralType>((IntegralType)1), "");
}



class TEUCHOS_LIB_DLL_EXPORT AnyNumberParameterEntryValidator
 : public ParameterEntryValidator
{
public:


  enum EPreferredType { PREFER_INT, PREFER_DOUBLE, PREFER_STRING };


  class AcceptedTypes {
  public:
    AcceptedTypes( bool allowAllTypesByDefault = true )
      :allowInt_(allowAllTypesByDefault),allowDouble_(allowAllTypesByDefault),
       allowString_(allowAllTypesByDefault)
      {}
    AcceptedTypes& allowInt( bool _allowInt )
      { allowInt_ = _allowInt; return *this; }
    AcceptedTypes& allowDouble( bool _allowDouble )
      { allowDouble_ = _allowDouble; return *this; }
    AcceptedTypes& allowString( bool _allowString )
      { allowString_ = _allowString; return *this; }
    bool allowInt() const { return allowInt_; }
    bool allowDouble() const { return allowDouble_; }
    bool allowString() const { return allowString_; }
  private:
    bool  allowInt_;
    bool  allowDouble_;
    bool  allowString_;
  };



  AnyNumberParameterEntryValidator();

  AnyNumberParameterEntryValidator(
    EPreferredType const preferredType,
    AcceptedTypes const& acceptedTypes
    );



  int getInt(
    const ParameterEntry &entry, const std::string &paramName = "",
    const std::string &sublistName = "", const bool activeQuery = true
    ) const;

  double getDouble(
    const ParameterEntry &entry, const std::string &paramName = "",
    const std::string &sublistName = "", const bool activeQuery = true
    ) const;

  std::string getString(
    const ParameterEntry &entry, const std::string &paramName = "",
    const std::string &sublistName = "", const bool activeQuery = true
    ) const;

  int getInt(
    ParameterList &paramList, const std::string &paramName,
    const int defaultValue
    ) const;

  double getDouble(
    ParameterList &paramList, const std::string &paramName,
    const double defaultValue
    ) const;

  std::string getString(
    ParameterList &paramList, const std::string &paramName,
    const std::string &defaultValue
    ) const;

  bool isDoubleAllowed() const;

  bool isIntAllowed() const;

  bool isStringAllowed() const;

  EPreferredType getPreferredType() const;

  static const std::string&
    getPrefferedTypeString(EPreferredType enumValue)
  {
    switch(enumValue){
      case PREFER_INT:
        return getIntEnumString();
        break;
      case PREFER_DOUBLE:
        return getDoubleEnumString();
        break;
      case PREFER_STRING:
        return getStringEnumString();
        break;
      default:
        static const std::string typeString(toString(enumValue));
        throw std::runtime_error("Cannot convert enumValue: " + typeString + " to a string");
        //Should never get here. This code is here so that a warning is not generated.
        return typeString;
    }
  }

  static EPreferredType getPrefferedTypeStringEnum(const std::string& enumString)
  {
    if(enumString == getIntEnumString()){
      return PREFER_INT;
    }
    else if(enumString == getDoubleEnumString()){
      return PREFER_DOUBLE;
    }
    else if(enumString == getStringEnumString()){
      return PREFER_STRING;
    }
    else{
      throw std::runtime_error("Cannot convert enumString: " + enumString + " to an enum");
    }
    //Should never get here. This code is here so that a warning is not generated.
    return (EPreferredType)-1;
  }



  const std::string getXMLTypeName() const;

  void printDoc(
    std::string const& docString,
    std::ostream & out
    ) const;

  ValidStringsList
  validStringValues() const;

  void validate(
    ParameterEntry const& entry,
    std::string const& paramName,
    std::string const& sublistName
    ) const;

  void validateAndModify(
    std::string const& paramName,
    std::string const& sublistName,
    ParameterEntry * entry
    ) const;



private:

  // ////////////////////////////
  // Private data members

  EPreferredType preferredType_;
  std::string acceptedTypesString_;

//use pragmas to disable some false-positive warnings for windows sharedlibs export
#ifdef _MSC_VER
#pragma warning(push)
#pragma warning(disable:4251)
#endif
  const AcceptedTypes acceptedTypes_;
#ifdef _MSC_VER
#pragma warning(pop)
#endif

  // ////////////////////////////
  // Private member functions

  /* \brief Gets the string representing the "int" preferred type enum */
  static const std::string& getIntEnumString(){
    static const std::string intEnumString_ = TypeNameTraits<int>::name();
    return intEnumString_;
  }

  /* \brief Gets the string representing the "double" preferred type enum */
  static const std::string& getDoubleEnumString(){
    static const std::string doubleEnumString_ = TypeNameTraits<double>::name();
    return doubleEnumString_;
  }

  /* \brief Gets the string representing the "string" preferred type enum */
  static const std::string& getStringEnumString(){
    static const std::string stringEnumString_ = TypeNameTraits<std::string>::name();
    return stringEnumString_;
  }


  void finishInitialization();

  void throwTypeError(
    ParameterEntry const& entry,
    std::string const& paramName,
    std::string const& sublistName
    ) const;

};


// Nonmember helper functions


TEUCHOS_LIB_DLL_EXPORT RCP<AnyNumberParameterEntryValidator>
anyNumberParameterEntryValidator();


TEUCHOS_LIB_DLL_EXPORT RCP<AnyNumberParameterEntryValidator>
anyNumberParameterEntryValidator(
  AnyNumberParameterEntryValidator::EPreferredType const preferredType,
  AnyNumberParameterEntryValidator::AcceptedTypes const& acceptedTypes
  );

TEUCHOS_LIB_DLL_EXPORT void setIntParameter(
  std::string const& paramName,
  int const value, std::string const& docString,
  ParameterList *paramList,
  AnyNumberParameterEntryValidator::AcceptedTypes const& acceptedTypes
  = AnyNumberParameterEntryValidator::AcceptedTypes()
  );


TEUCHOS_LIB_DLL_EXPORT void setDoubleParameter(
  std::string const& paramName,
  double const& value, std::string const& docString,
  ParameterList *paramList,
  AnyNumberParameterEntryValidator::AcceptedTypes const& acceptedTypes
  = AnyNumberParameterEntryValidator::AcceptedTypes()
  );


TEUCHOS_LIB_DLL_EXPORT void setNumericStringParameter(
  std::string const& paramName,
  std::string const& value, std::string const& docString,
  ParameterList *paramList,
  AnyNumberParameterEntryValidator::AcceptedTypes const& acceptedTypes
  = AnyNumberParameterEntryValidator::AcceptedTypes()
  );


TEUCHOS_LIB_DLL_EXPORT int getIntParameter(
  ParameterList const& paramList, std::string const& paramName
  );


TEUCHOS_LIB_DLL_EXPORT double getDoubleParameter(
  ParameterList const& paramList,
  std::string const& paramName
  );


TEUCHOS_LIB_DLL_EXPORT std::string getNumericStringParameter(
  ParameterList const& paramList,
  std::string const& paramName
  );

template<>
class TEUCHOS_LIB_DLL_EXPORT TEUCHOS_LIB_DLL_EXPORT DummyObjectGetter<AnyNumberParameterEntryValidator>{

public:


  static RCP<AnyNumberParameterEntryValidator > getDummyObject();


};


template <class T>
struct UndefinedEnhancedNumberTraits{
  static inline T notDefined() {
    return T::this_type_is_missing_a_specialization();
  }
};


template <class T>
class EnhancedNumberTraits{
public:

  static inline T min()
    { return UndefinedEnhancedNumberTraits<T>::notDefined(); }

  static inline T max()
    { return UndefinedEnhancedNumberTraits<T>::notDefined(); }

  static inline T defaultStep()
    { return UndefinedEnhancedNumberTraits<T>::notDefined(); }

  static inline unsigned short defaultPrecision()
     { return UndefinedEnhancedNumberTraits<T>::notDefined(); }

};


template<>
class EnhancedNumberTraits<short int>{
public:
  static inline short int min() { return std::numeric_limits<short int>::min(); }
  static inline short int max() { return std::numeric_limits<short int>::max(); }
  static inline short int defaultStep() { return 1; }
  static inline unsigned short defaultPrecision() { return 0; }
};


template<>
class EnhancedNumberTraits<short unsigned int>{
public:
  static inline short unsigned int min() { return std::numeric_limits<short unsigned int>::min(); }
  static inline short unsigned int max() { return std::numeric_limits<short unsigned int>::max(); }
  static inline short unsigned int defaultStep() { return 1; }
  static inline unsigned short defaultPrecision() { return 0; }
};


template<>
class EnhancedNumberTraits<int>{
public:
  static inline int min() { return std::numeric_limits<int>::min(); }
  static inline int max() { return std::numeric_limits<int>::max(); }
  static inline int defaultStep() { return 1; }
  static inline unsigned short defaultPrecision() { return 0; }
};


template<>
class EnhancedNumberTraits<unsigned int>{
public:
  static inline unsigned int min() { return std::numeric_limits<unsigned int>::min(); }
  static inline unsigned int max() { return std::numeric_limits<unsigned int>::max(); }
  static inline unsigned int defaultStep() { return 1; }
  static inline unsigned short defaultPrecision() { return 0; }
};


template<>
class EnhancedNumberTraits<long int>{
public:
  static inline long int min() { return std::numeric_limits<long int>::min(); }
  static inline long int max() { return std::numeric_limits<long int>::max(); }
  static inline long int defaultStep() { return 1; }
  static inline unsigned short defaultPrecision() { return 0; }
};


template<>
class EnhancedNumberTraits<long unsigned int>{
public:
  static inline long unsigned int min() { return std::numeric_limits<long unsigned int>::min(); }
  static inline long unsigned int max() { return std::numeric_limits<long unsigned int>::max(); }
  static inline long unsigned int defaultStep() { return 1; }
  static inline unsigned short defaultPrecision() { return 0; }
};


#ifdef HAVE_TEUCHOS_LONG_LONG_INT


template<>
class EnhancedNumberTraits<long long int>{
public:
  static inline long long int min() { return std::numeric_limits<long long int>::min(); }
  static inline long long int max() { return std::numeric_limits<long long int>::max(); }
  static inline long long int defaultStep() { return 1; }
  static inline unsigned short defaultPrecision() { return 0; }
};


template<>
class EnhancedNumberTraits<long long unsigned int>{
public:
  static inline long long unsigned int min() { return std::numeric_limits<long long unsigned int>::min(); }
  static inline long long unsigned int max() { return std::numeric_limits<long long unsigned int>::max(); }
  static inline long long unsigned int defaultStep() { return 1; }
  static inline unsigned short defaultPrecision() { return 0; }
};


#endif // HAVE_TEUCHOS_LONG_LONG_INT


template<>
class EnhancedNumberTraits<double>{
public:
  static inline double min() { return -std::numeric_limits<double>::max(); }
  static inline double max() { return std::numeric_limits<double>::max(); }
  static inline double defaultStep() { return 1; }
  static inline unsigned short defaultPrecision() { return 100; }
};


template<>
class EnhancedNumberTraits<float>{
public:
  static inline float min() { return -std::numeric_limits<float>::max(); }
  static inline float max() { return std::numeric_limits<float>::max(); }
  static inline float defaultStep() { return 1; }
  static inline unsigned short defaultPrecision() { return 100; }
};


template <class T>
class EnhancedNumberValidator : public ParameterEntryValidator{

public:


  EnhancedNumberValidator(
    T min,
    T max,
    T step=EnhancedNumberTraits<T>::defaultStep(),
    unsigned short precision=EnhancedNumberTraits<T>::defaultPrecision()):
    ParameterEntryValidator(),
    minVal(min), maxVal(max), step_(step), precision_(precision),
    containsMin(true), containsMax(true){}

  EnhancedNumberValidator():
    ParameterEntryValidator(),
    minVal(EnhancedNumberTraits<T>::min()),
    maxVal(EnhancedNumberTraits<T>::max()),
    step_(EnhancedNumberTraits<T>::defaultStep()),
    precision_(EnhancedNumberTraits<T>::defaultPrecision()),
    containsMin(false),
    containsMax(false){}




  void setMin(T min){
    minVal = min;
    containsMin = true;
  }

  void setMax(T max){
    maxVal = max;
    containsMax = true;
  }

  void setStep(T step){
    step_ = step;
  }

  void setPrecision(unsigned short precision){
    precision_ = precision;
  }



  T getMin() const{
    return minVal;
  }

  T getMax() const{
    return maxVal;
  }

  T getStep() const{
    return step_;
  }

  unsigned short getPrecision() const{
    return precision_;
  }




  bool hasMin() const{
    return containsMin;
  }

  bool hasMax() const{
    return containsMax;
  }



  ValidStringsList validStringValues() const{
    return null;
  }

  void validate(ParameterEntry const &entry, std::string const &paramName,
    std::string const &sublistName) const;

  const std::string getXMLTypeName() const{
    return  "EnhancedNumberValidator(" + TypeNameTraits<T>::name()+ ")";
  }

  void printDoc(std::string const &docString, std::ostream &out) const{
    StrUtils::printLines(out,"# ",docString);
    out << "#\tValidator Used: " << std::endl;
    out << "#\t\tNumber Validator" << std::endl;
    out << "#\t\tType: " << Teuchos::TypeNameTraits<T>::name() <<
      std::endl;
    out << "#\t\tMin (inclusive): " << minVal << std::endl;
    out << "#\t\tMax (inclusive): " << maxVal << std::endl;
  }


private:


  T minVal;

  T maxVal;

  T step_;

  unsigned short precision_;

  bool containsMin;

  bool containsMax;


};

template<class T>
void EnhancedNumberValidator<T>::validate(ParameterEntry const &entry, std::string const &paramName,
  std::string const &sublistName) const
{
  any anyValue = entry.getAny(true);
  const std::string &entryName = entry.getAny(false).typeName();

  TEUCHOS_TEST_FOR_EXCEPTION(anyValue.type() != typeid(T),
    Exceptions::InvalidParameterType,
    "The \"" << paramName << "\"" <<
    " parameter in the \"" << sublistName <<
    "\" sublist is has an error." << std::endl << std::endl <<
    "Error: The value that you entered was the wrong type." << std::endl <<
    "Parameter: " << paramName << std::endl <<
    "Type specified: " << entryName << std::endl <<
    "Type accepted: " << Teuchos::TypeNameTraits<T>::name() << std::endl);

  bool isValueInRange;
  any_cast<T>(anyValue) >= minVal && any_cast<T>(anyValue) <= maxVal
    ? isValueInRange = true : isValueInRange=false;
  TEUCHOS_TEST_FOR_EXCEPTION(!(isValueInRange),
    Exceptions::InvalidParameterValue,
    "The \"" << paramName << "\"" <<
    " parameter in the \"" << sublistName <<
    "\" sublist is has an error." << std::endl << std::endl <<
    "Error: The value that was entered doesn't fall with in " <<
    "the range set by the validator" << std::endl <<
    "Parameter: " << paramName  << std::endl <<
    "Min: " << minVal << std::endl <<
    "Max: " << maxVal << std::endl <<
    "Value entered: " <<
    (any_cast<T>(anyValue)) << std::endl << std::endl);
}

template<class T>
class DummyObjectGetter<EnhancedNumberValidator<T> >{

public:


  static RCP<EnhancedNumberValidator<T> > getDummyObject();

};

template<class T>
RCP<EnhancedNumberValidator<T> >
  DummyObjectGetter<EnhancedNumberValidator<T> >::getDummyObject()
{
  return rcp(new EnhancedNumberValidator<T>);
}

class TEUCHOS_LIB_DLL_EXPORT FileNameValidator : public ParameterEntryValidator {

public:


  static bool mustAlreadyExistDefault() { return false; }



  FileNameValidator(bool mustAlreadyExist = mustAlreadyExistDefault());




  bool fileMustExist() const;




  bool setFileMustExist(bool shouldFileExist);



  ValidStringsList validStringValues() const;

  void validate(
    ParameterEntry const &entry,
    std::string const &paramName,
    std::string const &sublistName) const;

  const std::string getXMLTypeName() const;

  void printDoc(std::string const &docString, std::ostream &out) const;


private:


  bool mustAlreadyExist_;


};

template<>
class TEUCHOS_LIB_DLL_EXPORT DummyObjectGetter<FileNameValidator>{

public:


  static RCP<FileNameValidator> getDummyObject();


};

class TEUCHOS_LIB_DLL_EXPORT StringValidator : public ParameterEntryValidator {

public:


  StringValidator();

  StringValidator(const Teuchos::Array<std::string> &validStrings);




  ValidStringsList setValidStrings(
    const Teuchos::Array<std::string> &validStrings);



  ValidStringsList validStringValues() const;

  void validate(ParameterEntry const &entry, std::string const &paramName,
    std::string const &sublistName) const;

  const std::string getXMLTypeName() const;

  void printDoc(std::string const &docString, std::ostream &out) const;


private:


  ValidStringsList validStrings_;


};

template<>
class TEUCHOS_LIB_DLL_EXPORT DummyObjectGetter<StringValidator>{

public:


  static RCP<StringValidator> getDummyObject();


};


template<class ValidatorType, class EntryType>
class AbstractArrayValidator : public ParameterEntryValidator {

public:


  AbstractArrayValidator(RCP<const ValidatorType> prototypeValidator):
    ParameterEntryValidator(),
    prototypeValidator_(prototypeValidator){}



  RCP<const ValidatorType> getPrototype() const{
    return prototypeValidator_;
  }



  ValidStringsList validStringValues() const {
    return prototypeValidator_->validStringValues();
  }


private:


  RCP<const ValidatorType> prototypeValidator_;

  AbstractArrayValidator<ValidatorType, EntryType>();


};

template<class ValidatorType, class EntryType>
class TwoDArrayValidator : public AbstractArrayValidator<ValidatorType, EntryType>{
public:

  TwoDArrayValidator(RCP<const ValidatorType> prototypeValidator):
    AbstractArrayValidator<ValidatorType, EntryType>(prototypeValidator){}



  virtual void validate(ParameterEntry const &entry, std::string const &paramName,
    std::string const &sublistName) const;

  const std::string getXMLTypeName() const{
    return "TwoDArrayValidator(" +
      this->getPrototype()->getXMLTypeName() + ", " +
      TypeNameTraits<EntryType>::name() + ")";
  }

  virtual void printDoc(std::string const &docString, std::ostream &out) const
  {
    StrUtils::printLines(out,"# ",docString);
    std::string toPrint;
    toPrint += "TwoDArrayValidator:\n";
    toPrint += "Prototype Validator:\n";
    this->getPrototype()->printDoc(toPrint, out);
  }


};

template<class ValidatorType, class EntryType>
void TwoDArrayValidator<ValidatorType, EntryType>::validate(ParameterEntry const &entry, std::string const &paramName,
  std::string const &sublistName) const
{
  any anyValue = entry.getAny(true);
  const std::string &entryName = entry.getAny(false).typeName();
  TEUCHOS_TEST_FOR_EXCEPTION(anyValue.type() != typeid(TwoDArray<EntryType>),
    Exceptions::InvalidParameterType,
    "The \"" << paramName << "\"" <<
    " parameter in the \"" << sublistName <<
    "\" sublist is has an error." << std::endl << std::endl <<
    "Error: The value you entered was the wrong type." << std::endl <<
    "Parameter: " << paramName << std::endl <<
    "Type specified: " << entryName << std::endl <<
    "Type accepted: " << TypeNameTraits<TwoDArray<EntryType> >::name() <<
    std::endl << std::endl);

  TwoDArray<EntryType> extracted =
    getValue<Teuchos::TwoDArray<EntryType> >(entry);
  RCP<const ParameterEntryValidator> prototype = this->getPrototype();
  for(int i = 0; i<extracted.getNumRows(); ++i){
    for(int j = 0; j<extracted.getNumCols(); ++j){
      ParameterEntry dummyParameter;
      dummyParameter.setValue(extracted(i,j));
      try{
        prototype->validate(
          dummyParameter, paramName, sublistName);
      }
      catch(Exceptions::InvalidParameterValue& e){
        std::stringstream oss;
        oss << "TwoDArray Validator Exception:" << std::endl <<
        "Bad Index: (" << i << "," << j << ")" << std::endl << e.what();
        throw Exceptions::InvalidParameterValue(oss.str());
      }
    }
  }
}


template<class ValidatorType, class EntryType>
class DummyObjectGetter<TwoDArrayValidator<ValidatorType, EntryType> >{

public:


  static RCP<TwoDArrayValidator<ValidatorType, EntryType> > getDummyObject();


};

template<class ValidatorType, class EntryType>
RCP<TwoDArrayValidator<ValidatorType, EntryType> >
  DummyObjectGetter<TwoDArrayValidator<ValidatorType, EntryType> >::getDummyObject()
{
  return rcp(new TwoDArrayValidator<ValidatorType, EntryType>(
    DummyObjectGetter<ValidatorType>::getDummyObject()));
}

class TEUCHOS_LIB_DLL_EXPORT TwoDArrayStringValidator :
  public TwoDArrayValidator<StringValidator, std::string>{

public:


  TwoDArrayStringValidator(RCP<const StringValidator> prototypeValidator):
    TwoDArrayValidator<StringValidator, std::string>(prototypeValidator){}


};


class TEUCHOS_LIB_DLL_EXPORT TwoDArrayFileNameValidator :
  public TwoDArrayValidator<FileNameValidator, std::string>{

public:


  TwoDArrayFileNameValidator(RCP<const FileNameValidator> prototypeValidator):
    TwoDArrayValidator<FileNameValidator, std::string>(prototypeValidator){}


};


template<class T>
class TwoDArrayNumberValidator : public TwoDArrayValidator<EnhancedNumberValidator<T>, T>{
public:

  TwoDArrayNumberValidator(
    RCP<const EnhancedNumberValidator<T> > prototypeValidator):
    TwoDArrayValidator<EnhancedNumberValidator<T>, T>(prototypeValidator){}


};


template<class ValidatorType, class EntryType>
class ArrayValidator : public AbstractArrayValidator<ValidatorType, EntryType>{

public:


  ArrayValidator(RCP<const ValidatorType> prototypeValidator):
    AbstractArrayValidator<ValidatorType, EntryType>(prototypeValidator){}



  virtual void validate(ParameterEntry const &entry, std::string const &paramName,
    std::string const &sublistName) const;

  const std::string getXMLTypeName() const{
    return "ArrayValidator(" +
      this->getPrototype()->getXMLTypeName() + ", " +
      TypeNameTraits<EntryType>::name() + ")";
  }

  virtual void printDoc(std::string const &docString, std::ostream &out) const
  {
    StrUtils::printLines(out,"# ",docString);
    std::string toPrint;
    toPrint += "ArrayValidator:\n";
    toPrint += "Prototype Validator:\n";
    this->getPrototype()->printDoc(toPrint, out);
  }


};

template<class ValidatorType, class EntryType>
void ArrayValidator<ValidatorType, EntryType>::validate(ParameterEntry const &entry, std::string const &paramName,
  std::string const &sublistName) const
{
  any anyValue = entry.getAny(true);
  const std::string &entryName = entry.getAny(false).typeName();
  TEUCHOS_TEST_FOR_EXCEPTION(anyValue.type() != typeid(Array<EntryType>),
    Exceptions::InvalidParameterType,
    "The \"" << paramName << "\"" <<
    " parameter in the \"" << sublistName <<
    "\" sublist is has an error." << std::endl << std::endl <<
    "Error: The value you entered was the wrong type." << std::endl <<
    "Parameter: " << paramName << std::endl <<
    "Type specified: " << entryName << std::endl <<
    "Type accepted: " << TypeNameTraits<Array<EntryType> >::name() <<
    std::endl << std::endl);

  Array<EntryType> extracted =
    getValue<Teuchos::Array<EntryType> >(entry);
  RCP<const ParameterEntryValidator> prototype = this->getPrototype();
  for(int i = 0; i<extracted.size(); ++i){
    ParameterEntry dummyParameter;
    dummyParameter.setValue(extracted[i]);
    try{
      prototype->validate(
        dummyParameter, paramName, sublistName);
    }
    catch(Exceptions::InvalidParameterValue& e){
      std::stringstream oss;
      oss << "Array Validator Exception:" << std::endl <<
      "Bad Index: " << i << std::endl << e.what();
      throw Exceptions::InvalidParameterValue(oss.str());
    }
  }
}

template<class ValidatorType, class EntryType>
class DummyObjectGetter<ArrayValidator<ValidatorType, EntryType> >{

public:


  static RCP<ArrayValidator<ValidatorType, EntryType> > getDummyObject();


};

template<class ValidatorType, class EntryType>
RCP<ArrayValidator<ValidatorType, EntryType> >
  DummyObjectGetter<ArrayValidator<ValidatorType, EntryType> >::getDummyObject()
{
  return rcp(new ArrayValidator<ValidatorType, EntryType>(
    DummyObjectGetter<ValidatorType>::getDummyObject()));
}


class TEUCHOS_LIB_DLL_EXPORT ArrayStringValidator :
  public ArrayValidator<StringValidator, std::string>{

public:


  ArrayStringValidator(RCP<const StringValidator> prototypeValidator):
    ArrayValidator<StringValidator, std::string>(prototypeValidator){}


};


class TEUCHOS_LIB_DLL_EXPORT ArrayFileNameValidator : public ArrayValidator<FileNameValidator, std::string>{

public:


  ArrayFileNameValidator(RCP<const FileNameValidator> prototypeValidator):
    ArrayValidator<FileNameValidator, std::string>(prototypeValidator){}


};


template<class T>
class ArrayNumberValidator : public ArrayValidator<EnhancedNumberValidator<T>, T>{
public:

  ArrayNumberValidator(
    RCP<const EnhancedNumberValidator<T> > prototypeValidator):
    ArrayValidator<EnhancedNumberValidator<T>, T>(prototypeValidator){}


};



// ///////////////////////////
// Implementations


//
// StringToIntegralParameterEntryValidator
//


// Constructors


template<class IntegralType>
StringToIntegralParameterEntryValidator<IntegralType>::StringToIntegralParameterEntryValidator(
  ArrayView<const std::string> const& strings, std::string const& defaultParameterName
  ):
  ParameterEntryValidator(),
  defaultParameterName_(defaultParameterName)
{
  typedef typename map_t::value_type val_t;
  for( int i = 0; i < static_cast<int>(strings.size()); ++i ) {
    const bool unique = map_.insert( val_t( strings[i], (IntegralType)i ) ).second;
    TEUCHOS_TEST_FOR_EXCEPTION(
      !unique, std::logic_error
      ,"Error, the std::string \"" << strings[i] << "\" is a duplicate for parameter \""
      << defaultParameterName_ << "\"."
      );
  }
  setValidValues(strings);
}


template<class IntegralType>
StringToIntegralParameterEntryValidator<IntegralType>::StringToIntegralParameterEntryValidator(
  ArrayView<const std::string> const& strings, ArrayView<const IntegralType> const& integralValues
  ,std::string const& defaultParameterName
  ):
  ParameterEntryValidator(),
  defaultParameterName_(defaultParameterName)
{
#ifdef TEUCHOS_DEBUG
  TEUCHOS_ASSERT_EQUALITY( strings.size(), integralValues.size() );
#endif
  TEUCHOS_TEST_FOR_EXCEPTION(
    strings.size() != integralValues.size(),
  std::logic_error,
  "Error, strings and integraValues must be of the same length."
  );
  typedef typename map_t::value_type val_t;
  for( int i = 0; i < static_cast<int>(strings.size()); ++i ) {
    const bool unique = map_.insert( val_t( strings[i], integralValues[i] ) ).second;
    TEUCHOS_TEST_FOR_EXCEPTION(
      !unique, std::logic_error
      ,"Error, the std::string \"" << strings[i] << "\" is a duplicate for parameter \""
      << defaultParameterName_ << "\""
      );
  }
  setValidValues(strings);
}

template<class IntegralType>
StringToIntegralParameterEntryValidator<IntegralType>::StringToIntegralParameterEntryValidator(
  ArrayView<const std::string>    const& strings
  ,ArrayView<const std::string>   const& stringsDocs
  ,ArrayView<const IntegralType>  const& integralValues
  ,std::string          const& defaultParameterName
  ):
  ParameterEntryValidator(),
  defaultParameterName_(defaultParameterName)
{
#ifdef TEUCHOS_DEBUG
  TEUCHOS_ASSERT_EQUALITY( strings.size(), stringsDocs.size() );
  TEUCHOS_ASSERT_EQUALITY( strings.size(), integralValues.size() );
#endif
  TEUCHOS_TEST_FOR_EXCEPTION(
    strings.size() != integralValues.size(),
  std::logic_error,
  "Error, strings and integraValues must be of the same length."
  );
  TEUCHOS_TEST_FOR_EXCEPTION(
    strings.size() != stringsDocs.size(),
  std::logic_error,
  "Error, strings and stringsDocs must be of the same length."
  );
  typedef typename map_t::value_type val_t;
  for( int i = 0; i < static_cast<int>(strings.size()); ++i ) {
    const bool unique = map_.insert( val_t( strings[i], integralValues[i] ) ).second;
    TEUCHOS_TEST_FOR_EXCEPTION(
      !unique, std::logic_error
      ,"Error, the std::string \"" << strings[i] << "\" is a duplicate for parameter \""
      << defaultParameterName_ << "\""
      );
  }
  setValidValues(strings,&stringsDocs);
}

// Lookup functions


template<class IntegralType>
IntegralType
StringToIntegralParameterEntryValidator<IntegralType>::getIntegralValue(
  const std::string &str, const std::string &paramName
  ,const std::string &sublistName
  ) const
{
  typename map_t::const_iterator itr = map_.find(str);
  TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(
    itr == map_.end(), Exceptions::InvalidParameterValue
    ,"Error, the value \"" << str << "\" is not recognized for the parameter \""
    << ( paramName.length() ? paramName : defaultParameterName_ ) << "\""
    << "\nin the sublist \"" << sublistName << "\"."
    << "\n\nValid values include:"
    << "\n  {\n"
    << validValues_
    << "  }"
    );
  return (*itr).second;
}


template<class IntegralType>
IntegralType
StringToIntegralParameterEntryValidator<IntegralType>::getIntegralValue(
  const ParameterEntry &entry, const std::string &paramName
  ,const std::string &sublistName, const bool activeQuery
  ) const
{
  const bool validType = ( entry.getAny(activeQuery).type() == typeid(std::string) );
  TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(
    !validType, Exceptions::InvalidParameterType
    ,"Error, the parameter {paramName=\""<<(paramName.length()?paramName:defaultParameterName_)
    << "\",type=\""<<entry.getAny(activeQuery).typeName()<<"\"}"
    << "\nin the sublist \"" << sublistName << "\""
    << "\nhas the wrong type."
    << "\n\nThe correct type is \"string\"!"
    );
  const std::string
    &strValue = any_cast<std::string>(entry.getAny(activeQuery)); // This cast should not fail!
  return getIntegralValue(strValue,paramName,sublistName); // This will validate the value and throw!
}


template<class IntegralType>
std::string
StringToIntegralParameterEntryValidator<IntegralType>::getStringValue(
  const ParameterEntry &entry, const std::string &paramName
  ,const std::string &sublistName, const bool activeQuery
  ) const
{
  // Validate the parameter's type and value
  this->getIntegralValue(entry,paramName,sublistName,activeQuery);
  // Return the std::string value which is now validated!
  return any_cast<std::string>(entry.getAny(activeQuery)); // This cast should not fail!
}


template<class IntegralType>
IntegralType
StringToIntegralParameterEntryValidator<IntegralType>::getIntegralValue(
  ParameterList &paramList, const std::string &paramName
  ,const std::string &defaultValue
  ) const
{
  const std::string
    &strValue = paramList.get(paramName,defaultValue);
  return getIntegralValue(strValue,paramName,paramList.name());
}


template<class IntegralType>
std::string
StringToIntegralParameterEntryValidator<IntegralType>::getStringValue(
  ParameterList &paramList, const std::string &paramName
  ,const std::string &defaultValue
  ) const
{
  const std::string
    &strValue = paramList.get(paramName,defaultValue);
  getIntegralValue(strValue,paramName,paramList.name()); // Validate!
  return strValue;
}

template<class IntegralType>
ParameterEntryValidator::ValidStringsList
StringToIntegralParameterEntryValidator<IntegralType>::getStringDocs() const
{
  return validStringValuesDocs_;
}

template<class IntegralType>
const std::string&
StringToIntegralParameterEntryValidator<IntegralType>::getDefaultParameterName() const
{
  return defaultParameterName_;
}

template<class IntegralType>
std::string
StringToIntegralParameterEntryValidator<IntegralType>::validateString(
  const std::string &str, const std::string &paramName
  ,const std::string &sublistName
  ) const
{
  getIntegralValue(str,paramName,sublistName); // Validate!
  return str;
}


// Overridden from ParameterEntryValidator

template<class IntegralType>
const std::string
StringToIntegralParameterEntryValidator<IntegralType>::getXMLTypeName() const{
  return "StringIntegralValidator(" +
    TypeNameTraits<IntegralType>::name() +
    ")";
}

template<class IntegralType>
void StringToIntegralParameterEntryValidator<IntegralType>::printDoc(
  std::string         const& docString
  ,std::ostream            & out
  ) const
{
  StrUtils::printLines(out,"# ",docString);
  out << "#   Valid std::string values:\n";
  out << "#     {\n";
  if(validStringValuesDocs_.get()) {
    for( int i = 0; i < static_cast<int>(validStringValues_->size()); ++i ) {
      out << "#       \"" << (*validStringValues_)[i] << "\"\n";
      StrUtils::printLines(out,"#          ",(*validStringValuesDocs_)[i] );
    }
  }
  else {
    StrUtils::printLines(out,"#   ",validValues_);
    // Note: Above validValues_ has for initial spaces already so indent should
    // be correct!
  }
  out << "#     }\n";
}


template<class IntegralType>
ParameterEntryValidator::ValidStringsList
StringToIntegralParameterEntryValidator<IntegralType>::validStringValues() const
{
  return validStringValues_;
}


template<class IntegralType>
void StringToIntegralParameterEntryValidator<IntegralType>::validate(
  ParameterEntry  const& entry
  ,std::string    const& paramName
  ,std::string    const& sublistName
  ) const
{
  this->getIntegralValue(entry,paramName,sublistName,false);
}


// private

template<class IntegralType>
void StringToIntegralParameterEntryValidator<IntegralType>::setValidValues(
  ArrayView<const std::string>   const& strings
  ,ArrayView<const std::string>  const* stringsDocs
  )
{
  validStringValues_ = rcp(new Array<std::string>(strings));
  if(stringsDocs)
    validStringValuesDocs_ = rcp(new Array<std::string>(*stringsDocs));
  // Here I build the list of valid values in the same order as passed in by
  // the client!
  std::ostringstream oss;
  for( int i = 0; i < static_cast<int>(strings.size()); ++i ) {
    oss << "    \""<<strings[i]<<"\"\n";
  }
  // Note: Above four spaces is designed for the error output above.
  validValues_ = oss.str();
}


} // namespace Teuchos


//
// Nonmember function implementations for StringToIntegralParameterEntryValidator
//


template<class IntegralType>
inline
Teuchos::RCP<Teuchos::StringToIntegralParameterEntryValidator<IntegralType> >
Teuchos::stringToIntegralParameterEntryValidator(
  ArrayView<const std::string> const& strings,
  std::string const& defaultParameterName
  )
{
  return rcp(
    new StringToIntegralParameterEntryValidator<IntegralType>(
      strings, defaultParameterName
      )
    );
}


template<class IntegralType>
inline
Teuchos::RCP<Teuchos::StringToIntegralParameterEntryValidator<IntegralType> >
Teuchos::stringToIntegralParameterEntryValidator(
  ArrayView<const std::string> const& strings,
  ArrayView<const IntegralType> const& integralValues,
  std::string const& defaultParameterName
  )
{
  return rcp(
    new StringToIntegralParameterEntryValidator<IntegralType>(
      strings, integralValues, defaultParameterName
      )
    );
}


template<class IntegralType>
inline
Teuchos::RCP< Teuchos::StringToIntegralParameterEntryValidator<IntegralType> >
Teuchos::stringToIntegralParameterEntryValidator(
  ArrayView<const std::string> const& strings,
  ArrayView<const std::string> const& stringsDocs,
  ArrayView<const IntegralType> const& integralValues,
  std::string const& defaultParameterName
  )
{
  return rcp(
    new StringToIntegralParameterEntryValidator<IntegralType>(
      strings, stringsDocs, integralValues, defaultParameterName
      )
    );
}

template<class IntegralType>
void Teuchos::setStringToIntegralParameter(
  std::string const& paramName,
  std::string const& defaultValue,
  std::string const& docString,
  ArrayView<const std::string> const& strings,
  ParameterList * paramList
  )
{
  typedef ParameterEntryValidator PEV;
  TEUCHOS_TEST_FOR_EXCEPT(0==paramList);
  paramList->set(
    paramName, defaultValue, docString,
    rcp_implicit_cast<const PEV>(
      stringToIntegralParameterEntryValidator<IntegralType>(
        strings, paramName
        )
      )
    );
}


template<class IntegralType>
void Teuchos::setStringToIntegralParameter(
  std::string const& paramName,
  std::string const& defaultValue,
  std::string const& docString,
  ArrayView<const std::string> const& strings,
  ArrayView<const IntegralType> const& integralValues,
  ParameterList * paramList
  )
{
  typedef ParameterEntryValidator PEV;
  TEUCHOS_TEST_FOR_EXCEPT(0==paramList);
  paramList->set(
    paramName, defaultValue, docString,
    rcp_implicit_cast<const PEV>(
      stringToIntegralParameterEntryValidator<IntegralType>(
        strings, integralValues, paramName
        )
      )
    );
}


template<class IntegralType>
void Teuchos::setStringToIntegralParameter(
  std::string const& paramName,
  std::string const& defaultValue,
  std::string const& docString,
  ArrayView<const std::string> const& strings,
  ArrayView<const std::string> const& stringsDocs,
  ArrayView<const IntegralType> const& integralValues,
  ParameterList * paramList
  )

{
  typedef ParameterEntryValidator PEV;
  TEUCHOS_TEST_FOR_EXCEPT(0==paramList);
  paramList->set(
    paramName, defaultValue, docString,
    rcp_implicit_cast<const PEV>(
      stringToIntegralParameterEntryValidator<IntegralType>(
        strings, stringsDocs, integralValues, paramName
        )
      )
    );
}


template<class IntegralType>
IntegralType Teuchos::getIntegralValue(
  ParameterList const& paramList, std::string const& paramName
  )
{
  const ParameterEntry &entry = paramList.getEntry(paramName);
  RCP<const StringToIntegralParameterEntryValidator<IntegralType> >
    integralValidator = getStringToIntegralParameterEntryValidator<IntegralType>(
      entry, paramList, paramName
      );
  return integralValidator->getIntegralValue(
    entry, paramName, paramList.name(), true );
}


template<class IntegralType>
std::string Teuchos::getStringValue(
  ParameterList const& paramList, std::string const& paramName
  )
{
  const ParameterEntry &entry = paramList.getEntry(paramName);
  RCP<const StringToIntegralParameterEntryValidator<IntegralType> >
    integralValidator = getStringToIntegralParameterEntryValidator<IntegralType>(
      entry, paramList, paramName
      );
  return integralValidator->getStringValue(
    entry, paramName, paramList.name(), true
    );
}


template<class IntegralType>
Teuchos::RCP<const Teuchos::StringToIntegralParameterEntryValidator<IntegralType> >
Teuchos::getStringToIntegralParameterEntryValidator(
  ParameterEntry const& entry, ParameterList const& paramList,
  std::string const& paramName
  )
{
  const RCP<const ParameterEntryValidator> validator = entry.validator();
  TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(
    is_null(validator), Exceptions::InvalidParameterType,
    "Error!  The parameter \""<<paramName<<"\" exists\n"
    "in the parameter (sub)list \""<<paramList.name()<<"\"\n"
    "but it does not contain any validator needed to extract\n"
    "an integral value of type \""<<TypeNameTraits<IntegralType>::name()<<"\"!"
    );
  const RCP<const StringToIntegralParameterEntryValidator<IntegralType> > integralValidator =
    rcp_dynamic_cast<const StringToIntegralParameterEntryValidator<IntegralType> >(
      validator
      );
  TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(
    is_null(integralValidator), Exceptions::InvalidParameterType,
    "Error!  The parameter \""<<paramName<<"\" exists\n"
    "in the parameter (sub)list \""<<paramList.name()<<"\"\n"
    "but it contains the wrong type of validator.  The expected validator type\n"
    "is \""<<TypeNameTraits<StringToIntegralParameterEntryValidator<IntegralType> >::name()<<"\"\n"
    "but the contained validator type is \""<<typeName(*validator)<<"\"!"
    );
  return integralValidator;
}


#endif // TEUCHOS_STANDARD_PARAMETER_ENTRY_VALIDATORS_H