Table Class

A class to make working with views and tabular data easier.

Changes

New in Maptitude 2022

Constructor

table = CreateObject(“Table”, array options)

Option	Type	Contents
View	String	Name of an existing view to create the table on
FileName	String	File path to be opened into a table. Can be either a table file (BIN or CSV) or a geographic file (DBD or CDF)
Fields	Array	An array of field definitions used to create a new table from scratch. See Table.AddFields() for details on this option
Layer	String or Numeric	Optional. Layer name or its position in the geographic file when FileName extension is CDF or DBD. For example, node layers are always first in line layers. Defaults to 1 (for the first layer in the file).

Only one of View, FileName or Fields options should be provided.

Methods

AddField(array options)

Adds a single field to the table.

Option	Type	Contents
FieldName	String	Name of field to be added. If the only argument passed to AddField() is a string, it is assumed to be the FieldName
Type	String	Optional. Field type. Default: real. Allowed Values: 'short', 'integer', 'real', 'string', etc. See ModifyTable() help page for all possible values
Width	Integer	Optional display width of the field. Default: 12
Decimals	Integer	Optional. Number of decimal places to display. Default: 2 for real fields. 0 otherwise
Description	String	Optional description for the field

If the field already exists it will not be modified

AddFields(array options)

Adds multiple fields at once, which is faster than adding many fields one at a time.

Option	Type	Contents
Fields	Array	Array where each element is an array containing the options describe din the Add\|Field() method above. See the example under Adding/Dropping multiple fields below

Fields that already exist are not modified

AddRows(array options)

Add empty rows to a table.

Option	Type	Contents
EmptyRows	Integer	The number of empty rows to be added

Aggregate(array options)

Groups and summarizes tables by fields.

Option	Type	Contents
GroupBy	String or array of strings	Fields to group by
FieldStats	Array	Each element is a field name paired with stats. Example: {Length: "sum", "FFSpeed": {"average", "max"}}. Stats supported: count, sum, average, distinct, variance, min, max. Resulting fields have a naming convention like “sum_Length” and “average_FFSpeed”

ChangeField(array options)

Used to change various attributes of a field. See RenameField() if just changing field name.

Option	Type	Contents
FieldName	String	Name of the existing field to be changed
NewName	String	Optional. The new name of the field
Type	String	Optional. Field type. Default: real. Allowed Values: 'short', 'integer', 'real', 'string', etc. See ModifyTable() help page for all possible values
Width	Integer	Optional display width of the field.
Decimals	Integer	Optional. Number of decimal places to display. Default: 2 for real fields. 0 otherwise
Description	String	Optional description for the field

ChangeSet(array options)

Changes which set is active. Active sets are used when getting/setting data vectors and must be created using CreateSet(). Call ChangeSet() with no arguments to clear the active set (i.e. use all records).

Option	Type	Contents
SetName	String	Name of the set to switch to or null to clear the active set. If the only argument passed is a string, it is assumed to be the SetName

CreateSet(array options)

Creates a selection set on the table. If the set already exists, it is updated. Does not make that set active (See ChangeSet() ).

Option	Type	Contents
SetName	String	Name of the new set to create
Filter	String	Conditional statement / query used to select records. Example: "Area > 1"
Operation	String	Optional. How the new set should be created (see SelectByQuery() for details). Valid values: “several”, “less”, “more”, “subset”. Default: “several”
Options	Array	Other options passed to SelectByQuery()

DropSet(array options)

Removes a set from the table.

Option	Type	Contents
SetName	String	The set to be dropped

DropFields(array options)

Permanently removes a field (or fields) from a table.

Option	Type	Contents
FieldNames	String or Array	Name(s) of field(s) to be removed
NotFoundError	Boolean	Should an error be thrown if the field does not exist when attempting to remove? Default: false

Export(array options)

Exports a table to a file (either FFB or CSV). Returns a table object.

Option	Type	Contents
FileName	String	Optional. Full file path where the table will be exported. Do not provide if providing ViewName
ViewName	String	Optional. The name of the view for the memory table that will be created. If neither FileName nor ViewName is provided, a mem table will be created with a unique name
FieldNames	Array	Optional. Names of fields to include in the new table. Default is all fields

GetActiveSet(array options)

Returns the currently active set on the table.

GetDataVectors(array options)

Retrieve multiple fields at once.

Option	Type	Contents
FieldNames	Array	Optional. Name of fields to get data for. If null, data for all fields is returned
Options	Array	Optional. Other options passed to GetDataVectors(). Note: the “Sort Order” option is set to the table’s sort order by default (see Table.Sort() ). Also, the “options” option is set to true by default

GetFieldNames()

Returns the field names of the table.

GetFieldSpes()

Returns the field specs of the table.

GetRecordCount(array options)

Returns the number of records in a table.

Option	Type	Contents
SetName	String	Optional. If provided, only the number of records in the set are returned

GetSets()

Returns the names of selection sets on the table.

GetSortOrder()

Returns the current sort order of the table.

GetView()

Returns the name of the view referenced by the table object.

Join(array options)

Joins two tables together and returns a new table object.

Option	Type	Contents
Table	Table object	The table to be joined to the current table
LeftFields	String or Array	Fields in existing (left) table used for joining
RightFields	String or Array	Fields in second (right) table used for joining.
Options	Array	Optional. Additional options passed to JoinViewsMulti()

RenameField(array options)

Changes the name of a field.

Option	Type	Contents
FieldName	String	Name of the existing field to be changed
NewName	String or Array	The new name of the field

SetDataVectors(array options)

Used to write values to multiple fields at once. Faster than writing vectors one at a time.

Option	Type	Contents
FieldData	Array	An array of two-element arrays. The first element is the name of the field and the second is a data vector. Example: {{“Speed”, v_speed}, {“Time”, v_time}}
Options	Array	Optional. Other options passed to GetDataVectors(). Note: the “Sort Order” option is set to the table’s sort order by default (see Table.Sort() )

SetDataVectors(array options)

Used to write values to multiple fields at once. Faster than writing vectors one at a time.

Option	Type	Contents
FieldData	Array	An array of two-element arrays. The first element is the name of the field and the second is a data vector. Example: {{“Speed”, v_speed}, {“Time”, v_time}}
Options	Array	Optional. Other options passed to GetDataVectors(). Note: the “Sort Order” option is set to the table’s sort order by default (see Table.Sort() )

Sort(array options)

Sorts a table by given fields.

Option	Type	Contents
FieldArray	Array	An array of field-direction pairs. If null, any existing sort order is removed. Example: {{"State", "Ascending"}, {"Population", "Descending"}}

View()

Displays a table in an editor window.

Examples

folder = RunMacro("G30 Tutorial Folder")

file = folder + "AIRPORTS.BIN"

// Test export and create a copy for join tests

table = CreateObject("Table", {FileName: file})

// can also call like this:

// table = CreateObject("Table", file)

file_copy = Substitute(file, ".BIN", "_copy.bin",)

table.Export({FileName: file_copy})

// Basics of getting/setting data

v = table.City

v = table.[Site#]

table.AddField("test")

fields = table.GetFieldNames()

table.DropFields({FieldNames: "test"})

fields = table.GetFieldNames()

table.CreateSet({SetName: "Hawaii", Filter: "State = 'HI'"})

sets = table.GetSets()

table.ChangeSet({SetName: "Hawaii"})

table.[A Real] = 5.1

table.AnInt = 5

table.ChangeSet()

table.AString = "test"

table.RenameField({FieldName: "AString", NewName: "String"})

table.ChangeField({FieldName: "A Real", Decimals: 3})

table.DropFields({FieldNames: {"String", "A Real", "AnInt"}})

// Getting/setting multiple fields

data = table.GetDataVectors({FieldNames: {"City", "County"}})

v = data.City

table.SetDataVectors({FieldData: data})

// Sorting

table.Sort({FieldArray: {County: "Ascending", Name: "Ascending"}})

view = table.GetView()

n = GetRecordCount(view, )

v = Vector(n, "Long", {{"Sequence", 1, 1}})

table.test = v

table.Sort({FieldArray: {County: "Descending", Name: "Descending"}})

v = table.test

data = table.GetDataVectors({FieldNames: {"test"}})

table.DropFields({FieldNames: "test"})

data = table.GetDataVectors({FieldNames: {"City", "County"}})

table.SetDataVectors({FieldData: data})

table.DropFields({FieldNames: {"test", "test2"}})

table.Sort()

// Adding/dropping multiple fields

fields = {

{FieldName: "CongSpeed", Type: "Real", Width: 10, Decimals: 3, Description: "Congested Speed"},

{FieldName: "CongTime", Type: "Real", Width: 10, Decimals: 3, Description: "Congested Travel Time"}

}

table.AddFields({Fields: fields})

table.DropFields({FieldNames: {"CongSpeed", "CongTime"}})

// Fields with odd names

table.Length = 1

table.DropFields({FieldNames: "Length"})

table.[A Space] = 1

table.DropFields({FieldNames: "A Space"})

table.[An *] = 1

table.DropFields({FieldNames: "An *"})

// Joining views and getting data

right_table = CreateObject("Table", {FileName: file_copy})

jt = table.Join({

Table: right_table,

LeftFields: {"Name", "City"},

RightFields: {"Name", "City"}

})

jt.ChangeSet("Hawaii")

test = jt.[Table_1.Site#]

jt.View()

jt = null

// Aggregation

agg_tbl = table.Aggregate({

GroupBy: {"Name", "City"},

FieldStats: {FLIGHTS: "sum", Domestic: {"sum", "average"}}

})

v = agg_tbl.average_Domestic

agg_tbl = table.Aggregate({

GroupBy: "State",

FieldStats: {FLIGHTS: "sum", Domestic: {"sum", "average"}}

})

v = agg_tbl.sum_FLIGHTS

agg_tbl.View()

// Creating a new table from scratch

fields = {

{FieldName: "CongSpeed", Type: "Real", Width: 10, Decimals: 3, Description: "Congested Speed"},

{FieldName: "CongTime", Type: "Real", Width: 10, Decimals: 3, Description: "Congested Travel Time"}

}

new = CreateObject("Table", {Fields: fields})

new.AddRows({EmptyRows: 5})

new.View()

// Using methods inherited from the CalculateTable class

table.ApplyFilter("State = 'NY'")

sum = table.Statistics(FieldName: {"Foreign"} )

See Also:

CC.ModifyTableOperations