A Gekko string looks like for instance %s = 'a';, note that string names always start with the symbol % (like the other scalars value and date), and strings are generally enclosed in single quotes.

An important capability regarding Gekko strings is so-called string interpolation, using {}-curlies inside the '...' string. If %s1 = 'cat' and %s2 = 'black', it is more readable to use %s = 'The {%s1} is {%s2}'; than %s = 'The ' + %s1 + ' is ' + %s2;. String interpolation resembles name composition, because if %s = 'x', the interpolated string 'a{%s}b' is equal to 'axb', whereas in a similar way, the composed series name a{%s}b is equal to axb. A string can be used to refer to a variable, when using {}-curlies. For instance, if %s = 'b2:x!q', the name {%s} will refer to the variable b2:x!q (a quarterly series x, taken from the b2 databank). See also the syntax diagrams.

Strings are often used as list elements, for instance #m = ('a', 'b', 'c'). In that case, prt #m; will print these three strings, whereas prt {#m}; will print the series a, b, and c.

There are a lot of possibilities regarding the manipulation of strings, cf. the sections below.

Syntax

%s = expression;
string ?; //print string scalars

Note: You may use the non-mandatory string keyword to indicate string type (like string %x = %y + %z;).

Strings can be added together (concatenated) with the + operator.

A string (or list of strings) representing variable names may be manipulated by means of Gekko's inbuilt functions to handle these. Variable names here include bank, frequency, indexes, etc., and examples of such functions could be setBank(), removeBank(), replaceBank(), setFreq(), removeFreq(), setNamePrefix(), etc. There are many more of such functions, see the functions section, under ‘Bank/name/frequency/index manipulations’.

For instance, if you have a list #m = ('x', 'y');, you may use prt {#m}; to print out x and y, prt {#m.setBank('b')}; to print out b:x and b:y, or prt {#m.setFreq('q')}; to print out x!q and y!q (here, prt b:{#m}; and prt {#m}!q; will work, too).

There are quite a few string functions, where strings can be combined in different fashions.

String combining functions

Function name	Description	Examples
[x]-index	Index: returns the character at position x (integer). Returns: string	%s = 'abcd'; prt %s[2]; //'b'
[x1..x2]-index	Index: returns the range of characters from position x1 to x2 (both inclusive, integers). You may omit x1 or x2. Returns: string	%s = 'abcd'; prt %s[2..3]; //'bc' prt %s[2..]; //'bcd'
concat(s1, s2)	Appends the two strings: same as s1 + s2. Returns: string	%s = concat('He', 'llo'); Result: 'Hello'.
endswith(s1, s2)	Returns 1 if the string s1 ends with the string s2, else 0. The comparison is case-insensitive. Returns: val	%v = endswith('abcde', 'cde'); Returns: 1
includes(s1, s2)	Returns 1 if the string s2 is found inside (as a part of) string 1, else 0 is returned. The search is case-insensitive. Note that the contains() function is not useful regarding such in-string searches. Returns: val	%s = 'abCd'; prt %s.includes('bc'); //1
index(s1, s2)	Searches for the first occurrence of string s2 in string s1 and returns the position. It returns 0 if the string is not found. The search is case-insensitive Returns: val	%v = index('onetwothreetwo', 'two'); Returns: 4. %v = index('oneTWO', 'two'); Returns: 4.
isAlpha(s)	Returns 1 if all the characters of the string s are letters (alphabet).	%v = isAlpha('aBc'); Returns: 1
isLower(s)	Returns 1 if the string s contains no uppercase characters.	%v = isLower('abc12'); Returns: 1
isNumeric(s)	Returns 1 if all the characters of the string s are of numeric value.	%v = isNumeric('123'); Returns: 1
isUpper(s)	Returns 1 if the string s contains no lowercase characters.	%v = isUpper('ABC12'); Returns: 1
length(s) len(s)	The length of the string s (number of characters). You may use len() instead of length(). Returns: val	%v = %s.length();
lower(s)	The string s in lower-case letters. Returns: string	%s = lower('aBcD'); Result: 'abcd'.
nl()	A system newline/linebreak. Computerwise, nl() is equal to the C# string "\n", but beware that you cannot use the Gekko string '\n' instead of nl(), because the former is equal to the C# string "\\n". Returns: string	%s = 'a' + nl() + 'b'; //string with newline tell %s; #m = %s.split(nl()); //list with 2 elements p #m;
prefix(s1, s2)	If s1 is a string, it has the string s2 prefixed (prepended). Returns: string	%s1 = %s2.prefix('a');
replace(s1, s2, s3) replace(s1, s2, s3, max)	In the string s1, the function replaces all occurrences of s2 with s3. Replacement is case-insensitive. If max > 0, the replacement is performed at most max times. Returns: string	%s = replace(%s1, %s2); //or: replace(%s, %s1, %s2)
split(s1, s2) split(s1, s2, removeempty) split(s1, s2, removeempty, strip)	Splits the string s1 by means of the delimiter s2. Empty elements are removed per default, and the resulting strings are stripped (blanks are removed from the start and end of the strings). The last two options are 1 and 1, if omitted.	%s = 'a, b,c,,d, , e'; #m1 = %s.split(','); //--> ('a', 'b', 'c', 'd', 'e') #m2 = %s.split(',', 1, 1); //--> ('a', 'b', 'c', 'd', 'e'); #m3 = %s.split(',', 0, 1);'); //--> ('a', 'b', 'c', '', 'd', '', 'e') #m4 = %s.split(',', 1, 0);'); //--> ('a', ' b', 'c', 'd', ' ', ' e') #m5 = %s.split(',', 0, 0);'); //--> ('a', ' b', 'c', '', 'd', ' ', ' e') %s = 'a' + nl() + 'b'; //string with newline #m = %s.split(nl(), 0); //--> ('a', 'b') //Note: the 0 argument keeps empty lines
startswith(s1, s2)	Returns 1 if the string s1 starts with the string s2, else 0. The comparison is case-insensitive. Returns: val	%s = 'abcde'; %v = %s.startswith('abc'); Returns: 1
strip(s)	Removes blank characters from the start and end of the string s. Returns: string	%s1 = %s2.strip(); //or: strip(%s1)
stripstart(s)	Removes blank characters from the start of the string s. Returns: string	%s1 = %s2.striptart(); //or: stripstart(%s1, %s2)
stripend(s)	Removes blank characters from the end of the string s. Returns: string	%s1 = %s2.stripend(); //or: stripend(%s1, %s2)
substring(s, start, length)	The piece of the string s between character number start and length (these must be integer values). You can alternatively use a 'slice', using []-notation, see example. Returns: string	%s = %s1.substring(3, 2); //or: substring(%s1, 3, 2) %s = %s1[3 .. 5]; //a slice from pos 3 to 5 (both inclusive)
suffix(s1, s2)	If s1 is a string, it has the string s2 suffixed (appended) Returns: string	%s1 = %s2.suffix('a');
upper(s)	The string s with upper-case letters. Returns: string (works for list of strings, too)	%s = upper('aBcD'); Result: 'ABCD'.
upperFirst(s)	The string s with upper-case first letter. Returns: string (works for list of strings, too)	%s = upperFirst('abcd'); Result: 'Abcd'.

In addition, there are some functions that fetch different kinds of meta-data (as strings) from the system or databanks, see under functions.

Examples

Concatenation:

%s1 = 'ab';
%s2 = 'cd';
%s3 = %s1 + %s2; //result: 'abcd'

You may wish to use strings to control file names.

%path = 'folderA' ;
%bank = 'prognosis' ;
read c:\{%path}\{%bank};

As mentioned above, Gekko supports string interpolation using {}-curlies. For instance:

%s1 = 'b';
%s2 = 'a' + %s1 + 'c'; //result: 'abc'
%s3 = 'a{%s1}c'; //result: 'abc', easier to type and read

In general, in such cases, it is better and more readable to use {}-curlies, instead of concatenating with +. Using {}-curlies both for name-composition (like a{%s1}b) and string substitution (like 'a{%s1}b') makes it easy to move composed names in and out of strings, because the syntax is the same.

The tilde (~) can be used to avoid in-substitution of {}-curlies. Tilde can also be used to allow single quotes inside a string:

%s1 = 'blue';
%s2 = 'the' + %s1 + 'car';   //result: 'the blue car'
%s3 = 'the {%s1} car';     //result: 'the blue car'
%s4 = 'the ~{%s1} car';   //result: 'the {%s1} car'
%s5 = 'the ~'blue~' car';   //result: 'the 'blue' car'

You may put any valid Gekko expression inside the {}-braces, as long as it can be evaluated to a string:

time 2020 2022;
x = 55000000;
%date = 2021;
%s1 = 'value in {%date} is {x[%date]/1e6} M'; //result: 'value in 2021 is 55 M'
%s2 = 'value in ' + %date + ' is ' + x[%date]/1e6 + ' M'; //same, but more cumbersome to write and read

Strings are often used in loops, to loop over variables, see FOR.

If you need to convert a string to a date or value, you must convert it explicitly with the date() and val() conversion functions, for instance:

%s1 = '2010';
%s2 = '123.45';
%d = date(%s1);
%v = val(%s1);

Note: whole lists of strings can be converted into lists of dates or values with the dates() and vals() functions.

TELL examples

Below are some examples regarding the use of strings in the TELL statement (TELL prints the string on the screen):

%s1 = 'Value in ';
%d1 = 2010;
%s2 = ' is: ';
%v1 = 113.45;
%v2 = 10;
%s3 = %s1 + %d1 + %s2 + (%v1 + %v2);
tell %s3;
tell 'Value in ' + %d1 + ' is: ' + (%v1 + %v2);
tell 'Value in {%d1} is: {%v1 + %v2}';

This will print Value in 2010 is: 123.45 three times, so the three last TELLs are equivalent. When adding the scalars, it should be noted that scalar dates and scalar values are automatically converted to strings when added to a string with the + operator. So there is no need to use %s3 = %s1 + string(%d1) + %s2 + string(%v1);.

If you need to write curly braces like {%d1} literally, preprend the symbol ~ to indicate that Gekko should not try to in-substitute. For example:

tell 'The scalar name is ~{%d1}';

This will print 'The scalar name is {%d1}' on the screen, and not try to evaluate the inside of the {}-curlies. If you need to format values, you can either use the format() function, or use global formatting of {}-curlies via option string interpolate format val = ... . For instance. See more regarding format() function in the Gekko functions section (the code '6:0.00' means a 6 character wide field, where the number has exactly two decimals).

%v11 = 1/3; %v12 = 1/4; %v21 = 1/5; %v22 = 1/6;
tell '{format(%v11, '6:0.00')},{format(%v12, '6:0.00')}';
tell '{format(%v21, '6:0.00')},{format(%v22, '6:0.00')}';
//since the formatting is the same, you can use an option:
option string interpolate format val = '6:0.00';
tell '{%v11},{%v12}';
tell '{%v21},{%v22}';

// result:
// 0.33, 0.25
// 0.20, 0.17

Notes

See the page with syntax diagrams if the basics of names, expressions, etc. is confusing.

If you need to convert a VAL or DATE scalar to a string type, use the string() conversion function.

See also the format() function and OPTION string interpolate format val = ... ; regarding {...}-formatting of values inside strings.

Regarding variable types and the Gekko type system, see the VAR section. In this appendix, variable assignment rules, including variable types, is explained in more detail.

Related options

OPTION string interpolate format val = '';

Related functions

format(), readFile(), writeFile()

Related statements

DATE, FOR, LIST, MEM, VAL

STRING