Perl functions provided with deceit

deceit is distributed with the following Perl functions that can be used to fill the dataset with data from text files.

• rows

  This function determines the number of rows in a text file. Blank lines, as well as line starting with # are not counted. The function takes one string argument, namely the name of the text file to be used.

  Example:

  table "Table" rows("table.dat") "a table"
  

• fillColumn

  The function signature is as follows: the first argument must be the variable col, the second the name of a text file from which the data is to be extracted, the third argument an integer denoting from which column in the text file data should be extracted. A column separator can be specified as an optional fourth argument. This is most useful when dealing with vector or string columns, as explained in the examples that follow. An optional fifth argument is a boolean (1/0) that indicates whether vector columns should be padded with zeroes if the text file does not contain enough elements to fill the row.

  Example of a scalar column:

  column "Column" int32 "integer column" "s" fillColumn(col, "column.dat", 0)
  

  Columns in the text file are delimited by white space. The first column is given number 0. Blank lines and lines starting with # are ignored.

  The file column.dat might look like this:

  1 10 100
  2 20 200
  3 30 300
  

  fillColumn will interpret this as a three-column ascii file. The data will be extracted from the first column (the first column is number 0).

  Example of a vector column:

  column(2) "Column" int32 "integer column" "s" fillColumn(col, "column.dat", 1, ":")
  

  The file column.dat might look like this:

  1 : 10 100 : 1000
  2 : 20 200 : 2000
  3 : 30 300 : 3000
  

  When the separator : is given, fillColumn will interpret this as a three-column ascii file. The second column (column number 1), from which the data are to be extracted, contains a vector of two elements. An error will result should any row in the second column contain more or less than 2 elements.

  At times it is acceptable to have less elements in the ascii file than cells in the dataset column. It is possible to instruct fillColumn to pad rows with trailing zeroes with a fifth parameter:

  column(2) "Column" int32 "integer column" "s" fillColumn(col, "column.dat", 1, ":", 1)
  

  Example of a two-dimensional vector column:

  column(2,3) "Column" int32 "integer column" "s" fillColumn(col, "column.dat", 0, ":")
  

  Vector columns in the text file are delimited by the separator character. Inside each vector column the individual elements are separated by white space. deceit follows the C convention for array indeces, i.e., the right-most index running faster. For instance, to fill a cell of dimensions (2,3) the elements must be stored as: (1,1) (1,2) (1,3) (2,1) (2,2) (2,3).

  Example of a string column:

  column(10) "Column" string "string column" "s" fillColumn(col, "column.dat", 0)
  

  String columns are vector columns of characters. Multidimensional columns are not supported. That is, a string column with dimensions (2,3) is treated as one with dimensions (6). This is not a limitation of deceit. Strings in the text file should be quoted if they contain blanks. Strings are blank padded or truncated, as needed. A warning is issued in this case.

• fillArray

  This function takes a file name as its only argument. The file should contain the array data ``unwrapped'', with the left-most indices running faster (C convention).

• fillConstColumn

  This function takes two arguments: the variable col and a scalar. Each element in the column is set equal to the scalar specified.

• fillConstArray

  This function takes two arguments: the variable arr and a scalar. Each element in the array is set equal to the scalar specified.