2.3.2.2 Substitution 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: %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
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;

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;

(-13 + 27) = 14

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