2.3.2.2 Substitution Notation


Introduction

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:

%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 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 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):

Option Return Value
@# Returns the total number of worksheet columns.
@CS Returns the column index of the first selected column to the right of (and including) the columnNumber column, regardless of column designation.
@E# If columnNumber = 1, returns the number of Y error columns in the worksheet. If columnNumber = 2, returns the number of Y error columns in the current selection range. If columnNumber is omitted, columnNumber is assumed to be 1.
@H# If columnNumber = 1, returns the number of X error columns in the worksheet. If columnNumber = 2, returns the number of X error columns in the current selection range. If columnNumber is omitted, columnNumber is assumed to be 1.
@OY Returns the offset from the left-most selected Y column to the columnNumber column in the current selection.
@OYX Returns the offset from the left-most selected Y column to the columnNumber Y column counting on Y columns in the current selection.
@OYY Returns the offset from the left-most selected Y column to the columnNumber X column counting on X columns in the current selection.
@T Returns the column type. 1 = Y , 2 = disregarded, 3 = Y error, 4 = X , 5 = label, 6 = Z, and 7 = X error.
@X Returns the index number of the worksheet's first X column. Columns are enumerated from left to right, starting from 1. Use the syntax:  %(worksheetName, @X);
@Xn Returns the column short name of the worksheet's first X column. Use the syntax:  %(worksheetName, @Xn);
@Y Returns the offset from the left-most selected column to the columnNumber column in the current selection.
@Y- Returns the column number of the first Y column to the left. Returns columnNumber if the column is a Y column, or returns 0 when the Y column doesn't exist. Use the syntax:  %(worksheetName, @Y-, ColumnNumber);
@Y# If columnNumber = 1, returns the number of Y columns in the worksheet. If columnNumber = 2, returns the number of Y columns in the current selection range. If columnNumber is omitted, columnNumber is assumed to be 1.
@Y+ Returns the column number of the first Y column to the right. Returns columnNumber if the column is a Y column, or returns 0 when the Y column doesn't exist. Use the syntax:  %(worksheetName, @Y+, ColumnNumber);
@YS Returns the number of the first selected Y column to the right of (and including) the columnNumber column.
@Z# If columnNumber = 1, returns the number of Z columns in the worksheet. If columnNumber = 2, returns the number of Z columns in the current selection range. If columnNumber is omitted, columnNumber is assumed to be 1.

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)

Option Return Value
@W Returns the information in varOrNodeName; the variable is understood to be located at the workbook level, which can be seen in workbook Organizer. When it is used, there is no need to specify worksheetName!ColumnName.
@WFn Returns the information in varOrNodeName for the nth imported file. The variable can be seen in the workbook Organizer.
@WS Returns the information in varOrNodeName; the variable is understood to be located at the worksheet level, which can be seen in workbook Organizer. When it is used, there is no need to specify ColumnName.
@WC Returns the information in varOrNodeName; the variable is understood to be located at the column level, which can be seen in the Column Properties dialog.


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 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 Substitution

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

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.


Format Description Example
*n Display n significant digits 
xx=1.23456; 
type "xx = $(xx, *2)"; //ANS: xx=1.2
.n Display n decimal places 
xx=1.23456; 
type "xx = $(xx, .2)"; //ANS: xx=1.23
*n* Display n significant digits, truncating trailing zeros 
xx = 1.10001; 
type "xx = $(xx, *4*)"; //ANS: xx=1.1
.n, Display n decimal places, using comma separator (US, UK, etc.) 
xx = 1234.5678;
type "xx = $(xx, .2,)"; //ANS: xx=1,234.57
xx= 10000;
type "$(xx, .0,)"; //ANS: 10,000
E.n Display n decimal places, in engineering format 
xx=203465987;
type "xx = $(xx, E*3)"; //ANS: xx=203M
S*n Display n significant digits in scientific notation of the form 1E3 
xx=203465987;
type "xx = $(xx, S*3)"; //ANS: xx=2.03E+08
D<format> Display in custom date format, where <format> is either the index number (counting from 0) of the format, starting from the top of the Column Properties Display list; or a string built using these date and time format specifiers. 
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
T<format> Display in custom time format, where <format> is either the index number (counting from 0) of the format, starting from the top of the Column Properties Display list; or a string built using these time format specifiers. 
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
C<format> Display month or day of week in Calendar format. <format> is either M# (month), or D#=day of the week. # can be 0 (3 characters), 1 (full characters) or 2 (1 character) 
type "$(12, CM0)";  // ANS: Dec
type "$(3, CD1)";  // ANS: Wednesday
#n or ## Display an integer to n places, zero padding where necessary. Or use n number of #'s to refer to nth places 
xx=45;
type "xx=$(xx, #5)"; //ANS: 00045
type "xx=$(xx, ###)"; //AnS: 045
<prefix>##<sep>###<suffix> Display a number by specifying a separator (<sep>) between digits and optionally add prefix(<prefix>) and/or suffix (<suffix>). One # symbol indicates one digit. The last # in this expression always refers to the unit digit. The numbers of # in both first and second parts can be varied. 
xx=56000;
type "xx=$(xx, ##+###)"; //ANS: xx=56+000
xx=4000; 
type "xx=$(xx, ##+##M)"; //ANS: xx=40+00M
# #/n Round and display a number as a fraction with specified n as denominator. The numerator and denominator are separated by a forward slash /. The number of digits of numerator is adjusted accordingly. 
AA = 0.334;
type "AA = $(AA, # ##/##)"; //ANS: AA = 1/3
type "AA = $(AA, # #/8)"; //ANS: AA = 3/8
D[<space>]M[S][F][n] Display a degree number in the format of Degree° Minute' Second", where 1 degree = 60 minutes, and 1 minute = 60 seconds. Space can be inserted to separate each part. n indicates decimal places for fractions. F displays degree number without symbols and inserting spaces as separator. 
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.

Option Un/Signed Output Input Range Example
d, i SIGNED Integer values (of decimal or integer value) -2^31 -- 2^31 -1 
double nn = -247.56;
type "Value: $(nn,%d)"; // ANS: -247
f, e, E, g, G SIGNED Decimal, scientific, decimal-or-scientific +/-1e290 -- +/-1e-290 
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
o, u, x, X UNSIGNED Octal, Integer, hexadecimal, HEXADECIMAL -2^31 -- 2^32 - 1 
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

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.

English | Deutsch | 日本語