ion_timestamp.h

Go to the documentation of this file.

/*
 * Copyright 2009-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License").
 * You may not use this file except in compliance with the License.
 * A copy of the License is located at:
 *
 *     http://aws.amazon.com/apache2.0/
 *
 * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
 * language governing permissions and limitations under the License.
 */
 
//
// ion timestamp support routines
// includes toString and Parse (in Java terms)
//
// overall format is (from ion wiki):
//
//      null.timestamp                   // A null timestamp value
//      
//      2007-02-23                       // A day, equivalent to 2007-02-23T00:00:00-00:00
//      2007-02-23T12:14Z                // Seconds are optional, but timezone is not
//      2007-02-23T12:14:33.079-08:00    // A timestamp with millisecond precision and PST local time
//      2007-02-23T20:14:33.079Z         // The same instant in UTC ("zero" or "zulu")
//      2007-02-23T20:14:33.079+00:00    // The same instant with explicit local offset
//      
 
#ifndef ION_TIMESTAMP_H_
#define ION_TIMESTAMP_H_
 
#include "ion_types.h"
#include "ion_platform_config.h"
#include "time.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct _ion_timestamp {
    uint8_t     precision;
 
    int16_t     tz_offset;
    uint16_t    year, month, day;
    uint16_t    hours, minutes, seconds;
 
    decQuad     fraction;
};
 
#define ION_TT_BIT_YEAR  0x01
#define ION_TT_BIT_MONTH 0x02
#define ION_TT_BIT_DAY   0x04
#define ION_TT_BIT_MIN   0x10
#define ION_TT_BIT_SEC   0x20 /* with secs must have time & date */
#define ION_TT_BIT_FRAC  0x40 /* must have all */
 
#define ION_TS_YEAR      (0x0         | ION_TT_BIT_YEAR)
#define ION_TS_MONTH     (ION_TS_YEAR | ION_TT_BIT_MONTH)
#define ION_TS_DAY       (ION_TS_MONTH  | ION_TT_BIT_DAY)
#define ION_TS_MIN       (ION_TS_DAY  | ION_TT_BIT_MIN)
#define ION_TS_SEC       (ION_TS_MIN  | ION_TT_BIT_SEC)
#define ION_TS_FRAC      (ION_TS_SEC | ION_TT_BIT_FRAC)
 
#define ION_MAX_TIMESTAMP_STRING (26+DECQUAD_String) /* y-m-dTh:m:s.<dec>+h:m */ // TODO there is another definition of a similar constant in ion_debug.h that is shorter. Investigate.
 
ION_API_EXPORT iERR ion_timestamp_get_precision(const ION_TIMESTAMP *ptime, int *precision);
 
ION_API_EXPORT iERR ion_timestamp_to_string(ION_TIMESTAMP *ptime, char *buffer, SIZE buf_length,
        SIZE *output_length, decContext *pcontext);
 
ION_API_EXPORT iERR ion_timestamp_parse(ION_TIMESTAMP *ptime, char *buffer, SIZE length,
        SIZE *p_characters_used, decContext *pcontext);
 
ION_API_EXPORT iERR ion_timestamp_for_time_t(ION_TIMESTAMP *ptime, const time_t *time);
 
ION_API_EXPORT iERR ion_timestamp_to_time_t(const ION_TIMESTAMP *ptime, time_t *time);
 
ION_API_EXPORT iERR ion_timestamp_equals(const ION_TIMESTAMP *ptime1, const ION_TIMESTAMP *ptime2,
        BOOL *is_equal, decContext *pcontext);
 
ION_API_EXPORT iERR ion_timestamp_instant_equals(const ION_TIMESTAMP *ptime1, const ION_TIMESTAMP *ptime2,
                                  BOOL *is_equal, decContext *pcontext);
 
ION_API_EXPORT iERR ion_timestamp_for_year(ION_TIMESTAMP *ptime,
        int year);
 
ION_API_EXPORT iERR ion_timestamp_for_month(ION_TIMESTAMP *ptime,
        int year, int month);
 
ION_API_EXPORT iERR ion_timestamp_for_day(ION_TIMESTAMP *ptime,
        int year, int month, int day);
 
ION_API_EXPORT iERR ion_timestamp_for_minute(ION_TIMESTAMP *ptime,
        int year, int month, int day, int hours, int minutes);
 
ION_API_EXPORT iERR ion_timestamp_for_second(ION_TIMESTAMP *ptime,
        int year, int month, int day, int hours, int minutes, int seconds);
 
ION_API_EXPORT iERR ion_timestamp_for_fraction(ION_TIMESTAMP *ptime,
        int year, int month, int day, int hours, int minutes, int seconds,
        decQuad *p_fraction, decContext *pcontext);
 
ION_API_EXPORT iERR ion_timestamp_get_thru_year(ION_TIMESTAMP *ptime, int *p_year);
 
ION_API_EXPORT iERR ion_timestamp_get_thru_month(ION_TIMESTAMP *ptime,
        int *p_year, int *p_month);
 
ION_API_EXPORT iERR ion_timestamp_get_thru_day(ION_TIMESTAMP *ptime,
        int *p_year, int *p_month, int *p_day);
 
ION_API_EXPORT iERR ion_timestamp_get_thru_minute(ION_TIMESTAMP *ptime,
        int *p_year, int *p_month, int *p_day, int *p_hour, int *p_minute);
 
ION_API_EXPORT iERR ion_timestamp_get_thru_second(ION_TIMESTAMP *ptime,
        int *p_year, int *p_month, int *p_day, int *p_hour, int *p_minute, int *p_second);
 
ION_API_EXPORT iERR ion_timestamp_get_thru_fraction(ION_TIMESTAMP *ptime,
        int *p_year, int *p_month, int *p_day, int *p_hour, int *p_minute, int *p_second,
        decQuad *p_fraction);
 
ION_API_EXPORT iERR ion_timestamp_has_local_offset(ION_TIMESTAMP *ptime, BOOL *p_has_local_offset);
 
ION_API_EXPORT iERR ion_timestamp_get_local_offset(ION_TIMESTAMP *ptime, int *p_offset_minutes);
 
ION_API_EXPORT iERR ion_timestamp_unset_local_offset(ION_TIMESTAMP *ptime);
 
ION_API_EXPORT iERR ion_timestamp_set_local_offset(ION_TIMESTAMP *ptime, int offset_minutes);
 
#ifdef __cplusplus
}
#endif
 
#endif