Instance constructors

Instance constructors

An instance constructor is a member that implements the actions required to initialize an instance of a class. Instance constructors are declared using constructor-declarations:

constructor-declaration:
attributes_opt constructor-modifiers_opt constructor-declarator constructor-body

constructor-modifiers:
constructor-modifier
constructor-modifiers constructor-modifier

constructor-modifier:
public
protected
internal
private
extern

constructor-declarator:
identifier ( formal-parameter-list_opt ) constructor-initializer_opt

constructor-initializer:
: base ( argument-list_opt )
: this ( argument-list_opt )

constructor-body:
block
;

A constructor-declaration may include a set of attributes (‎17), an extern modifier, and a valid combination of the four access modifiers (‎10.2.3).

The identifier of a constructor-declarator must name the class in which the constructor is declared. If any other name is specified, an error occurs.

The optional formal-parameter-list of an instance constructor is subject to the same rules as the formal-parameter-list of a method (‎10.5). The formal parameter list defines the signature (‎3.6) of an instance constructor and governs the process whereby overload resolution (‎7.4.2) selects a particular instance constructor in an invocation.

Each of the types referenced in the formal-parameter-list of an instance constructor must be at least as accessible as the constructor itself (‎3.5.4).

The optional constructor-initializer specifies another instance constructor to invoke before executing the statements given in the constructor-body of this instance constructor. This is described further in ‎10.10.1.

When a constructor declaration includes an extern modifier, the constructor is said to be an external constructor. External constructors are implemented externally, using a language other than C#.

For external constructors, the constructor-body consists simply of a semicolon. For all other constructors, the constructor-body consists of a block which specifies the statements to initialize a new instance of the class. This corresponds exactly to the block of an instance method with a void return type (‎10.5.8).

Instance constructors are not inherited. Thus, a class has no instance constructors other than those actually declared in the class. If a class contains no instance constructor declarations, a default constructor is automatically provided (‎10.10.4).

Instance constructors are invoked by object-creation-expressions (‎7.5.10.1) and through constructor-initializers.

Constructor initializers

All instance constructors (except those for class object) implicitly include an invocation of another instance constructor immediately before the constructor-body. The constructor to implicitly invoke is determined by the constructor-initializer:

A instance constructor initializer of the form base(argument-list_opt) causes an instance constructor from the direct base class to be invoked. The constructor is selected using the argument-list and overload resolution rules of ‎7.4.2. The set of candidate instance constructors consists of all accessible instance constructors declared in the direct base class. If the set is empty, or if a single best instance constructor cannot be identified, an error occurs.

An instance constructor initializer of the form this(argument-list_opt) causes an instance constructor from the class itself to be invoked. The constructor is selected using the argument-list and overload resolution rules of ‎7.4.2. The set of candidate instance constructors consists of all accessible instance constructors declared in the class itself. If the set is empty, or if a single best instance constructor cannot be identified, an error occurs. If an instance constructor declaration includes a constructor initializer that invokes the constructor itself, an error occurs.

If an instance constructor has no instance constructor initializer, an instance constructor initializer of the form base() is implicitly provided. Thus, an instance constructor declaration of the form

C()

is equivalent to

C(): base()

The scope of the parameters given by the formal-parameter-list of an instance constructor declaration includes the instance constructor initializer of that declaration. Thus, an instance constructor initializer is permitted to access the parameters of the instance constructor. For example:

class A

}

class B: A

}

An instance constructor initializer cannot access the instance being created. It is therefore an error to reference this in an argument expression of the instance constructor initializer, as it is an error for an argument expression to reference any instance member through a simple-name.

Instance variable initializers

When an instance constructor has no instance constructor initializer, or when it has an instance constructor initializer of the form base(), it implicitly performs the initializations specified by the variable-initializers of the instance fields declared in the class. This corresponds to a sequence of assignments that are executed immediately upon entry to the instance constructor and before the implicit invocation of the direct base class instance constructor. The variable initializers are executed in the textual order in which they appear in the class declaration.

Constructor execution

Variable initializers are transformed into assignment statements, and these assignment statements are executed before the invocation of the base class instance constructor. This ordering ensures that all instance fields are initialized by their variable initializers before any statements that have access to that instance are executed.

In the example

class A

public virtual void PrintFields()

}

class B: A

public override void PrintFields() , y = ', x, y);
}
}

class T

}

the following output is produced:

x = 1, y = 0

The value of x is 1 because the variable initializer is executed before the base class instance constructor is invoked. However, the value of y is 0 (the default value of an int) because the assignment to y is not executed until after the base class constructor returns.

It is useful to think of instance variable initializers and constructor initializers as statements that are automatically inserted before the constructor-body of an instance constructor. The example

using System.Collections;

class A

public A(int n)
}

class B: A

public B(int n): base(n - 1)
}

contains several variable initializers and also contains constructor initializers of both forms (base and this). The example corresponds to the code shown below, where each comment indicates an automatically inserted statement (the syntax used for the automatically inserted constructor invocations isn't valid, but merely serves to illustrate the mechanism).

using System.Collections;

class A

public A(int n)
}

class B: A

public B(int n): base(n - 1)
}

Default constructors

If a class contains no instance constructor declarations, a default instance constructor is automatically provided. The default constructor simply invokes the parameterless constructor of the direct base class. If the direct base class does not have an accessible parameterless instance constructor, an error occurs. If the class is abstract then the declared accessibility for the default constructor is protected. Otherwise, the declared accessibility for the default constructor is public. Thus, the default constructor is always of the form

protected C(): base()

or

public C(): base()

where C is the name of the class.

In the example

class Message

a default constructor is provided because the class contains no instance constructor declarations. Thus, the example is precisely equivalent to

class Message
{
object sender;
string text;

public Message(): base()
}

Private constructors

When a class declares only private instance constructors, it is not possible for other classes to derive from the class or create instances of the class (an exception being classes nested within the class). Private instance constructors are commonly used in classes that contain only static members. For example:

public class Trig
{
private Trig() // Prevent instantiation

public const double PI = 3.14159265358979323846;

public static double Sin(double x)
public static double Cos(double x)
public static double Tan(double x)
}

The Trig class groups related methods and constants, but is not intended to be instantiated. Therefore it declares a single empty private instance constructor. At least one instance constructor must be declared to suppress the automatic generation of a default constructor.

Optional instance constructor parameters

The this() form of an instance constructor initializer is commonly used in conjunction with overloading to implement optional instance constructor parameters. In the example

class Text
{
public Text(): this(0, 0, null)

public Text(int x, int y): this(x, y, null)

public Text(int x, int y, string s)
}

the first two instance constructors merely provide the default values for the missing arguments. Both use a this() constructor initializer to invoke the third instance constructor, which actually does the work of initializing the new instance. The effect is that of optional instance constructor parameters:

Text t1 = new Text(); // Same as Text(0, 0, null)
Text t2 = new Text(5, 10); // Same as Text(5, 10, null)
Text t3 = new Text(5, 20, 'Hello');