^ programmer's guide | basic ugen | std uana

Chuck Standard Classes and Objects

The Standard Classes and Objects are built-in to ChucK. You can create your own classes via the ChucK language. Advanced developers can extend ChucK via C++ plugins. The Standard Classes and Objects by class name in ChucK. They are as follows:

Object | Array | String
Std | Math | Machine
Event | Shred | RegEx

Object

The Object class is the base class for all class types in ChucK.

Object.functions Description
string toString() Returns a textual description of this object.

Array

The array class a subclass of Object and is used to store linear sequences of data, also providing capabilities for stack and map data structures.

Array.functions Description
int cap() Return current capacity of the array (number of elements that can be held without reallocating internal buffer).
void clear() Clear the contents of the array.
int erase(string key) Erase all elements with the specified key.
int find(string key) Return number of elements with the specified key.
<< Append the array with the value to the right of this operator.
void popBack() Remove the last item of the array
void reset() Reset array to original state; clears the array and sets capacity to 8.
int size() Return the number of elements in the array.
int size(int newSize) Set the size of the array. If the new size is less than the current size, elements will be deleted from the end; if the new size is larger than the current size, 0 or null elements will be added to the end.
void getKeys(string keys[]) Fills keys with all of the keys in the array.
void zero() Zeros out the array while keeping the size unchanged.

see: array_argument.ck, array_assign.ck, array_dynamic.ck, array_mdim.ck, array_mmixed.ck, array_resize.ck, array_storage.ck, array_sub_assign.ck array_associative.ck array_zero.ck

String

The string class is a subclass of Object and holds textual data as a sequence of characters, and provides a number of functions for manipulating text.

string.functions Description
int charAt(int index) Return a character at the specified index.
void erase(int start, int length) Erase length characters of the string from start position.
int find(int theChar) Return the index of the first occurence of theChar, or -1 if theChar is not found.
int find(int theChar, int start) Return the index of the first occurence of theChar at or after the start position, or -1 if theChar is not found.
int find(string str) Return the index of the first occurence of str, or -1 if str is not found.
int find(string str, int start) Return the index of the first occurence of str at or after the start position, or -1 if str is not found.
void insert(int position, string str) Insert str at the specified position.
int length() Return the number of characters of the string.
string lower() Return a new string in which the uppercase characters of the original string have been converted to lowercase.
string ltrim() Return a new string in which leading whitespace has been removed.
void replace(int position, string str) Replace characters from the start position to the end of the string with str.
void replace(int position, int length, string str) Replace length characters from the start position with str.
int rfind(int theChar) Return the index of the last occurence of theChar, or -1 if theChar is not found.
int rfind(int theChar, int start) Return the index of the last occurence of theChar at or before the start position, or -1 if theChar is not found.
int rfind(string str) Return the index of the last occurence of str, or -1 if str is not found.
int rfind(string str, int start) Return the index of the last occurence of str at or before the start position, or -1 if str is not found.
string rtrim() Return a new string in which trailing whitespace has been removed.
int setCharAt(int index, int theChar) Set the character at the specified index.
string substring(int start) Return a new string containing the substring from the start index to the end of the string.
string substring(int start, int length) Return a new string containing the substring from the start index of the specified length.
float toFloat() Attempt to convert the contents of the string to an float and return the result, or 0 if conversion failed.
int toInt() Attempt to convert the contents of the string to an integer and return the result, or 0 if conversion failed.
string toString() (inherited from Object)
string trim() Return a new string in which leading and trailing whitespace has been removed.
string upper() Return a new string in which the lowercase characters of the original string have been converted to uppercase.

Std

The Std class is a subclass of Object and is comprised of several static utility functions, legacy random number generation, unit conversions, and absolute value.

// infinite time-loop
while( true )
{
  // generate random float (and print)
  <<< Std.rand2f( 100.0, 1000.0 ) >>>;
  // wait a bit
  50::ms => now;
}
Std.functions Description
int abs(int value) returns absolute value of integer
float atof(string value) converts ascii (string) to floating point value (float)
int atoi(string value) converts ascii (string) to integer (int)
int clamp(int v, int min, int max) clamp integer between range [min, max0
int clampf(float v, float min, float max) clamp float between range [min, max0
float dbtolin(float value) converts decibels (dB) to linear amplitude
float dbtopow(float value) converts decibels (dB) to signal power ratio
float dbtorms(float value) converts decibles (dB) to rms
float fabs(float) returns absolute value of float
string ftoa(float f, int precision) converts floating point value to ascii (string) with specified percision (number of decimal digits).
int ftoi(float f) converts float to int
int ftom(float f) converts frequency (Hz) to MIDI note number space.
string getenv(string key) returns the value of an environment variable, such as of "PATH"
string itoa(int f) converts integer value to ascii (string)
float lintodb(float value) Convert linear amplitude to decibels (dB).
float mtof(float value) converts a MIDI note number to frequency (Hz) note the input value is of type 'float' (supports fractional note number)
float powtodb(float value) converts signal power ratio to decibels (dB)
int rand2(int min, int max) generates random integer between [min, max],
float rand2f(float min, float max) generates random floating point number in the range [min, max]
int rand() generates random integer,
float randf() generates random floating point number in the range [-1, 1]
float rmstodb(float value) converts linear amplitude to decibels (dB)
float scalef(float v, float srcmin, float srcmax, float dstmin, float dstmax) Scale a float from source range to destination range
int setenv(string key, string value) sets environment variable named 'key' to 'value'
float sgn(float value) computes the sign of the input as -1.0 (negative), 0 (zero), or 1.0 (positive)
float srand(int seed) Provide a seed to the random function. Different seeds will generate very different sequences of random numbers even if the seeds are close together. Alternatively, a sequence of random numbers can be repeated by setting the same seed.
int system(string cmd) pass a command to be executed in the shell (may be disabled for security)

Math

The Math class is a subclass of Object and is comprised of a number of static math function including all trignometric functions as well as random number generators. Expresses angles in radians. There is some overlap with static functions of the Std class. Generally the Math variant should be preferred.

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

// infinite time-loop
while( true )
{
  // generate random float (and print)
  <<< Math.random2f( 100.0, 1000.0 ) >>>;
  // wait a bit
  50::ms => now;
}
Math.functions Description
float PI constant PI; used: Math.PI
float TWO_PI constant PI*2; used: Math.TWO_PI
float e Euler's constant, base of natural logarithm; same as Math.exp(1); use as: Math.e or Math.E
complex i the imaginary number 'i' as a complex value; use as: Math.i or Math.j or Math.I or Math.J
int RANDOM_MAX max value returned by Math.random() (NOTE: not to be confused with Std.rand*)
int abs(int x) returns the absolute value of an integer
float acos(float x) computes the arc cosine of x
float asin(float x) computes the arc sine of x
float atan2(float y, 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
float atan(float x) computes the arc tangent of x
float ceil(float x) round to smallest integral value (returned as float) not less than x
float cos(float x) computes the cosine of x
float cosh(float x) computes the hyperbolic cosine of x
float dbtopow(float value) converts decibels (dB) to signal power ratio
float dbtorms(float value) converts decibles (dB) to rms
int ensurePow2(int n) return the integral (returned as int) smallest power of 2 greater than the value of x.
float exp(float x) computes e^x, the base-e exponential of x
float fabs(float value) return the absolute value of float
float floor(float x) round to largest integral value (returned as float) not greater than x
float fmod(float x, float y) computes the floating point remainder of x / y
float ftom(float f) converts frequency (Hz) to MIDI note number space.
float gauss(float x, float mean, float sd) computes the weight for input x taken from a gaussian distribution around the mean and standard deviation
float hypot(float x, float y) computes the euclidean distance of the orthogonal vectors (x,0) and (0,y)
float im(complex value) return the imaginary component of a complex number
int isinf(float x) return 1 if x is infinite, else return 0
int isnan(float x) return 1 if x "is not a number", else return 0
float log10(float x) computes the logarithm of x to base 10
float log2(float x) computes the logarithm of x to base 2
float log(float x) computes the natural logarithm of x
float mag(polar value) return the magnitude of a polar value
float map(float value, float x1, float x2, float y1, float y2) maps a number in one range to a second range. Unclamped.
float map2(float value, float x1, float x2, float y1, float y2) maps a number in one range to a second range. Clamped.
float max(float x, float y) return greater of two values
float min(float x, float y) return lesser of two values
float mtof(float value) converts a MIDI note number to frequency (Hz) note the input value is of type 'float' (supports fractional note number)
int nextpow2(int x) computes the integeral (returned as int) smallest power of 2 greater than the value of x
float phase(polar value) return the phase of a polar return
float pow(float x, float y) computes x taken to the y-th power
float powtodb(float value) converts signal power ratio to decibels (dB)
float ptor(polar[] from, complex[] to) convert an array of polar complex numbers to an array of rectangular complex numbers in place (the second argument is the array that is to be modified). Returns the total number of conversions.
int random2(int min, int max) generates random integer in the range [min, max]
float random2f(float min, float max) generates random floating point number in the range [min, max]
int random() generates random integer between 0 and Math.RANDOM_MAX (NOTE: Math.random() functions use a different, superior random number generator than the Std.rand() functions)
float randomf() generates random floating point number in the range [0, 1] (NOTE: this is different semantics than Std.randf(), which has the range [-1,1])
float re(complex value) return the real component of a complex number
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
float rmstodb(float value) converts rms to decibels (dB)
float round(float x) round to nearest integral value (returned as float)
float rtop(complex[] from, polar[] to) convert an array of rectangular complex numbers to an array of polar complex numbers in place (the second argument is the array that is to be modified). Returns the total number of conversions.
float sgn(float value) computes the sign of the input as -1.0 (negative), 0 (zero), or 1.0 (positive)
float sin(float x) computes the sine of x
float sinh(float x) computes the hyperbolic sine of x
float sqrt(float x) computes the nonnegative square root of x (x must be >= 0)
void srandom(int seed) provide a seed to the random function. Different seeds will generate very different sequences of random numbers even if the seeds are close together. Alternatively, a sequence of random numbers can be repeated by setting the same seed.
float tan(float x) computes the tangent of x
float tanh(float x) computes the hyperbolic tangent of x
float trunc(float x) round to largest integral value (returned as float) no greater in magnitude than x

Machine

Machine is a subclass of Object and constitutes the ChucK runtime interface to the virtual machine. It is comprised entirely of static functions, so there's no need to create an instance of this class. Machine is used to manage shreds and the functions 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.

Machine.function Description
int add(string path) compile and spork a new shred from file at 'path' into the VM now. Returns the new shredID(see example/machine.ck)
void crash() literally causes the VM to crash. The very last resort; use with care. Thanks.
int intsize() return the bit size of a integer.
int remove(int id) remove shred from VM by shred ID (returned by add/spork)
int replace(int id, string path) replace shred with new shred from file (returns new shred id or 0 on error)
int[] shreds() return an integer array containing IDs of current Shred objects
int status() display current status of VM (see example/status.ck)

Event

The Event is a subclass of Object and allows exact synchronization across an arbitrary number of shreds. It is common to create a subclass of of Event comprised of custom methods and member variables.

Event.function Description
void broadcast() Signal all shreds that are waiting on this event.
int can_wait() Whether or not the event can be waited on. Currently always returns true.
void signal() Signal one shred that is waiting on this event.
void wait(Shred me) (Currently unsupported.)

Shred

Shred is a subclass of Object and facilitates various operations and interactions with shreds running in the ChucK virtual machine.

Shred.function Description
static Shred fromId(int id) returns a Shred object corresponding to the provided ID. Machine.shreds() can be used to obtain a list of active Shred ids
string arg(int index) return the launch argument at the specified index.
int args() return the number of arguments provided to the shred.
void clone()
string dir() return the enclosing directory of the source code file from which this shred's code is derived (same as .sourceDir()).
string dir(int levelsUp) return the enclosing directory, the specified number of parent directories up.
int done() Return true if the shred is done processing; false otherwise.
void exit() immediately halt the shred's operation and remove it from the virtual machine.
int id() return the unique numeric id of the shred.
string path() return the file path of the source code file from which this shred's code is derived (same as .sourcePath()).
int running() return true if the shred is currently running; false otherwise.
string sourceDir() return the enclosing directory of the source code file from which this shred's code is derived.
string sourcePath() return the path of the source code file from which this shred's code is derived.
void yield() cause the shred to temporarily stop processing, allowing other scheduled shreds to run as needed.

RegEx

RegEx is a subclass of Object and implements regular expression matching and replacing in strings. The RegEx style supported is POSIX-extended. RegEx is comprised of 4 static functions and so there is no need to create an instance of this class.

RegEx.function Description
int match(string pattern, string str) return true if match for pattern is found in str, false otherwise
int match(string pattern, string str, string[] matches) return the match and sub-patterns in matches. matches[0] in the entire matched pattern, matches[1] is the first sub-pattern (if any), and so on.
string replace(string pattern, string replacement, string str) replace the first instance of pattern in str with replacement, returning the result.
string replaceAll(string pattern, string replacement, string str) replace all instances of pattern in str with replacement, returning the result.
home .. language .. program .. examples