vinstant.h

Go to the documentation of this file.

/*
Copyright c1997-2014 Trygve Isaacson. All rights reserved.
This file is part of the Code Vault version 4.1
http://www.bombaydigital.com/
License: MIT. See LICENSE.md in the Vault top level directory.
*/

#ifndef vinstant_h
#define vinstant_h

#include "vtypes.h"

#include "vstring.h"

class VCodePoint;
class VInstant;
class VDate;
class VTimeOfDay;
class VDateAndTime;
class VInstantFormatter;

class VDuration {
    public:

        static const VDuration& ZERO();        
        static const VDuration& MILLISECOND(); 
        static const VDuration& SECOND();      
        static const VDuration& MINUTE();      
        static const VDuration& HOUR();        
        static const VDuration& DAY();         

        static const VDuration& UNSPECIFIED();         
        static const VDuration& NEGATIVE_INFINITY();   
        static const VDuration& POSITIVE_INFINITY();   

        VDuration() : mDurationMilliseconds(0) {}
        VDuration(const VDuration& d) : mDurationMilliseconds(d.mDurationMilliseconds) {}
        VDuration(const VInstant& sinceWhen);
        ~VDuration() {}

        static VDuration createFromDurationString(const VString& s);

        VDuration& operator=(const VDuration& d) { if (this != &d) mDurationMilliseconds = d.getDurationMilliseconds(); return *this; }
        VDuration& operator+=(const VDuration& forwardOffset);
        VDuration& operator-=(const VDuration& backwardOffset);
        VDuration& operator*=(Vs64 multiplier);
        VDuration& operator/=(int divisor);
        VDuration& operator%=(const VDuration& divisor);
        VDuration operator-() const;

        Vs64 getDurationMilliseconds() const { return mDurationMilliseconds; }
        int getDurationSeconds() const { return static_cast<int>(mDurationMilliseconds / kMillisecondsPerSecond); }
        int getDurationMinutes() const { return static_cast<int>(mDurationMilliseconds / kMillisecondsPerMinute); }
        int getDurationHours() const { return static_cast<int>(mDurationMilliseconds / kMillisecondsPerHour); }
        int getDurationDays() const { return static_cast<int>(mDurationMilliseconds / kMillisecondsPerDay); }
        VString getDurationString() const;
        VString getDurationStringFractionalSeconds() const;

        void setDurationMilliseconds(Vs64 durationMilliseconds) { mDurationMilliseconds = durationMilliseconds; }
        void setDurationSeconds(int durationSeconds) { mDurationMilliseconds = kMillisecondsPerSecond * static_cast<Vs64>(durationSeconds); }
        void setDurationMinutes(int durationMinutes) { mDurationMilliseconds = kMillisecondsPerMinute * static_cast<Vs64>(durationMinutes); }
        void setDurationHours(int durationHours) { mDurationMilliseconds = kMillisecondsPerHour * static_cast<Vs64>(durationHours); }
        void setDurationDays(int durationDays) { mDurationMilliseconds = kMillisecondsPerDay * static_cast<Vs64>(durationDays); }

        void setDurationString(const VString& s);

        friend inline bool operator==(const VDuration& lhs, const VDuration& rhs);  
        friend inline bool operator!=(const VDuration& lhs, const VDuration& rhs);  
        friend inline bool operator< (const VDuration& lhs, const VDuration& rhs);  
        friend inline bool operator<=(const VDuration& lhs, const VDuration& rhs);  
        friend inline bool operator>=(const VDuration& lhs, const VDuration& rhs);  
        friend inline bool operator> (const VDuration& lhs, const VDuration& rhs);  
        friend inline VDuration operator+(const VDuration& d1, const VDuration& d2);
        friend inline VDuration operator-(const VDuration& d1, const VDuration& d2);
        friend inline VDuration operator*(Vs64 multiplier, const VDuration& d1);    
        friend inline VDuration operator*(const VDuration& d1, Vs64 multiplier);    
        friend VDuration operator/(const VDuration& d, int divisor);                
        friend VDuration operator%(const VDuration& d, const VDuration& divisor);   

        static inline VDuration min(const VDuration& d1, const VDuration& d2);      
        static inline VDuration max(const VDuration& d1, const VDuration& d2);      
        static inline VDuration abs(const VDuration& d);                            

        bool isComparable() const { return (*this != VDuration::UNSPECIFIED()); }
        bool isSpecific() const { return (*this != VDuration::UNSPECIFIED()) && (*this != VDuration::NEGATIVE_INFINITY()) && (*this != VDuration::POSITIVE_INFINITY()); }
        static bool areValuesSpecific(const VDuration& d1, const VDuration& d2) { return d1.isSpecific() && d2.isSpecific(); }

    private:

        // These are called by the friend inline comparison operators for comparing non-simple durations.
        static VDuration _complexAdd(const VDuration& d1, const VDuration& d2);
        static VDuration _complexSubtract(const VDuration& d1, const VDuration& d2);
        static VDuration _complexMultiply(const VDuration& d, Vs64 multiplier);
        static VDuration _complexMin(const VDuration& d1, const VDuration& d2);
        static VDuration _complexMax(const VDuration& d1, const VDuration& d2);
        static VDuration _complexAbs(const VDuration& d);

        // This is the private constructor used internally.
        explicit VDuration(Vs64 durationMilliseconds) : mDurationMilliseconds(durationMilliseconds) {}

        Vs64 mDurationMilliseconds; 

        // These are used internally for conversion.
        static const Vs64 kMillisecondsPerSecond = CONST_S64(1000);
        static const Vs64 kMillisecondsPerMinute = CONST_S64(60000);
        static const Vs64 kMillisecondsPerHour = CONST_S64(3600000);
        static const Vs64 kMillisecondsPerDay = CONST_S64(86400000);
};

// Inline implementations of some of the above VDuration operators.
// For non-specific values, some operators need to call more complicated functions to provide
// sensible values.
inline bool operator==(const VDuration& lhs, const VDuration& rhs) { return lhs.mDurationMilliseconds == rhs.mDurationMilliseconds; }
inline bool operator!=(const VDuration& lhs, const VDuration& rhs) { return !operator==(lhs, rhs); }
inline bool operator< (const VDuration& lhs, const VDuration& rhs) { return lhs.mDurationMilliseconds < rhs.mDurationMilliseconds; }
inline bool operator<=(const VDuration& lhs, const VDuration& rhs) { return !operator>(lhs, rhs); }
inline bool operator>=(const VDuration& lhs, const VDuration& rhs) { return !operator<(lhs, rhs); }
inline bool operator> (const VDuration& lhs, const VDuration& rhs) { return  operator<(rhs, lhs); }
inline VDuration operator+(const VDuration& d1, const VDuration& d2) { if (VDuration::areValuesSpecific(d1, d2)) return VDuration(d1.mDurationMilliseconds + d2.mDurationMilliseconds); else return VDuration::_complexAdd(d1, d2); }
inline VDuration operator-(const VDuration& d1, const VDuration& d2) { if (VDuration::areValuesSpecific(d1, d2)) return VDuration(d1.mDurationMilliseconds - d2.mDurationMilliseconds); else return VDuration::_complexSubtract(d1, d2); }
inline VDuration operator*(Vs64 multiplier, const VDuration& d) { if (d.isSpecific()) return VDuration(d.mDurationMilliseconds * multiplier); else return VDuration::_complexMultiply(d, multiplier); }
inline VDuration operator*(const VDuration& d, Vs64 multiplier) { if (d.isSpecific()) return VDuration(d.mDurationMilliseconds * multiplier); else return VDuration::_complexMultiply(d, multiplier); }
inline VDuration VDuration::min(const VDuration& d1, const VDuration& d2) { if (VDuration::areValuesSpecific(d1, d2)) return (d1 < d2) ? d1 : d2; else return VDuration::_complexMin(d1, d2); }
inline VDuration VDuration::max(const VDuration& d1, const VDuration& d2) { if (VDuration::areValuesSpecific(d1, d2)) return (d1 > d2) ? d1 : d2; else return VDuration::_complexMax(d1, d2); }
inline VDuration VDuration::abs(const VDuration& d) { if (d.isSpecific()) return (d.mDurationMilliseconds < CONST_S64(0)) ? -d : d; else return VDuration::_complexAbs(d); }

typedef std::vector<VDuration> VDurationVector;

class VInstantStruct {
    public:
        VInstantStruct() : mYear(0), mMonth(1), mDay(1), mHour(0), mMinute(0), mSecond(0), mMillisecond(0), mDayOfWeek(0) {}
        VInstantStruct(const VDate& date, const VTimeOfDay& timeOfDay);
        
        Vs64 getOffsetFromUTCStruct() const;
        Vs64 getOffsetFromLocalStruct() const;
        void setUTCStructFromOffset(Vs64 offset);
        void setLocalStructFromOffset(Vs64 offset);
        
        void getTmStruct(struct tm& fields) const;
        void setFromTmStruct(const struct tm& fields, int millisecond);

        int mYear;          
        int mMonth;         
        int mDay;           
        int mHour;          
        int mMinute;        
        int mSecond;        
        int mMillisecond;   
        int mDayOfWeek;     

    private:

        // These are the 3 platform-defined helper functions for converting between
        // offsets and UTC or local broken-down time struct. There isn't one for
        // "from UTC struct" because it is not per-platform; if timegm is available
        // we call it, otherwise we implement it directly.

        static Vs64 _platform_offsetFromLocalStruct(const VInstantStruct& when);
        static void _platform_offsetToLocalStruct(Vs64 offset, VInstantStruct& when);
        static void _platform_offsetToUTCStruct(Vs64 offset, VInstantStruct& when);

        static void _threadsafe_localtime(const time_t epochOffset, struct tm* resultStorage);
        static void _threadsafe_gmtime(const time_t epochOffset, struct tm* resultStorage);

};

class IVRemoteTimeZoneConverter {
    public:

        virtual void offsetToRTZStruct(Vs64 offset, const VString& timeZoneID, VInstantStruct& when) = 0;
        virtual Vs64 offsetFromRTZStruct(const VString& timeZoneID, const VInstantStruct& when) = 0;

    protected:

        IVRemoteTimeZoneConverter() {}
        virtual ~IVRemoteTimeZoneConverter() {}

};

class VInstant {
    public:

        static const VInstant& INFINITE_PAST();
        static const VInstant& INFINITE_FUTURE();
        static const VInstant& NEVER_OCCURRED();

        static const VString& UTC_TIME_ZONE_ID();
        static const VString& LOCAL_TIME_ZONE_ID();

        static VInstant instantFromRawValue(Vs64 value) { return VInstant(value); }

        static VInstant instantFromPosixTime(time_t value) { return VInstant(CONST_S64(1000) * static_cast<Vs64>(value)); }

        VInstant();
        VInstant(const VInstant& i) : mValue(i.mValue) {}
        ~VInstant() {}

        VInstant& operator=(const VInstant& i);
        VInstant& operator+=(const VDuration& forwardOffsetDuration);
        VInstant& operator-=(const VDuration& backwardOffsetDuration);
        void setNow();
        void setTrueNow();
        VInstantStruct getUTCInstantFields() const;
        VInstantStruct getLocalInstantFields() const;
        
        /*
        There are two flavors of string conversion -- UTC and local -- and each one has
        a modern form and a legacy form.
        
        The modern form returns the string, and is supplied a VInstantFormatter to control
        the format; there are several preset formatters available in VInstantFormatter.
        If you omit the formatter you get the same format that the legacy API provided
        prior to Vault 4.0, for backward compatibility.
        
        The legacy form puts the string into a read-write parameter and has optional
        parameters to control whether milliseconds are included and whether punctuation
        is stripped out to make the string safe to use as a file system node name.
        */
        
        // Modern APIs starting with Vault 4.0:
        
        VString getUTCString() const;
        VString getUTCString(const VInstantFormatter& formatter) const;
        VString getLocalString() const;
        VString getLocalString(const VInstantFormatter& formatter) const;

        // Legacy APIs:

        void getUTCString(VString& s, bool fileNameSafe = false, bool wantMilliseconds = true) const;
        void getLocalString(VString& s, bool fileNameSafe = false, bool wantMilliseconds = true) const;

        void setUTCString(const VString& s);
        void setLocalString(const VString& s);

        bool isSpecific() const { return (*this != VInstant::NEVER_OCCURRED()) && (*this != VInstant::INFINITE_PAST()) && (*this != VInstant::INFINITE_FUTURE()); }
        bool isComparable() const { return (*this != VInstant::NEVER_OCCURRED()); }
        Vs64 getValue() const { return mValue; }
        void setValue(Vs64 value) { mValue = value; }
        VDate getLocalDate() const;
        VDate getDate(const VString& timeZoneID) const;
        VTimeOfDay getLocalTimeOfDay() const;
        VTimeOfDay    getTimeOfDay(const VString& timeZoneID) const;
        VDateAndTime getLocalDateAndTime() const;
        VDateAndTime getDateAndTime(const VString& timeZoneID) const;
        void setLocalDateAndTime(const VDateAndTime& dt);
        void setDateAndTime(const VDateAndTime& dt, const VString& timeZoneID);
        void getValues(VDate& date, VTimeOfDay& timeOfDay, const VString& timeZoneID) const;
        void setValues(const VDate& date, const VTimeOfDay& timeOfDay, const VString& timeZoneID);
        Vs64 getLocalOffsetMilliseconds() const;

        friend inline bool operator==(const VInstant& lhs, const VInstant& rhs);    
        friend inline bool operator!=(const VInstant& lhs, const VInstant& rhs);    
        friend inline bool operator< (const VInstant& lhs, const VInstant& rhs);    
        friend inline bool operator<=(const VInstant& lhs, const VInstant& rhs);    
        friend inline bool operator>=(const VInstant& lhs, const VInstant& rhs);    
        friend inline bool operator> (const VInstant& lhs, const VInstant& rhs);    
        friend inline VDuration operator-(const VInstant& i1, const VInstant& i2);  
        friend inline VInstant operator+(const VInstant& i1, const VDuration& forwardDuration);    
        friend inline VInstant operator-(const VInstant& i1, const VDuration& backwardDuration);

        static inline VInstant min(const VInstant& i1, const VInstant& i2); 
        static inline VInstant max(const VInstant& i1, const VInstant& i2); 

        static Vs64 snapshot();
        static VDuration snapshotDelta(Vs64 snapshotValue);

        static void setRemoteTimeZoneConverter(IVRemoteTimeZoneConverter* converter);
        static IVRemoteTimeZoneConverter* getRemoteTimeZoneConverter();

        // Time simulation features. Note that if "frozen time" is in effect, the
        // "clock offset" information is not used.
        static void incrementSimulatedClockOffset(const VDuration& delta);
        static void setSimulatedClockOffset(const VDuration& offset);
        static void setSimulatedClockValue(const VInstant& simulatedCurrentTime);
        static VDuration getSimulatedClockOffset();
        static void freezeTime(const VInstant& frozenTimeValue);
        static void shiftFrozenTime(const VDuration& delta);
        static void unfreezeTime();
        static bool isTimeFrozen();

    private:

        // This is the private constructor used internally.
        explicit VInstant(Vs64 utcOffsetMilliseconds) : mValue(utcOffsetMilliseconds) {}

        Vs64 mValue; 

        static bool canCompareValues(const VInstant& i1, const VInstant& i2) { return i1.isSpecific() && i2.isSpecific(); }
        static bool _complexGT(const VInstant& i1, const VInstant& i2);
        static bool _complexGTE(const VInstant& i1, const VInstant& i2);
        static bool _complexLT(const VInstant& i1, const VInstant& i2);
        static bool _complexLTE(const VInstant& i1, const VInstant& i2);

        /*
        These are the core function interfaces that must be implemented on a
        per-platform basis. That is, they are platform-specific and are
        implemented in the vinstant_platform.* files. All other time
        conversion is performed via these calls. This allows us to isolate
        the platform and library quirks in those files rather than conditionally
        compile code in vinstant.cpp.

        There are only two types used here.
        - The 64-bit millisecond "offset" from UTC 1970. This is also what VInstant
          uses an offset. We'll just refer to this as a UTC Epoch Offset.
        - The y/m/d/h/m/s "struct" in some time zone. We'll just refer to this
          as a "Time Struct".

        It's all about converting between them.

        There is one additional function, _platform_snapshot(), which is not about
        time conversion, but just about measuring short time durations with
        millisecond resolution.
        */

        static Vs64 _platform_now();
        static Vs64 _platform_snapshot();

        static Vs64 gSimulatedClockOffset; 
        static Vs64 gFrozenClockValue;     
        static IVRemoteTimeZoneConverter* gRemoteTimeZoneConverter; 

        // Let VDate call the getTimeValue() bottleneck for getting the day of
        // week, but don't make it a public API since it's exposing the tm
        // structure which is dependent on time.h functionality.
        friend class VDate;
        friend class VInstantUnit;  // Let unit test validate our internal APIs.
};

// Inline implementations of some of the above VInstant operators.
inline bool operator==(const VInstant& lhs, const VInstant& rhs) { return lhs.mValue == rhs.mValue; }
inline bool operator!=(const VInstant& lhs, const VInstant& rhs) { return !operator==(lhs, rhs); }
inline bool operator< (const VInstant& lhs, const VInstant& rhs) { if (VInstant::canCompareValues(lhs, rhs)) return lhs.mValue < rhs.mValue; else return VInstant::_complexLT(lhs, rhs); }
inline bool operator<=(const VInstant& lhs, const VInstant& rhs) { if (VInstant::canCompareValues(lhs, rhs)) return lhs.mValue <= rhs.mValue; else return VInstant::_complexLTE(lhs, rhs); }
inline bool operator>=(const VInstant& lhs, const VInstant& rhs) { if (VInstant::canCompareValues(lhs, rhs)) return lhs.mValue >= rhs.mValue; else return VInstant::_complexGTE(lhs, rhs); }
inline bool operator> (const VInstant& lhs, const VInstant& rhs) { if (VInstant::canCompareValues(lhs, rhs)) return lhs.mValue > rhs.mValue; else return VInstant::_complexGT(lhs, rhs); }
inline VDuration operator-(const VInstant& i1, const VInstant& i2) { if (VInstant::canCompareValues(i1, i2)) return VDuration::MILLISECOND() * (i1.mValue - i2.mValue); else return VDuration(); }
inline VInstant operator+(const VInstant& i1, const VDuration& forwardDuration) { VInstant result = i1; result += forwardDuration; return result; }
inline VInstant operator-(const VInstant& i1, const VDuration& backwardDuration) { VInstant result = i1; result -= backwardDuration; return result; }
inline VInstant VInstant::min(const VInstant& i1, const VInstant& i2) { return (i1 < i2) ? i1 : i2; }
inline VInstant VInstant::max(const VInstant& i1, const VInstant& i2) { return (i1 > i2) ? i1 : i2; }

typedef std::vector<VInstant> VInstantVector;

class VDate {
    public:
    
        static VDate createFromDateString(const VString& dateString, const VCodePoint& delimiter);

        VDate();
        VDate(const VString& timeZoneID);
        VDate(int year, int month, int day);
        virtual ~VDate() {}

        int getYear() const;
        int getMonth() const;
        int getDay() const;
        int getDayOfWeek() const;
        void set(int year, int month, int day);
        void setYear(int year);
        void setMonth(int month);
        void setDay(int day);

        // These static functions can be extended in the future to
        // return values based on the locale.

        static const VCodePoint& getLocalDateSeparator() { return kLocalDateSeparator; }

        enum {
            kYMD,   
            kYDM,   
            kMYD,   
            kMDY,   
            kDYM,   
            kDMY    
        };

        static int getLocalDateOrder() { return kMDY; }

        enum {
            kSunday = 0,
            kMonday,
            kTuesday,
            kWednesday,
            kThursday,
            kFriday,
            kSaturday
        };

        friend inline bool operator==(const VDate& lhs, const VDate& rhs);    
        friend inline bool operator!=(const VDate& lhs, const VDate& rhs);    
        friend inline bool operator< (const VDate& lhs, const VDate& rhs);    
        friend inline bool operator<=(const VDate& lhs, const VDate& rhs);    
        friend inline bool operator>=(const VDate& lhs, const VDate& rhs);    
        friend inline bool operator> (const VDate& lhs, const VDate& rhs);    

    private:

        void _assertInvariant() const;

        int mYear;  
        int mMonth; 
        int mDay;   

        static const VCodePoint kLocalDateSeparator; 
};

inline bool operator==(const VDate& lhs, const VDate& rhs) { return (lhs.mYear == rhs.mYear) && (lhs.mMonth == rhs.mMonth) && (lhs.mDay == rhs.mDay); }
inline bool operator!=(const VDate& lhs, const VDate& rhs) { return !operator==(lhs, rhs); }
inline bool operator< (const VDate& lhs, const VDate& rhs) {
    if (lhs.mYear < rhs.mYear) return true;
    if (lhs.mYear > rhs.mYear) return false;
    if (lhs.mMonth < rhs.mMonth) return true;
    if (lhs.mMonth > rhs.mMonth) return false;
    return (lhs.mDay < rhs.mDay);
}
inline bool operator<=(const VDate& lhs, const VDate& rhs) { return !operator>(lhs, rhs); }
inline bool operator>=(const VDate& lhs, const VDate& rhs) { return !operator<(lhs, rhs); }
inline bool operator> (const VDate& lhs, const VDate& rhs) { return  operator<(rhs, lhs); }

class VTimeOfDay {
    public:

        VTimeOfDay();
        VTimeOfDay(const VString& timeZoneID);
        VTimeOfDay(int hour, int minute, int second, int millisecond);
        virtual ~VTimeOfDay() {}

        int getHour() const;
        int getMinute() const;
        int getSecond() const;
        int getMillisecond() const;
        void set(int hour, int minute, int second, int millisecond);
        void setHour(int hour);
        void setMinute(int minute);
        void setSecond(int second);
        void setMillisecond(int millisecond);
        void setToStartOfDay();

        // These static functions can be extended in the future to
        // return values based on the locale.

        static const VCodePoint& getLocalTimeSeparator() { return kLocalTimeSeparator; }

        friend inline bool operator==(const VTimeOfDay& t1, const VTimeOfDay& t2);

    private:

        void _assertInvariant() const;

        int mHour;          
        int mMinute;        
        int mSecond;        
        int mMillisecond;   

        static const VCodePoint kLocalTimeSeparator;    
};

inline bool operator==(const VTimeOfDay& t1, const VTimeOfDay& t2) { return (t1.mHour == t2.mHour) && (t1.mMinute == t2.mMinute) && (t1.mSecond == t2.mSecond) && (t1.mMillisecond == t2.mMillisecond); }

class VDateAndTime {
    public:

        VDateAndTime() : mDate(), mTimeOfDay() {}
        VDateAndTime(const VString& timeZoneID);
        VDateAndTime(int inYear, int inMonth, int inDay, int inHour, int inMinute, int inSecond, int inMillisecond) :
            mDate(inYear, inMonth, inDay), mTimeOfDay(inHour, inMinute, inSecond, inMillisecond) {}
        ~VDateAndTime() {}

        // Use these accessors to call the date and time of day sub-objects directly.
        const VDate& getDate() const { return mDate; }
        const VTimeOfDay& getTimeOfDay() const { return mTimeOfDay; }

        int getYear() const { return mDate.getYear(); }
        int getMonth() const { return mDate.getMonth(); }
        int getDay() const { return mDate.getDay(); }
        int getDayOfWeek() const { return mDate.getDayOfWeek(); }
        int getHour() const { return mTimeOfDay.getHour(); }
        int getMinute() const { return mTimeOfDay.getMinute(); }
        int getSecond() const { return mTimeOfDay.getSecond(); }
        int getMillisecond() const { return mTimeOfDay.getMillisecond(); }

        void set(int inYear, int inMonth, int inDay, int inHour, int inMinute, int inSecond, int inMillisecond) {
            mDate.set(inYear, inMonth, inDay); mTimeOfDay.set(inHour, inMinute, inSecond, inMillisecond);
        }

        void setYear(int year) { mDate.setYear(year); }
        void setMonth(int month) { mDate.setMonth(month); }
        void setDay(int day) { mDate.setDay(day); }
        void setHour(int hour) { mTimeOfDay.setHour(hour); }
        void setMinute(int minute) { mTimeOfDay.setMinute(minute); }
        void setSecond(int second) { mTimeOfDay.setSecond(second); }
        void setMillisecond(int millisecond) { mTimeOfDay.setMillisecond(millisecond); }
        void setToStartOfDay() { mTimeOfDay.setToStartOfDay(); }

        friend inline bool operator==(const VDateAndTime& dt1, const VDateAndTime& dt2);

    private:

        VDate       mDate;
        VTimeOfDay  mTimeOfDay;
};

inline bool operator==(const VDateAndTime& dt1, const VDateAndTime& dt2) { return (dt1.mDate == dt2.mDate) && (dt1.mTimeOfDay == dt2.mTimeOfDay); }

// VInstantFormatterLocaleInfo -----------------------------------------------

class VInstantFormatterLocaleInfo {
    public:
    
        static const VInstantFormatterLocaleInfo& getLocaleInfo(const VString& localeName);

        VInstantFormatterLocaleInfo();
        ~VInstantFormatterLocaleInfo() {}
        
        // The instance variables are public since they are just data, which you can
        // build if you are setting up your own locale object.

        VString         CE_MARKER;              
        VString         AM_MARKER;              
        VString         PM_MARKER;              
        VStringVector   MONTH_NAMES_SHORT;      
        VStringVector   MONTH_NAMES_LONG;       
        VStringVector   DAY_NAMES_SHORT;        
        VStringVector   DAY_NAMES_LONG;         
};

// VInstantFormatter ---------------------------------------------------------

class VInstantFormatter {
    public:

        VInstantFormatter();
        VInstantFormatter(const VInstantFormatterLocaleInfo& localeInfo);
        VInstantFormatter(const VString& formatSpecifier);
        VInstantFormatter(const VString& formatSpecifier, const VInstantFormatterLocaleInfo& localeInfo);

        ~VInstantFormatter() {}

        VString formatLocalString(const VInstant& when) const;
        VString formatUTCString(const VInstant& when) const;
        
        // Getter, for debugging use.
        VString getFormatSpecifier() const { return mFormatSpecifier; }

    private:
    
        VString _format(const VInstantStruct& when, int utcOffsetMilliseconds) const;
        void _flushPendingFieldSpecifier(const VInstantStruct& when, int utcOffsetMilliseconds, VString& fieldSpecifier/*will be set to empty on return*/, VString& resultToAppendTo) const;

        void _flushFixedLengthTextValue(const VString& value, VString& resultToAppendTo) const;
        void _flushVariableLengthTextValue(const VString& shortValue, const VString& longValue, int fieldLength, VString& resultToAppendTo) const;
        void _flushNumberValue(int value, int fieldLength, VString& resultToAppendTo) const;
        void _flushYearValue(int year, int fieldLength, VString& resultToAppendTo) const;
        void _flushMonthValue(int month, int fieldLength, VString& resultToAppendTo) const;
        void _flushDayNameValue(int dayOfWeek/*0=sun ... 6=sat*/, int fieldLength, VString& resultToAppendTo) const;
        void _flushDayNumberValue(int dayOfWeek/*0=sun ... 6=sat*/, int fieldLength, VString& resultToAppendTo) const;
        void _flushTimeZoneValue(int utcOffsetMilliseconds, const VString& fieldSpecifier, VString& resultToAppendTo) const;
        
        VString mFormatSpecifier;
        
        // Pseudo-constants: Potentially localized values, not static, because we allow setting per VInstantFormatter.
        const VInstantFormatterLocaleInfo& mLocaleInfo;
};

#endif /* vinstant_h */