OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup Class Reference

Class used to encapsulate options belonging an options group. More...

#include <OptionsFromStreamPack_OptionsFromStream.hpp>

List of all members.

Public Types

typedef option_to_value_map_t::iterator iterator
 
typedef option_to_value_map_t::const_iterator const_iterator
 

Lookup an an value of an option given the option's name.

If the option does not exist then option_exists( option_value( option_name ) ) will return false otherwise the option exists and can be read.

std::string & option_value (const std::string &option_name)
 
const std::string & option_value (const std::string &option_name) const
 

Iterator access

int num_options () const
 
iterator begin ()
 
iterator end ()
 
const_iterator begin () const
 
const_iterator end () const
 

Public Member Functions

bool options_group_exists () const
 Returns true if this options groups exists.
 OptionsGroup (option_to_value_map_t *option_to_value_map)

Static Public Member Functions

static bool option_exists (const std::string &option_value)
 

Private Member Functions

 OptionsGroup ()
OptionsGroupoperator= (const OptionsGroup &)

Private Attributes

option_to_value_map_toption_to_value_map_

Static Private Attributes

static std::string option_does_not_exist_

Friends

class OptionsFromStream


Detailed Description

Class used to encapsulate options belonging an options group.

This class offers two ways to access the options and their values in an options group. These two methods differ in their convience, the cost of performing them and the level of validation possible. In the following discussion, n_total is the total number of options being checked for and n_set is the number of options set.

1) Looking up the values directly.

Here the software client just looks up the value directly. If the option with the given name does not exist then the function option_exists( ... ) will return false.

In the following example, the lookup of the option named "tol" is attempted on the OptionsGroup object optgrp.

  const std::string& val = optgrp.option_value( "tol" );
  if( OptionsGroup::option_exists( val ) )
      std::cout << "\ntol = " << val;

  
The total cost of this way of looking up option values is:

O(n_total*log(n_set)).

The disadvantage of using this method is that if the user misspelled the name of the option then the option will not be found or set. In the above example, if the user misspelled the option "tol" as "tal" then OptionsGroup::option_exists( val ) would return false and the option value would not be accessed.

2) Setting options by iterating through options present.

In this method the software client must keep a map to translate from an options name to an id representing the option. Then a switch can be used to take action.

In the following example (see the example from OptionsFromStream} , three possible options are looked for. Here the client has defined an enum for the options and initialized a StringToIntMap}.

  const char optgrp_name[] = "MySolverOptions";
  const int num_opt = 3;
  enum EOptions {
    TOL
    ,MAX_ITER
    ,PROB_TYPE
  };
  const char* SOptions[num_opt] = {
    "tol"
    ,"max_iter"
    ,"prob_type"
  };
  StringToIntMap	opt_map( optgrp_name, num_opt, SOptions );
  OptionsGroup::const_iterator
    itr     = optgrp.begin(),
    itr_end = optgrp.end();
  for( ; itr != itr_end; ++itr ) {
    switch( (EOptions)opt_map(option_name(itr)) ) {
      case TOL:
        std::cout << "\noption tol = " << option_value(itr);
        break;
      case MAX_ITER:
        std::cout << "\noption max_iter = " << option_value(itr);
        break;
      case PROB_TYPE:
        std::cout << "\noption prob_type = " << option_value(itr);
        break;
      default:
        std::cout << "\nThe option " << option_name(itr) << " is not valid";
        exit(-1);	            
    }
  }

  

The above code terminates the program in case the option with the name returned from option_name(itr) is not expected. This option could be ignored (as would have been in method 1) or some other action could be taken. It is a good idea to use the above method to validate that all of the options that the user sets for an options_group are known by the client software so that misspellings are caught. For example, if the user misspelled "tol" as "tal" then the "opt_map" object above would not find this option name an the default: case above would be executed.

The total cost of this way off looking up option values is:

O(n_set*log(n_total))

As it can be clearly seen, method 2 will be faster since n_total >= n_set. Method 1 takes less overhead for the client (no map or enum needed) and is easier to maintain. The real advantage of Method 2 though is that if a user misspells an option then Method 1 will not catch this while Method 2 will. For this reason alone Method 2 is to be preferred.

Definition at line 216 of file OptionsFromStreamPack_OptionsFromStream.hpp.


Member Typedef Documentation

typedef option_to_value_map_t::iterator OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::iterator

Definition at line 226 of file OptionsFromStreamPack_OptionsFromStream.hpp.

typedef option_to_value_map_t::const_iterator OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::const_iterator

Definition at line 228 of file OptionsFromStreamPack_OptionsFromStream.hpp.


Constructor & Destructor Documentation

OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::OptionsGroup (  )  [private]

OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::OptionsGroup ( option_to_value_map_t option_to_value_map  )  [inline]

Definition at line 622 of file OptionsFromStreamPack_OptionsFromStream.hpp.


Member Function Documentation

std::string & OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::option_value ( const std::string &  option_name  )  [inline]

Definition at line 575 of file OptionsFromStreamPack_OptionsFromStream.hpp.

const std::string & OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::option_value ( const std::string &  option_name  )  const [inline]

Definition at line 581 of file OptionsFromStreamPack_OptionsFromStream.hpp.

bool OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::option_exists ( const std::string &  option_value  )  [inline, static]

Definition at line 587 of file OptionsFromStreamPack_OptionsFromStream.hpp.

bool OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::options_group_exists (  )  const [inline]

Returns true if this options groups exists.

Definition at line 592 of file OptionsFromStreamPack_OptionsFromStream.hpp.

int OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::num_options (  )  const [inline]

Definition at line 597 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsGroup::iterator OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::begin (  )  [inline]

Definition at line 602 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsGroup::iterator OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::end (  )  [inline]

Definition at line 607 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsGroup::const_iterator OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::begin (  )  const [inline]

Definition at line 612 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsGroup::const_iterator OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::end (  )  const [inline]

Definition at line 617 of file OptionsFromStreamPack_OptionsFromStream.hpp.

OptionsGroup& OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::operator= ( const OptionsGroup  )  [private]


Friends And Related Function Documentation

friend class OptionsFromStream [friend]

Definition at line 220 of file OptionsFromStreamPack_OptionsFromStream.hpp.


Member Data Documentation

option_to_value_map_t* OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::option_to_value_map_ [private]

Definition at line 279 of file OptionsFromStreamPack_OptionsFromStream.hpp.

std::string OptionsFromStreamPack::OptionsFromStreamUtilityPack::OptionsGroup::option_does_not_exist_ [static, private]

Definition at line 280 of file OptionsFromStreamPack_OptionsFromStream.hpp.


The documentation for this class was generated from the following files:
Generated on Tue Jul 13 09:36:08 2010 for MOOCHO (Single Doxygen Collection) by  doxygen 1.4.7