asymptote: Data types
6.1 Data types
==============
'Asymptote' supports the following data types (in addition to
user-defined types):
'void'
The void type is used only by functions that take or return no
arguments.
'bool'
a boolean type that can only take on the values 'true' or 'false'.
For example:
bool b=true;
defines a boolean variable 'b' and initializes it to the value
'true'. If no initializer is given:
bool b;
the value 'false' is assumed.
'bool3'
an extended boolean type that can take on the values 'true',
'default', or 'false'. A bool3 type can be cast to or from a bool.
The default initializer for bool3 is 'default'.
'int'
an integer type; if no initializer is given, the implicit value '0'
is assumed. The minimum allowed value of an integer is 'intMin'
and the maximum value is 'intMax'.
'real'
a real number; this should be set to the highest-precision native
floating-point type on the architecture. The implicit initializer
for reals is '0.0'. Real numbers have precision 'realEpsilon',
with 'realDigits' significant digits. The smallest positive real
number is 'realMin' and the largest positive real number is
'realMax'. The variables 'inf' and 'nan', along with the function
'bool isnan(real x)' are useful when floating-point exceptions are
masked with the '-mask' command-line option (the default in
interactive mode).
'pair'
complex number, that is, an ordered pair of real components
'(x,y)'. The real and imaginary parts of a pair 'z' can read as
'z.x' and 'z.y'. We say that 'x' and 'y' are virtual members of
the data element pair; they cannot be directly modified, however.
The implicit initializer for pairs is '(0.0,0.0)'.
There are a number of ways to take the complex conjugate of a pair:
pair z=(3,4);
z=(z.x,-z.y);
z=z.x-I*z.y;
z=conj(z);
Here 'I' is the pair '(0,1)'. A number of built-in functions are
defined for pairs:
'pair conj(pair z)'
returns the conjugate of 'z';
'real length(pair z)'
returns the complex modulus '|z|' of its argument 'z'. For
example,
pair z=(3,4);
length(z);
returns the result 5. A synonym for 'length(pair)' is
'abs(pair)';
'real angle(pair z, bool warn=true)'
returns the angle of 'z' in radians in the interval
[-'pi','pi'] or '0' if 'warn' is 'false' and 'z=(0,0)' (rather
than producing an error);
'real degrees(pair z, bool warn=true)'
returns the angle of 'z' in degrees in the interval [0,360) or
'0' if 'warn' is 'false' and 'z=(0,0)' (rather than producing
an error);
'pair unit(pair z)'
returns a unit vector in the direction of the pair 'z';
'pair expi(real angle)'
returns a unit vector in the direction 'angle' measured in
radians;
'pair dir(real degrees)'
returns a unit vector in the direction 'degrees' measured in
degrees;
'real xpart(pair z)'
returns 'z.x';
'real ypart(pair z)'
returns 'z.y';
'pair realmult(pair z, pair w)'
returns the element-by-element product '(z.x*w.x,z.y*w.y)';
'real dot(explicit pair z, explicit pair w)'
returns the dot product 'z.x*w.x+z.y*w.y';
'real cross(explicit pair z, explicit pair w)'
returns the 2D scalar product 'z.x*w.y-z.y*w.x';
'real orient(pair a, pair b, pair c);'
returns a positive (negative) value if 'a--b--c--cycle' is
oriented counterclockwise (clockwise) or zero if all three
points are colinear. Equivalently, a positive (negative)
value is returned if 'c' lies to the left (right) of the line
through 'a' and 'b' or zero if 'c' lies on this line. The
value returned can be expressed in terms of the 2D scalar
cross product as 'cross(a-c,b-c)', which is the determinant
|a.x a.y 1|
|b.x b.y 1|
|c.x c.y 1|
'real incircle(pair a, pair b, pair c, pair d);'
returns a positive (negative) value if 'd' lies inside
(outside) the circle passing through the
counterclockwise-oriented points 'a,b,c' or zero if 'd' lies
on the this circle. The value returned is the determinant
|a.x a.y a.x^2+a.y^2 1|
|b.x b.y b.x^2+b.y^2 1|
|c.x c.y c.x^2+c.y^2 1|
|d.x d.y d.x^2+d.y^2 1|
'pair minbound(pair z, pair w)'
returns '(min(z.x,w.x),min(z.y,w.y))';
'pair maxbound(pair z, pair w)'
returns '(max(z.x,w.x),max(z.y,w.y))'.
'triple'
an ordered triple of real components '(x,y,z)' used for
three-dimensional drawings. The respective components of a triple
'v' can read as 'v.x', 'v.y', and 'v.z'. The implicit initializer
for triples is '(0.0,0.0,0.0)'.
Here are the built-in functions for triples:
'real length(triple v)'
returns the length '|v|' of the vector 'v'. A synonym for
'length(triple)' is 'abs(triple)';
'real polar(triple v, bool warn=true)'
returns the colatitude of 'v' measured from the z axis in
radians or '0' if 'warn' is 'false' and 'v=O' (rather than
producing an error);
'real azimuth(triple v, bool warn=true)'
returns the longitude of 'v' measured from the x axis in
radians or '0' if 'warn' is 'false' and 'v.x=v.y=0' (rather
than producing an error);
'real colatitude(triple v, bool warn=true)'
returns the colatitude of 'v' measured from the z axis in
degrees or '0' if 'warn' is 'false' and 'v=O' (rather than
producing an error);
'real latitude(triple v, bool warn=true)'
returns the latitude of 'v' measured from the xy plane in
degrees or '0' if 'warn' is 'false' and 'v=O' (rather than
producing an error);
'real longitude(triple v, bool warn=true)'
returns the longitude of 'v' measured from the x axis in
degrees or '0' if 'warn' is 'false' and 'v.x=v.y=0' (rather
than producing an error);
'triple unit(triple v)'
returns a unit triple in the direction of the triple 'v';
'triple expi(real polar, real azimuth)'
returns a unit triple in the direction '(polar,azimuth)'
measured in radians;
'triple dir(real colatitude, real longitude)'
returns a unit triple in the direction
'(colatitude,longitude)' measured in degrees;
'real xpart(triple v)'
returns 'v.x';
'real ypart(triple v)'
returns 'v.y';
'real zpart(triple v)'
returns 'v.z';
'real dot(triple u, triple v)'
returns the dot product 'u.x*v.x+u.y*v.y+u.z*v.z';
'triple cross(triple u, triple v)'
returns the cross product
'(u.y*v.z-u.z*v.y,u.z*v.x-u.x*v.z,u.x*v.y-v.x*u.y)';
'triple minbound(triple u, triple v)'
returns '(min(u.x,v.x),min(u.y,v.y),min(u.z,v.z))';
'triple maxbound(triple u, triple v)'
returns '(max(u.x,v.x),max(u.y,v.y),max(u.z,v.z)').
'string'
a character string, implemented using the STL 'string' class.
Strings delimited by double quotes ('"') are subject to the
following mappings to allow the use of double quotes in TeX
(e.g. for using the 'babel' package, 
babel):
* \" maps to "
* \\ maps to \\
Strings delimited by single quotes (''') have the same mappings as
character strings in ANSI 'C':
* \' maps to '
* \" maps to "
* \? maps to ?
* \\ maps to backslash
* \a maps to alert
* \b maps to backspace
* \f maps to form feed
* \n maps to newline
* \r maps to carriage return
* \t maps to tab
* \v maps to vertical tab
* \0-\377 map to corresponding octal byte
* \x0-\xFF map to corresponding hexadecimal byte
The implicit initializer for strings is the empty string '""'.
Strings may be concatenated with the '+' operator. In the
following string functions, position '0' denotes the start of the
string:
'int length(string s)'
returns the length of the string 's';
'int find(string s, string t, int pos=0)'
returns the position of the first occurrence of string 't' in
string 's' at or after position 'pos', or -1 if 't' is not a
substring of 's';
'int rfind(string s, string t, int pos=-1)'
returns the position of the last occurrence of string 't' in
string 's' at or before position 'pos' (if 'pos'=-1, at the
end of the string 's'), or -1 if 't' is not a substring of
's';
'string insert(string s, int pos, string t)'
returns the string formed by inserting string 't' at position
'pos' in 's';
'string erase(string s, int pos, int n)'
returns the string formed by erasing the string of length 'n'
(if 'n'=-1, to the end of the string 's') at position 'pos' in
's';
'string substr(string s, int pos, int n=-1)'
returns the substring of 's' starting at position 'pos' and of
length 'n' (if 'n'=-1, until the end of the string 's');
'string reverse(string s)'
returns the string formed by reversing string 's';
'string replace(string s, string before, string after)'
returns a string with all occurrences of the string 'before'
in the string 's' changed to the string 'after';
'string replace(string s, string[][] table)'
returns a string constructed by translating in string 's' all
occurrences of the string 'before' in an array 'table' of
string pairs {'before','after'} to the corresponding string
'after';
'string[] split(string s, string delimiter="")'
returns an array of strings obtained by splitting 's' into
substrings delimited by 'delimiter' (an empty delimiter
signifies a space, but with duplicate delimiters discarded);
'string format(string s, int n, string locale="")'
returns a string containing 'n' formatted according to the
C-style format string 's' using locale 'locale' (or the
current locale if an empty string is specified), following the
behaviour of the C function 'fprintf'), except that only one
data field is allowed.
'string format(string s=defaultformat, string s=defaultseparator, real x, string locale="")'
returns a string containing 'x' formatted according to the
C-style format string 's' using locale 'locale' (or the
current locale if an empty string is specified), following the
behaviour of the C function 'fprintf'), except that only one
data field is allowed, trailing zeros are removed by default
(unless '#' is specified), and (if the format string specifies
math mode) TeX is used to typeset scientific notation using
the 'defaultseparator="\!\times\!";';
'int hex(string s);'
casts a hexidecimal string 's' to an integer;
'int ascii(string s);'
returns the ASCII code for the first character of string 's';
'string string(real x, int digits=realDigits)'
casts 'x' to a string using precision 'digits' and the C
locale;
'string locale(string s="")'
sets the locale to the given string, if nonempty, and returns
the current locale;
'string time(string format="%a %b %d %T %Z %Y")'
returns the current time formatted by the ANSI C routine
'strftime' according to the string 'format' using the current
locale. Thus
time();
time("%a %b %d %H:%M:%S %Z %Y");
are equivalent ways of returning the current time in the
default format used by the 'UNIX' 'date' command;
'int seconds(string t="", string format="")'
returns the time measured in seconds after the Epoch (Thu Jan
01 00:00:00 UTC 1970) as determined by the ANSI C routine
'strptime' according to the string 'format' using the current
locale, or the current time if 't' is the empty string. Note
that the '"%Z"' extension to the POSIX 'strptime'
specification is ignored by the current GNU C Library. If an
error occurs, the value -1 is returned. Here are some
examples:
seconds("Mar 02 11:12:36 AM PST 2007","%b %d %r PST %Y");
seconds(time("%b %d %r %z %Y"),"%b %d %r %z %Y");
seconds(time("%b %d %r %Z %Y"),"%b %d %r "+time("%Z")+" %Y");
1+(seconds()-seconds("Jan 1","%b %d"))/(24*60*60);
The last example returns today's ordinal date, measured from
the beginning of the year.
'string time(int seconds, string format="%a %b %d %T %Z %Y")'
returns the time corresponding to 'seconds' seconds after the
Epoch (Thu Jan 01 00:00:00 UTC 1970) formatted by the ANSI C
routine 'strftime' according to the string 'format' using the
current locale. For example, to return the date corresponding
to 24 hours ago:
time(seconds()-24*60*60);
'int system(string s)'
'int system(string[] s)'
if the setting 'safe' is false, call the arbitrary system
command 's';
'void asy(string format, bool overwrite=false ... string[] s)'
conditionally process each file name in array 's' in a new
environment, using format 'format', overwriting the output
file only if 'overwrite' is true;
'void abort(string s="")'
aborts execution (with a non-zero return code in batch mode);
if string 's' is nonempty, a diagnostic message constructed
from the source file, line number, and 's' is printed;
'void assert(bool b, string s="")'
aborts execution with an error message constructed from 's' if
'b=false';
'void exit()'
exits (with a zero error return code in batch mode);
'void sleep(int seconds)'
pauses for the given number of seconds;
'void usleep(int microseconds)'
pauses for the given number of microseconds;
'void beep()'
produces a beep on the console;
As in C/C++, complicated types may be abbreviated with 'typedef' (see
the example in Functions).
Info Catalog
asymptote: Programming
asymptote: Programming
asymptote: Paths and guides