fileUtils.hpp

Go to the documentation of this file.

 
/** \file fileUtils.hpp
 * \brief Declarations of utilities for working with files
 *
 * \author Jared R. Males (jaredmales@gmail.com)
 *
 * \ingroup fileutils
 *
 */
 
//***********************************************************************//
// Copyright 2015-2020 Jared R. Males (jaredmales@gmail.com)
//
// This file is part of mxlib.
//
// mxlib is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// mxlib 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 General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with mxlib.  If not, see <http://www.gnu.org/licenses/>.
//***********************************************************************//
 
#ifndef filtUtils_hpp
#define filtUtils_hpp
 
#include <string>
#include <vector>
 
#include "../mxlib.hpp"
 
namespace mx
{
namespace ioutils
{
 
/** \addtogroup fileutils
 * @{
 */
 
/// Create a directory or directories
/** This will create any directories in path that don't exist.  It silently ignores already existing directories.
 *
 * \returns 0 on success, indicating the directories were created or already existed.
 * \returns -1 on error
 */
int createDirectories( const std::string &path /**< [in] the path of the directory(ies)to create */ );
 
/// Get the stem of the filename
/**
 * \returns the stem for the filename, that is without the path or extension
 */
std::string pathStem( const std::string &fname );
 
/// Get the base filename
/**
 * \returns the filename, including the extension but without the path
 */
std::string pathFilename( const std::string &fname );
 
/// Get the parent path from a filename
/**
 * \returns the parent path of the file
 */
std::string parentPath( const std::string &fname );
 
/// Get a list of file names from the specified directory, specifying a prefix, a substring to match, and an extension
/**
 * \returns a std::vector<std::string> which contains the matching file names.
 */
std::vector<std::string>
getFileNames( const std::string &directory, ///< [in] the path to the directory to search. Can not be empty.
              const std::string &prefix,   ///< [in] the file name prefix (the beginning characters of the file name) to
                                           ///< search for, if "" then not used.
              const std::string &substr,   ///< [in] a substring of the filename to earch for, if "" then not used.
              const std::string &extension ///< [in] the file name extension to search for, if "" then not used.  Note
                                           ///< that this must include the ".", as in".ext".
);
 
/// Get a list of file names from the specified directory, specifying the extension
/** \overload
 *
 * \returns a std::vector<std::string> which contains the matching file names.
 */
std::vector<std::string>
getFileNames( const std::string &directory, ///< [in] the path to the directory to search. Can not be empty.
              const std::string &extension  ///< [in] the file name extension to search for, if "" then not used.  Note
                                            ///< that this must include the ".", as in ".ext".
);
 
/// Get a list of file names from the specified directory
/** \overload
 *
 * \returns a std::vector<std::string> which contains the matching file names.
 */
std::vector<std::string>
getFileNames( const std::string &directory /**< [in] the path to the directory to search.  Can not be empty. */ );
 
/// Prepend and/or append strings to a file name, leaving the directory and extension unaltered.
/**
 * \returns the new file name
 */
std::string fileNamePrependAppend(
    const std::string &fname,   ///< [in] the original file name, possibly including a directory and extension
    const std::string &prepend, ///< [in] is the string to insert at the beginning of the file name after the path
    const std::string &append   ///< [in] is the string to insert at the end of the file name, before the extension
);
 
/// Append a string to a file name, leaving the directory and extension unaltered.
/**
 * \returns the new file name
 */
std::string fileNameAppend(
    const std::string &fname, ///< [in] the original file name, possibly including a directory and extension
    const std::string &append ///< [in] is the string to insert at the end of the file name, before the extension
);
 
/// Prepend strings to a file name, leaving the directory and extension unaltered.
/**
 * \returns the new file name
 */
std::string fileNamePrepend(
    const std::string &fname,  ///< [in] the original file name, possibly including a directory and extension
    const std::string &prepend ///< [in] is the string to insert at the beginning of the file name after the path
);
 
/// Get the next file in a numbered sequence
/** Searches for files in the path designated by basename of the form basenameXXXXextension
 * where the number of digits in XXXX is set by the \a ndigit parameter.
 *
 * \warning this does not currently detect missing files in the sequence, e.g. if you have 0,1,3 in the directory this
 * will start with 2!
 *
 * \todo switch to using a regex or something so we can detect the missing file.
 *
 * \retval std::string containing the next filename.
 *
 * \test Verify creation of sequential file names \ref tests_ioutils_fileUtils_getSequentialFilename "[test doc]"
 */
std::string getSequentialFilename(
    const std::string &basename,       ///< [in] path and initial name of the file
    const std::string &extension = "", ///< [in] [optional] extension to append after the number. Default is empty.
    const int startat = 0,             ///< [in] [optional] number to start the search from.  Default is 0.
    int ndigit = 4 ///< [in] [optional] number of digits in string representation of the number.  Default is 4.
);
 
/// Get the size in bytes of a file
/** Uses fstat.
 *
 * \returns the file size if fd is valid and no errors occur
 * \returns -1 on an error
 */
off_t fileSize( int fd /**< [in] an open file descriptor */ );
 
/// Get the size in bytes of a file pointed to by a FILE pointer
/** Uses fileno to get the associated descriptor, then uses fstat.
 *
 * \returns the file size if fd is valid and no errors occur
 * \returns -1 on an error
 *
 * \overload
 */
off_t fileSize( FILE *f /**< [in] an open file */ );
 
///@} -fileutils
 
} // namespace ioutils
} // namespace mx
 
#endif // fileUtils_hpp