Time Stamper

This struct basically makes timing things much easier by packaging a few useful methods together.

Now, instead of writing and retrieving timestamp variables, and formatting strings to the listener, you simply call struct methods such as start(), end(), and print(), or see a report of the process with getReport().

Example Code

Create a new Time Stamper, assigning a task name:

ts = timeStamper "Testing"

Time something, and alert the results in a messagebox:

ts.start()
-- your code here
ts.alert()

Benchmark a series of tests, and print the results to the listener when completed:

for i = 1 to 10 do (
	ts.start()
	-- your code here
	ts.end()
)
ts.print average:true

-- Average processing time for 'Testing' was 24.6162 seconds, based on 10 timed sessions.

Methods

Starting and stopping

• <number> start() – start timing. Returns start time
• <number> end() – end timing. Returns last timing duration
• <void> reset() – reset all timing data

Getting results in English

• <void> print average: <boolean> difference: <TimeStamper> – end timing and print results to listener
• <void> prompt average: <boolean> difference: <TimeStamper> – end timing and prompt results to notification area
• <void> alert average: <boolean> difference: <TimeStamper> – end timing and alert the results in a messagebox

For the above methods, the following keyword arguments can be supplied:

• average <boolean> – returns the average result of all the timed tests since the TimeStamper was instantiated or last reset
• difference <TimeStamper> – returns the comparative difference between another TimeStamper, in English, e.g."Test 1' was 2.58 times quicker than 'Test 2'"

Getting results as numbers

• <number> getLast() – gets the last single timed session (alias for duration property)
• <number> getTotal() – gets the total of all timed sessions
• <number> getAverage() – gets the average of all timed sessions
• <array> getDifference difference: <TimeStamper> average: <boolean> – Returns a 3-element array representing how much quicker one time stamper is than another.

The array's elements are ordered like so:

1. <number> – how many times quicker the quickest Time Stamper was
2. <string> – the task name of the quicker time stamper
3. <string> – the task name of the slower time stamper

Getting results as an Excel-compatible report

• <string> getReport columns:<array> step:<number> output:<string/name/windowstream/filestream> – gets all timed sessions as a customizable report

The step property defines how many iterations to average/total values for, and defaults to 10.

The columns property can take any of the following name values:

• #index – the numeric index of the row, e.g. 1, 2, 3
• #step – the current step, e.g. 1, 11, 21
• #stepaverage – the average of all measurements from the current step
• #steptotal – the total of all the measurements from the current step
• #slower – how much slower the current step was than the fastest step
• #quicker – how much quicker the current step was than the slowest step
• #total – the cumulative total from all measurements so far

The output property defines where the generate report will be output to. Values can be:

• No value – the report will be returned as a string
• "path/to/file.txt" – a file path. If the file exists it will be overwritten, if not it will be created
• #window – a new script window
• <windowstream> – a reference to a windowstream
• <stringstream> – a reference to a stringstream

Download a report that was built using calls to getReport() in Excel 2007 or in Excel 2003

Properties

• duration <number> – the duration of the last timed session
• durations <array> – an array of all timed sessions
• task <string> – the name of the current timed task

Demo and case study

Check out a case study and download a demo script here:

Download

Download TimeStamper.ms.