Merge branch 'main' of feistymeow.org:feisty_meow
[feisty_meow.git] / filesystem / file_time.h
1 #ifndef FILE_TIME_CLASS
2 #define FILE_TIME_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : file_time                                                         *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 1992-$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 //! A platform independent way to obtain the timestamp of a file.
19
20 #include <basis/astring.h>
21 #include <basis/byte_array.h>
22 #include <basis/contracts.h>
23
24 #include <stdio.h>
25 #include <time.h>
26
27 namespace filesystem {
28
29 class file_time
30 : public virtual basis::hoople_standard,
31   public virtual basis::orderable
32 {
33 public:
34   file_time();  //!< sets up a bogus file_time object.
35
36   file_time(FILE *the_FILE);
37     //!< sets up the file_time information given a the file stream of interest.
38     /*!< If the stream is NULL_POINTER, then the file_time is set up with an invalid
39     time. */
40
41   file_time(const basis::astring &filename);
42     //!< this constructor operates on a file's name rather than a FILE stream.
43
44   file_time(const time_t &init);
45     //!< starts the file_time with a particular "init" time.
46
47 //hmmm: need a converter that sucks in an earth_time time_locus object.
48
49   virtual ~file_time();
50
51   DEFINE_CLASS_NAME("file_time");
52
53   virtual void text_form(basis::base_string &time_string) const;
54     //!< returns a definitive but sorta ugly version of the file's time.
55
56   virtual void readable_text_form(basis::base_string &time_string) const;
57     //!< sets "time_string" to a human readable form of the file's time.
58
59   void reset(FILE *the_FILE);
60     //!< reacquires the time from a different FILE than constructed with.
61     /*!< this also can connect a FILE to the file_time object after using the
62     empty constructor.  further, it can also be used to refresh a file's time
63     to account for changes in its timestamp. */
64
65   void reset(const basis::astring &filename);
66     //!< parallel version of reset() takes a file name instead of a stream.
67
68   void reset(const time_t &init);
69     //!< parallel version of reset() takes a time_t instead of a stream.
70
71   time_t raw() const { return _when; }
72     //!< provides the OS version of the file's timestamp.
73
74   bool set_time(const basis::astring &filename);
75     //!< sets the time for the the "filename" to the currently held time.
76
77   // Standard comparison operators between this file time and the file time
78   // "ft2".  These are meaningless if either time is invalid.
79   virtual bool less_than(const basis::orderable &ft2) const;
80   virtual bool equal_to(const basis::equalizable &ft2) const;
81
82   // supports streaming the time into and out of a byte array.
83   virtual int packed_size() const;
84   virtual void pack(basis::byte_array &packed_form) const;
85   virtual bool unpack(basis::byte_array &packed_form);
86
87 private:
88   time_t _when;  //!< our record of the file's timestamp.
89
90   int compare(const file_time &ft2) const;
91     //!< root comparison function for all the operators.
92 };
93
94 } //namespace.
95
96 #endif
97