MySQL 9.1.0
Source Code Documentation
Server time functions
Collaboration diagram for Server time functions:

Files

file  sql_time.cc
 Implementation of server functions to handle date and time.
 
file  sql_time.h
 Interface for server time utilities.
 

Functions

my_time_flags_t DatetimeConversionFlags (const THD *thd)
 Generate flags to use when converting a string to a date or datetime value. More...
 
static uint to_ascii (const CHARSET_INFO *cs, const char *src, size_t src_length, char *dst, size_t dst_length)
 Convert a string to 8-bit representation, for use in str_to_time/str_to_date/str_to_date. More...
 
bool str_to_time (const CHARSET_INFO *cs, const char *str, size_t length, MYSQL_TIME *l_time, my_time_flags_t flags, MYSQL_TIME_STATUS *status)
 Character set-aware version of str_to_time(). More...
 
bool str_to_datetime (const CHARSET_INFO *cs, const char *str, size_t length, MYSQL_TIME *l_time, my_time_flags_t flags, MYSQL_TIME_STATUS *status)
 Character set-aware version of str_to_datetime(). More...
 
bool str_to_datetime_with_warn (String *str, MYSQL_TIME *l_time, my_time_flags_t flags)
 Convert a timestamp string to a MYSQL_TIME value and produce a warning if string was truncated during conversion. More...
 
static bool lldiv_t_to_datetime (lldiv_t lld, MYSQL_TIME *ltime, my_time_flags_t flags, int *warnings)
 Convert lldiv_t to datetime. More...
 
bool decimal_to_datetime (const my_decimal *decimal, MYSQL_TIME *ltime, my_time_flags_t flags)
 Convert decimal value to datetime. More...
 
bool my_decimal_to_datetime_with_warn (const my_decimal *decimal, MYSQL_TIME *ltime, my_time_flags_t flags)
 Convert decimal value to datetime value with a warning. More...
 
bool double_to_datetime (double nr, MYSQL_TIME *ltime, my_time_flags_t flags)
 Convert double value to datetime. More...
 
bool my_double_to_datetime_with_warn (double nr, MYSQL_TIME *ltime, my_time_flags_t flags)
 Convert double value to datetime value with a warning. More...
 
bool my_longlong_to_datetime_with_warn (longlong nr, MYSQL_TIME *ltime, my_time_flags_t flags)
 Convert longlong value to datetime value with a warning. More...
 
static bool lldiv_t_to_time (lldiv_t lld, MYSQL_TIME *ltime, int *warnings)
 Convert lldiv_t value to time with nanosecond rounding. More...
 
bool decimal_to_time (const my_decimal *decimal, MYSQL_TIME *ltime)
 Convert decimal number to TIME. More...
 
bool my_decimal_to_time_with_warn (const my_decimal *decimal, MYSQL_TIME *ltime)
 Convert decimal number to TIME. More...
 
bool double_to_time (double nr, MYSQL_TIME *ltime)
 Convert double number to TIME. More...
 
bool my_double_to_time_with_warn (double nr, MYSQL_TIME *ltime)
 Convert double number to TIME. More...
 
bool my_longlong_to_time_with_warn (longlong nr, MYSQL_TIME *ltime)
 Convert longlong number to TIME. More...
 
bool datetime_with_no_zero_in_date_to_timeval (const MYSQL_TIME *ltime, const Time_zone &tz, my_timeval *tm, int *warnings)
 Converts a datetime in MYSQL_TIME representation to corresponding struct timeval value. More...
 
bool datetime_to_timeval (const MYSQL_TIME *ltime, const Time_zone &tz, my_timeval *tm, int *warnings)
 Convert a datetime MYSQL_TIME representation to corresponding "struct timeval" value. More...
 
bool str_to_time_with_warn (String *str, MYSQL_TIME *l_time)
 Convert a time string to a MYSQL_TIME struct and produce a warning if string was cut during conversion. More...
 
void time_to_datetime (THD *thd, const MYSQL_TIME *ltime, MYSQL_TIME *ltime2)
 Convert time to datetime. More...
 
const char * get_date_time_format_str (const Known_date_time_format *format, enum_mysql_timestamp_type type)
 Return format string according format name. More...
 
void make_time (const Date_time_format *format, const MYSQL_TIME *l_time, String *str, uint dec)
 Convert TIME value to String. More...
 
void make_date (const Date_time_format *format, const MYSQL_TIME *l_time, String *str)
 Convert DATE value to String. More...
 
void make_datetime (const Date_time_format *format, const MYSQL_TIME *l_time, String *str, uint dec)
 Convert DATETIME value to String. More...
 
bool my_TIME_to_str (const MYSQL_TIME *ltime, String *str, uint dec)
 Convert TIME/DATE/DATETIME value to String. More...
 
bool make_truncated_value_warning (THD *thd, Sql_condition::enum_severity_level level, const ErrConvString &val, enum_mysql_timestamp_type time_type, const char *field_name)
 Create and add a truncated value warning to the THD. More...
 
bool date_add_interval_with_warn (THD *thd, MYSQL_TIME *ltime, interval_type int_type, Interval interval)
 Uses propagate_datetime_overflow() to handle and propagate any warnings from date_add_interval() to the THD. More...
 
void propagate_datetime_overflow_helper (THD *thd, int *warnings)
 Propagates a DATETIME_OVERFLOW warning from warnings bitfield to DA in thd. More...
 
my_decimalmy_decimal_from_datetime_packed (my_decimal *dec, enum enum_field_types type, longlong packed_value)
 Unpack packed numeric temporal value to date/time value and then convert to decimal representation. More...
 
ulonglong gmt_time_to_local_time (ulonglong gmt_time)
 This function gets GMT time and adds value of time_zone to get the local time. More...
 
MYSQL_TIME my_time_set (uint y, uint m, uint d, uint h, uint mi, uint s, unsigned long ms, bool negative, enum_mysql_timestamp_type type)
 In lieu of a proper constructor for the C struct MYSQL_TIME, this method initializes the struct. More...
 
uint actual_decimals (const MYSQL_TIME *ts)
 Return the number of significant second fraction decimals in ts, e.g. More...
 
size_t max_fraction (uint decimals)
 For a time fraction with a given number of decimals, return maximum fraction, if any, can be are present in a time value. More...
 

Variables

const LEX_CSTRING interval_type_to_name [INTERVAL_LAST]
 Name description of interval names used in statements. More...
 
my_time_t TIME_to_timestamp (const MYSQL_TIME *t, const Time_zone &tz, bool *not_exist)
 
void time_to_datetime (THD *thd, const MYSQL_TIME *tm, const Time_zone &tz, MYSQL_TIME *dt)
 
template<class T >
propagate_datetime_overflow (THD *thd, int *warnings, T t)
 Wrapper function which will propagate any DATETIME_OVERFLOW warnings to the THD. More...
 
template<class CLOS >
auto propagate_datetime_overflow (THD *thd, CLOS &&clos)
 Wrapper function which will propagate any DATETIME_OVERFLOW warnings to the THD. More...
 
bool str_to_time (const String *str, MYSQL_TIME *ltime, my_time_flags_t flags, MYSQL_TIME_STATUS *status)
 Converts a time String value to MYSQL_TIME. More...
 
bool str_to_datetime (const String *str, MYSQL_TIME *ltime, my_time_flags_t flags, MYSQL_TIME_STATUS *status)
 Converts a datetime String value to MYSQL_TIME. More...
 
enum_mysql_timestamp_type field_type_to_timestamp_type (enum enum_field_types type)
 Return the timstamp value corresponding the field type passed as argument. More...
 

Detailed Description

Functions to create default time/date/datetime

strings
Note
For the moment the Date_time_format argument is ignored because MySQL doesn't support comparing of date/time/datetime strings that are not in arbutary order as dates are compared as strings in some context) This functions don't check that given MYSQL_TIME structure members are in valid range. If they are not, return value won't reflect any valid date either. Additionally, make_time doesn't take into account time->day member: it's assumed that days have been converted to hours already.

Function Documentation

◆ actual_decimals()

uint actual_decimals ( const MYSQL_TIME ts)

Return the number of significant second fraction decimals in ts, e.g.

for ts->second_part == 120300, return 4.

Parameters
tsthe time value for which we want the number of decmals
Returns
the number of decimals

◆ date_add_interval_with_warn()

bool date_add_interval_with_warn ( THD thd,
MYSQL_TIME ltime,
interval_type  int_type,
Interval  interval 
)

Uses propagate_datetime_overflow() to handle and propagate any warnings from date_add_interval() to the THD.

Returns
False on success, true on error.

◆ datetime_to_timeval()

bool datetime_to_timeval ( const MYSQL_TIME ltime,
const Time_zone tz,
my_timeval tm,
int *  warnings 
)

Convert a datetime MYSQL_TIME representation to corresponding "struct timeval" value.

Things like '0000-01-01', '2000-00-01', '2000-01-00' (i.e. incomplete date) return error.

Things like '0000-00-00 10:30:30' or '0000-00-00 00:00:00.123456' (i.e. empty date with non-empty time) return error.

Zero datetime '0000-00-00 00:00:00.000000' is allowed and is mapper to {tv_sec=0, tv_usec=0}.

Note: In case of error, tm value is not initialized.

Note: "warnings" is not initialized to zero, so new warnings are added to the old ones. Caller must make sure to initialize "warnings".

Parameters
[in]ltimedatetime value
[in]tzThe time zone.
[out]tmtimeval value
[out]warningspointer to warnings vector
Returns
False on success, true on error.

◆ datetime_with_no_zero_in_date_to_timeval()

bool datetime_with_no_zero_in_date_to_timeval ( const MYSQL_TIME ltime,
const Time_zone tz,
my_timeval tm,
int *  warnings 
)

Converts a datetime in MYSQL_TIME representation to corresponding struct timeval value.

ltime must be previously checked for TIME_NO_ZERO_IN_DATE. Things like '0000-01-01', '2000-00-01', '2000-01-00' are not allowed and asserted.

Things like '0000-00-00 10:30:30' or '0000-00-00 00:00:00.123456' (i.e. empty date with non-empty time) return error.

Zero datetime '0000-00-00 00:00:00.000000' is allowed and is mapped to {tv_sec=0, tv_usec=0}.

Note
In case of error, tm value is not initialized.
warnings is not initialized to zero, so new warnings are added to the old ones. The caller must make sure to initialize warnings.
Parameters
[in]ltimeDatetime value
[in]tzTime zone to convert to.
[out]tmTimeval value
[out]warningsPointer to warnings.
Returns
False on success, true on error.

◆ DatetimeConversionFlags()

my_time_flags_t DatetimeConversionFlags ( const THD thd)

Generate flags to use when converting a string to a date or datetime value.

Parameters
thdThread handle
Returns
Flags to use for calls to e.g my_str_to_datetime()

◆ decimal_to_datetime()

bool decimal_to_datetime ( const my_decimal decimal,
MYSQL_TIME ltime,
my_time_flags_t  flags 
)

Convert decimal value to datetime.

Parameters
decimalThe value to convert from.
[out]ltimeThe variable to convert to.
flagsConversion flags.
Returns
false on success, true if not convertible to datetime.

◆ decimal_to_time()

bool decimal_to_time ( const my_decimal decimal,
MYSQL_TIME ltime 
)

Convert decimal number to TIME.

Parameters
decimalThe number to convert from.
[out]ltimeThe variable to convert to.
Returns
false on success, true if not convertible to time.

◆ double_to_datetime()

bool double_to_datetime ( double  nr,
MYSQL_TIME ltime,
my_time_flags_t  flags 
)

Convert double value to datetime.

Parameters
nrThe value to convert from.
[out]ltimeThe variable to convert to.
flagsConversion flags.
Returns
false on success, true if not convertible to datetime.

◆ double_to_time()

bool double_to_time ( double  nr,
MYSQL_TIME ltime 
)

Convert double number to TIME.

Parameters
nrThe number to convert from.
[out]ltimeThe variable to convert to.
Returns
false on success, true if not convertible to time.

◆ field_type_to_timestamp_type()

enum_mysql_timestamp_type field_type_to_timestamp_type ( enum enum_field_types  type)
inline

Return the timstamp value corresponding the field type passed as argument.

Parameters
typefield type
Returns
corresponding timestamp type

◆ get_date_time_format_str()

const char * get_date_time_format_str ( const Known_date_time_format format,
enum_mysql_timestamp_type  type 
)

Return format string according format name.

If name is unknown, result is NULL

Returns
format string according format name.
Return values
NULLif name is unknown.

◆ gmt_time_to_local_time()

ulonglong gmt_time_to_local_time ( ulonglong  gmt_time)

This function gets GMT time and adds value of time_zone to get the local time.

This function is used when server wants a timestamp value from dictionary system.

Parameters
gmt_timeGMT time value.
Returns
time as ulonglong

◆ lldiv_t_to_datetime()

static bool lldiv_t_to_datetime ( lldiv_t  lld,
MYSQL_TIME ltime,
my_time_flags_t  flags,
int *  warnings 
)
static

Convert lldiv_t to datetime.

Parameters
lldThe value to convert from.
[out]ltimeThe variable to convert to.
flagsConversion flags.
[in,out]warningsWarning flags.
Returns
False on success, true on error.

◆ lldiv_t_to_time()

static bool lldiv_t_to_time ( lldiv_t  lld,
MYSQL_TIME ltime,
int *  warnings 
)
static

Convert lldiv_t value to time with nanosecond rounding.

Parameters
lldThe value to convert from.
[out]ltimeThe variable to convert to,
[in,out]warningsWarning flags.
Returns
False on success, true on error.

◆ make_date()

void make_date ( const Date_time_format format,
const MYSQL_TIME l_time,
String str 
)

Convert DATE value to String.

Parameters
formatFormat (unused, see comments above)
l_timeDATE value
[out]strString to convert to

◆ make_datetime()

void make_datetime ( const Date_time_format format,
const MYSQL_TIME l_time,
String str,
uint  dec 
)

Convert DATETIME value to String.

Parameters
formatFormat (unused, see comments above)
l_timeDATE value
[out]strString to convert to
decNumber of fractional digits.

◆ make_time()

void make_time ( const Date_time_format format,
const MYSQL_TIME l_time,
String str,
uint  dec 
)

Convert TIME value to String.

Parameters
formatFormat (unused, see comments above)
l_timeTIME value
[out]strString to convert to
decNumber of fractional digits.

◆ make_truncated_value_warning()

bool make_truncated_value_warning ( THD thd,
Sql_condition::enum_severity_level  level,
const ErrConvString val,
enum_mysql_timestamp_type  time_type,
const char *  field_name 
)

Create and add a truncated value warning to the THD.

Returns
value of thd->is_error() after adding the warning

◆ max_fraction()

size_t max_fraction ( uint  decimals)

For a time fraction with a given number of decimals, return maximum fraction, if any, can be are present in a time value.

For example, if 2 decimals are specified, return 990000. If none, 0.

Parameters
decimalsthe number of decimals
Returns
the maximum fraction

◆ my_decimal_from_datetime_packed()

my_decimal * my_decimal_from_datetime_packed ( my_decimal dec,
enum enum_field_types  type,
longlong  packed_value 
)

Unpack packed numeric temporal value to date/time value and then convert to decimal representation.

Parameters
[out]decThe variable to write to.
typeMySQL field type.
packed_valuePacked numeric temporal representation.
Returns
A decimal value in on of the following formats, depending on type: YYYYMMDD, hhmmss.ffffff or YYMMDDhhmmss.ffffff.

◆ my_decimal_to_datetime_with_warn()

bool my_decimal_to_datetime_with_warn ( const my_decimal decimal,
MYSQL_TIME ltime,
my_time_flags_t  flags 
)

Convert decimal value to datetime value with a warning.

Parameters
decimalThe value to convert from.
[out]ltimeThe variable to convert to.
flagsConversion flags.
Returns
False on success, true on error.

◆ my_decimal_to_time_with_warn()

bool my_decimal_to_time_with_warn ( const my_decimal decimal,
MYSQL_TIME ltime 
)

Convert decimal number to TIME.

Parameters
decimalThe number to convert from.
[out]ltimeThe variable to convert to.
Returns
False on success, true on error.

◆ my_double_to_datetime_with_warn()

bool my_double_to_datetime_with_warn ( double  nr,
MYSQL_TIME ltime,
my_time_flags_t  flags 
)

Convert double value to datetime value with a warning.

Parameters
nrThe value to convert from.
[out]ltimeThe variable to convert to.
flagsConversion flags.
Returns
False on success, true on error.

◆ my_double_to_time_with_warn()

bool my_double_to_time_with_warn ( double  nr,
MYSQL_TIME ltime 
)

Convert double number to TIME.

Parameters
nrThe number to convert from.
[out]ltimeThe variable to convert to.
Returns
False on success, true on error.

◆ my_longlong_to_datetime_with_warn()

bool my_longlong_to_datetime_with_warn ( longlong  nr,
MYSQL_TIME ltime,
my_time_flags_t  flags 
)

Convert longlong value to datetime value with a warning.

Parameters
nrThe value to convert from.
[out]ltimeThe variable to convert to.
flagsConversion flags
Returns
False on success, true on error.

◆ my_longlong_to_time_with_warn()

bool my_longlong_to_time_with_warn ( longlong  nr,
MYSQL_TIME ltime 
)

Convert longlong number to TIME.

Parameters
nrThe number to convert from.
[out]ltimeThe variable to convert to.
Returns
False on success, true on error.

◆ my_time_set()

MYSQL_TIME my_time_set ( uint  y,
uint  m,
uint  d,
uint  h,
uint  mi,
uint  s,
unsigned long  ms,
bool  negative,
enum_mysql_timestamp_type  type 
)

In lieu of a proper constructor for the C struct MYSQL_TIME, this method initializes the struct.

◆ my_TIME_to_str()

bool my_TIME_to_str ( const MYSQL_TIME ltime,
String str,
uint  dec 
)

Convert TIME/DATE/DATETIME value to String.

Parameters
ltimeDATE value
[out]strString to convert to
decNumber of fractional digits.

◆ propagate_datetime_overflow() [1/2]

template<class CLOS >
auto propagate_datetime_overflow ( THD thd,
CLOS &&  clos 
)
inline

Wrapper function which will propagate any DATETIME_OVERFLOW warnings to the THD.

Overload for the case when a warnings bitset must be created and inspected to call a mysys function. The mysys function must be invoked by the closure argument which invoked with a pointer to the warnings bitset as argument.

Parameters
thdThread context
closclosure to call with empty warnings bitset
Returns
return value of closure

◆ propagate_datetime_overflow() [2/2]

template<class T >
T propagate_datetime_overflow ( THD thd,
int *  warnings,
t 
)
inline

Wrapper function which will propagate any DATETIME_OVERFLOW warnings to the THD.

Overload for the case where a warnings bitset already exists which can be inspected before the value of the mysys function is passed on.

Parameters
thdThread context
warningsbitset used mysys function
tvalue mysys function which is passed on
Returns
t

◆ propagate_datetime_overflow_helper()

void propagate_datetime_overflow_helper ( THD thd,
int *  warnings 
)

Propagates a DATETIME_OVERFLOW warning from warnings bitfield to DA in thd.

Parameters
thdthread context
[in,out]warningsbitfield of warnings set

◆ str_to_datetime() [1/2]

bool str_to_datetime ( const CHARSET_INFO cs,
const char *  str,
size_t  length,
MYSQL_TIME l_time,
my_time_flags_t  flags,
MYSQL_TIME_STATUS status 
)

Character set-aware version of str_to_datetime().

Returns
False on success, true on error.

◆ str_to_datetime() [2/2]

bool str_to_datetime ( const String str,
MYSQL_TIME ltime,
my_time_flags_t  flags,
MYSQL_TIME_STATUS status 
)
inline

Converts a datetime String value to MYSQL_TIME.

Forwards to the version taking an explicit charset, c-string and length.

Returns
False on success, true on error.

◆ str_to_datetime_with_warn()

bool str_to_datetime_with_warn ( String str,
MYSQL_TIME l_time,
my_time_flags_t  flags 
)

Convert a timestamp string to a MYSQL_TIME value and produce a warning if string was truncated during conversion.

Note
See description of str_to_datetime() for more information.
Uses current_thd
Returns
False on success, true on error.

◆ str_to_time() [1/2]

bool str_to_time ( const CHARSET_INFO cs,
const char *  str,
size_t  length,
MYSQL_TIME l_time,
my_time_flags_t  flags,
MYSQL_TIME_STATUS status 
)

Character set-aware version of str_to_time().

Returns
False on success, true on error.

◆ str_to_time() [2/2]

bool str_to_time ( const String str,
MYSQL_TIME ltime,
my_time_flags_t  flags,
MYSQL_TIME_STATUS status 
)
inline

Converts a time String value to MYSQL_TIME.

Forwards to the version taking an explicit charset, c-string and length.

Returns
False on success, true on error.

◆ str_to_time_with_warn()

bool str_to_time_with_warn ( String str,
MYSQL_TIME l_time 
)

Convert a time string to a MYSQL_TIME struct and produce a warning if string was cut during conversion.

Note
See str_to_time() for more info.
Returns
False on success, true on error.

◆ time_to_datetime() [1/2]

void time_to_datetime ( THD thd,
const MYSQL_TIME ltime,
MYSQL_TIME ltime2 
)

Convert time to datetime.

The time value is added to the current datetime value.

Parameters
thdThread context
[in]ltimeTime value to convert from.
[out]ltime2Datetime value to convert to.

◆ time_to_datetime() [2/2]

void time_to_datetime ( THD thd,
const MYSQL_TIME tm,
const Time_zone tz,
MYSQL_TIME dt 
)

◆ TIME_to_timestamp()

my_time_t TIME_to_timestamp ( const MYSQL_TIME t,
const Time_zone tz,
bool *  not_exist 
)

◆ to_ascii()

static uint to_ascii ( const CHARSET_INFO cs,
const char *  src,
size_t  src_length,
char *  dst,
size_t  dst_length 
)
static

Convert a string to 8-bit representation, for use in str_to_time/str_to_date/str_to_date.

In the future to_ascii() can be extended to convert non-ASCII digits to ASCII digits (for example, ARABIC-INDIC, DEVANAGARI, BENGALI, and so on) so DATE/TIME/DATETIME values understand digits in the respected scripts.

Returns
number of bytes written to dst

Variable Documentation

◆ interval_type_to_name

const LEX_CSTRING interval_type_to_name[INTERVAL_LAST]
Initial value:
= {
{STRING_WITH_LEN("YEAR")},
{STRING_WITH_LEN("QUARTER")},
{STRING_WITH_LEN("MONTH")},
{STRING_WITH_LEN("WEEK")},
{STRING_WITH_LEN("DAY")},
{STRING_WITH_LEN("HOUR")},
{STRING_WITH_LEN("MINUTE")},
{STRING_WITH_LEN("SECOND")},
{STRING_WITH_LEN("MICROSECOND")},
{STRING_WITH_LEN("YEAR_MONTH")},
{STRING_WITH_LEN("DAY_HOUR")},
{STRING_WITH_LEN("DAY_MINUTE")},
{STRING_WITH_LEN("DAY_SECOND")},
{STRING_WITH_LEN("HOUR_MINUTE")},
{STRING_WITH_LEN("HOUR_SECOND")},
{STRING_WITH_LEN("MINUTE_SECOND")},
{STRING_WITH_LEN("DAY_MICROSECOND")},
{STRING_WITH_LEN("HOUR_MICROSECOND")},
{STRING_WITH_LEN("MINUTE_MICROSECOND")},
{STRING_WITH_LEN("SECOND_MICROSECOND")}}
#define STRING_WITH_LEN(X)
Definition: string_with_len.h:29

Name description of interval names used in statements.

'interval_type_to_name' is ordered and sorted on interval size and interval complexity. Order of elements in 'interval_type_to_name' should correspond to the order of elements in 'interval_type' enum

See also
interval_type, interval_names