About

TableJar is a user defined class written in LotusScript. It implements a 2-dimensional table with following key features:

• automatic dynamic resize: as soon as you try to write a value into a cell that does not yet exist, the table resizes autonomously to accomodate for the new value
• memory efficient on inhomogenous rows: this datastructure does not use a strict 2-dimensional array but reserves memory for each row individually. Thus a table with a few rows containing hundreds of columns but a lot of rows which only have a small number of columns doesn't use up too much memory and so helps not to exceed the 64kByte barrier for arrays.
• maximum compatibility: each table cell uses the Variant data type
• mutability: methods to delete individual rows or to add new rows are provided
• sortable: you can sort the table rows by a choosable column. The heap-sort algorithm guarantees a fast sorting, even in worst-case scenarios.

This class was created to the sole purpose of gathering a first handful of experience with objects in Lotus Notes. However, I chose this special datastructure because it might actually be of practical use. Having years of experience in coding in Java the first contact with Lotus Script was a bit weird. The result is quite useful though. Here it is:

Methods

Sub New

The New subroutine is automatically called when you create a TableJar object with the keyword New. No further parameters are necessary.

Example: Dim books As New TableJar

Property Count

This property gives back the number of rows the table currently has. This does include empty rows as well.

Example:
i% = 0
While i% < someTable.Count
Msgbox someTable.getValue(i%, 0)
i% = i% + 1
Wend

Public Sub setValue(row As Integer, column As Integer, value As Variant)

This inserts values into the table. You specify the row, the column as positive integers and any value that is to be put into that position of the table. If the row or column exceeds the current size of the table it will be automatically enlarged.

Example: Call someTable.setValue(4,2, "I'm a value that has been inserted into cell (4,2)")

Public Function getValue(row As Integer, column As Integer) As Variant

Returns the value stored at the given position. If you specify a cell that has not been assigned a value before by 'setValue' this function may throw an error (Subscript out of range)!

Example: someValue = someTable.getValue(4, 2)

Public Sub deleteRow(row As Integer)

Removes the given row and moves all following rows up by one place. This also reduces the table size by 1.

Example: Call someTable.deleteRow(4)

Public Sub insertRow(row As Integer)

Inserts an empty row before the row given in the sub-call. That way you can insert a new row even before the first row (row #0). To add a new row before the last row no call of 'insertRow' is necessary. Using 'setValue' for rows that exceed the current row-count of the table automatically inserts the rows needed.

Example: Call someTable.insertRow(4)

This example would insert an empty row with the number 4 and move all earlier rows n>=4 to their new positions n+1.

Public Sub sort(keyColumn As Integer)

Sorts the rows of the table by using the values in the given column as a key. The table is sorted by ascending keys.

Example: Call someTable.sort(0) ' sorts the table using the first column as a key

Usage example (the big picture)

Dim books As New TableJar

Call books.setValue(0,0, "The Elegant Universe")
Call books.setValue(0,1, "Brian Greene")
Call books.setValue(0,2, 11.17)

Call books.setValue(1,0, "The Feeling Good Handbook")
Call books.setValue(1,1, "David D. Burns")
Call books.setValue(1,2, 12.57)

Call books.setValue(2,0, "Backyard Ballistics")
Call books.setValue(2,1, "William Gurstelle")
Call books.setValue(2,2, 11.87)

This creates a table like this one here:

You can easily sort this table by any column. Let's try it with the price:

Call books.sort(2) ' sorts by price which is the colum 2 (first column has the number 0)

The table will look like this then:

To remove individual rows do this:

Call books.remove(1) ' removes the row with the index 1 (which is the second row)

As to be expected the result would look like this:

Things to keep an eye on

Cells with no contents

If you access a cell that has not been filled with contents the value 'Nothing' will be returned. This also happens when you specify a row or column that is out of the scope of the current table (which basically is a cell that has not been filled...).

Why the name "TableJar"

Well... 'table' should be clear. As for the 'Jar': all my recent weird inventions have the word 'Jar' in them ;-) This comes from my IRC nick "Jaran". However, as for this code the suffix "Jar" is in fact appropriate, as a jar is - like a table - a form of container.

Download

You can download the code for TableJar here. The text file contains two user defined classes: the TableJar and a class Row. The latter one is used by TableJar.

If you have any questions, suggestions or anything else to say about Lotus Script and my code, feel free to write in my forum! No registration is required!