---

CdbPathName.hh

Go to the documentation of this file.

#ifndef CDB_PATH_NAME_HH
#define CDB_PATH_NAME_HH

// File and Version Information:
//      $Id: CdbPathName.hh,v 1.4 2005/08/23 18:54:59 gapon Exp $

#include "CdbBase/CdbCommon.hh"

#include <vector>
#include <string>
#include <iostream>

template< class T > class CdbIItr;

/// This class facilitates path name operations
/**
  * Details to come...
  */
class CdbPathName {

friend class CdbPathNameItr;

public:

  /// The separator of path elements
  /**
    * This separator is also used as the name of the "root" path.
    */
    static const char* separator( );

  /// Produce a name ending with the folder separator
  /**
    * The method would ensure that the output string produced out of
    * the input one has a path name separator in its end.
    *
    * EXAMPLE:
    *
    *   Input    Output
    *   -------  ------
    *   <empty>  ** ERROR **
    *   ""       ** ERROR **
    *   "/"      "/"
    *   "abc"    "abc/"
    *   "efg/"   "efg/"
    *   "xyz//"  "xyz//"
    *
    * The method won't attempt to sqeeze multiple separators as in case of
    * the "xyz//" example shown above into a single one.
    *
    * Also, the input string should not be empty (non-initialized) and its length
    * must be at least 1.
    * 
    * IMPORTANT NOTE:
    *
    *   If the input string is empty or it has zero characters then the method would
    *   crash the application. That's because the method doesn't have a clean way
    *   to tell a caller abouta wrong value of the parameter. In the end passing
    *   an empty string into this method is most likely a result of either a serious
    *   bug in an application's logic, or a sign of a memory corruption.
    */
    static std::string separatorTerminated( const std::string& theName );

public:

  /// The normal & default constructor
  /**
    * Loads the path from specified string. This constructor expects
    * a string pointer to be passed as value of the parameter. If this
    * is a null pointer or if it points onto a non-translatable string
    * then the new object will remain in the invalid state.
    *
    * @see CdbPathName::isValid()
    */
    explicit CdbPathName( const char* theStr = 0 );

  /// Construct an object from a string
  /**
    * A non-empty string is expected. Otherwise the object will be put into
    * a non-valid state.
    *
    * @see CdbPathName::isValid()
    */
    explicit CdbPathName( const std::string& theStr );

  /// The copy constructor

    CdbPathName( const CdbPathName& thePath );

  /// The destructor

    ~CdbPathName( );

  /// The assignment operator

    CdbPathName& operator=( const CdbPathName& thePath );

  /// Check if the path has the valid state
  /**
    * Any other operations with a path object can only make sense
    * if this method will return true.
    */
    bool isValid( ) const;

  /// Check if the path is an ABSOLUTE one
  /**
    * Every absolute path begins with the "root" path. The "root" path
    * itself is just a case of an absolute path.
    */
    bool isAbsolute( ) const;

  /// Check if the path corresponds to the "root" path
  /**
    * More details...
    */
    bool isRoot( ) const;

  /// Check if the path is a COMPOSITE one
  /**
    * A composite path is made from more than one simple token.
    */
    bool isComposite( ) const;

  /// Get the first element in the path
  /**
    * More details...
    */
    CdbPathName first( ) const;

  /// Get the rest of the path after (excluding) the first element
  /**
    * More details...
    */
    CdbPathName afterFirst( ) const;

  /// Get the last element in the path
  /**
    * More details...
    */
    CdbPathName last( ) const;

  /// Get the beginning of the path before (excluding) the last element
  /**
    * More details...
    */
    CdbPathName beforeLast( ) const;

  /// The explicit conversion

    std::string toString( ) const;

  /// Add one path to the other one

    CdbPathName operator+( const CdbPathName& thePath ) const;

  /// Add a C-style string to a path

    CdbPathName operator+( const char* theStr ) const;

  /// Add a C++ string to a path

    CdbPathName operator+( const std::string& theStr ) const;

  /// Return an iterator to iterate over the elements of a path
  /**
    * The iterator will return elements of the path in a form
    * of path objects.
    */
    CdbIItr<CdbPathName>* iterator( ) const;

  /// Dump the internal state of the object

    void dump( std::ostream&      theStream,
               const std::string& thePrefix = "" ) const;

private:

  /// Special constructor
  /**
    * The constructor will take a copy of the passed passed list of tokens.
    * The constructor will also recalculate the attributes of the object given
    * its new value.
    *
    * NOTE:
    *
    *   The constructor does not check for the correctness of the parameters'
    *   values.
    */
    CdbPathName( const std::vector< std::string >& theTokens    /**< a list of tokens to load. */
               );

  /// Translate specified string into tokens
  /**
    * This method will break (if successful) the specified input string into tokens,
    * update a list of tokens, and it will also try to build a full path.
    *
    * A successful completion of the method indicated by the "true" means that the path
    * object can be assigned a valid state.
    *
    * NOTE: The method doesn't change the path descriptors!
    */
    bool translateStringIntoTokens( const char* theStr );

  /// Rebuild the full path
  /**
    * The method will reconstruct a full path name of the current list of tokens.
    *
    * The operation assumes that a non-empty list of tokens has already been loaded. The correct
    * contents of the list of tokens is not assumed though.
    *
    * @see CdbPathName::isValid()
    */
    bool rebuildFullPath( );

  /// Recalculate descriptor flags: isAbsolute, isRoot and isComposite
  /**
    * NOTE: The object must be in a valid state!
    *
    * @see CdbPathName::isValid()
    */
    void recalculateDescriptorFlags( );

private:

  // The current state of the object

    bool _isValid;

  // The path descriptors

    bool _isAbsolute;
    bool _isRoot;
    bool _isComposite;

  // The path as a single string

    std::string _name;

  // The path as a list of tokens

    std::vector< std::string > _tokens;
};

inline
std::ostream&
operator<<( std::ostream&      o,
            const CdbPathName& thePathName )
{
    o << thePathName.toString( );
    return o;
}

inline
CdbPathName
operator+( const char*        theStr,
           const CdbPathName& thePath )
{
    return CdbPathName( theStr ) + thePath;
}

inline
CdbPathName
operator+( const std::string& theStr,
           const CdbPathName& thePath )
{
    return CdbPathName( theStr ) + thePath;
}

#endif  // CDB_PATH_NAME_HH

---