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).
The function abs2(pair z) returns |z|^2;
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 its argument v.
A synonym for length(triple) is abs(triple).
The function abs2(triple v) returns |v|^2;
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, see babel):
Strings delimited by single quotes (') have the same mappings as
character strings in ANSI C:
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[] array(string s) ¶returns an array of strings obtained by splitting s into
individual characters. The inverse operation is provided by
operator +(...string[] a).
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 behavior of the C function
fprintf), except that only one data field is allowed.
string format(string s=defaultformat, bool forcemath=false, 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 behavior of the C function
fprintf), except that only one data field is allowed, trailing
zeros are removed by default (unless # is specified), and
if s specifies math mode or forcemath=true, TeX is
used to typeset scientific notation using the
defaultseparator="\!\times\!";;
int hex(string s); ¶casts a hexadecimal 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
or using. For instance, the line
using multipath = path[];
will make multipath a type equivalent path[], as will
the equivalent line
typedef path[] multipath;
For the most part such type aliasing is a convenience. However, it is required when declaring a function whose return type is a function (see the example in Functions).