Date Utility
This chapter describes APIs of the utility for date and time processing.
1. pfmIsValidDate
Checks the validity of an input date. The date must be a string of 8 digits. The dates before 1850 are not allowed.
-
Prototype
long pfmIsValidDate(char *in_date);
-
Parameters
Parameter Description *in_date (input)
Date string in the format of yyyymmdd.
-
yyyy: 4-digit year.
-
mm: 2-digit month.
-
dd: 2-digit day.
-
-
Return values
Return Value Description TRUE
The input date is valid.
FALSE
The input date is not valid.
-
Example
rc = pfmIsValidDate("200504080011"); /* rc == FALSE */ rc = pfmIsValidDate ("20050408"); /* rc == TRUE */ rc = pfmIsValidDate ("20010229"); /* rc == FALSE */ if(rc == FALSE) { PFM_ERR("Invalid date error %s", pfmDateGetErrorMsg()); return FALSE; }
2. pfmIsValidTime
Checks the validity of an input time. The time must be a string of 6 digits.
-
Prototype
long pfmIsValidTime(char *in_time);
-
Parameters
Parameter Description *in_time (input)
Time string in the format of hhmmss.
-
hh: 2-digit hour.
-
mm: 2-digit minute.
-
ss: 2-digit second.
-
-
Return values
Return Value Description TRUE
The input time is valid.
FALSE
The input time is not valid.
-
Example
rc = pfmIsValidTime("231752"); /* rc == TRUE */ rc = pfmIsValidTime ("23175213"); /* rc == FALSE */ rc = pfmIsValidTime ("271752"); /* rc == FALSE */ rc = pfmIsValidTime ("238727"); /* rc == FALSE */ rc = pfmIsValidTime ("230787"); /* rc == FALSE */ if(rc == FALSE) { PFM_ERR("Invalid time error %s", pfmDateGetErrorMsg()); return FALSE; }
3. pfmIsInYyyymmdd
Checks the format of an input date. The date must be a string of 4, 6, or 8 digits. A 4-digit string is assumed as yyyy (year), a 6-digit string is assumed as yyyymm (year and month), and an 8-digit string is assumed as yyyymmdd (year, month, and day).
-
Prototype
long pfmIsInYyyymmdd(char *yyyymmdd);
-
Parameters
Parameter Description *yyyymmdd (input)
Date string in the format of yyyymmdd.
-
Return values
Return Value Description TRUE
The input date format is valid.
FALSE
The input date format is not valid.
-
Example
rc = pfmIsInYyyymmdd("200504080011"); /* rc == FALSE */ rc = pfmIsInYyyymmdd ("2005"); /* rc == TRUE */ rc = pfmIsInYyyymmdd ("200504"); /* rc == TRUE */ rc = pfmIsInYyyymmdd ("20050408"); /* rc == TRUE */ rc = pfmIsInYyyymmdd ("20010229"); /* rc == FALSE */ if(rc == FALSE) { PFM_ERR("Invalid date error %s", pfmDateGetErrorMsg()); return FALSE; }
4. pfmDateCmp
Compares the order of two input dates.
-
Prototype
long pfmDateCmp(char *date1, char *date2);
-
Parameters
Parameter Description *date1 (input)
First date string to compare.
*date2 (input)
Second date string to compare.
-
Return values
Return Value Description Negative value
Means that date1 < date2.
0
Means that date1 == date2.
Positive value
Means that date1 > date2.
-
Example
rc = pfmDateCmp("19710413", "19710414"); /* rc < 0 */ if(pfmDateCmp (begin_date, end_date) > 0) { PFM_ERR("The start date is greater than the end date."); return RC_ERR; }
5. pfmGetDate
Gets the current system date in the format of yyyymmdd.
-
Prototype
long pfmGetDate(char *buff);
-
Parameters
Parameter Description *buff (output)
String used to save the current system date.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The input value is NULL, or this API is not executed successfully.
-
Example
char date[LEN_DATE + 1] = {0,}; rc = pfmGetDate(date); if(rc == RC_ERR) { PFM_ERR("Current date error %s", pfmDateGetErrorMsg()); return RC_ERR; } /* date == "20081020" */
6. pfmGetTime
Gets the current system time in the format of hhmmss.
-
Prototype
long pfmGetTime(char *buf);
-
Parameters
Parameter Description *buf (output)
String used to save the current system time.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The input value is NULL, or this API is not executed successfully.
-
Example
char timebuf[LEN_TIME + 1] = {0,}; rc = pfmGetTime(timebuf); if(rc == RC_ERR) { PFM_ERR("Current time error %s", pfmDateGetErrorMsg()); return RC_ERR; } /* timebuf == "051430" */
7. pfmGetUTime
Gets the current system time in the format of hhmmssuuuuuu (uuuuuu: 6-digit microsecond).
-
Prototype
long pfmGetUTime(char *buf);
-
Parameters
Parameter Description *buf (output)
String used to save the current system time. Space of char[12+1] is required.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The input value is NULL, or this API is not executed successfully.
-
Example
char utime[12 + 1] = {0,}; rc = pfmGetUTime(utime); if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; } /* utime == "hhmmssuuuuuu" */
8. pfmGetNTime
Gets the current system time in the format of hhmmssnnnnnnnnn (nnnnnnnnn: 9-digit nanosecond).
Depending on the OS, all the 9 digits can be obtained for nanoseconds and 6-digit microseconds followed by 000 can be obtained.
-
Prototype
long pfmGetNTime(char *buf);
-
Parameters
Parameter Description *buf (output)
String used to save the current system time. Space of char[15+1] is required.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The input value is NULL, or this API is not executed successfully.
-
Example
char ntime[15 + 1] = {0,}; rc = pfmGetNTime(ntime); if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; } /* utime == "hhmmssnnnnnnnnn" */
9. pfmGetDateTime
Gets the current system date and time in the format of yyyymmddhhmmss.
-
Prototype
long pfmGetDateTime(char *out_buf);
-
Parameters
Parameter Description *out_buf (output)
String used to save the current system date and time. Space of char[14+1] is required.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The input value is NULL, or this API is not executed successfully.
-
Example
char dtime[14 + 1]; bzero(dtime, sizeof(dtime)); rc = pfmGetDateTime(dtime); if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; } /* strlen(dtime) == strlen("yyyymmddhhmmss") */
10. pfmGetDateUTime
Gets the current system date and time in the format of yyyymmddhhmmssuuuuuu.
-
Prototype
long pfmGetDateUTime(char *out_buf);
-
Parameters
Parameter Description *out_buf (output)
String used to save the current system date and time. Space of char[20+1] is required.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The input value is NULL, or this API is not executed successfully.
-
Example
char dtime[20 + 1]; bzero(dutime, sizeof(dutime)); rc = pfmGetDateUTime(dutime); if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; } /* strlen(dutime) == strlen("yyyymmddhhmmssuuuuuu") */
11. pfmGetDateNTime
Gets the current system date and time in the format of yyyymmddhhmmssnnnnnnnnn.
-
Prototype
long pfmGetDateNTime(char *out_buf);
-
Parameters
Parameter Description *out_buf (output)
String used to save the current system date and time. Space of char[23+1] is required.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
The input value is NULL, or this API is not executed successfully.
-
Example
char dntime[23 + 1]; bzero(dntime, sizeof(dntime)); rc = pfmGetDateNTime(dntime); if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; } /* strlen(dntime) == strlen("yyyymmddhhmmssnnnnnnnnn") */
12. pfmGetLastDayOfFebruary
Returns the number of days in February of the input year.
-
Prototype
long pfmGetLastDayOfFebruary(long in_year);
-
Parameters
Parameter Description in_year (input)
Year to check the number of days in February.
-
Return values
Return Value Description 29
The input year is a leap year.
28
The input year is not a leap year.
RC_ERR
This API is not executed successfully.
-
Example
rc = pfmGetLastDayOfFebruary(1999); /* rc == 28 */ rc = pfmGetLastDayOfFebruary(2000); /* rc == 29 */ rc = pfmGetLastDayOfFebruary(2100); /* rc == 28 */ rc = pfmGetLastDayOfFebruary(2104); /* rc == 29 */ if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; }
13. pfmIsLeapYear
Checks whether the input year is a leap year.
-
Prototype
long pfmIsLeapYear(long in_year);
-
Parameters
Parameter Description in_year (input)
Year to check whether it is a leap year.
-
Return values
Return Value Description TRUE
The input year is a leap year.
FALSE
The input year is not a leap year.
RC_ERR
This API is not executed successfully.
-
Example
rc = pfmIsLeapYear(1999); /* rc == 0(FALSE) */ rc = pfmIsLeapYear(2000); /* rc == 1(TRUE) */ rc = pfmIsLeapYear(2100); /* rc == 0(FALSE) */ rc = pfmIsLeapYear(2104); /* rc == TRUE */ if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; }
14. pfmGetWeekDay
Gets the day of the week of the input date.
-
Prototype
long pfmGetWeekDay(long *wday, char *in_date);
-
Parameters
Parameter Description *wday (output)
Long pointer to an integer indicating the day of the week.
(Sunday = 1, Monday = 2, … , Saturday = 7)
*in_date (input)
Date string in the format of yyyymmdd.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed successfully.
-
Example
/* illegal date */ rc = pfmGetWeekDay(&onum, "0020050411"); /* rc == RC_ERR */ /* Sunday */ rc = pfmGetWeekDay(&onum, "20050410"); /* rc == RC_NRM */ /* onum == 1 */ /* Monday */ rc = pfmGetWeekDay(&onum, "20050411"); /* rc == RC_NRM */ /* onum == 2 */ /* Tuesday */ rc = pfmGetWeekDay(&onum, "20050412"); /* rc == RC_NRM */ /* onum == 3 */ /* Wednesday */ rc = pfmGetWeekDay(&onum, "20050413"); /* rc == RC_NRM */ /* onum == 4 */ /* Thursday */ rc = pfmGetWeekDay(&onum, "20050414"); /* rc == RC_NRM */ /* onum == 5 */ /* Friday */ rc = pfmGetWeekDay(&onum, "20050415"); /* rc == RC_NRM */ /* onum == 6 */ /* Saturday */ rc = pfmGetWeekDay(&onum, "20050416"); /* rc == RC_NRM */ /* onum == 7 */ if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; }
15. pfmWeekDayToDate
Gets the date that corresponds to the input day of the input week.
-
Prototype
long pfmWeekDayToDate(char *out_date, char *in_yyyymm, long week, long wday, long opt);
-
Parameters
Parameter Description *out_date (output)
Pointer to the result date.
*in_yyyymm (input)
Input date.
week (input)
Input week.
wday (input)
Input day of the week.
-
PFM_WEEK_DAY_SUN → 1
-
PFM_WEEK_DAY_MON → 2
-
PFM_WEEK_DAY_TUE → 3
-
PFM_WEEK_DAY_WED → 4
-
PFM_WEEK_DAY_THU → 5
-
PFM_WEEK_DAY_FRI → 6
-
PFM_WEEK_DAY_SAT → 7
opt (input)
Unit of a week.
-
PFM_CONV_WDATTODATE_BY_CA: A week is from Sunday to Saturday.
-
PFM_CONV_WDATTODATE_BY_WC: A week is from 1 to 7.
-
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed successfully.
An error occurs when the format of year or month is incorrect or a week value is negative or greater than 6. An error also occurs when the result date is negative or greater than the last day of the month. For example, if you input the first Tuesday of April 2006, the first Tuesday does not exist in April 2006 because the first week of April 2006 starts from Saturday, which causes an error.
-
Example
long rc; char out_date[LEN_DATE + 1]; rc = pfmWeekDayToDate (out_date, "200506", 3, PFM_WEEK_DAY_FRI, PFM_CONV_WDATTODATE_BY_CA); if(rc != RC_NRM) { PFM_ERR("Fail pfmWeekDayToDate %s", pfmDateGetErrorMsg()); Return RC_ERR; } /* out_date = "20050617" */
16. pfmDateFormat
Converts a date to a string in a desired format.
-
Prototype
long pfmDateFormat(char *dest, char *frmt, char *date);
-
Parameters
Parameter Description *dest (output)
String used to save the converted date. The length must be the same as that of frmt.
*frmt (input)
Desired date format. The length can be up to 1024 bytes.
-
yyyy or YYYY: 4-digit year.
-
yy or YY: 2-digit year.
-
mm or MM: 2-digit month.
-
dd or DD: 3-digit day.
-
mon or MON: 3-character day of the week.
*date (input)
Date string in the format of yyyymmdd.
-
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed successfully.
-
Example
/* date = 20051231 */ rc = pfmDateFormat(dest, "yyyy/mm/dd", date); if(rc != RC_NRM) { PFM_ERR("%s", pfmDateGetErrorMsg()); Return RC_ERR; } /* format : yyyymmdd -> dest : 20051231 */ /* format : yy-mm-dd -> dest : 05-12-31 */ /* format : mm/dd/yyyy -> dest : 12/31/2005 */ /* format : mm.dd -> dest : 12.31 */ /* format : mon.dd -> dest : dec.31 */ /* format : MON.dd.yy -> dest : DEC.31.05 */
17. pfmDateJulianToGregorian
Converts a date from Julian to Gregorian.
-
Prototype
long pfmDateJulianToGregorian(char *jul_date, char *grg_date, long base_year);
-
Parameters
Parameter Description *jul_date (input)
Julian date.
*grg_date (output)
Gregorian date.
base_year (input)
Base year.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed successfully.
-
Example
char in_date[] = "123"; char grg_date[LEN_DATE + 1]; /* Converting a date from Julian to Gregorian based on 2001 */ rc = pfmDateJulianToGregorian(grg_date, in_date, 2001); if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; }
18. pfmDateGregorianToJulian
Converts a date from Gregorian to Julian.
-
Prototype
long pfmDateGregorianToJulian(char *grg_date, char *jul_date, long base_year);
-
Parameters
Parameter Description *grg_date (input)
Gregorian date.
*jul_date (output)
Julian date.
base_year (input)
Base year.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed successfully.
-
Example
char in_date[LEN_DATE + 1] = "20040504"; char jul_date[20 + 1]; /* Converting a date from Gregorian to Julian based on 2001 */ rc = pfmDateGregorianToJulian(jul_date, in_date, 2001); if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; }
19. pfmDateSolarToLunar
Converts a solar date to a lunar date.
-
Prototype
long pfmDateSolarToLunar(char * out_date, char *in_date);
-
Parameters
Parameter Description *out_date (output)
Converted lunar date.
*in_date (input)
Solar date.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed successfully.
-
Example
long rc; char lunar_date[LEN_DATE + 1]; rc = pfmDateSolarToLunar(lunar_date, "19750413"); if(rc != RC_NRM) { PFM_ERR("Fail pfmDateSolarToLunar %s", pfmDateGetErrorMsg()); return RC_ERR; } /* lunar_date = "019750402" The first byte: Leap month or not 0: Not a leap month, 1: Leap month */
20. pfmDateLunarToSolar
Converts a lunar date to a solar date.
-
Prototype
long pfmDateLunarToSolar(char *out_date, char *in_date);
-
Parameters
Parameter Description *out_date (output)
Converted solar date.
*in_date (input)
Lunar date.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed successfully.
-
Example
long rc; char solar_date[LEN_DATE + 1]; rc = pfmDateLunarToSolar(solar_date, "019750302"); /* The first byte: Leap month or not (0: Not a leap month, 1: Leap month) */ if(rc != RC_NRM) { PFM_ERR("Fail pfmDateLunarToSolar %s", pfmDateGetErrorMsg()); return RC_ERR; } /* solar_date = "19750413" */
21. pfmCountDays
Calculates the number of days and months between a start date and an end date.
-
Prototype
long pfmCountDays(PfmCountDaysIO *pfmCountDays_io);
-
Parameters
Parameter Description *pfmCountDays_io (input/output)
Pointer to the result.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed successfully.
-
Example
#define PFM_CNT_DAYS_CALC_ONE 1 /* Calculation type: Including one side */ #define PFM_CNT_DAYS_CALC_BOTH 2 /* Calculation type: Including both sides */ #define PFM_CNT_DAYS_OUT_DD 1 /* Output type: Days */ #define PFM_CNT_DAYS_OUT_MMDD 2 /* Output type: Months, Days */ typedef struct PfmDateCountDateIn PfmDateCountDateIn; struct PfmDateCountDateIn { long calc_type; /* Calculation type */ long out_type; /* Output type */ char beg_date[LEN_DATE + 1]; /* Start date */ char end_date[LEN_DATE + 1]; /* End date */ }; typedef struct PfmDateCountDateOut PfmDateCountDateOut; struct PfmDateCountDateOut { long mm_cnt; /* Number of months */ long dd_cnt; /* Number of days */ }; typedef struct PfmDateCountDateIO PfmDateCountDateIO; struct PfmDateCountDateIO { PfmDateCountDateIn in; PfmDateCountDateOut out; }; PfmDateCountDateIO pfmCountDays_io; strncpy(pfmCountDays_io.in.beg_date, "20040228", LEN_DATE); strncpy(pfmCountDays_io.in.end_date, "20040530", LEN_DATE); pfmCountDays_io.in.out_type = PFM_CNT_DAY_OUT_MMDD; /* Months, Days */ /* Including one side:Excludes the start date */ pfmCountDays_io.in.calc_type = PFM_CNT_DAYS_CALC_ONE; rc = pfmCountDays(&pfmCountDays_io); /* pfmCountDays_io.out.mm_cnt == 3 */ /* pfmCountDays_io.out.dd_cnt == 2 */ /* Including both sides: Includes the start date */ pfmCountDays.in.calc_type= PFM_CNT_DAYS_CALC_BOTH; rc = pfmCountDays(&pfmCountDays _io); /* pfmCountDays_io.out.mm_cnt == 3 */ /* pfmCountDays_io.out.dd_cnt == 3 */ pfmCountDays_io.in.out_type = MPFMCNTDAY_OUT_DD; /* Days */ /* Including one side:Excludes the start date */ pfmCountDays_io.in.calc_type = PFMCNTDAY_NO; rc = pfmCountDays(&pfmCountDays_io); /* pfmCountDays_io.out.dd_cnt == 93 */ /* Including both sides: Includes the start date */ pfmCountDays.in.calc_type = PFMCNTDAY_YES; rc = pfmCountDays(&pfmCountDays_io); /* pfmCountDays_io.out.dd_cnt == 94 */ if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; }
22. pfmCalcDate
Calculates the end date if a start date is given or the start date if an end date is given.
-
Prototype
long pfmCalcDate(PfmCalculateDateIO *pfmCalculateDate_io);
-
Parameters
Parameter Description *pfmCalculateDate_io (input/output)
Pointer to the result.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed successfully.
(An error occurs when both the start and end dates are input or both of them are not input. An error also occurs when the date format is not yyyymmdd.)
-
Example
#define PFM_CALC_DATE_CALC_ONE 1 /* Calculation type: Including one side */ #define PFM_CALC_DATE_CALC_BOTH 2 /* Calculation type: Including both sides */ #define PFM_CALC_DATE_START_DATE 1 /* Start date of the quareter */ typedef struct PfmDateCalculateDateIn PfmDateCalculateDateIn; struct PfmDateCalculateDateIn { long calc_type; /* Calculation type */ char beg_date[LEN_DATE + 1]; /* Start date */ char end_date[LEN_DATE + 1]; /* End date */ long mm_cnt; /* Number of months */ long dd_cnt; /* Number of days */ }; typedef struct PfmDateCalculateDateOut PfmDateCalculateDateOut; struct PfmDateCalculateDateOut { char beg_date[LEN_DATE + 1]; /* Start date */ char end_date[LEN_DATE + 1]; /* End date */ }; typedef struct PfmDateCalculateDateIO PfmDateCalculateDateIO; struct PfmDateCalculateDateIO { PfmDateCalculateDateIn in; PfmDateCalculateDateOut out; }; strcpy( pfmCalcDate_io.in.beg_date, "20040228" ); pfmCalcDate_io.in.mm_cnt = 3; pfmCalcDate_io.in.dd_cnt = 2; pfmCalcDate_io.in.calc_type = PFM_CALC_DATE_CALC_ONE; rc = pfmCalcDate( &pfmCalcDate_io ); /* pfmCalcDate_io.out.end_date = 20040530 */ pfmCalcDate_io.in.calc_type = PFM_CALC_DATE_CALC_BOTH; rc = pfmCalcDate( &pfmCalcDate_io ); /* pfmCalcDate_io.out.end_date = 20040529 */
23. pfmDateCalcQuarterStartDateEndDate
Gets an input date’s quarter information and the start and end dates of the quarter.
-
Prototype
long pfmDateCalcQuarterStartDateEndDate(char *i_date, long *o_qyear, char *o_st_date, char *o_end_date); -
Parameters
Parameter Description *i_date (input)
Input date.
*o_qyear (output)
Quarter (number) of the input date.
*o_st_date (output)
Start date of the quarter of the input date.
* o_end_date(output)
End date of the quarter of the input date.
-
Return values
Return Value Description RC_NRM
This API is executed successfully.
RC_ERR
This API is not executed successfully.
-
Example
char i_date[] = "200500821"; char o_st_date[LEN_DATE + 1]; char o_end_date[LEN_DATE + 1]; long rc, o_qyear; /* Getting an input date's quarter information and the start and end dates of the quarter. */ rc = pfmDateCalcQuarterStartDateEndDate(i_date, &o_qyear, o_st_date, o_end_date); /* o_qyear = 3 */ /* o_st_date = "20050701" */ /* o_end_date = "20050930" */ if(rc == RC_ERR) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); return RC_ERR; }
24. pfmDateGetErrorMsg
Returns a date utility error message.
-
Prototype
long pfmDateGetErrorMsg(void);
-
Return values
Returns the error message.
-
Example
rc = pfmDateGetWeekDay(&a, b); if(rc != RC_NRM) { PFM_ERR("Error %s", pfmDateGetErrorMsg()); /* Or, PFM_ERR("%s", pfmUtilGetErrorMsg()); */ Return RC_ERR; }