DATE_ITEM

Overview

DATE_ITEM is a structure that represents a single date item within a date collection or date log. It contains date information in various formats (FILETIME, SYSTEMTIME, large integer, date number) to support flexible date representation and manipulation across the mdts_date library.

The structure maintains date information and provides access through multiple representations, allowing callers to retrieve and work with dates in their preferred format. This structure is used extensively when working with date collections, date logs, and date-based operations.

Structure Definition

The DATE_ITEM structure is defined in datelog.h as follows:

typedef struct _DATE_ITEM {
    FILETIME     FileTime;        /* Date represented as FILETIME */
    SYSTEMTIME   SystemTime;      /* Date represented as SYSTEMTIME */
    LARGE_INTEGER LargeInteger;  /* Date represented as large integer */
    double       DateNumber;      /* Date represented as date number (e.g., OLE Date) */
} DATE_ITEM, *PDATE_ITEM;

Structure Members

Remarks

• A DATE_ITEM should only be created and initialized through the InitializeDateItem() function to ensure proper initialization and validation.
• The library maintains consistency across all date representations within a DATE_ITEM, ensuring that all four representations refer to the same point in time.
• When working with date items, use the appropriate accessor functions like GetDateItemFiletime(), GetDateItemDate(), etc., rather than accessing the structure members directly.
• Date items are validated to ensure they do not fall on holiday dates when added to a date log with a holidays handle.
• Date items are immutable after creation; to modify a date, create a new DATE_ITEM with the desired date value.

Usage Patterns

Creating a DATE_ITEM

To create a DATE_ITEM, use the InitializeDateItem() function:

DATE_ITEM dateItem = {0};
HRESULT hr = InitializeDateItem(
    &dateItem,           /* Output parameter */
    2024, 12, 25,       /* Year, Month, Day */
    12, 30, 45, 0       /* Hour, Minute, Second, Milliseconds */
);
if (FAILED(hr)) {
    /* Handle error */
}

Accessing DATE_ITEM Data

Use accessor functions to retrieve date information in your preferred format:

FILETIME ft = GetDateItemFiletime(&dateItem);
SYSTEMTIME st = GetDateItemSystemTime(&dateItem);
LARGE_INTEGER li = GetDateItemLargeInteger(&dateItem);
double dateNum = GetDateItemNumber(&dateItem);

Comparing Dates

Compare two DATE_ITEM structures using the comparison function:

DATE_ITEM item1 = {0}, item2 = {0};
/* Initialize item1 and item2 ... */

int result = CompareDateItem(&item1, &item2);
if (result < 0) {
    /* item1 is before item2 */
} else if (result > 0) {
    /* item1 is after item2 */
} else {
    /* item1 equals item2 */
}

Working with Date Collections

DATE_ITEM structures are used when working with date collections and date logs:

DATE_COLLECTION_HANDLE hCollection = /* ... */;
DATE_ITEM dateItem = {0};

/* Find a date item in the collection */
HRESULT hr = FindDateItemHandle(
    hCollection,
    NULL,           /* Start from beginning */
    &dateItem,      /* Output: found date item */
    NULL            /* No gap information needed */
);

Sample Code

Complete Example: Creating and Using DATE_ITEM

#include "datelog.h"
#include 

int main(void)
{
    HRESULT hr = S_OK;
    DATE_ITEM dateItem = {0};
    FILETIME ft = {0};
    SYSTEMTIME st = {0};

    /* Initialize a date item for December 25, 2024, 12:30:45 */
    hr = InitializeDateItem(
        &dateItem,
        2024, 12, 25,
        12, 30, 45, 0
    );
    if (FAILED(hr)) {
        printf("Failed to initialize date item.\n");
        return 1;
    }

    /* Retrieve the date in FILETIME format */
    ft = GetDateItemFiletime(&dateItem);
    printf("FILETIME: %lld\n", *(unsigned long long*)&ft);

    /* Retrieve the date in SYSTEMTIME format */
    st = GetDateItemSystemTime(&dateItem);
    printf("Date: %04d-%02d-%02d %02d:%02d:%02d\n",
        st.wYear, st.wMonth, st.wDay,
        st.wHour, st.wMinute, st.wSecond);

    /* Retrieve the date as a date number (OLE format) */
    double dateNum = GetDateItemNumber(&dateItem);
    printf("Date Number (OLE): %.2f\n", dateNum);

    /* Compare with another date */
    DATE_ITEM anotherItem = {0};
    hr = InitializeDateItem(
        &anotherItem,
        2024, 12, 26,
        12, 0, 0, 0
    );
    if (SUCCEEDED(hr)) {
        int cmp = CompareDateItem(&dateItem, &anotherItem);
        printf("Comparison result: %d (negative means first is earlier)\n", cmp);
    }

    /* Cleanup - free the date item if necessary */
    hr = FreeDateItem(&dateItem);

    return 0;
}