Tcl Date/Time API Library Module

The Tcl date/time API library module has the file name datime.tcl. This module manipulates and converts dates and times.

Here is a list of procedures in this library module:

- datime_month_name_2_num
- datime_month_num_2_name
- get_ftime
- get_time
- datime_hour12_2_hour24
- datime_get_ampm
- run_year
- days_in_month
- isleap
- juldate
- datdif

# Module Dependencies

The following modules are required along with this module:

- parse.tcl

# Module Definition Files

This module requires the definition file:

- stdhead.tcl

# Module Procedures

## datime_month_name_2_num

    Declaration  : proc datime_month_name_2_num {mname}
    Parameters   :
          Name   : mname
          Type   : string
    Description  : month name

    Returns      : month number upon success, zero otherwise

This procedure will convert a month name to a month number. Only the first three characters of the month name are compared so you may use the long or short month names. January is considered month one.

## datime_month_num_2_name

    Declaration  : proc datime_month_num_2_name {mnum mname}
    Parameters   :
          Name   : mnum
          Type   : positive integer
          Range  : 1-12
    Description  : month number (jan=1)

          Name   : mname
          Type   : string
    Description  : output month name

    Returns      : 1 upon success, 0 otherwise

This procedure will translate a month number to the short month name and place the result into the output month name.

## get_ftime

    Declaration  : proc get_ftime {}

    Returns      : formatted date/time string

This procedure will format and return the current time string. Returned format is:

       yyyy/mm/dd hh:mm:ss

## get_time

    Declaration  : proc get_time {}

    Returns      : formatted date/time string

This procedure will format and place a date/time string into the returned date/time string. The format of the string will be a series of digits in the form:

       yyyymmddhhmmss

The string uses no delimiters and can therefore be considered fixed length.

## datime_hour12_2_hour24

    Declaration  : proc datime_hour12_2_hour24 {intime outime sep_flag}
    Parameters   :
          Name   : intime
          Type   : time string
    Description  : input time

          Name   : outime
          Type   : time string
    Description  : output time

          Name   : sep_flag
          Type   : boolean number(0-1)
    Description  : separator flag

    Returns      : 1 upon success, 0 otherwise

This procedure will convert a time string expressed in 12 hour format to a time string expressed in 24 format. The input time may be in any of the following formats:

- hh[:mm][:ss]p, hh[:mm][:ss] p, hh[:mm][:ss]pm, hh[:mm][:ss] pm
- hh[:mm][:ss]a, hh[:mm][:ss] a, hh[:mm][:ss]am, hh[:mm][:ss] am
- hh[:mm][:ss]m, hh[:mm][:ss] m, hh[:mm][:ss]n, hh[:mm][:ss] n

Where p and pm are the same, a and am are also the same. A trailing m indicates midnight and a trailing n indicates noon. When a trailing m or n is used, the time is assumed to be 12:00 regardless of any other hour/minute value. Spaces may or may not be present after the time and before the am or pm designator. The colon separator is required in the input time string. The separator flag is used to indicate whether the output time should have a colon separator. The minute and seconds fields are completely optional. The output time always contains two digits each for the hour, minute and optional seconds. The hour and minute are always present in the output time. Seconds are only present in the output time if present in the input time. Procedure returns the converted time loaded into the output time upon success.

## datime_get_ampm

    Declaration  : proc datime_get_ampm {wrd ap)
    Parameters   :
          Name   : wrd
          Type   : string
    Description  : time string

          Name   : ap
          Type   : string
    Description  : output designator

    Returns      : 1 upon success, 0 otherwise

This procedure will get the am, pm designator in the time string. If found, the designator will be removed from the time string and a single character will be loaded into the output designator. Acceptable designators in the time string are a, am, p, pm, n and m.

## run_year

    Declaration  : proc run_year {}

    Returns      : run year upon success, zero otherwise

This procedure will get the year of program run via the get_time procedure.

## days_in_month

    Declaration  : proc days_in_month {year month}
    Parameters   :
          Name   : year
          Type   : positive integer
    Description  : full year (with century)

          Name   : month
          Type   : positive integer
    Description  : month number (jan=1)

    Returns      : number of days in month upon success, zero otherwise

This procedure will determine the number of days in a month taking into account leap years.

## isleap

    Declaration  : proc isleap {year}
    Parameters   :
          Name   : year
          Type   : positive integer
    Description  : full year (with century)

    Returns      : 1 upon a leap year, 0 otherwise

This procedure will determine whether the full year is a leap year.

## juldate

    Declaration  : proc juldate {dte julout}
    Parameters   :
          Name   : dte
          Type   : integer
    Description  : input date (in the form yyyymmdd)

          Name   : julout
    Description  : output Julian number

    Returns      : 1 upon success, 0 otherwise

This procedure will convert the input date to a Julian value using DATIME_JUL_BASE (defined in this module) as the base year. Upon success the Julian number will be loaded into the output Julian number.

## datdif

    Declaration  : proc datdif {d1 d2 difout)
    Parameters   :
          Name   : d1
          Type   : integer
    Description  : input date 1 (in the form yyyymmdd)

          Name   : d2
          Type   : integer
    Description  : input date 2 (in the form yyyymmdd)

          Name   : difout
          Type   : integer
    Description  : output date difference

    Returns      : 1 upon success, 0 otherwise

This procedure will calculate the number of days difference between two dates. The input date 1 is assumed to be the later of the two dates. Upon success the number of days difference will be loaded into the output date difference.

Goto Top | Tcl Applications | Tcl Software Overview | Tcl Library Overview
| Future Lab Home | Contact Webmaster | Feedback

Copyright © 2005-2006 Future Lab, Last Updated Jul 01, 2006