/  Base Classes

Object

Event

Shred

Math

Machine

Std

string

@array

Basic classes (Object, Event, Shred, etc.) and standard libraries (Math, Machine, Std)


Event

inherits : Object

A mechanism for precise synchronization across shreds.

examples

constructors

Event()

Default constructor for Event.

member functions

void broadcast()

Signal all shreds that are waiting on this event.

int can_wait()

Can the event can be waited on? (internal) used by virtual machine for synchronization.

void signal()

Signal one shred that is waiting on this event.

void waiting_on()

(internal) used by virtual machine to be notified when a shred starts waiting on this Event.


Shred

inherits : Object

A strongly-timed ChucK thread of execution.

examples

constructors

Shred()

Default constructor for Shred.

member functions

Shred ancestor()

Get the calling shred's "ancestor" shred (i.e., the top-level shred). Returns itself if the calling shred is the top-level shred. (Related: see Shred.parent())

string arg(int index)

Get the Shred argument at the specified index.

int args()

Get the number of arguments provided to the Shred.

int childMemSize(int sizeInBytes)

Set size hint of per-shred call stack ("mem") for children shreds subsequently sporked from the calling shred (NOTE this size hint does not affect the calling shred--only its descendants); if sizeInBytes <= 0, the size hint is set to the VM default. (FYI This is an arcane functionality that most programmers never need to worry about. Advanced usage: set size hint to small values (e.g., 1K) to support A LOT (e.g., >10000) of simultaneous shreds; set size hint to large values (e.g., >65K) to spork functions with extremely deep recursion, or to support A LOT (>10000) of declared local variables. Use with care.)

int childMemSize()

Get the memory stack size hint (in bytes) for shreds sporked from this one.

int childRegSize(int sizeInBytes)

Set size hint of per-shred operand stack ("reg") for children shreds subsequently sporked from the calling shred (NOTE this size hint does not affect the calling shred--only its descendants); if sizeInBytes <= 0, the size hint is set to the VM default. (FYI This is an arcane functionality that most programmers never need to worry about. Advanced usage: set size hint to small values (e.g., 256 bytes) to support A LOT (>10000) of simultaneous shreds; set size hint to large values (e.g., >20K) to spork functions with extremely lengthy (>10000) statements, including array initializer lists. Use with care.)

int childRegSize()

Get the operand stack size hint (in bytes) for shreds sporked from this one.

string dir()

Get the enclosing directory of the source file from which this Shred's code is derived (same as .sourceDir()).

string dir(int levelsUp)

Get the enclosing directory, the specified number of parent directories up.

int done()

Has the Shred reached the end of its execution?

void exit()

Halt the shred's operation and remove it from the virtual machine.

int id()

Get the unique numeric id of the Shred.

int memSP()

Get the calling shred's current memory/call stack pointer; useful for debugging, general information, or amusement.

Shred parent()

Get the calling shred's parent shred (i.e., the shred that sporked the calling shred). Returns null if there is no parent Shred. (Related: see Shred.ancestor())

string path()

Get the path of the source file from which this Shred's code is derived (same as .sourcePath()).

int pc()

Get the calling shred's current program counter (CP); useful for debugging, general information, or amusement.

int regSP()

Get the calling shred's current register/operand stack pointer; useful for debugging, general information, or amusement.

int running()

Is the Shred currently actively running in the VM?

string sourceDir()

Get the enclosing directory of the source file from which this Shred's code is derived (same as .dir()).

string sourcePath()

Get the path of the source file from which this Shred's code is derived (same as .path()).

void yield()

Cause the current Shred to temporarily suspend without advancing time, allowing other simultaneously schreduled shreds to run as needed. NOTE: yield() is equivalent to '0::second +=> now;'

static member functions

Shred fromId(int id)

Get Shred corresponding to a Shred ID.


Math

inherits : Object

Math class library.

examples

static member functions

int abs(int value)

Return absolute value of an integer value.

float acos(float x)

Compute arccosine of x; result in [0, pi].

float asin(float x)

Compute arcsine of x; result in [-pi/2, +pi/2].

float atan2(float y, float x)

Compute arc tangent of two variables (y/x).

float atan(float x)

Compute arctangent of x; result in [-pi/2, +pi/2].

float ceil(float x)

Return the smallest integer value (returned as float) not less than x.

float clampf(float value, float min, float max)

Clamp a float to range [min,max].

int clampi(int value, int min, int max)

Clamp an integer to range [min,max].

float cos(float x)

Compute cosine of x (measured in radians).

float cosh(float x)

Compute the hyperbolic cosine of x.

float cossim(float[] a, float[] b)

Compute the cosine similarity between arrays a and b.

float cossim(vec3 a, vec3 b)

Compute the cosine similarity between 3D vectors a and b.

float cossim(vec4 a, vec4 b)

Compute the cosine similarity between 4D vectors a and b.

float dbtopow(float value)

Convert decibels (dB) to signal power ratio.

float dbtorms(float value)

Convert decibles (dB) to linear amplitude.

int ensurePow2(int x)

Return the smallest power-of-2 greater than or equal to the value of x.

int equal(float x, float y)

Return whether two floats are considered equal.

float euclidean(float[] a, float[] b)

Compute the euclidean distance between arrays a and b.

float euclidean(vec2 a, vec2 b)

Compute the euclidean distance between 2D vectors a and b.

float euclidean(vec3 a, vec3 b)

Compute the euclidean distance between 3D vectors a and b.

float euclidean(vec4 a, vec4 b)

Compute the euclidean distance between 4D vectors a and b.

float exp2(float x)

Compute 2^x, the base-2 exponential of x.

float exp(float x)

Compute e^x, the base-e exponential of x.

float fabs(float value)

Return absolute value of a floating point value.

float floor(float x)

Return the largest integer value (returned as float) not greater than x.

float fmod(float x, float y)

Compute the floating-point remainder of x / y.

float ftom(float value)

Convert frequency (Hz) to MIDI note number space.

float gauss(float x, float mean, float sd)

Compute gaussian function at x, given mean and SD.

float hypot(float x, float y)

Compute the euclidean distance sqrt(x*x+y*y).

float im(complex v)

Return the imaginary component of complex value v.

int isinf(float x)

Return true if x is infinity, else return false.

int isnan(float x)

Return true if x is not a number, else return false.

float log10(float x)

Compute the logarithm of x to base 10.

float log2(float x)

Compute the logarithm of x to base 2.

float log(float x)

Compute the natural logarithm of x.

float mag(polar v)

Return the magnitude component of polar value v.

float map2(float value, float x1, float y1, float x2, float y2)

Map 'value' from range [x1,y1] into range [x2,y2]; 'value' will be clamped to [x1,y1] if outside range. (see also: Math.map())

float map(float value, float x1, float y1, float x2, float y2)

Map 'value' from range [x1,y1] into range [x2,y2]; 'value' can be outside range[x1,y1]. (see also: Math.map2())

int max(int x, int y)

Return the greater of x and y (integer).

float max(float x, float y)

Return the greater of x and y (float).

int min(int x, int y)

Return the lesser of x and y (int).

float min(float x, float y)

Return the lesser of x and y (float).

float mtof(float value)

Convert a MIDI note number to frequency (Hz). Note that the input value is of type float and supports fractional note numbers.

int nextpow2(int x)

Compute the smallest power-of-2 greater than x.

float phase(polar v)

Return the phase component of polar value v.

float pow(float x, float y)

Compute x raised to the y-th power.

float powtodb(float value)

Convert signal power ratio to decibels (dB).

int ptor(polar[] from, complex[] to)

Convert polar values to complex values; returns number of values converted.

int random2(int min, int max)

Return successive pseudo-random numbers in the range [min, max].

float random2f(float min, float max)

Return successive pseudo-random floating-point numbers in the range [min, max].

int random()

Return successive pseudo-random integer numbers in the range [0, Math.RANDOM_MAX]].

float randomf()

Return successive pseudo-random floating-point numbers in the range [0,1].

void randomize()

Randomize the seed of the random number generator (RNG), using an non-deterministic mechanism. Whereas srandom() explicitly seeds the RNG and will produce a deterministic sequence of pseudo-random numbers, randomize() "shakes things up" and causes RNG to start generating from a practically unpredicable seed. The quality of randomize() depends on the underlying implementation.

float re(complex v)

Return the real component of complex value v.

float remainder(float x, float y)

Compute 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 remap(float value, float x1, float y1, float x2, float y2)

Same as Math.map2().

float rmstodb(float value)

Convert linear amplitude to decibels (dB).

float round(float x)

Return the integer value (returned as float) nearest to x (rounding halfway cases away from zero).

int rtop(complex[] from, polar[] to)

Convert complex values to polar values; returns number of values converted.

float sgn(float value)

Return sign of 'value' as -1.0 (negative), 0.0, or 1.0 (positive).

float sin(float x)

Compute sine of x (measured in radians).

float sinh(float x)

Compute the hyperbolic sine of x.

float sqrt(float x)

Compute the non-negative square root of x.

void srandom(int seed)

Seed the random number generator (RNG). Different seeds will generate very different sequences of random numbers even if the seeds are close together. Alternatively, a deterministic sequence of pseudo-random numbers can repeatably generated by setting the same seed.

float tan(float x)

Compute tangent of x (measured in radians).

float tanh(float x)

Compute the hyperbolic tangent of x.

float trunc(float x)

Return the integer value nearest to but no greater in magnitude than x.

static member variables

float e

Euler's number; base of the natural logarithm.

float E

Euler's number; base of the natural logarithm.

float FLOAT_MAX

Largest representable floating-point value.

float FLOAT_MIN_MAG

Smallest representable non-negative floating-point value.

complex i

The complex number sqrt(-1).

complex I

The complex number sqrt(-1).

float INFINITY

Like, infinity.

int INT_MAX

Largest representable integer value.

complex j

The complex number sqrt(-1).

complex J

The complex number sqrt(-1).

float pi

An approximation of pi. (Same as global keyword 'pi'.)

float PI

An approximation of pi. (Same as global keyword 'pi'.)

int RANDOM_MAX

The largest possible value returned by random().

float two_pi

An approximation of 2*pi.

float TWO_PI

An approximation of 2*pi.


Machine

inherits : Object

Machine is the runtime interface to the ChucK Virtual Machine (Ck.VM or simply VM). This interface can be used to manage shreds, evaluate code, set log levels, etc. Machine's shred commands (add, replace, remove, etc.) are similar to the on-the-fly programming commands, except these are invoked from within a ChucK program, and benefit from ChucK's strongly-timed mechanics.

examples

static member functions

int add(string path)

Compile and spork a new shred from file at 'path' into the VM; returns the new shred ID. It is possible to include arguments with the file being added, e.g., `Machine.add( "foo.ck:bar:3:5.0" )`.

void clearVM()

Reset the type system, removing all user-defined types and all global variables; removes all shreds in the VM (including the shred calling this function); use with care.

void crash()

Explicitly crash the virtual machine. The very last resort; or an emphatic gesture. Use with care.

int eval(string code)

Evaluate a string as ChucK code, compile it and immediately spork it as a new independent shred, and automatically yield the current shred to give the new shred a chance to run, without advancing time.

int eval(string code, string args)

Evaluate a string as ChucK code, with arguments (bundled in 'args' as "ARG1:ARG2:...", compile it and immediately spork it as a new independent shred, and automatically yield the current shred to give the new shred a chance to run, without advancing time.

int eval(string code, string args, int count)

Evaluate a string as ChucK code, with optional arguments (bundled in 'args' as "ARG1:ARG2:...", compile it and immediately spork 'count' independent shreds; and automatically yield the current shred to give all new shreds a chance to run, without advancing time.

int intsize()

Return the bit size of an integer.

int loglevel(int level)

Set log level |- 0: NONE |- 1: CORE |- 2: SYSTEM |- 3: HERALD |- 4: WARNING |- 5: INFO |- 6: DEBUG |- 7: FINE |- 8: FINER |- 9: FINEST |- 10: ALL.

int loglevel()

Get log level.

int numShreds()

Get the number of shreds currently in the VM.

void printStatus()

Print (to terminal or console) the current status of the VM.

void printTimeCheck()

Print (to terminal or console) the current time information in the VM.

int realtime()

Return true if the shred is in realtime mode, false if it's in silent mode (i.e. --silent is enabled)

int refcount(Object obj)

Get an object's current internal reference count; this is intended for testing or curiosity; NOTE: this function intentionally does not take into account any reference counting related to the calling of this function (normally all functions increments the reference count for objects passed as arguments and decrements upon returning)

int remove(int id)

Remove shred from VM by shred ID (returned by Machine.add).

void removeAllShreds()

Remove all shreds in the VM (including the shred calling this function).

int removeLastShred()

Remove the most recently added shred in the VM (could be the shred calling this function); returns the ID of the removed shred.

int replace(int id, string path)

Replace shred with new shred from file. Returns new shred ID, or 0 on error. It is possible to include arguments, e.g., `Machine.replace( outID, "foo.ck:bar:3:5.0" )`.

void resetOperators()

Reset operator overloading state to default startup state; removes all public @operator overloads; use with care.

int resetShredID()

Reset shred IDs to 1 + the highest current shred ID in the VM; can be used as shred management to keep shred IDs low, after a lot of sporks; returns what the next shred ID would be.

int[] shreds()

Retrieve an array of active shred ids.

int silent()

Return false if the shred is in realtime mode, true if it's in silent mode (i.e. --silent is enabled)

int sp_mem()

Get the calling shred's memory (aka "mem") stack pointer; intended for either debugging or curiosity.

int sp_reg()

Get the calling shred's operand (aka "reg"/register) stack pointer; intended for either debugging or curiosity.

int status()

Print the current status of the VM; legacy version of printStatus().

string version()

Return language and VM version string.


Std

inherits : Object

A standard library in ChucK, which includes utility functions for random number generation, unit conversions, and absolute value.

static member functions

int abs(int value)

Return absolute value of integer.

float atof(string value)

Converts ascii (string) to floating point value (float).

int atoi(string value)

Convert ascii (string) to integer (int).

int clamp(int value, int min, int max)

Clamp integer to range [min, max].

float clampf(float value, float min, float max)

Clamp float to range [min, max].

float dbtolin(float value)

Convert decibels (dB) to linear amplitude.

float dbtopow(float value)

Convert decibels (dB) to signal power ratio.

float dbtorms(float value)

Convert decibels (dB) to rms.

float fabs(float value)

Return absolute value of float.

string ftoa(float f, int precision)

Converts floating point value (float) to ascii (string) with specified precision (number of decimal digits).

int ftoi(float f)

Convert float to integer.

float ftom(float value)

Convert frequency (Hz) to MIDI note number space.

string getenv(string key)

Get the value of an environment variable (e.g., PATH).

string getenv(string key, string default)

Get the value of an environment variable, returning the provided default if unset.

string itoa(int i)

Converts integer (int) to ascii (string).

float lintodb(float value)

Convert linear amplitude to decibels (dB).

float mtof(float value)

Convert a MIDI note number to frequency (Hz). Note the input value is of type float (supports fractional note number). For reference, MIDI note number 60 is Middle C; each whole number is one semitone.

float powtodb(float value)

Convert signal power ratio to decibels (dB).

int rand2(int min, int max)

Generate a random integer in range [min, max]. (NOTE: this is deprecated; use Math.random2()).

float rand2f(float min, float max)

Generate random floating point number in the range [min, max]. (NOTE: this is deprecated; use Math.random2f())

int rand()

Generate a random integer between 0 and Std.RAND_MAX. (NOTE: this is deprecated; use Math.random()).

float randf()

Generate random floating point number in the range [-1, 1]. (Note: this is deprecated; use Math.randomf())

int[] range(int stop)

Return array containing the range [0,stop).

int[] range(int start, int stop)

Return array containing the range [start,stop).

int[] range(int start, int stop, int step)

Return array containing values from start up to (but not including) stop, hopping by step.

float rmstodb(float value)

Convert rms to decibels (dB).

float scalef(float value, float srcmin, float srcmax, float dstmin, float dstmax)

Scale a float from source range to destination range.

int setenv(string key, string value)

Set the value of environment variable named 'key'

float sgn(float value)

Get sign of value as -1 (negative), 0, or 1 (positive).

void srand(int seed)

Seed the random number generator. Different seeds will likely generate 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. (NOTE: this is deprecated; use Math.srandom())

int system(string cmd)

Pass a command to be executed in the shell (requires --caution-to-the-wind flag to be set).

static member variables

int RAND_MAX

The largest possible value returned by Std.rand().


string

inherits : Object

Textual data as a sequence of characters, along with functions for manipulating text.

examples

constructors

string()

Default constructor for string.

string(string str)

Construct a string as a copy of another string.

member functions

string appendChar(int theChar)

Append a character by its ASCII code and return a reference to itself; same as using the << operator `STR << INT`.

int charAt(int index)

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

Get the index of the first occurrence of theChar, or -1 if theChar is not found.

int find(int theChar, int start)

Get the index of the first occurrence of theChar at or after the start position, or -1 if theChar is not found.

int find(string str)

Get the index of the first occurrence of str, or -1 if str is not found.

int find(string str, int start)

Get the index of the first occurrence of str at or after the start position, or -1 if str is not found.

void insert(int position, string str)

Insert a string at the specified position.

int length()

Get the number of characters of the string.

string lower()

Get a new string in which the uppercase characters of the original string have been converted to lowercase.

string ltrim()

Get a new string in which leading whitespace has been removed.

void replace(int position, string str)

Replace characters from 'position' with contents of 'str'.

void replace(int position, int length, string str)

Replace 'length' characters from 'position' with contents of 'str'.

void replace(string from, string to)

Replace all instances of 'from' in the string with 'to'.

int rfind(int theChar)

Get the index of the last occurrence of theChar, or -1 if theChar is not found.

int rfind(int theChar, int start)

Get the index of the last occurrence of theChar at or before the start position, or -1 if theChar is not found.

int rfind(string str)

Get the index of the last occurrence of str, or -1 if str is not found.

int rfind(string str, int start)

Get the index of the last occurrence of str at or before the start position, or -1 if str is not found.

string rtrim()

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

Get a new string containing the substring from the start index to the end of the string.

string substring(int start, int length)

Get 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()

Return the reference of calling string.

string trim()

Get a new string in which leading and trailing whitespace has been removed.

string upper()

Get a new string in which the lowercase characters of the original string have been converted to uppercase.


@array

inherits : Object

Storage construct for sequential data of the same type; can also be used as an associative map data structure; also can be used as a stack with << operator to append/push and popBack to pop.

examples

member functions

int cap()

(deprecated) For historical/compatibilty reasons, .cap() is always equal to .size(); instead of using .cap(), it is recommended to explicitly use .size() or .capacity().

int capacity(int val)

Ensure capacity of the array (number of addressable elements).

int capacity()

Get current capacity of the array (number of addressable elements).

void clear()

Clear the contents of the array.

int erase(int position)

Remove element at 'position' from the array (same as popOut(int)).

int erase(int begin, int end)

Remove element(s) in the range [begin,end).

int erase(string key)

(map only) Erase all elements with the specified key.

void getKeys(string[] keys)

Return all keys found in associative array in keys.

int isInMap(string key)

(map only) test if 'key' is in the map; (historical) this was renamed from .find() to avoid confusion with the vector part of array.

void popBack()

Remove the last element of the array.

void popFront()

Remove the first element of the array.

void popOut(int position)

Remove the element at 'position' from the array (same as erase(int)).

void reset()

Reset array size to 0, set capacity to (at least) 8.

void reverse()

Reverses the array in-place.

void shuffle()

Shuffle the contents of the array.

int size()

Get 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 sort()

Sort the contents of the array in ascending order.

void zero()

Zero out the contents of the array; size is unchanged.