CTCLString

DESCRIPTION

The Tcl API provides a dynamic string type Tcl_DString. For many purposes, the C++ std::string is sufficient, however the Tcl_DString list building functions are unmatched in std::string. CTCLString is an object oriented wrapping of a Tcl_DString

METHODS

CTCLString ();
CTCLString (const char* pString) ;
CTCLString(const std::string& rString);
CTCLString(const Tcl_DString& rString);
CTCLString (const CTCLString& aCTCLString );
            

Constructs a CTCLString object. With the exception of the first constructor, which produces an empty string, all of these constructors initialize the contents of the underlying Tcl_DString with the string representation of their parameter.

CTCLString& operator= (const CTCLString& rhs);
        

Supports assignment to a CTCLString from another; rhs.

int operator== (const CTCLString& rhs);
int operator!= (const CTCLString& rhs);
int operator> (const CTCLString& rhs);
int operator< (const CTCLString& rhs);
int operator>=(const CTCLString& rhs);
int operator<=(const CTCLString& rhs);
        

Relational operators provide for lexicographic copmarisons between the object and rhs which is another CTCLString.

Tcl_DString& getString();
        

Returns a reference tothe underlying Tcl_DString of the object.

CTCLString& Append (const std::string& String,
                  Int_t nLength=-1);
CTCLString& Append (const CTCLString& String,
                  Int_t nLength=-1);
CTCLString& Append (Tcl_DString&       String,
                  Int_t nLength=-1);
CTCLString& Append (const char*            String,
                  Int_t nLength=-1);
        

Appends a section of String to the CTCLString that is being built up. The first nLength characters are appended. if nLength is -1 then all String is appended.

CTCLString& AppendElement (const Tcl_DString*  item);
CTCLString& AppendElement (const CTCLString&   item);
CTCLString& AppendElement (const std::string&  item);
CTCLString& AppendElement (const char*         item);
CTCLString& AppendElement(DFloat_t item,
                         const char* pFormat = "%f");
CTCLString& AppendElement(long     item,
                         const char* pFormat = "%i");
        

Appends item as a list element to the end of the string. If necessary quotation is performed to ensure the item is treated as a single list element. The pFormat parameter controls the conversion of non string data types to a string and is of the form of any control sequence used by sprintf. For example "i = %d" could be used to convert an integer to a label and its value which would be appended to the string as e.g. {i = 1234}

CTCLString& StartSublist ()  ;
CTCLString& EndSublist ()  ;
        

Used in conjuntion with AppendElement these start and end sublists which are list elements that consist of lists. Sublists can be nested to any depth. For example:

    CTCLString s;
    s.AppendElement("a");
    s.StartSublist();
    s.AppendElement("b");
    s.AppendElement("c");
    s.StartSublist();
    s.AppendElement("d");
    s.AppendElement("e");
    s.EndSublist();
    s.AppendElement("f");
    s.EndSublist();
    s.AppendElement("g");
            

UInt_t  Length() const ;
        

Returns the number of characters in the string.

CTCLString& Truncate (UInt_t nNewLength)  ;
        

Truncates the string to the first nNewLength characters.

Bool_t isCommand () const  ;
        

Analyzes the string and returns kfTRUE if the string is a 'well formed command'. Note that a well formed command may still have syntax and execution errors. This just ensures that a string has a balanced set of quoting characters.

Bool_t Match (const char*           Pattern) const;
Bool_t Match (std::string&      Pattern) const;
Bool_t Match (const CTCLString& Pattern) const;
        

Returns kfTRUE if the contents of the string matches the Pattern parameter. The Pattern parameter can contain all of the wildcards in glob style pattern matching. See REFERENCES below for moer information about glob style matching.

operator const char* () const;
operator std::string () const;
operator Tcl_DString* ();
    

These operators are implicit and explicit type conversion operators that allow a CTCLString object to be treated as a char* pointing to a null terminated string, a std::string object, or a Tcl_DString pointer.

SEE ALSO

Tcl_DStringAppend(3tcl), Tcl_DStringAppendElement(3tcl), Tcl_DStringEndSublist(3tcl), Tcl_DStringFree(3tcl), Tcl_DStringGetResult(3tcl), Tcl_DStringInit(3tcl), Tcl_DStringLength(3tcl), Tcl_DStringResult(3tcl), Tcl_DStringSetLength(3tcl), Tcl_DStringStartSublist(3tcl)

REFERENCES

J.K. Ousterhout Tcl and the Tk Toolkit
Addison-Wesley Professional Computing Series 1994 see section 9.2