1. Introduction

The tarray extension implements typed arrays and associated commands column and table. This page only provides reference documentation for commands. See the main contents for an introduction, programming guide and other reference documentation.

1.1. Installation and loading

Binary packages for some platforms are available from the Sourceforge download area. See the build instructions for other platforms.

To install the extension, extract the files from the distribution to any directory that is included in your Tcl installation’s auto_path variable.

Once installed, the extension can be loaded with the standard Tcl package require command.

% package require tarray
→ 0.9.0

2. Command reference

All commands are located in the tarray namespace.

2.1. Commands

loop INDEXVAR VAR VALUES SCRIPT

In the first form, SCRIPT is executed for each element in VALUES with VAR taking on the value of each element or row in VALUES in turn. VALUES may be a column, table or a Tcl list.

The second form is similar but in addition INDEXVAR is assigned the index of the element.

prettify VALUES ?options?

Returns VALUES as a more readable string format. VALUES is expected to be a column or a table. If not, it is returned unchanged.

The command takes the following options

Table 1. Prettify options
Option Description

-full BOOLEAN

If true, the full table or column is formatted and returned. Otherwise, only the leading and trailing lines specified by the -head and -tail options are returned. For VALUES that is not a column or table, the entire string is returned irrespective of this option.

-head NELEMS

Specifies the number of leading elements that are included in the returned string. Ignored if VALUES is not a column or table.

-tail NELEMS

Specifies the number of trailing elements that are included in the returned string. Ignored if VALUES is not a column or table.

print VALUES ?CHANNEL? ?options?

Prints VALUES to the specified channel in a readable string format. CHANNEL defaults to stdout if unspecified. VALUES is expected to be a column or a table. If not, it is output as by the Tcl puts command. See Prettify options for a list of valid options.

randseed ?SEED1 SEED2?

Sets the initial seed values for the random number generator (RNG). The optional SEED1 and SEED2 should be any 64-bit numbers. For normal use, this command need not be invoked as the RNG is automatically initialized internally using runtime data. For use cases such as testing where you want reproducible “random” values to be produced, you can call the command with the same seed arguments before every run.

When no arguments are specified, the RNG is reinitialized in the same manner as startup. This is generally useful to undo the effects of a previous call to randseed with specific seed values.

rng create CMDNAME TYPE ?LOWERBOUND? ?HIGHERBOUND?

Returns a new random number generator (RNG) command object named CMDNAME that can be used to produce uniformly distributed random numbers of the specified type. For types boolean, byte, int, uint and wide the range of generated values corresponds to the entire domain range by default. For type double the values are generated in the range [0,1] by default. The optional LOWERBOUND and UPPERBOUND arguments may be supplied to modify the range from which values are sampled. These are ignored for TYPE boolean.

The returned RNG command object can be used to generate random numbers by calling its get subcommand and its seed values set with the seed subcommand.

rng new TYPE ?LOWERBOUND? ?HIGHERBOUND?

Returns a new random number generator (RNG) command object that can be used to produce random numbers of the specified type. See rng create CMDNAME TYPE ?LOWERBOUND? ?HIGHERBOUND? for details. This command differs only in that the name of the returned command object is automatically generated.

RNG get ?COUNT ?LOWERBOUND UPPERBOUND??

Returns COUNT (defaults to 1 if unspecified) random numbers. RNG is a random number generator created by the rng create or rng new commands. The random numbers are within the bounds specified for RNG at the time it was created unless overridden by the additional arguments LOWERBOUND and UPPERBOUND.

RNG seed SEED1 SEED2

Sets the seed of the random number generator command object RNG created by the rng create or rng new commands. The SEED1 and SEED2 should be any 64-bit numbers. For normal use, this command need not be invoked as the RNG is automatically initialized internally using runtime data. For use cases such as testing where you want reproducible “random” values to be produced, you can set the same seed arguments before every run.

table SUBCOMMAND …​

Operates on tables. See Table commands.