CompareFiletime

Overview

CompareFiletime compares two FILETIME values by converting each to a LARGE_INTEGER and comparing the QuadPart members. The relation returned mirrors the standard C library’s strcmp() convention: negative, zero, or positive. Only the sign of a non-zero result is meaningful.

Purpose

Provides a total ordering over FILETIME values (100-nanosecond intervals since January 1, 1601 UTC) that treats NULL pointers as valid input, which makes the function directly usable as a comparator for sorting and searching arrays of FILETIME values.

Key Features

• Compares the full 64-bit value, not just the low or high DWORD
• Defined for NULL arguments (NULL sorts before any non-NULL value; two NULLs are equal)
• Returns a plain int, not an HRESULT — there is no failure code to check

Function Signature

int CompareFiletime(
    _In_ PFILETIME ft1,
    _In_ PFILETIME ft2
);

Parameters

Return Values

The function returns an int, not an HRESULT.

Remarks

Relation to CompareDateItem

CompareDateItem compares the FILETIME member of two date items; to compare an item against a raw FILETIME, obtain the item’s value with GetDateItemFiletime and pass both values here.

Thread Safety

The function takes no handle and acquires no lock; the existing documentation does not describe any synchronization for it. The caller must make sure that no other thread modifies either FILETIME while the call is in progress.

Ordering and Using as a Comparator

Because the result follows strcmp() semantics, the function can be wrapped for qsort() or bsearch() as shown in the sample. Do not use the subtraction of FILETIME members as a substitute: the 64-bit difference does not fit in an int.

Sample Code

The example builds FILETIME values from calendar dates, compares them, exercises the NULL rules, and uses the function as a qsort() comparator. It allocates no library resources, so nothing needs to be freed.

#include <stdio.h>
#include <stdlib.h>
#include "datelog.h"

static int __cdecl CompareForQsort(const void *a, const void *b)
{
    return CompareFiletime((PFILETIME)a, (PFILETIME)b);
}

static BOOL MakeFiletime(WORD wYear, WORD wMonth, WORD wDay, PFILETIME pFt)
{
    SYSTEMTIME st = { 0 };

    st.wYear = wYear;
    st.wMonth = wMonth;
    st.wDay = wDay;
    return SystemTimeToFileTime(&st, pFt);
}

int main(void)
{
    FILETIME first  = { 0 };
    FILETIME second = { 0 };
    FILETIME list[3] = { 0 };
    int      result = 0;
    int      i      = 0;

    if (!MakeFiletime(2024, 1, 2, &first) || !MakeFiletime(2024, 1, 31, &second)) {
        printf("SystemTimeToFileTime failed: %lu\n", GetLastError());
        return 1;
    }

    result = CompareFiletime(&first, &second);
    if (result < 0) {
        printf("first is earlier than second\n");
    }
    else if (result > 0) {
        printf("first is later than second\n");
    }
    else {
        printf("both FILETIME values are equal\n");
    }

    /* A FILETIME always equals itself. */
    result = CompareFiletime(&first, &first);
    printf("first vs first: %d\n", result);

    /* NULL arguments are accepted: NULL sorts before any non-NULL value. */
    result = CompareFiletime(NULL, &first);
    printf("NULL vs first: %s\n", (result < 0) ? "negative" : "unexpected");
    result = CompareFiletime(&first, NULL);
    printf("first vs NULL: %s\n", (result > 0) ? "positive" : "unexpected");
    result = CompareFiletime(NULL, NULL);
    printf("NULL vs NULL: %d\n", result);

    /* Use it as a qsort comparator to order an array chronologically. */
    list[0] = second;
    list[1] = first;
    if (!MakeFiletime(2024, 1, 16, &list[2])) {
        return 1;
    }
    qsort(list, 3, sizeof(list[0]), CompareForQsort);
    for (i = 0; i < 3; i++) {
        SYSTEMTIME st = { 0 };
        if (FileTimeToSystemTime(&list[i], &st)) {
            printf("%04u-%02u-%02u\n", st.wYear, st.wMonth, st.wDay);
        }
    }
    return 0;
}

See Also

• CompareDateItem — compares two date items by FILETIME
• GetDateItemFiletime — retrieves an item’s FILETIME
• GetDateItemDate — retrieves an item’s calendar date
• datelog_h — public header reference