The POV-Ray language requires you to specify a string of characters to be used as a file name, text for messages or text for a text object. Strings may be specified using literals, identifiers or functions which return string values. See "String Functions" for details on string functions. Although you cannot build string expressions from symbolic operators such as are used with floats, vectors or colors, you may perform various string operations using string functions. Some applications of strings in POV-Ray allow for non-printing formatting characters such as newline or form-feed.
" "
str( , INT , INT ) | concat( STRING , STRING , [STRING ,...]) | chr( INT ) |
substr( , INT , INT ) | strupr( STRING ) | strlwr( STRING )
String literals begin with a double quote mark '"' which is followed by up to 256 printable ASCII characters and are terminated by another double quote mark. The following are all valid string literals:
"Here" "There" "myfile.gif" "textures.inc"
Note if you need to specify a quote mark in a string literal you must precede it with a backslash. For example
"Joe said \"Hello\" as he walked in."
is converted to
Joe said "Hello" as he walked in.
If you need to specify a backslash, most of the time you need do nothing special. However if the string ends in a backslash, you will have to specify two. For example:
"This is a backslash \ and so is this\\"
Is converted to:
This is a backslash \ and so is this\
The substitution of \" with a " occurs in all POV-Ray string literals regardless usage however other formatting codes such as \n for new line are only supported in user message streams. See "Text Formatting" for details.
String identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows.
#declare = STRING |
#local = STRING
Where IDENTIFIER is the name of the identifier up to 40 characters long and STRING is any valid string specification. Note that unlike floats, vectors, or colors, there need not be a semi-colon at the end of the declaration. See "#declare vs. #local" for information on identifier scope. Here are some examples...
#declare Font_Name = "ariel.ttf" #declare Inc_File = "myfile.inc" #declare Name = "John" #declare Name = concat(Name," Doe")
As the last example shows, you can re-declare a string identifier and may use previously declared values in that re-declaration.
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)
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,...)
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):
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)
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)
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)
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.