gnc-date.h

Go to the documentation of this file.

/********************************************************************
 *            gnc-date.h (to be renamed qofdate.h)
 *
 *  Copyright (C) 1997 Robin D. Clark <rclark@cs.hmc.edu>
 *  Copyright (C) 1998-2000, 2003 Linas Vepstas <linas@linas.org>
 *  Copyright  2005  Neil Williams <linux@codehelp.co.uk>
 *  Copyright (C) 2005 David Hampton <hampton@employees.org>
 *  Copyright 2012 John Ralls <jralls@ceridwen.us>
 ********************************************************************/
/********************************************************************\
 * 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, contact:                        *
 *                                                                  *
 * Free Software Foundation           Voice:  +1-617-542-5942       *
 * 51 Franklin Street, Fifth Floor    Fax:    +1-617-542-2652       *
 * Boston, MA  02110-1301,  USA       gnu@gnu.org                   *
\********************************************************************/
#ifndef GNC_DATE_H
#define GNC_DATE_H

#include <glib-object.h>

#include <time.h>

#ifdef __cplusplus
extern "C"
{
#endif


typedef gint64 time64;
/* A bit of a hack to create a type separate from the alias of int64_t so that
 * compile-time dispatch can use the right KVP visitor.
 */
typedef struct
{
    time64 t;
} Time64;


GType time64_get_type( void );
#define GNC_TYPE_TIME64 (time64_get_type ())

extern const char *gnc_default_strftime_date_format;

#define MAX_DATE_LENGTH 34

#define QOF_UTC_DATE_FORMAT     "%Y-%m-%dT%H:%M:%SZ"

typedef enum
{
    QOF_DATE_FORMAT_US,       
    QOF_DATE_FORMAT_UK,       
    QOF_DATE_FORMAT_CE,       
    QOF_DATE_FORMAT_ISO,      
    QOF_DATE_FORMAT_LOCALE,   
    QOF_DATE_FORMAT_UTC,      
    QOF_DATE_FORMAT_CUSTOM,   
    QOF_DATE_FORMAT_UNSET     
} QofDateFormat;

#define DATE_FORMAT_FIRST QOF_DATE_FORMAT_US
#define DATE_FORMAT_LAST  QOF_DATE_FORMAT_UTC

typedef enum
{
    QOF_DATE_COMPLETION_THISYEAR, 
    QOF_DATE_COMPLETION_SLIDING,  
} QofDateCompletion;

typedef enum
{
    GNCDATE_MONTH_NUMBER,
    GNCDATE_MONTH_ABBREV,
    GNCDATE_MONTH_NAME
} GNCDateMonthFormat;

/* Replacements for POSIX functions which use time_t. Time_t is still
 * 32 bits in Microsoft Windows, Apple OSX, and some BSD versions even
 * when the rest of the system is 64-bits, as well as all 32-bit
 * versions of Unix. 32-bit time_t overflows at 03:14:07 UTC on
 * Tuesday, 19 January 2038 and so cannot represent dates after that.
 *
 * These functions use boost::date_time internally.
 */
struct tm* gnc_localtime (const time64 *secs);

struct tm* gnc_localtime_r (const time64 *secs, struct tm* time);

struct tm* gnc_gmtime (const time64 *secs);

gint gnc_start_of_week (void);

time64 gnc_mktime (struct tm* time);

time64 gnc_timegm (struct tm* time);

gchar* gnc_ctime (const time64 *secs);

time64 gnc_time (time64 *tbuf);

gdouble gnc_difftime (const time64 secs1, const time64 secs2);

void gnc_tm_free (struct tm* time);


const gchar* gnc_date_dateformat_to_string(QofDateFormat format);

gboolean gnc_date_string_to_dateformat(const gchar* format_string,
                                       QofDateFormat *format);

const gchar* gnc_date_monthformat_to_string(GNCDateMonthFormat format);

gboolean gnc_date_string_to_monthformat(const gchar *format_string,
                                        GNCDateMonthFormat *format);

char* gnc_print_time64(time64 time, const char* format);

// @}

GDate* gnc_g_date_new_today (void);

void gnc_gdate_set_today (GDate* gd);

void gnc_gdate_set_time64 (GDate* gd, time64 time);

time64 time64CanonicalDayTime(time64 t);

time64 gdate_to_time64 (GDate d);

time64 gnc_dmy2time64 (gint day, gint month, gint year);

time64 gnc_dmy2time64_neutral (gint day, gint month, gint year);

time64 gnc_dmy2time64_end (gint day, gint month, gint year);

time64 gnc_iso8601_to_time64_gmt(const gchar *);

gchar * gnc_time64_to_iso8601_buff (time64, char * buff);
// @}

/* ======================================================== */

// @{
QofDateFormat qof_date_format_get(void);

void qof_date_format_set(QofDateFormat df);

const gchar *qof_date_format_get_string(QofDateFormat df);

const gchar *qof_date_text_format_get_string(QofDateFormat df);
// @}

/* ======================================================== */

void qof_date_completion_set(QofDateCompletion dc, int backmonths);

gchar dateSeparator(void);

/* ======================================================== */

// @{
/* qof_format_time takes a format specification in UTF-8 and a broken-down time,
 *  tries to call strftime with a sufficiently large buffer and, if successful,
 *  return a newly allocated string in UTF-8 for the printing result.
 *
 *  @param format A format specification in UTF-8.
 *
 *  @param tm A broken-down time.
 *
 *  @return A newly allocated string on success, or NULL otherwise.
 */
/* gchar *qof_format_time(const gchar *format, const struct tm *tm); */

gsize qof_strftime(gchar *buf, gsize max, const gchar *format,
                   const struct tm *tm);

size_t qof_print_date_dmy_buff (gchar * buff, size_t buflen, int day, int month, int year);

size_t qof_print_date_buff (char * buff, size_t buflen, time64 secs);

size_t qof_print_gdate(char *buf, size_t bufflen, const GDate *gd);

char * qof_print_date (time64 secs);


/* ------------------------------------------------------------------ */
/* time printing utilities */

size_t qof_print_date_time_buff (char * buff, size_t len, time64 secs);

gboolean qof_scan_date (const char *buff, int *day, int *month, int *year);

// @}

/* ======================================================== */

// @{

static inline
void gnc_tm_set_day_start (struct tm *tm)
{
    /* First second of the day */
    g_return_if_fail (tm != NULL);
    tm->tm_hour = 0;
    tm->tm_min = 0;
    tm->tm_sec = 0;
}

void gnc_tm_set_day_neutral (struct tm *tm);

static inline
void gnc_tm_set_day_middle (struct tm *tm)
{
    /* First second of the day */
    g_return_if_fail (tm != NULL);
    tm->tm_hour = 12;
    tm->tm_min = 0;
    tm->tm_sec = 0;
}

static inline
void gnc_tm_set_day_end (struct tm *tm)
{
    /* Last second of the day */
    g_return_if_fail (tm != NULL);
    tm->tm_hour = 23;
    tm->tm_min = 59;
    tm->tm_sec = 59;
}

time64 gnc_time64_get_day_start(time64 time_val);

time64 gnc_time64_get_day_neutral(time64 time_val);

time64 gnc_time64_get_day_end(time64 time_val);

int gnc_date_get_last_mday (int month, int year);

// @}

/* ======================================================== */

// @{
void   gnc_tm_get_today_start(struct tm *tm);

void   gnc_tm_get_today_neutral(struct tm *tm);

void   gnc_tm_get_today_end(struct tm *tm);

time64 gnc_time64_get_today_start(void);

time64 gnc_time64_get_today_end(void);

char * gnc_date_timestamp (void);

#define MIN_BUF_LEN 10

void gnc_dow_abbrev(gchar *buf, int buf_len, int dow);


/* ======================================================== */

// @{

gint gnc_gdate_equal(gconstpointer gda, gconstpointer gdb);


guint gnc_gdate_hash( gconstpointer gd );


/* ======================================================== */

// @{
GDate time64_to_gdate (time64 t);

time64 gnc_time64_get_day_start_gdate (const GDate *date);

time64 gnc_time64_get_day_end_gdate (const GDate *date);


/* ======================================================== */

// @{

void gnc_gdate_set_month_start (GDate *date);


void gnc_gdate_set_month_end (GDate *date);


void gnc_gdate_set_prev_month_start (GDate *date);


void gnc_gdate_set_prev_month_end (GDate *date);


void gnc_gdate_set_quarter_start (GDate *date);


void gnc_gdate_set_quarter_end (GDate *date);


void gnc_gdate_set_prev_quarter_start (GDate *date);


void gnc_gdate_set_prev_quarter_end (GDate *date);


void gnc_gdate_set_year_start (GDate *date);


void gnc_gdate_set_year_end (GDate *date);


void gnc_gdate_set_prev_year_start (GDate *date);


void gnc_gdate_set_prev_year_end (GDate *date);


void gnc_gdate_set_fiscal_year_start (GDate *date, const GDate *year_end);


void gnc_gdate_set_fiscal_year_end (GDate *date, const GDate *year_end);


void gnc_gdate_set_prev_fiscal_year_start (GDate *date, const GDate *year_end);


void gnc_gdate_set_prev_fiscal_year_end (GDate *date, const GDate *year_end);


#ifdef __cplusplus
}
#endif

#endif /* GNC_DATE_H */