writing a custom class

ChucK is an object-oriented language and it is possible to define new types and their behavior by authoring a new class. If a class has been defined (either in the same file or as a public class in a different file) then it can be instantiated similar to any other type.

Unless declared public, class definitions are scoped to the shred and will not conflict with identically named classes in other running shreds.

Classes encapsulate a set of behaviors and data. To define a new object type, the keyword class is used followed by the name of that class.

// define class X
class X
{
    // insert code here
}

If a class is defined as public, it is integrated into the central namespace (instead of the local one), and can be instantiated from other programs that are subsequently compiled. There can be at most one public class per file.

// define public class MissPopular
public class MissPopular
{
    // ...
}

// define non-public class Flarg
class Flarg
{
    // ...
}

// Both MissPopular and Flarg can be used in this file.
// Only MissPopular can be used from another file. Poor Flarg.

We define member data and methods to specify the data types and functionality required of the class. Members, or instance data and instance functions are associated with individual instances of a class, whereas static data and functions are only associated with the class (and shared by the instances).

members (instance data + functions)

Instance data and methods are associated with an object.

// define class X
class X
{
    // declare instance variable 'm_foo'
    int m_foo;
    // another instance variable 'm_bar'
    float m_bar;
    // yet another, this time an object
    Event m_event;

    // function that returns value of m_foo
    fun int getFoo() { return m_foo; }

    // function to set the value of m_foo
    fun void setFoo( int value ) { value => m_foo; }

    // calculate something
    fun float calculate( float x, float y )
    {
        // insert code
    }

    // print some stuff
    fun void print()
    {
        <<< m_foo, m_bar, m_event >>>;
    }
}

// instantiate an X
X x;

// set the Foo
x.setFoo( 5 );
// print the Foo
<<< x.getFoo() >>>;

// call print
x.print();

class constructors

As of version 1.5.2.0, ChucK now supports constructors and destructors.

Constructors can be invoked when declaring a variable or with `new`:

// connecting UGens, with construtors
SinOsc foo( 440 ) => Gain g( .5 ) => dac;
// `new` and assignment
new TriOsc( 440, 0.5 ) @=> Osc @ oscillator;
// can combine constructors with arrays
string arr( "foo" )[10];

Constructors can also be defined and overloaded in class definitions:

class Foo
{
    // a member variable
    1 => int num;

    // constructor "default"
    fun Foo() { 2 => num; }

    // another constructor
    fun Foo( int x ) { x => num; }

    // yet another constructor
    fun Foo( int x, int y ) { x*y => num; }

    // alternate way of defining a constructor, using the @construct keyword
    fun @construct( int x, int y, int z ) { x*y*z => num; }

    // destructor
    fun @destruct() { <<< "bye:", this.num >>>; }
}

// constructor "default"
Foo f1();
// another constructor
Foo f2( 15 );
// yet another constructor
new Foo( 8, 9 ) @=> Foo @ f3;
// yet another constructor
new Foo( 10, 11, 12 ) @=> Foo @ f4;
// print
<<< f1.num, f2.num, f3.num, f4.num >>>;

static (data + functions)

Static data and functions are associated with a class, and are shared by all instances of that class -- in fact,static elements can be accessed without an instance, by using the name of the class: Classname.element.

// define class X
class X
{
    // static data
    static int our_data;

    // static function
    fun static int doThatThing()
    {
        // return the data
        return our_data;
    }
}

// do not need an instance to access our_data
2 => X.our_data;
// print out
<<< X.our_data >>>;
// print
<<< X.doThatThing() >>>;

// create instances of X
X x1;
X x2;

// print out their static data - should be same
<<< x1.our_data, x2.our_data >>>;

// change use one
5 => x1.our_data;

// the other should be changed as well
<<< x1.our_data, x2.our_data >>>;

Update (chuck-1.5.4.3 or higher): full static variable instantiation is now supported for all primitive and Object types. See examples/class/static-init.ck.

// a class
public class Foo
{
    // int
    1 => static int S_INT;
    // float
    2 => static float S_FLOAT;
    // dur
    3::second => static dur S_DUR;
    // time
    now + 4::second => static time S_TIME;
    // vec3
    @(5,6,7) => static vec3 S_VEC3;
    // array
    [8,9,10,11] @=> static int S_INT_ARRAY[];
    // string
    static string S_STRING("12");
    // ugen
    static SinOsc S_SINOSC(440);
}

// access and print static variables
<<< Foo.S_INT >>>;
<<< Foo.S_FLOAT >>>;
<<< Foo.S_DUR / second >>>;
<<< (Foo.S_TIME-now) / second >>>;
<<< Foo.S_VEC3 >>>;
for( auto i : Foo.S_INT_ARRAY ) <<< i >>>;
<<< Foo.S_STRING >>>;
<<< Foo.S_SINOSC.freq() >>>;

inheritance

Inheritance in object-oriented code allows the programmer to take an existing class and extend or alter its functionality. In doing so we can create a taxonomy of classes that all share a specific set of behaviors, while implementing those behaviors in different, yet well-defined, ways. We indicate that a new class inherits from another class using the extends keyword. The class from which we inherit is referred to as the parent class, and the inheriting class is the child class. The Child class receives all of the member data and functions from the parent class, although functions from the parent class may be overridden ( below ). Because the children contain the functionality of the parent class, references to instances of a child class may be assigned to a parent class reference type.

For now, access modifiers (public, protected, private) are included but not fully implemented. Everything is public by default.

// define class X
class X
{
    // define member function
    fun void doThatThing()
    {
        <<<"Hallo">>>;
    }

    // define another
    fun void hey()
    {
        <<<"Hey!!!">>>;
    }

    // data
    int the_data;
}

// define child class Y
class Y extends X
{
    // override doThatThing()
    fun void doThatThing()
    {
        <<<"No! Get away from me!">>>;
    }
}

// instantiate a Y
Y y;

// call doThatThing
y.doThatThing();

// call hey() - should use X's hey(), since we didn't override
y.hey();

// data is also inherited from X
<<< y.the_data >>>;

Inheritance provides us a way of efficiently sharing code between classes which perform similar roles. We can define a particular complex pattern of behavior, while changing the way that certain aspects of the behavior operate.

// parent class defines some basic data and methods 
class Xfunc
{ 
    int x; 

    fun int doSomething( int a, int b ) { 
        return 0; 
    }
}

// child class, which overrides the doSomething function with an addition operation
class Xadds extends Xfunc
{ 
    fun int doSomething ( int a, int b )
    { 
         return a + b ; 
    }
}

// child class, which overrides the doSomething function with a multiply operation 
class Xmuls extends Xfunc
{ 
    fun int doSomething ( int a, int b )
    { 
         return a * b; 
    }
}

// array of references to Xfunc
Xfunc @ operators[2];

// instantiate two children and assign reference to the array 
new Xadds @=> operators[0];
new Xmuls @=> operators[1];

// loop over the Xfunc
for( 0 => int i; i < operators.cap(); i++ )
{
    // doSomething, potentially different for each Xfunc
    <<< operators[i].doSomething( 4, 5 ) >>>;
}

because Xmuls and Xadds each redefine doSomething( int a, int b ) with their own code, we say that they have overridden the behavior of the parent class. They observe the same interface, but have potentially different implementation. This is known as polymorphism.

Overloading

Function overloading in classes is similar to that of regular functions. see functions.