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
(see the example in Functions).