2.3.2.2 Substitution Notation

Substitution-Notation

IntroductionSubstitution Notation

When a script is executed, it is sent to the LabTalk interpreter. Among other tasks, the interpreter searches for special substitution notations, which are identified by their initial characters, % or $. When a substitution notation is found, the interpreter replaces the original string with another string, as described in the following section. The value of the substituted string is unknown until the statement is actually executed. Thus, this procedure is called a run-time string substitution.

There are three types of substitutions described below:

• String register substitution, %A - %Z
• %( ) Substitution, a powerful notation to resolve %(str$), %(range), worksheet info and column dataset names, worksheet cells, legend and etc.
• $( ) Substitution, where $(expression) resolves the numeric expression and formats the result as a string

%A - %Z

Using a string register is the simplest form of substitution. String registers are substituted by their contents during script execution, for example

FDLOG.Open(A);   // put file name into %A from dialog
%B=FDLOG.path$;  // file path put into %B
doc -open %B%A;  // %B%A forms the full path file name

String registers are used more often in older scripts, before the introduction of string variables (Origin 8), which allows for more reliable codes. To resolve string variables, %( ) substitution is used, and is discussed in the next section.

%( ) Substitution

String Expression SubstitutionString Expression Substitution

While LabTalk commands often accept numeric expressions as arguments, none accept a string expression. So if a string is needed as an argument, you have to pass in a string variable or a string expression using the %( ) substitution to resolve run-time values. The simplest form of a string expression is a single string variable, like in the example below:

string str$ = "Book2";         
win -o %(str$) {wks.ncols=;}

Worksheet Column and Cell Substitutionsubstitution, worksheet column/cellworksheet, column and cell substitution

The following notation allows you to access worksheet cells as a string as well as to get the column dataset name from any workbook sheet. Before Origin 8, each book had only one sheet so you could refer to its content with the book name only. Newer versions support multiple worksheets, so we recommend that you use [workbookname]sheetname to refer to a specific sheet, unless you are certain that the workbook contains only one sheet.

To return individual cell contents

• %(workbookName, column, row) -- references the active sheet in the named book
• %([workbookname]sheetname, column, row) -- specifies book and sheet

For example, if the third cell in the fourth column in the active worksheet of Book1 contains the value 25, then entering the following statement in the Script window will set A to 25 and put double that value into column 1, row 4 of the sheet named "Results" in the same book.

A = %(Book1, 4, 3);
%([Book1]Results, 1, 4) = 2 * A;

To return the contents of a text cell, use a string variable:

string strVar$ = %(Book1, 2, 5); // Note : No end '$' needed here
strVar$ = ;

Formatting the return value

• Before Origin 8.1, you could only specify column and row index and numeric cells always returned full precision.
• Origin 8.1 added support for referencing column by either index or name, and row will also support Label Row Characters such as L for Long Name.
• Additionally, the syntax supports an optional format argument to return numbers in a specific format (i.e. %([workbookname]sheetname, column, row[,format])).

Return value in current column format with "W" and "@WL"

Use the letter "W" as your "format" parameter to return the value in the current column format.

%([workbookname]sheetname, column, row[,W])

Example:

Assume Book2, sheet3 col(Signal)[3] has a numeric value of 12.3456789, but only 2 decimal places are displayed (set in the Column Properties dialog).

//format string W to use current column format
//Should return 12.35
type "Col(Signal)[3] displayed value is %([Book2]Sheet3,Signal,3,W)";
//full precision if format not specified
A=%([Book2]Sheet3,Signal,3);
A=;// shows 12.3456789
//Or specify a custom format e.g. 3 decimal places
type "Showing 3 decimal places:%([Book2]Sheet3,Signal,3,.3)";

Another syntax can be used to maintain the displayed format of the data, for customizations made either in the Format Cells dialog or the Column Properties dialog:

%([workbookName]sheetName, @WL, column[row][, W])

Example:

//Use W with @WL option to keep the display format 
type "Col(Signal)[3] displayed value is %([Book2]Sheet3, @WL, Signal[3], W)";
//When W is omitted, return full precision
B=%([Book2]Sheet3,@WL, Signal[3]);
B=;// shows 12.3456789
//Or specify a custom format e.g. 3 decimal places
type "Showing 3 decimal places:%([Book2]Sheet3,@WL, Signal,3,.3)";

The format character W was introduced in Originl 9.1 to replace the usage of "C" in previous versions. However, Origin maintains support for the use of %([workbookName]sheetName, column, row, C) to return the value in the current column format.

Calculation Involving Datasets from Another Sheet

The ability to get a dataset name from any book or sheet (Dataset Substitution) can be very useful in doing calculations involving columns in different sheets, like:

// Sum col(1) from sheet2 and 3 and place the result into col(1) of the active sheet 
col(1)=%([%H]sheet2, 1) + %([%H]sheet3, 1);

// subtract by col "signal" in the 1st sheet of book2 and 
// put result into the active book's sheet3, "calibrated" col
%([%H]sheet3, "calibrated")=col(signal) - %([Book2]1,signal);

The column name should be quoted if using long name. If not quoted, then Origin will first assume short name, if not found, then it will try using long name. So in the example above,

%([%H]sheet3, "calibrated")

will force a long name search, while

%([Book2]1,signal)

will use long name only if there is no column with such a short name.

Worksheet Information Substitution

Similar to worksheet column and cell access with substitution notation, the @ Substitution (worksheet info substitution) make uses of the @ character to differentiate from a column index or name in the 2nd argument. This notation allows access to worksheet info and metadata.

As with the Worksheet Column and Cell Substitution notation described above, there is an older still-supported syntax for a one-sheet window but we recommend using the newer notation (introduced in Origin 8):

To return information on the worksheet

• %(workbookName, @option, columnNumber) -- references the active sheet in the named book
• %([workbookName]worksheetName, @option, columnNumber) -- specifies sheet and book

Here, option can be one of the following (note that parameter columnNumber is omitted for some options):

The options in this table are sometimes identified as @ options or @ variables. The @Options in the Text Label Options page can also be used in worksheet information substitution.

Information Storage and Imported File Information

These @W variables access metadata stored within Origin workbooks, worksheets, and columns, as well as information stored about imported files.

Use a similar syntax as above, replacing column number with variable or node information:

%([workbookName]worksheetName!columnName, @option, varOrNodeName)

Examples of @ Substitution

The script below returns the column type for the fourth column in Book 2, Sheet 3:

string colType$ = %([Book2]Sheet3, @T, 4);  
colType$=;

An import filter can create a tree structure of information about the imported file that gets stored with the workbook. Here, for a multifile import, we return the number of points in the 3rd dataset imported into the current book:

%z=%(%H,@WF3,variables.header.noofpoints);
%z=

If the currently active worksheet window has six columns (XYYYYY) and columns 2, 4, and 5 are selected, then the following script shows the number of the first selected Y column to the right of (and including) the column whose index is equal to columnNumber (the third argument):

loop(ii,1,6)
{
    type -l %(%H, @YS, ii),;
}
type;

This outputs:

   2,2,4,4,5,0,

Legend and Axis Title SubstitutionLegend Substitution Axis Title Substitution

Graph legends and axis titles also use %( ) substitution. The first argument must be an integer to differentiate it from other %( ) notations, where the first argument is a worksheet specifier. The legend and axis title substitution syntax is:

%(PlotIndex[, @option])

where PlotIndex is the index of the data plot in the current layer or a question mark ("?"). The variable PlotIndex might be followed by more options, such as a plot designation character (X, Y or Z) associated with the data plot; when not specified this is assumed to be Y. The @option parameter is an optional argument that controls the legend contents. For example:

// In the legend of the current graph layer ...
// display the Long Name for the first dependent dataset.
legend.text$ = %(1Y, @LL)  

// Equivalent command (where, Y, the default, is understood):
legend.text$ = %(1, @LL)

Alternatively, to display the Short Name for the second independent (i.e., X) dataset in the legend, use:

legend.text$ = %(2X, @LS)

The %(?Y) for Axis title is a special syntax that allows the text label to default to a pre-specified data plot index (which can be set in Plot Details: Legends/Titles: Data Plot Index for Auto Axis Titles), instead of an index (1, 2, ... n) that you supply. To display Y data long name followed by units in <> as left Y axis title, use:

yl.text$ = %(?Y,@(@LL<@LU>));

You can refer to the legend substitution notation page for further information and the text label options page for a complete list of @options.

Note: This style of legend modification is limited in that it only changes a single legend entry, but the syntax is good to understand, as it can be used in the Plot Details dialog.

The legendupdate X-Function provides an easier and more comprehensive way to modify or redraw a legend from Script!

Keyword Substitutionsubstitution, keyword

The %( ) substitution notation is also used to insert non-printing characters (also called control characters), such as tabs or carriage returns into strings. Use LabTalk keywords to access these non-printing characters. For example,

// Insert a carriage-return, line-feed (CRLF) into a string:
string ss$ = "Hello%(CRLF)Goodbye";
ss$=;     // ANS: 'Hello', 'Goodbye' printed on separate lines
// Can be typed directly
type ss$;
// But use %() substitution when mixed with literals
ty I say %(ss$) you say;

$( ) Substitution$( ) Substitution

The $() notation is used for numeric to string conversion. This notation evaluates the given expression at run-time, converts the result to a numeric string, and then substitutes the string for itself.

The notation has the following form:

$(expression [, format])

where expression can be any mathematical expression, dataset or data range. The format is optional. It can be either an Origin format or a C-language format.

If expression is a dataset or data range, it returns a value list separated by space. (Minimum Version: 9.1 SR0)

For example:

//Define a dataset
dataset ds1 = {1, 3, 5, 7};
//Output the result of substitution notation
type $(ds1);//ANS:1 3 5 7;
type $(ds1, *2);//ANS: 1.0 3.0 5.0 7.0

//Pass the values in the first column to range variable rx
range rx = col(1);
//Output the result of substitution notation
type $(rx);

Default Format

The square brackets indicate that format is an optional argument for the $() substitution notation. If format is excluded Origin will carry expression to the number of decimal digits or significant digits specified by the @SD system variable (which default value is 14). For example:

double aa =  3.14159265358979323846;
type $(aa);    // ANS: 3.1415926535898

Origin Formats

Origin supports custom formatting of numeric values in the worksheet or in text labels. The following is a partial list, shown only for demonstrating the concept. For a full list of numeric format options, see Reference Tables: Origin Formats.

xx=1.23456; 
type "xx = $(xx, *2)"; //ANS: xx=1.2

xx=1.23456; 
type "xx = $(xx, .2)"; //ANS: xx=1.23

xx = 1.10001; 
type "xx = $(xx, *4*)"; //ANS: xx=1.1

xx = 1234.5678;
type "xx = $(xx, .2,)"; //ANS: xx=1,234.57
xx= 10000;
type "$(xx, .0,)"; //ANS: 10,000

xx=203465987;
type "xx = $(xx, E*3)"; //ANS: xx=203M

xx=203465987;
type "xx = $(xx, S*3)"; //ANS: xx=2.03E+08

type "$(date(7/20/2009), D1)";  // ANS: Monday, July 20, 2009
type "$(date(7/20/2009), Dyyyy'-'MM'-'dd)";  //ANS: 2009-07-20
DT=2459858.6946202; //assign a julian date to DT
type "DT = $(DT, D1)"; // ANS: DT = Thursday, October 6, 2022
type "Now= $(@D, DMM-dd-yyyy h:mm:ss tt)"; // @D: current date&time

type "$(time(14:31:04), T4)";   //ANS: 02 PM
type "$(time(14:31:04), Thh'.'mm'.'ss)";  //ANS: 02.31.04
DT=2459858.6946202;
type "DT = $(DT, T0)"; // ANS: DT = 16:40
type "Now = $(@D, THH:mm:ss.##)"; // @D: current date&time

type "$(12, CM0)";  // ANS: Dec
type "$(3, CD1)";  // ANS: Wednesday

xx=45;
type "xx=$(xx, #5)"; //ANS: 00045

xx=56000;
type "xx=$(xx, ##+###)"; //ANS: xx=56+000
xx=4000; 
type "xx=$(xx, ##+##M)"; //ANS: xx=40+00M

AA = 0.334;
type "AA = $(AA, # ##/##)"; //ANS: AA = 1/3
type "AA = $(AA, # #/8)"; //ANS: AA = 3/8

DD = 37.34255;
type "DD = $(DD, DMS)"; //ANS: DD = 37°20'33"
type "DD = $(DD, D MS)"; //ANS: DD = 37° 20' 33"
type "DD = $(DD, DMSF)"; //ANS: DD = 37 20 33
type "DD = $(DD, DMF1)"; //ANS: DD = 37 20.6

C-Language Formats

The format portion of the $() notation also supports C-language formatting statements.

double nn = -247.56;
type "Value: $(nn,%d)"; // ANS: -247

double nn = 1.23456e5;
type "Values: $(nn, %9.4f), $(nn, %9.4E), $(nn, %g)";
// ANS: 123456.0000, 1.2346E+005, 123456
double nn = 1.23456e6;
type "Values: $(nn, %9.4f), $(nn, %9.4E), $(nn, %g)";
// ANS: 123456.0000, 1.2346E+006, 1.23456e+006

double nn = 65551;
type "Values: $(nn, %o), $(nn, %u), $(nn, %X)";
// ANS: 200017, 65551, 1000F

Note: In the last category, negative values will be expressed as two's complement.

Combining Origin and C-language Formats

Origin supports the use of formats E and S along with C-language format specifiers. For example:

xx = 1e6;
type "xx = $(xx, E%4.2f)";  // ANS: 1.00M

Displaying Negative Values

The command parsing for the type command (and others) looks for the - character as an option switch indicator. If you assign a negative value to the variable K and try to use the type command to express that value, you must protect the - by enclosing the substitution in quotes or parentheses. For example:

K = -5;
type "$(K)"; // This works
type ($(K)); // as does this
type $(K);   // but this fails since type command has no -5 option

Dynamic Variable Naming and Creation

Note that in assignment statements, the $() notation is substitution-processed and resolved to a value regardless of which side of the assignment operator it is located.

This script creates a variable A with the value 2.

A = 2;

Then we can create a variable A2 with the value 3 with this notation:

A$(A) = 3;

You can verify it by entering A$(A) = or A2 = in the Script window.

For more examples of $() substitution, see Numeric to String conversion.

%n Macro and Script Arguments Argument, Subsitution%n, Argument

Substitutions of the form %n, where n is an integer 1-5 (up to five arguments can be passed to a macro or a script), are used for arguments passed into macros or sections of script.

In the following example, the script defines a macro that takes two arguments (%1 and %2), adds them, and outputs the sum to a dialog box:

def add {type -b "(%1 + %2) = $(%1 + %2)"}

Once defined, the macro can be run by typing:

add -13 27;

The output string reads:

(-13 + 27) = 14

since the expression $(%1 + %2) resolves to 14.