# c.datetimeutils

**Repository Path**: zinface/c.datetimeutils

## Basic Information

- **Project Name**: c.datetimeutils
- **Description**: C 语言的 DateTime 封装
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-02-14
- **Last Updated**: 2022-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DateTimeUtils
> C 语言的 日期时间封装工具

* 什么是GMT？
    1. Greenwich Mean Time 格林尼治标准时间。\
    这是以英国格林尼治天文台观测结果得出的时间，这是英国格林尼治当地时间，这个地方的当地时间过去被当成世界标准的时间。\
    1972年之前，格林威治时间(GMT)一直是世界时间的标准。\
    1972年之后，GMT 不再是一个时间标准了。
* 什么是UTC？
    1. UTC：Coordinated Universal Time 协调世界时。
    2. 1972年1月1日，UTC（协调世界时）成为新的世界标准时间\
    因为地球自转越来越慢，每年都会比前一年多出零点几秒，每隔几年协调世界时组织都会给世界时+1秒，让基于原子钟的世界时和基于天文学（人类感知）的格林尼治标准时间相差不至于太大。\
    并将得到的时间称为UTC，这是现在使用的世界标准时间。\
    协调世界时不与任何地区位置相关，也不代表此刻某地的时间，所以在说明某地时间时要加上时区。
* 中国是哪个时区？
    1. 中国标准时间（China Standard Time）CST是UTC+8，与UTC-0的时区相差8个小时

> 关于 格林尼治时间` 和 `格林威治时间

1. GreenwichMean 曾被译为 格林威治(现已废弃)\
    现代应采用格林尼治(GMT)作为标准命名，但仍可用格林威治命名

> 关于 UTC 与 GMT 计量

1. UTC是我们现在用的时间标准，GMT是老的时间计量标准。
2. UTC 是根据原子钟来计算时间，
3. GMT 是根据地球的自转和公转来计算时间，也就是太阳每天经过位于英国伦敦郊区的皇家格林威治天文台的时间就是中午12点。

> 关于 Calendar Time(日历时间)

1. 一般被称为"从一个标准时间点到此时的时间经过的秒数"\
    标准时间是不变的。一般是表示距离UTC时间 1970-01-01 00:00:00的秒数。\
    标准时间点对不同编译器可能会不同


> 注意事项: 关于 C 语言中，#include <time.h> 下的 struct tm 结构体

1. 它是共享的指针，不需要释放。
2. 但是在多线程中，如果你使用了其它日期函数，并改变了数据结构将会导致时间错乱



---- 

以下是本函数库提供的功能

1. 基本函数
    ```c
    // 初始化 DateTime 结构体为某种时间
    struct tm* makeDateTime(DateTime *datetime, time_t timestamp, bool useLocalTime);
    
    // 时间戳
    // 日历时间: 由协调世界时(UTC)时间计算历来的秒数
    // 日历时间: 1970年1月1日 00:00:00 开始到现在的秒数
    time_t currentCalendarTime();

    // GMT(Greenwich Mean Time)格林尼治标准时 - 共享时间结构
    struct tm* currentGreenwichMeanDateTime();

    // UTC(Coordinated Universal Time)协调世界时，
    // 由于目前无法提供闰秒功能，与格林尼治标准时实现相同 - 共享时间结构
    struct tm* currentCoordinatedUniversalDateTime();
    ```
2. 日历时间 - 取值函数**未对应值增加(year + 1900, month + 1)**
    ```c
    // 获取日历时间信息
    struct tm* createCalendarDateTime(DateTime *datetime);
    /*获取当前年份，从1900开始计算*/
    int currentCalendarDateTimeYear(DateTime *datetime);
    /*获取当前月份，范围是0-11*/
    int currentCalendarDateTimeYearMonth(DateTime *datetime);
    /*获取当前月分日数，范围是1-31*/
    int currentCalendarDateTimeYearMonthDay(DateTime *datetime);
    /*获取当前时，这里获取西方的时间，刚好相差八小时*/
    int currentCalendarDateTimeYearMonthDayHour(DateTime *datetime);
    /*获取当前分*/
    int currentCalendarDateTimeYearMonthDayMinute(DateTime *datetime);
    /*获取当前秒*/
    int currentCalendarDateTimeYearMonthDaySecond(DateTime *datetime);
    ```
3. 本地时间 - 取值函数**已对应值增加(year + 1900, month + 1)**
    ```c
    // Local Time 本地时间 - 经由 '日历时间' 计算，时区自动调整(+8)
    struct tm* createLocalDateTime(DateTime *datetime);
    /*获取当前年份*/
    int currentLocalDateTimeYear(DateTime *datetime);
    /*获取当前月份，范围是1-12*/
    int currentLocalDateTimeYearMonth(DateTime *datetime);
    /*获取当前月分日数，范围是1-31*/
    int currentLocalDateTimeYearMonthDay(DateTime *datetime);
    /*获取当前时，这里获取西方的时间，刚好相差八小时*/
    int currentLocalDateTimeYearMonthDayHour(DateTime *datetime);
    /*获取当前分*/
    int currentLocalDateTimeYearMonthDayMinute(DateTime *datetime);
    /*获取当前秒*/
    int currentLocalDateTimeYearMonthDaySecond(DateTime *datetime);
    ```


注: 由于时间复杂性，本库提供的众多函数均为多功能函数库


1. makeDateTime(DateTime *datetime, time_t timestamp, bool useLocalTime): \
    如果你有一个时间戳，需要进行后续时间转换，可用该函数初始化 DateTime 结构体
2. currentCalendarTime():\
    如果你需要一个当前时间戳，可使用该函数
3. currentGreenwichMeanDateTime():\
    如果你需要一个相对于`格林尼治标准时(GMT)`标准时间，可使用该函数
4. currentCoordinatedUniversalDateTime():\
    如果你需要一个相对于`协调世界时(UTC)`标准时间，可使用该函数

> 以下与 DateTime 结构体有关, 格林尼治(GMT)/协调世界时(UTC)

1. createCalendarDateTime(DateTime *datetime):\
    可用该函数初始化 DateTime 结构体, \
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间
0. currentCalendarDateTimeYear(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间年份\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的`年份`
0. currentCalendarDateTimeYearMonth(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间月份\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的`月份`
0. currentCalendarDateTimeYearMonthDay(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间月天\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的`月天`
0. currentCalendarDateTimeYearMonthDayHour(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间小时\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的`小时`
0. currentCalendarDateTimeYearMonthDayMinute(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间分钟\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的`分钟`
0. currentCalendarDateTimeYearMonthDaySecond(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间秒钟\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的`秒钟`

> 以下与 DateTime 结构体有关, 本地时区时间

1. createLocalDateTime(DateTime *datetime):\
    可用该函数初始化 DateTime 结构体, \
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的本地时区
0. currentLocalDateTimeYear(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间年份\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的本地时区`年份`
0. currentLocalDateTimeYearMonth(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间月份\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的本地时区`月份`
0. currentLocalDateTimeYearMonthDay(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间月天\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的本地时区`月天`
0. currentLocalDateTimeYearMonthDayHour(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间小时\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的本地时区`小时`
0. currentLocalDateTimeYearMonthDayMinute(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间分钟\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的本地时区`分钟`
0. currentLocalDateTimeYearMonthDaySecond(DateTime *datetime):\
    可用当前函数获取 datetime 内的时间秒钟\
    如果 datetime 为 NULL将获取到一个相对于`格林尼治标准时(GMT)`标准时间的本地时区`秒钟`