Previous:String Identifiers Main Index Next:Array Identifiers

#### String Functions

POV-Ray defines a variety of built-in functions for manipulating floats, vectors and strings. Function calls consist of a keyword which specifies the name of the function followed by a parameter list enclosed in parentheses. Parameters are separated by commas. For example:

     keyword(param1,param2)

The following are the functions which return string values. They take one or more float, integer, vector, or string parameters. Assume that `A` is any valid expression that evaluates to a float; `B`, `L`, and `P` are floats which are truncated to integers internally, `S`, `S1`, `S2` etc are strings.

`chr(B)` Character whose ASCII value is `B`. Returns a single character string. The ASCII value of the character is specified by an integer `B` which must be in the range 0 to 255. For example `chr(70)` is the string "F". When rendering text objects you should be aware that the characters rendered for values of B > 127 are dependent on the (TTF) font being used. Many (TTF) fonts use the Latin-1 (ISO 8859-1) character set, but not all do.

`concat(S1,S2,...)` Concatenate strings `S1` and `S2`. Returns a string that is the concatenation of all parameter strings. Must have at least 2 parameters but may have more. For example:

     concat("Value is ", str(A,3,1), " inches")

If the float value `A` was `12.34321` the result is `"Value is 12.3 inches"` which is a string.

`str(A,L,P):` Convert float A to a formatted string. Returns a formatted string representation of float value `A`. The integer parameter `L` specifies the minimum length of the string and the type of left padding used if the string's representation is shorter than the minimum. If `L` is positive then the padding is with blanks. If `L` is negative then the padding is with zeros. The overall minimum length of the formatted string is abs(L). If the string needs to be longer, it will be made as long as necessary to represent the value.

The integer parameter `P` specifies the number of digits after the decimal point. If `P` is negative then a compiler-specific default precision is use. Here are some examples:

str(123.456,0,3) "123.456"

str(123.456,4,3) "123.456"

str(123.456,9,3) " 123.456"

str(123.456,-9,3) "00123.456"

str(123.456,0,2) "123.46"

str(123.456,0,0) "123"

str(123.456,5,0) " 123"

str(123.000,7,2) " 123.00"

str(123.456,0,-1) "123.456000" (platform specific)

`strlwr(S)` Lower case of `S`. Returns a new string in which all upper case letters in the string S1 are converted to lower case. The original string is not affected. For example `strlwr("Hello There!")` results in "hello there!".

`substr(S,P,L)` Sub-string from `S`. Returns a string that is a subset of the characters in parameter `S` starting at the position specified by the integer value `P` for a length specified by the integer value `L`. For example `substr("ABCDEFGHI",4,2)` evaluates to the string "EF". If P+L>strlen(S) an error occurs.

`strupr(S)` Upper case of `S`. Returns a new string in which all lower case letters in the string `S` are converted to upper case. The original string is not affected. For example `strupr("Hello There!")` results in "HELLO THERE!".

See section "Float Functions" for other functions which are somewhat string-related but which return floats. In addition to the above built-in functions, you may also define your own functions using the new `#macro` directive. See the section "User Defined Macros" for more details.

Previous:String Identifiers Main Index Next:Array Identifiers