---

ACE_Arg_Shifter Class Reference

This ADT operates on a specified set of arguments (argv). As known arguments are scanned, they are shifted to the back of the argv vector, so deeper levels of argument parsing can locate the yet unprocessed arguments at the beginning of the vector. More...

#include <Arg_Shifter.h>

List of all members.

Public Methods
	ACE_Arg_Shifter (int &argc, const ACE_TCHAR **argv, const ACE_TCHAR **temp=0)
	ACE_Arg_Shifter (int &argc, ACE_TCHAR **argv, ACE_TCHAR **temp=0)
	Same behavior as the preceding constructor, but without the "const" qualifier. More...
	~ACE_Arg_Shifter (void)
	Destructor. More...
const ACE_TCHAR *	get_current (void) const
	Get the current head of the vector. More...
const ACE_TCHAR *	get_the_parameter (const ACE_TCHAR *flag)
int	cur_arg_strncasecmp (const ACE_TCHAR *flag)
int	consume_arg (int number=1)
	Consume number argument(s) by sticking them/it on the end of the vector. More...
int	ignore_arg (int number=1)
	Place number arguments in the same relative order ahead of the known arguments in the vector. More...
int	is_anything_left (void) const
	Returns the number of args left to see in the vector. More...
int	is_option_next (void) const
	Returns 1 if there's a next item in the vector and it begins with '-'. More...
int	is_parameter_next (void) const
	Returns 1 if there's a next item in the vector and it doesn't begin with '-'. More...
int	num_ignored_args (void) const
	Returns the number of irrelevant args seen. More...
Private Methods
	ACE_Arg_Shifter (const ACE_Arg_Shifter &)
	Copy Constructor should not be used. More...
ACE_Arg_Shifter	operator= (const ACE_Arg_Shifter &)
	Assignment '=' operator should not be used. More...
void	init (void)
	Refactor the constructor logic. More...
Private Attributes
int &	argc_
	The size of the argument vector. More...
int	total_size_
	The size of argv_. More...
const ACE_TCHAR **	temp_
	The temporary array over which we traverse. More...
const ACE_TCHAR **	argv_
	The array in which the arguments are reordered. More...
int	current_index_
	The element in <temp_> we're currently examining. More...
int	back_
	The index of <argv_> in which we'll stick the next unknown argument. More...
int	front_
	The index of <argv_> in which we'll stick the next known argument. More...

---

Detailed Description

This ADT operates on a specified set of arguments (argv). As known arguments are scanned, they are shifted to the back of the argv vector, so deeper levels of argument parsing can locate the yet unprocessed arguments at the beginning of the vector.

The ACE_Arg_Shifter copies the pointers of the argv vector into a temporary array. As the ACE_Arg_Shifter iterates over the copied vector, it places known arguments in the rear of the vector, leaving the unknown ones in the beginning. So, after having visited all the arguments in the temporary vector, ACE_Arg_Shifter has placed all the unknown arguments in their original order at the front of original argv.

Definition at line 40 of file Arg_Shifter.h.

---

Constructor & Destructor Documentation

ACE_Arg_Shifter::ACE_Arg_Shifter (  int &    argc, const ACE_TCHAR **    argv, const ACE_TCHAR **    temp = 0 )

Initialize the ACE_Arg_Shifter to the vector over which to iterate. Optionally, also provide the temporary array for use in shifting the arguments. If ACE_Arg_Shifter must allocate the temporary vector internally and dynamic allocation fails, the ACE_Arg_Shifter will set all indicators to end of the vector, forbidding iteration. Following iteration over argv, the argc value will be updated to contain the number of unconsumed arguments. Parameters: argc  The number of strings in argv. argc will be updated to reflect the number of unconsumed arguments. argv  The argument vector to shift. The string pointers in the vector will be reordered to place the argc unconsumed arguments at the front of the vector. temp  A vector of ACE_TCHAR pointers at least argc elements long. The vector will be used for argument shifting as the specified argv vector is consumed. The vector must not be modified while this object exists. If this argument is 0 (the default) the object will allocate and free the temporary vector transparently. Definition at line 12 of file Arg_Shifter.cpp. References ACE_TCHAR, and init. : argc_ (argc), total_size_ (argc), temp_ (temp), argv_ (argv), current_index_ (0), back_ (argc - 1), front_ (0) { this->init (); }

ACE_Arg_Shifter::ACE_Arg_Shifter (  int &    argc, ACE_TCHAR **    argv, ACE_TCHAR **    temp = 0 )

Same behavior as the preceding constructor, but without the "const" qualifier. Definition at line 26 of file Arg_Shifter.cpp. References ACE_TCHAR, and init. : argc_ (argc), total_size_ (argc), temp_ ((const ACE_TCHAR **) temp), argv_ ((const ACE_TCHAR **) argv), current_index_ (0), back_ (argc - 1), front_ (0) { this->init (); }

ACE_Arg_Shifter::~ACE_Arg_Shifter (  void    )

Destructor. Definition at line 66 of file Arg_Shifter.cpp. References temp_. { // Delete the temporary vector. delete [] temp_; }

ACE_Arg_Shifter::ACE_Arg_Shifter (  const ACE_Arg_Shifter &    )  [private]

Copy Constructor should not be used.

---

Member Function Documentation

int ACE_Arg_Shifter::consume_arg (  int    number = 1 )

Consume number argument(s) by sticking them/it on the end of the vector. Definition at line 145 of file Arg_Shifter.cpp. References argv_, back_, current_index_, is_anything_left, and temp_. Referenced by get_the_parameter. { int retval = 0; // Stick knowns at the end of the vector (consumed). if (this->is_anything_left() >= number) { for (int i = 0, j = this->back_ - (number - 1); i < number; ++i, ++j, ++this->current_index_) this->argv_[j] = this->temp_[this->current_index_]; this->back_ -= number; retval = 1; } return retval; }

int ACE_Arg_Shifter::cur_arg_strncasecmp (  const ACE_TCHAR *    flag )

Check if the current argument matches (case insensitive) <flag> ------------------------------------------------------------ Case A: Perfect Match (case insensitive) 0 is returned. ie: when current_arg = "-foobar" or "-FOOBAR" or "-fooBAR" this->cur_arg_strncasecmp ("-FooBar); will return 0 ------------------------------------------------------------ Case B: Perfect Match (case insensitive) but the current_arg is longer than the flag. Returns a number equal to the index in the char* indicating the start of the extra characters ie: when current_arg = "-foobar98023" this->cur_arg_strncasecmp ("-FooBar); will return 7 Notice: this number will always be > 0 ------------------------------------------------------------ Case C: If neither of Case A or B is met (no match) then -1 is returned Definition at line 112 of file Arg_Shifter.cpp. References ACE_LIB_TEXT, ACE_TCHAR, current_index_, is_anything_left, ACE_OS_String::strlen, ACE_OS_String::strncasecmp, ACE_OS_String::strspn, and temp_. Referenced by get_the_parameter. { // Check for a current argument if (this->is_anything_left()) { size_t flag_length = ACE_OS_String::strlen (flag); // Check for presence of the flag if (ACE_OS_String::strncasecmp(this->temp_[current_index_], flag, flag_length) == 0) { if (ACE_OS_String::strlen(temp_[current_index_]) == flag_length) { // match and lengths are equal return 0; } else { // matches, with more info to boot! size_t remaining = ACE_OS_String::strspn (this->temp_[current_index_] + flag_length, ACE_LIB_TEXT (" ")) + flag_length; return ACE_static_cast (int, remaining); } } } // failure return -1; }

const ACE_TCHAR * ACE_Arg_Shifter::get_current (  void    )  const

Get the current head of the vector. Definition at line 73 of file Arg_Shifter.cpp. References ACE_TCHAR, current_index_, is_anything_left, and temp_. { const ACE_TCHAR * retval = 0; if (this->is_anything_left ()) retval = this->temp_[current_index_]; return retval; }

const ACE_TCHAR * ACE_Arg_Shifter::get_the_parameter (  const ACE_TCHAR *    flag )

If the <flag> matches the current_arg of arg shifter this method will attempt to return the associated parameter value Safe to call without checking that a current arg exists In the following examples, a pointer to the char* "value" is ret eg: main -foobar value, main -FooBar value main -FOOBARvalue all of the above will all match the <flag> == -FooBar and will return a char* to "value" main -foobar 4 would succeed and return a char* to "4" main -foobar -4 does not succeed (-4 is not a parameter) but instead, would return 0 0 is returned: If the current argument does not match flag If there is no parameter found after a 'matched' flag If the flag is matched and the flag and paramter DO NOT RUN together, the flag is consumed, the parameter is returned, and the new current argument is the parameter value. ie '-foobarflag VALUE' leaves the new cur arg == "VALUE" If the flag is matched and the flag and parameter RUN together '-foobarflagVALUE', the flag is NOT consumed and the cur arg is left pointing to the entire flag/value pair Definition at line 84 of file Arg_Shifter.cpp. References ACE_TCHAR, consume_arg, cur_arg_strncasecmp, current_index_, is_anything_left, is_parameter_next, and temp_. { // the return 0's abound because this method // would otherwise be a deep if { } else { } // check to see if any arguments still exist if (!this->is_anything_left()) return 0; // check to see if the flag is the argument int offset = this->cur_arg_strncasecmp (flag); if (offset == -1) return 0; if (offset == 0) { this->consume_arg (); if (!this->is_parameter_next()) { return 0; } } // the paramter is in the middle somewhere... return this->temp_[current_index_] + offset; }

int ACE_Arg_Shifter::ignore_arg (  int    number = 1 )

Place number arguments in the same relative order ahead of the known arguments in the vector. Definition at line 165 of file Arg_Shifter.cpp. References argc_, argv_, current_index_, front_, is_anything_left, and temp_. { int retval = 0; // Keep unknowns at the head of the vector. if (this->is_anything_left () >= number) { for (int i = 0; i < number; i++, this->current_index_++, this->front_++) this->argv_[this->front_] = this->temp_[this->current_index_]; retval = 1; this->argc_ += number; } return retval; }

void ACE_Arg_Shifter::init (  void    )  [private]

Refactor the constructor logic. Definition at line 41 of file Arg_Shifter.cpp. References ACE_NEW, ACE_TCHAR, argc_, argv_, current_index_, front_, temp_, and total_size_. Referenced by ACE_Arg_Shifter. { // If not provided with one, allocate a temporary array. if (this->temp_ == 0) ACE_NEW (this->temp_, const ACE_TCHAR *[this->total_size_]); if (this->temp_ != 0) { // Fill the temporary array. this->argc_ = 0; for (int i = 0; i < this->total_size_; i++) { this->temp_[i] = this->argv_[i]; this->argv_[i] = 0; } } else { // Allocation failed, prohibit iteration. this->current_index_ = this->argc_; this->front_ = this->argc_; } }

int ACE_Arg_Shifter::is_anything_left (  void    )  const

Returns the number of args left to see in the vector. Definition at line 185 of file Arg_Shifter.cpp. References current_index_, and total_size_. Referenced by consume_arg, cur_arg_strncasecmp, get_current, get_the_parameter, ignore_arg, is_option_next, and is_parameter_next. { return this->total_size_ - this->current_index_; }

int ACE_Arg_Shifter::is_option_next (  void    )  const

Returns 1 if there's a next item in the vector and it begins with '-'. Definition at line 191 of file Arg_Shifter.cpp. References current_index_, is_anything_left, and temp_. { return this->is_anything_left () && this->temp_[this->current_index_][0] == '-'; }

int ACE_Arg_Shifter::is_parameter_next (  void    )  const

Returns 1 if there's a next item in the vector and it doesn't begin with '-'. Definition at line 198 of file Arg_Shifter.cpp. References current_index_, is_anything_left, and temp_. Referenced by get_the_parameter. { return this->is_anything_left () && this->temp_[this->current_index_][0] != '-'; }

int ACE_Arg_Shifter::num_ignored_args (  void    )  const

Returns the number of irrelevant args seen. Definition at line 205 of file Arg_Shifter.cpp. References front_. { return this->front_; }

ACE_Arg_Shifter ACE_Arg_Shifter::operator= (  const ACE_Arg_Shifter &    )  [private]

Assignment '=' operator should not be used.

---

Member Data Documentation

int& ACE_Arg_Shifter::argc_ [private]

The size of the argument vector. Definition at line 179 of file Arg_Shifter.h. Referenced by ignore_arg, and init.

const ACE_TCHAR** ACE_Arg_Shifter::argv_ [private]

The array in which the arguments are reordered. Definition at line 188 of file Arg_Shifter.h. Referenced by consume_arg, ignore_arg, and init.

int ACE_Arg_Shifter::back_ [private]

The index of <argv_> in which we'll stick the next unknown argument. Definition at line 195 of file Arg_Shifter.h. Referenced by consume_arg.

int ACE_Arg_Shifter::current_index_ [private]

The element in <temp_> we're currently examining. Definition at line 191 of file Arg_Shifter.h. Referenced by consume_arg, cur_arg_strncasecmp, get_current, get_the_parameter, ignore_arg, init, is_anything_left, is_option_next, and is_parameter_next.

int ACE_Arg_Shifter::front_ [private]

The index of <argv_> in which we'll stick the next known argument. Definition at line 199 of file Arg_Shifter.h. Referenced by ignore_arg, init, and num_ignored_args.

const ACE_TCHAR** ACE_Arg_Shifter::temp_ [private]

The temporary array over which we traverse. Definition at line 185 of file Arg_Shifter.h. Referenced by consume_arg, cur_arg_strncasecmp, get_current, get_the_parameter, ignore_arg, init, is_option_next, is_parameter_next, and ~ACE_Arg_Shifter.

int ACE_Arg_Shifter::total_size_ [private]

The size of argv_. Definition at line 182 of file Arg_Shifter.h. Referenced by init, and is_anything_left.

---

The documentation for this class was generated from the following files:

• Arg_Shifter.h
• Arg_Shifter.cpp

---