5.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.

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(pair z, pair w)

returns the dot product z.x*w.x+z.y*w.y;

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, see section 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;

string format(string s, int n)

returns a string containing n formatted according to the C-style format string s using the current locale;

string format(string s, 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 TeX is used to typeset scientific notation;

int hex(string s);

casts a hexidecimal string s to an integer.

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);

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 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).