Time Calculations with AddUp 2

Times can be manipulated in many ways once we have a proper notation format to represent them. AddUp uses a "timestamp" notation: a timestamp is written using an hour value, a minute value and a second value separated from each other by colons and placed inside square brackets. For example: [10:30:59] is a timestamp that represents 59 seconds past 10:30 in the morning. The default notation uses a 24-hour clock. A 12-hour clock is used instead by using either 'A' or 'P' before the time to indicate AM or PM, so [A 10:30:59] is the same time in the morning as on the 24-hour clock but [P 10:30:59] is twelve hours later or [22:30:59] on the 24-hour clock.

What exactly is a "timestamp"? It is an expression that AddUp translates into a number of seconds elapsed since the start of the day. (Technically it is the time of day on January 1st of year 0.) The square brackets indicate that the content is not a calculation but that it represents a time and/or a date. The value of this timestamp expression is just a plain number, a number of seconds in this case. For example, the above timestamp has this value:

[10:30:59] = 37,859

Since timestamps represent a number of seconds and since a second is the standard unit of time, we can use timestamps in all calculations where a unit of time is suitable. For example, we can do a time difference calculation by subtracting two timestamps to see how much time has passed between them.

[13:00:00] - [10:30:59] = 8,941

Of course the number of seconds may not be what we want to know, so we convert this value into minutes or hours (or any other time unit we need). Apply the "->" conversion operator to the result of the subtraction and select the desired time unit. Be sure to use parentheses around the subtraction so that the conversion applies to all of it and not just to the last time value.

Difference between two times in hours.

([13:00:00] - [10:30:59]) -> hours = 2.484

Difference between two times in minutes.

([13:00:00] - [10:30:59]) -> minutes = 149.017

Normally, the later time is subtracted from the earlier time to get a positive value. If the reverse is done instead then the value will be negative but the amount of time is still correct in absolute terms.

Another kind of time calculation is to add or subtract some duration from a known time in order to obtain a different time. This is also easily done with an expression such as this:

[10:30:59] + 5 hours = 55,859

Here again, the number of seconds obtained from this operation is not very informative, it is just the original timestamp's value (in seconds) plus the number of seconds in 5 hours. We want to see an actual time instead. To get the result in timestamp format, start the operation with a '] prefix. The single quote indicates that what follows is an output format specification. The right square bracket says that this format should be a time. A formatting prefix must not contain any space because it ends at the first space character found before the expression itself, but separate the prefix and the expression itself with at least one space.

Show a timestamp for 5 hours later than [10:30:59].

'] [10:30:59] + 5 hours = [15:30:59]

Timestamps always represent both a date and a time. When only the time is given, the base date is assumed to be January 1st of year zero. This means that timestamp [10:30:59] gives the same value as timestamp [0000-01-01 10:30:59] where the base date is also given. The date portion of a timestamp can be seen when the '[] output prefix is used instead of just ']:

Show a timestamp for 5 hours later than [10:30:59], including the date.

'[] [10:30:59] + 5 hours = [0000-01-01 15:30:59]

The current date can be added to a timestamp by using only the punctuation normally present in a date: two dash characters before the date portion. For example [-- 10:30:59] represents 10:30:59 on today's date. You must separate the "--" date indicator from the time with either 'A' or 'P' if you use a 12-hour clock, or with either 'T' or a space if you use a 24-hour clock.

Assuming that today's date is 2000-12-31...

'[] [-- 10:30:59] = [2000-12-31 10:30:59]

You can see the help file for details regarding the date format. Date and time calculations work the same way.

Returning to time operations, let's see what happens if we try to subtract an excessive duration from a time of day timestamp:

Show a timestamp for 20 hours earlier than [10:30:59].

'[ [10:30:59] - 20 hours = Error (negative value not allowed)

The "negative value" situation results from trying to display a negative number as a timestamp: 20 hours is greater than 10:30:59 hours so the subtraction gives a negative value that cannot be shown as a timestamp. An easy solution exists: add two dash characters to the time in order to assume today's date instead of 0000-01-01. The time of day will roll-over to yesterday and the clock time will be shown correctly:

Show a timestamp 20 hours before [10:30:59] today.

'] [-- 10:30:59] - 20 hours = [14:30:59]

A few useful time functions include:

getHr (getHour)
returns the hour value of a timestamp
getMn (getMinute)
returns the minute value of a timestamp
getSc (getSecond)
returns the second value of a timestamp
returns a timestamp for the current date and time
returns a timestamp for the current time alone

More formatting alternatives exist for timestamp values. Punctuation can be omitted or used to specify default values. Coordinated universal time can be used and reported. Daylight saving time can be specified. These alternative formats and other details are described in the help file that is created by AddUp's installation program.