Timezone Converter
==================

Display time converted from one timezone to another timezone, with daylight saving handled automatically.
The input time can default to local time, or can be entered in either of two formats.  The format of 
the output time can be specified using the -f option, or default to a full featured string.

Timezones are checked against an internal list.  A (extended) regex can be used to search for a timezone.
If a timezone is not a perfect match against the internal list, but is so close that there is only one
possible valid candidate (e.g. paris = Europe/Paris), that candidate is automatically substituted.  A warning
message is displayed.  If there are multiple possible candidates, they are listed and the program exits.

The time to be converted can be entered in two possible formats (which can be changed in the source code--
see the #defines near the top): "YYYY-MM-DD HH:MM" or YYYYMMDDHHMM.

All warning and error messages can be suppressed with the -s command line option.

The output time format defaults to "%a, %d %b %Y %H:%M:%S %z (%Z)", or can be specified on the command line
with the -f option.

Command line options:

    -s		Suppress all messages except for the datetime.  Possible use is for scripts that don't 
		care about warnings or errors.
		This flag means that an invalid timezone or regex will result in no output.  
		The return value can be tested to detect this.

    -f	"xxxx"	Format customised output using strftime formatting.  See man 3 strftime.

Input:

    timezone			the local machine's localtime is converted to that timezone; or

    timezone time timezone	the time in the first timezone is converted to the second timezone; or

    regex			the internal list of timezones is searched using the regex
				(which can be a simple string).	

Input Formats:
    timezone	in the format of the /usr/share/zoneinfo directory structure
		(e.g.  Australia/Sydney, Europe/Rome, Zulu, Israel), or an extended regex.  If
		the regex matches only one timezone from the internal list, that timezone is
		susbstituted automatically on the basis that the user should not have to retype
		it again.  The return value can be used to detect if this substitution has
		occurred.  The timezone is case-sensitive, but the regex search is
		case-insensitive.  This lets you do quick data entry of "paris" since the regex
		search will substitute the correct value of Europe/Paris.  The regex does
		partial matches automatically.  You don't need to specify ".*foo.*", foo
		will work fine.

    time	in either of two strftime formats (which can be changed in #define in the 
		source code): "%Y-%m-%d %H:%M" or %Y%m%d%H%M (the second for quick and dirty
		typing, sacrificing legibility).

Output:
    formatted string of the time; or
    list of possible candidate timezones.

Return value:
    0	timezone(s) match exactly (perfect match) with the internal list; no errors
    1	at least one of the timezones was substituted because there was only one 
	match in the internal list (i.e. imperfect match); no errors
    2	an error occurred: too many timezone candidates to automatically choose one, time format wrong, regex invalid.

Usage:
    tzconvert paris
    tzconvert "s(aint)?_"
    tzconvert Europe/Rome
    tzconvert "Europe/Paris" "2004-10-30 06:30" "America/New_York"
    tzconvert Australia/Sydney 201105061928 America/New_York
    tzconvert -f "%H:%M" Europe/Paris
    tzconvert -s -f %H%M paris 201105150130 sydney

Examples:
    Normal:
	$ tzconvert Europe/Rome
	    Thu, 12 May 2011 06:57:09 +0200 (CEST)
	$ tzconvert "Europe/Paris" "2004-10-30 06:30" "America/New_York"
	    Sat, 30 Oct 2004 00:30:00 -0400 (EDT)
	$ tzconvert Australia/Sydney 201105061928 America/New_York
	    Fri, 06 May 2011 05:28:00 -0400 (EDT)
	$ tzconvert -f "%H:%M" Europe/Paris
	    05:51

    Substitution:
	$ tzconvert paris
	    "paris" timezone not found.  Possible candidates:
	    Europe/Paris
	    Fri, 13 May 2011 05:46:01 +0200 (CEST)
	$ echo $?
	  1
	$ tzconvert paris "2011-05-13 9:30" rome
	    "rome" timezone not found.  Possible candidates:
	    Europe/Rome
	    "paris" timezone not found.  Possible candidates:
	    Europe/Paris
	    Fri, 13 May 2011 09:30:00 +0200 (CEST)
	$ echo $?
	  1
	(Below is the same example with messages suppressed and with custom output time format)
	$ tzconvert -s -f %H:%M paris "2011-05-13 9:30" rome
	    09:30

    Not found:
	$ tzconvert par
	    "par" timezone not found.  Possible candidates:
	    America/Paramaribo
	    Europe/Paris
	$ echo $?
	  2

    Using a regex:
	$ tzconvert "s(ain)?t_"
	    "s(ain)?t_" timezone not found.  Possible candidates:
	    America/St_Barthelemy
	    America/St_Johns
	    America/St_Kitts
	    America/St_Lucia
	    America/St_Thomas
	    America/St_Vincent
	    Atlantic/St_Helena

Compilation:
    make
    or, to compile manually:
    cc tz.c timezones.c -O2 -o tzconvert

    The timezones.c file is almost certainly correct for a unix-like
    system, including Linux.  If you have to generate the entries in
    timzones.c for your machine, run `find /usr/share/zoneinfo -type f -ls
    | cut -d '/'  -f 5-9` and edit the output or use sed to add leading "
    char and trailing ", chars.   The posix and right directory entries
    can be deleted, along with zone.tab.  You will need to regenerate (or
    manually add) the entries if a new timezone is created in the world
    and your /usr/share/timezone entries change.  I imagine this would be
    a very rare event.

Remarks:
    Bang off an email to me, I'd like to hear from you.   [email protected]

    Timezone conversion concept based on http://stackoverflow.com/questions/2413418/how-to-programatically-convert-a-time-from-one-timezone-to-another-in-c

Licence:
	MIT-style licence (see source file for particulars).  Copyright 2011 Nick Coleman