The file date_api.module is basically a big collection of date utility functions. You can scan through the file and it should be pretty obvious what they are and what they do.

Usage example for the api (Drupal 5, version 1)

The Date module was designed to be used as a date api, if desired. The date.inc api creates a date object that has both db and local values for a date and timezone info. That object is then passed to all other functions that need it.

Timezone handling options include using gmt, the site timezone, a date-specific timezone (selected when the date is edited), or no timezone handling. The last option will store and display dates exactly as entered, useful in situations where timezone conversions don't work accurately, or when they are just not desired.

• create a new date object:
  $date = date_make_date();
• set local value of 2006-05-04T10:24:00 US/Eastern
  date_set_date($date, '2006-05-04T10:24:00', 'US/Eastern', 'local', DATE_ISO);
• display the local value using the format string 'm/d/Y H:i'
  print date_show_date($date, 'm/d/Y H:i', 'local');
• display the db values of the date object:
  print date_show_value($date, 'db', DATE_UNIX); // the unix db value
  print date_show_value($date, 'db', DATE_ISO); // the iso db value
• display the date object and all its parts:
  print_r($date);

Use within a form

Including a date/time field within a form is easy:

/**
 * Your form builder.
 */
function my_module_form($form_values = NULL) {
  $form = array();

  // [...snip...] add many fields to your form

  // Creating the date/time element starts here
  include_once(drupal_get_path('module', 'date_api') .'/date.inc'); // Include the API.

  // Set some variables in an array. Look at the documentation at the top of 
  // the function date_select_input() in date.inc
  $params = array(
    'label' => 'My date and time field',
    'weight' => 2,
    'granularity' => array('M', 'D', 'Y', 'H', 'N'),
    // more params can be set according to documentation in date_select_input().
  );
  $form['date'] = date_select_input($params); // That's it!

  // [...snip...] more fields, including the 'submit' button.

  return $form;
}

Then process the data in the my_module_form_submit function as you would any other data.

Default Date Assignment Alternative

I have an array of the elements of a date. To make it the "default" date I use a bit of script like so:

<?php
include_once(drupal_get_path('module', 'date_api') .'/date.inc');
$widget_value = mktime(0, 0, 0, $date[1], $date[2], $date[0]);
$widget_value = date_unix2iso(date_gmadj_zone($widget_value));
$params = array(
  'value' => $widget_value,
);
$form['date'] = date_select_input($params);
?>

From-To Discussion
Like a "from - to" scenario, have a look at this support request.