Script Library: 1247 scripts

Documentation for: form-date.r

Usage document for %form-date.r

1. Introduction to %form-date.r

2. form-date At a Glance

3. Using %form-date.r

4. The format string

5. What you can learn

6. What you can break

7. What's new

7.1. Precision versus Accuracy

8. Credits

1. Introduction to %form-date.r

This library script is for inclusion in other programs and allows sophisticated date formatting, ala strftime, but not exactly

2. form-date At a Glance

 >> form-date now "%A %e%i %B, %Y at %T"
 == "Thursday 26th April, 2007 at 00:44:12"

 >> form-date now "%d-%b-%Y/%H:%M:%S%Z"
 == "26-Apr-2007/00:49:39-04:00"

 >> now
 == 26-Apr-2007/0:52:13-4:00

 >> form-date now/precise "%c"
 == "19-Jul-2007/00:01:45.108242-04:00"

3. Using %form-date.r

Including this function is simple. Just DO it.

 >> do %form-date.r

or to execute this right out of the rebol.org library

 >> do http://www.rebol.org/download-a-script.r?script-name=form-date.r

You now have the form-date function

 >> help form-date
 USAGE:
     FORM-DATE date format /gmt

 DESCRIPTION:
      Renders a date to a given format (largely compatible with strftime)
      FORM-DATE is a function value.

 ARGUMENTS:
      date -- (Type: date)
      format -- (Type: any-string)

 REFINEMENTS:
      /gmt -- Align time with GMT

4. The format string

Ordinary characters placed in the format string are inserted into return value without conversion. Conversion specifications are introduced by a % character, and terminated by a conversion specifier character, and are replaced and inserted into return value as follows:

%a	The abbreviated weekday name according to the current locale.
%A	The full weekday name according to the current locale.
%b	The abbreviated month name according to the current locale.
%B	The full month name according to the current locale.
%c	The preferred date and time representation for the current locale. In this case the locale is REBOLand, with a little %b mixed in.
%C	The century number (year/100) as a 2-digit integer.
%d	The day of the month as a decimal number (range 01 to 31).
%D	Equivalent to %Y/%m/%d.
%e	Like %d, the day of the month as a decimal number, without a leading zero.
%G	The ISO 8601 year with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %y, except that if the ISO week number belongs to the previous or next year, that year is used instead.
%g	Like %G, but without century, i.e., with a 2-digit year (00-99).
%H	The hour as a decimal number using a 24-hour clock (range 00 to 23).
%i	The english suffix for numeric value, st for 01, th for 04.
%I	The hour as a decimal number using a 12-hour clock (range 01 to 12).
%j	The day of the year as a decimal number (range 001 to 366).
%J	Like %j, but without leading zeroes.
%m	The month as a decimal number (range 01 to 12).
%M	The minute as a decimal number (range 00 to 59).
%p	Either "AM" or "PM" according to the given time value. Noon is treated as "PM" and midnight as "AM".
%s	The second as a decimal number 00-60 with REBOL nanosecond precision, a period followed by 6 digits.
%S	The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for occasional leap seconds.)
%t	A tab character.
%T	The time in 24-hour notation (%H:%M:%S).
%u	The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w.
%U	The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W.
%V	The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. See also %U and %W.
%w	The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
%W	The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01.
%y	The year as a decimal number without a century (range 00 to 99).
%Y	The year as a decimal number including the century.
%Z	The time-zone as hour offset from GMT.
%%	A literal "%" character.

5. What you can learn

The interpolate function, along with date-codes is an excellent example of parse. The dialect created is the two character format specifiers that produce the date and time pieces. A strftime dialect.

REBOL can emulate the functionality of other systems, while still remaining REBOL.

REBOL code can look world-class elegant when properly formatted and factored.

6. What you can break

The date! parameter has to be a date!. If you use any time related format specifiers, it has to be a date! that includes time information or returned fields may be incorrect.

 >> form-date now/date "%T"
 == "00:00:00"

 >> form-date now/time "%T"
  Script Error: form-date expected date argument of type: date
  Near: form-date now/time "%T"

 >> form-date now "%T"
 == "02:29:39"

7. What's new

With the addition of %c, you have clean, always the same length REBOL time-stamps.

 >> 01-Jan-0001/00:00:00.000000-00:00
 == 1-Jan-0001/0:00
 >> form-date 01-Jan-0001/00:00:00.000000-00:00 "%c"
 == "01-Jan-0001/00:00:00.000000+00:00"

 >> form-date now/precise "%c"
 == "19-Jul-2007/00:42:53.586560-04:00"

 >> form-date now "%c"
 == "19-Jul-2007/00:43:19.000000-04:00"

7.1. Precision versus Accuracy

Please note that now/precise while reporting 6 digit precision for the sub-seconds, is only as accurate as your computer clock will allow.

8. Credits

%form-date.r original author: Christopher Ross-Gill
Part of QuarterMaster, %qm.r by Christopher Ross-Gill http://www.ross-gill.com/
Usage document by Brian Tiffin, Library Team Apprentice, Last updated: 19-Feb-2009