File indexing completed on 2024-04-14 03:40:55

 /*
     SPDX-FileCopyrightText: 2007 James B. Bowlin <bowlin@mindspring.com>
 
     SPDX-License-Identifier: GPL-2.0-or-later
 */
 
 #pragma once
 
 #include <QFile>
 #include <QObject>
 #include <QTextStream>
 
 class QString;
 
 /**
  * @class KSFileReader
  * I totally rewrote this because the earlier scheme of reading all the lines of
  * a file into a buffer before processing is actually extremely inefficient
  * because it makes it impossible to interleave file reading and data processing
  * which all modern computers can do.  It also force large data files to be
  * split up into many smaller files which made dealing with the data much more
  * difficult and made the code to read in the data needlessly complicated.  A
  * simple subclassing of QTextStream fixed all of the above problems (IMO).
  *
  * I had added periodic progress reports based on line number to several parts
  * of the code that read in large files.  So I combined that duplicated code
  * into one place which was naturally here.  The progress code causes almost
  * nothing extra to take place when reading a file that does not use it.  The
  * only thing extra is incrementing the line number.  For files that you want to
  * emit periodic progress reports, you call setProgress() once setting up the
  * message to display and the intervals the message will be emitted.  Then
  * inside the loop you call showProgress().  This is an extra call in the read
  * loop but it just does an integer compare and almost always returns.  We could
  * inline it to reduce the call overhead but I don't think it makes a bit of
  * difference considering all of the processing that takes place when we read in
  * a line from a data file.
  *
  * NOTE: We no longer close the file like the previous version did.  I've
  * changed the code where this was assumed.
  *
  * There are two ways to use this class.  One is pass in a QFile& in the
  * constructor which is included only for backward compatibility.  The preferred
  * way is to just instantiate KSFileReader with no parameters and then use the
  * open( QString fname ) method to let this class handle the file opening which
  * helps take unneeded complexity out of the calling classes.  I didn't make a
  * constructor with the filename in it because we need to be able to inform the
  * caller of an error opening the file, hence the bool open(filename) method.
  *
  *
  * -- James B. Bowlin
  */
 
 class KSFileReader : public QObject, public QTextStream
 {
     Q_OBJECT
 
   public:
     /**
      * @short this is the preferred constructor.  You can then use
      * the open() method to let this class open the file for you.
      */
     explicit KSFileReader(qint64 maxLen = 1024);
 
     /**
      * Constructor
      * @param file is a previously opened (for reading) file.
      * @param maxLen sets the maximum line length before wrapping.  Setting
      * this parameter should help efficiency.  The little max-length.pl
      * script will tell you the maximum line length of files.
      */
     explicit KSFileReader(QFile &file, qint64 maxLen = 1024);
 
     /**
      * @short opens the file fname from the QStandardPaths::AppLocalDataLocation directory and uses that
      * file for the QTextStream.
      *
      * @param fname the name of the file to open
      * @return returns true on success.  Prints an error message and returns
      * false on failure.
      */
     bool open(const QString &fname);
 
     /**
      * @short opens the file with full path fname and uses that
      * file for the QTextStream. open() locates QStandardPaths::AppLocalDataLocation behind the scenes,
      * so passing fname such that
      * QString fname = KSPaths::locate(QStandardPaths::AppLocalDataLocation, "file_name" );
      * is equivalent
      *
      * @param fname full path to directory + name of the file to open
      * @return returns true on success.  Prints an error message and returns
      * false on failure.
      */
     bool openFullPath(const QString &fname);
 
     /**
      * @return true if we are not yet at the end of the file.
      * (I added this to be compatible with existing code.)
      */
     bool hasMoreLines() const { return !QTextStream::atEnd(); }
 
     /**
      * @short increments the line number and returns the next line from the file as a QString.
      */
     inline QString readLine()
     {
         m_curLine++;
         return QTextStream::readLine(m_maxLen);
     }
 
     /** @short returns the current line number */
     int lineNumber() const { return m_curLine; }
 
     /**
      * @short Prepares this instance to emit progress reports on how much
      * of the file has been read (in percent).
      * @param label the label
      * @param lastLine the number of lines to be read
      * @param numUpdates the number of progress reports to send
      */
     void setProgress(QString label, unsigned int lastLine, unsigned int numUpdates = 10);
 
     /**
      * @short emits progress reports when required and updates bookkeeping
      * for when to send the next report.  This might seem slow at first
      * glance but almost all the time we are just doing an integer compare
      * and returning.  If you are worried about speed we can inline it.
      * It could also safely be included in the readLine() method since
      * m_targetLine is set to MAXUINT in the constructor.
      */
     void showProgress();
 
   signals:
     void progressText(const QString &message);
 
   private:
     QFile m_file;
     qint64 m_maxLen;
     unsigned int m_curLine { 0 };
 
     unsigned int m_totalLines { 0 };
     unsigned int m_targetLine { UINT_MAX };
     unsigned int m_targetIncrement { 0 };
     QString m_label;
 };