Function
	difftime

Purpose
	Subtracts one time from another time.

Return Type
	str

Syntax
	difftime( time1 ( <time1> )   time2 ( <time2> ) )

Arguments
	<time1>	Time string of up to 14 characters in the following format.

		yyyymmddHHMMss

		yyyy	4 digit year
		mm	2 digit month, 01 thru 12
		dd	2 digit day, 01 thru 31
		HH	2 digit hour on 24-hour basis, 00 thru 23
		MM	2 digit minute, 00 thru 59
		ss	2 digit second, 00 thru 59

		Ending characters may be dropped. Following examples illustrate.

		"2010072312"	July 23, 2010, 12:00:00 noon
		"201007231210"	July 23, 2010, 12:10:00 PM
		"201007231310"	July 23, 2010, 01:10:00 PM
		"2010072313105"	July 23, 2010, 01:10:05 PM
			(Please note that "2010072313105" is interpreted as July 23, 2010, 01:10:05 PM,
			and NOT as July 23, 2010, 01:10:50 PM.)

		If this argument is not specified, the current time will be used.

	<time2>	Time string in the same format as <time1>.

		If this argument is not specified, the current time will be used.

	
Return Value
	A str value representing the time difference between <time1> and <time2>.

	If <time1> is later than <time2>, a positive value is returned.
	If <time1> is earlier than <time2>, a negative value is returned.
	If <time1> is same as <time2>, zero value is returned.

Stream Input	
	Streams apply to commands and not to functions.

Stream Output
	Streams apply to commands and not to functions.

Stream Error
	Streams apply to commands and not to functions, although any errors
	will be written here.

Description
	This function subtracts <time2> from <time1> and returns a string representing
	the time difference in the following format.

	[-]dddHHMMss

	ddd	complete days, with any number of digits
	HH	2 digit complete hours, 00 thru 23
	MM	2 digit complete minutes, 00 thru 59
	ss	2 digit seconds, 00 thru 59

	If <time1> is later than or equal to <time2>, the return value has no sign in front of it.
	If <time1> is earlier than <time2>, the return value has a minus (-) sign in front of it.

	chex command can be used to further extract individual components
	of the returned time.
		
Restrictions
	Times before year 1977, or after year 2036 (these limits are processor-dependent), are not supported.
	An appropriate error will be produced.

	All system functions are declared as global, and can not be redeclared (overloaded).

Valid Examples
	echo difftime(time1("20100601170000") time2("20090601170000"))

	Will subtract time2 (June 1, 2009, 5:00:00 PM) from time1 (June 1, 2010, 5:00:00 PM)
	and return the time difference. Since time1 is later than time2, the return value
	will be positive. The return string will be "365000000", or, 365 days.


	echo difftime(time1("20090601170000") time2("20100601170000"))

	Will subtract time2 (June 1, 2010, 5:00:00 PM) from time1 (June 1, 2009, 5:00:00 PM)
	and return the time difference. Since time1 is earlier than time2, the return value
	will be negative. The return string will be "-365000000", or, 365 days.


	echo difftime(time2("20100101000000"))

	Will subtract January 1, 2010, 12:00:00 midnight, from the current time. Since time1
	is not specified, the current time will be used for that argument.


	The following commands will show how long ago each file in directory "/temp" was
	created.

	var str list, file
	lf -n "*" "/temp" ($ftype=="f") > $list
	while ($list <> "")
	do
	    lex "1" $list > $file ; af $file > null
	    echo $file "\t" difftime(time2($fctime))
	done


Invalid Examples
	echo difftime(time2(20100101000000))

	Will produce an error. The argument time2 needs a string value. The value supplied
	(20100101000000) is integer. An integer value can not be automatically converted to
	a string value.

	var bool bdiff
	set $bdiff = difftime(time1("20090601170000") time2("20100601170000"))

	Will produce an error. The difftime function returns a value of type str. It can not
	be automatically converted to bool. (See help page for conversion.)


	The following will, however, work.
	
	var str sdiff
	set $sdiff = difftime(time1("20090601170000") time2("20100601170000"))


See Also
gettime
addtime
getdow
var
conversion
chex