|
 |
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.
2.2.1.7.2 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.
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,...) 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.
More about "global_settings"
More about "#macro"
|
|
