Reference:Strings
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.
STRING: STRING_FUNCTION | STRING_IDENTIFIER | STRING_LITERAL STRING_LITERAL: "up to 256 ASCII characters" STRING_REL_TERM: STRING_LITERAL [STRING_REL_OPERATOR STRING_LITERAL]... STRING_REL_OPERATOR: < | <= | = | >= | > | != STRING_FUNCTION: str( FLOAT , INT , INT ) | concat( STRING , STRING , [STRING ,...]) | chr( INT ) | substr( STRING , INT , INT ) | strupr( STRING ) | strlwr( STRING ) | vstr( INT, VECTOR, STRING, INT, INT )
String Literals
String literals begin with a double quote mark '"' which is followed by up to 256 characters and are terminated by another double quote mark. You can change the character set of strings using the global_settings charset option. 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.
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, you will have to specify two. For example:
"This is a backslash \\ and this is two \\\\"
Is converted to:
This is a backslash \ and this is two \\
Windows users need to be especially wary about this as the backslash is also the windows path separator. For example, the following code does not produce the intended result:
#declare DisplayFont = "c:\windows\fonts\lucon.ttf"
text { ttf DisplayFont "Hello", 2,0 translate y*1.50 }
New users might expect this to create a text object using the font c:\windows\fonts\lucon.ttf. Instead, it will give an error message saying that it cannot find the font file c:windowsontslucon.ttf.
The correct form of the above code is as follows:
#declare DisplayFont = "c:\\windows\\fonts\\lucon.ttf"
text { ttf DisplayFont "Hello", 2,0 translate y*1.50 }
However, as POV-Ray for Windows also supports forward slashes as path separator, it is recommended to use the following form:
#declare DisplayFont = "c:/windows/fonts/lucon.ttf"
text { ttf DisplayFont "Hello", 2,0 translate y*1.50 }
The escaping of backslashes occurs in all POV-Ray string literals. There are also
other formatting codes such as \n for new line.
See Text Formatting for details.
Note: Up to (and including) version 3.7.0, contrary to the documentation (and on all platforms) backslashes lost their special meaning where a file name is expected, except when preceding a double quote. For backward compatibility, this behaviour is still retained for scenes specifying a #version of 3.70 or lower, but a warning will be issued.
String Identifiers
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.
STRING_DECLARATION: #declare IDENTIFIER = STRING | #local IDENTIFIER = STRING
Where IDENTIFIER is a valid identifier name and STRING is any valid string specification.
Note: Unlike floats, vectors, or colors, there need not be a semi-colon at the end of the declaration.
See also: Identifiers and #declare vs. #local for additional information on identifier naming and 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.
String Relational Operators
POV-Ray supports the following string relational operators: < <= = >= > != and are subject to standard ASCII collating sequence rules.
Note: These relational operators are nothing more than a shortcut as they are an equivalent to calling the strcmp() function.
For example:
#if (string1 = string2)
#declare Color = pigment {rgb <0, 1, 0>};
#else
#declare Color = pigment {rgb <1, 0, 0>};
#end
Is the same as:
#if (strcmp(string1, string2) = 0)
#declare Color = pigment {rgb <0, 1, 0>};
#else
#declare Color = pigment {rgb <1, 0, 0>};
#end
This simple example shows just one usage:
// perspective (default) camera
camera {
location <0.0, 2.0, -5.0>
look_at <0.0, 0.0, 0.0>
right x*image_width/image_height
}
// create a regular point light source
light_source {
0*x // light's position (translated below)
color rgb <1,1,1> // light's color
translate <0, 20, -20>
}
background {rgb 1}
#declare TestCase = "ABC";
#if (TestCase < "ABD")
#declare Color = pigment {rgb <0, 1, 0>};
#else
#declare Color = pigment {rgb <1, 0, 0>};
#end
sphere {0,1 pigment {Color}}
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 character value is
B. Returns a single character string. The character value of the
character is specified by an integer B which must be in the
range 0 to 65535 if you specified charset utf8 in the
global_settings and 0 to 127 if you specified charset
ascii. Refer to your platform specific documentation if you specified
charset sys. For example chr(70) is the string
"F". When rendering text objects you should be aware that the
characters rendered are dependent on the (TTF) font being used.
concat(S1,S2,...) concatenates 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.
datetime() Can be used to return the string representation of a date and time. It's syntax is:
datetime(FLOAT [,STRING])
where FLOAT is the time elapsed since 2000-01-01, 00:00:00 GMT in days. Note that this fits with the now keyword, so the following example will give you a string representation of the current date and time:
datetime(now)
The optional STRING parameter should conform to the same formatting as that of the strftime() C function.
The default for the STRING parameter format is %Y-%m-%d %H:%M:%SZ
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
"DE". If P+L-1>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!".
vstr(N,A,S,L,P) Convert vector A to a formatted string. Returns a
formatted string representation of vector A where the elements of
the vector are separated by the string parameter S. The integer
parameter N specifies the amount of dimensions in vector A.
N is autoclipped to the range of 2 to 5, without warning. Specifying a
vector A with more dimensions than given by N will result
in an error.
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. 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. The function of L and P is the
same as in str. Here are some examples:
vstr(2, <1,2>, ", ", 0,1) "1.0, 2.0" vstr(5, <1,2,3,4,5>, ", ", 0,1) "1.0, 2.0, 3.0, 4.0, 5.0" vstr(1, 1, ", ", 0,1) "1.0, 1.0" vstr(2, 1, ", ", 0,1) "1.0, 1.0" vstr(5, 1, ", ", 0,1) "1.0, 1.0, 1.0, 1.0, 1.0" vstr(7, 1, ", ", 0,1) "1.0, 1.0, 1.0, 1.0, 1.0" vstr(3, <1,2>, ", ", 0,1) "1.0, 2.0, 0.0" vstr(5, <1,2,3>, ", ", 0,1) "1.0, 2.0, 3.0, 0.0, 0.0" vstr(3, <1,2,3,4>, ", ", 0,1) error
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
#macro directive. See the section
User Defined Macros for more details.
Built-in Variables
At the moment there is only one built-in string variable. You can use it to specify values or to create expressions but you cannot re-declare it to change it's value.
File-related are:
STRING_BUILT-IN_IDENT: input_file_name
input_file_name
The name of the scene input file.