In almost any program string objects are needed, to manupilate filenames and such. The C char* is generally too low-level and error-prone to use except for the most basic operations. Unfortunately, C++ does not have a standard string class that is widely used. So in hush, for your convenience, an additional string class is introduced providing the capabilities needed for hush programming. The actual name of the class is dvstring. Hence, if a name clash occurs, you only need to undefine string (which is otherwise defined as dvstring when you include hush/string.h. Similartly, list is an abbreviation for dvlist.
One of the particularities of the hush string class ist that it allows you to work a string in various modes, as explained below.
The string class is still under construction, that is it will very likely be extended with other features in the near future.
interface substring { auxiliary class
operator char(); to obtain character
operator char*(); to obtains (C) string
operator string&(); to obtain (hush) string
operator=(char*); to replace by (C) string
operator=(string&); to replace by (sub)string
};
interface string { <hush/string.h>
examples/hush/tutorial/util/string.c
enum { plain = 0, argcv, pair }; // modes
// Constructors and assignment
string(); // plain
string(const char* s);
string(const string& a);
string(int argc, char** argv); // argc/argv mode
string(const event*); // to deal with argc/argv in (tcl) events
string& operator=( const string& a ); // plain only
string& operator=( const char* a );
// Destructor
~string();
// Test
int length() const;
// Access and coercion
operator char*() const; // to convert to char*
char operator[](int i) const; // to behave like char*
// Comparison operators
int operator==( const string& a) const;
int operator==( const char* a) const;
// Concatenation
string operator+( const string& a ) const;
string operator+( const char* a ) const;
// Iteration -- to obtain arguments or the results of splitting
operator iter<string>&() const; // obtained by assignment
// Splitting
list<string>* split(const char* sp);
// User: (argc/argv mode)
int argc(); // no of args (in argcv mode)
string operator()(int i); // return i'th arg (shorthand)
string arg(int i = 1) ; // return i'th arg
char** argv( int i = 0 ); // return char* argv[]
// Flattening
string& flatten(int quote=0); // to flatten argc/argv pair
string& quote() { return flatten (1); }
// Unflattening -- to obtain argc/argv pair from (flat) string
int unflatten(); // does not modify stored string
// Advanced: (pair mode) -- experimental
int isassoc(); // tests for key=value format
string key(); // delivers key
string value(); // delivers value
};
The string class allows you to work in various modes. In the plain mode, a string merely encapsulates a traditional C char* string, as reflected in the constructors for this mode. In the argc/argv mode, a string encapsulates an argc/argv pair as obtained from the main function or from a (tcl) event. Notice that such a pair may also be obtained from a flat string by calling the function unflatten. For convenience, a constructor taking a pointer to an event is included. This allows you to create a string in argc/argv mode directly. Strings use reference counting to deal with copy constructors and assignment. Only when the string is actually changes a new copy is made.
Currently one can only test for the length of a string, that is the number of characters in the flat representation of the string. To obtain the number of arguments the function argc must be used. When invoking split, the number of substring can be obtained by checking the length of the resulting list.
Since string objects are supposed to behave like char* strings, an approriate type conversion operator is included. Also, the [] operator behaves as if the string where an array of characters.
To access the arguments in of an argc/argv an iterator may be obtained from the string object that encapsulates the arguments. Notice that, in accord with the hush conventions, the type parameter of the iterator is string, whereas the iterator actually delivers pointers to string objects. Iterators are obtained by assignment, as explained in iter(4). See the example below.
An iterator may also be used to access the elements of a split string. Calling split results in substrings which were originally separated by one of the characters in the arguments of split. Multiple occurrences of a splitting character are considered as a (single) splitting point. Notice that an iterator may also be obtained from the list resulting from splitting, as explained in iter(4).
The number of arguments in an argc/argv pair is delivered by the function argc(). Individual arguments may be obtained by using the application operator, or in a more explicit way by using the arg function. The (raw) argv array (which is an array of char*) can be obtained by the function argv.
Occassionally, one may need to produce a flat string from an argc/argv pair. This may be done by the flatten function or, when (Tcl) quoting is needed, by the function quote. Reversely, the unflatten function may be used to obtain an argc/argv pair from a flat string.
As an experimental feature, the string class supports the use of (key,value) attribute pairs that have the form key=value. No spaces are allowed between the = sign and the key and value strings. Quotes (as in Tcl) may be used in the value part however. To test whether an ordinary string has the key=value form, the function isassoc may be used.
The following example shows you how to deal with argc/argv pairs stored in (tcl) events.
class some_handler : public handler {
public:
some_handler() { n = 0; }
int operator()();
void red() { cout << " red " << n++; }
void blue() { cout << " blue " << n++; }
void green() { cout << " green " << n++; }
private:
int n;
};
int some_handler::operator()() {
string args = _event; // event comes from dispatch
iter<string> it = args; // iterator by assignment
string* sp = 0;
while ( sp = it() ) {
string s = *sp;
if ( s == "red" ) red();
else if ( s == "blue" ) blue();
else if ( s == "green" ) green();
else cout << " *no such color*";
}
cout << endl;
return OK;
}
A string is created from the _event
(that comes from fdispatch),
and then an iterator is obtained from that string which allows
you to inspect the respective arguments.
Since the iterator produces (pointers to) string objects,
equality can be tested using the == operator
(instead of the function strcmp as for char* objects).
See examples/hush/handler.c.
For more examples
see examples/hush/string.c.
hush -- file <hush/string.h>
|
Hush Online Technology
hush@cs.vu.nl
09/24/99 |
|
|