UtlString.h

Go to the documentation of this file.

//
// Copyright (C) 2006-2014 SIPez LLC.  All rights reserved.
//
// Copyright (C) 2004-2006 SIPfoundry Inc.
// Licensed by SIPfoundry under the LGPL license.
//
// Copyright (C) 2004-2006 Pingtel Corp.  All rights reserved.
// Licensed to SIPfoundry under a Contributor Agreement.
//
// $$


#ifndef _UtlString_h_
#define _UtlString_h_

// SYSTEM INCLUDES
#include <stdarg.h>

#include "os/OsDefs.h"

// APPLICATION INCLUDES
#include "utl/UtlDefs.h"
#include "utl/UtlCopyableContainable.h"

// DEFINES
#define DEFAULT_UTLSTRING_CAPACITY 100 

// MACROS
// EXTERNAL FUNCTIONS
// EXTERNAL VARIABLES
// CONSTANTS
// STRUCTS
// TYPEDEFS
// FORWARD DECLARATIONS

class UtlString : public UtlCopyableContainable
{
/* //////////////////////////// PUBLIC //////////////////////////////////// */
public:
    static const UtlContainableType TYPE;    
    static const char* ssNull;

    static const size_t UTLSTRING_NOT_FOUND; 

    static const size_t UTLSTRING_TO_END; 
    typedef enum StripType
       {
          leading=1,  
          trailing,   
          both        
       } StripType;

    typedef enum CompareCase
       {
          matchCase,    
          ignoreCase    
       } CompareCase;

// ================================================================

    UtlString();

    UtlString(const char* szSource  );
    UtlString(const char* szSource, size_t length);
    UtlString(const UtlString& source);

    UtlString(const UtlString& source, size_t length);
    virtual UtlCopyableContainable* clone() const;

// ================================================================

    UtlString& operator=(const char* szStr);

    UtlString& operator=(const UtlString& str);

// ================================================================

    size_t length() const;

    const char* data() const;
    operator const char*() const;
    size_t capacity() const;

// ================================================================

    UtlString operator() (size_t start, 
                          size_t len    
                          ) const;
    char operator()(size_t N);
// ================================================================


    UtlBoolean isNull() const;

    virtual int compareTo(const char *) const;
    int compareTo(const char *, CompareCase type) const;

    int compareTo(UtlString const *, CompareCase type) const;
    UtlBoolean contains(const char *) const;
    friend UtlBoolean operator!=(const char *, const UtlString& );

    friend UtlBoolean operator!=(const char , const UtlString& );

    friend UtlBoolean operator==(const char , const UtlString& );

    friend UtlBoolean operator==(const char *, const UtlString& );

    UtlBoolean operator==(const char *) const;

    UtlBoolean operator!=(const char *) const;

    UtlBoolean operator==(const UtlString&) const;

    UtlBoolean operator!=(const UtlString&) const;

// ================================================================

    size_t index(char c) const;
    size_t index(char c, size_t offset) const;
    size_t first(char c) const;
    size_t index(const char* ) const;
    size_t index(const char* , size_t ) const;
    size_t index(const char* , size_t , CompareCase ) const;
    size_t index(const UtlString& ) const;
    size_t index(const UtlString& match, 
                 size_t offset           
                 ) const;
    size_t index(const UtlString& , size_t , CompareCase ) const;
    size_t first(const char* ) const;
    size_t last(char s) const;
// ================================================================

    UtlString& operator+=(const char *);

    UtlString& append(const char* szStr);

    UtlString& operator+=(const UtlString& s);

    UtlString& append(const UtlString& str 
                      );

    UtlString& append(const UtlString& str, 
                      size_t position,      
                      size_t length 
                      );
    UtlString& append(const char* szStr, size_t N);

    UtlString& operator+=(const char c);

    UtlString& append(const char c);

    UtlString& appendFormat(const char* format, ... )
#ifdef __GNUC__
       /* with the -Wformat switch, this enables format string checking */
       __attribute__ ((format(printf, 2, 3)))
#endif
       ;

    UtlString& appendBinaryToString(const void* binaryData, int numBytes, int valuesPerRow = 16);
// ================================================================

    UtlString& insert(size_t position,     
                      const UtlString& src 
                      );
    UtlString& insert(size_t position,   
                      const char newChar 
                      );
    UtlString& insert(size_t position,   
                      const char* src    
                      );
    UtlString& prepend(const char* szStr);
    UtlString& insert(size_t position,   
                      const char* src,   
                      size_t sourceLenth 
                      );
// ================================================================

    void replaceAt(size_t pos,  
                              char newChar 
                              );


    UtlString& replace(const char src, const char tgt);

    UtlString& replace(size_t pos,    
                       size_t N,      
                       const char* replaceStr 
                       );
    UtlString& replace(size_t pos,             
                       size_t N,               
                       const char* replaceStr, 
                       size_t L                
                       );
    UtlString& replace(size_t pos,    
                       size_t N,      
                       const UtlString& replaceStr 
                       );
// ================================================================

    friend UtlString operator+(const UtlString& s1, const UtlString& s2);

    friend UtlString operator+(const UtlString& s,  const char* c);

    friend UtlString operator+(const char* c, const UtlString& s);

// ================================================================

    UtlString& remove(size_t pos);
    UtlString& remove(size_t pos, size_t N);
// ================================================================

    UtlString strip();

    UtlString strip(StripType whichEnd);
    UtlString strip(StripType whichEnd, char charToStrip);
// ================================================================

    void toLower();

    void toUpper();

// ================================================================

    size_t capacity(size_t N);
    void resize(size_t N, UtlBoolean clearTail=TRUE);
// ================================================================

    virtual unsigned hash() const;
    virtual UtlContainableType getContainableType() const;
    virtual int compareTo(UtlContainable const *other) const;
    virtual UtlBoolean isEqual(UtlContainable const *) const;
    virtual UtlBoolean isInstanceOf(const UtlContainableType type) const;

// ================================================================

    virtual ~UtlString();


/* //////////////////////////// PROTECTED ///////////////////////////////// */
protected:

/* //////////////////////////// PRIVATE /////////////////////////////////// */
private:
    char*  mpData;      //: The value of UtlString.
    size_t mSize;       //: The number of bytes of data used.
    size_t mCapacity;   //: The allocated size of data.
    char   mBuiltIn[DEFAULT_UTLSTRING_CAPACITY];
};

/* ============================ INLINE METHODS ============================ */

#endif    // _UtlString_h_