UT/UT_String.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 *
 * Produced by:
 *      Mark Elendt
 *      Side Effects Software Inc.
 *      20 Maud St.
 *      Toronto, Ontario,  M5V 2M5
 *      Canada
 *      416-366-4607
 *
 * NAME:        Utility Library (C++)
 *
 * COMMENTS:    String class
 *
 */

#ifndef __UT_String_h__
#define __UT_String_h__

#include "UT_API.h"
#include <iostream.h>
#include <string.h>
#include <malloc.h>
#include <ctype.h>
#include <string>
#include "UT_Assert.h"
#include "UT_Algorithm.h"

#ifdef WIN32
    #define strcasecmp stricmp
    #define strncasecmp strnicmp
#endif

class UT_WorkBuffer;
class UT_String;
class UT_StringCshIO;
class UT_WorkArgs;
class UT_IStream;

//  The following lookup functions are used by cshParse.  By default,
//      varLookup simply uses getenv, exprLookup opens the command as
//      a pipe and uses the result.
UT_API extern void      UTvarLookup(const char *name, UT_String &result);
UT_API extern void      UTexprLookup(const char *name, UT_String &result);

inline bool             UTisstring(const char *s) { return s && *s; }

class UT_API UT_String {
public:
    enum UT_AlwaysDeepType { ALWAYS_DEEP };

    // make UT_String with str. If deepCopy is used, a local buffer
    // will be used. The len parameter will specify the size of
    // the local buffer (ie strncpy is used). In this case, the deepCopy
    // flag is ignored (set to 1). And if str is 0, a buffer will be
    // allocated, and initialized to ""
    UT_String(const char *str = 0, int deepCopy = 0, int len = -1);

    // This contructor will ensure the string always stores a deep copy.
    UT_String(UT_AlwaysDeepType, const char *str = 0)
        : myIsReference(false),
          myIsAlwaysDeep(true)
    { myData = str ? strdup(str) : 0; }

    // If the string we're copying always stores a deep copy then we'll
    // always store a deep copy.  This way, you can pass/return a string
    // by value.
    UT_String(const UT_String &str);
                
    ~UT_String();

    // Make a string always deep
    void         setAlwaysDeep(bool deep)
                 {
                     myIsAlwaysDeep = deep;
                     if (deep && myIsReference)
                     {
                         if (myData != NULL)
                             harden();
                         else
                         {
                             // This takes the same semantic as
                             //     str = NULL;
                             // where str is an always deep string
                             myIsReference = false;
                         }
                     }
                 }
    bool         isAlwaysDeep() const
                 {
                     return myIsAlwaysDeep;
                 }
                    
    //  Take shallow copy and make it deep.
    void         swap( UT_String &other );
    void         harden();
    void         harden(const char *s, int len = -1);
    void         hardenIfNeeded();
    void         hardenIfNeeded(const char *s);

    // Returns whether this string is hardened already.
    bool         isHard() const { return !myIsReference; }

    // Take a hard reference and make it shallow. This method makes sure
    // it gives back something you can delete, because this UT_String is
    // taking its hands off the data. Use it with care since it may lead
    // to memory leaks if, for example, you harden it again later.
    char *       steal(void)
                 {
                     if (!myIsAlwaysDeep)
                     {
                         if (myIsReference) 
                             myData = strdup(myData ? myData : ""); // harden
                         myIsReference = true;            // but say it's soft
                         return myData;
                     }
                     else
                     {
                         // return a new copy of the data without releasing
                         // ownership for always deep strings
                         return strdup(myData ? myData : "");
                     }
                 }
    
    //
    // adopt is the opposite of steal. Basically, you're giving
    // the UT_String ownership of the string.
    //
    void         adopt(char *s)
                 {
                    if (!myIsReference)
                    {
                        if (s != myData)
                            free(myData);
                    }
                    myData = s;
                    myIsReference = false;
                 }
    void         adopt(UT_String &str)
                 {
                     adopt(str.steal());
                 }

    //
    //  Return -1 on failure otherwise length of data saved
    //
    void        saveBinary(ostream &os) const   { save(os, 1); }
    void         saveAscii(ostream &os) const   { save(os, 0); }

    // use is.eof() to check eof status
    bool         load(UT_IStream &is);
    void         save(ostream &os, int binary) const;

    // Reset the string to the default constructor.
    void         clear()
                    { *this = (const char *)NULL; }

    // Prepend a string (or character)
    void         prepend(const char *prefix);
    void         prepend(char ch);

    // Append a character
    void         append(char ch);

    UT_String   &operator=(const UT_String &str);
    UT_String   &operator=(const char *str);
    UT_String   &operator+=(const char *str)
                 {
                     if (!isstring())
                     {
                        // We are an empty string, so we merely copy
                        // the incoming string rather than trying to append
                        // to it.
                        harden(str);
                     }
                     else
                     {
                        bool same = (str == myData);
                        harden();
                        if (str)
                        {
                            int mylen = (int)strlen(myData);
                            myData = (char *)realloc(myData,
                                                     mylen+strlen(str)+1);
                            if (!same)
                            {
                                strcpy(&myData[mylen], str);
                            }
                            else
                            {
                                memcpy(myData + mylen, myData, mylen);
                                myData[mylen * 2] = '\0';
                            }
                        }
                     }
                    return *this;
                 }

    UT_String   &operator+=(const UT_String &str)
                 {
                     *this += (const char *)str.myData;
                     return *this;
                 }
    unsigned     operator==(const char *str) const
                 {
                    if (!myData || !str)
                        return (!myData && !str) ? 1 : 0;
                    return (strcmp(str, myData) == 0) ? 1 : 0;
                 }
    unsigned     operator==(const UT_String &str) const
                 {
                    if (!myData || !str.myData)
                        return (!myData && !str.myData) ? 1 : 0;
                    return (strcmp(str.myData, myData) == 0) ? 1 : 0;
                 }
    unsigned     operator!=(const char *str) const
                 {
                    unsigned    rval;
                    if (!myData || !str)
                    {
                        rval = (!myData && !str) ? 0U : 1U;
                    }
                    else rval = (strcmp(str, myData) != 0) ? 1U : 0U;
                    return rval;
                 }
    unsigned     operator!=(const UT_String &str) const
                 {
                    return *this != (const char *)str.myData;
                 }
    unsigned     operator<(const char *str) const
                 {
                    unsigned    rval;
                    if (!myData)
                    {
                        if (str)
                            rval = 1;   // Yes, null ptr is < than str
                        else
                            rval = 0;           // Two nulls make an ==
                    }
                    else
                    {
                        if (!str)
                            rval = 0;   // Nope, null is < than str
                        else
                            rval = (strcmp(myData, str) < 0) ? 1U : 0U;
                    }
                    return rval;
                 }
    unsigned     operator<(const UT_String &str) const
                 {
                    return *this < (const char *)str.myData;
                 }

    unsigned     operator<=(const char *str) const
                 {
                    unsigned    rval;
                    if (!myData)
                        rval = 1;
                    else
                    {
                        if (!str)
                            rval = 0;   // Nope, null is < than str
                        else
                            rval = (strcmp(myData, str) > 0) ? 0U : 1U;
                    }
                    return rval;
                 }
    unsigned     operator<=(const UT_String &str) const
                 {
                    return *this <= (const char *)str.myData;
                 }
    unsigned     operator>(const char *str) const
                 {
                    unsigned    rval;
                    if (!myData)
                        rval = 0;
                    else
                    {
                        if (!str)
                            rval = 1;   // Nope, null is < than str
                        else
                            rval = (strcmp(myData, str) > 0) ? 1U : 0U;
                    }
                    return rval;
                 }
    unsigned     operator>(const UT_String &str) const
                 {
                    return *this > (const char *)str.myData;
                 }
    unsigned     operator>=(const char *str) const
                 {
                    unsigned    rval;
                    if (!myData)
                    {
                        if (str)
                            rval = 0;   // Nope, null ptr is < than str
                        else
                            rval = 1;           // Two nulls make an ==
                    }
                    else
                    {
                        if (!str)
                            rval = 1;   // Nope, null is < than str
                        else
                            rval = (strcmp(myData, str) < 0) ? 0U : 1U;
                    }
                    return rval;
                 }
    unsigned     operator>=(const UT_String &str) const
                 {
                    return *this >= (const char *)str.myData;
                 }

#ifdef METROWERKS_BUILD
    operator     char *() const
                 { return myData; }
#else
    operator     const char *() const
                 { return (const char *)myData; }
    operator     char *()
                 { return myData; }
#endif    
    const char  *buffer() const
                 { return myData; }
    const char  *nonNullBuffer() const
                 { return myData ? myData : ""; }
    char         operator()(unsigned i) const
                 {
                     UT_ASSERT_P( isstring() );
                     UT_ASSERT_SLOW(i <= strlen(myData));
                     return myData[i];
                 }
    char        &operator()(unsigned i) 
                 {
                     harden();
                     return myData[i];
                 }
    int          toInt() const;
    fpreal       toFloat() const;

    /// Converts the contents of this UT_String to a std::string.  Note that
    /// std::string can't be constructed with a null pointer, so you can't
    /// just write std::string s = ut_string.buffer();
    std::string toStdString() const;

    //
    //  Here, we're finished with operators
    //

    unsigned     length(void) const
                 { return (myData) ? (unsigned)strlen(myData) : 0; }
    int64        getMemoryUsage() const
                 {
                     return
                         sizeof(*this)
                         + (!myIsReference ? (length() + 1)*sizeof(char) : 0);
                 }

    char        *findChar(int c) const
                 { return (myData) ? strchr(myData, c) : 0; }

    //
    //  Like findChar(int c), but will find first occurence of any char
    //    in the string passed.
    //
    char        *findChar(const char *str) const 
                 { return (myData) ? strpbrk(myData, str) : NULL; }
    char        *findChar(const UT_String &str) const
                 { return findChar((const char *) str); }
    char        *lastChar(int c) const
                 { return myData ? strrchr(myData, c):0; }
    // Returns the number of occurrences of the specified character.
    int          countChar(int c) const;
    char        *findNonSpace() const;
    const char  *findWord(const char *word) const;
    bool         findString(const char *str, bool fullword,
                            bool usewildcards) const;
    int          changeWord(const char *from, const char *to, int all=1);
    int          changeString(const char *from, const char *to, bool fullword);
    int          changeQuotedWord(const char *from, const char *to,
                                  int quote = '`', int all = 1);

    int          findLongestCommonSuffix( const char *with );

    // Does a deep copy of the substring starting from 'index' 
    // for 'len' characters into the specified UT_String.
    // If 'len' is too long, then a substring starting from 'index' to
    // the end of the string is copied.
    // Returns the length of the copied substring.
    int          substr(UT_String &buf, int index, int len=0) const;

    //
    //  Determine if string can be seen as a single floating point number
    unsigned     isFloat(int skip_spaces = 0, int loose = 0) const;
    unsigned     isInteger(int skip_spaces = 0) const;

    void         toUpper()
                 {
                    char *ptr; 
                    harden();
                    for (ptr=myData; *ptr; ptr++)
                        *ptr = (char)toupper(*ptr);
                 }
    void         toLower()
                 {
                    char *ptr;
                    harden();
                    for (ptr=myData; *ptr; ptr++)
                        *ptr = (char)tolower(*ptr);
                 }


    // If there is a slash in the string, fileName() returns the string
    // starting after the slash.  Otherwise, it returns the contents of
    // this string.  Note that it returns a pointer into this string.
    const char  *fileName() const
                 {
                     const char         *fname;

                     if (!myData) return 0;
                     
                     fname = strrchr(myData, '/');
                     if (!fname)
                         fname = myData;
                     else
                         fname++;       // Get past the /
                     return fname;
                 }
    const char  *fileExtension( ) const
                 {
                     const char * slash;
                     const char * dot;

                     if( !isstring() )
                         return 0;

                     dot   = lastChar( '.' );
                     slash = lastChar( '/' );

                    return (slash < dot) ? dot : 0;
                 }
    // Returns path terminated just before the extension
    // If the filename starts with '.' and no path is provided,
    // returns NULL
    UT_String   pathUpToExtension() const;

    // Split a path into dir_name and file_name, where file_name is everything
    // after the final slash (i.e. the same as fileName()).  Either part may be
    // empty.  Note that if the string starts with / and only contains that one
    // slash, the dir_name will be / and not blank.  dir_name and file_name
    // will either be set to hardened strings or an empty string.
    void         splitPath(UT_String &dir_name, UT_String &file_name) const;

    // parseNumberedFileName will breakup a filename into its various
    // parts: file = prefix$Fsuffix (note: suffix is
    // not the same as file extension.) 0 is returned if there is
    // no frame number. 'negative' allows -[frame] to be interpreted as a
    // negative number. 'fractional' allows [frame].[number] to be interpreted
    // as a fractional frame.
    int          parseNumberedFilename(UT_String &prefix,
                                       UT_String &frame, 
                                       UT_String &suff, 
                                       bool negative = true,
                                       bool fractional = false) const;

    int          isstring() const
                 { return (myData && *myData); }

    // trimSpace() will remove all space characters (leading and following)
    // from a string.  If the string consists of multiple words, the words will
    // be collapsed.  The function returns 1 if space was trimmed.
    int          trimSpace(bool leaveSingleSpaceBetweenWords = false);

    // A version of trimSpace() that only removes leading and following spaces
    // from a string, leaving any between words intact.
    int          trimBoundingSpace();

    // strips out all characters found in 'chars'. The string length will be
    // reduced by the number of characters removed. The number of characters
    // removed is returned.
    int          strip(const char *chars);

    // protectString() will modify the existing string to escape double quotes
    // and backslashes.  It will not wrap the string in double quotes.
    void         protectString();

    /// returns true if the string begins and ends with a (non-escaped) quote
    /// 'delimiter'.
    bool         isQuotedString(char delimiter='\'') const;
    
    // makeQuotedString() is similar to protectString() except it returns a
    // new string instead of changing this string, it does wrap the string
    // in quotes, and it lets you use either ' or " as the delimiter.  The
    // string that's returned is UT_String::ALWAYS_DEEP.
    UT_String    makeQuotedString(char delimiter='\'') const;

    // makeSmartQuotedString() will use either ' or " as the delimiter to
    // avoid escaped quotes, using the default delimiter if it doesn't
    // matter.  The string that's returned is UT_String::ALWAYS_DEEP.
    UT_String    makeSmartQuotedString(char default_delimiter='\'') const;

    void         expandControlSequences();

    bool         hasWhiteSpace() const;

    void         removeTrailingSpace();

    void         removeTrailingDigits();

    //  cshParse() does not need to harden the string.  It does very robust
    //  parsing in the style of csh.  It actually does better parsing than
    //  csh.  Variable expansion & backquote expansion are done in the
    //  correct order for the correct arguments.  One caveat is that the
    //  string cannot have \0377 (0xff) as a character in it.
    //
    //  If there is an error in parsing, the error flag (if passed in) will be
    //  set to:
    //          0 = no error
    //          1 = line too long
    int         cshParse(char *argv[], int maxArgs,
                        void (*vlookup)(const char *, UT_String&)=UTvarLookup,
                        void (*elookup)(const char *, UT_String&)=UTexprLookup,
                        int *error = 0,
                        UT_StringCshIO *io=0);

    int         cshParse(UT_WorkArgs &argv,
                        void (*vlookup)(const char *, UT_String&)=UTvarLookup,
                        void (*elookup)(const char *, UT_String&)=UTexprLookup,
                        int *error = 0,
                        UT_StringCshIO *io=0);

    //  dosParse() uses the semi-braindead approach of ms-dos to argument
    //  parsing.  That is, arguments are separated by a double quote or space
    //  (being a space or a tab).  Back-slashes are passed through verbatim,
    //  unless the following character is a double quote.  Any pairs of
    //  back-slashes preceeding a double quote are turned into single
    //  back-slashes.
    int         dosParse(UT_WorkArgs &argv);
    int         dosParse(char *argv[], int maxArgs);

    //  parse will insert nulls into the string.
    //  NB: The argv array is null terminated, thus the effective
    //      maximum number of arguments is one less than maxArgs.
    //  NB: The maxArgs variants are all deprecated, use UT_WorkArgs
    //      instead.
    int          parse(char *argv[], int maxArgs)
                 {
                     harden();
                     return parseInPlace(argv, maxArgs);
                 }
                 // Warning: the following method inserts nulls into the
                 //     string without hardening.
    int          parseInPlace(char *argv[], int maxArgs);
    int          parse(UT_WorkArgs &argv)
                 {
                     harden();
                     return parseInPlace(argv);
                 }
    int          parseInPlace(UT_WorkArgs &argv);

    int          tokenize(char *argv[], int maxArgs, char separator)
                 {
                     harden();
                     return tokenizeInPlace(argv, maxArgs, separator);
                 }
    int          tokenizeInPlace(char *argv[], int maxArgs, char separator);
    int          tokenize(UT_WorkArgs &argv, char separator)
                 {
                     harden();
                     return tokenizeInPlace(argv, separator);
                 }
    int          tokenizeInPlace(UT_WorkArgs &argv, char separator);
    int          tokenize(char *argv[], int maxArgs,
                          const char *separators = " \t\n")
                 {
                     harden();
                     return tokenizeInPlace(argv, maxArgs, separators);
                 }
    int          tokenizeInPlace(char *argv[], int maxArgs, 
                                 const char *separators = " \t\n");
    int          tokenize(UT_WorkArgs &argv, const char *separators = " \t\n")
                 {
                     harden();
                     return tokenizeInPlace(argv, separators);
                 }
    int          tokenizeInPlace(UT_WorkArgs &argv,
                                 const char *separators = " \t\n");

    // Replaces the contents with variables expanded.
    void         expandVariables();

    //  Functions to hash a string
    inline unsigned hash() const
    {
        return hash(myData);
    }

    static inline unsigned hash(const char *str, unsigned code = 0)
    {
        char    c;

        // We are relying on the overflow behaviour of value to be good
        // old wrap-around.  That's why we use unigned so the mod will
        // also always be positive.

        // We shouldn't rely on overflow behaviour to be pure good people.
        // But hash functions are in there with random functions in the
        // realm of ugly code.  Be happy we aren't using assembly language.
        if (str)
        {
            for (; c = *str; str++)
            {
                // A note on the magic number 37.
                // We want to scale by SOMETHING so that order is preserved.
                // That something should be prime and not a power of two to
                // avoid wrapping issues.
                // That something should be larger than our range of expected
                // values to avoid interference between consecutive letters.
                // 0-9a-z is 36 letters long.
                //
                // The real reason is that this is what Perl uses.
                code = 37 * code + c;
            }
        }
        return code;
    }

    //  This does pattern matching on a string.  The pattern may include
    //  the following syntax:
    //          ? = match a single character
    //          * = match any number of characters
    //          [char_set] = matches any character in the set
    unsigned     match(const char *pattern, int caseSensitive=1) const;
    //  multiMatch will actually check multiple patterns all separated
    //  by the separator character:  i.e. geo1,geo2,foot*
    //
    //  NOTE: No pattern or may contain the separator 
    unsigned    multiMatch(const char *pattern, 
                           int caseSensitive, char separator) const;
    unsigned    multiMatch(const char *pattern, int caseSensitive = 1,
                           const char *separators = ", ",
                           bool *explicitlyExcluded = 0,
                           int *matchIndex = 0) const;

    // this method matches a pattern while recording any wildcard
    // patterns used.
    unsigned    multiMatchRecord(const char *pattern, int maxpatterns,
                                 char *singles, int &nsingles,
                                 char **words,  int &nwords,
                                 int case_sensitive = 1, 
                                 const char *separators = ", ") const;

    /// matchPattern(UT_WorkArgs &) assumes that the arguments contain the
    /// components of a pattern to be matched against.  The method returns
    /// true if the pattern matches, false if it doesn't.  This matching
    /// process handles ^ expansion properly (and efficiently).
    /// If the string doesn't match any components of the pattern, then the
    /// assumed value is returned.
    bool        matchPattern(const UT_WorkArgs &pattern_args,
                             bool assume_match=false);

    static int  multiMatchCheck(const char *pattern);
    static int  wildcardMatchCheck(const char *pattern);

    // Same as match but equivalent to "*pattern*"
    unsigned    contains(const char *pattern, int caseSensitive=1) const;
    // Returns true if our string starts with the specified prefix.
    bool        startsWith(const char *prefix) const;
    // Returns true if our string ends with the specified suffix.
    bool        endsWith(const char *suffix) const;
    bool        endsWith(const char *suffix, bool case_sensitive) const;

    // Will parse strings like 1-10:2,3 and call func for every element
    // implied.  It will stop when the func returns 0 or the parsing
    // is complete, in which case it returns 1.  
    // Parsing also allows secondary elements to be specified eg 3.4 0.12
    // The secfunc is used to find the maximum index of secondary elements
    // for each compound num. The elements are assumed to be 
    // non-negative integers.
    int          traversePattern(int max, void *data, 
                                 int (*func)(int num, int sec, void *data),
                                 unsigned int (*secfunc)(int num,void *data)=0,
                                 int offset=0) const;

    // Fast containment, assumes no special characters
    const char  *fcontain(const char *pattern) const
                 { return (myData) ? strstr(myData, pattern) : 0; }

    // Given the match pattern which fits our contents, any assigned wildcards
    // are subsitituted. The wildcards may also be indexed.
    // NB: - There is currently a maximum of 256 subpatterns, and 256 subwords
    //     - This code was adapted from CHOP_Rename::subPatterns() and
    //       works the same way
    //     - Returns true if rename was successful
    //
    // eg. this = apple, match = a*le, replace = b* ---> bpp
    //     this = a_to_b, match = *_to_*, replace = *(1)_to_*(0) ---> b_to_a
    bool patternRename(const char *match_pattern, const char *replace);

    // Given the name rule according to which a name consists of a base name
    // (char sequence ending in a non-digit) and a numerical suffix, the 
    // following two methods return the base and the suffix respectively. 
    // base() returns a newly allocated string. base() always returns a 
    // non-zero pointer, while suffix() returns 0 if no suffix is found.
    UT_String   *base(void) const;
    const char  *suffix(void) const;

    // incrementNumberedName will increment a name.  If it has a numerical
    // suffix, that suffix is incremented.  If not, "2" is appended to the
    // name.
    void         incrementNumberedName();

    // setFormat is used to set how an outstream formats its ascii output.
    // So you can use printf style formatting. eg:
    //          UT_String::setFormat(cout, "%08d") << 100;
    //
    // Note: Don't do:
    //          cout << UT_String::setFormat(cout, "%08d") << 100;
    //          ^^^^
    // Also: The formating changes (except for field width) are permanent,
    // so you'll have to reset them manually.
    //
    // TODO: A resetFormat, and a push/pop format pair.
    static ostream      &setFormat(ostream &os, const char *fmt);
    ostream             &setFormat(ostream &os);

    int          replacePrefix(const char *oldpref, 
                               const char *newpref);
    int          replaceSuffix(const char *oldsuffix, 
                               const char *newsuffix);

    // expandArrays will expand a series of tokens of the
    // form prefix[pattern]suffix into the names array
    //
    // Note: Each names[i] must be free'd after use
    //       and label is used on the non-const parse method
    int          expandArrays(char *names[], int max);

    // This routine will ensure no line is over the specified
    // number of columns.  Offending lines will be wrapped at
    // the first spaceChar or cut at exactly cols if spaceChar
    // is not found.
    // It returns one if any changes were done.
    // It currently treats tabs as single characters which should be
    // changed.
    // It will break words at hyphens if possible.
    int         format(int cols);

    // this method is similar to changeWord.. This method performs
    // a "dumb" substitution.   Return's the # of substitutions
    int         substitute( const char *find, const char *replacement,
                            bool all = true );

    // this function removes the substring at pos and len, and inserts str
    // at pos. it returns the difference (new_length - old_length)
    int         replace( int pos, int len, const char *str );

    // insert the given string at pos into this string
    int         insert(int pos, const char *str)
                    { return replace(pos, 0, str); }

    //  Does a "smart" string compare which will sort based on numbered names.
    //  That is "text20" is bigger than "text3".  In a strictly alphanumeric
    //  comparison, this would not be the case.
    static int  compareNumberedString(const char *s1, const char *s2,
                                bool case_sensitive=true);
    static int  qsortCmpNumberedString(const void *v1, const void *v2);
    static int  qsortCmpNumberedString(char *const*v1, char *const*v2);

    //  Like compare numbered strings, but it sorts better when there are
    //  .ext extensions (i.e. it handles '.' as a special case)
    static int  compareNumberedFilename(const char *s1, const char *s2,
                                bool case_sensitive=false);
    static int  qsortCmpNumberedFilename(const void *v1, const void *v2);
    static int  qsortCmpNumberedFilename(char *const*v1, char *const*v2);

    // A very fast integer to string converter.  This is faster (at least on
    // SGI) than using sprintf("%d").  About two to three times as fast.  Both
    // of these methods return the length of the string generated.
    static int  itoa(char *str, int i);
    static int  utoa(char *str, unsigned i);

    // Versions of the above functions which set into this string object
    void        itoa(int i);
    void        utoa(int i);

    // A reader-friendly version of itoa.  This places commas appropriately
    // to ensure the person can pick out the kilo points easily.
    // This can handle numbers up to 999,999,999,999,999,999.
    void        itoa_pretty(int64 val);

    // Do an sprintf into this string. This method will allocate exactly the
    // number of bytes required for the final string. If the format string is
    // bad, isstring() will return false afterwards.
    int         sprintf(const char *fmt, ...) SYS_PRINTF_CHECK_ATTRIBUTE(2, 3);

    // This will change the string into a valid C style variable name.
    // All non-alpha numerics will be converted to _.
    // If the first letter is a digit, it is prefixed with an _.
    // This returns 0 if no changes occurred, 1 if something had to
    // be adjusted.
    // Note that this does NOT force the name to be non-zero in length.
    // The safechars parameter is a string containing extra characters
    // that should be considered safe. These characters are not
    // converted to underscores.
    int         forceValidVariableName(const char *safechars = NULL);

    // This will force all non-alphanumeric characters to be underscores.
    // Returns true if any changes were required.
    bool        forceAlphaNumeric();

    // This function will calculate the relative path to get from src to dest.
    // NB: This function DOES NOT handle NT style drive names! It is currently
    //     only used for op paths. If you want to add support for this, you
    //     should add a third default parameter to do this.
    void        getRelativePath(const char *src_fullpath,
                                const char *dest_fullpath);

    // This function takes two absolute paths and returns the length of the
    // longest common path prefix, up to and including the last '/'.  This
    // means, for instance, that if fullpath1[len1-1] == '/' then all of 
    // fullpath1 is eligible as a common prefix.
    // NB: This function DOES NOT handle NT style drive names! It is currently
    //     only used for op paths. If you want to add support for this, you
    //     should add another default parameter to do this.
    static int  findLongestCommonPathPrefix(const char *fullpath1, int len1,
                                            const char *fullpath2, int len2);

    // This function tests whether we are an absolute path, and returns true or
    // false depending on whether we are.
    bool        isAbsolutePath(bool file_path=false) const;

    // This function assumes that we are an absolute path and will remove all
    // un-necessary components from it as long as we remain an absolute path.
    // We return false if an error was encountered, in which case the results
    // are unpredictable.
    bool        collapseAbsolutePath(bool file_path=false);

    // This function will make sure that the string is at most max_length
    // characters long.  If the string is longer than that, it will
    // replace the middle of the string by "...".  Returns true if the string
    // has changed and false otherwise.  max_length must be greater than 3.
    bool        truncateMiddle(int max_length);

    static const UT_String      &getEmptyString();

    /// Finds the first colon and extracts the modifier string.
    /// this string is truncated at the first colon.
    /// @param[out] modifiers Filled with the modifier string, which is
    /// everything after the first colon.
    void        extractModifiers(UT_String &modifiers);

    /// loops through a modifier string created by extractModifiers
    /// @param[in] modifiers The modifiers to apply to this string;
    /// must start with a colon
    /// @return whether any modification was performed
    bool        applyModifiers(const UT_String &modifiers);

    /// implements a few csh-style modifiers.
    /// @param mod pointer to a string starting with the modifier to apply.
    /// so, to apply a global substitute modifier :gs/l/r/ 
    /// mod should be: s/l/r
    /// @param all True if all possible modifications should be 
    /// (recursively) performed.
    /// Otherwise, at most one modification is applied.
    /// @return whether any modification was performed
    bool        applyNextModifier(const char *mod, bool all);

    static bool isValidModifier(const char c, bool have_subst);

    /// will find all valid characters including modifiers and their preceding
    /// text
    /// @return: number of modifier chars found, ie, for ":ras/foo/bar", 12
    static int  findModifiers(const char *src);

    /// This will remove the range from a string of the form foo$Fbar.ext (#-#)
    /// and return the first number from the range. If there is only 1 range 
    /// number, it will be returned. If there is no range, 0 is returned.
    /// The returned string is hardened.
    UT_String   removeRange ();

private:
    void         freeData();
    char        *myData;
    bool         myIsReference:1,
                 myIsAlwaysDeep:1;

    /// This operator saves the string to the stream via the string's
    /// saveAscii() method, protecting any whitespace (by adding quotes),
    /// backslashes or quotes in the string.
    friend UT_API ostream       &operator<<(ostream &os, const UT_String &d);
};

class UT_API UT_StringCshIO {
public:
    UT_String    myOut;         // Points to argument following '>'
    UT_String    myErr;         // Points to argument following '>&'
    UT_String    myIn;          // Points to argument following '<'
    short        myDoubleOut;   // If the argument is '>>' or '>>&'
    short        myDoubleIn;    // If the argument is '<<'
};

UT_API ostream & do_setformat(ostream &os, const char fmt[]);

UT_SWAPPER_CLASS(UT_String);

#endif

---