ALib.Files.TextFile.H

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
#ifndef H_ALIB_FILES_TEXTFILE
#define H_ALIB_FILES_TEXTFILE
#pragma once
#ifndef INL_ALIB
#   include "alib/alib.inl"
#endif
 
#if ALIB_FILES
#include <fstream>
#include "ALib.Files.H"
 
namespace alib { namespace files {
 
/// A rather simple text file line-reader. While this is used with the class #"TTextFile",
/// it might well be used as a standalone helper, i.e. in cases where the text file is
/// read but does not need to be stored in a vector.
/// @tparam TLocalBufferSize The size of the local buffer. If lines are wider and the local
///                          buffer is exceeded, it will be replaced by an heap-allocated
///                          buffer, which is then reused for any further line.<br>
///                          Defaults to 1024.
template <size_t TLocalBufferSize= 1024>
struct TextFileLineReader {
    std::ifstream                  IFStream; ///< The input stream opened on construction.
    NLocalString<TLocalBufferSize> Line;     ///< The line buffer.
    alib::IStreamLine              ReadOp;   ///< An <em>AString-appendable</em> object used for
                                             ///< reading.
    std::errc                      Status;   ///< Set after construction. If \b std::errc(0), the
                                             ///< filewas correctly opened.
 
  protected:
    /// Implementation of the two constructors.
    /// @param filePath   The path of the text-file to read.
    void construct( const CString& filePath )  {
        Line.DbgDisableBufferReplacementWarning();
        errno= 0;
        Path tFilePath(filePath);
        ALIB_STRINGS_TO_NARROW(filePath, nFilePath, 256)
        IFStream.open( nFilePath );
        Status= std::errc(errno);
        if ( !IFStream.is_open() ) {
            ALIB_WARNING( "FILES/TEXTFILE", "Error <{}: \"{}\"> opening input file \"{}\"",
                                            errno, std::errc(errno), filePath)
            return;
        }
        ALIB_MESSAGE( "FILES/TEXTFILE", "file \"{}\" opened for reading", filePath)
    }
  public:
 
    /// Constructor. Opens the file specified by \p{filePath}.
    /// On success, the field #"Status" will hold std::errc(0), an error code otherwise.
    /// @param filePath   The path of the text-file to read.
    TextFileLineReader( const CString& filePath )
    : ReadOp{&IFStream}
    , Status{0}                                                             { construct(filePath); }
 
    /// Alternative constructor taking a #"files::File" object instead of a file's path string.
    /// @param file  The text-file to read.
    TextFileLineReader(files::File file)
    : ReadOp{&IFStream}
    , Status{0}      { Path filePath; file.AsCursor().AssemblePath(filePath); construct(filePath); }
 
    /// Reads the next text-line into the field #".Line" and returns a \b Substring pointing to it.
    /// When the end of the file is reached, the returned object is \e nulled.\b
    /// Prior to the invocation, method #"TIStreamLine;IsEOF" may be called to detect the end of
    /// the file actively.
    /// @return The next line read, or #"NULL_STRING" when all lines were read.
    Substring NextLine()  {
        Line.Reset( ReadOp );
        if (ReadOp.IsEOF && Line.IsEmpty())
            return NULL_STRING;
        return Line;
    }
};
 
 
/// Deduction guide fixing emtplate parameter #\p{TLocalBufferSize} to its default \c 1024.
TextFileLineReader(const CString&) -> TextFileLineReader<1024>;
 
/// Deduction guide fixing emtplate parameter #\p{TLocalBufferSize} to its default \c 1024.
TextFileLineReader(files::File)    -> TextFileLineReader<1024>;
 
/// A rather simple text file reader and writer.
/// @see Reading is performed using helper type class #"TextFileLineReader",
///      which be used as a standalone helper, i.e. in cases where a text file is
///      read but does not need to be stored in a vector.
/// @tparam TNString    The string-type.
///                     This may also be a type derived from #"NString"
///                     which contains further fields available with each line of the file.
/// @tparam TAllocator  The #"lang::Allocator;allocator type" to use.
/// @tparam TLocalBufferSize The size of the local buffer. If lines are wider and the local
///                          buffer is exceeded, it will be replaced by an heap-allocated
///                          buffer, which is then reused for any further line.<br>
///                          Defaults to 1024.
template <typename TNString= NString, typename TAllocator= MonoAllocator,
                   size_t TLocalBufferSize= 1024>
class TTextFile : public lang::AllocatorMember<TAllocator>
                , public StdVectorMA<TNString>
{
  protected:
    /// The given allocator
    MonoAllocator&              allocator;
 
  public:
    /// Type definition publishing template parameter \p{TAllocator}.
    using AllocatorType     = TAllocator;
 
    /// Type definition publishing the type in the <c>std::vector</c> that this type is derived
    /// of.
    /// (As is defined with template parameter \p{TNString}.)
    using StoredType        = TNString;
 
    /// Type definition publishing the base container type.
    using Vector= StdVectorMA<TNString>;
 
    /// Constructor.
    /// @param ma The allocator to use.
    TTextFile(MonoAllocator& ma)
    : lang::AllocatorMember<TAllocator>(ma)
    , Vector(ma)
    , allocator( ma )                                                                             {}
 
    /// Returns the vector's size as \alib's signed integral type.
    /// @return The number of lines in this source file.
    constexpr integer Size()                          const noexcept { return int(Vector::size()); }
 
    /// Returns the element in the vector at the given position.<br>
    /// Note that this is the same as calling inherited <c>std::vector::at()</c>, but this method
    /// accepts any integral type for parameter \p{idx}.<br>
    /// Furthermore, this method raises an \alib_assertion in debug-builds, instead of throwing
    /// an exception.
    /// @tparam TIntegral The integral type that the index is provided by.
    /// @param  idx The index to retrieve an element for.
    /// @return A reference to the element stored at the given \p{idx}.
    template<typename TIntegral>
    [[__nodiscard__]]
    constexpr StoredType& At(TIntegral idx)             noexcept { return Vector::at(size_t(idx)); }
 
    /// <c>const</c>-version of #"At".
    /// @tparam TIntegral The integral type that the index is provided by.
    /// @param  idx The index to retrieve an element for.
    /// @return A \c const reference to the element stored at the given \p{idx}.
    template<typename TIntegral>
    [[__nodiscard__]]
    constexpr const StoredType& At(TIntegral idx) const noexcept { return Vector::at(size_t(idx)); }
 
    /// Reads the file into this vector of lines.
    /// @param filePath             The path of the file.
    /// @return <c>std::errc(0)</c> if all went well, otherwise an error code.
    std::errc  Read(const CString& filePath) {
        TextFileLineReader<TLocalBufferSize> reader(filePath);
        if ( reader.Status != std::errc(0) )
            return reader.Status;
 
        Substring line;
        while ( (line= reader.NextLine()).IsNotNull() )
            Vector::emplace_back( allocator, line );
 
        ALIB_MESSAGE( "FILES/TEXTFILE", "File \"{}\", {} lines read", filePath, Vector::size() )
 
        return std::errc(0);
    }
 
    /// Reads the file into this vector of lines.
    /// @param file  The file to read.
    /// @return <c>std::errc(0)</c> if all went well, otherwise an error code.
    std::errc  Read(files::File file) {
        Path filePath;
        file.AsCursor().AssemblePath(filePath);
        return Read(filePath);
    }
 
    /// Writes this text file to the given \p{filePath}.
    /// @param filePath     The path of the file.
    /// @return <c>std::errc(0)</c> if all went well, otherwise an error code.
    ALIB_DLL
    std::errc    Write(const String& filePath) {
        errno= 0;
        Path tFilePath(filePath);
        ALIB_STRINGS_TO_NARROW(tFilePath, nTFilePath, 256)
        std::ofstream oFile( nTFilePath.Terminate() );
        if ( !oFile.is_open() ) {
            auto result= std::errc(errno);
            ALIB_WARNING( "FILES/TEXTFILE", "Error <{}: \"{}\"> opening output file \"{}\"",
                                            errno, result, filePath)
            return result;
        }
        ALIB_MESSAGE( "FILES/TEXTFILE", "file \"{}\" opened for writing", filePath)
 
        for( auto& line : *this )
            oFile << line << std::endl;
 
        ALIB_MESSAGE( "FILES/TEXTFILE",  "File \"{}\", {} lines written", filePath, Vector::size() )
 
        return std::errc(0);
    }
 
};
 
} // namespace alib[::files]
 
/// Type alias in namespace \b alib.
/// @tparam TLocalBufferSize The size of the local buffer. If lines are wider and the local
///                          buffer is exceeded, it will be replaced by an heap-allocated
///                          buffer, which is then reused for any further line.<br>
///                          Defaults to 1024.
template <size_t TLocalBufferSize= 1024>
using     TextFileLineReader =   files::TextFileLineReader<TLocalBufferSize>;
 
/// Type alias in namespace \b alib.
/// @tparam TLocalBufferSize The size of the local buffer. If lines are wider and the local
///                          buffer is exceeded, it will be replaced by an heap-allocated
///                          buffer, which is then reused for any further line.<br>
///                          Defaults to 1024.
template <size_t TLocalBufferSize= 1024>
using     TextFile           =   files::TTextFile<NString, MonoAllocator, TLocalBufferSize>;
 
 
} // namespace [alib]
 
#endif // ALIB_FILES
 
#endif // H_ALIB_FILES_TEXTFILE