ChucK

Standard Libraries

Standard Libraries API

ChucK Standard Libraries API these libraries are provide by default with ChucK - new ones can also be imported with ChucK dynamic linking (soon to be documented...). The existing libraries are organized by namespaces in ChucK. They are as follows.

Std

Std is a standard library in ChucK, which includes utility functions, random number generation, unit conversions and absolute value.

/* a simple example... */
// infinite time-loop
while( true )
{
    // generate random float (and print)
    Std.rand2f( 100.0, 1000.0 )
    // wait a bit
    50::ms =>now;
}

[function] int abs ( int value ) - returns absolute value of integer

[function] float fabs ( float value ) - returns absolute value of floating point number

[function] int rand ( ) - generates random integer
[function] int rand2 ( int min, int max ) - generates random integer in the range [min, max]
[function] float randf ( ) - generates random floating point number in the range [-1, 1]
[function] float rand2f ( float min, float max ) - generates random floating point number in the range [min, max]
[function] float srand (int value) - seeds value for random number generation
[function] float sgn ( float value ) - computes the sign of the input as -1.0 (negative), 0 (zero), or 1.0 (positive)
[function] int system ( string cmd ) - pass a command to be executed in the shell
[function] int atoi ( string value ) - converts ascii (string) to integer (int)
[function] float atof ( string value ) - converts ascii (string) to floating point value (float)
[function] string getenv ( string value ) - returns the value of an environment variable, such as of "PATH"
[function] int setenv ( string key, string value ) - sets environment variable named 'key' to 'value
[function] float mtof ( float value ) - converts a MIDI note number to frequency (Hz) note the input value is of type 'float' (supports fractional note number)
[function] float ftom ( float value ) - converts frequency (Hz) to MIDI note number space
[function] float powtodb ( float value ) - converts signal power ratio to decibels (dB)
[function] float rmstodb ( float value ) - converts linear amplitude to decibels (dB)
[function] float dbtopow ( float value ) - converts decibels (dB) to signal power ratio
[function] float dbtorms ( float value ) - converts decibles (dB) to linear amplitude

Machine

Machine is ChucK runtime interface to the virtual machine. this interface can be used to manage shreds. They are similar to the On-the-fly Programming Commands, except these are invoked from within a ChucK program, and are subject to the timing mechanism.

//add a file foo.ck to the VM machine.add("foo.ck");
//check the virtual machine like using 'chuck ^' on the command line
machine.status();
//wait a week and cause ChucK to crash
1::week => now;
machine.crash();

[function] int add ( string path ) - compile and spork a new shred from file at 'path' into the VM now returns the shred ID (see example/machine.ck)
[function] int spork ( string path ) - same as add/+
[function] int remove ( int id ) - remove shred from VM by shred ID (returned by add/spork)
[function] int replace ( int id, string path ) - replace shred with new shred from file returns shred ID , or 0 on error
[function] int status ( ) - display current status of VM same functionality as status/ (see example/status.ck)
[function] void crash ( ) - iterally causes the VM to crash. the very last resort;⁞ use with care. Thanks.

Math

Math contains the standard math functions. all trigonometric functions expects angles to be in radians.

// print sine of pi/2
<<<< Math.sin( pi / 2.0 ) >>>;

[function] float sin ( float x ) - computes the sine of x
[function] float cos ( float x ) - computes the cosine of x
[function] float tan( float x ) - computes the tangent of x
[function] float asin ( float x ) - computes the arc sine of x
[function] float acos ( float x ) - computes the arc cosine of x
[function] float atan ( float x ) - computes the arc tangent of x
[function] float atan2 ( float x ) - computes the principal value of the arc tangent of y/x, using the signs of both arguments to determine the quadrant of the return value
[function] float sinh ( float x ) - computes the hyperbolic sine of x
[function] float cosh ( float x ) - computes the hyperbolic cosine of x
[function] float tanh ( float x ) - computes the hyperbolic tangent of x
[function] float hypot ( float x, float y ) - computes the euclidean distance of the orthogonal vectors (x,0) and (0,y)
[function] float pow ( float x, float y ) - computes x taken to the y-th power
[function] int ensurePow2( int x ) - returns the next largest integer power of 2.
[function] float sqrt ( float x ) - computes the nonnegative square root of x (x must be >= 0)
[function] float exp ( float x ) - computes ex, the base-e exponential of x
[function] float log ( float x ) - computes the natural logarithm of x
[function] float log2 ( float x ) - computes the logarithm of x to base 2
[function] float log10 ( float x ) - computes the logarithm of x to base 10
[function] float floor ( float x ) - round to largest integral value (returned as float) not greater than x
[function] float ceil ( float x ) - round to smallest integral value (returned as float) not less than x
[function] float round ( float x ) - round to nearest integral value (returned as float)
[function] float trunc ( float x ) - round to largest integral value (returned as float) no greater in magnitude than x
[function] float fmod ( float x, float y ) - computes the floating point remainder of x / y
[function] float remainder ( float x, float y ) - computes the value r such that r = x - n * y, where n is the integer nearest the exact value of x / y. If there are two integers closest to x / y, n shall be the even one. If r is zero, it is given the same sign as x
[function] float min ( float x, float y ) - choose lesser of two values
[function] float max ( float x, float y ) - choose greater of two values
[function] int nextpow2 ( int n ) - computes the integeral (returned as int) smallest power of 2 greater than the value of x
[function] int isinf ( float x ) - is x infinity?
[function] int isnan ( float x ) - is x "not a number"?
[function] float pi - (currently disabled - use pi)
[function] float twopi - (currently disabled)
[function] float e - (currently disabled - use Math.exp(1) )
[float] float Math.INFINITY -constant representing infinity
[float] float Math.FLOAT_MAX -constant set to the largest possible value a float can have.
[float] float Math.FLOAT_MIN_MAG - constant set to the smallest positive value a float can have
[int] int Math.INT_MAX -constant set to the largest value a integer can have