Date/Time Processing

Jason Diamond

$Id: date-time.html,v 1.10 2004/10/10 06:18:57 balls Exp $


Introduction

This module provides templates for formatting and parsing date/time strings.

See http://www.tondering.dk/claus/calendar.html for more information on calendars and the calculations this library performs.

Table of Contents

dt:format-date-time - Returns a string with a formatted date/time.
dt:calculate-day-of-the-week - Calculates the day of the week.
dt:calculate-last-day-of-month - Calculates the number of days for a specified month.
dt:get-day-of-the-week-name - Gets the day of the week's full name.
dt:get-day-of-the-week-abbreviation - Gets the day of the week's abbreviation.
dt:get-month-name - Gets the month's full name.
dt:get-month-abbreviation - Gets the month's abbreviation.
dt:calculate-julian-day - Calculates the Julian Day for a specified date.
dt:format-julian-day - Returns a string with a formatted date for a specified Julian Day.
dt:calculate-week-number - Calculates the week number for a specified date.
dt:get-month-number - Take a month by name and return a number which can be used as input to the templates.
dt:get-xsd-datetime-year - Return year component of XSD DateTime value.
dt:get-xsd-datetime-month - Return month component of XSD DateTime value.
dt:get-xsd-datetime-day - Return day component of XSD DateTime value.
dt:get-xsd-datetime-hour - Return hour component of XSD DateTime value.
dt:get-xsd-datetime-minute - Return minute component of XSD DateTime value.
dt:get-xsd-datetime-second - Return second component of XSD DateTime value.
dt:get-xsd-datetime-timezone - Return timezone component of XSD DateTime value.

Name

dt:format-date-time — Returns a string with a formatted date/time.

Synopsis

<xsl:template name="dt:format-date-time"><xsl:param name="xsd-date-time"/><xsl:param name="year"/><xsl:param name="month"/><xsl:param name="day"/><xsl:param name="hour"/><xsl:param name="minute"/><xsl:param name="second"/><xsl:param name="time-zone"/><xsl:param name="format" select="'%Y-%m-%dT%H:%M:%S%z'"/>  ...</xsl:template>

The formatted date/time is determined by the format parameter. The default format is %Y-%m-%dT%H:%M:%S%z, the W3C format.

Parameters
xsd-date-time

The date-time value in XML Schemas (WXS) format.

If this value is specified, it takes priority over other parameters.

year

Year

month

Month (1 - 12; January = 1)

day

Day of month (1 - 31)

hour

Hours since midnight (0 - 23)

minute

Minutes after hour (0 - 59)

second

Seconds after minute (0 - 59)

time-zone

Time zone string (e.g., 'Z' or '-08:00')

format

The format specification.

%a

Abbreviated weekday name

%A

Full weekday name

%b

Abbreviated month name

%B

Full month name

%c

Date and time representation appropriate for locale

%d

Day of month as decimal number (01 - 31)

%e

Day of month as decimal number (1 - 31)

%H

Hour in 24-hour format (00 - 23)

%I

Hour in 12-hour format (01 - 12)

%i

Hour in 12-hour format (1 - 12)

%j

Day of year as decimal number (001 - 366)

%m

Month as decimal number (01 - 12)

%n

Month as decimal number (1 - 12)

%M

Minute as decimal number (00 - 59)

%P

Current locale's A.M./P.M. indicator for 12-hour clock, uppercase

%Q

Current locale's A.M./P.M. indicator for 12-hour clock, uppercase with periods

%p

Current locale's A.M./P.M. indicator for 12-hour clock, lowercase

%q

Current locale's A.M./P.M. indicator for 12-hour clock, lowercase with periods

%S

Second as decimal number (00 - 59)

%U

Week of year as decimal number, with Sunday as first day of week (00 - 53)

%w

Weekday as decimal number (0 - 6; Sunday is 0)

%W

Week of year as decimal number, with Monday as first day of week (00 - 53)

%x

Date representation for current locale

%X

Time representation for current locale

%y

Year without century, as decimal number (00 - 99)

%Y

Year with century, as decimal number

%z

Time-zone name or abbreviation; no characters if time zone is unknown

%%

Percent sign

Returns

Returns a formatted date/time string.



Name

dt:calculate-day-of-the-week — Calculates the day of the week.

Synopsis

<xsl:template name="dt:calculate-day-of-the-week"><xsl:param name="year"/><xsl:param name="month"/><xsl:param name="day"/>  ...</xsl:template>

Given any Gregorian date, this calculates the day of the week.

Parameters
year

Year

month

Month (1 - 12; January = 1)

day

Day of month (1 - 31)

Returns

Returns the day of the week (0 - 6; Sunday = 0).



Name

dt:calculate-last-day-of-month — Calculates the number of days for a specified month.

Synopsis

<xsl:template name="dt:calculate-last-day-of-month"><xsl:param name="year"/><xsl:param name="month"/>  ...</xsl:template>

Given any Gregorian month, this calculates the last day of the month.

Parameters
year

Year

month

Month (1 - 12; January = 1)

Returns

Returns the number of days in given month as a decimal number.



Name

dt:get-day-of-the-week-name — Gets the day of the week's full name.

Synopsis

<xsl:template name="dt:get-day-of-the-week-name"><xsl:param name="day-of-the-week"/>  ...</xsl:template>

Converts a numeric day of the week value into a string representing the day's full name.

Parameters
day-of-the-week

Day of the week (0 - 6; Sunday = 0)

Returns

Returns a string.



Name

dt:get-day-of-the-week-abbreviation — Gets the day of the week's abbreviation.

Synopsis

<xsl:template name="dt:get-day-of-the-week-abbreviation"><xsl:param name="day-of-the-week"/>  ...</xsl:template>

Converts a numeric day of the week value into a string representing the day's abbreviation.

Parameters
day-of-the-week

Day of the week (0 - 6; Sunday = 0)

Returns

Returns a string.



Name

dt:get-month-name — Gets the month's full name.

Synopsis

<xsl:template name="dt:get-month-name"><xsl:param name="month"/>  ...</xsl:template>

Converts a numeric month value into a string representing the month's full name.

Parameters
month

Month (1 - 12; Januaray = 1)

Returns

Returns a string.



Name

dt:get-month-abbreviation — Gets the month's abbreviation.

Synopsis

<xsl:template name="dt:get-month-abbreviation"><xsl:param name="month"/>  ...</xsl:template>

Converts a numeric month value into a string representing the month's abbreviation.

Parameters
month

Month (1 - 12; Januaray = 1)

Returns

Returns a string.



Name

dt:calculate-julian-day — Calculates the Julian Day for a specified date.

Synopsis

<xsl:template name="dt:calculate-julian-day"><xsl:param name="year"/><xsl:param name="month"/><xsl:param name="day"/>  ...</xsl:template>

Given any Gregorian date, this calculates the Julian Day.

Parameters
year

Year

month

Month (1 - 12; January = 1)

day

Day of month (1 - 31)

Returns

Returns the Julian Day as a decimal number.



Name

dt:format-julian-day — Returns a string with a formatted date for a specified Julian Day.

Synopsis

<xsl:template name="dt:format-julian-day"><xsl:param name="julian-day"/><xsl:param name="format" select="'%Y-%m-%d'"/>  ...</xsl:template>

Given any Julian Day, this returns a string according to the format specification.

Parameters
julian-day

A Julian Day

format

The format specification. See dt:format-date-time for more details.

Returns

A string.



Name

dt:calculate-week-number — Calculates the week number for a specified date.

Synopsis

<xsl:template name="dt:calculate-week-number"><xsl:param name="year"/><xsl:param name="month"/><xsl:param name="day"/>  ...</xsl:template>

Assumes Monday is the first day of the week.

Parameters
year

Year

month

Month (1 - 12; January = 1)

day

Day of month (1 - 31)

Returns

Returns the week number as a decimal number.



Name

dt:get-month-number — Take a month by name and return a number which can be used as input to the templates.

Synopsis

<xsl:template name="dt:get-month-number"><xsl:param name="month"/>  ...</xsl:template>

Input

Parameters
month

Month as described either by full name or abbreviation.

Returns

Return a month as a decimal number. (Jan = 1)



Name

dt:get-xsd-datetime-year — Return year component of XSD DateTime value.

Synopsis

<xsl:template name="dt:get-xsd-datetime-year"><xsl:param name="xsd-date-time"/>  ...</xsl:template>

Extract component of XML Schemas DateTime value.

Parameters
xsd-date-time

A value in XSD DateTime format.

Returns

Returns year component.



Name

dt:get-xsd-datetime-month — Return month component of XSD DateTime value.

Synopsis

<xsl:template name="dt:get-xsd-datetime-month"><xsl:param name="xsd-date-time"/>  ...</xsl:template>

Extract component of XML Schemas DateTime value.

Parameters
xsd-date-time

A value in XSD DateTime format.

Returns

Returns month component.



Name

dt:get-xsd-datetime-day — Return day component of XSD DateTime value.

Synopsis

<xsl:template name="dt:get-xsd-datetime-day"><xsl:param name="xsd-date-time"/>  ...</xsl:template>

Extract component of XML Schemas DateTime value.

Parameters
xsd-date-time

A value in XSD DateTime format.

Returns

Returns day component.



Name

dt:get-xsd-datetime-hour — Return hour component of XSD DateTime value.

Synopsis

<xsl:template name="dt:get-xsd-datetime-hour"><xsl:param name="xsd-date-time"/>  ...</xsl:template>

Extract component of XML Schemas DateTime value.

Parameters
xsd-date-time

A value in XSD DateTime format.

Returns

Returns hour component.



Name

dt:get-xsd-datetime-minute — Return minute component of XSD DateTime value.

Synopsis

<xsl:template name="dt:get-xsd-datetime-minute"><xsl:param name="xsd-date-time"/>  ...</xsl:template>

Extract component of XML Schemas DateTime value.

Parameters
xsd-date-time

A value in XSD DateTime format.

Returns

Returns minute component.



Name

dt:get-xsd-datetime-second — Return second component of XSD DateTime value.

Synopsis

<xsl:template name="dt:get-xsd-datetime-second"><xsl:param name="xsd-date-time"/>  ...</xsl:template>

Extract component of XML Schemas DateTime value.

Parameters
xsd-date-time

A value in XSD DateTime format.

Returns

Returns second component.



Name

dt:get-xsd-datetime-timezone — Return timezone component of XSD DateTime value.

Synopsis

<xsl:template name="dt:get-xsd-datetime-timezone"><xsl:param name="xsd-date-time"/>  ...</xsl:template>

Extract component of XML Schemas DateTime value.

Parameters
xsd-date-time

A value in XSD DateTime format.

Returns

Returns timezone component.