Topic: Programming
Online Help
Strings (Pro only)
This feature is available only in Calcpad VM Pro 8.
Besides numbers, Calcpad can work with text values, called strings. A string is enclosed in double quotes, e.g. "text". To include a double quote in a string, type it twice: "say ""hi""" gives say "hi". Strings can contain any characters, including separators like "|", ":" and ";", which are not treated as operators inside the quotes. A string must end on the same line where it starts. Otherwise, the program will report a missing closing quote. Do not confuse strings with comments, which are enclosed in single quotes and are not part of the calculations.
String variables
You can assign a string to a variable and use it further in expressions and function calls:
s = "Hello"t = join(left(s; 1); "."; mid(s; 2; 4))ucase(t) = "H.ELLO"
String results are displayed in quotes, e.g. s = left("Hello"; 2) = "He", except in #val mode, where only the text itself is shown. The text is always displayed as it is. If it contains Html tags, they are not interpreted, but displayed as text. Custom functions can also accept strings as arguments and return strings, e.g. f(s) = ucase(s).
String functions
str(x)- converts x to text, as it is displayed in the output, including the units;val(s)- converts the text s to a number with optional units, e.g.val("1.5 kN/m^2");val(M)- converts the string elements of a vector or matrix to numbers;len(s)- number of characters;join(s1; s2; s3…)- joins texts and values into a single text;join(M; colsep; rowsep)- joins the elements of a vector or matrix into a text;left(s; n),right(s; n),mid(s; i; n)- parts of the text;trim(s),ltrim(s),rtrim(s)- remove leading and/or trailing spaces;ucase(s),lcase(s),tcase(s),scase(s)- upper, lower, title and sentence case;instr(s; t; i)- position of t in s, starting from i, or 0 if t is not found;replace(s; a; b)- replaces all occurrences of a with b;split(s; sep)- splits a text into a vector of strings;split(s; colsep; rowsep)- splits a text into a matrix of strings;table(M; nhrows; nhcols)- displays a matrix as a table (see "Tables").
Their main features are:
- Arguments that are expected to be text, but are not, are converted by str first. For example,
left(12345; 3) = "123". The str function formats numbers as they are displayed in the output, including units, e.g.str(2m) = "2 m"; - Positions are counted from 1. The positions and the numbers of characters must be integers, otherwise an error is returned. The third argument of instr is optional (1 by default);
- join joins texts if at least one of its arguments is text. Otherwise, it joins vectors. For example,
join("x = "; 1.5; " m") = "x = 1.5 m", butjoin(1; 2; 3) = [1 2 3]. With a string separator, join joins the elements of a vector or matrix into a single text:join(v; ", ")orjoin(M; ", "; "; "); - split works in the opposite way. It splits a text into a vector of strings, e.g.
split("a, 2, 3"; ", ") = ["a" "2" "3"], or into a matrix of strings, if you specify both column and row separators; - val converts a text to a number. The text can include units, e.g.
val("1.5 kN/m^2"), and must use a decimal point, regardless of the regional settings. It returns 0 for a blank text and an error if the text is not a valid number. Applied to a vector or matrix, val converts all string elements to numbers, e.g.val(split("1, 2.5, 3e2"; ", ")) = [1 2.5 300]; - ucase, lcase, tcase and scase work with all Unicode letters. tcase capitalizes the first letter of each word and scase - of each sentence, while the other letters are converted to lower case.
Strings and operators
Only two kinds of operators work with strings: "+" and the relational (comparison) operators. The "+" operator concatenates two strings into one, e.g. "Hello" + ", " + "world" = "Hello, world".
The relational operators "≡", "≠", "<", ">", "≤" and "≥" compare strings character by character, by their Unicode codes. They return 1 if the condition is satisfied and 0 otherwise, as for numbers. The comparison is case sensitive, so "abc" ≡ "Abc" returns 0. Capital letters come before small ones, e.g. "B" < "a", and Latin letters come before Cyrillic. Digits are compared as characters, not as numbers, so "10" < "9" returns 1. If one string matches the beginning of a longer one, the shorter string is smaller: "ab" < "abc". Spaces are not ignored: "a " ≡ "a" returns 0. You can use trim, lcase or ucase to compare strings regardless of spaces and case.
As addition, concatenation has higher precedence than comparison, so "a" + "b" ≡ "ab" returns 1. Since comparisons return numbers, you can use them in conditions, logical expressions and solver blocks, as well as inside custom functions, e.g.:
f(s) = if(s ≡ ""; "empty"; s + "!")#if s ≡ "a"n = $Sum{v.k ≡ "a" @ k = 1 : 3}
Both operands must be strings. The other operators, like "-", "*", "/", "^" and the logical ones, are not defined for strings, and a string cannot be added to or compared with a number. For example, "12" + 1 and "2" ≡ 2 will return errors. To include a number in a text, convert it by str or use join: "L = " + str(2m) = "L = 2 m". If a string contains a number, you have to convert it by val to use it in calculations: val("12") + 1 = 13. Most math functions, like sqrt, sin, max or sum, also do not accept strings.
Strings in vectors and matrices
Vectors and matrices can contain strings, numbers and values with units, mixed together, e.g. b = [1; "abc"; 2m]. You can access and assign string elements by index (b.2, M.(i; j)), fill vectors and matrices with strings, and use the structural functions, like slice, extract, first, last, reverse, take, row, col, transp, augment and stack, as well as the lookup functions. In this way, you can build tables with text and numerical columns. The data functions for sorting, ordering, searching, counting and lookup, like sort, rsort, order, revorder, search, count, find, lookup, sort_rows, order_rows, mcount, msearch, mfind, hlookup and vlookup, also work with strings. Strings are compared by Unicode code, case sensitive, as with the "<" and "≡" operators, e.g. sort(["b"; "a"; "c"]) = ["a" "b" "c"]. A string cannot be compared with a number, so the compared elements must be either all strings or all numbers. You can search in one vector and return the values from another: lookup(names; values; "B2"). However, math operations other than "+" and comparison, and other functions that require numerical values, like summing and norms, return an error if any of the elements is a string. High performance (hp) vectors and matrices cannot contain strings. The functions setunits and clrunits skip the string elements and leave them unchanged.
The "+" and relational operators work element-wise on vectors and matrices with string elements. A single string is applied to each element and keeps its place, because concatenation is not commutative. For example, if v = ["a"; "b"], then v + "!" = ["a!" "b!"] and "<" + v = ["<a" "<b"]. Two vectors or matrices of the same size are combined element by element, e.g. ["a"; "b"] + ["x"; "y"] = ["ax" "by"]. Comparisons return vectors or matrices of ones and zeros, e.g. v ≡ "a" = [1 0], so sum(v ≡ "a") counts the elements that are equal to "a". The corresponding elements must be both strings or both numbers. Numbers are added and compared as usual, e.g. ["a"; 1] + ["b"; 2] = ["ab" 3], but a string and a number at the same position return an error. Since hp vectors and matrices contain only numbers, they cannot be combined with strings.
The str function converts a whole vector or matrix to a text without quotes, e.g. str(["a"; "2"; 3]) = "[a 2 3]". A vector of strings is also used to specify the labels along the category axis of data charts (see "Data charts").
Strings in input forms
You can enter a string in an input field, by including it in double quotes, e.g. s = ?{"abc"}. A question mark inside a string is treated as a regular character and does not create an input field.