core/library/filesystem/byte_filer.h

   1 #ifndef BYTE_FILER_CLASS
   2 #define BYTE_FILER_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : byte_filer                                                        *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2000-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include <basis/astring.h>
  19 #include <basis/byte_array.h>
  20 #include <basis/definitions.h>
  21
  22 namespace filesystem {
  23
  24 // forward declarations.
  25 class file_hider;
  26
  27 //! Provides file managment services using the standard I/O support.
  28
  29 class byte_filer
  30 {
  31 public:
  32   byte_filer();
  33     //!< constructs an object that doesn't access a file yet.
  34     /*!< use open() to make the object valid. */
  35
  36   byte_filer(const basis::astring &filename, const basis::astring &permissions);
  37     //!< opens a file "filename" as specified in "permissions".
  38     /*!< these are identical to the standard I/O permissions:
  39
  40     - "r"  - opens text file for reading.
  41     - "w"  - opens text file for writing and discards any previous contents.
  42     - "a"  - opens text file for writing at end; appends to contents.
  43     - "r+" - opens text file for update (both reading and writing).
  44     - "w+" - creates a text file for update; any previous contents are lost.
  45     - "a+" - opens or creates a text file for update, appending at end.
  46
  47     a "b" can be added to the end of these to indicate a binary file should
  48     be used instead of a text file. */
  49
  50   byte_filer(const char *filename, const char *permissions);
  51     //!< synonym for above but takes char pointers.
  52
  53   byte_filer(bool auto_close, void *opened);
  54     //!< uses a previously "opened" stdio FILE handle.  be careful!
  55     /*!< the "opened" object must be a valid FILE pointer; void * is used to
  56     avoid pulling in the stdio header.  this method will not close the file
  57     handle if "auto_close" is false. */
  58
  59   ~byte_filer();
  60
  61   static size_t file_size_limit();
  62     //!< returns the maximum size that seek and length can support.
  63     /*!< use the huge_file class if you need to exceed the stdio limits. */
  64
  65   bool open(const basis::astring &filename, const basis::astring &permissions);
  66     //!< opens a file with "filename" and "permissions" as in the constructor.
  67     /*!< if a different file had already been opened, it is closed. */
  68
  69   void close();
  70     //!< shuts down the open file, if any.
  71     /*!< open() will have to be invoked before this object can be used again. */
  72
  73   basis::astring filename() const;
  74     //!< returns the filename that this was opened with.
  75
  76   bool good();
  77     //!< returns true if the file seems to be in the appropriate desired state.
  78
  79   size_t length();
  80     //!< returns the file's total length, in bytes.
  81     /*!< this cannot accurately report a file length if it is file_size_limit()
  82     or greater. */
  83
  84   size_t tell();
  85     //!< returns the current position within the file, in terms of bytes.
  86     /*!< this is also limited to file_size_limit(). */
  87
  88   void flush();
  89     //!< forces any pending writes to actually be saved to the file.
  90
  91   enum origins {
  92     FROM_START,    //!< offset is from the beginning of the file.
  93     FROM_END,      //!< offset is from the end of the file.
  94     FROM_CURRENT   //!< offset is from current cursor position.
  95   };
  96
  97   bool seek(int where, origins origin = FROM_START);
  98     //!< places the cursor in the file at "where", based on the "origin".
  99     /*!< note that if the origin is FROM_END, then the offset "where" should
 100     be a negative number if you're trying to access the interior of the file;
 101     positive offsets indicate places after the actual end of the file. */
 102
 103   bool eof();
 104     //!< returns true if the cursor is at (or after) the end of the file.
 105
 106   int read(basis::abyte *buffer, int buffer_size);
 107     //!< reads "buffer_size" bytes from the file into "buffer".
 108     /*!< for all of the read and write operations, the number of bytes that
 109     is actually processed for the file is returned. */
 110   int write(const basis::abyte *buffer, int buffer_size);
 111     //!< writes "buffer_size" bytes into the file from "buffer".
 112
 113   int read(basis::byte_array &buffer, int desired_size);
 114     //!< reads "buffer_size" bytes from the file into "buffer".
 115   int write(const basis::byte_array &buffer);
 116     //!< writes the "buffer" into the file.
 117
 118   int read(basis::astring &buffer, int desired_size);
 119     //!< read() pulls up to "desired_size" bytes from the file into "buffer".
 120     /*!< since the read() will grab as much data as is available given that it
 121     fits in "desired_size".  null characters embedded in the file are a bad
 122     issue here; some other method must be used to read the file instead (such
 123     as the byte_array read above).  the "buffer" is shrunk to fit the zero
 124     terminator that we automatically add. */
 125
 126   int write(const basis::astring &buffer, bool add_null = false);
 127     //!< stores the string in "buffer" into the file at the current position.
 128     /*!< if "add_null" is true, then write() adds a zero terminator to what
 129     is written into the file.  otherwise just the string's non-null contents
 130     are written. */
 131
 132   int getline(basis::abyte *buffer, int desired_size);
 133     //!< reads a line of text (terminated by a return) into the "buffer".
 134   int getline(basis::byte_array &buffer, int desired_size);
 135     //!< reads a line of text (terminated by a return) into the "buffer".
 136   int getline(basis::astring &buffer, int desired_size);
 137     //!< reads a line of text (terminated by a return) into the "buffer".
 138
 139   bool truncate();
 140     //!< truncates the file after the current position.
 141
 142   void *file_handle();
 143     //!< provides a hook to get at the operating system's file handle.
 144     /*!< this is of the type FILE *, as defined by <stdio.h>. */
 145
 146 private:
 147   file_hider *_handle;  //!< the standard I/O support that we rely upon.
 148   basis::astring *_filename;  //!< holds onto our current filename.
 149   bool _auto_close;  //!< true if the object should close the file.
 150
 151   // not to be called.
 152   byte_filer(const byte_filer &);
 153   byte_filer &operator =(const byte_filer &);
 154 };
 155
 156 } //namespace.
 157
 158 #endif
 159