Linux Assemblycollection of fast libraries

Time libraryTime.h

Time library is implemented as Time class, which allow programs to convert time variables from human readable format to Unix time format and vice versa. It also understands time zone records which are covered by tzfiles from package "tzdata". You may load data from that files into Time objects and use them to get local time in different time zones.

They are extremely fast in comparison with standard GNU libc library. See the benchmarks.

Contents

Function list

C function nameFunctionsC++ function nameFunctions
ConvertDate1 function(constructor) Time1 function
ConvertTime1 functionConvertDate1 function
ExtractDate1 functionConvertTime1 function
ExtractTime1 functionExtractDate1 function
InitTime1 functionExtractTime1 function
LoadTimeZone1 functionLoadTimeZone1 function
LocalTime1 functionLocalTime1 function
SystemTime1 functionSystemTime1 function
WeekDay1 functionWeekDay1 function
C function nameFunctionsC++ function nameFunctions

Time constants

ConstantDescription
Time zone limits
TIME_CHANGE_SIZESize of time changes array
TIME_ZONE_SIZESize of time zone array
Standard periods of time
TIME_MINUTESeconds per minute
TIME_HOURSeconds per hour
TIME_DAYSeconds per day
TIME_WEEKSeconds per week
Other constants
TIME_MINMin time value
TIME_MAXMax time value
TIME_ERRORWrong time value (indicates an error)

Time structure

Time library provides structure called time_struct, which holds wall clock time value without date.

C/C++struct time_struct
{
    uint8_t hour;
    uint8_t min;
    uint8_t sec;
};

It has following fields:

  • hour - hours [0-23]
  • min - minutes [0-59]
  • sec - seconds [0-59]

Date structure

Date structure date_struct holds calendar date in natural format, instead of Unix time format.

C/C++struct date_struct
{
    sint32_t year;
    uint8_t  mon;
    uint8_t  day;
    uint8_t  wday;
    uint8_t  hour;
    uint8_t  min;
    uint8_t  sec;
};

This structure has following members:

  • year - year from beginning of Gregorian calendar
  • mon - month of year [1-12]
  • day - day of month [1-31]
  • wday - day of week (0 - Sunday) [0-6]
  • hour - hours [0-23]
  • min - minutes [0-59]
  • sec - seconds [0-59]

Note:Be aware that month range is 1-12 instead of range 0-11, which is used by standard C library. And year is full year number. Not since 1900.

Constructor

Cvoid Time_InitTime (struct Time *tzone);
C++Time::Time (void);

Description: Constructor which init Time object with default values (cleans time zone). In C++ code it is called automatically when Time class object is created. In C code you should manually call appropriate function.

Parameters:

  • tzone - a pointer to time zone structure

Return value: None.

Loading time zone data from tzfile

Cerror_t Time_LoadTimeZone (struct Time *tzone, const char8_t tzfile[]);
C++error_t Time::LoadTimeZone (const char8_t tzfile[]);

Description: Loads time zone data from specified tzfile into time zone structure. Time zone information may be used to convert system time to local time for selected time zone.

Parameters:

  • tzone - a pointer to a time zone structure, where time zone data will be placed
  • tzfile - path to tzfile, which describes required time zone

Return value:

  • 0 (zero) if no errors.
  • ERRNO if an error occurred during reading or analyzing tzfile.

Time conversion

Ctime_t Time_ConvertTime (uint8_t hour, uint8_t min, uint8_t sec);
C++time_t Time::ConvertTime (uint8_t hour, uint8_t min, uint8_t sec);

Description: Converts wall clock time (HH:MM:SS) into Unix time format and skips date value (equal to set date to 1-st of January 0000 year).

Parameters:

  • hour - hours [0-23]
  • min - minutes [0-59]
  • sec - seconds [0-59]

Return value:

  • Unix time value without date.
  • TIME_ERROR in case of hours or minutes or seconds are out of range.

Date conversion

Ctime_t Time_ConvertDate (uint8_t day, uint8_t mon, sint32_t year, uint8_t hour, uint8_t min, uint8_t sec);
C++time_t Time::ConvertDate (uint8_t day, uint8_t mon, sint32_t year, uint8_t hour, uint8_t min, uint8_t sec);

Description: Converts calendar date and wall clock time into Unix time format.

Parameters:

  • day - day of month [1-31] depends of month
  • mon - month of year [1-12]
  • year - year from beginning of Gregorian calendar
  • hour - hours [0-23]
  • min - minutes [0-59]
  • sec - seconds [0-59]

Return value:

  • Unix time value.
  • TIME_ERROR in case of any of parameters is out of range.

Note:Be aware that month range is 1-12 instead of range 0-11, which is used by standard C library. And year is full year number. Not since 1900.

Time extraction

Ctime_struct Time_ExtractTime (time_t time);
C++time_struct Time::ExtractTime (time_t time);

Description: Extracts wall clock time from specified Unix time value.

Parameters:

  • time - Unix time value from which wall clock time value should be extracted

Return value:

  • Time value in human readable format "HH:MM:SS".
  • "24:00:00" if Unix time is set to TIME_ERROR. Be aware that hour field is set to 24, which is out of hours range and indicates an error.

Date extraction

Cdate_struct Time_ExtractDate (time_t time);
C++date_struct Time::ExtractDate (time_t time);

Description: Converts time from Unix format to human readable calendar date format.

Parameters:

  • time - Unix time to convert

Return value:

  • Calendar date and time value in human readable format "YYYY-MM-DD HH:MM:SS".
  • "0000-00-00 00:00:00" if Unix time is set to TIME_ERROR. Be aware that all fields are set to 0, which indicates an error.

Week day extraction

Cuint8_t Time_WeekDay (time_t time);
C++uint8_t Time::WeekDay (time_t time);

Description: Extracts day of week from Unix time value.

Parameters:

  • time - Unix time value from which day of week should be extracted

Return value:

  • 0 - Sunday.
  • 1 - Monday.
  • 2 - Tuesday.
  • 3 - Wednesday.
  • 4 - Thursday.
  • 5 - Friday.
  • 6 - Saturday.
  • 7 if Unix time is set to TIME_ERROR. Be aware that returned value is out of week day range and indicates an error.

Current system time

Ctime_t Time_SystemTime (void);
C++time_t Time::SystemTime (void);

Description: Returns system's clock time value (current UTC time) from Linux kernel.

Parameters: None.

Return value:

  • Current UTC time value.
  • TIME_ERROR if system call returned an error value.

Local time

Ctime_t Time_LocalTime (const struct Time *tzone, time_t UTC);
C++time_t Time::LocalTime (time_t UTC) const;

Description: Converts UTC time to local time, using time zone data, previously loaded by "LoadTimeZone" function.

Parameters:

  • tzone - a pointer to time zone structure, which holds time correction data for selected time zone
  • UTC - UTC Unix time value which should be converted to local time

Return value:

  • Local time value in Unix time format, which corresponds to UTC time.
  • TIME_ERROR if UTC time is equal to TIME_ERROR or Time object was not initialized or has wrong data.
Copyright 2012-2016 Jack Black. All rights reserved.