Protected access for instance members

When a protected instance member is accessed outside the program text of the class in which it is declared, and when a protected internal instance member is accessed outside the program text of the program in which it is declared, the access must take place within a class declaration that derives from the class in which it is declared. Furthermore, the access is required to take place through an instance of that derived class type or a class type constructed from it. This restriction prevents one derived class from accessing protected members of other derived classes, even when the members are inherited from the same base class.

Let B be a base class that declares a protected instance member M, and let D be a class that derives from B. Within the class-body of D, access to M can take one of the following forms:

· An unqualified type-name or primary-expression of the form M.

· A primary-expression of the form E.M, provided the type of E is T or a class derived from T, where T is the class type D, or a class type constructed from D

· A primary-expression of the form base.M.

In addition to these forms of access, a derived class can access a protected instance constructor of a base class in a constructor-initializer (§10.11.1).

In the example

public class A
{
protected int x;

static void F(A a, B b) {
a.x = 1; // Ok
b.x = 1; // Ok
}
}

public class B: A
{
static void F(A a, B b) {
a.x = 1; // Error, must access through instance of B
b.x = 1; // Ok
}
}

within A, it is possible to access x through instances of both A and B, since in either case the access takes place through an instance of A or a class derived from A. However, within B, it is not possible to access x through an instance of A, since A does not derive from B.

In the example

class C<T>
{
protected T x;
}

class D<T>: C<T>
{
static void F() {
D<T> dt = new D<T>();
D<int> di = new D<int>();
D<string> ds = new D<string>();
dt.x = default(T);
di.x = 123;
ds.x = "test";
}
}

the three assignments to x are permitted because they all take place through instances of class types constructed from the generic type.

Accessibility constraints

Several constructs in the C# language require a type to be at least as accessible as a member or another type. A type T is said to be at least as accessible as a member or type M if the accessibility domain of T is a superset of the accessibility domain of M. In other words, T is at least as accessible as M if T is accessible in all contexts in which M is accessible.

The following accessibility constraints exist:

· The direct base class of a class type must be at least as accessible as the class type itself.

· The explicit base interfaces of an interface type must be at least as accessible as the interface type itself.

· The return type and parameter types of a delegate type must be at least as accessible as the delegate type itself.

· The type of a constant must be at least as accessible as the constant itself.

· The type of a field must be at least as accessible as the field itself.

· The return type and parameter types of a method must be at least as accessible as the method itself.

· The type of a property must be at least as accessible as the property itself.

· The type of an event must be at least as accessible as the event itself.

· The type and parameter types of an indexer must be at least as accessible as the indexer itself.

· The return type and parameter types of an operator must be at least as accessible as the operator itself.

· The parameter types of an instance constructor must be at least as accessible as the instance constructor itself.

In the example

class A {...}

public class B: A {...}

the B class results in a compile-time error because A is not at least as accessible as B.

Likewise, in the example

class A {...}

public class B
{
A F() {...}

internal A G() {...}

public A H() {...}
}

the H method in B results in a compile-time error because the return type A is not at least as accessible as the method.

Signatures and overloading

Methods, instance constructors, indexers, and operators are characterized by their signatures:

· The signature of a method consists of the name of the method, the number of type parameters and the type and kind (value, reference, or output) of each of its formal parameters, considered in the order left to right. For these purposes, any type parameter of the method that occurs in the type of a formal parameter is identified not by its name, but by its ordinal position in the type argument list of the method. The signature of a method specifically does not include the return type, the params modifier that may be specified for the right-most parameter, nor the optional type parameter constraints.

· The signature of an instance constructor consists of the type and kind (value, reference, or output) of each of its formal parameters, considered in the order left to right. The signature of an instance constructor specifically does not include the params modifier that may be specified for the right-most parameter.

· The signature of an indexer consists of the type of each of its formal parameters, considered in the order left to right. The signature of an indexer specifically does not include the element type, nor does it include the paramsmodifier that may be specified for the right-most parameter.

· The signature of an operator consists of the name of the operator and the type of each of its formal parameters, considered in the order left to right. The signature of an operator specifically does not include the result type.

Signatures are the enabling mechanism for overloading of members in classes, structs, and interfaces:

· Overloading of methods permits a class, struct, or interface to declare multiple methods with the same name, provided their signatures are unique within that class, struct, or interface.

· Overloading of instance constructors permits a class or struct to declare multiple instance constructors, provided their signatures are unique within that class or struct.

· Overloading of indexers permits a class, struct, or interface to declare multiple indexers, provided their signatures are unique within that class, struct, or interface.

· Overloading of operators permits a class or struct to declare multiple operators with the same name, provided their signatures are unique within that class or struct.

Although out and ref parameter modifiers are considered part of a signature, members declared in a single type cannot differ in signature solely by ref and out. A compile-time error occurs if two members are declared in the same type with signatures that would be the same if all parameters in both methods with out modifiers were changed to ref modifiers. For other purposes of signature matching (e.g., hiding or overriding), ref and out are considered part of the signature and do not match each other. (This restriction is to allow C# programs to be easily translated to run on the Common Language Infrastructure (CLI), which does not provide a way to define methods that differ solely in ref and out.)

For the purposes of singatures, the types object and dynamic are considered the same. Members declared in a single type can therefore not differ in signature solely by object and dynamic.

The following example shows a set of overloaded method declarations along with their signatures.

interface ITest
{
void F(); // F()

void F(int x); // F(int)

void F(ref int x); // F(ref int)

void F(out int x); // F(out int) error

void F(int x, int y); // F(int, int)

int F(string s); // F(string)

int F(int x); // F(int) error

void F(string[] a); // F(string[])

void F(params string[] a); // F(string[]) error
}

Note that any ref and out parameter modifiers (§10.6.1) are part of a signature. Thus, F(int) and F(ref int) are unique signatures. However, F(ref int) and F(out int) cannot be declared within the same interface because their signatures differ solely by ref and out. Also, note that the return type and the params modifier are not part of a signature, so it is not possible to overload solely based on return type or on the inclusion or exclusion of the params modifier. As such, the declarations of the methods F(int) and F(params string[]) identified above result in a compile-time error.

Scopes

The scope of a name is the region of program text within which it is possible to refer to the entity declared by the name without qualification of the name. Scopes can be nested, and an inner scope may redeclare the meaning of a name from an outer scope (this does not, however, remove the restriction imposed by §3.3 that within a nested block it is not possible to declare a local variable with the same name as a local variable in an enclosing block). The name from the outer scope is then said to be hidden in the region of program text covered by the inner scope, and access to the outer name is only possible by qualifying the name.

· The scope of a namespace member declared by a namespace-member-declaration (§9.5) with no enclosing namespace-declaration is the entire program text.

· The scope of a namespace member declared by a namespace-member-declaration within a namespace-declaration whose fully qualified name is N is the namespace-body of every namespace-declaration whose fully qualified name is N or starts with N, followed by a period.

· The scope of name defined by an extern-alias-directive extends over the using-directives, global-attributes and namespace-member-declarations of its immediately containing compilation unit or namespace body. An extern-alias-directive does not contribute any new members to the underlying declaration space. In other words, an extern-alias-directive is not transitive, but, rather, affects only the compilation unit or namespace body in which it occurs.

· The scope of a name defined or imported by a using-directive (§9.4) extends over the namespace-member-declarations of the compilation-unit or namespace-body in which the using-directive occurs. A using-directive may make zero or more namespace or type names available within a particular compilation-unit or namespace-body, but does not contribute any new members to the underlying declaration space. In other words, a using-directive is not transitive but rather affects only the compilation-unit or namespace-body in which it occurs.

· The scope of a type parameter declared by a type-parameter-list on a class-declaration (§10.1) is the class-base, type-parameter-constraints-clauses, and class-body of that class-declaration.

· The scope of a type parameter declared by a type-parameter-list on a struct-declaration (§11.1) is the struct-interfaces, type-parameter-constraints-clauses, and struct-body of that struct-declaration.

· The scope of a type parameter declared by a type-parameter-list on an interface-declaration (§13.1) is the interface-base, type-parameter-constraints-clauses, and interface-body of that interface-declaration.

· The scope of a type parameter declared by a type-parameter-list on a delegate-declaration (§15.1) is the return-type, formal-parameter-list, and type-parameter-constraints-clauses of that delegate-declaration.

· The scope of a member declared by a class-member-declaration (§10.1.6) is the class-body in which the declaration occurs. In addition, the scope of a class member extends to the class-body of those derived classes that are included in the accessibility domain (§3.5.2) of the member.

· The scope of a member declared by a struct-member-declaration (§11.2) is the struct-body in which the declaration occurs.

· The scope of a member declared by an enum-member-declaration (§14.3) is the enum-body in which the declaration occurs.

· The scope of a parameter declared in a method-declaration (§10.6) is the method-body of that method-declaration.

· The scope of a parameter declared in an indexer-declaration (§10.9) is the accessor-declarations of that indexer-declaration.

· The scope of a parameter declared in an operator-declaration (§10.10) is the block of that operator-declaration.

· The scope of a parameter declared in a constructor-declaration (§10.11) is the constructor-initializer and block of that constructor-declaration.

· The scope of a parameter declared in a lambda-expression (§7.15) is the lambda-expression-body of that lambda-expression

· The scope of a parameter declared in an anonymous-method-expression (§7.15) is the block of that anonymous-method-expression.

· The scope of a label declared in a labeled-statement (§8.4) is the block in which the declaration occurs.

· The scope of a local variable declared in a local-variable-declaration (§8.5.1) is the block in which the declaration occurs.

· The scope of a local variable declared in a switch-block of a switch statement (§8.7.2) is the switch-block.

· The scope of a local variable declared in a for-initializer of a for statement (§8.8.3) is the for-initializer, the for-condition, the for-iterator, and the contained statement of the for statement.

· The scope of a local constant declared in a local-constant-declaration (§8.5.2) is the block in which the declaration occurs. It is a compile-time error to refer to a local constant in a textual position that precedes its constant-declarator.

· The scope of a variable declared as part of a foreach-statement, using-statement, lock-statement or query-expression is determined by the expansion of the given construct.

Within the scope of a namespace, class, struct, or enumeration member it is possible to refer to the member in a textual position that precedes the declaration of the member. For example

class A
{
void F() {
i = 1;
}

int i = 0;
}

Here, it is valid for F to refer to i before it is declared.

Within the scope of a local variable, it is a compile-time error to refer to the local variable in a textual position that precedes the local-variable-declarator of the local variable. For example

class A
{
int i = 0;

void F() {
i = 1; // Error, use precedes declaration
int i;
i = 2;
}

void G() {
int j = (j = 1); // Valid
}

void H() {
int a = 1, b = ++a; // Valid
}
}

In the F method above, the first assignment to i specifically does not refer to the field declared in the outer scope. Rather, it refers to the local variable and it results in a compile-time error because it textually precedes the declaration of the variable. In the G method, the use of j in the initializer for the declaration of j is valid because the use does not precede the local-variable-declarator. In the H method, a subsequent local-variable-declarator correctly refers to a local variable declared in an earlier local-variable-declarator within the same local-variable-declaration.

The scoping rules for local variables are designed to guarantee that the meaning of a name used in an expression context is always the same within a block. If the scope of a local variable were to extend only from its declaration to the end of the block, then in the example above, the first assignment would assign to the instance variable and the second assignment would assign to the local variable, possibly leading to compile-time errors if the statements of the block were later to be rearranged.

The meaning of a name within a block may differ based on the context in which the name is used. In the example

using System;

class A {}

class Test
{
static void Main() {
string A = "hello, world";
string s = A; // expression context

Type t = typeof(A); // type context

Console.WriteLine(s); // writes "hello, world"
Console.WriteLine(t); // writes "A"
}
}

the name A is used in an expression context to refer to the local variable A and in a type context to refer to the class A.

Name hiding

The scope of an entity typically encompasses more program text than the declaration space of the entity. In particular, the scope of an entity may include declarations that introduce new declaration spaces containing entities of the same name. Such declarations cause the original entity to become hidden. Conversely, an entity is said to be visible when it is not hidden.

Name hiding occurs when scopes overlap through nesting and when scopes overlap through inheritance. The characteristics of the two types of hiding are described in the following sections.

Hiding through nesting

Name hiding through nesting can occur as a result of nesting namespaces or types within namespaces, as a result of nesting types within classes or structs, and as a result of parameter and local variable declarations.

In the example

class A
{
int i = 0;

void F() {
int i = 1;
}

void G() {
i = 1;
}
}

within the F method, the instance variable i is hidden by the local variable i, but within the G method, i still refers to the instance variable.

When a name in an inner scope hides a name in an outer scope, it hides all overloaded occurrences of that name. In the example

class Outer
{
static void F(int i) {}

static void F(string s) {}

class Inner
{
void G() {
F(1); // Invokes Outer.Inner.F
F("Hello"); // Error
}

static void F(long l) {}
}
}

the call F(1) invokes the F declared in Inner because all outer occurrences of F are hidden by the inner declaration. For the same reason, the call F("Hello") results in a compile-time error.

Hiding through inheritance

Name hiding through inheritance occurs when classes or structs redeclare names that were inherited from base classes. This type of name hiding takes one of the following forms:

· A constant, field, property, event, or type introduced in a class or struct hides all base class members with the same name.

· A method introduced in a class or struct hides all non-method base class members with the same name, and all base class methods with the same signature (method name and parameter count, modifiers, and types).

· An indexer introduced in a class or struct hides all base class indexers with the same signature (parameter count and types).

The rules governing operator declarations (§10.10) make it impossible for a derived class to declare an operator with the same signature as an operator in a base class. Thus, operators never hide one another.

Contrary to hiding a name from an outer scope, hiding an accessible name from an inherited scope causes a warning to be reported. In the example

class Base
{
public void F() {}
}

class Derived: Base
{
public void F() {} // Warning, hiding an inherited name
}

the declaration of F in Derived causes a warning to be reported. Hiding an inherited name is specifically not an error, since that would preclude separate evolution of base classes. For example, the above situation might have come about because a later version of Base introduced an F method that wasn’t present in an earlier version of the class. Had the above situation been an error, then any change made to a base class in a separately versioned class library could potentially cause derived classes to become invalid.

The warning caused by hiding an inherited name can be eliminated through use of the new modifier:

class Base
{
public void F() {}
}

class Derived: Base
{
new public void F() {}
}

The new modifier indicates that the F in Derived is “new”, and that it is indeed intended to hide the inherited member.

A declaration of a new member hides an inherited member only within the scope of the new member.

class Base
{
public static void F() {}
}

class Derived: Base
{
new private static void F() {} // Hides Base.F in Derived only
}

class MoreDerived: Derived
{
static void G() { F(); } // Invokes Base.F
}

In the example above, the declaration of F in Derived hides the F that was inherited from Base, but since the new F in Derived has private access, its scope does not extend to MoreDerived. Thus, the call F() in MoreDerived.G is valid and will invoke Base.F.

Namespace and type names

Several contexts in a C# program require a namespace-name or a type-name to be specified.

namespace-name:
namespace-or-type-name

type-name:
namespace-or-type-name

namespace-or-type-name:
identifier type-argument-list_opt
namespace-or-type-name. identifier type-argument-list_opt
qualified-alias-member

A namespace-name is a namespace-or-type-name that refers to a namespace. Following resolution as described below, the namespace-or-type-name of a namespace-name must refer to a namespace, or otherwise a compile-time error occurs. No type arguments (§4.4.1) can be present in a namespace-name (only types can have type arguments).

A type-name is a namespace-or-type-name that refers to a type. Following resolution as described below, the namespace-or-type-name of a type-name must refer to a type, or otherwise a compile-time error occurs.

If the namespace-or-type-name is a qualified-alias-member its meaning is as described in §9.7. Otherwise, a namespace-or-type-name has one of four forms:

· I

· I<A₁,..., A_K>

· N.I

· N.I<A₁,..., A_K>

where I is a single identifier, N is a namespace-or-type-name and <A₁,..., A_K> is an optional type-argument-list. When no type-argument-list is specified, consider K to be zero.

The meaning of a namespace-or-type-name is determined as follows:

· If the namespace-or-type-name is of the form I or of the form I<A₁,..., A_K>:

o If K is zero and the namespace-or-type-name appears within a generic method declaration (§10.6) and if that declaration includes a type parameter (§10.1.3) with name I, then the namespace-or-type-name refers to that type parameter.

o Otherwise, if the namespace-or-type-name appears within a type declaration, then for each instance type T (§10.3.1), starting with the instance type of that type declaration and continuing with the instance type of each enclosing class or struct declaration (if any):

· If K is zero and the declaration of T includes a type parameter with name I, then the namespace-or-type-name refers to that type parameter.

· Otherwise, if the namespace-or-type-name appears within the body of the type declaration, and T or any of its base types contain a nested accessible type having name I and K type parameters, then the namespace-or-type-name refers to that type constructed with the given type arguments. If there is more than one such type, the type declared within the more derived type is selected. Note that non-type members (constants, fields, methods, properties, indexers, operators, instance constructors, destructors, and static constructors) and type members with a different number of type parameters are ignored when determining the meaning of the namespace-or-type-name.

o If the previous steps were unsuccessful then, for each namespace N, starting with the namespace in which the namespace-or-type-name occurs, continuing with each enclosing namespace (if any), and ending with the global namespace, the following steps are evaluated until an entity is located:

· If K is zero and I is the name of a namespace in N, then:

o If the location where the namespace-or-type-name occurs is enclosed by a namespace declaration for N and the namespace declaration contains an extern-alias-directive or using-alias-directive that associates the name I with a namespace or type, then the namespace-or-type-name is ambiguous and a compile-time error occurs.

o Otherwise, the namespace-or-type-name refers to the namespace named I in N.

· Otherwise, if N contains an accessible type having name I and K type parameters, then:

o If K is zero and the location where the namespace-or-type-name occurs is enclosed by a namespace declaration for N and the namespace declaration contains an extern-alias-directive or using-alias-directive that associates the name I with a namespace or type, then the namespace-or-type-name is ambiguous and a compile-time error occurs.

o Otherwise, the namespace-or-type-name refers to the type constructed with the given type arguments.

· Otherwise, if the location where the namespace-or-type-name occurs is enclosed by a namespace declaration for N:

o If K is zero and the namespace declaration contains an extern-alias-directive or using-alias-directive that associates the name I with an imported namespace or type, then the namespace-or-type-name refers to that namespace or type.

o Otherwise, if the namespaces imported by the using-namespace-directives of the namespace declaration contain exactly one type having name I and K type parameters, then the namespace-or-type-name refers to that type constructed with the given type arguments.

o Otherwise, if the namespaces imported by the using-namespace-directives of the namespace declaration contain more than one type having name I and K type parameters, then the namespace-or-type-name is ambiguous and an error occurs.

o Otherwise, the namespace-or-type-name is undefined and a compile-time error occurs.

· Otherwise, the namespace-or-type-name is of the form N.I or of the form N.I<A₁,..., A_K>. N is first resolved as a namespace-or-type-name. If the resolution of N is not successful, a compile-time error occurs. Otherwise, N.I or N.I<A₁,..., A_K> is resolved as follows:

o If K is zero and N refers to a namespace and N contains a nested namespace with name I, then the namespace-or-type-name refers to that nested namespace.

o Otherwise, if N refers to a namespace and N contains an accessible type having name I and K type parameters, then the namespace-or-type-name refers to that type constructed with the given type arguments.

o Otherwise, if N refers to a (possibly constructed) class or struct type and N or any of its base classes contain a nested accessible type having name I and K type parameters, then the namespace-or-type-name refers to that type constructed with the given type arguments. If there is more than one such type, the type declared within the more derived type is selected. Note that if the meaning of N.I is being determined as part of resolving the base class specification of N then the direct base class of N is considered to be object (§10.1.4.1).

o Otherwise, N.I is an invalid namespace-or-type-name, and a compile-time error occurs.

A namespace-or-type-name is permitted to reference a static class (§10.1.1.3) only if

· The namespace-or-type-name is the T in a namespace-or-type-name of the form T.I, or

· The namespace-or-type-name is the T in a typeof-expression (§7.5.11) of the form typeof(T).

Fully qualified names

Every namespace and type has a fully qualified name, which uniquely identifies the namespace or type amongst all others. The fully qualified name of a namespace or type N is determined as follows:

· If N is a member of the global namespace, its fully qualified name is N.

· Otherwise, its fully qualified name is S.N, where S is the fully qualified name of the namespace or type in which N is declared.

In other words, the fully qualified name of N is the complete hierarchical path of identifiers that lead to N, starting from the global namespace. Because every member of a namespace or type must have a unique name, it follows that the fully qualified name of a namespace or type is always unique.

The example below shows several namespace and type declarations along with their associated fully qualified names.

class A {} // A

namespace X // X
{
class B // X.B
{
class C {} // X.B.C
}

namespace Y // X.Y
{
class D {} // X.Y.D
}
}

namespace X.Y // X.Y
{
class E {} // X.Y.E
}

Automatic memory management

C# employs automatic memory management, which frees developers from manually allocating and freeing the memory occupied by objects. Automatic memory management policies are implemented by a garbage collector. The memory management life cycle of an object is as follows:

1. When the object is created, memory is allocated for it, the constructor is run, and the object is considered live.

2. If the object, or any part of it, cannot be accessed by any possible continuation of execution, other than the running of destructors, the object is considered no longer in use, and it becomes eligible for destruction. The C# compiler and the garbage collector may choose to analyze code to determine which references to an object may be used in the future. For instance, if a local variable that is in scope is the only existing reference to an object, but that local variable is never referred to in any possible continuation of execution from the current execution point in the procedure, the garbage collector may (but is not required to) treat the object as no longer in use.

3. Once the object is eligible for destruction, at some unspecified later time the destructor (§10.13) (if any) for the object is run. Under normal circumstances the destructor for the object is run once only, though implementation-specific APIs may allow this behavior to be overridden.

4. Once the destructor for an object is run, if that object, or any part of it, cannot be accessed by any possible continuation of execution, including the running of destructors, the object is considered inaccessible and the object becomes eligible for collection.

5. Finally, at some time after the object becomes eligible for collection, the garbage collector frees the memory associated with that object.

The garbage collector maintains information about object usage, and uses this information to make memory management decisions, such as where in memory to locate a newly created object, when to relocate an object, and when an object is no longer in use or inaccessible.

Like other languages that assume the existence of a garbage collector, C# is designed so that the garbage collector may implement a wide range of memory management policies. For instance, C# does not require that destructors be run or that objects be collected as soon as they are eligible, or that destructors be run in any particular order, or on any particular thread.

The behavior of the garbage collector can be controlled, to some degree, via static methods on the class System.GC. This class can be used to request a collection to occur, destructors to be run (or not run), and so forth.

Since the garbage collector is allowed wide latitude in deciding when to collect objects and run destructors, a conforming implementation may produce output that differs from that shown by the following code. The program

using System;

class A
{
~A() {
Console.WriteLine("Destruct instance of A");
}
}

class B
{
object Ref;

public B(object o) {
Ref = o;
}

~B() {
Console.WriteLine("Destruct instance of B");
}
}

class Test
{
static void Main() {
B b = new B(new A());
b = null;
GC.Collect();
GC.WaitForPendingFinalizers();
}
}

creates an instance of class A and an instance of class B. These objects become eligible for garbage collection when the variable b is assigned the value null, since after this time it is impossible for any user-written code to access them. The output could be either

Destruct instance of A
Destruct instance of B

or

Destruct instance of B
Destruct instance of A

because the language imposes no constraints on the order in which objects are garbage collected.

In subtle cases, the distinction between “eligible for destruction” and “eligible for collection” can be important. For example,

using System;

class A
{
~A() {
Console.WriteLine("Destruct instance of A");
}

public void F() {
Console.WriteLine("A.F");
Test.RefA = this;
}
}

class B
{
public A Ref;

~B() {
Console.WriteLine("Destruct instance of B");
Ref.F();
}
}

class Test
{
public static A RefA;
public static B RefB;

static void Main() {
RefB = new B();
RefA = new A();
RefB.Ref = RefA;
RefB = null;
RefA = null;

// A and B now eligible for destruction
GC.Collect();
GC.WaitForPendingFinalizers();

// B now eligible for collection, but A is not
if (RefA!= null)
Console.WriteLine("RefA is not null");
}
}

In the above program, if the garbage collector chooses to run the destructor of A before the destructor of B, then the output of this program might be:

Destruct instance of A
Destruct instance of B
A.F
RefA is not null

Note that although the instance of A was not in use and A’s destructor was run, it is still possible for methods of A (in this case, F) to be called from another destructor. Also, note that running of a destructor may cause an object to become usable from the mainline program again. In this case, the running of B’s destructor caused an instance of A that was previously not in use to become accessible from the live reference Test.RefA. After the call to WaitForPendingFinalizers, the instance of B is eligible for collection, but the instance of A is not, because of the reference Test.RefA.

To avoid confusion and unexpected behavior, it is generally a good idea for destructors to only perform cleanup on data stored in their object's own fields, and not to perform any actions on referenced objects or static fields.

An alternative to using destructors is to let a class implement the System.IDisposable interface. This allows the client of the object to determine when to release the resources of the object, typically by accessing the object as a resource in a using statement (§8.13).

Execution order

Execution of a C# program proceeds such that the side effects of each executing thread are preserved at critical execution points. A side effectis defined as a read or write of a volatile field, a write to a non-volatile variable, a write to an external resource, and the throwing of an exception. The critical execution points at which the order of these side effects must be preserved are references to volatile fields (§10.5.3), lock statements (§8.12), and thread creation and termination. The execution environment is free to change the order of execution of a C# program, subject to the following constraints:

· Data dependence is preserved within a thread of execution. That is, the value of each variable is computed as if all statements in the thread were executed in original program order.

· Initialization ordering rules are preserved (§10.5.4 and §10.5.5).

· The ordering of side effects is preserved with respect to volatile reads and writes (§10.5.3). Additionally, the execution environment need not evaluate part of an expression if it can deduce that that expression’s value is not used and that no needed side effects are produced (including any caused by calling a method or accessing a volatile field). When program execution is interrupted by an asynchronous event (such as an exception thrown by another thread), it is not guaranteed that the observable side effects are visible in the original program order.

Types

The types of the C# language are divided into two main categories: Value types and reference types. Both value types and reference types may be generic types, which take one or more type parameters. Type parameters can designate both value types and reference types.

type:
value-type
reference-type
type-parameter

A third category of types, pointers, is available only in unsafe code. This is discussed further in §18.2.

Value types differ from reference types in that variables of the value types directly contain their data, whereas variables of the reference types store references to their data, the latter being known as objects. With reference types, it is possible for two variables to reference the same object, and thus possible for operations on one variable to affect the object referenced by the other variable. With value types, the variables each have their own copy of the data, and it is not possible for operations on one to affect the other.

C#’s type system is unified such that a value of any type can be treated as an object. Every type in C# directly or indirectly derives from the object class type, and object is the ultimate base class of all types. Values of reference types are treated as objects simply by viewing the values as type object. Values of value types are treated as objects by performing boxing and unboxing operations (§4.3).

Value types

A value type is either a struct type or an enumeration type. C# provides a set of predefined struct types called the simple types. The simple types are identified through reserved words.

value-type:
struct-type
enum-type

struct-type:
type-name
simple-type
nullable-type

simple-type:
numeric-type
bool

numeric-type:
integral-type
floating-point-type
decimal

integral-type:
sbyte
byte
short
ushort
int
uint
long
ulong
char

floating-point-type:
float
double

nullable-type:
non-nullable-value-type?

non-nullable-value-type:
type

enum-type:
type-name

Unlike a variable of a reference type, a variable of a value type can contain the value null only if the value type is a nullable type. For every non-nullable value type there is a corresponding nullable value type denoting the same set of values plus the value null.

Assignment to a variable of a value type creates a copy of the value being assigned. This differs from assignment to a variable of a reference type, which copies the reference but not the object identified by the reference.

The System.ValueType type

All value types implicitly inherit from the class System.ValueType, which, in turn, inherits from class object. It is not possible for any type to derive from a value type, and value types are thus implicitly sealed (§10.1.1.2).

Note that System.ValueType is not itself a value-type. Rather, it is a class-type from which all value-types are automatically derived.

Default constructors

All value types implicitly declare a public parameterless instance constructor called the default constructor. The default constructor returns a zero-initialized instance known as the default value for the value type:

· For all simple-types, the default value is the value produced by a bit pattern of all zeros:

o For sbyte, byte, short, ushort, int, uint, long, and ulong, the default value is 0.

o For char, the default value is '\x0000'.

o For float, the default value is 0.0f.

o For double, the default value is 0.0d.

o For decimal, the default value is 0.0m.

o For bool, the default value is false.

· For an enum-type E, the default value is 0, converted to the type E.

· For a struct-type, the default value is the value produced by setting all value type fields to their default value and all reference type fields to null.

· For a nullable-type the default value is an instance for which the HasValue property is false and the Value property is undefined. The default value is also known as the null value of the nullable type.

Like any other instance constructor, the default constructor of a value type is invoked using the new operator. For efficiency reasons, this requirement is not intended to actually have the implementation generate a constructor call. In the example below, variables i and j are both initialized to zero.

class A
{
void F() {
int i = 0;
int j = new int();
}
}

Because every value type implicitly has a public parameterless instance constructor, it is not possible for a struct type to contain an explicit declaration of a parameterless constructor. A struct type is however permitted to declare parameterized instance constructors (§11.3.8).

Struct types

A struct type is a value type that can declare constants, fields, methods, properties, indexers, operators, instance constructors, static constructors, and nested types. The declaration of struct types is described in §11.1.

Simple types

C# provides a set of predefined struct types called the simple types. The simple types are identified through reserved words, but these reserved words are simply aliases for predefined struct types in the System namespace, as described in the table below.

 

Reserved word	Aliased type
sbyte	System.SByte
byte	System.Byte
short	System.Int16
ushort	System.UInt16
int	System.Int32
uint	System.UInt32
long	System.Int64
ulong	System.UInt64
char	System.Char
float	System.Single
double	System.Double
bool	System.Boolean
decimal	System.Decimal

 

Because a simple type aliases a struct type, every simple type has members. For example, int has the members declared in System.Int32 and the members inherited from System.Object, and the following statements are permitted:

int i = int.MaxValue; // System.Int32.MaxValue constant
string s = i.ToString(); // System.Int32.ToString() instance method
string t = 123.ToString(); // System.Int32.ToString() instance method

The simple types differ from other struct types in that they permit certain additional operations:

· Most simple types permit values to be created by writing literals (§2.4.4). For example, 123 is a literal of type int and 'a' is a literal of type char. C# makes no provision for literals of struct types in general, and non-default values of other struct types are ultimately always created through instance constructors of those struct types.

· When the operands of an expression are all simple type constants, it is possible for the compiler to evaluate the expression at compile-time. Such an expression is known as a constant-expression (§7.19). Expressions involving operators defined by other struct types are not considered to be constant expressions.

· Through const declarations it is possible to declare constants of the simple types (§10.4). It is not possible to have constants of other struct types, but a similar effect is provided by static readonly fields.

· Conversions involving simple types can participate in evaluation of conversion operators defined by other struct types, but a user-defined conversion operator can never participate in evaluation of another user-defined operator (§6.4.3).

Integral types

C# supports nine integral types: sbyte, byte, short, ushort, int, uint, long, ulong, and char. The integral types have the following sizes and ranges of values:

· The sbyte type represents signed 8-bit integers with values between –128 and 127.

· The byte type represents unsigned 8-bit integers with values between 0 and 255.

· The short type represents signed 16-bit integers with values between –32768 and 32767.

· The ushort type represents unsigned 16-bit integers with values between 0 and 65535.

· The int type represents signed 32-bit integers with values between –2147483648 and 2147483647.

· The uint type represents unsigned 32-bit integers with values between 0 and 4294967295.

· The long type represents signed 64-bit integers with values between –9223372036854775808 and 9223372036854775807.

· The ulong type represents unsigned 64-bit integers with values between 0 and 18446744073709551615.

· The char type represents unsigned 16-bit integers with values between 0 and 65535. The set of possible values for the char type corresponds to the Unicode character set. Although char has the same representation as ushort, not all operations permitted on one type are permitted on the other.

The integral-type unary and binary operators always operate with signed 32-bit precision, unsigned 32-bit precision, signed 64-bit precision, or unsigned 64-bit precision:

· For the unary + and ~ operators, the operand is converted to type T, where T is the first of int, uint, long, and ulong that can fully represent all possible values of the operand. The operation is then performed using the precision of type T, and the type of the result is T.

· For the unary – operator, the operand is converted to type T, where T is the first of int and long that can fully represent all possible values of the operand. The operation is then performed using the precision of type T, and the type of the result is T. The unary – operator cannot be applied to operands of type ulong.

· For the binary +, –, *, /, %, &, ^, |, ==,!=, >, <, >=, and <= operators, the operands are converted to type T, where T is the first of int, uint, long, and ulong that can fully represent all possible values of both operands. The operation is then performed using the precision of type T, and the type of the result is T (or bool for the relational operators). It is not permitted for one operand to be of type long and the other to be of type ulong with the binary operators.

· For the binary << and >> operators, the left operand is converted to type T, where T is the first of int, uint, long, and ulong that can fully represent all possible values of the operand. The operation is then performed using the precision of type T, and the type of the result is T.

The char type is classified as an integral type, but it differs from the other integral types in two ways:

· There are no implicit conversions from other types to the char type. In particular, even though the sbyte, byte, and ushort types have ranges of values that are fully representable using the char type, implicit conversions from sbyte, byte, or ushort to char do not exist.

· Constants of the char type must be written as character-literals or as integer-literals in combination with a cast to type char. For example, (char)10 is the same as '\x000A'.

The checked and unchecked operators and statements are used to control overflow checking for integral-type arithmetic operations and conversions (§7.6.12). In a checked context, an overflow produces a compile-time error or causes a System.OverflowException to be thrown. In an unchecked context, overflows are ignored and any high-order bits that do not fit in the destination type are discarded.

Floating point types

C# supports two floating point types: float and double. The float and double types are represented using the 32-bit single-precision and 64-bit double-precision IEEE 754 formats, which provide the following sets of values:

· Positive zero and negative zero. In most situations, positive zero and negative zero behave identically as the simple value zero, but certain operations distinguish between the two (§7.8.2).

· Positive infinity and negative infinity. Infinities are produced by such operations as dividing a non-zero number by zero. For example, 1.0 / 0.0 yields positive infinity, and –1.0 / 0.0 yields negative infinity.

· The Not-a-Number value, often abbreviated NaN. NaNs are produced by invalid floating-point operations, such as dividing zero by zero.

· The finite set of non-zero values of the form s × m × 2^e, where s is 1 or −1, and m and e are determined by the particular floating-point type: For float, 0 < m < 2²⁴ and −149 ≤ e ≤ 104, and for double, 0 < m < 2⁵³ and −1075 ≤ e ≤ 970. Denormalized floating-point numbers are considered valid non-zero values.

The float type can represent values ranging from approximately 1.5 × 10⁻⁴⁵ to 3.4 × 10³⁸ with a precision of 7 digits.

The double type can represent values ranging from approximately 5.0 × 10⁻³²⁴ to 1.7 × 10³⁰⁸ with a precision of 15-16 digits.

If one of the operands of a binary operator is of a floating-point type, then the other operand must be of an integral type or a floating-point type, and the operation is evaluated as follows:

· If one of the operands is of an integral type, then that operand is converted to the floating-point type of the other operand.

· Then, if either of the operands is of type double, the other operand is converted to double, the operation is performed using at least double range and precision, and the type of the result is double (or bool for the relational operators).

· Otherwise, the operation is performed using at least float range and precision, and the type of the result is float (or bool for the relational operators).

The floating-point operators, including the assignment operators, never produce exceptions. Instead, in exceptional situations, floating-point operations produce zero, infinity, or NaN, as described below:

· If the result of a floating-point operation is too small for the destination format, the result of the operation becomes positive zero or negative zero.

· If the result of a floating-point operation is too large for the destination format, the result of the operation becomes positive infinity or negative infinity.

· If a floating-point operation is invalid, the result of the operation becomes NaN.

· If one or both operands of a floating-point operation is NaN, the result of the operation becomes NaN.

Floating-point operations may be performed with higher precision than the result type of the operation. For example, some hardware architectures support an “extended” or “long double” floating-point type with greater range and precision than the double type, and implicitly perform all floating-point operations using this higher precision type. Only at excessive cost in performance can such hardware architectures be made to perform floating-point operations with less precision, and rather than require an implementation to forfeit both performance and precision, C# allows a higher precision type to be used for all floating-point operations. Other than delivering more precise results, this rarely has any measurable effects. However, in expressions of the form x * y / z, where the multiplication produces a result that is outside the double range, but the subsequent division brings the temporary result back into the double range, the fact that the expression is evaluated in a higher range format may cause a finite result to be produced instead of an infinity.

The decimal type

The decimal type is a 128-bit data type suitable for financial and monetary calculations. The decimal type can represent values ranging from 1.0 × 10⁻²⁸ to approximately 7.9 × 10²⁸ with 28-29 significant digits.

The finite set of values of type decimal are of the form (–1)^s × c × 10^-e, where the sign s is 0 or 1, the coefficient c is given by 0 ≤ c < 2⁹⁶, and the scale e is such that 0 ≤ e ≤ 28.The decimal type does not support signed zeros, infinities, or NaN's. A decimal is represented as a 96-bit integer scaled by a power of ten. For decimals with an absolute value less than 1.0m, the value is exact to the 28^th decimal place, but no further. For decimals with an absolute value greater than or equal to 1.0m, the value is exact to 28 or 29 digits. Contrary to the float and double data types, decimal fractional numbers such as 0.1 can be represented exactly in the decimal representation. In the float and double representations, such numbers are often infinite fractions, making those representations more prone to round-off errors.

If one of the operands of a binary operator is of type decimal, then the other operand must be of an integral type or of type decimal. If an integral type operand is present, it is converted to decimal before the operation is performed.

The result of an operation on values of type decimal is that which would result from calculating an exact result (preserving scale, as defined for each operator) and then rounding to fit the representation. Results are rounded to the nearest representable value, and, when a result is equally close to two representable values, to the value that has an even number in the least significant digit position (this is known as “banker’s rounding”). A zero result always has a sign of 0 and a scale of 0.

If a decimal arithmetic operation produces a value less than or equal to 5 × 10^-29 in absolute value, the result of the operation becomes zero. If a decimal arithmetic operation produces a result that is too large for the decimal format, a System.OverflowException is thrown.

The decimal type has greater precision but smaller range than the floating-point types. Thus, conversions from the floating-point types to decimal might produce overflow exceptions, and conversions from decimal to the floating-point types might cause loss of precision. For these reasons, no implicit conversions exist between the floating-point types and decimal, and without explicit casts, it is not possible to mix floating-point and decimal operands in the same expression.

The bool type

The bool type represents boolean logical quantities. The possible values of type bool are true and false.

No standard conversions exist between bool and other types. In particular, the bool type is distinct and separate from the integral types, and a bool value cannot be used in place of an integral value, and vice versa.

In the C and C++ languages, a zero integral or floating-point value, or a null pointer can be converted to the boolean value false, and a non-zero integral or floating-point value, or a non-null pointer can be converted to the boolean value true. In C#, such conversions are accomplished by explicitly comparing an integral or floating-point value to zero, or by explicitly comparing an object reference to null.

Enumeration types

An enumeration type is a distinct type with named constants. Every enumeration type has an underlying type, which must be byte, sbyte, short, ushort, int, uint, long or ulong. The set of values of the enumeration type is the same as the set of values of the underlying type. Values of the enumeration type are not restricted to the values of the named constants. Enumeration types are defined through enumeration declarations (§14.1).

Nullable types

A nullable type can represent all values of its underlying type plus an additional null value. A nullable type is written T?, where T is the underlying type. This syntax is shorthand for System.Nullable<T>, and the two forms can be used interchangeably.

A non-nullable value type conversely is any value type other than System.Nullable<T> and its shorthand T? (for any T), plus any type parameter that is constrained to be a non-nullable value type (that is, any type parameter with a struct constraint). The System.Nullable<T> type specifies the value type constraint for T (§10.1.5), which means that the underlying type of a nullable type can be any non-nullable value type. The underlying type of a nullable type cannot be a nullable type or a reference type. For example, int?? and string? are invalid types.

An instance of a nullable type T? has two public read-only properties:

· A HasValue property of type bool

· A Value property of type T

An instance for which HasValue is true is said to be non-null. A non-null instance contains a known value and Value returns that value.

An instance for which HasValue is false is said to be null. A null instance has an undefined value. Attempting to read the Value of a null instance causes a System.InvalidOperationException to be thrown. The process of accessing the Value property of a nullable instance is referred to as unwrapping.

In addition to the default constructor, every nullable type T? has a public constructor that takes a single argument of type T. Given a value x of type T, a constructor invocation of the form

new T?(x)

creates a non-null instance of T? for which the Value property is x. The process of creating a non-null instance of a nullable type for a given value is referred to as wrapping.

Implicit conversions are available from the null literal to T? (§6.1.5) and from T to T? (§6.1.4).

Reference types

A reference type is a class type, an interface type, an array type, or a delegate type.

reference-type:
class-type
interface-type
array-type
delegate-type

class-type:
type-name
object
dynamic
string

interface-type:
type-name

array-type:
non-array-type rank-specifiers

non-array-type:
type

rank-specifiers:
rank-specifier
rank-specifiers rank-specifier

rank-specifier:
[ dim-separators_opt ]

dim-separators:
,
dim-separators,

delegate-type:
type-name

A reference type value is a reference to an instance of the type, the latter known as an object. The special value null is compatible with all reference types and indicates the absence of an instance.

Class types

A class type defines a data structure that contains data members (constants and fields), function members (methods, properties, events, indexers, operators, instance constructors, destructors and static constructors), and nested types. Class types support inheritance, a mechanism whereby derived classes can extend and specialize base classes. Instances of class types are created using object-creation-expressions (§7.6.10.1).

Class types are described in §10.

Certain predefined class types have special meaning in the C# language, as described in the table below.

 

Class type	Description
System.Object	The ultimate base class of all other types. See §4.2.2.
System.String	The string type of the C# language. See §4.2.4.
System.ValueType	The base class of all value types. See §4.1.1.
System.Enum	The base class of all enum types. See §14.
System.Array	The base class of all array types. See §12.
System.Delegate	The base class of all delegate types. See §15.
System.Exception	The base class of all exception types. See §16.

 

The object type

The object class type is the ultimate base class of all other types. Every type in C# directly or indirectly derives from the object class type.

The keyword object is simply an alias for the predefined class System.Object.

The dynamic type

The dynamic type, like object, can reference any object. When operators are applied to expressions of type dynamic, their resolution is deferred until the program is run. Thus, if the operator cannot legally be applied to the referenced object, no error is given during compilation. Instead an exception will be thrown when resolution of the operator fails at run-time.

The dynamic type is further described in §4.7, and dynamic binding in §7.2.2.

The string type

The string type is a sealed class type that inherits directly from object. Instances of the string class represent Unicode character strings.

Values of the string type can be written as string literals (§2.4.4.5).

The keyword string is simply an alias for the predefined class System.String.

Interface types

An interface defines a contract. A class or struct that implements an interface must adhere to its contract. An interface may inherit from multiple base interfaces, and a class or struct may implement multiple interfaces.

Interface types are described in §13.

Array types

An array is a data structure that contains zero or more variables which are accessed through computed indices. The variables contained in an array, also called the elements of the array, are all of the same type, and this type is called the element type of the array.

Array types are described in §12.

Delegate types

A delegate is a data structure that refers to one or more methods. For instance methods, it also refers to their corresponding object instances.

The closest equivalent of a delegate in C or C++ is a function pointer, but whereas a function pointer can only reference static functions, a delegate can reference both static and instance methods. In the latter case, the delegate stores not only a reference to the method’s entry point, but also a reference to the object instance on which to invoke the method.

Delegate types are described in §15.

Boxing and unboxing

The concept of boxing and unboxing is central to C#’s type system. It provides a bridge between value-types and reference-types by permitting any value of a value-type to be converted to and from ty