Timespan Online Manual (HTML)

Usage: timespan [Input/Output Options] [Answer Options] [Operation]

Input/Output Options
Short form	Long form	Explanation
-H	--help	Show basic usage information and exit.
-v	--version	Show version information and exit.
-ee	--nous	Input of dates will be interpreted in non-US format; Output of dates will be in non-US format. This is equivalent to using both -ei and -eo together.
-ei	--nousin	Input of dates will be interpreted in non-US format.
-eo	--nousout	Output of dates will be in non-US format.
-l	--long	Output any dates in long format (using words for months instead of numbers--for example, January instead of 1).
-e	--extraline	Output a blank line at the end of each operation. This is particularly useful for "batch" operations using files, as it will separate each set of answers with blank lines.

Answer Options
-a	--all	Enables all Answer Options. This is equivalent to using "-t -d -h -m -s" in the command.
-t	--date	Give a date as one answer. This works only with the epoch and now Operations. This calculates the date based on relevant info given in the command.
-d	--days	Give a calculated number of days as an answer. This is the default answer, but will be overridden when ANY Answer Option is specified.
-h	--hours	Give a calculated number of hours as an answer.
-m	--minutes	Give a calculated number of minutes as an answer.
-s	--seconds	Give a calculated number of seconds as an answer.

Operations
Name	Usage	Explanation
epoch	epoch [+ number unit]	Arguments to "epoch" are optional, but if any are given, exactly three must be given. The + sign must be the first argument after epoch, because currently time can be added to the epoch but not subtracted from it, although this may be supported in the future. number and unit are explained below. When no arguments are supplied after "epoch", the epoch's date is displayed. The epoch is defined as January 1, 1970 (1 January 1970 for those preferring that form). Time may be added in the supported units.
now	now [{+\|-} number unit]	Arguments to "now" are optional, but if any are given, exactly three must be given. The + or - sign must be the first argument after "now", as timespan must know what you want to do. Time may be either subtracted from or added to "now&qout; in the supported units. number and unit are explained below. When no arguments are supplied after "now", the current date is displayed. All calculations using "now" are based on the epoch; therefore, subtracting a larger value than the amount of time "now" is after the epoch is not supported. For example, if "now" is 20000 days after the epoch, no value larger than 20000 days (or its equivalent in other units) may be subtracted.
between ... and	between date 1 and date 2	Caclulates time between date 1 and date 2. The "and" is required. The keywords "epoch" and "now" may be used to replace date 1 or date 2, however, the same keyword may not replace both dates. Date formats are explained below; each date is three arguments. Examples of each of the six possible combinations of dates and keywords to use "between" are included in the EXAMPLES section below.

EXAMPLES:

Here are some usage examples:

timespan -d now + 23 days
timespan --days now + 23 days
timespan -a now + 23 days
timespan --all now + 23 days
timespan -d -t -s now + 23 days
timespan --days --date --seconds now + 23 days
timespan -d epoch + 1200 days
timespan --days epoch + 1200 days
timespan -a epoch + 1200 days
timespan --all epoch + 1200 days
timespan -d -t -s epoch + 1200 days
timespan --days --date --seconds epoch + 1200 days
timespan -t -l epoch + 49710 days
timespan --date --long epoch + 49710 days
timespan -eo -t epoch + 49710 days
timespan --nousout --date epoch + 49710 days
timespan --days between January 20 2003 and November 1 2004
timespan -d between 1 20 2003 and 11 1 2004
timespan -ei -d between 20 1 2003 and 1 11 2004
timespan --all between now and January 30 2345
timespan --all between January 30 2345 and now
timespan --all between epoch and January 30 2345
timespan --all between January 30 2345 and epoch
timespan --all between epoch and now
timespan --all between now and epoch
timespan --nousin --days between 20 January 2003 and 1 November 2004
cat argslist.txt | xargs --replace=ARGS timespan --extraline --all ARGS >> outputlist.txt
(argslist.txt should contain each operation, such as "epoch + 500 days" on one line. You can also put more arguments on a line if you choose, so that each operation can have different output. -e or --extraline was meant for this so that the output file would have each operation's output separated.)

NOTES:

number, as shown in the Usage column of the table above, should be replaced with a positive whole number (positive integer).
unit, as shown in the Usage column of the table above, should be replaced with one of the following units of time (note that they are case-sensitive and must be entered in all lowercase--this will be corrected in a future release):
- days
- hours
- minutes
- seconds
When using multiple Answer Options, the output is always in the order listed below, skipping any Answer Options that are not specified. Remember that --all activates all the Answer Options supported for each operation.
- date
- days
- hours
- minutes
- seconds
Answers given in units of time smaller than one day are not intended to be 100% accurate. Timezones and Daylight Savings Time severely complicate the matter of accuracy in such cases, and have not been implemented (nor is there an intention to do so at any time during the course of the current maintainership). Use values reported for units of time smaller than one day as a "ballpark" figure, or estimate; do not assume that they are absolutely correct in all cases. This is described also in the BUGS section below.
date 1 and date 2 must each be replaced by a date. The format for dates specified on the command line in this manner is as follows:
- Dates must be entered as three space-delimited, unpunctuated arguments. For example, "1 23 1987" or "January 23 1987" are proper dates. When entered on the command line, however, dates must not contain quotation marks.
- Months may be specified with either their numeric values or their English names. If names are used, they are NOT case-sensitive.
- Month names may NOT contain punctuation. "Jan." would be an invalid way to specify a month.
- Although it is in some cases possible to include a trailing comma in a number, such as in the date "Jan 3, 2004", when specified on the command line, it is not recommended.
- Years MUST be specified as four-digit numbers. Instead of specifying simply 73 for the year, the specified number MUST be 1873, 1973, 2073, etc.
File I/O support has been removed from timespan because through creative use of cat, xargs, and pipes, special file formats that must be parsed within the code are an unnecessary annoyance to both the developers and the users. For Windows users, there are versions of the cat and xargs utilities available; some search effort will turn these up.

BUGS:

Daylight Savings Time is not taken into account. Therefore, hour counts may be high by 1, minute counts by 60, and second counts by 3600. The maintainer has no intention of fixing this bug himself, because it is timezone specific--not all timezones use Daylight Savings Time. 100% precision with units of time smaller than one day have never been the goal of the project.

To submit bug reports, visit the SourceForge.net project page and click the Bugs link near the top center of the page.

Patches are always welcome, even for bugs the maintainer has no intention of fixing. Patches will be reviewed and accepted or denied. Please use the SourceForge Patches tracker to submit patches, as it provides a method of tracking the history of submitted patches.