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.

Static Public Member Functions

bool option_exists (const std::string &option_value)

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:


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 {
  const char* SOptions[num_opt] = {
  StringToIntMap	opt_map( optgrp_name, num_opt, SOptions );
    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);
      case MAX_ITER:
        std::cout << "\noption max_iter = " << option_value(itr);
      case PROB_TYPE:
        std::cout << "\noption prob_type = " << option_value(itr);
        std::cout << "\nThe option " << option_name(itr) << " is not valid";


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:


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.

Member Function Documentation

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

Definition at line 571 of file OptionsFromStreamPack_OptionsFromStream.hpp.

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

Definition at line 577 of file OptionsFromStreamPack_OptionsFromStream.hpp.

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

Definition at line 583 of file OptionsFromStreamPack_OptionsFromStream.hpp.

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

Returns true if this options groups exists.

Definition at line 588 of file OptionsFromStreamPack_OptionsFromStream.hpp.

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

Definition at line 593 of file OptionsFromStreamPack_OptionsFromStream.hpp.

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

Definition at line 598 of file OptionsFromStreamPack_OptionsFromStream.hpp.

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

Definition at line 603 of file OptionsFromStreamPack_OptionsFromStream.hpp.

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

Definition at line 608 of file OptionsFromStreamPack_OptionsFromStream.hpp.

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

Definition at line 613 of file OptionsFromStreamPack_OptionsFromStream.hpp.

The documentation for this class was generated from the following files:
Generated on Thu Sep 18 12:33:34 2008 for MoochoPack: Miscellaneous Utilities for MOOCHO by doxygen