varch/doc/date.en.md

Introduction

The date module in C language is a simple date calculation module. It offers developers numerous practical functions, covering aspects like date validity verification, leap year determination, calculation of date differences, obtaining the corresponding day of the week based on a date, and displaying the calendar for a specified month and year. It facilitates efficient handling of various date-related business logics in C language projects.

Interfaces

Functions

date_isleap Function

uint8_t date_isleap(uint16_t year);

Usage Example:

int test() 
{
    uint16_t year = 2024;
    uint8_t result = date_isleap(year);
    if (result == 1) 
    {
        printf("%d is a leap year.\n", year);
    } 
    else 
    {
        printf("%d is not a leap year.\n", year);
    }
    return 0;
}

This function is used to check if a given year is a leap year. It returns 1 if it is a leap year and 0 otherwise.

date_isvalid Function

uint8_t date_isvalid(DATE date);

Usage Example:

int test()  
{
    DATE date = DATE(2024, 2, 29);  // Assume a date example
    uint8_t result = date_isvalid(date);
    if (result == 1) {
        printf("The date is valid.\n");
    } else {
        printf("The date is invalid.\n");
    }
    return 0;
}

It's used to verify the validity of a given date. If the date is valid according to the rules of the calendar, it returns 1; otherwise, it returns 0.

date_century_days Function

uint32_t date_century_days(uint16_t century);

Usage Example:

int test() 
{
    uint16_t century = 21;
    uint32_t result = date_century_days(century);
    printf("The number of days in the %d century is: %u\n", century, result);
    return 0;
}

This function calculates and returns the total number of days in a specified century.

date_year_days Function

uint32_t date_year_days(uint16_t year);

Usage Example:

int test() 
{
    uint16_t year = 2024;
    uint32_t result = date_year_days(year);
    printf("The number of days in the year %d is: %u\n", year, result);
    return 0;
}

It determines and returns the number of days in a particular year, taking into account whether it's a leap year or not.

date_month_days Function

uint32_t date_month_days(uint16_t year, uint8_t month);

Usage Example:

int test() 
{
    uint16_t year = 2024;
    uint8_t month = 2;
    uint32_t result = date_month_days(year, month);
    printf("The number of days in month %d of year %d is: %u\n", month, year, result);
    return 0;
}

This function figures out and returns the number of days in a specific month of a given year.

date_get_dow Function

uint32_t date_get_dow(DATE date);

Usage Example:

int test() 
{
    DATE date = DATE(2024, 12, 31);
    uint32_t result = date_get_dow(date);
    switch (result) {
        case 1:
            printf("The day of week is Monday.\n");
            break;
        case 2:
            printf("The day of week is Tuesday.\n");
            break;
        case 3:
            printf("The day of week is Wednesday.\n");
            break;
        case 4:
            printf("The day of week is Thursday.\n");
            break;
        case 5:
            printf("The day of week is Friday.\n");
            break;
        case 6:
            printf("The day of week is Saturday.\n");
            break;
        case 7:
            printf("The day of week is Sunday.\n");
            break;
        default:
            printf("The input date is invalid.\n");
    }
    return 0;
}

It's used to obtain the day of the week corresponding to a given date.

date_current_days Function

uint32_t date_current_days(DATE date);

Usage Example:

int test() 
{
    DATE date = DATE(2024, 12, 31);
    uint32_t result = date_current_days(date);
    printf("The total number of days from the base date to the given date is: %u\n", result);
    return 0;
}

This function calculates the total number of days from a base date (presumably some predefined starting point) to the provided date.

date_diff_days Function

int32_t date_diff_days(DATE date1, DATE date2);

Usage Example:

int test() 
{
    DATE date1 = DATE(2024, 1, 1);
    DATE date2 = DATE(2024, 12, 31);
    int32_t result = date_diff_days(date1, date2);
    printf("The difference in days between the two dates is: %d\n", result);
    return 0;
}

It calculates the difference in days between two given dates.

date_from_days Function

DATE date_from_days(uint32_t days);

Usage Example:

int test() 
{
    uint32_t days = 366;  // Assume corresponding number of days
    DATE result = date_from_days(days);
    printf("The date converted from %u days is: %d-%d-%d\n", days, result.year, result.month, result.day);
    return 0;
}

This function converts a given number of days into a specific date.

date_offset Function

DATE date_offset(DATE date, int32_t days);

Usage Example:

int test() 
{
    DATE date = DATE(2024, 1, 1);
    int32_t days = 365;
    DATE result = date_offset(date, days);
    printf("The offset date is: %d-%d-%d\n", result.year, result.month, result.day);
    return 0;
}

It calculates a new date by offsetting the given date by a specified number of days.

date_calendar Function

void date_calendar(uint16_t year, uint8_t month);

Usage Example:

int test()
{
    uint16_t year = 2024;
    uint8_t month = 12;
    date_calendar(year, month);
    return 0;
}

This function displays the calendar for a specified month and year, presenting it in a formatted table-like structure as shown in the example result:

+-----------------------------------------+
| 2024/12                                 |
+-----------------------------------------+
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
+-----------------------------------------+
|   1 |   2 |   3 |   4 |   5 |   6 |   7 |
|   8 |   9 |  10 |  11 |  12 |  13 |  14 |
|  15 |  16 |  17 |  18 |  19 |  20 |  21 |
|  22 |  23 |  24 |  25 |  26 |  27 |  28 |
|  29 |  30 |  31 |     |     |     |     |
+-----------------------------------------+