DateTime.dll  A lightweight library for manipulating dates and time

Copyright 2011-2017 Roberto Bianchi

Softspecialists - www.softspecialists.com

Introduction

DateTime is a library that provides support for date and time calculation. It's very useful in order to avoid wasting time with time calculations, formatting and date evaluation.

DateTime is compatible with all versions of Windows starting with version 98.

Using DateTime

DateTime is implemented as DLL that export some functions using the __stdcall calling convention like all Win32 APIs functions.

You can use the DATETIME.DLL both using dynamic or static linkage as showed in the sample code provided with the library.

Functions Reference

DWORD WINAPI Date10To8(__in LPCSTR  szpDate10, __out LPSTR szpDate8)

Packs a date removing the separators.

 

 szpDate10

Pointer to the buffer that holds the 10 bytes strings to pack. Typically this string will look like "12-31-2011", so this function remove the date separator.

 

 szpDate8

Pointer to the buffer that will receive the 8 bytes strings. Typically this string will look like "12312011", so this function remove the date separator. This buffer must allocate 9 bytes lenght (8 for the date plus 1 for the null byte).

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


DWORD WINAPI Date8To10(__in LPCSTR  szpDate8, __out LPSTR szpDate10)

Unpacks a date inserting the separators.

 

 szpDate8

Pointer to the 8 bytes string that should be extended to 10 bytes strings. Typically this string looks like "12312011".

 

 szpDate10

Pointer to the buffer that will receive the 10 bytes strings. Typically this string will look like "12-31-2011", so this function insert the date separator. This buffer must allocate 11 bytes lenght (10 for the date plus 1 for the null byte).

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


void  WINAPI DateToSeconds(__in LPCSTR  szpDate10,  __out LPINT64 nSeconds)

Converts a date in it's equivalent number of seconds starting from the date set by TimeBaseLine.

 

 szpDate10

Pointer to the date string that should be converted to seconds. Typically this string looks like "12-31-2011".

 

 nSeconds

Pointer to 64 bit integer that will receive the number of seconds. This value is calculed as seconds from the time base line to the specified date.

 

Return Value

This function has no return value.


DWORD  WINAPI DaysFromBOY(__in LPCSTR  szpDate10)

Calculates the number of days elapsed since the beginning of the year.

 

 szpDate10

Pointer to the date string. Typically this string looks like "12-31-2011".

 

Return Value

Returns the elapsed number of days.


DWORD  WINAPI DaysToEOY(__in LPCSTR  szpDate10)

Calculates the number of days before the end of the year.

 

 szpDate10

Pointer to the date string. Typically this string looks like "12-31-2011".

 

Return Value

Returns the remaining number of days.


void WINAPI DaysToSeconds(__in DWORD dwDays, __out LPINT64 nSeconds)

Calculates the number of seconds from a given number of days.

 

dwDays

Numbers of days to convert into seconds.

 

nSeconds

Pointer to 64 bit integer that will receive the number of seconds.

 

Return Value

This function has no return value.


void WINAPI FormatDate(__in DWORD nMonth, __in DWORD nDay, __in DWORD nYear, __out LPSTR szpDate10)

Giving it's numeric values build a date string using date separator character.

 

 nMonth

Month to be used in formatting the date.

 

 nDay

Day to be used in formatting the date.

 

 nYear

Year to be used in formatting the date.

 

 szpDate10

Pointer to the buffer that will receive the 10 bytes strings. Typically this string will look like "12-31-2011", so this function insert the date separator. This buffer must allocate 11 bytes lenght (10 for the date plus 1 for the null byte).

 

Return Value

This function has no return value.


void WINAPI FormatTime(__in DWORD nHour, __in DWORD nMinute, __in DWORD nSecond, __out LPSTR szpTime8)

Giving it's numeric values build a time string using time separator character.

 

 nHour

Month to be used in formatting the date.

 

 nMinute

Day to be used in formatting the date.

 

 nSecond

Year to be used in formatting the date.

 

 szpTime8

Pointer to the buffer that will receive the 8 bytes strings. Typically this string will look like "22:30:01", so this function insert the time separator. This buffer must allocate 9 bytes lenght (8 for the time plus 1 for the null byte).

 

Return Value

This function has no return value.


void WINAPI GetDate(__out LPSTR szpDate10)

Retrieves the system date as string

 

 szpDate10

Pointer to the buffer that will receive the 10 bytes strings. Typically this string will look like "12-31-2011", so this function insert the date separator. This buffer must allocate 11 bytes lenght (10 for the date plus 1 for the null byte).

 

Return Value

This function has no return value.


DWORD WINAPI GetDateSeparator(void)

Retrieves the character use as date separator. The default value is "-".

 

Return Value

Returns the ASCII values of current date separator.


DWORD WINAPI GetDay(__in LPCSTR szpDate10)

Returns the numeric value of day from a given date string.

 

 szpDate10

Pointer to the buffer that holds the 10 bytes strings from where to extract the day. Typically this string looks like "12-31-2011". Actually this function can handle only date in the US date format that is "MM-DD-YYYY".

 

Return Value

This function returns the day of the given date, for example 31.


DWORD WINAPI GetDayOfWeek(__in LPCSTR szpDate10)

Returns the numeric value of day of week from a given date string.

 

 szpDate10

Pointer to the buffer that holds the 10 bytes strings from where to extract the day. Typically this string looks like "12-31-2011". Actually this function can handle only date in the US date format that is "MM-DD-YYYY".

 

Return Value

This function returns the day of the week, Sunday = 0, Monday = 1, and so on.


DWORD WINAPI GetDayOfWeekName(__in DWORD dwDay, __out LPSTR szpWeekDayName)

Build a time stamp from the actual system date and time string..

 

szpWeekDayName

Pointer to the buffer that will receive the week day name. Typically this string will look like "October". This buffer must be large enought to holds the day of week name. Since the lenght of the day of week name depends also from the language ID, the suggested lenght is 14 bytes.

 

Return Valuee

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


DWORD WINAPI GetHours(__in LPCSTR szpTime8)

Returns the hour (from 0 to 23) of the specified time string.

 

 szpTime8

Pointer to the buffer that holds the 8 bytes strings from where to extract the hour. Typically this string looks like "22:30:01".

 

Return Value

This function returns a number that correspond to the hour of given time, for example 22.


DWORD WINAPI GetLanguageID(void)

Returns the numeric value of primary language ID used for returning the day and month name.

 

Return Value

This function returns the primary language ID that can be one of following values:

0x07 German, 0x09 English, 0x0A Spanish, 0x0C French, 0x10 Italian, 0x13 Dutch, 0x16 Portuguese, 0x3FF Latin.


DWORD WINAPI GetMinutes(__in LPCSTR szpTime8)

Returns the minute (from 0 to 59) of the specified time string.

 

szpTime8

Pointer to the buffer that holds the 8 bytes strings from where to extract the minute. Typically this string looks like "22:30:01".

 

Return Value

This function returns a number that correspond to the minute of given time, for example 30.


DWORD WINAPI GetMonth(__in LPCSTR szpDate10)

Returns the numeric value of month from a given date string.

 

 szpDate10

Pointer to the buffer that holds the 10 bytes strings from where to extract the month. Typically this string looks like "12-31-2011". Actually this function can handle only date in the US date format that is "MM-DD-YYYY".

 

Return Value

This function returns the month of the given date, for example 12.


BOOL WINAPI GetMonthName(__in dwMonth, __out LPSTR szMonthName)

Returns the name of given numeric month.

 

dwMonth

The month numbers.

 

szMonthName

A buffer that will receive the month name. It should be large enought to holds the month name. Since the lenght of the month name depends also from the language ID, the suggested lenght is 11 bytes.

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


DWORD WINAPI GetSeconds(__in LPCSTR szpTime)

Returns the second (from 0 to 59) of the specified time string.

 

szpTime8

Pointer to the buffer that holds the 8 bytes strings from where to extract the second. Typically this string looks like "22:30:01".

 

Return Value

This function returns a number that correspond to the minute of given time, for example 1.


void WINAPI GetTime(__out LPSTR szpTime8)

Retrives the current values of time as string.

 

szpDate10

Pointer to the buffer that will receive the 8 bytes strings. Typically this string will look like "22:30:01", so this function insert the time separator. This buffer must allocate 9 bytes lenght (8 for the time plus 1 for the null byte).

 

Return Value

This function has no return value.


DWORD WINAPI GetTimeBaseLine(__out DWORD_PTR nMonth, __out DWORD_PTR nDay, __out DWORD_PTR nYear)

Retrives the TimeBaseLine used as beginning for date calculation. Default values is January, 1 1061.

 

 nMonth

Month currently use for base as date calculation. Default 1.

 

 nDay

Day currently use for base as date calculation. Default 1.

 

 nYear

Year currently use for base as date calculation. Default 1061.

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


DWORD WINAPI GetTimeSeparator(void)

Retrieves the character use as time separator. The default value is ":".

 

Return Value

Returns the ASCII values of current time separator.


DWORD WINAPI GetTimeStamp(__in LPCSTR szpDate10, __in LPCSTR szpTime8, __out LPSTR szpTimeStamp14)

Build a time stamp from a given date and time string.

 

 szpDate10

Pointer to the buffer that holds the 10 bytes date strings. Typically this string looks like "12-31-2011". Actually this function can handle only date in the US date format that is "MM-DD-YYYY".

 

 szpTime8

Pointer to the buffer that holds the 8 bytes time strings. Typically this string looks like "22:30:01".

 

 szpTimeStamp14

Pointer to the buffer that will receive the time stamp string. Typically this string will look like "20111231223001". This buffer must allocate 15 bytes lenght (14 for the date and time plus 1 for the null byte).

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


DWORD WINAPI GetTimeStampNow(__out LPSTR szpTimeStamp14)

Build a time stamp from the actual system date and time string.

 

 szpTimeStamp14

Pointer to the buffer that will receive the time stamp string. Typically this string will look like "20111231223001". This buffer must allocate 15 bytes lenght (14 for the date and time plus 1 for the null byte).

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


DWORD WINAPI GetWeekNumber(__in LPCSTR szpDate10)

Returns the week number of the specified date.

 

 szpDate10

Pointer to the buffer that holds the 10 bytes strings from where to extract the year. Typically this string looks like "12-31-2011". Actually this function can handle only date in the US date format that is "MM-DD-YYYY".

 

Return Value

This function returns the year of the given date, for example 52.


DWORD WINAPI GetYear(__in LPCSTR sz)

Returns the numeric value of year from a given date string.

 

 szpDate10

Pointer to the buffer that holds the 10 bytes strings from where to extract the year. Typically this string looks like "12-31-2011". Actually this function can handle only date in the US date format that is "MM-DD-YYYY".

 

Return Value

This function returns the year of the given date, for example 2011.


void WINAPI HoursToSeconds(__in DWORD dwHours, __out LPINT64 nSeconds)

Calculates the number of seconds from a given number of hours.

 

 dwHours

Numbers of hours to convert into seconds.

 

 nSeconds

Pointer to 64 bit integer that will receive the number of seconds.

 

Return Value

This function has no return value.


BOOL WINAPI IsLeapYear(__in DWORD nYear)

Checks if a given year is leap or not.

 

 szpDate10

Pointer to the buffer that holds the 10 bytes strings from where to extract the year. Typically this string looks like "12-31-2011". Actually this function can handle only date in the US date format that is "MM-DD-YYYY".

 

Return Value

If the given year is leap this function returns nonzero otherwise returns zero.


BOOL WINAPI IsValidDate(__in LPCSTR szpDate10)

Checks if a given date is valid.

 

 szpDate10

Pointer to the buffer that holds the 10 bytes strings from where to extract the year. Typically this string looks like "12-31-2011". Actually this function can handle only date in the US date format that is "MM-DD-YYYY".

 

Return Value

If the given date is valid this function returns nonzero otherwise returns zero.


BOOL WINAPI IsValidTime(__in LPCSTR szpTime8)

Checks if a given time is valid.

 

 szpTime8

Pointer to the buffer that holds the 8 bytes strings from where to extract the year. Typically this string looks like "22:30:01".

 

Return Value

If the given time is valid this function returns nonzero otherwise returns zero.


BOOL WINAPI IsWorkingDay(__in LPCSTR szpDate10, __in DWORD dwSatIsWorkDay)

Checks if the corresponding day of given date is a working day given date is valid.

 

 szpDate10

Pointer to the buffer that holds the 10 bytes strings from where to extract the year. Typically this string looks like "12-31-2011". Actually this function can handle only date in the US date format that is "MM-DD-YYYY".

 

 dwSatIsWorkDay

Set this parameter to non zero values if you want evaluate Saturday as working day. If it's zero both Saturday and Sunday are not working days.

 

Return Value

If the corresponding day of given date is a working day this function returns nonzero otherwise returns zero.


void  WINAPI SecondsFromMidnight(__in LPCSTR szpTime8, __out LPINT64 nSeconds)

Converts a number of seconds into it's equivalent date string, the calculation is based on starting date set by TimeBaseLine.

 

szpTime8

Pointer to the time string. Typically this string will look like "22:30:01".  This buffer must allocate 9 bytes lenght (8 for the date plus 1 for the null byte).

 

 nSeconds

A pointer to 64 bit integer that will receive the numbers of seconds elapsed from midnight of given time string.

 

Return Value

This function has no return value.


void  WINAPI SecondsToDate(__in INT64 nSeconds, __out LPSTR  szpDate10)

Converts a number of seconds into it's equivalent date string, the calculation is based on starting date set by TimeBaseLine.

 

nSeconds

A 64 bit integer that holds the numbers of seconds to convert as date.

 

 szpDate10

Pointer to the date string that correspond to the givin number of seconds be converted to seconds. Typically this string will look like "12-31-2011".  This buffer must allocate 11 bytes lenght (10 for the date plus 1 for the null byte).

 

Return Value

This function has no return value.


DWORD WINAPI SecondsToDays(__in INT64 nSeconds)

Converts a number of seconds into it's equivalent numbers of days.

 

nSeconds

A 64 bit integer that holds the numbers of seconds to convert as days.

 

Return Value

This function returns  the numebr of day that corresponding to the passed number of seconds.


DWORD WINAPI SecondsToHours(__in INT64 nSeconds)

Converts a number of seconds into it's equivalent numbers of hours.

 

nSeconds

A 64 bit integer that holds the numbers of seconds to convert as hours.

 

Return Value

This function returns  the numebr of day that corresponding to the passed number of seconds.


DWORD WINAPI SetDateSeparator(__in DWORD nDateSeparator)

Sets the character use as date separator. Default value is internally set to "-".

 

 nDateSeparator

The ASCII code of date separator character to use.

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


DWORD WINAPI SetLanguageID(__in DWORD dwLanguageID)

Sets the primary language identifier to be used for returning the day and month name in the correct language.

 

dwLanguageID

language ID that can be one of following values: 0x07 German, 0x09 English, 0x0A Spanish, 0x0C French, 0x10 Italian, 0x13 Dutch, 0x16 Portuguese, 0x3FF Latin. If you don't specify a language ID the DLL retrieve the primary language ID from Windows and then use it.

 

Return Value

The return value is the new language ID.


DWORD WINAPI SetTimeBaseLine(__in DWORD nMonth, __in DWORD nDay, __in DWORD_PTR nYear)

Sets the TimeBaseLine used as beginning for date calculation. Default values is January, 1 1061.

 

 nMonth

Month to use for base as date calculation. Default 1.

 

 nDay

Day to use for base as date calculation. Default 1.

 

 nYear

Year to use for base as date calculation. Default 1061.

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


DWORD WINAPI SetTimeSeparator(__in DWORD nTimeSeparator)

Sets the character use as time separator. Default value is internally set to ":".

 

 nTimeSeparator

The ASCII code of time separator character to use.

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


DWORD WINAPI Time6To8(__in LPCSTR  szpTime6, __out LPSTR szpTime8)

Unpacks a time string inserting the separators.

 

 szpTime6

Pointer to the buffer that holds the 6 bytes time strings. Typically this string will look like "223001".

 

 szpTime8

Pointer to the buffer that will receive the 8 bytes time strings. Typically this string will look like "22:30:01", so this function inserts the date separator. This buffer must allocate 9 bytes lenght (8 for the time plus 1 for the null byte).

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


DWORD WINAPI Time8To6(__in LPCSTR  szpTime8, __out LPSTR szpTime6)

Packs a time string removing the separators.

 

 szpTime8

Pointer to the 8 bytes time string that should be packed to 6 bytes strings. Typically this string looks like "22:30:01".

 

 szpTime6

Pointer to the buffer that will receive the 6 bytes time strings. Typically this string will look like "223001", so this function remove the time separator. This buffer must allocate 7 bytes lenght (6 for the time plus 1 for the null byte).

 

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.


void WINAPI TimeFromMidnight(__in INT64 nSeconds, __out LPSTR szpTime6)

Converts a number of seconds elapsed from midnight into te correspondent time string.

 

 nSeconds

Number of seconds elapsed from midnight.

 

 szpTime6

Pointer to the buffer that will receive the 6 bytes time strings. Typically this string will look like "223001". This buffer must allocate 7 bytes lenght (6 for the time plus 1 for the null byte).

 

Return Value

This function has no return value.


 

Examples

Here are the some code fragments for VISUAL STUDIO 2010 EXPRESS C++ and POWER BASIC compilers:

The picture below shows a C++ dynamic linking example.

C Dynamic

The picture below shows a C++ example with static linking.

C Static

The picture below shows a PowerBASIC dynamic linking example.

PB Dynamic

The picture below shows a PowerBASIC example with static linking.

PB Static

Complete sources are encloses in the appropriate download.

Note

All strings used internally by the DLL are 8-bit Windows (ANSI) characters (not UNICODE) string terminated by the null byte, thus when allocate buffer for date and time string it's lenght must include the null byte.

The current versions of DTCALC.EXE utility is build around the DateTime.dll.