Sometimes you just want to store lists of name/value pairs, to keep track of a few settings throughout your script, without relying on a host of variables, resorting to .ini files, or custom attributes.

Therefore, I set about writing a basic Dictionary, or List struct, similar to VB and other languages.

Example code

Here’s a really basic example of storing 5 named variables within a List:

names = #("five", "four", "three", "two", "one")
values = #(5,4,3,2,1)
lst = List()

for i = 1 to 5 do lst.addItem names[i] values[i]

So let’s get some data back out:

lst.getValue "two"
-- 2

lst.getIndex "two"
-- 4

lst.getValues()
-- #(5, 4, 3, 2, 1)

Or print the whole lot:

lst.print() -- unsorted

five:	5
four:	4
three:	3
two:	2
one:	1

How about some sorting:

lst.sort() -- by name, alphabetically

five:	5
four:	4
one:	1
three:	3
two:	2

lst.sort field:#value -- by value

one:	1
two:	2
three:	3
four:	4
five:	5

As you can see, it’s pretty straightforward stuff!

Properties and Methods

Properties

• <array> items <name> <value> – the key/value pairs.
  • Names can be a #name, “string”, or even an index
  • Values can be any MaxWrapper value (i.e. anything)

Setters

• <ListItem> addItem <name> <value> – adds an item to the List, and if it already exists
• <ListItem> setItem <name> <value> – synonym for the above

Getters

• <value> getValue <name> – returns the value of the named item
• <index> getIndex <name> – returns the index of the named item
• <name> getName <value> – returns the name of the first item that matches the supplied value
• <ListItem> getItem <name> – returns the List item corresponding to the supplied name (typically, you wouldn’t use this, as you know the name component already, it’s just included for completeness)
• <array> getItems() – returns all items as an array of ListItem structs
• <array> getNames() – returns all names as an array
• <array> getValues() - returns all values as an array

Clear or delete

• <array> clear() – clears the lit of all items, and returns the empty ListItems array
• <boolean> deleteItem <name> – deletes the named item from the list, and returns it
• <boolean> deleteIndex <index> – deletes the item at the index, and returns it

Utilities

• <array> sort field:<name> order:<name> func:<function> – sorts the list in a variety of ways, even supply a comparison function (see the max help on qsort)
• <string> print() – prints the List items to the Listener

Next version

Possible improvements in the next version might be:

• .ini file integration, with save() and load() methods
• Support for hierarchical Lists, perhaps getValue #(#parent, #child, #grandchild, …)

Download

Download List.struct.ms here.

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.