FileHandling.hh

/*
This file is part of the BIAS library (Basic ImageAlgorithmS).

Copyright (C) 2003-2009    (see file CONTACT for details)
  Multimediale Systeme der Informationsverarbeitung
  Institut fuer Informatik
  Christian-Albrechts-Universitaet Kiel


BIAS is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

BIAS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with BIAS; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/
#ifndef __FileHandling_hh__
#define __FileHandling_hh__

#include <bias_config.h>

#include <string>
#include <sstream>
#include <vector>
#include <iomanip>
#include <stdio.h>

#define DEFAULT_LEADING_ZEROS 5


namespace BIAS {

/**
 * @class  FileHandling
 * @brief  Functions to create, check and delete files and to handle file
 *         names, such as splitting into directory, filename and suffix.
 * @author BIAS
 * @todo   Correct handling of Win32 SAMBA paths including \\machine\...
 */
class BIASCommon_EXPORT FileHandling
{
public:
  
  /** @brief Delete directory and all contents. */
  static int RemoveDir(const std::string &subdir);
  
  /** @brief Create directory (parent directory must exist). */
  static int CreateDir(const std::string &subdir);
  
  /** @brief Create directory recursively (if any parent directory does not
            exist it will be created). */
  static int CreateDirRecursive(const std::string &dir);

  /** @brief Check if the given file exists. */
  static bool FileExists(const std::string &file);
        
  /**
    @brief Read all files in @param Dir, match against @param suffix and
    @param prefix and put into @param content. If you want to use the full
    path, set @param GetFullPath=true, otherwise only the file name is used.
  */
  static int GetDirectoryContent(const std::string &Dir,
                                 const std::string &prefix,
                                 const std::string &suffix,
                                 std::vector<std::string> &content,
                                 const bool GetFullPath = false);

  /** @brief Checks if the given file exists and is readable on file system. */
  static bool FileReadable(const std::string &filename);

  /** @brief Removes the file with the given name. Just wraps C call. */
  static inline
  bool RemoveFile(const std::string &filename)
  {
    return (remove(filename.c_str()) == 0);
  }

  /** @brief Renames or moves the file with the given name. Just wraps C call. */
  static inline
  bool MoveOrRenameFile(const std::string &oldFilename, const std::string &newFilename)
  {
    return (rename(oldFilename.c_str(), newFilename.c_str()) == 0);
  }

  /** @brief Copies the file with the given name. */
  static
  bool CopyFileTo(const std::string &oldFilename, const std::string &newFilename);

  /** @brief Converts number to string with leading zeros. */
  template <class T>
    inline static std::string toString(const T thenumber,
                                       int numzeros = DEFAULT_LEADING_ZEROS)
  {
    std::stringstream ss;
    ss << std::setfill('0')<<std::setw(numzeros)<<thenumber;
    return ss.str();
  }

  /** @brief Split full path into:
             - directory
             - file base name
             - file suffix (including dot!)
      @todo Extract machine name or IP for SMB network shares for WIN32, e.g.
            \\machine\share, and fix backslashes on WIN32.
            Fix also to make \, \\ and / work on directories!
      @author Jan Woetzel
   */
  static void SplitName(const std::string &fullname, std::string &dir,
                        std::string &base, std::string &suffix);

  /** @brief Get directory from given path and filename. */
  static std::string Directory(const std::string &fullname);

  /** @brief Get file base name without path from given path and filename. */
  static std::string Basename(const std::string &fullname);

  /** @brief Get file suffix (including dot!) from given path and filename. */
  static std::string Suffix(const std::string &fullname);

  /** @brief Get file extension (without dot!) from given path and filename. */
  static std::string Extension(const std::string &fullname);

  /** @brief Get file name (base name + suffix) without path from given path
             and filename. */
  static std::string Filename(const std::string &fullname);

  /** @brief Get path and file base name (without suffix) from given path
             and filename. */
  static std::string DirectoryAndBasename(const std::string &fullname);

  /** @brief Split full directory name into individual subdirectory names,
             e.g. /home/user/data -> ["home", "user", "data"].
      @attention If a file name is given in @param fullpath, it will be
                 returned as the last element of @param result! */
  static void SplitPath(const std::string &fullpath,
                        std::vector<std::string> &result);

  /** @brief Return lower case string of input. */
  static std::string LowerCase(const std::string &input);

  /** @brief Return upper case string of input. */
  static std::string UpperCase(const std::string &input);

  /** @brief Write compilation time/date and all command line arguments
             to an output stream. */
  static void LogCommandLine( int argc, char** argv, std::ostream &os);

  /** @brief Write compilation time/date and all command line arguments
             to a log file. */
  static void LogCommandLine(int argc, char** argv, const std::string & filename);

  /** @brief Create a string with leading zeroes from number
      @deprecated Use FileHandling::toString(n, digits) instead! */
  static std::string LeadingZeroString(const int &n,
                                       const unsigned int &digits=DEFAULT_LEADING_ZEROS);

  /** @brief Create a string containing date and time like 20060329_173054
      @author koeser */
  static std::string CurrentDateTimeString();

  /** @brief Extract numeric value from string beginning from right, e.g.
             "blah042foo.txt" --> return 42 and positions of "0" and "2". */
  static int ExtractNumberFromRight(const std::string &inStr,
                                    int &number, int &posL, int &posR );

  /** @brief Construct sequential filename from a given filename by manipulating
             the number within base part of @param refFilename of an image
             sequence given a reference filename and an offset. The number of
             leading zeroes is kept but digits may be added if required.
      @param offsetFromRef Number of frames forward or backward from ref. image
      @param stepsize Number of increment/decrement per offset

         Example:
         C:/foo/image00100bar.jpg
         ref=100, offset=2, stepsize=7 --> 114
         resultFilename --> C:/foo/image00114bar.jpg
         or:
         foo9   -> foo10
         foo009 -> foo010

      @return 0 for success, !=0 for failure.
      @author Jan Woetzel
   */
  static int FilenameSequence(const std::string &refFileName,
                              std::string &resultFilename,
                              const int &offsetFromRef,
                              const unsigned int &stepsize = 1);

  /** @brief Expand filename, e.g. tilde to home expands "~" to $HOME if set
             and $USERPROFILE otherwise.
      @author Jan Woetzel */
  static int FilenameExpansion(const std::string &in, std::string &out);

  /** @brief Return current working directory as string. */
  static std::string GetCwd();

  /** @brief Change current working directory. */
  static int ChDir(const std::string &dir);

  /** @brief Return full path of current thread/application/module/exe/dll.
      @author Jan Woetzel */
  static std::string GetApplicationPath();

  /** @brief Determines if path is absolute (starting with "/") or local. */
  static bool IsAbsolute(const std::string &path);

  /** @brief Remove a trailing slash from the path if there is one. */
  inline static std::string StripTerminatingSlash(const std::string& thepath)
  {
    if (thepath.empty()) return thepath;
    // separator for directory
#ifdef WIN32
    std::string::size_type poslastslash = thepath.rfind('\\');
#else
    std::string::size_type poslastslash = thepath.rfind('/');
#endif
    if (poslastslash == thepath.size()-1) {
      // copy everything without the trailing slash
      return thepath.substr(0, poslastslash);
    }
    // already fine, no slash at the end of path
    return thepath;
  }

  /** @brief Replace wrong slashes with respect to current operating system. */
  inline static std::string CorrectSlashes(const std::string& thepath)
  {
    // replace slash by backslash (Windows) or vice versa (Unix)
    std::string result = thepath;
#ifdef WIN32
    const std::string delimiter = "\\";
    const std::string toReplace = "/";
#else
    const std::string delimiter = "/";
    const std::string toReplace = "\\";
#endif
    std::string::size_type pos = result.find_first_of(toReplace);
    while (pos != std::string::npos) {
      result.replace(pos, 1, delimiter);
      pos = result.find_first_of(toReplace, pos+1);
    }
    return result;
  }  

private:

  /** @brief Type correct helper wrapper for tolower, required for chars. */
  static char ToLower_c(char c);

  /** @brief Type correct helper wrapper for toupper, required for chars. */
  static char ToUpper_c(char c);

}; // class

} // namespace BIAS

#endif // __FileHandling_hh__