Function
	addtime

Purpose
	Adds (or subtracts) a time difference to (from) a time.

Return Type
	str

Syntax
	addtime( time ( <time> )   diff ( <diff> ) )

Arguments
	<time>	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.

	<diff>	Time difference string 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

		When a plus (+) sign is present, or no sign is present, the time difference is added
		to the time. When a minus (-) sign is present, the time difference is subtracted
		from the time.

		Leading characters may be dropped. Following examples illustrate.

		"2"	2 seconds. (Please note that "2" is treated as 2 seconds, and NOT as 20 seconds.)
		"321"	3 minutes, 21 seconds
		"3000"	30 minutes
		"30000000"	30 days
		"0030000000"	30 days
		"365000000"	365 days

		If this argument is not specified, 0 seconds will be used.


Return Value
	A str value representing the resulting time. This string is in the same 14 character
	format as the format used for <time> argument, described above. Ending characters are
	NOT dropped in the return value.

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 adds or subtracts a time difference from a time.

	When a plus (+) sign is present, or no sign is present,  at the beginning of
	the <diff> value, the time difference is added to the time.

	When a minus (-) sign is present at the beginning of
	the <diff> value, the time difference is subtracted from the time.

	The returned str has 14 characters in the same format as the <time> argument.

	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.

	Time differences of more than 365 days (this limit is processor-dependent) are not supported.
	An appropriate error will be produced.

	Most 32-bit systems will not be able to hold the entire 14-digit time value
	described above, in an int variable. So to convert the return value from
	this function into a numeric value, always use real.

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

Valid Examples
	echo addtime(time("20100601170000") diff("365000000"))

	Will add 365 days to June 1, 2010, 5:00:00 PM and print the resulting time.


	echo addtime(time("20100601170000") diff("-365000000"))

	Will subtract 365 days from June 1, 2010, 5:00:00 PM and print the resulting time.


	echo addtime(time(gettime()) diff("-3000"))

	Will subtract 30 minutes from the current time and print the resulting time. This can
	often be used in conjunction with the lf command as shown below.


	lf -n "*" "." ( $fmtime >= addtime(time(gettime()) diff("-3000")) )


	The following will be more efficient.

	var str targettime
	set $targettime = addtime(time(gettime()) diff("-3000"))
	lf -n "*" "." ( $fmtime >= $targettime )


Invalid Examples
	var bool btime
	set $btime = addtime(time("20100601170000") diff("365000000"))

	Will produce an error. The addtime 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 stime
	set $stime = addtime(time("20100601170000") diff("365000000"))


See Also
gettime
difftime
getdow
var
conversion
chex