|
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_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 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 }
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.
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.
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 plafform 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,...) 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
"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.
|