Date/time manipulation

## Detailed Description

OCILIB encapsulates Oracle SQL Date data type within OCI_Date structure

Basically, the OCI_Date routines are wrappers around the Oracle OCIDate APIs

Example
  #include "ocilib.h"
  #define SIZE_STR 260
  void err_handler(OCI_Error *err)
  {
  printf("%s\n", OCI_ErrorGetString(err));
  }
  int main(void)
  {
  OCI_Date *d1, *d2;
  char str[SIZE_STR + 1];
  if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
  {
  return EXIT_FAILURE;
  }
  d1 = OCI_DateCreate(NULL);
  d2 = OCI_DateCreate(NULL);
  strcpy(str, "13041978 20:20:12");
  OCI_DateFromText(d1, str, "DDMMYYYY HH24:MI:SS");
  OCI_DateToText(d1, "DD/MM/YYYY HH24:MI:SS", SIZE_STR, str);
  printf("\nDate is %s\n", str);
  OCI_DateSysDate(d1);
  OCI_DateToText(d1, "DD/MM/YYYY HH24:MI:SS", SIZE_STR, str);
  printf("\nSysdate is %s\n", str);
  OCI_DateAddDays(d1, 5);
  OCI_DateAddMonths(d1, 2);
  OCI_DateToText(d1, "DD/MM/YYYY HH24:MI:SS", SIZE_STR, str);
  printf("\nDate + 5 days and 2 months is %s\n", str);
  OCI_DateAssign(d2, d1);
  OCI_DateLastDay(d1);
  OCI_DateToText(d1, "DD/MM/YYYY HH24:MI:SS", SIZE_STR, str);
  printf("\nLast day of the month : %s\n", str);
  printf("\nNumber of days until the end of the months : %i\n", OCI_DateDaysBetween(d1, d2));
  OCI_DateFree(d1);
  OCI_DateFree(d2);
  OCI_Cleanup();
  return EXIT_SUCCESS;
  }

## Functions

OCI_EXPORT OCI_Date *OCI_API | OCI_DateCreate (OCI_Connection *con)
| Create a local date object. More...
OCI_EXPORT boolean OCI_API | OCI_DateFree (OCI_Date *date)
| Free a date object. More...
OCI_EXPORT OCI_Date **OCI_API | OCI_DateArrayCreate (OCI_Connection *con, unsigned int nbelem)
| Create an array of date object. More...
OCI_EXPORT boolean OCI_API | OCI_DateArrayFree (OCI_Date **dates)
| Free an array of date objects. More...
OCI_EXPORT boolean OCI_API | OCI_DateAddDays (OCI_Date *date, int nb)
| Add or subtract days to a date handle. More...
OCI_EXPORT boolean OCI_API | OCI_DateAddMonths (OCI_Date *date, int nb)
| Add or subtract months to a date handle. More...
OCI_EXPORT int OCI_API | OCI_DateAssign (OCI_Date *date, OCI_Date *date_src)
| Assign the value of a date handle to another one. More...
OCI_EXPORT int OCI_API | OCI_DateCheck (OCI_Date *date)
| Check if the given date is valid. More...
OCI_EXPORT int OCI_API | OCI_DateCompare (OCI_Date *date, OCI_Date *date2)
| Compares two date handles. More...
OCI_EXPORT int OCI_API | OCI_DateDaysBetween (OCI_Date *date, OCI_Date *date2)
| Return the number of days betWeen two dates. More...
OCI_EXPORT boolean OCI_API | OCI_DateFromText (OCI_Date *date, const otext *str, const otext *fmt)
| Convert a string to a date and store it in the given date handle. More...
OCI_EXPORT boolean OCI_API | OCI_DateToText (OCI_Date *date, const otext *fmt, int size, otext *str)
| Convert a Date value from the given date handle to a string. More...
OCI_EXPORT boolean OCI_API | OCI_DateGetDate (OCI_Date *date, int *year, int *month, int *day)
| Extract the date part from a date handle. More...
OCI_EXPORT boolean OCI_API | OCI_DateGetTime (OCI_Date *date, int *hour, int *min, int *sec)
| Extract the time part from a date handle. More...
OCI_EXPORT boolean OCI_API | OCI_DateGetDateTime (OCI_Date *date, int *year, int *month, int *day, int *hour, int *min, int *sec)
| Extract the date and time parts from a date handle. More...
OCI_EXPORT boolean OCI_API | OCI_DateSetDate (OCI_Date *date, int year, int month, int day)
| Set the date portion if the given date handle. More...
OCI_EXPORT boolean OCI_API | OCI_DateSetTime (OCI_Date *date, int hour, int min, int sec)
| Set the time portion if the given date handle. More...
OCI_EXPORT boolean OCI_API | OCI_DateSetDateTime (OCI_Date *date, int year, int month, int day, int hour, int min, int sec)
| Set the date and time portions if the given date handle. More...
OCI_EXPORT boolean OCI_API | OCI_DateLastDay (OCI_Date *date)
| Place the last day of month (from the given date) into the given date. More...
OCI_EXPORT boolean OCI_API | OCI_DateNextDay (OCI_Date *date, const otext *day)
| Gets the date of next day of the week, after a given date. More...
OCI_EXPORT boolean OCI_API | OCI_DateSysDate (OCI_Date *date)
| Return the current system date/time into the date handle. More...
OCI_EXPORT boolean OCI_API | OCI_DateZoneToZone (OCI_Date *date, const otext *zone1, const otext *zone2)
| Convert a date from one zone to another zone. More...
OCI_EXPORT boolean OCI_API | OCI_DateToCTime (OCI_Date *date, struct tm *ptm, time_t *pt)
| Affect an OCI_Date handle value to ISO C time data types. More...
OCI_EXPORT boolean OCI_API | OCI_DateFromCTime (OCI_Date *date, struct tm *ptm, time_t t)
| Affect ISO C time data types values to an OCI_Date handle. More...

## Function Documentation

## OCI_DateCreate()

OCI_EXPORT OCI_Date* OCI_API OCI_DateCreate | ( | OCI_Connection * | con | ) |

`#include <ocilib.h>`

Create a local date object.

Parameters

  con | - Connection handle

Note
  From version 2.5.0, parameter 'con' can be NULL in order to manipulate dates independently from database connections

Returns
  Return the date handle on success otherwise NULL on failure

Referenced by ocilib::Date::Date().

## OCI_DateFree()

OCI_EXPORT boolean OCI_API OCI_DateFree | ( | OCI_Date * | date | ) |

`#include <ocilib.h>`

Free a date object.

Parameters

  date | - Date handle

Warning
  Only dates created with OCI_DateCreate() should be freed by OCI_DateFree()

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::Date().

## OCI_DateArrayCreate()

OCI_EXPORT OCI_Date** OCI_API OCI_DateArrayCreate | ( | OCI_Connection * | con,
|  | unsigned int | nbelem
| ) |  |

`#include <ocilib.h>`

Create an array of date object.

Parameters

  con | - Connection handle
  nbelem | - number of elements in the array

Note
  see OCI_DateCreate() for more details

Returns
  Return the date handle array on success otherwise NULL on failure

## OCI_DateArrayFree()

OCI_EXPORT boolean OCI_API OCI_DateArrayFree | ( | OCI_Date ** | dates | ) |

`#include <ocilib.h>`

Free an array of date objects.

Parameters

  dates | - Array of date objects

Warning
  Only arrays of dates created with OCI_DateArrayCreate() should be freed by OCI_DateArrayFree()

Returns
  TRUE on success otherwise FALSE

## OCI_DateAddDays()

OCI_EXPORT boolean OCI_API OCI_DateAddDays | ( | OCI_Date * | date,
|  | int | nb
| ) |  |

`#include <ocilib.h>`

Add or subtract days to a date handle.

Parameters

  date | - Date handle
  nb | - Number of days to add/remove

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::AddDays().

## OCI_DateAddMonths()

OCI_EXPORT boolean OCI_API OCI_DateAddMonths | ( | OCI_Date * | date,
|  | int | nb
| ) |  |

`#include <ocilib.h>`

Add or subtract months to a date handle.

Parameters

  date | - Date handle
  nb | - Number of months to add/remove

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::AddMonths().

## OCI_DateAssign()

OCI_EXPORT int OCI_API OCI_DateAssign | ( | OCI_Date * | date,
|  | OCI_Date * | date_src
| ) |  |

`#include <ocilib.h>`

Assign the value of a date handle to another one.

Parameters

  date | - Destination Date handle
  date_src | - Source Date handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::Clone().

## OCI_DateCheck()

OCI_EXPORT int OCI_API OCI_DateCheck | ( | OCI_Date * | date | ) |

`#include <ocilib.h>`

Check if the given date is valid.

Parameters

  date | - Date handle

Returns
  - Zero if date is valid
  - Any other value means the date is invalid

Referenced by ocilib::Date::IsValid().

## OCI_DateCompare()

OCI_EXPORT int OCI_API OCI_DateCompare | ( | OCI_Date * | date,
|  | OCI_Date * | date2
| ) |  |

`#include <ocilib.h>`

Compares two date handles.

Parameters

  date | - Date1 handle
  date2 | - Date2 handle

Returns
  - -1 if date1 is smaller than date2,
  - 0 if they are equal
  - 1 if date1 is greater than date2.

Referenced by ocilib::Date::Clone().

## OCI_DateDaysBetween()

OCI_EXPORT int OCI_API OCI_DateDaysBetween | ( | OCI_Date * | date,
|  | OCI_Date * | date2
| ) |  |

`#include <ocilib.h>`

Return the number of days betWeen two dates.

Parameters

  date | - Date1 handle
  date2 | - Date2 handle

Returns
  Number of days on success otherwise OCI_ERROR on failure

Referenced by ocilib::Date::DaysBetween().

## OCI_DateFromText()

OCI_EXPORT boolean OCI_API OCI_DateFromText | ( | OCI_Date * | date,
|  | const otext * | str,
|  | const otext * | fmt
| ) |  |

`#include <ocilib.h>`

Convert a string to a date and store it in the given date handle.

Parameters

  date | - Destination Date handle
  str | - Source date string
  fmt | - Date format

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::FromString().

## OCI_DateToText()

OCI_EXPORT boolean OCI_API OCI_DateToText | ( | OCI_Date * | date,
|  | const otext * | fmt,
|  | int | size,
|  | otext * | str
| ) |  |

`#include <ocilib.h>`

Convert a Date value from the given date handle to a string.

Parameters

  date | - source Date handle
  fmt | - Date format
  size | - Destination string size in characters
  str | - Destination date string

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::ToString().

## OCI_DateGetDate()

OCI_EXPORT boolean OCI_API OCI_DateGetDate | ( | OCI_Date * | date,
|  | int * | year,
|  | int * | month,
|  | int * | day
| ) |  |

`#include <ocilib.h>`

Extract the date part from a date handle.

Parameters

  date | - Date handle
  year | - Place holder for year value
  month | - Place holder for month value
  day | - Place holder for day value

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::GetDate().

## OCI_DateGetTime()

OCI_EXPORT boolean OCI_API OCI_DateGetTime | ( | OCI_Date * | date,
|  | int * | hour,
|  | int * | min,
|  | int * | sec
| ) |  |

`#include <ocilib.h>`

Extract the time part from a date handle.

Parameters

  date | - Date handle
  hour | - Place holder for hour value
  min | - Place holder for minute value
  sec | - Place holder for second value

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::GetTime().

## OCI_DateGetDateTime()

OCI_EXPORT boolean OCI_API OCI_DateGetDateTime | ( | OCI_Date * | date,
|  | int * | year,
|  | int * | month,
|  | int * | day,
|  | int * | hour,
|  | int * | min,
|  | int * | sec
| ) |  |

`#include <ocilib.h>`

Extract the date and time parts from a date handle.

Parameters

  date | - Date handle
  year | - Place holder for year value
  month | - Place holder for month value
  day | - Place holder for day value
  hour | - Place holder for hour value
  min | - Place holder for minute value
  sec | - Place holder for second value

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::GetDateTime().

## OCI_DateSetDate()

OCI_EXPORT boolean OCI_API OCI_DateSetDate | ( | OCI_Date * | date,
|  | int | year,
|  | int | month,
|  | int | day
| ) |  |

`#include <ocilib.h>`

Set the date portion if the given date handle.

Parameters

  date | - Date handle
  year | - Year value
  month | - Month value
  day | - Day value

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::SetDate().

## OCI_DateSetTime()

OCI_EXPORT boolean OCI_API OCI_DateSetTime | ( | OCI_Date * | date,
|  | int | hour,
|  | int | min,
|  | int | sec
| ) |  |

`#include <ocilib.h>`

Set the time portion if the given date handle.

Parameters

  date | - Date handle
  hour | - Hour value
  min | - Minute value
  sec | - Second value

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::SetTime().

## OCI_DateSetDateTime()

OCI_EXPORT boolean OCI_API OCI_DateSetDateTime | ( | OCI_Date * | date,
|  | int | year,
|  | int | month,
|  | int | day,
|  | int | hour,
|  | int | min,
|  | int | sec
| ) |  |

`#include <ocilib.h>`

Set the date and time portions if the given date handle.

Parameters

  date | - Date handle
  year | - Year value
  month | - Month value
  day | - Day value
  hour | - Hour value
  min | - Minute value
  sec | - Second value

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::SetDateTime().

## OCI_DateLastDay()

OCI_EXPORT boolean OCI_API OCI_DateLastDay | ( | OCI_Date * | date | ) |

`#include <ocilib.h>`

Place the last day of month (from the given date) into the given date.

Parameters

  date | - Date handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::LastDay().

## OCI_DateNextDay()

OCI_EXPORT boolean OCI_API OCI_DateNextDay | ( | OCI_Date * | date,
|  | const otext * | day
| ) |  |

`#include <ocilib.h>`

Gets the date of next day of the week, after a given date.

Parameters

  date | - Date handle
  day | - Day of the week

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::NextDay().

## OCI_DateSysDate()

OCI_EXPORT boolean OCI_API OCI_DateSysDate | ( | OCI_Date * | date | ) |

`#include <ocilib.h>`

Return the current system date/time into the date handle.

Parameters

  date | - Date handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::SysDate().

## OCI_DateZoneToZone()

OCI_EXPORT boolean OCI_API OCI_DateZoneToZone | ( | OCI_Date * | date,
|  | const otext * | zone1,
|  | const otext * | zone2
| ) |  |

`#include <ocilib.h>`

Convert a date from one zone to another zone.

Parameters

  date | - Date handle
  zone1 | - Source zone
  zone2 | - Destination zone

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::Date::ChangeTimeZone().

## OCI_DateToCTime()

OCI_EXPORT boolean OCI_API OCI_DateToCTime | ( | OCI_Date * | date,
|  | struct tm * | ptm,
|  | time_t * | pt
| ) |  |

`#include <ocilib.h>`

Affect an OCI_Date handle value to ISO C time data types.

Parameters

  date | - Date handle
  ptm | - Pointer to a structure tm to receive date/time values
  pt | - Pointer to a time_t to hold the date/time in the time_t format

Note
  Both parameters 'ptm' and 'p' are optional but one of them has to be provided.

Returns
  TRUE on success otherwise FALSE

## OCI_DateFromCTime()

OCI_EXPORT boolean OCI_API OCI_DateFromCTime | ( | OCI_Date * | date,
|  | struct tm * | ptm,
|  | time_t | t
| ) |  |

`#include <ocilib.h>`

Affect ISO C time data types values to an OCI_Date handle.

Parameters

  date | - Date handle
  ptm | - Pointer to a structure tm that hold the date/time value
  t | - Value (time_t) that hold the date/time in the time_t format

Note
  Both parameters 'ptm' and 'p' are optional but one of them has to be provided. If 'ptm' is not null, its value is affected to the OCI_Timestamp handle, otherwise the value of 't' is used.

Returns
  TRUE on success otherwise FALSE