From eeab6fe60ea4ce2e4b0ece16aca889f09c39ae73 Mon Sep 17 00:00:00 2001 From: Egon Schmid Date: Wed, 1 Mar 2000 20:38:59 +0000 Subject: [PATCH] Only formatting, content hasn't changed. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@20803 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/datetime.xml | 608 ++++++++++++++++++++++++++++++----------- 1 file changed, 441 insertions(+), 167 deletions(-) diff --git a/functions/datetime.xml b/functions/datetime.xml index 04f88a686b..fedf1b41f5 100644 --- a/functions/datetime.xml +++ b/functions/datetime.xml @@ -5,7 +5,7 @@ checkdate - validate a date/time + Validate a date/time Description @@ -17,29 +17,34 @@ Returns true if the date given is valid; otherwise returns false. - Checks the validity of the date formed by the arguments. A date is - considered valid if: + Checks the validity of the date formed by the arguments. A date + is considered valid if: - + + year is between 0 and 32767 inclusive - - + + + + month is between 1 and 12 inclusive - - + + + + day is within the allowed number of days for the given month. Leap years are taken into consideration. - + + - date - format a local time/date + Format a local time/date Description @@ -55,70 +60,175 @@ Returns a string formatted according to the given format string using the given timestamp or the current - local time if no timestamp is given. - + local time if no timestamp is given. + The following characters are recognized in the format string: - a - "am" or "pm" - A - "AM" or "PM" - d - day of the month, 2 digits with leading zeros; i.e. "01" to "31" - D - day of the week, textual, 3 letters; i.e. "Fri" - F - month, textual, long; i.e. "January" - h - hour, 12-hour format; i.e. "01" to "12" - H - hour, 24-hour format; i.e. "00" to "23" - g - hour, 12-hour format without leading zeros; i.e. "1" to "12" - G - hour, 24-hour format without leading zeros; i.e. "0" to "23" - i - minutes; i.e. "00" to "59" - j - day of the month without leading zeros; i.e. "1" to "31" - l (lowercase 'L') - day of the week, textual, long; i.e. "Friday" - L - boolean for whether it is a leap year; i.e. "0" or "1" - m - month; i.e. "01" to "12" - n - month without leading zeros; i.e. "1" to "12" - M - month, textual, 3 letters; i.e. "Jan" - s - seconds; i.e. "00" to "59" - S - English ordinal suffix, textual, 2 characters; i.e. "th", "nd" - t - number of days in the given month; i.e. "28" to "31" - U - seconds since the epoch - w - day of the week, numeric, i.e. "0" (Sunday) to "6" (Saturday) - Y - year, 4 digits; i.e. "1999" - y - year, 2 digits; i.e. "99" - z - day of the year; i.e. "0" to "365" - Z - timezone offset in seconds (i.e. "-43200" to "43200") + + + a - "am" or "pm" + + + + + A - "AM" or "PM" + + + + + d - day of the month, 2 digits with leading zeros; i.e. "01" + to "31" + + + + + D - day of the week, textual, 3 letters; i.e. "Fri" + + + + + F - month, textual, long; i.e. "January" + + + + + h - hour, 12-hour format; i.e. "01" to "12" + + + + + H - hour, 24-hour format; i.e. "00" to "23" + + + + + g - hour, 12-hour format without leading zeros; i.e. "1" to + "12" + + + + + G - hour, 24-hour format without leading zeros; i.e. "0" to + "23" + + + + + i - minutes; i.e. "00" to "59" + + + + + j - day of the month without leading zeros; i.e. "1" to "31" + + + + + l (lowercase 'L') - day of the week, textual, long; + i.e. "Friday" + + + + + L - boolean for whether it is a leap year; i.e. "0" or "1" + + + + + m - month; i.e. "01" to "12" + + + + + n - month without leading zeros; i.e. "1" to "12" + + + + + M - month, textual, 3 letters; i.e. "Jan" + + + + + s - seconds; i.e. "00" to "59" + + + + + S - English ordinal suffix, textual, 2 characters; i.e. "th", + "nd" + + + + + t - number of days in the given month; i.e. "28" to "31" + + + + + U - seconds since the epoch + + + + + w - day of the week, numeric, i.e. "0" (Sunday) to "6" + (Saturday) + + + + + Y - year, 4 digits; i.e. "1999" + + + + + y - year, 2 digits; i.e. "99" + + + + + z - day of the year; i.e. "0" to "365" + + + + + Z - timezone offset in seconds (i.e. "-43200" to "43200") + + - Unrecognized characters in the format string will be printed as-is. - The "Z" format will always return "0" when using gmdate(). - + Unrecognized characters in the format string will be printed + as-is. The "Z" format will always return "0" when using + gmdate. - <function>date</function> example + <function>Date</function> example -print (date("l dS of F Y h:i:s A")); -print ("July 1, 2000 is on a " . date("l", mktime(0,0,0,7,1,2000))); +print (date ("l dS of F Y h:i:s A")); +print ("July 1, 2000 is on a " . date ("l", mktime(0,0,0,7,1,2000))); - + + It is possible to use date and mktime together to find dates in the future or the past. - - <function>date</function> and <function>mktime</function> example + <function>Date</function> and <function>mktime</function> + example -$tomorrow = mktime(0,0,0,date("m") ,date("d")+1,date("Y")); -$lastmonth = mktime(0,0,0,date("m")-1,date("d"), date("Y")); -$nextyear = mktime(0,0,0,date("m"), date("d"), date("Y")+1); +$tomorrow = mktime (0,0,0,date("m") ,date("d")+1,date("Y")); +$lastmonth = mktime (0,0,0,date("m")-1,date("d"), date("Y")); +$nextyear = mktime (0,0,0,date("m"), date("d"), date("Y")+1); - To format dates in other languages, you should use the setlocale and strftime functions. - See also gmdate and mktime. @@ -126,11 +236,10 @@ $nextyear = mktime(0,0,0,date("m"), date("d"), date("Y")+1); - getdate - get date/time information + Get date/time information Description @@ -139,20 +248,59 @@ $nextyear = mktime(0,0,0,date("m"), date("d"), date("Y")+1); int timestamp - Returns an associative array containing the date information of the - timestamp as the following array elements: + Returns an associative array containing the date information of + the timestamp as the following array elements: - "seconds" - seconds - "minutes" - minutes - "hours" - hours - "mday" - day of the month - "wday" - day of the week, numeric - "mon" - month, numeric - "year" - year, numeric - "yday" - day of the year, numeric; i.e. "299" - "weekday" - day of the week, textual, full; i.e. - "Friday" - "month" - month, textual, full; i.e. "January" + + + "seconds" - seconds + + + + + "minutes" - minutes + + + + + "hours" - hours + + + + + "mday" - day of the month + + + + + "wday" - day of the week, numeric + + + + + "mon" - month, numeric + + + + + "year" - year, numeric + + + + + "yday" - day of the year, numeric; i.e. "299" + + + + + "weekday" - day of the week, textual, full; i.e. "Friday" + + + + + "month" - month, textual, full; i.e. "January" + + @@ -161,7 +309,7 @@ $nextyear = mktime(0,0,0,date("m"), date("d"), date("Y")+1); gettimeofday - get current time + Get current time Description @@ -171,13 +319,29 @@ $nextyear = mktime(0,0,0,date("m"), date("d"), date("Y")+1); This is an interface to gettimeofday(2). It returns an - associative array containing the data returned from the - system call. + associative array containing the data returned from the system + call. - "sec" - seconds - "usec" - microseconds - "minuteswest" - minutes west of Greenwich - "dsttime" - type of dst correction + + + "sec" - seconds + + + + + "usec" - microseconds + + + + + "minuteswest" - minutes west of Greenwich + + + + + "dsttime" - type of dst correction + + @@ -186,7 +350,7 @@ $nextyear = mktime(0,0,0,date("m"), date("d"), date("Y")+1); gmdate - format a GMT/CUT date/time + Gormat a GMT/CUT date/time Description @@ -196,31 +360,29 @@ $nextyear = mktime(0,0,0,date("m"), date("d"), date("Y")+1); int timestamp - Identical to the date - function except that the time returned is Greenwich Mean Time - (GMT). For example, when run in Finland (GMT +0200), the first - line below prints "Jan 01 1998 00:00:00", while the second prints - "Dec 31 1997 22:00:00". + Identical to the date function except that + the time returned is Greenwich Mean Time (GMT). For example, when + run in Finland (GMT +0200), the first line below prints "Jan 01 + 1998 00:00:00", while the second prints "Dec 31 1997 22:00:00". - <function>gmdate</function> example + <function>Gmdate</function> example -echo date( "M d Y H:i:s",mktime(0,0,0,1,1,1998) ); -echo gmdate( "M d Y H:i:s",mktime(0,0,0,1,1,1998) ); +echo date ("M d Y H:i:s", mktime (0,0,0,1,1,1998)); +echo gmdate ("M d Y H:i:s", mktime (0,0,0,1,1,1998)); - See also date, - mktime and gmmktime. + See also date, mktime, + and gmmktime. - gmmktime - get UNIX timestamp for a GMT date + Get UNIX timestamp for a GMT date Description @@ -232,11 +394,13 @@ echo gmdate( "M d Y H:i:s",mktime(0,0,0,1,1,1998) ); int month int day int year - int is_dst + int + is_dst + - Identical to mktime except the passed parameters - represents a GMT date. + Identical to mktime except the passed + parameters represents a GMT date. @@ -244,7 +408,9 @@ echo gmdate( "M d Y H:i:s",mktime(0,0,0,1,1,1998) ); gmstrftime - format a GMT/CUT time/date according to locale settings + + Format a GMT/CUT time/date according to locale settings + Description @@ -257,13 +423,14 @@ echo gmdate( "M d Y H:i:s",mktime(0,0,0,1,1,1998) ); Behaves the same as strftime except that the time returned is Greenwich Mean Time (GMT). For example, when run in Eastern Standard Time (GMT -0500), the first line below prints - "Dec 31 1998 20:00:00", while the second prints "Jan 01 1999 01:00:00". + "Dec 31 1998 20:00:00", while the second prints "Jan 01 1999 + 01:00:00". - <function>gmstrftime</function> example + <function>Gmstrftime</function> example -setlocale ('LC_TIME','en_US'); -echo strftime ("%b %d %Y %H:%M:%S",mktime(20,0,0,12,31,98))."\n"; -echo gmstrftime ("%b %d %Y %H:%M:%S",mktime(20,0,0,12,31,98))."\n"; +setlocale ('LC_TIME', 'en_US'); +echo strftime ("%b %d %Y %H:%M:%S", mktime (20,0,0,12,31,98))."\n"; +echo gmstrftime ("%b %d %Y %H:%M:%S", mktime (20,0,0,12,31,98))."\n"; @@ -276,7 +443,8 @@ echo gmstrftime ("%b %d %Y %H:%M:%S",mktime(20,0,0,12,31,98))."\n"; microtime - return current UNIX timestamp with microseconds + + Return current UNIX timestamp with microseconds Description @@ -300,7 +468,7 @@ echo gmstrftime ("%b %d %Y %H:%M:%S",mktime(20,0,0,12,31,98))."\n"; mktime - get UNIX timestamp for a date + Get UNIX timestamp for a date Description @@ -312,52 +480,58 @@ echo gmstrftime ("%b %d %Y %H:%M:%S",mktime(20,0,0,12,31,98))."\n"; int month int day int year - int is_dst + int + is_dst + Warning: Note the strange order of - arguments, which differs from the order of arguments in - a regular UNIX mktime() call and which does not lend - itself well to leaving out parameters from right to left - (see below). It is a common error to mix these values up - in a script. + arguments, which differs from the order of arguments in a regular + UNIX mktime() call and which does not lend itself well to leaving + out parameters from right to left (see below). It is a common + error to mix these values up in a script. + Returns the Unix timestamp corresponding to the arguments given. This timestamp is a long integer containing the number of seconds between the Unix Epoch (January 1 1970) and the time specified. - + + Arguments may be left out in order from right to left; any arguments thus omitted will be set to the current value according to the local date and time. - - is_dst can be set to 1 if the time - is during daylight savings time, 0 if it is not, or -1 (the - default) if it is unknown whether the time is within daylight - savings time or not. + + + is_dst can be set to 1 if the time is + during daylight savings time, 0 if it is not, or -1 (the default) + if it is unknown whether the time is within daylight savings time + or not. - is_dst was added in 3.0.10. + + is_dst was added in 3.0.10. + - mktime is useful for doing date arithmetic and - validation, as it will automatically calculate the correct value - for out-of-range input. For example, each of the following lines - produces the string "Jan-01-1998". + Mktime is useful for doing date arithmetic + and validation, as it will automatically calculate the correct + value for out-of-range input. For example, each of the following + lines produces the string "Jan-01-1998". - <function>mktime</function> example + <function>Mktime</function> example -echo date( "M-d-Y", mktime(0,0,0,12,32,1997) ); -echo date( "M-d-Y", mktime(0,0,0,13,1,1997) ); -echo date( "M-d-Y", mktime(0,0,0,1,1,1998) ); -echo date( "M-d-Y", mktime(0,0,0,1,1,98) ); +echo date ("M-d-Y", mktime (0,0,0,12,32,1997)); +echo date ("M-d-Y", mktime (0,0,0,13,1,1997)); +echo date ("M-d-Y", mktime (0,0,0,1,1,1998)); +echo date ("M-d-Y", mktime (0,0,0,1,1,98)); - year may be a two or four digit value, with - values between 0-69 mapping to 2000-2069 and 70-99 to 1970-1999 - (on systems where time_t is a 32bit signed integer, as most common - today, the valid range for year is somewhere - between 1902 and 2037). + year may be a two or four digit value, + with values between 0-69 mapping to 2000-2069 and 70-99 to + 1970-1999 (on systems where time_t is a 32bit signed integer, as + most common today, the valid range for + year is somewhere between 1902 and 2037). The last day of any given month can be expressed as the "0" day @@ -365,12 +539,12 @@ echo date( "M-d-Y", mktime(0,0,0,1,1,98) ); will produce the string "The last day in Feb 2000 is: 29". Last day of next month - -$lastday=mktime(0,0,0,3,0,2000); -echo strftime("Last day in Feb 2000 is: %d",$lastday); + +$lastday = mktime (0,0,0,3,0,2000); +echo strftime ("Last day in Feb 2000 is: %d", $lastday); -$lastday=mktime(0,0,0,4,-31,2000); -echo strftime("Last day in Feb 2000 is: %d",$lastday); +$lastday = mktime (0,0,0,4,-31,2000); +echo strftime ("Last day in Feb 2000 is: %d", $lastday); @@ -396,53 +570,152 @@ echo strftime("Last day in Feb 2000 is: %d",$lastday); Returns a string formatted according to the given format string using the given timestamp or the current - local time if no timestamp is given. Month and weekday names - and other language dependent strings respect the current locale - set with setlocale. - + local time if no timestamp is given. Month and weekday names and + other language dependent strings respect the current locale set + with setlocale. + - The following conversion specifiers are recognized in the format string: + The following conversion specifiers are recognized in the format + string: - %a - abbreviated weekday name according to the current locale - %A - full weekday name according to the current locale - %b - abbreviated month name according to the current locale - %B - full month name according to the current locale - %c - preferred date and time representation for the current locale - %d - day of the month as a decimal number (range 00 to 31) - %H - hour as a decimal number using a 24-hour clock (range 00 to 23) - %I - hour as a decimal number using a 12-hour clock (range 01 to 12) - %j - day of the year as a decimal number (range 001 to 366) - %m - month as a decimal number (range 1 to 12) - %M - minute as a decimal number - %p - either `am' or `pm' according to the given time value, or the corresponding strings for the current locale - %S - second as a decimal number - %U - week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week - %W - week number of the current year as a decimal number, starting with the first Monday as the first day of the first week - %w - day of the week as a decimal, Sunday being 0 - %x - preferred date representation for the current locale without the time - %X - preferred time representation for the current locale without the date - %y - year as a decimal number without a century (range 00 to 99) - %Y - year as a decimal number including the century - %Z - time zone or name or abbreviation - %% - a literal `%' character + + + %a - abbreviated weekday name according to the current locale + + + + + %A - full weekday name according to the current locale + + + + + %b - abbreviated month name according to the current locale + + + + + %B - full month name according to the current locale + + + + + %c - preferred date and time representation for the current + locale + + + + + %d - day of the month as a decimal number (range 00 to 31) + + + + + %H - hour as a decimal number using a 24-hour clock (range 00 + to 23) + + + + + %I - hour as a decimal number using a 12-hour clock (range 01 + to 12) + + + + + %j - day of the year as a decimal number (range 001 to 366) + + + + + %m - month as a decimal number (range 1 to 12) + + + + + %M - minute as a decimal number + + + + + %p - either `am' or `pm' according to the given time value, or + the corresponding strings for the current locale + + + + + %S - second as a decimal number + + + + + %U - week number of the current year as a decimal number, + starting with the first Sunday as the first day of the first + week + + + + + %W - week number of the current year as a decimal number, + starting with the first Monday as the first day of the first + week + + + + + %w - day of the week as a decimal, Sunday being 0 + + + + + %x - preferred date representation for the current locale + without the time + + + + + %X - preferred time representation for the current locale + without the date + + + + + %y - year as a decimal number without a century (range 00 to + 99) + + + + + %Y - year as a decimal number including the century + + + + + %Z - time zone or name or abbreviation + + + + + %% - a literal `%' character + + - - <function>strftime</function> example + <function>Strftime</function> example setlocale ("LC_TIME", "C"); -print(strftime("%A in Finnish is ")); +print (strftime ("%A in Finnish is ")); setlocale ("LC_TIME", "fi_FI"); -print(strftime("%A, in French ")); +print (strftime ("%A, in French ")); setlocale ("LC_TIME", "fr_CA"); -print(strftime("%A and in German ")); +print (strftime ("%A and in German ")); setlocale ("LC_TIME", "de_DE"); -print(strftime("%A.\n")); +print (strftime ("%A.\n")); This example works if you have the respective locales installed - in your system. - + in your system. + See also setlocale and mktime. @@ -453,7 +726,7 @@ print(strftime("%A.\n")); time - return current UNIX timestamp + Return current UNIX timestamp Description @@ -464,7 +737,8 @@ print(strftime("%A.\n")); Returns the current time measured in the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT). - + + See also date.