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 an arbitrary number of 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 the name of the identifier up to 40 characters long 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 #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.

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 date and time. It's syntax is:

datetime(FLOAT [,STRING])

when FLOAT uses the keyword now it will return a string which evaluates to the time elapsed since 2000-01-01, 00:00:00 GMT in days, with a precision of seconds or better. For example:

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.