~drizzle-trunk/drizzle/development

/* - mode: c; c-basic-offset: 2; indent-tabs-mode: nil; -*-
 *  vim:expandtab:shiftwidth=2:tabstop=2:smarttab:
 *
 *  Copyright (C) 2008 Sun Microsystems
 *
 *  Authors:
 *
 *  Jay Pipes <jay.pipes@sun.com>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */

/**
 * @file 
 *
 * Defines the API for dealing with temporal data inside the server.
 *
 * The Temporal class is the base class for all data of any temporal
 * type.  A number of derived classes define specialized classes 
 * representng various date, date-time, time, or timestamp types.
 *
 * All Temporal derived classes are ValueObjects.  That is to say that
 * Temporal class instances are not part of the Item hierarchy and serve
 * <em>only</em> to represent a time or date-related piece of data.
 *
 * @note
 *
 * Low-level calendrical calculations are done via routines in the
 * calendar.cc file.
 *
 * @see drizzled/calendar.cc
 */

#ifndef DRIZZLED_TEMPORAL_H
#define DRIZZLED_TEMPORAL_H

#define DRIZZLE_MAX_SECONDS 59
#define DRIZZLE_MAX_MINUTES 59
#define DRIZZLE_MAX_HOURS 23
#define DRIZZLE_MAX_DAYS 31
#define DRIZZLE_MAX_MONTHS 12
#define DRIZZLE_MAX_YEARS_SQL 9999
#define DRIZZLE_MAX_YEARS_EPOCH 2038
#define DRIZZLE_MIN_SECONDS 0
#define DRIZZLE_MIN_MINUTES 0
#define DRIZZLE_MIN_HOURS 0
#define DRIZZLE_MIN_DAYS 1
#define DRIZZLE_MIN_MONTHS 1
#define DRIZZLE_MIN_YEARS_SQL 1
#define DRIZZLE_MIN_YEARS_EPOCH 1970

#define DRIZZLE_SECONDS_IN_MINUTE 60
#define DRIZZLE_SECONDS_IN_HOUR (60*60)
#define DRIZZLE_SECONDS_IN_DAY (60*60*24)
#define DRIZZLE_NANOSECONDS_IN_MICROSECOND 1000

#define DRIZZLE_MAX_LENGTH_DATETIME_AS_STRING 40

#define DRIZZLE_YY_PART_YEAR  70

#include "drizzled/calendar.h"

/* Outside forward declarations */
class my_decimal;

namespace drizzled 
{

/**
 * Base class for all temporal data classes.
 */
class Temporal
{
protected:
  enum calendar _calendar;
  uint32_t _years;
  uint32_t _months;
  uint32_t _days;
  uint32_t _hours;
  uint32_t _minutes;
  uint32_t _seconds;
  time_t _epoch_seconds;
  uint32_t _useconds;
  uint32_t _nseconds;
  /** Returns number of seconds in time components (hour + minute + second) */
  uint64_t _cumulative_seconds_in_time() const;
public:
  Temporal();
  virtual ~Temporal() {}

  /** Returns the calendar component. */
  inline enum calendar calendar() const {return _calendar;}
  /** Returns the nanoseconds component. */
  inline uint32_t nseconds() const {return _nseconds;}
  /** Sets the useconds component. */
  inline void set_useconds(const uint32_t usecond) {_useconds= usecond;}
  /** Returns the microsseconds component. */
  inline uint32_t useconds() const {return _useconds;}
  /** Sets the epoch_seconds component. */
  virtual void set_epoch_seconds();
  /** Returns the UNIX epoch seconds component. */
  inline time_t epoch_seconds() const {return _epoch_seconds;}
  /** Sets the seconds component. */
  inline void set_seconds(const uint32_t second) {_seconds= second;}
  /** Returns the seconds component. */
  inline uint32_t seconds() const {return _seconds;}
  /** Sets the days component. */
  inline void set_minutes(const uint32_t minute) {_minutes= minute;}
  /** Returns the minutes component. */
  inline uint32_t minutes() const {return _minutes;}
  /** Sets the hours component. */
  inline void set_hours(const uint32_t hour) {_hours= hour;}
  /** Returns the hours component. */
  inline uint32_t hours() const {return _hours;}
  /** Sets the days component. */
  inline void set_days(const uint32_t day) {_days= day;}
  /** Returns the days component. */
  inline uint32_t days() const {return _days;}
  /** Sets the months component. */
  inline void set_months(const uint32_t month) {_months= month;}
  /** Returns the months component. */
  inline uint32_t months() const {return _months;}
  /** Sets the years component. */
  inline void set_years(const uint32_t year) {_years= year;}
  /** Returns the years component. */
  inline uint32_t years() const {return _years;}

  /** Returns whether the temporal value is valid as a date. */
  virtual bool is_valid_date() const= 0;
  /** Returns whether the temporal value is valid as a datetime. */
  virtual bool is_valid_datetime() const= 0;
  /** Returns whether the temporal value is valid as a time. */
  virtual bool is_valid_time() const= 0;
  /** Returns whether the temporal value is valid as a UNIX timestamp. */
  virtual bool is_valid_timestamp() const= 0;

  /**
   * Returns whether the temporal
   * value is valid. Each subclass defines what is
   * valid for the range of temporal data it contains.
   */
  virtual bool is_valid() const= 0;

  /**
   * All Temporal derived classes must implement
   * conversion routines for converting to and from
   * a string. Subclasses implement other conversion 
   * routines, but should always follow these notes:
   *
   * 1) Ensure that ALL from_xxx methods call is_valid()
   * 2) Ensure that ALL to_xxx methods are void returns and
   *    do not call is_valid()
   *
   * This minimizes the repeated bounds-checking to
   * just the conversion from_xxx routines.
   */

  friend class TemporalFormat;
};

/**
 * Class representing temporal components in a valid
 * SQL date range, with no time component
 */
class Date: public Temporal 
{
public:
  /**
   * Comparison operator overloads to compare a Date against
   * another Date value.
   *
   * @param Date to compare against.
   */
  bool operator==(const Date &rhs);
  bool operator!=(const Date &rhs);
  bool operator>(const Date &rhs);
  bool operator>=(const Date &rhs);
  bool operator<(const Date &rhs);
  bool operator<=(const Date &rhs);
  /**
   * Operator overload for adding/subtracting another Date
   * (or subclass) to/from this temporal.  When subtracting 
   * or adding two Dates, we return a new Date instance.
   *
   * @param Temporal instance to add/subtract to/from
   */
  const Date operator-(const Date &rhs);
  const Date operator+(const Date &rhs);
  Date& operator+=(const Date &rhs);
  Date& operator-=(const Date &rhs);

  virtual bool is_valid_date() const {return is_valid();}
  virtual bool is_valid_datetime() const {return is_valid();}
  virtual bool is_valid_time() const {return false;}
  virtual bool is_valid_timestamp() const {return is_valid() && in_unix_epoch();}
  /** Returns whether the temporal value is valid date. */
  virtual bool is_valid() const;
  /* Returns whether the Date (or subclass) instance is in the Unix Epoch. */
  virtual bool in_unix_epoch() const;

  /**
   * Fills a supplied char string with a
   * string representation of the Date  
   * value.
   *
   * @param C-String to fill.
   * @param Length of filled string (out param)
   */
  virtual void to_string(char *to, size_t *to_len) const;

  /**
   * Attempts to populate the Date instance based
   * on the contents of a supplied string.
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param String to convert from
   * @param Length of supplied string
   */
  virtual bool from_string(const char *from, size_t from_len);

  /**
   * Fills a supplied 8-byte integer pointer with an
   * integer representation of the Date
   * value.
   *
   * @param Integer to fill.
   */
  virtual void to_int64_t(int64_t *to) const;

  /**
   * Fills a supplied 4-byte integer pointer with an
   * integer representation of the Date
   * value.
   *
   * @param Integer to fill.
   */
  virtual void to_int32_t(int32_t *to) const;

  /**
   * Attempts to populate the Date instance based
   * on the contents of a supplied 4-byte integer.
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param Integer to convert from
   */
  virtual bool from_int32_t(const int32_t from);

  /**
   * Attempts to populate the Date instance based
   * on the contents of a supplied Julian Day Number
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param Integer to convert from
   */
  virtual bool from_julian_day_number(const int64_t from);

  /**
   * Fills a supplied tm pointer with an
   * representation of the Date 
   * value.
   *
   * @param tm to fill.
   */
  virtual void to_tm(struct tm *to) const;

  /**
   * Attempts to populate the Date instance based
   * on the contents of a supplied pointer to struct tm
   * (broken time).
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param Pointe rto the struct tm to convert from
   */
  virtual bool from_tm(const struct tm *from);

  /**
   * Attempts to convert the Date value into
   * a supplied time_t.
   *
   * @param Pointer to a time_t to convert to
   */
  virtual void to_time_t(time_t *to) const;

  /**
   * Attempts to populate the Date instance based
   * on the contents of a supplied time_t
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param time_t to convert from
   */
  virtual bool from_time_t(const time_t from);

  /**
   * Fills a supplied my_decimal with a representation of 
   * the Date value.
   *
   * @param Pointer to the my_decimal to fill
   */
  virtual void to_decimal(my_decimal *to) const;
};

/* Forward declare needed for friendship */
class DateTime;

/**
 * Class representing temporal components having only
 * a time component, with no date structure
 */
class Time: public Temporal
{
public:

  /**
   * Comparison operator overloads to compare a Time against
   * another Time value.
   *
   * @param Time to compare against.
   */
  bool operator==(const Time &rhs);
  bool operator!=(const Time &rhs);
  bool operator>(const Time &rhs);
  bool operator>=(const Time &rhs);
  bool operator<(const Time &rhs);
  bool operator<=(const Time &rhs);
  /**
   * Operator to add/subtract a Time from a Time.  
   * We can return a Time new temporal instance.
   *
   * @param Temporal instance to add/subtract to/from
   */
  const Time operator-(const Time &rhs);
  const Time operator+(const Time &rhs);
  Time& operator-=(const Time &rhs);
  Time& operator+=(const Time &rhs);

  virtual bool is_valid_date() const {return false;}
  virtual bool is_valid_datetime() const {return false;}
  virtual bool is_valid_time() const {return is_valid();}
  virtual bool is_valid_timestamp() const {return false;}
  /** Returns whether the temporal value is valid date. */
  virtual bool is_valid() const;

  /**
   * Fills a supplied char string with a
   * string representation of the Time  
   * value.
   *
   * @param C-String to fill.
   * @param Length of filled string (out param)
   */
  virtual void to_string(char *to, size_t *to_len) const;

  /**
   * Attempts to populate the Time instance based
   * on the contents of a supplied string.
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param String to convert from
   * @param Length of supplied string
   */
  virtual bool from_string(const char *from, size_t from_len);

  /**
   * Fills a supplied 4-byte integer pointer with an
   * integer representation of the Time
   * value.
   *
   * @param Integer to fill.
   */
  virtual void to_int32_t(int32_t *to) const;

  /**
   * Attempts to populate the Time instance based
   * on the contents of a supplied 4-byte integer.
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param Integer to convert from
   */
  virtual bool from_int32_t(const int32_t from);

  /**
   * Fills a supplied my_decimal with a representation of 
   * the Time value.
   *
   * @param Pointer to the my_decimal to fill
   */
  virtual void to_decimal(my_decimal *to) const;

  friend class DateTime;
};

/**
 * Class representing temporal components in a valid
 * SQL datetime range, including a time component
 */
class DateTime: public Date
{
public:
  /**
   * Comparison operator overloads to compare a DateTime against
   * another DateTime value.
   *
   * @param DateTime to compare against.
   */
  bool operator==(const DateTime &rhs);
  bool operator!=(const DateTime &rhs);
  bool operator>(const DateTime &rhs);
  bool operator>=(const DateTime &rhs);
  bool operator<(const DateTime &rhs);
  bool operator<=(const DateTime &rhs);
  /**
   * Operator to add/subtract a Time from a Time.  
   * We can return a Time new temporal instance.
   *
   * @param Temporal instance to add/subtract to/from
   */
  const DateTime operator-(const Time &rhs);
  const DateTime operator+(const Time &rhs);
  DateTime& operator-=(const Time &rhs);
  DateTime& operator+=(const Time &rhs);
  /**
   * Operator overload for adding/subtracting another DateTime
   * (or subclass) to/from this temporal.  When subtracting 
   * or adding two DateTimes, we return a new DateTime instance.
   *
   * @param Temporal instance to add/subtract to/from
   */
  const DateTime operator-(const DateTime &rhs);
  const DateTime operator+(const DateTime &rhs);
  DateTime& operator+=(const DateTime &rhs);
  DateTime& operator-=(const DateTime &rhs);

  /* Returns whether the DateTime (or subclass) instance is in the Unix Epoch. */
  bool in_unix_epoch() const;
  /** Returns whether the temporal value is valid datetime. */
  virtual bool is_valid() const;

  /**
   * It's not possible to convert to and from a DateTime and 
   * a 4-byte integer, so let us know if we try and do it!
   */
  inline void to_int32_t(int32_t *) {assert(0);}
  inline bool from_int32_t(int32_t) {assert(0); return false;}

  /**
   * Fills a supplied char string with a
   * string representation of the DateTime
   * value.
   *
   * @param C-String to fill.
   * @param Length of filled string (out param)
   */
  virtual void to_string(char *to, size_t *to_len) const;

  /**
   * Attempts to populate the DateTime instance based
   * on the contents of a supplied string.
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param String to convert from
   * @param Length of supplied string
   */
  virtual bool from_string(const char *from, size_t from_len);

  /**
   * Fills a supplied 8-byte integer pointer with an
   * integer representation of the DateTime
   * value.
   *
   * @param Integer to fill.
   */
  virtual void to_int64_t(int64_t *to) const;

  /**
   * Attempts to populate the DateTime instance based
   * on the contents of a supplied time_t
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param time_t to convert from
   */
  virtual bool from_time_t(const time_t from);

  /**
   * Attempts to populate the DateTime instance based
   * on the contents of a supplied 8-byte integer.
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param Integer to convert from
   */
  virtual bool from_int64_t(const int64_t from);

  /**
   * Fills a supplied tm pointer with an
   * representation of the DateTime
   * value.
   *
   * @param tm to fill.
   */
  virtual void to_tm(struct tm *to) const;

  /**
   * Fills a supplied my_decimal with a representation of 
   * the DateTime value.
   *
   * @param Pointer to the my_decimal to fill
   */
  virtual void to_decimal(my_decimal *to) const;
};

/**
 * Class representing temporal components in the UNIX epoch
 */
class Timestamp: public DateTime 
{
public:
  /**
   * Comparison operator overloads to compare a Timestamp against
   * another Timestamp value.
   *
   * @param Timestamp to compare against.
   */
  bool operator==(const Timestamp &rhs);
  bool operator!=(const Timestamp &rhs);
  bool operator>(const Timestamp &rhs);
  bool operator>=(const Timestamp &rhs);
  bool operator<(const Timestamp &rhs);
  bool operator<=(const Timestamp &rhs);

  inline bool is_valid_timestamp() const {return is_valid();}
  /** Returns whether the temporal value is valid timestamp. */
  virtual bool is_valid() const;

  /**
   * Attempts to convert the Timestamp value into
   * a supplied time_t.
   *
   * @param Pointer to a time_t to convert to
   */
  virtual void to_time_t(time_t *to) const;
};

/**
 * Class representing temporal components in the UNIX epoch
 * with an additional microsecond component.
 */
class MicroTimestamp: public Timestamp
{
public:
  /** Returns whether the temporal value is valid micro-timestamp. */
  bool is_valid() const;

  /**
   * Fills a supplied char string with a
   * string representation of the MicroTimestamp
   * value.
   *
   * @param C-String to fill.
   * @param Length of filled string (out param)
   */
  virtual void to_string(char *to, size_t *to_len) const;

  /**
   * Fills a supplied timeval pointer with an
   * representation of the MicroTimestamp
   * value.
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param timeval to fill.
   */
  virtual void to_timeval(struct timeval *to) const;
};

/**
 * Class representing temporal components in the UNIX epoch
 * with an additional nanosecond component.
 */
class NanoTimestamp: public Timestamp
{
public:
  /** Returns whether the temporal value is valid nano-timestamp. */
  bool is_valid() const;

  /**
   * Fills a supplied timespec pointer with an
   * representation of the NanoTimestamp
   * value.
   *
   * Returns whether the conversion was 
   * successful.
   *
   * @param timespec to fill.
   */
  void to_timespec(struct timespec *to) const;
};

} /* end namespace drizzled */

#endif /* DRIZZLED_TEMPORAL_H */