2.3.2.2.3 $( ) Substitution - Numeric to String Conversion

$( ) 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, but typically a single number or variable(dataset and data range), and format can be either an Origin output format or a C-language format.

If expression is a dataset or range variable, 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. For a full list of numeric format options, see Reference Tables: Origin Formats.

Format Description
*n Display n significant digits
.n Display n decimal places
*n* Display n significant digits, truncating trailing zeros
.n, Display n decimal places, using comma separator (US, UK, etc.)
E.n Display n decimal places, in engineering format
S*n Display n significant digits in scientific notation of the form 1E3
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. See examples below.
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. See examples below.
#n Display an integer to n places, zero padding where necessary
<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.
# #/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.
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.


Examples:

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

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

zz = 203465987;
type "zz = $(zz, E*3)";  // ANS: 203M 
type "zz = $(zz, S*3)";  // ANS: 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

type "$(time(14:31:04), T4)";   // ANS: 02 PM

type "$(time(14:31:04), Thh'.'mm'.'ss)";  // ANS: 02.31.04

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

type "$(56000, ##+###)"; //ANS: 56+000

type "$(4000, ##+##M)"; //ANS: 40+00M

type "$(10000, .0,)"; //ANS: 10,000

//display a fraction in different formats:
AA = 0.334;
type "AA = $(AA, # ##/##)"; //ANS: AA = 1/3
type "AA = $(AA, # #/8)"; //ANS: AA = 3/8

//display degree value in different formats
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
d, i SIGNED Integer values (of decimal or integer value) -2^31 -- 2^31 -1
f, e, E, g, G SIGNED Decimal, scientific, decimal-or-scientific +/-1e290 -- +/-1e-290
o, u, x, X UNSIGNED Octal, Integer, hexadecimal, HEXADECIMAL -2^31 -- 2^32 - 1

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

Here are a few examples of C codes in use in LabTalk:

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

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.