Add markdown specification (#9)
* Initial port of the C# 6 specification; all the heavy lifting had been done by @ljw1004 * Remove pdf, html versions and grammar versions until we figure out how to build them.
This commit is contained in:
Neal Gafter
GitHub
parent
0709623617
commit
6027ad5a4a
6
spec/LICENSE.md
Normal file
6
spec/LICENSE.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
THE FOLLOWING NOTICE GOVERNS THE C# SPEC
|
||||
=====
|
||||
|
||||
(c) Copyright 1999-2017 Microsoft Corporation. All rights reserved.
|
||||
Microsoft, Windows, Visual Basic, Visual C#, and Visual C++ are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries/regions.
|
||||
Other product and company names mentioned herein may be the trademarks of their respective owners.
|
||||
172
spec/README.md
Normal file
172
spec/README.md
Normal file
|
|
@ -0,0 +1,172 @@
|
|||
C# Language Specification
|
||||
===========================
|
||||
__Version 6__
|
||||
|
||||
*Microsoft has not yet released an official copy of the C#6 spec. This is an unofficial draft. __When Microsoft does release its official copy, before end 2016 at the latest, then this current repository will be deleted__. That's because I wouldn't want to have two copies of the C#6 spec floating around.*
|
||||
|
||||
<!--
|
||||
(This document is also available for download: [csharp.pdf](CSharp%20Language%20Specification.pdf?raw=true) and [csharp.docx](CSharp%20Language%20Specification.docx?raw=true))
|
||||
-->
|
||||
|
||||
* [Introduction](introduction.md)
|
||||
* [Hello world](introduction.md#hello-world)
|
||||
* [Program structure](introduction.md#program-structure)
|
||||
* [Types and variables](introduction.md#types-and-variables)
|
||||
* [Expressions](introduction.md#expressions)
|
||||
* [Statements](introduction.md#statements)
|
||||
* [Classes and objects](introduction.md#classes-and-objects)
|
||||
* [Lexical structure](lexical-structure.md)
|
||||
* [Programs](lexical-structure.md#programs)
|
||||
* [Grammars](lexical-structure.md#grammars)
|
||||
* [Lexical analysis](lexical-structure.md#lexical-analysis)
|
||||
* [Tokens](lexical-structure.md#tokens)
|
||||
* [Pre-processing directives](lexical-structure.md#pre-processing-directives)
|
||||
* [Basic concepts](basic-concepts.md)
|
||||
* [Application Startup](basic-concepts.md#application-startup)
|
||||
* [Application termination](basic-concepts.md#application-termination)
|
||||
* [Declarations](basic-concepts.md#declarations)
|
||||
* [Members](basic-concepts.md#members)
|
||||
* [Member access](basic-concepts.md#member-access)
|
||||
* [Signatures and overloading](basic-concepts.md#signatures-and-overloading)
|
||||
* [Scopes](basic-concepts.md#scopes)
|
||||
* [Namespace and type names](basic-concepts.md#namespace-and-type-names)
|
||||
* [Automatic memory management](basic-concepts.md#automatic-memory-management)
|
||||
* [Execution order](basic-concepts.md#execution-order)
|
||||
* [Types](types.md)
|
||||
* [Value types](types.md#value-types)
|
||||
* [Reference types](types.md#reference-types)
|
||||
* [Boxing and unboxing](types.md#boxing-and-uboxing)
|
||||
* [Constructed types](types.md#constructed-types)
|
||||
* [Type parameters](types.md#type-parameters)
|
||||
* [Expression tree types](types.md#expression-tree-types)
|
||||
* [The dynamic type](types.md#the-dynamic-type)
|
||||
* [Variables](variables.md)
|
||||
* [Variable categories](variables.md#variable-categories)
|
||||
* [Default values](variables.md#default-values)
|
||||
* [Definite assignment](variables.md#definite-assignment)
|
||||
* [Variable references](variables.md#variable-references)
|
||||
* [Atomicity of variable references](variables.md#atomicity-of-variable-references)
|
||||
* [Conversions](conversions.md)
|
||||
* [Implicit conversions](conversions.md#implicit-conversions)
|
||||
* [Explicit conversions](conversions.md#explicit-conversions)
|
||||
* [Standard conversions](conversions.md#standard-conversions)
|
||||
* [User-defined conversions](conversions.md#user-defined-conversions)
|
||||
* [Anonymous function conversions](conversions.md#anonymous-function-conversions)
|
||||
* [Method group conversions](conversions.md#method-group-conversions)
|
||||
* [Expressions](expressions.md)
|
||||
* [Expression classifications](expressions.md#expression-classification)
|
||||
* [Static and Dynamic Binding](expressions.md#static-and-dynamic-binding)
|
||||
* [Operators](expressions.md#operators)
|
||||
* [Member lookup](expressions.md#member-lookup)
|
||||
* [Function members](expressions.md#function-members)
|
||||
* [Primary expressions](expressions.md#primary-expressions)
|
||||
* [Unary operators](expressions.md#unary-operators)
|
||||
* [Arithmetic operators](expressions.md#arithmetic-operators)
|
||||
* [Shift operators](expressions.md#shift-operators)
|
||||
* [Relational and type-testing operators](expressions.md#relational-and-type-testing-operators)
|
||||
* [Logical operators](expressions.md#logical-operators)
|
||||
* [Conditional logical operators](expressions.md#conditional-logical-operators)
|
||||
* [The null coalescing operator](expressions.md#the-null-coalescing-operator)
|
||||
* [Conditional operator](expressions.md#conditional-operator)
|
||||
* [Anonymous function expressions](expressions.md#anonymous-function-expressions)
|
||||
* [Query expressions](expressions.md#query-expressions)
|
||||
* [Assignment operators](expressions.md#assignment-operators)
|
||||
* [Expression](expressions.md#expression)
|
||||
* [Constant expressions](expressions.md#constant-expressions)
|
||||
* [Boolean expressions](expressions.md#boolean-expressions)
|
||||
* [Statements](statements.md)
|
||||
* [End points and reachability](statements.md#end-points-and-reachability)
|
||||
* [Blocks](statements.md#blocks)
|
||||
* [The empty statement](statements.md#the-empty-statement)
|
||||
* [Labeled statements](statements.md#labeled-statements)
|
||||
* [Declaration statements](statements.md#declaration-statements)
|
||||
* [Expression statements](statements.md#expression-statements)
|
||||
* [Selection statements](statements.md#selection-statements)
|
||||
* [Iteration statements](statements.md#iteration-statements)
|
||||
* [Jump statements](statements.md#jump-statements)
|
||||
* [The try statement](statements.md#the-try-statement)
|
||||
* [The checked and unchecked statements](statements.md#the-checked-and-unchecked-statements)
|
||||
* [The lock statement](statements.md#the-lock-statement)
|
||||
* [The using statement](statements.md#the-using-statement)
|
||||
* [The yield statement](statements.md#the-yield-statement)
|
||||
* [Namespaces](namespaces.md)
|
||||
* [Compilation units](namespaces.md#compilation-units)
|
||||
* [Namespace declarations](namespaces.md#namespace-declarations)
|
||||
* [Extern aliases](namespaces.md#extern-aliases)
|
||||
* [Using directives](namespaces.md#using-directives)
|
||||
* [Namespace members](namespaces.md#namespace-members)
|
||||
* [Type declarations](namespaces.md#type-declarations)
|
||||
* [Namespace alias qualifiers](namespaces.md#namespace-alias-qualifiers)
|
||||
* [Classes](classes.md)
|
||||
* [Class declarations](classes.md#class-declarations)
|
||||
* [Partial types](classes.md#partial-types)
|
||||
* [Class members](classes.md#class-members)
|
||||
* [Constants](classes.md#constants)
|
||||
* [Fields](classes.md#fields)
|
||||
* [Methods](classes.md#methods)
|
||||
* [Properties](classes.md#properties)
|
||||
* [Events](classes.md#events)
|
||||
* [Indexers](classes.md#indexers)
|
||||
* [Operators](classes.md#operators)
|
||||
* [Instance constructors](classes.md#instance-constructors)
|
||||
* [Static constructors](classes.md#static-constructors)
|
||||
* [Destructors](classes.md#destructors)
|
||||
* [Iterators](classes.md#iterators)
|
||||
* [Structs](structs.md)
|
||||
* [Struct declarations](structs.md#struct-declarations)
|
||||
* [Struct members](structs.md#struct-members)
|
||||
* [Class and struct differences](structs.md#class-and-struct-differences)
|
||||
* [Struct examples](structs.md#struct-examples)
|
||||
* [Arrays](arrays.md)
|
||||
* [Array types](arrays.md#array-types)
|
||||
* [Array creation](arrays.md#array-creation)
|
||||
* [Array element access](arrays.md#array-element-access)
|
||||
* [Array members](arrays.md#array-members)
|
||||
* [Array covariance](arrays.md#array-covariance)
|
||||
* [Array initializers](arrays.md#array-initializers)
|
||||
* [Interfaces](interfaces.md)
|
||||
* [Interface declarations](interfaces.md#interface-declarations)
|
||||
* [Interface members](interfaces.md#interface-members)
|
||||
* [Fully qualified interface member names](interfaces.md#fully-qualified-interface-member-names)
|
||||
* [Interface implementations](interfaces.md#interface-implementations)
|
||||
* [Enums](enums.md)
|
||||
* [Enum declarations](enums.md#enum-declarations)
|
||||
* [Enum modifiers](enums.md#enum-modifiers)
|
||||
* [Enum members](enums.md#enum-members)
|
||||
* [The System.Enum type](enums.md#the-systemenum-type)
|
||||
* [Enum values and operations](enums.md#enum-values-and-operations)
|
||||
* [Delegates](delegates.md)
|
||||
* [Delegate declarations](delegates.md#delegate-declarations)
|
||||
* [Delegate compatibility](delegates.md#delegate-compatibility)
|
||||
* [Delegate instantiation](delegates.md#delegate-instantiation)
|
||||
* [Delegate invocation](delegates.md#delegate-invocation)
|
||||
* [Exceptions](exceptions.md)
|
||||
* [Causes of exceptions](exceptions.md#causes-of-exceptions)
|
||||
* [The System.Exception class](exceptions.md#the-systemexception-class)
|
||||
* [How exceptions are handled](exceptions.md#how-exceptions-are-handled)
|
||||
* [Common Exception Classes](exceptions.md#common-exception-classes)
|
||||
* [Attributes](attributes.md)
|
||||
* [Attribute classes](attributes.md#attribute-classes)
|
||||
* [Attribute specification](attributes.md#attribute-specification)
|
||||
* [Attribute instances](attributes.md#attribute-instances)
|
||||
* [Reserved attributes](attributes.md#reserved-attributes)
|
||||
* [Attributes for Interoperation](attributes.md#attributes-for-interoperation)
|
||||
* [Unsafe code](unsafe-code.md)
|
||||
* [Unsafe contexts](unsafe-code.md#unsafe-contexts-)
|
||||
* [Pointer types](unsafe-code.md#pointer-types)
|
||||
* [Fixed and moveable variables](unsafe-code.md#fixed-and-moveable-variables)
|
||||
* [Pointer conversions](unsafe-code.md#pointer-conversions)
|
||||
* [Pointers in expressions](unsafe-code.md#pointers-in-expressions)
|
||||
* [The fixed statement](unsafe-code.md#the-fixed-statement)
|
||||
* [Fixed size buffers](unsafe-code.md#fixed-size-buffers)
|
||||
* [Stack allocation](unsafe-code.md#stack-allocation)
|
||||
* [Dynamic memory allocation](unsafe-code.md#dynamic-memory-allocation)
|
||||
* [Documentation comments](documentation-comments.md)
|
||||
* [Introduction](documentation-comments.md#introduction)
|
||||
* [Recommended tags](documentation-comments.md#recommended-tags)
|
||||
* [Processing the documentation file](documentation-comments.md#processing-the-documentation-file)
|
||||
* [An example](documentation-comments.md#an-example)
|
||||
|
||||
<!--
|
||||
* Grammar: [csharp.html](http://ljw1004.github.io/csharpspec/csharp.html). Or download in ANTLR format: [csharp.g4](csharp.g4?raw=true).
|
||||
-->
|
||||
197
spec/arrays.md
Normal file
197
spec/arrays.md
Normal file
|
|
@ -0,0 +1,197 @@
|
|||
# Arrays
|
||||
|
||||
An array is a data structure that contains a number of 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.
|
||||
|
||||
An array has a rank which determines the number of indices associated with each array element. The rank of an array is also referred to as the dimensions of the array. An array with a rank of one is called a ***single-dimensional array***. An array with a rank greater than one is called a ***multi-dimensional array***. Specific sized multi-dimensional arrays are often referred to as two-dimensional arrays, three-dimensional arrays, and so on.
|
||||
|
||||
Each dimension of an array has an associated length which is an integral number greater than or equal to zero. The dimension lengths are not part of the type of the array, but rather are established when an instance of the array type is created at run-time. The length of a dimension determines the valid range of indices for that dimension: For a dimension of length `N`, indices can range from `0` to `N - 1` inclusive. The total number of elements in an array is the product of the lengths of each dimension in the array. If one or more of the dimensions of an array have a length of zero, the array is said to be empty.
|
||||
|
||||
The element type of an array can be any type, including an array type.
|
||||
|
||||
## Array types
|
||||
|
||||
An array type is written as a *non_array_type* followed by one or more *rank_specifier*s:
|
||||
|
||||
```antlr
|
||||
array_type
|
||||
: non_array_type rank_specifier+
|
||||
;
|
||||
|
||||
non_array_type
|
||||
: type
|
||||
;
|
||||
|
||||
rank_specifier
|
||||
: '[' dim_separator* ']'
|
||||
;
|
||||
|
||||
dim_separator
|
||||
: ','
|
||||
;
|
||||
```
|
||||
|
||||
A *non_array_type* is any *type* that is not itself an *array_type*.
|
||||
|
||||
The rank of an array type is given by the leftmost *rank_specifier* in the *array_type*: A *rank_specifier* indicates that the array is an array with a rank of one plus the number of "`,`" tokens in the *rank_specifier*.
|
||||
|
||||
The element type of an array type is the type that results from deleting the leftmost *rank_specifier*:
|
||||
|
||||
* An array type of the form `T[R]` is an array with rank `R` and a non-array element type `T`.
|
||||
* An array type of the form `T[R][R1]...[Rn]` is an array with rank `R` and an element type `T[R1]...[Rn]`.
|
||||
|
||||
In effect, the *rank_specifier*s are read from left to right before the final non-array element type. The type `int[][,,][,]` is a single-dimensional array of three-dimensional arrays of two-dimensional arrays of `int`.
|
||||
|
||||
At run-time, a value of an array type can be `null` or a reference to an instance of that array type.
|
||||
|
||||
### The System.Array type
|
||||
|
||||
The type `System.Array` is the abstract base type of all array types. An implicit reference conversion ([Implicit reference conversions](conversions.md#implicit-reference-conversions)) exists from any array type to `System.Array`, and an explicit reference conversion ([Explicit reference conversions](conversions.md#explicit-reference-conversions)) exists from `System.Array` to any array type. Note that `System.Array` is not itself an *array_type*. Rather, it is a *class_type* from which all *array_type*s are derived.
|
||||
|
||||
At run-time, a value of type `System.Array` can be `null` or a reference to an instance of any array type.
|
||||
|
||||
### Arrays and the generic IList interface
|
||||
|
||||
A one-dimensional array `T[]` implements the interface `System.Collections.Generic.IList<T>` (`IList<T>` for short) and its base interfaces. Accordingly, there is an implicit conversion from `T[]` to `IList<T>` and its base interfaces. In addition, if there is an implicit reference conversion from `S` to `T` then `S[]` implements `IList<T>` and there is an implicit reference conversion from `S[]` to `IList<T>` and its base interfaces ([Implicit reference conversions](conversions.md#implicit-reference-conversions)). If there is an explicit reference conversion from `S` to `T` then there is an explicit reference conversion from `S[]` to `IList<T>` and its base interfaces ([Explicit reference conversions](conversions.md#explicit-reference-conversions)). For example:
|
||||
```csharp
|
||||
using System.Collections.Generic;
|
||||
|
||||
class Test
|
||||
{
|
||||
static void Main() {
|
||||
string[] sa = new string[5];
|
||||
object[] oa1 = new object[5];
|
||||
object[] oa2 = sa;
|
||||
|
||||
IList<string> lst1 = sa; // Ok
|
||||
IList<string> lst2 = oa1; // Error, cast needed
|
||||
IList<object> lst3 = sa; // Ok
|
||||
IList<object> lst4 = oa1; // Ok
|
||||
|
||||
IList<string> lst5 = (IList<string>)oa1; // Exception
|
||||
IList<string> lst6 = (IList<string>)oa2; // Ok
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The assignment `lst2 = oa1` generates a compile-time error since the conversion from `object[]` to `IList<string>` is an explicit conversion, not implicit. The cast `(IList<string>)oa1` will cause an exception to be thrown at run-time since `oa1` references an `object[]` and not a `string[]`. However the cast `(IList<string>)oa2` will not cause an exception to be thrown since `oa2` references a `string[]`.
|
||||
|
||||
Whenever there is an implicit or explicit reference conversion from `S[]` to `IList<T>`, there is also an explicit reference conversion from `IList<T>` and its base interfaces to `S[]` ([Explicit reference conversions](conversions.md#explicit-reference-conversions)).
|
||||
|
||||
When an array type `S[]` implements `IList<T>`, some of the members of the implemented interface may throw exceptions. The precise behavior of the implementation of the interface is beyond the scope of this specification.
|
||||
|
||||
## Array creation
|
||||
|
||||
Array instances are created by *array_creation_expression*s ([Array creation expressions](expressions.md#array-creation-expressions)) or by field or local variable declarations that include an *array_initializer* ([Array initializers](arrays.md#array-initializers)).
|
||||
|
||||
When an array instance is created, the rank and length of each dimension are established and then remain constant for the entire lifetime of the instance. In other words, it is not possible to change the rank of an existing array instance, nor is it possible to resize its dimensions.
|
||||
|
||||
An array instance is always of an array type. The `System.Array` type is an abstract type that cannot be instantiated.
|
||||
|
||||
Elements of arrays created by *array_creation_expression*s are always initialized to their default value ([Default values](variables.md#default-values)).
|
||||
|
||||
## Array element access
|
||||
|
||||
Array elements are accessed using *element_access* expressions ([Array access](expressions.md#array-access)) of the form `A[I1, I2, ..., In]`, where `A` is an expression of an array type and each `Ix` is an expression of type `int`, `uint`, `long`, `ulong`, or can be implicitly converted to one or more of these types. The result of an array element access is a variable, namely the array element selected by the indices.
|
||||
|
||||
The elements of an array can be enumerated using a `foreach` statement ([The foreach statement](statements.md#the-foreach-statement)).
|
||||
|
||||
## Array members
|
||||
|
||||
Every array type inherits the members declared by the `System.Array` type.
|
||||
|
||||
## Array covariance
|
||||
|
||||
For any two *reference_type*s `A` and `B`, if an implicit reference conversion ([Implicit reference conversions](conversions.md#implicit-reference-conversions)) or explicit reference conversion ([Explicit reference conversions](conversions.md#explicit-reference-conversions)) exists from `A` to `B`, then the same reference conversion also exists from the array type `A[R]` to the array type `B[R]`, where `R` is any given *rank_specifier* (but the same for both array types). This relationship is known as ***array covariance***. Array covariance in particular means that a value of an array type `A[R]` may actually be a reference to an instance of an array type `B[R]`, provided an implicit reference conversion exists from `B` to `A`.
|
||||
|
||||
Because of array covariance, assignments to elements of reference type arrays include a run-time check which ensures that the value being assigned to the array element is actually of a permitted type ([Simple assignment](expressions.md#simple-assignment)). For example:
|
||||
```csharp
|
||||
class Test
|
||||
{
|
||||
static void Fill(object[] array, int index, int count, object value) {
|
||||
for (int i = index; i < index + count; i++) array[i] = value;
|
||||
}
|
||||
|
||||
static void Main() {
|
||||
string[] strings = new string[100];
|
||||
Fill(strings, 0, 100, "Undefined");
|
||||
Fill(strings, 0, 10, null);
|
||||
Fill(strings, 90, 10, 0);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The assignment to `array[i]` in the `Fill` method implicitly includes a run-time check which ensures that the object referenced by `value` is either `null` or an instance that is compatible with the actual element type of `array`. In `Main`, the first two invocations of `Fill` succeed, but the third invocation causes a `System.ArrayTypeMismatchException` to be thrown upon executing the first assignment to `array[i]`. The exception occurs because a boxed `int` cannot be stored in a `string` array.
|
||||
|
||||
Array covariance specifically does not extend to arrays of *value_type*s. For example, no conversion exists that permits an `int[]` to be treated as an `object[]`.
|
||||
|
||||
## Array initializers
|
||||
|
||||
Array initializers may be specified in field declarations ([Fields](classes.md#fields)), local variable declarations ([Local variable declarations](statements.md#local-variable-declarations)), and array creation expressions ([Array creation expressions](expressions.md#array-creation-expressions)):
|
||||
|
||||
```antlr
|
||||
array_initializer
|
||||
: '{' variable_initializer_list? '}'
|
||||
| '{' variable_initializer_list ',' '}'
|
||||
;
|
||||
|
||||
variable_initializer_list
|
||||
: variable_initializer (',' variable_initializer)*
|
||||
;
|
||||
|
||||
variable_initializer
|
||||
: expression
|
||||
| array_initializer
|
||||
;
|
||||
```
|
||||
|
||||
An array initializer consists of a sequence of variable initializers, enclosed by "`{`" and "`}`" tokens and separated by "`,`" tokens. Each variable initializer is an expression or, in the case of a multi-dimensional array, a nested array initializer.
|
||||
|
||||
The context in which an array initializer is used determines the type of the array being initialized. In an array creation expression, the array type immediately precedes the initializer, or is inferred from the expressions in the array initializer. In a field or variable declaration, the array type is the type of the field or variable being declared. When an array initializer is used in a field or variable declaration, such as:
|
||||
```csharp
|
||||
int[] a = {0, 2, 4, 6, 8};
|
||||
```
|
||||
it is simply shorthand for an equivalent array creation expression:
|
||||
```csharp
|
||||
int[] a = new int[] {0, 2, 4, 6, 8};
|
||||
```
|
||||
|
||||
For a single-dimensional array, the array initializer must consist of a sequence of expressions that are assignment compatible with the element type of the array. The expressions initialize array elements in increasing order, starting with the element at index zero. The number of expressions in the array initializer determines the length of the array instance being created. For example, the array initializer above creates an `int[]` instance of length 5 and then initializes the instance with the following values:
|
||||
```csharp
|
||||
a[0] = 0; a[1] = 2; a[2] = 4; a[3] = 6; a[4] = 8;
|
||||
```
|
||||
|
||||
For a multi-dimensional array, the array initializer must have as many levels of nesting as there are dimensions in the array. The outermost nesting level corresponds to the leftmost dimension and the innermost nesting level corresponds to the rightmost dimension. The length of each dimension of the array is determined by the number of elements at the corresponding nesting level in the array initializer. For each nested array initializer, the number of elements must be the same as the other array initializers at the same level. The example:
|
||||
```csharp
|
||||
int[,] b = {{0, 1}, {2, 3}, {4, 5}, {6, 7}, {8, 9}};
|
||||
```
|
||||
creates a two-dimensional array with a length of five for the leftmost dimension and a length of two for the rightmost dimension:
|
||||
```csharp
|
||||
int[,] b = new int[5, 2];
|
||||
```
|
||||
and then initializes the array instance with the following values:
|
||||
```csharp
|
||||
b[0, 0] = 0; b[0, 1] = 1;
|
||||
b[1, 0] = 2; b[1, 1] = 3;
|
||||
b[2, 0] = 4; b[2, 1] = 5;
|
||||
b[3, 0] = 6; b[3, 1] = 7;
|
||||
b[4, 0] = 8; b[4, 1] = 9;
|
||||
```
|
||||
|
||||
If a dimension other than the rightmost is given with length zero, the subsequent dimensions are assumed to also have length zero. The example:
|
||||
```csharp
|
||||
int[,] c = {};
|
||||
```
|
||||
creates a two-dimensional array with a length of zero for both the leftmost and the rightmost dimension:
|
||||
```csharp
|
||||
int[,] c = new int[0, 0];
|
||||
```
|
||||
|
||||
When an array creation expression includes both explicit dimension lengths and an array initializer, the lengths must be constant expressions and the number of elements at each nesting level must match the corresponding dimension length. Here are some examples:
|
||||
```csharp
|
||||
int i = 3;
|
||||
int[] x = new int[3] {0, 1, 2}; // OK
|
||||
int[] y = new int[i] {0, 1, 2}; // Error, i not a constant
|
||||
int[] z = new int[3] {0, 1, 2, 3}; // Error, length/initializer mismatch
|
||||
```
|
||||
|
||||
Here, the initializer for `y` results in a compile-time error because the dimension length expression is not a constant, and the initializer for `z` results in a compile-time error because the length and the number of elements in the initializer do not agree.
|
||||
846
spec/attributes.md
Normal file
846
spec/attributes.md
Normal file
|
|
@ -0,0 +1,846 @@
|
|||
# Attributes
|
||||
|
||||
Much of the C# language enables the programmer to specify declarative information about the entities defined in the program. For example, the accessibility of a method in a class is specified by decorating it with the *method_modifier*s `public`, `protected`, `internal`, and `private`.
|
||||
|
||||
C# enables programmers to invent new kinds of declarative information, called ***attributes***. Programmers can then attach attributes to various program entities, and retrieve attribute information in a run-time environment. For instance, a framework might define a `HelpAttribute` attribute that can be placed on certain program elements (such as classes and methods) to provide a mapping from those program elements to their documentation.
|
||||
|
||||
Attributes are defined through the declaration of attribute classes ([Attribute classes](attributes.md#attribute-classes)), which may have positional and named parameters ([Positional and named parameters](attributes.md#positional-and-named-parameters)). Attributes are attached to entities in a C# program using attribute specifications ([Attribute specification](attributes.md#attribute-specification)), and can be retrieved at run-time as attribute instances ([Attribute instances](attributes.md#attribute-instances)).
|
||||
|
||||
## Attribute classes
|
||||
|
||||
A class that derives from the abstract class `System.Attribute`, whether directly or indirectly, is an ***attribute class***. The declaration of an attribute class defines a new kind of ***attribute*** that can be placed on a declaration. By convention, attribute classes are named with a suffix of `Attribute`. Uses of an attribute may either include or omit this suffix.
|
||||
|
||||
### Attribute usage
|
||||
|
||||
The attribute `AttributeUsage` ([The AttributeUsage attribute](attributes.md#the-attributeusage-attribute)) is used to describe how an attribute class can be used.
|
||||
|
||||
`AttributeUsage` has a positional parameter ([Positional and named parameters](attributes.md#positional-and-named-parameters)) that enables an attribute class to specify the kinds of declarations on which it can be used. The example
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface)]
|
||||
public class SimpleAttribute: Attribute
|
||||
{
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
defines an attribute class named `SimpleAttribute` that can be placed on *class_declaration*s and *interface_declaration*s only. The example
|
||||
|
||||
```csharp
|
||||
[Simple] class Class1 {...}
|
||||
|
||||
[Simple] interface Interface1 {...}
|
||||
```
|
||||
|
||||
shows several uses of the `Simple` attribute. Although this attribute is defined with the name `SimpleAttribute`, when this attribute is used, the `Attribute` suffix may be omitted, resulting in the short name `Simple`. Thus, the example above is semantically equivalent to the following:
|
||||
|
||||
```csharp
|
||||
[SimpleAttribute] class Class1 {...}
|
||||
|
||||
[SimpleAttribute] interface Interface1 {...}
|
||||
```
|
||||
|
||||
`AttributeUsage` has a named parameter ([Positional and named parameters](attributes.md#positional-and-named-parameters)) called `AllowMultiple`, which indicates whether the attribute can be specified more than once for a given entity. If `AllowMultiple` for an attribute class is true, then that attribute class is a ***multi-use attribute class***, and can be specified more than once on an entity. If `AllowMultiple` for an attribute class is false or it is unspecified, then that attribute class is a ***single-use attribute class***, and can be specified at most once on an entity.
|
||||
|
||||
The example
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
|
||||
public class AuthorAttribute: Attribute
|
||||
{
|
||||
private string name;
|
||||
|
||||
public AuthorAttribute(string name) {
|
||||
this.name = name;
|
||||
}
|
||||
|
||||
public string Name {
|
||||
get { return name; }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
defines a multi-use attribute class named `AuthorAttribute`. The example
|
||||
|
||||
```csharp
|
||||
[Author("Brian Kernighan"), Author("Dennis Ritchie")]
|
||||
class Class1
|
||||
{
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
shows a class declaration with two uses of the `Author` attribute.
|
||||
|
||||
`AttributeUsage` has another named parameter called `Inherited`, which indicates whether the attribute, when specified on a base class, is also inherited by classes that derive from that base class. If `Inherited` for an attribute class is true, then that attribute is inherited. If `Inherited` for an attribute class is false then that attribute is not inherited. If it is unspecified, its default value is true.
|
||||
|
||||
An attribute class `X` not having an `AttributeUsage` attribute attached to it, as in
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
class X: Attribute {...}
|
||||
```
|
||||
|
||||
is equivalent to the following:
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
[AttributeUsage(
|
||||
AttributeTargets.All,
|
||||
AllowMultiple = false,
|
||||
Inherited = true)
|
||||
]
|
||||
class X: Attribute {...}
|
||||
```
|
||||
|
||||
### Positional and named parameters
|
||||
|
||||
Attribute classes can have ***positional parameters*** and ***named parameters***. Each public instance constructor for an attribute class defines a valid sequence of positional parameters for that attribute class. Each non-static public read-write field and property for an attribute class defines a named parameter for the attribute class.
|
||||
|
||||
The example
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
[AttributeUsage(AttributeTargets.Class)]
|
||||
public class HelpAttribute: Attribute
|
||||
{
|
||||
public HelpAttribute(string url) { // Positional parameter
|
||||
...
|
||||
}
|
||||
|
||||
public string Topic { // Named parameter
|
||||
get {...}
|
||||
set {...}
|
||||
}
|
||||
|
||||
public string Url {
|
||||
get {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
defines an attribute class named `HelpAttribute` that has one positional parameter, `url`, and one named parameter, `Topic`. Although it is non-static and public, the property `Url` does not define a named parameter, since it is not read-write.
|
||||
|
||||
This attribute class might be used as follows:
|
||||
|
||||
```csharp
|
||||
[Help("http://www.mycompany.com/.../Class1.htm")]
|
||||
class Class1
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
[Help("http://www.mycompany.com/.../Misc.htm", Topic = "Class2")]
|
||||
class Class2
|
||||
{
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### Attribute parameter types
|
||||
|
||||
The types of positional and named parameters for an attribute class are limited to the ***attribute parameter types***, which are:
|
||||
|
||||
* One of the following types: `bool`, `byte`, `char`, `double`, `float`, `int`, `long`, `sbyte`, `short`, `string`, `uint`, `ulong`, `ushort`.
|
||||
* The type `object`.
|
||||
* The type `System.Type`.
|
||||
* An enum type, provided it has public accessibility and the types in which it is nested (if any) also have public accessibility ([Attribute specification](attributes.md#attribute-specification)).
|
||||
* Single-dimensional arrays of the above types.
|
||||
* A constructor argument or public field which does not have one of these types, cannot be used as a positional or named parameter in an attribute specification.
|
||||
|
||||
## Attribute specification
|
||||
|
||||
***Attribute specification*** is the application of a previously defined attribute to a declaration. An attribute is a piece of additional declarative information that is specified for a declaration. Attributes can be specified at global scope (to specify attributes on the containing assembly or module) and for *type_declaration*s ([Type declarations](namespaces.md#type-declarations)), *class_member_declaration*s ([Type parameter constraints](classes.md#type-parameter-constraints)), *interface_member_declaration*s ([Interface members](interfaces.md#interface-members)), *struct_member_declaration*s ([Struct members](structs.md#struct-members)), *enum_member_declaration*s ([Enum members](enums.md#enum-members)), *accessor_declarations* ([Accessors](classes.md#accessors)), *event_accessor_declarations* ([Field-like events](classes.md#field-like-events)), and *formal_parameter_list*s ([Method parameters](classes.md#method-parameters)).
|
||||
|
||||
Attributes are specified in ***attribute sections***. An attribute section consists of a pair of square brackets, which surround a comma-separated list of one or more attributes. The order in which attributes are specified in such a list, and the order in which sections attached to the same program entity are arranged, is not significant. For instance, the attribute specifications `[A][B]`, `[B][A]`, `[A,B]`, and `[B,A]` are equivalent.
|
||||
|
||||
```antlr
|
||||
global_attributes
|
||||
: global_attribute_section+
|
||||
;
|
||||
|
||||
global_attribute_section
|
||||
: '[' global_attribute_target_specifier attribute_list ']'
|
||||
| '[' global_attribute_target_specifier attribute_list ',' ']'
|
||||
;
|
||||
|
||||
global_attribute_target_specifier
|
||||
: global_attribute_target ':'
|
||||
;
|
||||
|
||||
global_attribute_target
|
||||
: 'assembly'
|
||||
| 'module'
|
||||
;
|
||||
|
||||
attributes
|
||||
: attribute_section+
|
||||
;
|
||||
|
||||
attribute_section
|
||||
: '[' attribute_target_specifier? attribute_list ']'
|
||||
| '[' attribute_target_specifier? attribute_list ',' ']'
|
||||
;
|
||||
|
||||
attribute_target_specifier
|
||||
: attribute_target ':'
|
||||
;
|
||||
|
||||
attribute_target
|
||||
: 'field'
|
||||
| 'event'
|
||||
| 'method'
|
||||
| 'param'
|
||||
| 'property'
|
||||
| 'return'
|
||||
| 'type'
|
||||
;
|
||||
|
||||
attribute_list
|
||||
: attribute (',' attribute)*
|
||||
;
|
||||
|
||||
attribute
|
||||
: attribute_name attribute_arguments?
|
||||
;
|
||||
|
||||
attribute_name
|
||||
: type_name
|
||||
;
|
||||
|
||||
attribute_arguments
|
||||
: '(' positional_argument_list? ')'
|
||||
| '(' positional_argument_list ',' named_argument_list ')'
|
||||
| '(' named_argument_list ')'
|
||||
;
|
||||
|
||||
positional_argument_list
|
||||
: positional_argument (',' positional_argument)*
|
||||
;
|
||||
|
||||
positional_argument
|
||||
: attribute_argument_expression
|
||||
;
|
||||
|
||||
named_argument_list
|
||||
: named_argument (',' named_argument)*
|
||||
;
|
||||
|
||||
named_argument
|
||||
: identifier '=' attribute_argument_expression
|
||||
;
|
||||
|
||||
attribute_argument_expression
|
||||
: expression
|
||||
;
|
||||
```
|
||||
|
||||
An attribute consists of an *attribute_name* and an optional list of positional and named arguments. The positional arguments (if any) precede the named arguments. A positional argument consists of an *attribute_argument_expression*; a named argument consists of a name, followed by an equal sign, followed by an *attribute_argument_expression*, which, together, are constrained by the same rules as simple assignment. The order of named arguments is not significant.
|
||||
|
||||
The *attribute_name* identifies an attribute class. If the form of *attribute_name* is *type_name* then this name must refer to an attribute class. Otherwise, a compile-time error occurs. The example
|
||||
|
||||
```csharp
|
||||
class Class1 {}
|
||||
|
||||
[Class1] class Class2 {} // Error
|
||||
```
|
||||
|
||||
results in a compile-time error because it attempts to use `Class1` as an attribute class when `Class1` is not an attribute class.
|
||||
|
||||
Certain contexts permit the specification of an attribute on more than one target. A program can explicitly specify the target by including an *attribute_target_specifier*. When an attribute is placed at the global level, a *global_attribute_target_specifier* is required. In all other locations, a reasonable default is applied, but an *attribute_target_specifier* can be used to affirm or override the default in certain ambiguous cases (or to just affirm the default in non-ambiguous cases). Thus, typically, *attribute_target_specifier*s can be omitted except at the global level. The potentially ambiguous contexts are resolved as follows:
|
||||
|
||||
* An attribute specified at global scope can apply either to the target assembly or the target module. No default exists for this context, so an *attribute_target_specifier* is always required in this context. The presence of the `assembly` *attribute_target_specifier* indicates that the attribute applies to the target assembly; the presence of the `module` *attribute_target_specifier* indicates that the attribute applies to the target module.
|
||||
* An attribute specified on a delegate declaration can apply either to the delegate being declared or to its return value. In the absence of an *attribute_target_specifier*, the attribute applies to the delegate. The presence of the `type` *attribute_target_specifier* indicates that the attribute applies to the delegate; the presence of the `return` *attribute_target_specifier* indicates that the attribute applies to the return value.
|
||||
* An attribute specified on a method declaration can apply either to the method being declared or to its return value. In the absence of an *attribute_target_specifier*, the attribute applies to the method. The presence of the `method` *attribute_target_specifier* indicates that the attribute applies to the method; the presence of the `return` *attribute_target_specifier* indicates that the attribute applies to the return value.
|
||||
* An attribute specified on an operator declaration can apply either to the operator being declared or to its return value. In the absence of an *attribute_target_specifier*, the attribute applies to the operator. The presence of the `method` *attribute_target_specifier* indicates that the attribute applies to the operator; the presence of the `return` *attribute_target_specifier* indicates that the attribute applies to the return value.
|
||||
* An attribute specified on an event declaration that omits event accessors can apply to the event being declared, to the associated field (if the event is not abstract), or to the associated add and remove methods. In the absence of an *attribute_target_specifier*, the attribute applies to the event. The presence of the `event` *attribute_target_specifier* indicates that the attribute applies to the event; the presence of the `field` *attribute_target_specifier* indicates that the attribute applies to the field; and the presence of the `method` *attribute_target_specifier* indicates that the attribute applies to the methods.
|
||||
* An attribute specified on a get accessor declaration for a property or indexer declaration can apply either to the associated method or to its return value. In the absence of an *attribute_target_specifier*, the attribute applies to the method. The presence of the `method` *attribute_target_specifier* indicates that the attribute applies to the method; the presence of the `return` *attribute_target_specifier* indicates that the attribute applies to the return value.
|
||||
* An attribute specified on a set accessor for a property or indexer declaration can apply either to the associated method or to its lone implicit parameter. In the absence of an *attribute_target_specifier*, the attribute applies to the method. The presence of the `method` *attribute_target_specifier* indicates that the attribute applies to the method; the presence of the `param` *attribute_target_specifier* indicates that the attribute applies to the parameter; the presence of the `return` *attribute_target_specifier* indicates that the attribute applies to the return value.
|
||||
* An attribute specified on an add or remove accessor declaration for an event declaration can apply either to the associated method or to its lone parameter. In the absence of an *attribute_target_specifier*, the attribute applies to the method. The presence of the `method` *attribute_target_specifier* indicates that the attribute applies to the method; the presence of the `param` *attribute_target_specifier* indicates that the attribute applies to the parameter; the presence of the `return` *attribute_target_specifier* indicates that the attribute applies to the return value.
|
||||
|
||||
In other contexts, inclusion of an *attribute_target_specifier* is permitted but unnecessary. For instance, a class declaration may either include or omit the specifier `type`:
|
||||
|
||||
```csharp
|
||||
[type: Author("Brian Kernighan")]
|
||||
class Class1 {}
|
||||
|
||||
[Author("Dennis Ritchie")]
|
||||
class Class2 {}
|
||||
```
|
||||
|
||||
It is an error to specify an invalid *attribute_target_specifier*. For instance, the specifier `param` cannot be used on a class declaration:
|
||||
|
||||
```csharp
|
||||
[param: Author("Brian Kernighan")] // Error
|
||||
class Class1 {}
|
||||
```
|
||||
|
||||
By convention, attribute classes are named with a suffix of `Attribute`. An *attribute_name* of the form *type_name* may either include or omit this suffix. If an attribute class is found both with and without this suffix, an ambiguity is present, and a compile-time error results. If the *attribute_name* is spelled such that its right-most *identifier* is a verbatim identifier ([Identifiers](lexical-structure.md#identifiers)), then only an attribute without a suffix is matched, thus enabling such an ambiguity to be resolved. The example
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
[AttributeUsage(AttributeTargets.All)]
|
||||
public class X: Attribute
|
||||
{}
|
||||
|
||||
[AttributeUsage(AttributeTargets.All)]
|
||||
public class XAttribute: Attribute
|
||||
{}
|
||||
|
||||
[X] // Error: ambiguity
|
||||
class Class1 {}
|
||||
|
||||
[XAttribute] // Refers to XAttribute
|
||||
class Class2 {}
|
||||
|
||||
[@X] // Refers to X
|
||||
class Class3 {}
|
||||
|
||||
[@XAttribute] // Refers to XAttribute
|
||||
class Class4 {}
|
||||
```
|
||||
|
||||
shows two attribute classes named `X` and `XAttribute`. The attribute `[X]` is ambiguous, since it could refer to either `X` or `XAttribute`. Using a verbatim identifier allows the exact intent to be specified in such rare cases. The attribute `[XAttribute]` is not ambiguous (although it would be if there was an attribute class named `XAttributeAttribute`!). If the declaration for class `X` is removed, then both attributes refer to the attribute class named `XAttribute`, as follows:
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
[AttributeUsage(AttributeTargets.All)]
|
||||
public class XAttribute: Attribute
|
||||
{}
|
||||
|
||||
[X] // Refers to XAttribute
|
||||
class Class1 {}
|
||||
|
||||
[XAttribute] // Refers to XAttribute
|
||||
class Class2 {}
|
||||
|
||||
[@X] // Error: no attribute named "X"
|
||||
class Class3 {}
|
||||
```
|
||||
|
||||
It is a compile-time error to use a single-use attribute class more than once on the same entity. The example
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
[AttributeUsage(AttributeTargets.Class)]
|
||||
public class HelpStringAttribute: Attribute
|
||||
{
|
||||
string value;
|
||||
|
||||
public HelpStringAttribute(string value) {
|
||||
this.value = value;
|
||||
}
|
||||
|
||||
public string Value {
|
||||
get {...}
|
||||
}
|
||||
}
|
||||
|
||||
[HelpString("Description of Class1")]
|
||||
[HelpString("Another description of Class1")]
|
||||
public class Class1 {}
|
||||
```
|
||||
|
||||
results in a compile-time error because it attempts to use `HelpString`, which is a single-use attribute class, more than once on the declaration of `Class1`.
|
||||
|
||||
An expression `E` is an *attribute_argument_expression* if all of the following statements are true:
|
||||
|
||||
* The type of `E` is an attribute parameter type ([Attribute parameter types](attributes.md#attribute-parameter-types)).
|
||||
* At compile-time, the value of `E` can be resolved to one of the following:
|
||||
* A constant value.
|
||||
* A `System.Type` object.
|
||||
* A one-dimensional array of *attribute_argument_expression*s.
|
||||
|
||||
For example:
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
[AttributeUsage(AttributeTargets.Class)]
|
||||
public class TestAttribute: Attribute
|
||||
{
|
||||
public int P1 {
|
||||
get {...}
|
||||
set {...}
|
||||
}
|
||||
|
||||
public Type P2 {
|
||||
get {...}
|
||||
set {...}
|
||||
}
|
||||
|
||||
public object P3 {
|
||||
get {...}
|
||||
set {...}
|
||||
}
|
||||
}
|
||||
|
||||
[Test(P1 = 1234, P3 = new int[] {1, 3, 5}, P2 = typeof(float))]
|
||||
class MyClass {}
|
||||
```
|
||||
|
||||
A *typeof_expression* ([The typeof operator](expressions.md#the-typeof-operator)) used as an attribute argument expression can reference a non-generic type, a closed constructed type, or an unbound generic type, but it cannot reference an open type. This is to ensure that the expression can be resolved at compile-time.
|
||||
|
||||
```csharp
|
||||
class A: Attribute
|
||||
{
|
||||
public A(Type t) {...}
|
||||
}
|
||||
|
||||
class G<T>
|
||||
{
|
||||
[A(typeof(T))] T t; // Error, open type in attribute
|
||||
}
|
||||
|
||||
class X
|
||||
{
|
||||
[A(typeof(List<int>))] int x; // Ok, closed constructed type
|
||||
[A(typeof(List<>))] int y; // Ok, unbound generic type
|
||||
}
|
||||
```
|
||||
|
||||
## Attribute instances
|
||||
|
||||
An ***attribute instance*** is an instance that represents an attribute at run-time. An attribute is defined with an attribute class, positional arguments, and named arguments. An attribute instance is an instance of the attribute class that is initialized with the positional and named arguments.
|
||||
|
||||
Retrieval of an attribute instance involves both compile-time and run-time processing, as described in the following sections.
|
||||
|
||||
### Compilation of an attribute
|
||||
|
||||
The compilation of an *attribute* with attribute class `T`, *positional_argument_list* `P` and *named_argument_list* `N`, consists of the following steps:
|
||||
|
||||
* Follow the compile-time processing steps for compiling an *object_creation_expression* of the form `new T(P)`. These steps either result in a compile-time error, or determine an instance constructor `C` on `T` that can be invoked at run-time.
|
||||
* If `C` does not have public accessibility, then a compile-time error occurs.
|
||||
* For each *named_argument* `Arg` in `N`:
|
||||
* Let `Name` be the *identifier* of the *named_argument* `Arg`.
|
||||
* `Name` must identify a non-static read-write public field or property on `T`. If `T` has no such field or property, then a compile-time error occurs.
|
||||
* Keep the following information for run-time instantiation of the attribute: the attribute class `T`, the instance constructor `C` on `T`, the *positional_argument_list* `P` and the *named_argument_list* `N`.
|
||||
|
||||
### Run-time retrieval of an attribute instance
|
||||
|
||||
Compilation of an *attribute* yields an attribute class `T`, an instance constructor `C` on `T`, a *positional_argument_list* `P`, and a *named_argument_list* `N`. Given this information, an attribute instance can be retrieved at run-time using the following steps:
|
||||
|
||||
* Follow the run-time processing steps for executing an *object_creation_expression* of the form `new T(P)`, using the instance constructor `C` as determined at compile-time. These steps either result in an exception, or produce an instance `O` of `T`.
|
||||
* For each *named_argument* `Arg` in `N`, in order:
|
||||
* Let `Name` be the *identifier* of the *named_argument* `Arg`. If `Name` does not identify a non-static public read-write field or property on `O`, then an exception is thrown.
|
||||
* Let `Value` be the result of evaluating the *attribute_argument_expression* of `Arg`.
|
||||
* If `Name` identifies a field on `O`, then set this field to `Value`.
|
||||
* Otherwise, `Name` identifies a property on `O`. Set this property to `Value`.
|
||||
* The result is `O`, an instance of the attribute class `T` that has been initialized with the *positional_argument_list* `P` and the *named_argument_list* `N`.
|
||||
|
||||
## Reserved attributes
|
||||
|
||||
A small number of attributes affect the language in some way. These attributes include:
|
||||
|
||||
* `System.AttributeUsageAttribute` ([The AttributeUsage attribute](attributes.md#the-attributeusage-attribute)), which is used to describe the ways in which an attribute class can be used.
|
||||
* `System.Diagnostics.ConditionalAttribute` ([The Conditional attribute](attributes.md#the-conditional-attribute)), which is used to define conditional methods.
|
||||
* `System.ObsoleteAttribute` ([The Obsolete attribute](attributes.md#the-obsolete-attribute)), which is used to mark a member as obsolete.
|
||||
* `System.Runtime.CompilerServices.CallerLineNumberAttribute`, `System.Runtime.CompilerServices.CallerFilePathAttribute` and `System.Runtime.CompilerServices.CallerMemberNameAttribute` ([Caller info attributes](attributes.md#caller-info-attributes)), which are used to supply information about the calling context to optional parameters.
|
||||
|
||||
### The AttributeUsage attribute
|
||||
|
||||
The attribute `AttributeUsage` is used to describe the manner in which the attribute class can be used.
|
||||
|
||||
A class that is decorated with the `AttributeUsage` attribute must derive from `System.Attribute`, either directly or indirectly. Otherwise, a compile-time error occurs.
|
||||
|
||||
```csharp
|
||||
namespace System
|
||||
{
|
||||
[AttributeUsage(AttributeTargets.Class)]
|
||||
public class AttributeUsageAttribute: Attribute
|
||||
{
|
||||
public AttributeUsageAttribute(AttributeTargets validOn) {...}
|
||||
public virtual bool AllowMultiple { get {...} set {...} }
|
||||
public virtual bool Inherited { get {...} set {...} }
|
||||
public virtual AttributeTargets ValidOn { get {...} }
|
||||
}
|
||||
|
||||
public enum AttributeTargets
|
||||
{
|
||||
Assembly = 0x0001,
|
||||
Module = 0x0002,
|
||||
Class = 0x0004,
|
||||
Struct = 0x0008,
|
||||
Enum = 0x0010,
|
||||
Constructor = 0x0020,
|
||||
Method = 0x0040,
|
||||
Property = 0x0080,
|
||||
Field = 0x0100,
|
||||
Event = 0x0200,
|
||||
Interface = 0x0400,
|
||||
Parameter = 0x0800,
|
||||
Delegate = 0x1000,
|
||||
ReturnValue = 0x2000,
|
||||
|
||||
All = Assembly | Module | Class | Struct | Enum | Constructor |
|
||||
Method | Property | Field | Event | Interface | Parameter |
|
||||
Delegate | ReturnValue
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### The Conditional attribute
|
||||
|
||||
The attribute `Conditional` enables the definition of ***conditional methods*** and ***conditional attribute classes***.
|
||||
|
||||
```csharp
|
||||
namespace System.Diagnostics
|
||||
{
|
||||
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = true)]
|
||||
public class ConditionalAttribute: Attribute
|
||||
{
|
||||
public ConditionalAttribute(string conditionString) {...}
|
||||
public string ConditionString { get {...} }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Conditional methods
|
||||
|
||||
A method decorated with the `Conditional` attribute is a conditional method. The `Conditional` attribute indicates a condition by testing a conditional compilation symbol. Calls to a conditional method are either included or omitted depending on whether this symbol is defined at the point of the call. If the symbol is defined, the call is included; otherwise, the call (including evaluation of the receiver and parameters of the call) is omitted.
|
||||
|
||||
A conditional method is subject to the following restrictions:
|
||||
|
||||
* The conditional method must be a method in a *class_declaration* or *struct_declaration*. A compile-time error occurs if the `Conditional` attribute is specified on a method in an interface declaration.
|
||||
* The conditional method must have a return type of `void`.
|
||||
* The conditional method must not be marked with the `override` modifier. A conditional method may be marked with the `virtual` modifier, however. Overrides of such a method are implicitly conditional, and must not be explicitly marked with a `Conditional` attribute.
|
||||
* The conditional method must not be an implementation of an interface method. Otherwise, a compile-time error occurs.
|
||||
|
||||
In addition, a compile-time error occurs if a conditional method is used in a *delegate_creation_expression*. The example
|
||||
|
||||
```csharp
|
||||
#define DEBUG
|
||||
|
||||
using System;
|
||||
using System.Diagnostics;
|
||||
|
||||
class Class1
|
||||
{
|
||||
[Conditional("DEBUG")]
|
||||
public static void M() {
|
||||
Console.WriteLine("Executed Class1.M");
|
||||
}
|
||||
}
|
||||
|
||||
class Class2
|
||||
{
|
||||
public static void Test() {
|
||||
Class1.M();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
declares `Class1.M` as a conditional method. `Class2`'s `Test` method calls this method. Since the conditional compilation symbol `DEBUG` is defined, if `Class2.Test` is called, it will call `M`. If the symbol `DEBUG` had not been defined, then `Class2.Test` would not call `Class1.M`.
|
||||
|
||||
It is important to note that the inclusion or exclusion of a call to a conditional method is controlled by the conditional compilation symbols at the point of the call. In the example
|
||||
|
||||
File `class1.cs`:
|
||||
|
||||
```csharp
|
||||
using System.Diagnostics;
|
||||
|
||||
class Class1
|
||||
{
|
||||
[Conditional("DEBUG")]
|
||||
public static void F() {
|
||||
Console.WriteLine("Executed Class1.F");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
File `class2.cs`:
|
||||
|
||||
```csharp
|
||||
#define DEBUG
|
||||
|
||||
class Class2
|
||||
{
|
||||
public static void G() {
|
||||
Class1.F(); // F is called
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
File `class3.cs`:
|
||||
|
||||
```csharp
|
||||
#undef DEBUG
|
||||
|
||||
class Class3
|
||||
{
|
||||
public static void H() {
|
||||
Class1.F(); // F is not called
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
the classes `Class2` and `Class3` each contain calls to the conditional method `Class1.F`, which is conditional based on whether or not `DEBUG` is defined. Since this symbol is defined in the context of `Class2` but not `Class3`, the call to `F` in `Class2` is included, while the call to `F` in `Class3` is omitted.
|
||||
|
||||
The use of conditional methods in an inheritance chain can be confusing. Calls made to a conditional method through `base`, of the form `base.M`, are subject to the normal conditional method call rules. In the example
|
||||
|
||||
File `class1.cs`:
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
using System.Diagnostics;
|
||||
|
||||
class Class1
|
||||
{
|
||||
[Conditional("DEBUG")]
|
||||
public virtual void M() {
|
||||
Console.WriteLine("Class1.M executed");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
File `class2.cs`:
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
class Class2: Class1
|
||||
{
|
||||
public override void M() {
|
||||
Console.WriteLine("Class2.M executed");
|
||||
base.M(); // base.M is not called!
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
File `class3.cs`:
|
||||
|
||||
```csharp
|
||||
#define DEBUG
|
||||
|
||||
using System;
|
||||
|
||||
class Class3
|
||||
{
|
||||
public static void Test() {
|
||||
Class2 c = new Class2();
|
||||
c.M(); // M is called
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`Class2` includes a call to the `M` defined in its base class. This call is omitted because the base method is conditional based on the presence of the symbol `DEBUG`, which is undefined. Thus, the method writes to the console "`Class2.M executed`" only. Judicious use of *pp_declaration*s can eliminate such problems.
|
||||
|
||||
#### Conditional attribute classes
|
||||
|
||||
An attribute class ([Attribute classes](attributes.md#attribute-classes)) decorated with one or more `Conditional` attributes is a ***conditional attribute class***. A conditional attribute class is thus associated with the conditional compilation symbols declared in its `Conditional` attributes. This example:
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
using System.Diagnostics;
|
||||
[Conditional("ALPHA")]
|
||||
[Conditional("BETA")]
|
||||
public class TestAttribute : Attribute {}
|
||||
```
|
||||
|
||||
declares `TestAttribute` as a conditional attribute class associated with the conditional compilations symbols `ALPHA` and `BETA`.
|
||||
|
||||
Attribute specifications ([Attribute specification](attributes.md#attribute-specification)) of a conditional attribute are included if one or more of its associated conditional compilation symbols is defined at the point of specification, otherwise the attribute specification is omitted.
|
||||
|
||||
It is important to note that the inclusion or exclusion of an attribute specification of a conditional attribute class is controlled by the conditional compilation symbols at the point of the specification. In the example
|
||||
|
||||
File `test.cs`:
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
using System.Diagnostics;
|
||||
|
||||
[Conditional("DEBUG")]
|
||||
|
||||
public class TestAttribute : Attribute {}
|
||||
```
|
||||
|
||||
File `class1.cs`:
|
||||
|
||||
```csharp
|
||||
#define DEBUG
|
||||
|
||||
[Test] // TestAttribute is specified
|
||||
|
||||
class Class1 {}
|
||||
```
|
||||
|
||||
File `class2.cs`:
|
||||
|
||||
```csharp
|
||||
#undef DEBUG
|
||||
|
||||
[Test] // TestAttribute is not specified
|
||||
|
||||
class Class2 {}
|
||||
```
|
||||
|
||||
the classes `Class1` and `Class2` are each decorated with attribute `Test`, which is conditional based on whether or not `DEBUG` is defined. Since this symbol is defined in the context of `Class1` but not `Class2`, the specification of the `Test` attribute on `Class1` is included, while the specification of the `Test` attribute on `Class2` is omitted.
|
||||
|
||||
### The Obsolete attribute
|
||||
|
||||
The attribute `Obsolete` is used to mark types and members of types that should no longer be used.
|
||||
|
||||
```csharp
|
||||
namespace System
|
||||
{
|
||||
[AttributeUsage(
|
||||
AttributeTargets.Class |
|
||||
AttributeTargets.Struct |
|
||||
AttributeTargets.Enum |
|
||||
AttributeTargets.Interface |
|
||||
AttributeTargets.Delegate |
|
||||
AttributeTargets.Method |
|
||||
AttributeTargets.Constructor |
|
||||
AttributeTargets.Property |
|
||||
AttributeTargets.Field |
|
||||
AttributeTargets.Event,
|
||||
Inherited = false)
|
||||
]
|
||||
public class ObsoleteAttribute: Attribute
|
||||
{
|
||||
public ObsoleteAttribute() {...}
|
||||
public ObsoleteAttribute(string message) {...}
|
||||
public ObsoleteAttribute(string message, bool error) {...}
|
||||
public string Message { get {...} }
|
||||
public bool IsError { get {...} }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If a program uses a type or member that is decorated with the `Obsolete` attribute, the compiler issues a warning or an error. Specifically, the compiler issues a warning if no error parameter is provided, or if the error parameter is provided and has the value `false`. The compiler issues an error if the error parameter is specified and has the value `true`.
|
||||
|
||||
In the example
|
||||
|
||||
```csharp
|
||||
[Obsolete("This class is obsolete; use class B instead")]
|
||||
class A
|
||||
{
|
||||
public void F() {}
|
||||
}
|
||||
|
||||
class B
|
||||
{
|
||||
public void F() {}
|
||||
}
|
||||
|
||||
class Test
|
||||
{
|
||||
static void Main() {
|
||||
A a = new A(); // Warning
|
||||
a.F();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
the class `A` is decorated with the `Obsolete` attribute. Each use of `A` in `Main` results in a warning that includes the specified message, "This class is obsolete; use class B instead."
|
||||
|
||||
### Caller info attributes
|
||||
|
||||
For purposes such as logging and reporting, it is sometimes useful for a function member to obtain certain compile-time information about the calling code. The caller info attributes provide a way to pass such information transparently.
|
||||
|
||||
When an optional parameter is annotated with one of the caller info attributes, omitting the corresponding argument in a call does not necessarily cause the default parameter value to be substituted. Instead, if the specified information about the calling context is available, that information will be passed as the argument value.
|
||||
|
||||
For example:
|
||||
|
||||
```csharp
|
||||
using System.Runtime.CompilerServices
|
||||
|
||||
...
|
||||
|
||||
public void Log(
|
||||
[CallerLineNumber] int line = -1,
|
||||
[CallerFilePath] string path = null,
|
||||
[CallerMemberName] string name = null
|
||||
)
|
||||
{
|
||||
Console.WriteLine((line < 0) ? "No line" : "Line "+ line);
|
||||
Console.WriteLine((path == null) ? "No file path" : path);
|
||||
Console.WriteLine((name == null) ? "No member name" : name);
|
||||
}
|
||||
```
|
||||
|
||||
A call to `Log()` with no arguments would print the line number and file path of the call, as well as the name of the member within which the call occurred.
|
||||
|
||||
Caller info attributes can occur on optional parameters anywhere, including in delegate declarations. However, the specific caller info attributes have restrictions on the types of the parameters they can attribute, so that there will always be an implicit conversion from a substituted value to the parameter type.
|
||||
|
||||
It is an error to have the same caller info attribute on a parameter of both the defining and implementing part of a partial method declaration. Only caller info attributes in the defining part are applied, whereas caller info attributes occurring only in the implementing part are ignored.
|
||||
|
||||
Caller information does not affect overload resolution. As the attributed optional parameters are still omitted from the source code of the caller, overload resolution ignores those parameters in the same way it ignores other omitted optional parameters ([Overload resolution](expressions.md#overload-resolution)).
|
||||
|
||||
Caller information is only substituted when a function is explicitly invoked in source code. Implicit invocations such as implicit parent constructor calls do not have a source location and will not substitute caller information. Also, calls that are dynamically bound will not substitute caller information. When a caller info attributed parameter is omitted in such cases, the specified default value of the parameter is used instead.
|
||||
|
||||
One exception is query-expressions. These are considered syntactic expansions, and if the calls they expand to omit optional parameters with caller info attributes, caller information will be substituted. The location used is the location of the query clause which the call was generated from.
|
||||
|
||||
If more than one caller info attribute is specified on a given parameter, they are preferred in the following order: `CallerLineNumber`, `CallerFilePath`, `CallerMemberName`.
|
||||
|
||||
#### The CallerLineNumber attribute
|
||||
|
||||
The `System.Runtime.CompilerServices.CallerLineNumberAttribute` is allowed on optional parameters when there is a standard implicit conversion ([Standard implicit conversions](conversions.md#standard-implicit-conversions)) from the constant value `int.MaxValue` to the parameter's type. This ensures that any non-negative line number up to that value can be passed without error.
|
||||
|
||||
If a function invocation from a location in source code omits an optional parameter with the `CallerLineNumberAttribute`, then a numeric literal representing that location's line number is used as an argument to the invocation instead of the default parameter value.
|
||||
|
||||
If the invocation spans multiple lines, the line chosen is implementation-dependent.
|
||||
|
||||
Note that the line number may be affected by `#line` directives ([Line directives](lexical-structure.md#line-directives)).
|
||||
|
||||
#### The CallerFilePath attribute
|
||||
|
||||
The `System.Runtime.CompilerServices.CallerFilePathAttribute` is allowed on optional parameters when there is a standard implicit conversion ([Standard implicit conversions](conversions.md#standard-implicit-conversions)) from `string` to the parameter's type.
|
||||
|
||||
If a function invocation from a location in source code omits an optional parameter with the `CallerFilePathAttribute`, then a string literal representing that location's file path is used as an argument to the invocation instead of the default parameter value.
|
||||
|
||||
The format of the file path is implementation-dependent.
|
||||
|
||||
Note that the file path may be affected by `#line` directives ([Line directives](lexical-structure.md#line-directives)).
|
||||
|
||||
#### The CallerMemberName attribute
|
||||
|
||||
The `System.Runtime.CompilerServices.CallerMemberNameAttribute` is allowed on optional parameters when there is a standard implicit conversion ([Standard implicit conversions](conversions.md#standard-implicit-conversions)) from `string` to the parameter's type.
|
||||
|
||||
If a function invocation from a location within the body of a function member or within an attribute applied to the function member itself or its return type, parameters or type parameters in source code omits an optional parameter with the `CallerMemberNameAttribute`, then a string literal representing the name of that member is used as an argument to the invocation instead of the default parameter value.
|
||||
|
||||
For invocations that occur within generic methods, only the method name itself is used, without the type parameter list.
|
||||
|
||||
For invocations that occur within explicit interface member implementations, only the method name itself is used, without the preceding interface qualification.
|
||||
|
||||
For invocations that occur within property or event accessors, the member name used is that of the property or event itself.
|
||||
|
||||
For invocations that occur within indexer accessors, the member name used is that supplied by an `IndexerNameAttribute` ([The IndexerName attribute](attributes.md#the-indexername-attribute)) on the indexer member, if present, or the default name `Item` otherwise.
|
||||
|
||||
For invocations that occur within declarations of instance constructors, static constructors, destructors and operators the member name used is implementation-dependent.
|
||||
|
||||
## Attributes for Interoperation
|
||||
|
||||
Note: This section is applicable only to the Microsoft .NET implementation of C#.
|
||||
|
||||
### Interoperation with COM and Win32 components
|
||||
|
||||
The .NET run-time provides a large number of attributes that enable C# programs to interoperate with components written using COM and Win32 DLLs. For example, the `DllImport` attribute can be used on a `static extern` method to indicate that the implementation of the method is to be found in a Win32 DLL. These attributes are found in the `System.Runtime.InteropServices` namespace, and detailed documentation for these attributes is found in the .NET runtime documentation.
|
||||
|
||||
### Interoperation with other .NET languages
|
||||
|
||||
#### The IndexerName attribute
|
||||
|
||||
Indexers are implemented in .NET using indexed properties, and have a name in the .NET metadata. If no `IndexerName` attribute is present for an indexer, then the name `Item` is used by default. The `IndexerName` attribute enables a developer to override this default and specify a different name.
|
||||
|
||||
```csharp
|
||||
namespace System.Runtime.CompilerServices.CSharp
|
||||
{
|
||||
[AttributeUsage(AttributeTargets.Property)]
|
||||
public class IndexerNameAttribute: Attribute
|
||||
{
|
||||
public IndexerNameAttribute(string indexerName) {...}
|
||||
public string Value { get {...} }
|
||||
}
|
||||
}
|
||||
```
|
||||
873
spec/basic-concepts.md
Normal file
873
spec/basic-concepts.md
Normal file
|
|
@ -0,0 +1,873 @@
|
|||
# Basic concepts
|
||||
|
||||
## Application Startup
|
||||
|
||||
An assembly that has an ***entry point*** is called an ***application***. When an application is run, a new ***application domain*** is created. Several different instantiations of an application may exist on the same machine at the same time, and each has its own application domain.
|
||||
|
||||
An application domain enables application isolation by acting as a container for application state. An application domain acts as a container and boundary for the types defined in the application and the class libraries it uses. Types loaded into one application domain are distinct from the same type loaded into another application domain, and instances of objects are not directly shared between application domains. For instance, each application domain has its own copy of static variables for these types, and a static constructor for a type is run at most once per application domain. Implementations are free to provide implementation-specific policy or mechanisms for the creation and destruction of application domains.
|
||||
|
||||
***Application startup*** occurs when the execution environment calls a designated method, which is referred to as the application's entry point. This entry point method is always named `Main`, and can have one of the following signatures:
|
||||
|
||||
```csharp
|
||||
static void Main() {...}
|
||||
|
||||
static void Main(string[] args) {...}
|
||||
|
||||
static int Main() {...}
|
||||
|
||||
static int Main(string[] args) {...}
|
||||
```
|
||||
|
||||
As shown, the entry point may optionally return an `int` value. This return value is used in application termination ([Application termination](basic-concepts.md#application-termination)).
|
||||
|
||||
The entry point may optionally have one formal parameter. The parameter may have any name, but the type of the parameter must be `string[]`. If the formal parameter is present, the execution environment creates and passes a `string[]` argument containing the command-line arguments that were specified when the application was started. The `string[]` argument is never null, but it may have a length of zero if no command-line arguments were specified.
|
||||
|
||||
Since C# supports method overloading, a class or struct may contain multiple definitions of some method, provided each has a different signature. However, within a single program, no class or struct may contain more than one method called `Main` whose definition qualifies it to be used as an application entry point. Other overloaded versions of `Main` are permitted, however, provided they have more than one parameter, or their only parameter is other than type `string[]`.
|
||||
|
||||
An application can be made up of multiple classes or structs. It is possible for more than one of these classes or structs to contain a method called `Main` whose definition qualifies it to be used as an application entry point. In such cases, an external mechanism (such as a command-line compiler option) must be used to select one of these `Main` methods as the entry point.
|
||||
|
||||
In C#, every method must be defined as a member of a class or struct. Ordinarily, the declared accessibility ([Declared accessibility](basic-concepts.md#declared-accessibility)) of a method is determined by the access modifiers ([Access modifiers](classes.md#access-modifiers)) specified in its declaration, and similarly the declared accessibility of a type is determined by the access modifiers specified in its declaration. In order for a given method of a given type to be callable, both the type and the member must be accessible. However, the application entry point is a special case. Specifically, the execution environment can access the application's entry point regardless of its declared accessibility and regardless of the declared accessibility of its enclosing type declarations.
|
||||
|
||||
The application entry point method may not be in a generic class declaration.
|
||||
|
||||
In all other respects, entry point methods behave like those that are not entry points.
|
||||
|
||||
## Application termination
|
||||
|
||||
***Application termination*** returns control to the execution environment.
|
||||
|
||||
If the return type of the application's ***entry point*** method is `int`, the value returned serves as the application's ***termination status code***. The purpose of this code is to allow communication of success or failure to the execution environment.
|
||||
|
||||
If the return type of the entry point method is `void`, reaching the right brace (`}`) which terminates that method, or executing a `return` statement that has no expression, results in a termination status code of `0`.
|
||||
|
||||
Prior to an application's termination, destructors for all of its objects that have not yet been garbage collected are called, unless such cleanup has been suppressed (by a call to the library method `GC.SuppressFinalize`, for example).
|
||||
|
||||
## Declarations
|
||||
|
||||
Declarations in a C# program define the constituent elements of the program. C# programs are organized using namespaces ([Namespaces](namespaces.md#namespaces)), which can contain type declarations and nested namespace declarations. Type declarations ([Type declarations](namespaces.md#type-declarations)) are used to define classes ([Classes](classes.md#classes)), structs ([Iterators](classes.md#iterators)), interfaces ([Interfaces](interfaces.md#interfaces)), enums ([Enums](enums.md#enums)), and delegates ([Delegates](delegates.md#delegates)). The kinds of members permitted in a type declaration depend on the form of the type declaration. For instance, class declarations can contain declarations for constants ([Constants](classes.md#constants)), fields ([Fields](classes.md#fields)), methods ([Methods](classes.md#methods)), properties ([Properties](classes.md#properties)), events ([Events](classes.md#events)), indexers ([Indexers](classes.md#indexers)), operators ([Operators](classes.md#operators)), instance constructors ([Instance constructors](classes.md#instance-constructors)), static constructors ([Static constructors](classes.md#static-constructors)), destructors ([Destructors](classes.md#destructors)), and nested types([Nested types](classes.md#nested-types)).
|
||||
|
||||
A declaration defines a name in the ***declaration space*** to which the declaration belongs. Except for overloaded members ([Signatures and overloading](basic-concepts.md#signatures-and-overloading)), it is a compile-time error to have two or more declarations that introduce members with the same name in a declaration space. It is never possible for a declaration space to contain different kinds of members with the same name. For example, a declaration space can never contain a field and a method by the same name.
|
||||
|
||||
There are several different types of declaration spaces, as described in the following.
|
||||
|
||||
* Within all source files of a program, *namespace_member_declaration*s with no enclosing *namespace_declaration* are members of a single combined declaration space called the ***global declaration space***.
|
||||
* Within all source files of a program, *namespace_member_declaration*s within *namespace_declaration*s that have the same fully qualified namespace name are members of a single combined declaration space.
|
||||
* Each class, struct, or interface declaration creates a new declaration space. Names are introduced into this declaration space through *class_member_declaration*s, *struct_member_declaration*s, *interface_member_declaration*s, or *type_parameter*s. Except for overloaded instance constructor declarations and static constructor declarations, a class or struct cannot contain a member declaration with the same name as the class or struct. A class, struct, or interface permits the declaration of overloaded methods and indexers. Furthermore, a class or struct permits the declaration of overloaded instance constructors and operators. For example, a class, struct, or interface may contain multiple method declarations with the same name, provided these method declarations differ in their signature ([Signatures and overloading](basic-concepts.md#signatures-and-overloading)). Note that base classes do not contribute to the declaration space of a class, and base interfaces do not contribute to the declaration space of an interface. Thus, a derived class or interface is allowed to declare a member with the same name as an inherited member. Such a member is said to ***hide*** the inherited member.
|
||||
* Each delegate declaration creates a new declaration space. Names are introduced into this declaration space through formal parameters (*fixed_parameter*s and *parameter_array*s) and *type_parameter*s.
|
||||
* Each enumeration declaration creates a new declaration space. Names are introduced into this declaration space through *enum_member_declarations*.
|
||||
* Each method declaration, indexer declaration, operator declaration, instance constructor declaration and anonymous function creates a new declaration space called a ***local variable declaration space***. Names are introduced into this declaration space through formal parameters (*fixed_parameter*s and *parameter_array*s) and *type_parameter*s. The body of the function member or anonymous function, if any, is considered to be nested within the local variable declaration space. It is an error for a local variable declaration space and a nested local variable declaration space to contain elements with the same name. Thus, within a nested declaration space it is not possible to declare a local variable or constant with the same name as a local variable or constant in an enclosing declaration space. It is possible for two declaration spaces to contain elements with the same name as long as neither declaration space contains the other.
|
||||
* Each *block* or *switch_block* , as well as a *for*, *foreach* and *using* statement, creates a local variable declaration space for local variables and local constants . Names are introduced into this declaration space through *local_variable_declaration*s and *local_constant_declaration*s. Note that blocks that occur as or within the body of a function member or anonymous function are nested within the local variable declaration space declared by those functions for their parameters. Thus it is an error to have e.g. a method with a local variable and a parameter of the same name.
|
||||
* Each *block* or *switch_block* creates a separate declaration space for labels. Names are introduced into this declaration space through *labeled_statement*s, and the names are referenced through *goto_statement*s. The ***label declaration space*** of a block includes any nested blocks. Thus, within a nested block it is not possible to declare a label with the same name as a label in an enclosing block.
|
||||
|
||||
The textual order in which names are declared is generally of no significance. In particular, textual order is not significant for the declaration and use of namespaces, constants, methods, properties, events, indexers, operators, instance constructors, destructors, static constructors, and types. Declaration order is significant in the following ways:
|
||||
|
||||
* Declaration order for field declarations and local variable declarations determines the order in which their initializers (if any) are executed.
|
||||
* Local variables must be defined before they are used ([Scopes](basic-concepts.md#scopes)).
|
||||
* Declaration order for enum member declarations ([Enum members](enums.md#enum-members)) is significant when *constant_expression* values are omitted.
|
||||
|
||||
The declaration space of a namespace is "open ended", and two namespace declarations with the same fully qualified name contribute to the same declaration space. For example
|
||||
```csharp
|
||||
namespace Megacorp.Data
|
||||
{
|
||||
class Customer
|
||||
{
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
namespace Megacorp.Data
|
||||
{
|
||||
class Order
|
||||
{
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The two namespace declarations above contribute to the same declaration space, in this case declaring two classes with the fully qualified names `Megacorp.Data.Customer` and `Megacorp.Data.Order`. Because the two declarations contribute to the same declaration space, it would have caused a compile-time error if each contained a declaration of a class with the same name.
|
||||
|
||||
As specified above, the declaration space of a block includes any nested blocks. Thus, in the following example, the `F` and `G` methods result in a compile-time error because the name `i` is declared in the outer block and cannot be redeclared in the inner block. However, the `H` and `I` methods are valid since the two `i`'s are declared in separate non-nested blocks.
|
||||
|
||||
```csharp
|
||||
class A
|
||||
{
|
||||
void F() {
|
||||
int i = 0;
|
||||
if (true) {
|
||||
int i = 1;
|
||||
}
|
||||
}
|
||||
|
||||
void G() {
|
||||
if (true) {
|
||||
int i = 0;
|
||||
}
|
||||
int i = 1;
|
||||
}
|
||||
|
||||
void H() {
|
||||
if (true) {
|
||||
int i = 0;
|
||||
}
|
||||
if (true) {
|
||||
int i = 1;
|
||||
}
|
||||
}
|
||||
|
||||
void I() {
|
||||
for (int i = 0; i < 10; i++)
|
||||
H();
|
||||
for (int i = 0; i < 10; i++)
|
||||
H();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Members
|
||||
|
||||
Namespaces and types have ***members***. The members of an entity are generally available through the use of a qualified name that starts with a reference to the entity, followed by a "`.`" token, followed by the name of the member.
|
||||
|
||||
Members of a type are either declared in the type declaration or ***inherited*** from the base class of the type. When a type inherits from a base class, all members of the base class, except instance constructors, destructors and static constructors, become members of the derived type. The declared accessibility of a base class member does not control whether the member is inherited—inheritance extends to any member that isn't an instance constructor, static constructor, or destructor. However, an inherited member may not be accessible in a derived type, either because of its declared accessibility ([Declared accessibility](basic-concepts.md#declared-accessibility)) or because it is hidden by a declaration in the type itself ([Hiding through inheritance](basic-concepts.md#hiding-through-inheritance)).
|
||||
|
||||
### Namespace members
|
||||
|
||||
Namespaces and types that have no enclosing namespace are members of the ***global namespace***. This corresponds directly to the names declared in the global declaration space.
|
||||
|
||||
Namespaces and types declared within a namespace are members of that namespace. This corresponds directly to the names declared in the declaration space of the namespace.
|
||||
|
||||
Namespaces have no access restrictions. It is not possible to declare private, protected, or internal namespaces, and namespace names are always publicly accessible.
|
||||
|
||||
### Struct members
|
||||
|
||||
The members of a struct are the members declared in the struct and the members inherited from the struct's direct base class `System.ValueType` and the indirect base class `object`.
|
||||
|
||||
The members of a simple type correspond directly to the members of the struct type aliased by the simple type:
|
||||
|
||||
* The members of `sbyte` are the members of the `System.SByte` struct.
|
||||
* The members of `byte` are the members of the `System.Byte` struct.
|
||||
* The members of `short` are the members of the `System.Int16` struct.
|
||||
* The members of `ushort` are the members of the `System.UInt16` struct.
|
||||
* The members of `int` are the members of the `System.Int32` struct.
|
||||
* The members of `uint` are the members of the `System.UInt32` struct.
|
||||
* The members of `long` are the members of the `System.Int64` struct.
|
||||
* The members of `ulong` are the members of the `System.UInt64` struct.
|
||||
* The members of `char` are the members of the `System.Char` struct.
|
||||
* The members of `float` are the members of the `System.Single` struct.
|
||||
* The members of `double` are the members of the `System.Double` struct.
|
||||
* The members of `decimal` are the members of the `System.Decimal` struct.
|
||||
* The members of `bool` are the members of the `System.Boolean` struct.
|
||||
|
||||
### Enumeration members
|
||||
|
||||
The members of an enumeration are the constants declared in the enumeration and the members inherited from the enumeration's direct base class `System.Enum` and the indirect base classes `System.ValueType` and `object`.
|
||||
|
||||
### Class members
|
||||
|
||||
The members of a class are the members declared in the class and the members inherited from the base class (except for class `object` which has no base class). The members inherited from the base class include the constants, fields, methods, properties, events, indexers, operators, and types of the base class, but not the instance constructors, destructors and static constructors of the base class. Base class members are inherited without regard to their accessibility.
|
||||
|
||||
A class declaration may contain declarations of constants, fields, methods, properties, events, indexers, operators, instance constructors, destructors, static constructors and types.
|
||||
|
||||
The members of `object` and `string` correspond directly to the members of the class types they alias:
|
||||
|
||||
* The members of `object` are the members of the `System.Object` class.
|
||||
* The members of `string` are the members of the `System.String` class.
|
||||
|
||||
### Interface members
|
||||
|
||||
The members of an interface are the members declared in the interface and in all base interfaces of the interface. The members in class `object` are not, strictly speaking, members of any interface ([Interface members](interfaces.md#interface-members)). However, the members in class `object` are available via member lookup in any interface type ([Member lookup](expressions.md#member-lookup)).
|
||||
|
||||
### Array members
|
||||
|
||||
The members of an array are the members inherited from class `System.Array`.
|
||||
|
||||
### Delegate members
|
||||
|
||||
The members of a delegate are the members inherited from class `System.Delegate`.
|
||||
|
||||
## Member access
|
||||
|
||||
Declarations of members allow control over member access. The accessibility of a member is established by the declared accessibility ([Declared accessibility](basic-concepts.md#declared-accessibility)) of the member combined with the accessibility of the immediately containing type, if any.
|
||||
|
||||
When access to a particular member is allowed, the member is said to be ***accessible***. Conversely, when access to a particular member is disallowed, the member is said to be ***inaccessible***. Access to a member is permitted when the textual location in which the access takes place is included in the accessibility domain ([Accessibility domains](basic-concepts.md#accessibility-domains)) of the member.
|
||||
|
||||
### Declared accessibility
|
||||
|
||||
The ***declared accessibility*** of a member can be one of the following:
|
||||
|
||||
* Public, which is selected by including a `public` modifier in the member declaration. The intuitive meaning of `public` is "access not limited".
|
||||
* Protected, which is selected by including a `protected` modifier in the member declaration. The intuitive meaning of `protected` is "access limited to the containing class or types derived from the containing class".
|
||||
* Internal, which is selected by including an `internal` modifier in the member declaration. The intuitive meaning of `internal` is "access limited to this program".
|
||||
* Protected internal (meaning protected or internal), which is selected by including both a `protected` and an `internal` modifier in the member declaration. The intuitive meaning of `protected internal` is "access limited to this program or types derived from the containing class".
|
||||
* Private, which is selected by including a `private` modifier in the member declaration. The intuitive meaning of `private` is "access limited to the containing type".
|
||||
|
||||
Depending on the context in which a member declaration takes place, only certain types of declared accessibility are permitted. Furthermore, when a member declaration does not include any access modifiers, the context in which the declaration takes place determines the default declared accessibility.
|
||||
|
||||
* Namespaces implicitly have `public` declared accessibility. No access modifiers are allowed on namespace declarations.
|
||||
* Types declared in compilation units or namespaces can have `public` or `internal` declared accessibility and default to `internal` declared accessibility.
|
||||
* Class members can have any of the five kinds of declared accessibility and default to `private` declared accessibility. (Note that a type declared as a member of a class can have any of the five kinds of declared accessibility, whereas a type declared as a member of a namespace can have only `public` or `internal` declared accessibility.)
|
||||
* Struct members can have `public`, `internal`, or `private` declared accessibility and default to `private` declared accessibility because structs are implicitly sealed. Struct members introduced in a struct (that is, not inherited by that struct) cannot have `protected` or `protected internal` declared accessibility. (Note that a type declared as a member of a struct can have `public`, `internal`, or `private` declared accessibility, whereas a type declared as a member of a namespace can have only `public` or `internal` declared accessibility.)
|
||||
* Interface members implicitly have `public` declared accessibility. No access modifiers are allowed on interface member declarations.
|
||||
* Enumeration members implicitly have `public` declared accessibility. No access modifiers are allowed on enumeration member declarations.
|
||||
|
||||
### Accessibility domains
|
||||
|
||||
The ***accessibility domain*** of a member consists of the (possibly disjoint) sections of program text in which access to the member is permitted. For purposes of defining the accessibility domain of a member, a member is said to be ***top-level*** if it is not declared within a type, and a member is said to be ***nested*** if it is declared within another type. Furthermore, the ***program text*** of a program is defined as all program text contained in all source files of the program, and the program text of a type is defined as all program text contained in the *type_declaration*s of that type (including, possibly, types that are nested within the type).
|
||||
|
||||
The accessibility domain of a predefined type (such as `object`, `int`, or `double`) is unlimited.
|
||||
|
||||
The accessibility domain of a top-level unbound type `T` ([Bound and unbound types](types.md#bound-and-unbound-types)) that is declared in a program `P` is defined as follows:
|
||||
|
||||
* If the declared accessibility of `T` is `public`, the accessibility domain of `T` is the program text of `P` and any program that references `P`.
|
||||
* If the declared accessibility of `T` is `internal`, the accessibility domain of `T` is the program text of `P`.
|
||||
|
||||
From these definitions it follows that the accessibility domain of a top-level unbound type is always at least the program text of the program in which that type is declared.
|
||||
|
||||
The accessibility domain for a constructed type `T<A1, ..., An>` is the intersection of the accessibility domain of the unbound generic type `T` and the accessibility domains of the type arguments `A1, ..., An`.
|
||||
|
||||
The accessibility domain of a nested member `M` declared in a type `T` within a program `P` is defined as follows (noting that `M` itself may possibly be a type):
|
||||
|
||||
* If the declared accessibility of `M` is `public`, the accessibility domain of `M` is the accessibility domain of `T`.
|
||||
* If the declared accessibility of `M` is `protected internal`, let `D` be the union of the program text of `P` and the program text of any type derived from `T`, which is declared outside `P`. The accessibility domain of `M` is the intersection of the accessibility domain of `T` with `D`.
|
||||
* If the declared accessibility of `M` is `protected`, let `D` be the union of the program text of `T` and the program text of any type derived from `T`. The accessibility domain of `M` is the intersection of the accessibility domain of `T` with `D`.
|
||||
* If the declared accessibility of `M` is `internal`, the accessibility domain of `M` is the intersection of the accessibility domain of `T` with the program text of `P`.
|
||||
* If the declared accessibility of `M` is `private`, the accessibility domain of `M` is the program text of `T`.
|
||||
|
||||
From these definitions it follows that the accessibility domain of a nested member is always at least the program text of the type in which the member is declared. Furthermore, it follows that the accessibility domain of a member is never more inclusive than the accessibility domain of the type in which the member is declared.
|
||||
|
||||
In intuitive terms, when a type or member `M` is accessed, the following steps are evaluated to ensure that the access is permitted:
|
||||
|
||||
* First, if `M` is declared within a type (as opposed to a compilation unit or a namespace), a compile-time error occurs if that type is not accessible.
|
||||
* Then, if `M` is `public`, the access is permitted.
|
||||
* Otherwise, if `M` is `protected internal`, the access is permitted if it occurs within the program in which `M` is declared, or if it occurs within a class derived from the class in which `M` is declared and takes place through the derived class type ([Protected access for instance members](basic-concepts.md#protected-access-for-instance-members)).
|
||||
* Otherwise, if `M` is `protected`, the access is permitted if it occurs within the class in which `M` is declared, or if it occurs within a class derived from the class in which `M` is declared and takes place through the derived class type ([Protected access for instance members](basic-concepts.md#protected-access-for-instance-members)).
|
||||
* Otherwise, if `M` is `internal`, the access is permitted if it occurs within the program in which `M` is declared.
|
||||
* Otherwise, if `M` is `private`, the access is permitted if it occurs within the type in which `M` is declared.
|
||||
* Otherwise, the type or member is inaccessible, and a compile-time error occurs.
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
public class A
|
||||
{
|
||||
public static int X;
|
||||
internal static int Y;
|
||||
private static int Z;
|
||||
}
|
||||
|
||||
internal class B
|
||||
{
|
||||
public static int X;
|
||||
internal static int Y;
|
||||
private static int Z;
|
||||
|
||||
public class C
|
||||
{
|
||||
public static int X;
|
||||
internal static int Y;
|
||||
private static int Z;
|
||||
}
|
||||
|
||||
private class D
|
||||
{
|
||||
public static int X;
|
||||
internal static int Y;
|
||||
private static int Z;
|
||||
}
|
||||
}
|
||||
```
|
||||
the classes and members have the following accessibility domains:
|
||||
|
||||
* The accessibility domain of `A` and `A.X` is unlimited.
|
||||
* The accessibility domain of `A.Y`, `B`, `B.X`, `B.Y`, `B.C`, `B.C.X`, and `B.C.Y` is the program text of the containing program.
|
||||
* The accessibility domain of `A.Z` is the program text of `A`.
|
||||
* The accessibility domain of `B.Z` and `B.D` is the program text of `B`, including the program text of `B.C` and `B.D`.
|
||||
* The accessibility domain of `B.C.Z` is the program text of `B.C`.
|
||||
* The accessibility domain of `B.D.X` and `B.D.Y` is the program text of `B`, including the program text of `B.C` and `B.D`.
|
||||
* The accessibility domain of `B.D.Z` is the program text of `B.D`.
|
||||
|
||||
As the example illustrates, the accessibility domain of a member is never larger than that of a containing type. For example, even though all `X` members have public declared accessibility, all but `A.X` have accessibility domains that are constrained by a containing type.
|
||||
|
||||
As described in [Members](basic-concepts.md#members), all members of a base class, except for instance constructors, destructors and static constructors, are inherited by derived types. This includes even private members of a base class. However, the accessibility domain of a private member includes only the program text of the type in which the member is declared. In the example
|
||||
```csharp
|
||||
class A
|
||||
{
|
||||
int x;
|
||||
|
||||
static void F(B b) {
|
||||
b.x = 1; // Ok
|
||||
}
|
||||
}
|
||||
|
||||
class B: A
|
||||
{
|
||||
static void F(B b) {
|
||||
b.x = 1; // Error, x not accessible
|
||||
}
|
||||
}
|
||||
```
|
||||
the `B` class inherits the private member `x` from the `A` class. Because the member is private, it is only accessible within the *class_body* of `A`. Thus, the access to `b.x` succeeds in the `A.F` method, but fails in the `B.F` method.
|
||||
|
||||
### 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* ([Constructor initializers](classes.md#constructor-initializers)).
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
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
|
||||
```csharp
|
||||
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
|
||||
```csharp
|
||||
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
|
||||
```csharp
|
||||
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 `params` modifier 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.
|
||||
```csharp
|
||||
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 ([Method parameters](classes.md#method-parameters)) 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 [Declarations](basic-concepts.md#declarations) 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* ([Namespace members](namespaces.md#namespace-members)) 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_directive*s, *global_attributes* and *namespace_member_declaration*s 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* ([Using directives](namespaces.md#using-directives)) extends over the *namespace_member_declaration*s of the *compilation_unit* or *namespace_body* in which the *using_directive* occurs. A *using_directive* may make zero or more namespace, type or member 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* ([Class declarations](classes.md#class-declarations)) is the *class_base*, *type_parameter_constraints_clause*s, and *class_body* of that *class_declaration*.
|
||||
* The scope of a type parameter declared by a *type_parameter_list* on a *struct_declaration* ([Struct declarations](structs.md#struct-declarations)) is the *struct_interfaces*, *type_parameter_constraints_clause*s, and *struct_body* of that *struct_declaration*.
|
||||
* The scope of a type parameter declared by a *type_parameter_list* on an *interface_declaration* ([Interface declarations](interfaces.md#interface-declarations)) is the *interface_base*, *type_parameter_constraints_clause*s, and *interface_body* of that *interface_declaration*.
|
||||
* The scope of a type parameter declared by a *type_parameter_list* on a *delegate_declaration* ([Delegate declarations](delegates.md#delegate-declarations)) is the *return_type*, *formal_parameter_list*, and *type_parameter_constraints_clause*s of that *delegate_declaration*.
|
||||
* The scope of a member declared by a *class_member_declaration* ([Class body](classes.md#class-body)) 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 ([Accessibility domains](basic-concepts.md#accessibility-domains)) of the member.
|
||||
* The scope of a member declared by a *struct_member_declaration* ([Struct members](structs.md#struct-members)) is the *struct_body* in which the declaration occurs.
|
||||
* The scope of a member declared by an *enum_member_declaration* ([Enum members](enums.md#enum-members)) is the *enum_body* in which the declaration occurs.
|
||||
* The scope of a parameter declared in a *method_declaration* ([Methods](classes.md#methods)) is the *method_body* of that *method_declaration*.
|
||||
* The scope of a parameter declared in an *indexer_declaration* ([Indexers](classes.md#indexers)) is the *accessor_declarations* of that *indexer_declaration*.
|
||||
* The scope of a parameter declared in an *operator_declaration* ([Operators](classes.md#operators)) is the *block* of that *operator_declaration*.
|
||||
* The scope of a parameter declared in a *constructor_declaration* ([Instance constructors](classes.md#instance-constructors)) is the *constructor_initializer* and *block* of that *constructor_declaration*.
|
||||
* The scope of a parameter declared in a *lambda_expression* ([Anonymous function expressions](expressions.md#anonymous-function-expressions)) is the *anonymous_function_body* of that *lambda_expression*
|
||||
* The scope of a parameter declared in an *anonymous_method_expression* ([Anonymous function expressions](expressions.md#anonymous-function-expressions)) is the *block* of that *anonymous_method_expression*.
|
||||
* The scope of a label declared in a *labeled_statement* ([Labeled statements](statements.md#labeled-statements)) is the *block* in which the declaration occurs.
|
||||
* The scope of a local variable declared in a *local_variable_declaration* ([Local variable declarations](statements.md#local-variable-declarations)) is the block in which the declaration occurs.
|
||||
* The scope of a local variable declared in a *switch_block* of a `switch` statement ([The switch statement](statements.md#the-switch-statement)) is the *switch_block*.
|
||||
* The scope of a local variable declared in a *for_initializer* of a `for` statement ([The for statement](statements.md#the-for-statement)) 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* ([Local constant declarations](statements.md#local-constant-declarations)) 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
|
||||
```csharp
|
||||
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
|
||||
```csharp
|
||||
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
|
||||
```csharp
|
||||
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
|
||||
```csharp
|
||||
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
|
||||
```csharp
|
||||
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 ([Operators](classes.md#operators)) 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
|
||||
```csharp
|
||||
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:
|
||||
```csharp
|
||||
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.
|
||||
|
||||
```csharp
|
||||
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.
|
||||
|
||||
```antlr
|
||||
namespace_name
|
||||
: namespace_or_type_name
|
||||
;
|
||||
|
||||
type_name
|
||||
: namespace_or_type_name
|
||||
;
|
||||
|
||||
namespace_or_type_name
|
||||
: identifier type_argument_list?
|
||||
| namespace_or_type_name '.' identifier type_argument_list?
|
||||
| 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 ([Type arguments](types.md#type-arguments)) 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 [Namespace alias qualifiers](namespaces.md#namespace-alias-qualifiers). Otherwise, a *namespace_or_type_name* has one of four forms:
|
||||
|
||||
* `I`
|
||||
* `I<A1, ..., Ak>`
|
||||
* `N.I`
|
||||
* `N.I<A1, ..., Ak>`
|
||||
|
||||
where `I` is a single identifier, `N` is a *namespace_or_type_name* and `<A1, ..., Ak>` 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<A1, ..., Ak>`:
|
||||
* If `K` is zero and the *namespace_or_type_name* appears within a generic method declaration ([Methods](classes.md#methods)) and if that declaration includes a type parameter ([Type parameters](classes.md#type-parameters)) with name `I`, then the *namespace_or_type_name* refers to that type parameter.
|
||||
* Otherwise, if the *namespace_or_type_name* appears within a type declaration, then for each instance type `T` ([The instance type](classes.md#the-instance-type)), 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*.
|
||||
* 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:
|
||||
* 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.
|
||||
* 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:
|
||||
* 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.
|
||||
* 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`:
|
||||
* 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.
|
||||
* Otherwise, if the namespaces and type declarations imported by the *using_namespace_directive*s and *using_alias_directive*s of the namespace declaration contain exactly one 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.
|
||||
* Otherwise, if the namespaces and type declarations imported by the *using_namespace_directive*s and *using_alias_directive*s of the namespace declaration contain more than one accessible type having name `I` and `K` type parameters, then the *namespace_or_type_name* is ambiguous and an error occurs.
|
||||
* 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<A1, ..., Ak>`. `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<A1, ..., Ak>` is resolved as follows:
|
||||
* 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.
|
||||
* 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.
|
||||
* 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 ([Base classes](classes.md#base-classes)).
|
||||
* 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 ([Static classes](classes.md#static-classes)) 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* ([Argument lists](expressions.md#argument-lists)1) 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.
|
||||
```csharp
|
||||
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 ([Destructors](classes.md#destructors)) (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
|
||||
```csharp
|
||||
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,
|
||||
```csharp
|
||||
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 ([The using statement](statements.md#the-using-statement)).
|
||||
|
||||
## 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 effect*** is 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 ([Volatile fields](classes.md#volatile-fields)), `lock` statements ([The lock statement](statements.md#the-lock-statement)), 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 ([Field initialization](classes.md#field-initialization) and [Variable initializers](classes.md#variable-initializers)).
|
||||
* The ordering of side effects is preserved with respect to volatile reads and writes ([Volatile fields](classes.md#volatile-fields)). 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.
|
||||
4738
spec/classes.md
Normal file
4738
spec/classes.md
Normal file
File diff suppressed because it is too large
Load diff
800
spec/conversions.md
Normal file
800
spec/conversions.md
Normal file
|
|
@ -0,0 +1,800 @@
|
|||
# Conversions
|
||||
|
||||
A ***conversion*** enables an expression to be treated as being of a particular type. A conversion may cause an expression of a given type to be treated as having a different type, or it may cause an expression without a type to get a type. Conversions can be ***implicit*** or ***explicit***, and this determines whether an explicit cast is required. For instance, the conversion from type `int` to type `long` is implicit, so expressions of type `int` can implicitly be treated as type `long`. The opposite conversion, from type `long` to type `int`, is explicit and so an explicit cast is required.
|
||||
|
||||
```csharp
|
||||
int a = 123;
|
||||
long b = a; // implicit conversion from int to long
|
||||
int c = (int) b; // explicit conversion from long to int
|
||||
```
|
||||
|
||||
Some conversions are defined by the language. Programs may also define their own conversions ([User-defined conversions](conversions.md#user-defined-conversions)).
|
||||
|
||||
## Implicit conversions
|
||||
|
||||
The following conversions are classified as implicit conversions:
|
||||
|
||||
* Identity conversions
|
||||
* Implicit numeric conversions
|
||||
* Implicit enumeration conversions.
|
||||
* Implicit nullable conversions
|
||||
* Null literal conversions
|
||||
* Implicit reference conversions
|
||||
* Boxing conversions
|
||||
* Implicit dynamic conversions
|
||||
* Implicit constant expression conversions
|
||||
* User-defined implicit conversions
|
||||
* Anonymous function conversions
|
||||
* Method group conversions
|
||||
|
||||
Implicit conversions can occur in a variety of situations, including function member invocations ([Compile-time checking of dynamic overload resolution](expressions.md#compile-time-checking-of-dynamic-overload-resolution)), cast expressions ([Cast expressions](expressions.md#cast-expressions)), and assignments ([Assignment operators](expressions.md#assignment-operators)).
|
||||
|
||||
The pre-defined implicit conversions always succeed and never cause exceptions to be thrown. Properly designed user-defined implicit conversions should exhibit these characteristics as well.
|
||||
|
||||
For the purposes of conversion, the types `object` and `dynamic` are considered equivalent.
|
||||
|
||||
However, dynamic conversions ([Implicit dynamic conversions](conversions.md#implicit-dynamic-conversions) and [Explicit dynamic conversions](conversions.md#explicit-dynamic-conversions)) apply only to expressions of type `dynamic` ([The dynamic type](types.md#the-dynamic-type)).
|
||||
|
||||
### Identity conversion
|
||||
|
||||
An identity conversion converts from any type to the same type. This conversion exists such that an entity that already has a required type can be said to be convertible to that type.
|
||||
|
||||
* Because object and dynamic are considered equivalent there is an identity conversion between `object` and `dynamic`, and between constructed types that are the same when replacing all occurences of `dynamic` with `object`.
|
||||
|
||||
### Implicit numeric conversions
|
||||
|
||||
The implicit numeric conversions are:
|
||||
|
||||
* From `sbyte` to `short`, `int`, `long`, `float`, `double`, or `decimal`.
|
||||
* From `byte` to `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `float`, `double`, or `decimal`.
|
||||
* From `short` to `int`, `long`, `float`, `double`, or `decimal`.
|
||||
* From `ushort` to `int`, `uint`, `long`, `ulong`, `float`, `double`, or `decimal`.
|
||||
* From `int` to `long`, `float`, `double`, or `decimal`.
|
||||
* From `uint` to `long`, `ulong`, `float`, `double`, or `decimal`.
|
||||
* From `long` to `float`, `double`, or `decimal`.
|
||||
* From `ulong` to `float`, `double`, or `decimal`.
|
||||
* From `char` to `ushort`, `int`, `uint`, `long`, `ulong`, `float`, `double`, or `decimal`.
|
||||
* From `float` to `double`.
|
||||
|
||||
Conversions from `int`, `uint`, `long`, or `ulong` to `float` and from `long` or `ulong` to `double` may cause a loss of precision, but will never cause a loss of magnitude. The other implicit numeric conversions never lose any information.
|
||||
|
||||
There are no implicit conversions to the `char` type, so values of the other integral types do not automatically convert to the `char` type.
|
||||
|
||||
### Implicit enumeration conversions
|
||||
|
||||
An implicit enumeration conversion permits the *decimal_integer_literal* `0` to be converted to any *enum_type* and to any *nullable_type* whose underlying type is an *enum_type*. In the latter case the conversion is evaluated by converting to the underlying *enum_type* and wrapping the result ([Nullable types](types.md#nullable-types)).
|
||||
|
||||
### Implicit interpolated string conversions
|
||||
|
||||
An implicit interpolated string conversion permits an *interpolated_string_expression* ([Interpolated strings](expressions.md#interpolated-strings)) to be converted to `System.IFormattable` or `System.FormattableString` (which implements `System.IFormattable`).
|
||||
|
||||
When this conversion is applied a string value is not composed from the interpolated string. Instead an instance of `System.FormattableString` is created, as further described in [Interpolated strings](expressions.md#interpolated-strings).
|
||||
|
||||
### Implicit nullable conversions
|
||||
|
||||
Predefined implicit conversions that operate on non-nullable value types can also be used with nullable forms of those types. For each of the predefined implicit identity and numeric conversions that convert from a non-nullable value type `S` to a non-nullable value type `T`, the following implicit nullable conversions exist:
|
||||
|
||||
* An implicit conversion from `S?` to `T?`.
|
||||
* An implicit conversion from `S` to `T?`.
|
||||
|
||||
Evaluation of an implicit nullable conversion based on an underlying conversion from `S` to `T` proceeds as follows:
|
||||
|
||||
* If the nullable conversion is from `S?` to `T?`:
|
||||
* If the source value is null (`HasValue` property is false), the result is the null value of type `T?`.
|
||||
* Otherwise, the conversion is evaluated as an unwrapping from `S?` to `S`, followed by the underlying conversion from `S` to `T`, followed by a wrapping ([Nullable types](types.md#nullable-types)) from `T` to `T?`.
|
||||
|
||||
* If the nullable conversion is from `S` to `T?`, the conversion is evaluated as the underlying conversion from `S` to `T` followed by a wrapping from `T` to `T?`.
|
||||
|
||||
### Null literal conversions
|
||||
|
||||
An implicit conversion exists from the `null` literal to any nullable type. This conversion produces the null value ([Nullable types](types.md#nullable-types)) of the given nullable type.
|
||||
|
||||
### Implicit reference conversions
|
||||
|
||||
The implicit reference conversions are:
|
||||
|
||||
* From any *reference_type* to `object` and `dynamic`.
|
||||
* From any *class_type* `S` to any *class_type* `T`, provided `S` is derived from `T`.
|
||||
* From any *class_type* `S` to any *interface_type* `T`, provided `S` implements `T`.
|
||||
* From any *interface_type* `S` to any *interface_type* `T`, provided `S` is derived from `T`.
|
||||
* From an *array_type* `S` with an element type `SE` to an *array_type* `T` with an element type `TE`, provided all of the following are true:
|
||||
* `S` and `T` differ only in element type. In other words, `S` and `T` have the same number of dimensions.
|
||||
* Both `SE` and `TE` are *reference_type*s.
|
||||
* An implicit reference conversion exists from `SE` to `TE`.
|
||||
* From any *array_type* to `System.Array` and the interfaces it implements.
|
||||
* From a single-dimensional array type `S[]` to `System.Collections.Generic.IList<T>` and its base interfaces, provided that there is an implicit identity or reference conversion from `S` to `T`.
|
||||
* From any *delegate_type* to `System.Delegate` and the interfaces it implements.
|
||||
* From the null literal to any *reference_type*.
|
||||
* From any *reference_type* to a *reference_type* `T` if it has an implicit identity or reference conversion to a *reference_type* `T0` and `T0` has an identity conversion to `T`.
|
||||
* From any *reference_type* to an interface or delegate type `T` if it has an implicit identity or reference conversion to an interface or delegate type `T0` and `T0` is variance-convertible ([Variance conversion](interfaces.md#variance-conversion)) to `T`.
|
||||
* Implicit conversions involving type parameters that are known to be reference types. See [Implicit conversions involving type parameters](conversions.md#implicit-conversions-involving-type-parameters) for more details on implicit conversions involving type parameters.
|
||||
|
||||
The implicit reference conversions are those conversions between *reference_type*s that can be proven to always succeed, and therefore require no checks at run-time.
|
||||
|
||||
Reference conversions, implicit or explicit, never change the referential identity of the object being converted. In other words, while a reference conversion may change the type of the reference, it never changes the type or value of the object being referred to.
|
||||
|
||||
### Boxing conversions
|
||||
|
||||
A boxing conversion permits a *value_type* to be implicitly converted to a reference type. A boxing conversion exists from any *non_nullable_value_type* to `object` and `dynamic`, to `System.ValueType` and to any *interface_type* implemented by the *non_nullable_value_type*. Furthermore an *enum_type* can be converted to the type `System.Enum`.
|
||||
|
||||
A boxing conversion exists from a *nullable_type* to a reference type, if and only if a boxing conversion exists from the underlying *non_nullable_value_type* to the reference type.
|
||||
|
||||
A value type has a boxing conversion to an interface type `I` if it has a boxing conversion to an interface type `I0` and `I0` has an identity conversion to `I`.
|
||||
|
||||
A value type has a boxing conversion to an interface type `I` if it has a boxing conversion to an interface or delegate type `I0` and `I0` is variance-convertible ([Variance conversion](interfaces.md#variance-conversion)) to `I`.
|
||||
|
||||
Boxing a value of a *non_nullable_value_type* consists of allocating an object instance and copying the *value_type* value into that instance. A struct can be boxed to the type `System.ValueType`, since that is a base class for all structs ([Inheritance](structs.md#inheritance)).
|
||||
|
||||
Boxing a value of a *nullable_type* proceeds as follows:
|
||||
|
||||
* If the source value is null (`HasValue` property is false), the result is a null reference of the target type.
|
||||
* Otherwise, the result is a reference to a boxed `T` produced by unwrapping and boxing the source value.
|
||||
|
||||
Boxing conversions are described further in [Boxing conversions](types.md#boxing-conversions).
|
||||
|
||||
### Implicit dynamic conversions
|
||||
|
||||
An implicit dynamic conversion exists from an expression of type `dynamic` to any type `T`. The conversion is dynamically bound ([Dynamic binding](expressions.md#dynamic-binding)), which means that an implicit conversion will be sought at run-time from the run-time type of the expression to `T`. If no conversion is found, a run-time exception is thrown.
|
||||
|
||||
Note that this implicit conversion seemingly violates the advice in the beginning of [Implicit conversions](conversions.md#implicit-conversions) that an implicit conversion should never cause an exception. However it is not the conversion itself, but the *finding* of the conversion that causes the exception. The risk of run-time exceptions is inherent in the use of dynamic binding. If dynamic binding of the conversion is not desired, the expression can be first converted to `object`, and then to the desired type.
|
||||
|
||||
The following example illustrates implicit dynamic conversions:
|
||||
|
||||
```csharp
|
||||
object o = "object"
|
||||
dynamic d = "dynamic";
|
||||
|
||||
string s1 = o; // Fails at compile-time -- no conversion exists
|
||||
string s2 = d; // Compiles and succeeds at run-time
|
||||
int i = d; // Compiles but fails at run-time -- no conversion exists
|
||||
```
|
||||
|
||||
The assignments to `s2` and `i` both employ implicit dynamic conversions, where the binding of the operations is suspended until run-time. At run-time, implicit conversions are sought from the run-time type of `d` -- `string` -- to the target type. A conversion is found to `string` but not to `int`.
|
||||
|
||||
### Implicit constant expression conversions
|
||||
|
||||
An implicit constant expression conversion permits the following conversions:
|
||||
|
||||
* A *constant_expression* ([Constant expressions](expressions.md#constant-expressions)) of type `int` can be converted to type `sbyte`, `byte`, `short`, `ushort`, `uint`, or `ulong`, provided the value of the *constant_expression* is within the range of the destination type.
|
||||
* A *constant_expression* of type `long` can be converted to type `ulong`, provided the value of the *constant_expression* is not negative.
|
||||
|
||||
### Implicit conversions involving type parameters
|
||||
|
||||
The following implicit conversions exist for a given type parameter `T`:
|
||||
|
||||
* From `T` to its effective base class `C`, from `T` to any base class of `C`, and from `T` to any interface implemented by `C`. At run-time, if `T` is a value type, the conversion is executed as a boxing conversion. Otherwise, the conversion is executed as an implicit reference conversion or identity conversion.
|
||||
* From `T` to an interface type `I` in `T`'s effective interface set and from `T` to any base interface of `I`. At run-time, if `T` is a value type, the conversion is executed as a boxing conversion. Otherwise, the conversion is executed as an implicit reference conversion or identity conversion.
|
||||
* From `T` to a type parameter `U`, provided `T` depends on `U` ([Type parameter constraints](classes.md#type-parameter-constraints)). At run-time, if `U` is a value type, then `T` and `U` are necessarily the same type and no conversion is performed. Otherwise, if `T` is a value type, the conversion is executed as a boxing conversion. Otherwise, the conversion is executed as an implicit reference conversion or identity conversion.
|
||||
* From the null literal to `T`, provided `T` is known to be a reference type.
|
||||
* From `T` to a reference type `I` if it has an implicit conversion to a reference type `S0` and `S0` has an identity conversion to `S`. At run-time the conversion is executed the same way as the conversion to `S0`.
|
||||
* From `T` to an interface type `I` if it has an implicit conversion to an interface or delegate type `I0` and `I0` is variance-convertible to `I` ([Variance conversion](interfaces.md#variance-conversion)). At run-time, if `T` is a value type, the conversion is executed as a boxing conversion. Otherwise, the conversion is executed as an implicit reference conversion or identity conversion.
|
||||
|
||||
If `T` is known to be a reference type ([Type parameter constraints](classes.md#type-parameter-constraints)), the conversions above are all classified as implicit reference conversions ([Implicit reference conversions](conversions.md#implicit-reference-conversions)). If `T` is not known to be a reference type, the conversions above are classified as boxing conversions ([Boxing conversions](conversions.md#boxing-conversions)).
|
||||
|
||||
### User-defined implicit conversions
|
||||
|
||||
A user-defined implicit conversion consists of an optional standard implicit conversion, followed by execution of a user-defined implicit conversion operator, followed by another optional standard implicit conversion. The exact rules for evaluating user-defined implicit conversions are described in [Processing of user-defined implicit conversions](conversions.md#processing-of-user-defined-implicit-conversions).
|
||||
|
||||
### Anonymous function conversions and method group conversions
|
||||
|
||||
Anonymous functions and method groups do not have types in and of themselves, but may be implicitly converted to delegate types or expression tree types. Anonymous function conversions are described in more detail in [Anonymous function conversions](conversions.md#anonymous-function-conversions) and method group conversions in [Method group conversions](conversions.md#method-group-conversions).
|
||||
|
||||
## Explicit conversions
|
||||
|
||||
The following conversions are classified as explicit conversions:
|
||||
|
||||
* All implicit conversions.
|
||||
* Explicit numeric conversions.
|
||||
* Explicit enumeration conversions.
|
||||
* Explicit nullable conversions.
|
||||
* Explicit reference conversions.
|
||||
* Explicit interface conversions.
|
||||
* Unboxing conversions.
|
||||
* Explicit dynamic conversions
|
||||
* User-defined explicit conversions.
|
||||
|
||||
Explicit conversions can occur in cast expressions ([Cast expressions](expressions.md#cast-expressions)).
|
||||
|
||||
The set of explicit conversions includes all implicit conversions. This means that redundant cast expressions are allowed.
|
||||
|
||||
The explicit conversions that are not implicit conversions are conversions that cannot be proven to always succeed, conversions that are known to possibly lose information, and conversions across domains of types sufficiently different to merit explicit notation.
|
||||
|
||||
### Explicit numeric conversions
|
||||
|
||||
The explicit numeric conversions are the conversions from a *numeric_type* to another *numeric_type* for which an implicit numeric conversion ([Implicit numeric conversions](conversions.md#implicit-numeric-conversions)) does not already exist:
|
||||
|
||||
* From `sbyte` to `byte`, `ushort`, `uint`, `ulong`, or `char`.
|
||||
* From `byte` to `sbyte` and `char`.
|
||||
* From `short` to `sbyte`, `byte`, `ushort`, `uint`, `ulong`, or `char`.
|
||||
* From `ushort` to `sbyte`, `byte`, `short`, or `char`.
|
||||
* From `int` to `sbyte`, `byte`, `short`, `ushort`, `uint`, `ulong`, or `char`.
|
||||
* From `uint` to `sbyte`, `byte`, `short`, `ushort`, `int`, or `char`.
|
||||
* From `long` to `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `ulong`, or `char`.
|
||||
* From `ulong` to `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, or `char`.
|
||||
* From `char` to `sbyte`, `byte`, or `short`.
|
||||
* From `float` to `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `char`, or `decimal`.
|
||||
* From `double` to `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `char`, `float`, or `decimal`.
|
||||
* From `decimal` to `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `char`, `float`, or `double`.
|
||||
|
||||
Because the explicit conversions include all implicit and explicit numeric conversions, it is always possible to convert from any *numeric_type* to any other *numeric_type* using a cast expression ([Cast expressions](expressions.md#cast-expressions)).
|
||||
|
||||
The explicit numeric conversions possibly lose information or possibly cause exceptions to be thrown. An explicit numeric conversion is processed as follows:
|
||||
|
||||
* For a conversion from an integral type to another integral type, the processing depends on the overflow checking context ([The checked and unchecked operators](expressions.md#the-checked-and-unchecked-operators)) in which the conversion takes place:
|
||||
* In a `checked` context, the conversion succeeds if the value of the source operand is within the range of the destination type, but throws a `System.OverflowException` if the value of the source operand is outside the range of the destination type.
|
||||
* In an `unchecked` context, the conversion always succeeds, and proceeds as follows.
|
||||
* If the source type is larger than the destination type, then the source value is truncated by discarding its "extra" most significant bits. The result is then treated as a value of the destination type.
|
||||
* If the source type is smaller than the destination type, then the source value is either sign-extended or zero-extended so that it is the same size as the destination type. Sign-extension is used if the source type is signed; zero-extension is used if the source type is unsigned. The result is then treated as a value of the destination type.
|
||||
* If the source type is the same size as the destination type, then the source value is treated as a value of the destination type.
|
||||
* For a conversion from `decimal` to an integral type, the source value is rounded towards zero to the nearest integral value, and this integral value becomes the result of the conversion. If the resulting integral value is outside the range of the destination type, a `System.OverflowException` is thrown.
|
||||
* For a conversion from `float` or `double` to an integral type, the processing depends on the overflow checking context ([The checked and unchecked operators](expressions.md#the-checked-and-unchecked-operators)) in which the conversion takes place:
|
||||
* In a `checked` context, the conversion proceeds as follows:
|
||||
* If the value of the operand is NaN or infinite, a `System.OverflowException` is thrown.
|
||||
* Otherwise, the source operand is rounded towards zero to the nearest integral value. If this integral value is within the range of the destination type then this value is the result of the conversion.
|
||||
* Otherwise, a `System.OverflowException` is thrown.
|
||||
* In an `unchecked` context, the conversion always succeeds, and proceeds as follows.
|
||||
* If the value of the operand is NaN or infinite, the result of the conversion is an unspecified value of the destination type.
|
||||
* Otherwise, the source operand is rounded towards zero to the nearest integral value. If this integral value is within the range of the destination type then this value is the result of the conversion.
|
||||
* Otherwise, the result of the conversion is an unspecified value of the destination type.
|
||||
* For a conversion from `double` to `float`, the `double` value is rounded to the nearest `float` value. If the `double` value is too small to represent as a `float`, the result becomes positive zero or negative zero. If the `double` value is too large to represent as a `float`, the result becomes positive infinity or negative infinity. If the `double` value is NaN, the result is also NaN.
|
||||
* For a conversion from `float` or `double` to `decimal`, the source value is converted to `decimal` representation and rounded to the nearest number after the 28th decimal place if required ([The decimal type](types.md#the-decimal-type)). If the source value is too small to represent as a `decimal`, the result becomes zero. If the source value is NaN, infinity, or too large to represent as a `decimal`, a `System.OverflowException` is thrown.
|
||||
* For a conversion from `decimal` to `float` or `double`, the `decimal` value is rounded to the nearest `double` or `float` value. While this conversion may lose precision, it never causes an exception to be thrown.
|
||||
|
||||
### Explicit enumeration conversions
|
||||
|
||||
The explicit enumeration conversions are:
|
||||
|
||||
* From `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `char`, `float`, `double`, or `decimal` to any *enum_type*.
|
||||
* From any *enum_type* to `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `char`, `float`, `double`, or `decimal`.
|
||||
* From any *enum_type* to any other *enum_type*.
|
||||
|
||||
An explicit enumeration conversion between two types is processed by treating any participating *enum_type* as the underlying type of that *enum_type*, and then performing an implicit or explicit numeric conversion between the resulting types. For example, given an *enum_type* `E` with and underlying type of `int`, a conversion from `E` to `byte` is processed as an explicit numeric conversion ([Explicit numeric conversions](conversions.md#explicit-numeric-conversions)) from `int` to `byte`, and a conversion from `byte` to `E` is processed as an implicit numeric conversion ([Implicit numeric conversions](conversions.md#implicit-numeric-conversions)) from `byte` to `int`.
|
||||
|
||||
### Explicit nullable conversions
|
||||
|
||||
***Explicit nullable conversions*** permit predefined explicit conversions that operate on non-nullable value types to also be used with nullable forms of those types. For each of the predefined explicit conversions that convert from a non-nullable value type `S` to a non-nullable value type `T` ([Identity conversion](conversions.md#identity-conversion), [Implicit numeric conversions](conversions.md#implicit-numeric-conversions), [Implicit enumeration conversions](conversions.md#implicit-enumeration-conversions), [Explicit numeric conversions](conversions.md#explicit-numeric-conversions), and [Explicit enumeration conversions](conversions.md#explicit-enumeration-conversions)), the following nullable conversions exist:
|
||||
|
||||
* An explicit conversion from `S?` to `T?`.
|
||||
* An explicit conversion from `S` to `T?`.
|
||||
* An explicit conversion from `S?` to `T`.
|
||||
|
||||
Evaluation of a nullable conversion based on an underlying conversion from `S` to `T` proceeds as follows:
|
||||
|
||||
* If the nullable conversion is from `S?` to `T?`:
|
||||
* If the source value is null (`HasValue` property is false), the result is the null value of type `T?`.
|
||||
* Otherwise, the conversion is evaluated as an unwrapping from `S?` to `S`, followed by the underlying conversion from `S` to `T`, followed by a wrapping from `T` to `T?`.
|
||||
* If the nullable conversion is from `S` to `T?`, the conversion is evaluated as the underlying conversion from `S` to `T` followed by a wrapping from `T` to `T?`.
|
||||
* If the nullable conversion is from `S?` to `T`, the conversion is evaluated as an unwrapping from `S?` to `S` followed by the underlying conversion from `S` to `T`.
|
||||
|
||||
Note that an attempt to unwrap a nullable value will throw an exception if the value is `null`.
|
||||
|
||||
### Explicit reference conversions
|
||||
|
||||
The explicit reference conversions are:
|
||||
|
||||
* From `object` and `dynamic` to any other *reference_type*.
|
||||
* From any *class_type* `S` to any *class_type* `T`, provided `S` is a base class of `T`.
|
||||
* From any *class_type* `S` to any *interface_type* `T`, provided `S` is not sealed and provided `S` does not implement `T`.
|
||||
* From any *interface_type* `S` to any *class_type* `T`, provided `T` is not sealed or provided `T` implements `S`.
|
||||
* From any *interface_type* `S` to any *interface_type* `T`, provided `S` is not derived from `T`.
|
||||
* From an *array_type* `S` with an element type `SE` to an *array_type* `T` with an element type `TE`, provided all of the following are true:
|
||||
* `S` and `T` differ only in element type. In other words, `S` and `T` have the same number of dimensions.
|
||||
* Both `SE` and `TE` are *reference_type*s.
|
||||
* An explicit reference conversion exists from `SE` to `TE`.
|
||||
* From `System.Array` and the interfaces it implements to any *array_type*.
|
||||
* From a single-dimensional array type `S[]` to `System.Collections.Generic.IList<T>` and its base interfaces, provided that there is an explicit reference conversion from `S` to `T`.
|
||||
* From `System.Collections.Generic.IList<S>` and its base interfaces to a single-dimensional array type `T[]`, provided that there is an explicit identity or reference conversion from `S` to `T`.
|
||||
* From `System.Delegate` and the interfaces it implements to any *delegate_type*.
|
||||
* From a reference type to a reference type `T` if it has an explicit reference conversion to a reference type `T0` and `T0` has an identity conversion `T`.
|
||||
* From a reference type to an interface or delegate type `T` if it has an explicit reference conversion to an interface or delegate type `T0` and either `T0` is variance-convertible to `T` or `T` is variance-convertible to `T0` ([Variance conversion](interfaces.md#variance-conversion)).
|
||||
* From `D<S1...Sn>` to `D<T1...Tn>` where `D<X1...Xn>` is a generic delegate type, `D<S1...Sn>` is not compatible with or identical to `D<T1...Tn>`, and for each type parameter `Xi` of `D` the following holds:
|
||||
* If `Xi` is invariant, then `Si` is identical to `Ti`.
|
||||
* If `Xi` is covariant, then there is an implicit or explicit identity or reference conversion from `Si` to `Ti`.
|
||||
* If `Xi` is contravariant, then `Si` and `Ti` are either identical or both reference types.
|
||||
* Explicit conversions involving type parameters that are known to be reference types. For more details on explicit conversions involving type parameters, see [Explicit conversions involving type parameters](conversions.md#explicit-conversions-involving-type-parameters).
|
||||
|
||||
The explicit reference conversions are those conversions between reference-types that require run-time checks to ensure they are correct.
|
||||
|
||||
For an explicit reference conversion to succeed at run-time, the value of the source operand must be `null`, or the actual type of the object referenced by the source operand must be a type that can be converted to the destination type by an implicit reference conversion ([Implicit reference conversions](conversions.md#implicit-reference-conversions)) or boxing conversion ([Boxing conversions](conversions.md#boxing-conversions)). If an explicit reference conversion fails, a `System.InvalidCastException` is thrown.
|
||||
|
||||
Reference conversions, implicit or explicit, never change the referential identity of the object being converted. In other words, while a reference conversion may change the type of the reference, it never changes the type or value of the object being referred to.
|
||||
|
||||
### Unboxing conversions
|
||||
|
||||
An unboxing conversion permits a reference type to be explicitly converted to a *value_type*. An unboxing conversion exists from the types `object`, `dynamic` and `System.ValueType` to any *non_nullable_value_type*, and from any *interface_type* to any *non_nullable_value_type* that implements the *interface_type*. Furthermore type `System.Enum` can be unboxed to any *enum_type*.
|
||||
|
||||
An unboxing conversion exists from a reference type to a *nullable_type* if an unboxing conversion exists from the reference type to the underlying *non_nullable_value_type* of the *nullable_type*.
|
||||
|
||||
A value type `S` has an unboxing conversion from an interface type `I` if it has an unboxing conversion from an interface type `I0` and `I0` has an identity conversion to `I`.
|
||||
|
||||
A value type `S` has an unboxing conversion from an interface type `I` if it has an unboxing conversion from an interface or delegate type `I0` and either `I0` is variance-convertible to `I` or `I` is variance-convertible to `I0` ([Variance conversion](interfaces.md#variance-conversion)).
|
||||
|
||||
An unboxing operation consists of first checking that the object instance is a boxed value of the given *value_type*, and then copying the value out of the instance. Unboxing a null reference to a *nullable_type* produces the null value of the *nullable_type*. A struct can be unboxed from the type `System.ValueType`, since that is a base class for all structs ([Inheritance](structs.md#inheritance)).
|
||||
|
||||
Unboxing conversions are described further in [Unboxing conversions](types.md#unboxing-conversions).
|
||||
|
||||
### Explicit dynamic conversions
|
||||
|
||||
An explicit dynamic conversion exists from an expression of type `dynamic` to any type `T`. The conversion is dynamically bound ([Dynamic binding](expressions.md#dynamic-binding)), which means that an explicit conversion will be sought at run-time from the run-time type of the expression to `T`. If no conversion is found, a run-time exception is thrown.
|
||||
|
||||
If dynamic binding of the conversion is not desired, the expression can be first converted to `object`, and then to the desired type.
|
||||
|
||||
Assume the following class is defined:
|
||||
```csharp
|
||||
class C
|
||||
{
|
||||
int i;
|
||||
|
||||
public C(int i) { this.i = i; }
|
||||
|
||||
public static explicit operator C(string s)
|
||||
{
|
||||
return new C(int.Parse(s));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The following example illustrates explicit dynamic conversions:
|
||||
```csharp
|
||||
object o = "1";
|
||||
dynamic d = "2";
|
||||
|
||||
var c1 = (C)o; // Compiles, but explicit reference conversion fails
|
||||
var c2 = (C)d; // Compiles and user defined conversion succeeds
|
||||
```
|
||||
|
||||
The best conversion of `o` to `C` is found at compile-time to be an explicit reference conversion. This fails at run-time, because `"1"` is not in fact a `C`. The conversion of `d` to `C` however, as an explicit dynamic conversion, is suspended to run-time, where a user defined conversion from the run-time type of `d` -- `string` -- to `C` is found, and succeeds.
|
||||
|
||||
### Explicit conversions involving type parameters
|
||||
|
||||
The following explicit conversions exist for a given type parameter `T`:
|
||||
|
||||
* From the effective base class `C` of `T` to `T` and from any base class of `C` to `T`. At run-time, if `T` is a value type, the conversion is executed as an unboxing conversion. Otherwise, the conversion is executed as an explicit reference conversion or identity conversion.
|
||||
* From any interface type to `T`. At run-time, if `T` is a value type, the conversion is executed as an unboxing conversion. Otherwise, the conversion is executed as an explicit reference conversion or identity conversion.
|
||||
* From `T` to any *interface_type* `I` provided there is not already an implicit conversion from `T` to `I`. At run-time, if `T` is a value type, the conversion is executed as a boxing conversion followed by an explicit reference conversion. Otherwise, the conversion is executed as an explicit reference conversion or identity conversion.
|
||||
* From a type parameter `U` to `T`, provided `T` depends on `U` ([Type parameter constraints](classes.md#type-parameter-constraints)). At run-time, if `U` is a value type, then `T` and `U` are necessarily the same type and no conversion is performed. Otherwise, if `T` is a value type, the conversion is executed as an unboxing conversion. Otherwise, the conversion is executed as an explicit reference conversion or identity conversion.
|
||||
|
||||
If `T` is known to be a reference type, the conversions above are all classified as explicit reference conversions ([Explicit reference conversions](conversions.md#explicit-reference-conversions)). If `T` is not known to be a reference type, the conversions above are classified as unboxing conversions ([Unboxing conversions](conversions.md#unboxing-conversions)).
|
||||
|
||||
The above rules do not permit a direct explicit conversion from an unconstrained type parameter to a non-interface type, which might be surprising. The reason for this rule is to prevent confusion and make the semantics of such conversions clear. For example, consider the following declaration:
|
||||
```csharp
|
||||
class X<T>
|
||||
{
|
||||
public static long F(T t) {
|
||||
return (long)t; // Error
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If the direct explicit conversion of `t` to `int` were permitted, one might easily expect that `X<int>.F(7)` would return `7L`. However, it would not, because the standard numeric conversions are only considered when the types are known to be numeric at binding-time. In order to make the semantics clear, the above example must instead be written:
|
||||
```csharp
|
||||
class X<T>
|
||||
{
|
||||
public static long F(T t) {
|
||||
return (long)(object)t; // Ok, but will only work when T is long
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This code will now compile but executing `X<int>.F(7)` would then throw an exception at run-time, since a boxed `int` cannot be converted directly to a `long`.
|
||||
|
||||
### User-defined explicit conversions
|
||||
|
||||
A user-defined explicit conversion consists of an optional standard explicit conversion, followed by execution of a user-defined implicit or explicit conversion operator, followed by another optional standard explicit conversion. The exact rules for evaluating user-defined explicit conversions are described in [Processing of user-defined explicit conversions](conversions.md#processing-of-user-defined-explicit-conversions).
|
||||
|
||||
## Standard conversions
|
||||
|
||||
The standard conversions are those pre-defined conversions that can occur as part of a user-defined conversion.
|
||||
|
||||
### Standard implicit conversions
|
||||
|
||||
The following implicit conversions are classified as standard implicit conversions:
|
||||
|
||||
* Identity conversions ([Identity conversion](conversions.md#identity-conversion))
|
||||
* Implicit numeric conversions ([Implicit numeric conversions](conversions.md#implicit-numeric-conversions))
|
||||
* Implicit nullable conversions ([Implicit nullable conversions](conversions.md#implicit-nullable-conversions))
|
||||
* Implicit reference conversions ([Implicit reference conversions](conversions.md#implicit-reference-conversions))
|
||||
* Boxing conversions ([Boxing conversions](conversions.md#boxing-conversions))
|
||||
* Implicit constant expression conversions ([Implicit dynamic conversions](conversions.md#implicit-dynamic-conversions))
|
||||
* Implicit conversions involving type parameters ([Implicit conversions involving type parameters](conversions.md#implicit-conversions-involving-type-parameters))
|
||||
|
||||
The standard implicit conversions specifically exclude user-defined implicit conversions.
|
||||
|
||||
### Standard explicit conversions
|
||||
|
||||
The standard explicit conversions are all standard implicit conversions plus the subset of the explicit conversions for which an opposite standard implicit conversion exists. In other words, if a standard implicit conversion exists from a type `A` to a type `B`, then a standard explicit conversion exists from type `A` to type `B` and from type `B` to type `A`.
|
||||
|
||||
## User-defined conversions
|
||||
|
||||
C# allows the pre-defined implicit and explicit conversions to be augmented by ***user-defined conversions***. User-defined conversions are introduced by declaring conversion operators ([Conversion operators](classes.md#conversion-operators)) in class and struct types.
|
||||
|
||||
### Permitted user-defined conversions
|
||||
|
||||
C# permits only certain user-defined conversions to be declared. In particular, it is not possible to redefine an already existing implicit or explicit conversion.
|
||||
|
||||
For a given source type `S` and target type `T`, if `S` or `T` are nullable types, let `S0` and `T0` refer to their underlying types, otherwise `S0` and `T0` are equal to `S` and `T` respectively. A class or struct is permitted to declare a conversion from a source type `S` to a target type `T` only if all of the following are true:
|
||||
|
||||
* `S0` and `T0` are different types.
|
||||
* Either `S0` or `T0` is the class or struct type in which the operator declaration takes place.
|
||||
* Neither `S0` nor `T0` is an *interface_type*.
|
||||
* Excluding user-defined conversions, a conversion does not exist from `S` to `T` or from `T` to `S`.
|
||||
|
||||
The restrictions that apply to user-defined conversions are discussed further in [Conversion operators](classes.md#conversion-operators).
|
||||
|
||||
### Lifted conversion operators
|
||||
|
||||
Given a user-defined conversion operator that converts from a non-nullable value type `S` to a non-nullable value type `T`, a ***lifted conversion operator*** exists that converts from `S?` to `T?`. This lifted conversion operator performs an unwrapping from `S?` to `S` followed by the user-defined conversion from `S` to `T` followed by a wrapping from `T` to `T?`, except that a null valued `S?` converts directly to a null valued `T?`.
|
||||
|
||||
A lifted conversion operator has the same implicit or explicit classification as its underlying user-defined conversion operator. The term "user-defined conversion" applies to the use of both user-defined and lifted conversion operators.
|
||||
|
||||
### Evaluation of user-defined conversions
|
||||
|
||||
A user-defined conversion converts a value from its type, called the ***source type***, to another type, called the ***target type***. Evaluation of a user-defined conversion centers on finding the ***most specific*** user-defined conversion operator for the particular source and target types. This determination is broken into several steps:
|
||||
|
||||
* Finding the set of classes and structs from which user-defined conversion operators will be considered. This set consists of the source type and its base classes and the target type and its base classes (with the implicit assumptions that only classes and structs can declare user-defined operators, and that non-class types have no base classes). For the purposes of this step, if either the source or target type is a *nullable_type*, their underlying type is used instead.
|
||||
* From that set of types, determining which user-defined and lifted conversion operators are applicable. For a conversion operator to be applicable, it must be possible to perform a standard conversion ([Standard conversions](conversions.md#standard-conversions)) from the source type to the operand type of the operator, and it must be possible to perform a standard conversion from the result type of the operator to the target type.
|
||||
* From the set of applicable user-defined operators, determining which operator is unambiguously the most specific. In general terms, the most specific operator is the operator whose operand type is "closest" to the source type and whose result type is "closest" to the target type. User-defined conversion operators are preferred over lifted conversion operators. The exact rules for establishing the most specific user-defined conversion operator are defined in the following sections.
|
||||
|
||||
Once a most specific user-defined conversion operator has been identified, the actual execution of the user-defined conversion involves up to three steps:
|
||||
|
||||
* First, if required, performing a standard conversion from the source type to the operand type of the user-defined or lifted conversion operator.
|
||||
* Next, invoking the user-defined or lifted conversion operator to perform the conversion.
|
||||
* Finally, if required, performing a standard conversion from the result type of the user-defined or lifted conversion operator to the target type.
|
||||
|
||||
Evaluation of a user-defined conversion never involves more than one user-defined or lifted conversion operator. In other words, a conversion from type `S` to type `T` will never first execute a user-defined conversion from `S` to `X` and then execute a user-defined conversion from `X` to `T`.
|
||||
|
||||
Exact definitions of evaluation of user-defined implicit or explicit conversions are given in the following sections. The definitions make use of the following terms:
|
||||
|
||||
* If a standard implicit conversion ([Standard implicit conversions](conversions.md#standard-implicit-conversions)) exists from a type `A` to a type `B`, and if neither `A` nor `B` are *interface_type*s, then `A` is said to be ***encompassed by*** `B`, and `B` is said to ***encompass*** `A`.
|
||||
* The ***most encompassing type*** in a set of types is the one type that encompasses all other types in the set. If no single type encompasses all other types, then the set has no most encompassing type. In more intuitive terms, the most encompassing type is the "largest" type in the set—the one type to which each of the other types can be implicitly converted.
|
||||
* The ***most encompassed type*** in a set of types is the one type that is encompassed by all other types in the set. If no single type is encompassed by all other types, then the set has no most encompassed type. In more intuitive terms, the most encompassed type is the "smallest" type in the set—the one type that can be implicitly converted to each of the other types.
|
||||
|
||||
### Processing of user-defined implicit conversions
|
||||
|
||||
A user-defined implicit conversion from type `S` to type `T` is processed as follows:
|
||||
|
||||
* Determine the types `S0` and `T0`. If `S` or `T` are nullable types, `S0` and `T0` are their underlying types, otherwise `S0` and `T0` are equal to `S` and `T` respectively.
|
||||
* Find the set of types, `D`, from which user-defined conversion operators will be considered. This set consists of `S0` (if `S0` is a class or struct), the base classes of `S0` (if `S0` is a class), and `T0` (if `T0` is a class or struct).
|
||||
* Find the set of applicable user-defined and lifted conversion operators, `U`. This set consists of the user-defined and lifted implicit conversion operators declared by the classes or structs in `D` that convert from a type encompassing `S` to a type encompassed by `T`. If `U` is empty, the conversion is undefined and a compile-time error occurs.
|
||||
* Find the most specific source type, `SX`, of the operators in `U`:
|
||||
* If any of the operators in `U` convert from `S`, then `SX` is `S`.
|
||||
* Otherwise, `SX` is the most encompassed type in the combined set of source types of the operators in `U`. If exactly one most encompassed type cannot be found, then the conversion is ambiguous and a compile-time error occurs.
|
||||
* Find the most specific target type, `TX`, of the operators in `U`:
|
||||
* If any of the operators in `U` convert to `T`, then `TX` is `T`.
|
||||
* Otherwise, `TX` is the most encompassing type in the combined set of target types of the operators in `U`. If exactly one most encompassing type cannot be found, then the conversion is ambiguous and a compile-time error occurs.
|
||||
* Find the most specific conversion operator:
|
||||
* If `U` contains exactly one user-defined conversion operator that converts from `SX` to `TX`, then this is the most specific conversion operator.
|
||||
* Otherwise, if `U` contains exactly one lifted conversion operator that converts from `SX` to `TX`, then this is the most specific conversion operator.
|
||||
* Otherwise, the conversion is ambiguous and a compile-time error occurs.
|
||||
* Finally, apply the conversion:
|
||||
* If `S` is not `SX`, then a standard implicit conversion from `S` to `SX` is performed.
|
||||
* The most specific conversion operator is invoked to convert from `SX` to `TX`.
|
||||
* If `TX` is not `T`, then a standard implicit conversion from `TX` to `T` is performed.
|
||||
|
||||
### Processing of user-defined explicit conversions
|
||||
|
||||
A user-defined explicit conversion from type `S` to type `T` is processed as follows:
|
||||
|
||||
* Determine the types `S0` and `T0`. If `S` or `T` are nullable types, `S0` and `T0` are their underlying types, otherwise `S0` and `T0` are equal to `S` and `T` respectively.
|
||||
* Find the set of types, `D`, from which user-defined conversion operators will be considered. This set consists of `S0` (if `S0` is a class or struct), the base classes of `S0` (if `S0` is a class), `T0` (if `T0` is a class or struct), and the base classes of `T0` (if `T0` is a class).
|
||||
* Find the set of applicable user-defined and lifted conversion operators, `U`. This set consists of the user-defined and lifted implicit or explicit conversion operators declared by the classes or structs in `D` that convert from a type encompassing or encompassed by `S` to a type encompassing or encompassed by `T`. If `U` is empty, the conversion is undefined and a compile-time error occurs.
|
||||
* Find the most specific source type, `SX`, of the operators in `U`:
|
||||
* If any of the operators in `U` convert from `S`, then `SX` is `S`.
|
||||
* Otherwise, if any of the operators in `U` convert from types that encompass `S`, then `SX` is the most encompassed type in the combined set of source types of those operators. If no most encompassed type can be found, then the conversion is ambiguous and a compile-time error occurs.
|
||||
* Otherwise, `SX` is the most encompassing type in the combined set of source types of the operators in `U`. If exactly one most encompassing type cannot be found, then the conversion is ambiguous and a compile-time error occurs.
|
||||
* Find the most specific target type, `TX`, of the operators in `U`:
|
||||
* If any of the operators in `U` convert to `T`, then `TX` is `T`.
|
||||
* Otherwise, if any of the operators in `U` convert to types that are encompassed by `T`, then `TX` is the most encompassing type in the combined set of target types of those operators. If exactly one most encompassing type cannot be found, then the conversion is ambiguous and a compile-time error occurs.
|
||||
* Otherwise, `TX` is the most encompassed type in the combined set of target types of the operators in `U`. If no most encompassed type can be found, then the conversion is ambiguous and a compile-time error occurs.
|
||||
* Find the most specific conversion operator:
|
||||
* If `U` contains exactly one user-defined conversion operator that converts from `SX` to `TX`, then this is the most specific conversion operator.
|
||||
* Otherwise, if `U` contains exactly one lifted conversion operator that converts from `SX` to `TX`, then this is the most specific conversion operator.
|
||||
* Otherwise, the conversion is ambiguous and a compile-time error occurs.
|
||||
* Finally, apply the conversion:
|
||||
* If `S` is not `SX`, then a standard explicit conversion from `S` to `SX` is performed.
|
||||
* The most specific user-defined conversion operator is invoked to convert from `SX` to `TX`.
|
||||
* If `TX` is not `T`, then a standard explicit conversion from `TX` to `T` is performed.
|
||||
|
||||
## Anonymous function conversions
|
||||
|
||||
An *anonymous_method_expression* or *lambda_expression* is classified as an anonymous function ([Anonymous function expressions](expressions.md#anonymous-function-expressions)). The expression does not have a type but can be implicitly converted to a compatible delegate type or expression tree type. Specifically, an anonymous function `F` is compatible with a delegate type `D` provided:
|
||||
|
||||
* If `F` contains an *anonymous_function_signature*, then `D` and `F` have the same number of parameters.
|
||||
* If `F` does not contain an *anonymous_function_signature*, then `D` may have zero or more parameters of any type, as long as no parameter of `D` has the `out` parameter modifier.
|
||||
* If `F` has an explicitly typed parameter list, each parameter in `D` has the same type and modifiers as the corresponding parameter in `F`.
|
||||
* If `F` has an implicitly typed parameter list, `D` has no `ref` or `out` parameters.
|
||||
* If the body of `F` is an expression, and either `D` has a `void` return type or `F` is async and `D` has the return type `Task`, then when each parameter of `F` is given the type of the corresponding parameter in `D`, the body of `F` is a valid expression (wrt [Expressions](expressions.md#expressions)) that would be permitted as a *statement_expression* ([Expression statements](statements.md#expression-statements)).
|
||||
* If the body of `F` is a statement block, and either `D` has a `void` return type or `F` is async and `D` has the return type `Task`, then when each parameter of `F` is given the type of the corresponding parameter in `D`, the body of `F` is a valid statement block (wrt [Blocks](statements.md#blocks)) in which no `return` statement specifies an expression.
|
||||
* If the body of `F` is an expression, and *either* `F` is non-async and `D` has a non-void return type `T`, *or* `F` is async and `D` has a return type `Task<T>`, then when each parameter of `F` is given the type of the corresponding parameter in `D`, the body of `F` is a valid expression (wrt [Expressions](expressions.md#expressions)) that is implicitly convertible to `T`.
|
||||
* If the body of `F` is a statement block, and *either* `F` is non-async and `D` has a non-void return type `T`, *or* `F` is async and `D` has a return type `Task<T>`, then when each parameter of `F` is given the type of the corresponding parameter in `D`, the body of `F` is a valid statement block (wrt [Blocks](statements.md#blocks)) with a non-reachable end point in which each `return` statement specifies an expression that is implicitly convertible to `T`.
|
||||
|
||||
For the purpose of brevity, this section uses the short form for the task types `Task` and `Task<T>` ([Async functions](classes.md#async-functions)).
|
||||
|
||||
A lambda expression `F` is compatible with an expression tree type `Expression<D>` if `F` is compatible with the delegate type `D`. Note that this does not apply to anonymous methods, only lambda expressions.
|
||||
|
||||
Certain lambda expressions cannot be converted to expression tree types: Even though the conversion *exists*, it fails at compile-time. This is the case if the lambda expression:
|
||||
|
||||
* Has a *block* body
|
||||
* Contains simple or compound assignment operators
|
||||
* Contains a dynamically bound expression
|
||||
* Is async
|
||||
|
||||
The examples that follow use a generic delegate type `Func<A,R>` which represents a function that takes an argument of type `A` and returns a value of type `R`:
|
||||
```csharp
|
||||
delegate R Func<A,R>(A arg);
|
||||
```
|
||||
|
||||
In the assignments
|
||||
```csharp
|
||||
Func<int,int> f1 = x => x + 1; // Ok
|
||||
|
||||
Func<int,double> f2 = x => x + 1; // Ok
|
||||
|
||||
Func<double,int> f3 = x => x + 1; // Error
|
||||
|
||||
Func<int, Task<int>> f4 = async x => x + 1; // Ok
|
||||
```
|
||||
the parameter and return types of each anonymous function are determined from the type of the variable to which the anonymous function is assigned.
|
||||
|
||||
The first assignment successfully converts the anonymous function to the delegate type `Func<int,int>` because, when `x` is given type `int`, `x+1` is a valid expression that is implicitly convertible to type `int`.
|
||||
|
||||
Likewise, the second assignment successfully converts the anonymous function to the delegate type `Func<int,double>` because the result of `x+1` (of type `int`) is implicitly convertible to type `double`.
|
||||
|
||||
However, the third assignment is a compile-time error because, when `x` is given type `double`, the result of `x+1` (of type `double`) is not implicitly convertible to type `int`.
|
||||
|
||||
The fourth assignment successfully converts the anonymous async function to the delegate type `Func<int, Task<int>>` because the result of `x+1` (of type `int`) is implicitly convertible to the result type `int` of the task type `Task<int>`.
|
||||
|
||||
Anonymous functions may influence overload resolution, and participate in type inference. See [Function members](expressions.md#function-members) for further details.
|
||||
|
||||
### Evaluation of anonymous function conversions to delegate types
|
||||
|
||||
Conversion of an anonymous function to a delegate type produces a delegate instance which references the anonymous function and the (possibly empty) set of captured outer variables that are active at the time of the evaluation. When the delegate is invoked, the body of the anonymous function is executed. The code in the body is executed using the set of captured outer variables referenced by the delegate.
|
||||
|
||||
The invocation list of a delegate produced from an anonymous function contains a single entry. The exact target object and target method of the delegate are unspecified. In particular, it is unspecified whether the target object of the delegate is `null`, the `this` value of the enclosing function member, or some other object.
|
||||
|
||||
Conversions of semantically identical anonymous functions with the same (possibly empty) set of captured outer variable instances to the same delegate types are permitted (but not required) to return the same delegate instance. The term semantically identical is used here to mean that execution of the anonymous functions will, in all cases, produce the same effects given the same arguments. This rule permits code such as the following to be optimized.
|
||||
|
||||
```csharp
|
||||
delegate double Function(double x);
|
||||
|
||||
class Test
|
||||
{
|
||||
static double[] Apply(double[] a, Function f) {
|
||||
double[] result = new double[a.Length];
|
||||
for (int i = 0; i < a.Length; i++) result[i] = f(a[i]);
|
||||
return result;
|
||||
}
|
||||
|
||||
static void F(double[] a, double[] b) {
|
||||
a = Apply(a, (double x) => Math.Sin(x));
|
||||
b = Apply(b, (double y) => Math.Sin(y));
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Since the two anonymous function delegates have the same (empty) set of captured outer variables, and since the anonymous functions are semantically identical, the compiler is permitted to have the delegates refer to the same target method. Indeed, the compiler is permitted to return the very same delegate instance from both anonymous function expressions.
|
||||
|
||||
### Evaluation of anonymous function conversions to expression tree types
|
||||
|
||||
Conversion of an anonymous function to an expression tree type produces an expression tree ([Expression tree types](types.md#expression-tree-types)). More precisely, evaluation of the anonymous function conversion leads to the construction of an object structure that represents the structure of the anonymous function itself. The precise structure of the expression tree, as well as the exact process for creating it, are implementation defined.
|
||||
|
||||
### Implementation example
|
||||
|
||||
This section describes a possible implementation of anonymous function conversions in terms of other C# constructs. The implementation described here is based on the same principles used by the Microsoft C# compiler, but it is by no means a mandated implementation, nor is it the only one possible. It only briefly mentions conversions to expression trees, as their exact semantics are outside the scope of this specification.
|
||||
|
||||
The remainder of this section gives several examples of code that contains anonymous functions with different characteristics. For each example, a corresponding translation to code that uses only other C# constructs is provided. In the examples, the identifier `D` is assumed by represent the following delegate type:
|
||||
```csharp
|
||||
public delegate void D();
|
||||
```
|
||||
|
||||
The simplest form of an anonymous function is one that captures no outer variables:
|
||||
```csharp
|
||||
class Test
|
||||
{
|
||||
static void F() {
|
||||
D d = () => { Console.WriteLine("test"); };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This can be translated to a delegate instantiation that references a compiler generated static method in which the code of the anonymous function is placed:
|
||||
```csharp
|
||||
class Test
|
||||
{
|
||||
static void F() {
|
||||
D d = new D(__Method1);
|
||||
}
|
||||
|
||||
static void __Method1() {
|
||||
Console.WriteLine("test");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the following example, the anonymous function references instance members of `this`:
|
||||
```csharp
|
||||
class Test
|
||||
{
|
||||
int x;
|
||||
|
||||
void F() {
|
||||
D d = () => { Console.WriteLine(x); };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This can be translated to a compiler generated instance method containing the code of the anonymous function:
|
||||
```csharp
|
||||
class Test
|
||||
{
|
||||
int x;
|
||||
|
||||
void F() {
|
||||
D d = new D(__Method1);
|
||||
}
|
||||
|
||||
void __Method1() {
|
||||
Console.WriteLine(x);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this example, the anonymous function captures a local variable:
|
||||
```csharp
|
||||
class Test
|
||||
{
|
||||
void F() {
|
||||
int y = 123;
|
||||
D d = () => { Console.WriteLine(y); };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The lifetime of the local variable must now be extended to at least the lifetime of the anonymous function delegate. This can be achieved by "hoisting" the local variable into a field of a compiler generated class. Instantiation of the local variable ([Instantiation of local variables](expressions.md#instantiation-of-local-variables)) then corresponds to creating an instance of the compiler generated class, and accessing the local variable corresponds to accessing a field in the instance of the compiler generated class. Furthermore, the anonymous function becomes an instance method of the compiler generated class:
|
||||
```csharp
|
||||
class Test
|
||||
{
|
||||
void F() {
|
||||
__Locals1 __locals1 = new __Locals1();
|
||||
__locals1.y = 123;
|
||||
D d = new D(__locals1.__Method1);
|
||||
}
|
||||
|
||||
class __Locals1
|
||||
{
|
||||
public int y;
|
||||
|
||||
public void __Method1() {
|
||||
Console.WriteLine(y);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Finally, the following anonymous function captures `this` as well as two local variables with different lifetimes:
|
||||
```csharp
|
||||
class Test
|
||||
{
|
||||
int x;
|
||||
|
||||
void F() {
|
||||
int y = 123;
|
||||
for (int i = 0; i < 10; i++) {
|
||||
int z = i * 2;
|
||||
D d = () => { Console.WriteLine(x + y + z); };
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Here, a compiler generated class is created for each statement block in which locals are captured such that the locals in the different blocks can have independent lifetimes. An instance of `__Locals2`, the compiler generated class for the inner statement block, contains the local variable `z` and a field that references an instance of `__Locals1`. An instance of `__Locals1`, the compiler generated class for the outer statement block, contains the local variable `y` and a field that references `this` of the enclosing function member. With these data structures it is possible to reach all captured outer variables through an instance of `__Local2`, and the code of the anonymous function can thus be implemented as an instance method of that class.
|
||||
|
||||
```csharp
|
||||
class Test
|
||||
{
|
||||
void F() {
|
||||
__Locals1 __locals1 = new __Locals1();
|
||||
__locals1.__this = this;
|
||||
__locals1.y = 123;
|
||||
for (int i = 0; i < 10; i++) {
|
||||
__Locals2 __locals2 = new __Locals2();
|
||||
__locals2.__locals1 = __locals1;
|
||||
__locals2.z = i * 2;
|
||||
D d = new D(__locals2.__Method1);
|
||||
}
|
||||
}
|
||||
|
||||
class __Locals1
|
||||
{
|
||||
public Test __this;
|
||||
public int y;
|
||||
}
|
||||
|
||||
class __Locals2
|
||||
{
|
||||
public __Locals1 __locals1;
|
||||
public int z;
|
||||
|
||||
public void __Method1() {
|
||||
Console.WriteLine(__locals1.__this.x + __locals1.y + z);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The same technique applied here to capture local variables can also be used when converting anonymous functions to expression trees: References to the compiler generated objects can be stored in the expression tree, and access to the local variables can be represented as field accesses on these objects. The advantage of this approach is that it allows the "lifted" local variables to be shared between delegates and expression trees.
|
||||
|
||||
## Method group conversions
|
||||
|
||||
An implicit conversion ([Implicit conversions](conversions.md#implicit-conversions)) exists from a method group ([Expression classifications](expressions.md#expression-classifications)) to a compatible delegate type. Given a delegate type `D` and an expression `E` that is classified as a method group, an implicit conversion exists from `E` to `D` if `E` contains at least one method that is applicable in its normal form ([Applicable function member](expressions.md#applicable-function-member)) to an argument list constructed by use of the parameter types and modifiers of `D`, as described in the following.
|
||||
|
||||
The compile-time application of a conversion from a method group `E` to a delegate type `D` is described in the following. Note that the existence of an implicit conversion from `E` to `D` does not guarantee that the compile-time application of the conversion will succeed without error.
|
||||
|
||||
* A single method `M` is selected corresponding to a method invocation ([Method invocations](expressions.md#method-invocations)) of the form `E(A)`, with the following modifications:
|
||||
* The argument list `A` is a list of expressions, each classified as a variable and with the type and modifier (`ref` or `out`) of the corresponding parameter in the *formal_parameter_list* of `D`.
|
||||
* The candidate methods considered are only those methods that are applicable in their normal form ([Applicable function member](expressions.md#applicable-function-member)), not those applicable only in their expanded form.
|
||||
* If the algorithm of [Method invocations](expressions.md#method-invocations) produces an error, then a compile-time error occurs. Otherwise the algorithm produces a single best method `M` having the same number of parameters as `D` and the conversion is considered to exist.
|
||||
* The selected method `M` must be compatible ([Delegate compatibility](delegates.md#delegate-compatibility)) with the delegate type `D`, or otherwise, a compile-time error occurs.
|
||||
* If the selected method `M` is an instance method, the instance expression associated with `E` determines the target object of the delegate.
|
||||
* If the selected method M is an extension method which is denoted by means of a member access on an instance expression, that instance expression determines the target object of the delegate.
|
||||
* The result of the conversion is a value of type `D`, namely a newly created delegate that refers to the selected method and target object.
|
||||
* Note that this process can lead to the creation of a delegate to an extension method, if the algorithm of [Method invocations](expressions.md#method-invocations) fails to find an instance method but succeeds in processing the invocation of `E(A)` as an extension method invocation ([Extension method invocations](expressions.md#extension-method-invocations)). A delegate thus created captures the extension method as well as its first argument.
|
||||
|
||||
The following example demonstrates method group conversions:
|
||||
```csharp
|
||||
delegate string D1(object o);
|
||||
|
||||
delegate object D2(string s);
|
||||
|
||||
delegate object D3();
|
||||
|
||||
delegate string D4(object o, params object[] a);
|
||||
|
||||
delegate string D5(int i);
|
||||
|
||||
class Test
|
||||
{
|
||||
static string F(object o) {...}
|
||||
|
||||
static void G() {
|
||||
D1 d1 = F; // Ok
|
||||
D2 d2 = F; // Ok
|
||||
D3 d3 = F; // Error -- not applicable
|
||||
D4 d4 = F; // Error -- not applicable in normal form
|
||||
D5 d5 = F; // Error -- applicable but not compatible
|
||||
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The assignment to `d1` implicitly converts the method group `F` to a value of type `D1`.
|
||||
|
||||
The assignment to `d2` shows how it is possible to create a delegate to a method that has less derived (contra-variant) parameter types and a more derived (covariant) return type.
|
||||
|
||||
The assignment to `d3` shows how no conversion exists if the method is not applicable.
|
||||
|
||||
The assignment to `d4` shows how the method must be applicable in its normal form.
|
||||
|
||||
The assignment to `d5` shows how parameter and return types of the delegate and method are allowed to differ only for reference types.
|
||||
|
||||
As with all other implicit and explicit conversions, the cast operator can be used to explicitly perform a method group conversion. Thus, the example
|
||||
```csharp
|
||||
object obj = new EventHandler(myDialog.OkClick);
|
||||
```
|
||||
could instead be written
|
||||
```csharp
|
||||
object obj = (EventHandler)myDialog.OkClick;
|
||||
```
|
||||
|
||||
Method groups may influence overload resolution, and participate in type inference. See [Function members](expressions.md#function-members) for further details.
|
||||
|
||||
The run-time evaluation of a method group conversion proceeds as follows:
|
||||
|
||||
* If the method selected at compile-time is an instance method, or it is an extension method which is accessed as an instance method, the target object of the delegate is determined from the instance expression associated with `E`:
|
||||
* The instance expression is evaluated. If this evaluation causes an exception, no further steps are executed.
|
||||
* If the instance expression is of a *reference_type*, the value computed by the instance expression becomes the target object. If the selected method is an instance method and the target object is `null`, a `System.NullReferenceException` is thrown and no further steps are executed.
|
||||
* If the instance expression is of a *value_type*, a boxing operation ([Boxing conversions](types.md#boxing-conversions)) is performed to convert the value to an object, and this object becomes the target object.
|
||||
* Otherwise the selected method is part of a static method call, and the target object of the delegate is `null`.
|
||||
* A new instance of the delegate type `D` is allocated. If there is not enough memory available to allocate the new instance, a `System.OutOfMemoryException` is thrown and no further steps are executed.
|
||||
* The new delegate instance is initialized with a reference to the method that was determined at compile-time and a reference to the target object computed above.
|
||||
258
spec/delegates.md
Normal file
258
spec/delegates.md
Normal file
|
|
@ -0,0 +1,258 @@
|
|||
# Delegates
|
||||
|
||||
Delegates enable scenarios that other languages—such as C++, Pascal, and Modula -- have addressed with function pointers. Unlike C++ function pointers, however, delegates are fully object oriented, and unlike C++ pointers to member functions, delegates encapsulate both an object instance and a method.
|
||||
|
||||
A delegate declaration defines a class that is derived from the class `System.Delegate`. A delegate instance encapsulates an invocation list, which is a list of one or more methods, each of which is referred to as a callable entity. For instance methods, a callable entity consists of an instance and a method on that instance. For static methods, a callable entity consists of just a method. Invoking a delegate instance with an appropriate set of arguments causes each of the delegate's callable entities to be invoked with the given set of arguments.
|
||||
|
||||
An interesting and useful property of a delegate instance is that it does not know or care about the classes of the methods it encapsulates; all that matters is that those methods be compatible ([Delegate declarations](delegates.md#delegate-declarations)) with the delegate's type. This makes delegates perfectly suited for "anonymous" invocation.
|
||||
|
||||
## Delegate declarations
|
||||
|
||||
A *delegate_declaration* is a *type_declaration* ([Type declarations](namespaces.md#type-declarations)) that declares a new delegate type.
|
||||
|
||||
```antlr
|
||||
delegate_declaration
|
||||
: attributes? delegate_modifier* 'delegate' return_type
|
||||
identifier variant_type_parameter_list?
|
||||
'(' formal_parameter_list? ')' type_parameter_constraints_clause* ';'
|
||||
;
|
||||
|
||||
delegate_modifier
|
||||
: 'new'
|
||||
| 'public'
|
||||
| 'protected'
|
||||
| 'internal'
|
||||
| 'private'
|
||||
| delegate_modifier_unsafe
|
||||
;
|
||||
```
|
||||
|
||||
It is a compile-time error for the same modifier to appear multiple times in a delegate declaration.
|
||||
|
||||
The `new` modifier is only permitted on delegates declared within another type, in which case it specifies that such a delegate hides an inherited member by the same name, as described in [The new modifier](classes.md#the-new-modifier).
|
||||
|
||||
The `public`, `protected`, `internal`, and `private` modifiers control the accessibility of the delegate type. Depending on the context in which the delegate declaration occurs, some of these modifiers may not be permitted ([Declared accessibility](basic-concepts.md#declared-accessibility)).
|
||||
|
||||
The delegate's type name is *identifier*.
|
||||
|
||||
The optional *formal_parameter_list* specifies the parameters of the delegate, and *return_type* indicates the return type of the delegate.
|
||||
|
||||
The optional *variant_type_parameter_list* ([Variant type parameter lists](interfaces.md#variant-type-parameter-lists)) specifies the type parameters to the delegate itself.
|
||||
|
||||
The return type of a delegate type must be either `void`, or output-safe ([Variance safety](interfaces.md#variance-safety)).
|
||||
|
||||
All the formal parameter types of a delegate type must be input-safe. Additionally, any `out` or `ref` parameter types must also be output-safe. Note that even `out` parameters are required to be input-safe, due to a limitiation of the underlying execution platform.
|
||||
|
||||
Delegate types in C# are name equivalent, not structurally equivalent. Specifically, two different delegate types that have the same parameter lists and return type are considered different delegate types. However, instances of two distinct but structurally equivalent delegate types may compare as equal ([Delegate equality operators](expressions.md#delegate-equality-operators)).
|
||||
|
||||
For example:
|
||||
|
||||
```csharp
|
||||
delegate int D1(int i, double d);
|
||||
|
||||
class A
|
||||
{
|
||||
public static int M1(int a, double b) {...}
|
||||
}
|
||||
|
||||
class B
|
||||
{
|
||||
delegate int D2(int c, double d);
|
||||
public static int M1(int f, double g) {...}
|
||||
public static void M2(int k, double l) {...}
|
||||
public static int M3(int g) {...}
|
||||
public static void M4(int g) {...}
|
||||
}
|
||||
```
|
||||
|
||||
The methods `A.M1` and `B.M1 `are compatible with both the delegate types `D1` and `D2` , since they have the same return type and parameter list; however, these delegate types are two different types, so they are not interchangeable. The methods `B.M2`, `B.M3`, and `B.M4` are incompatible with the delegate types `D1` and `D2`, since they have different return types or parameter lists.
|
||||
|
||||
Like other generic type declarations, type arguments must be given to create a constructed delegate type. The parameter types and return type of a constructed delegate type are created by substituting, for each type parameter in the delegate declaration, the corresponding type argument of the constructed delegate type. The resulting return type and parameter types are used in determining what methods are compatible with a constructed delegate type. For example:
|
||||
|
||||
```csharp
|
||||
delegate bool Predicate<T>(T value);
|
||||
|
||||
class X
|
||||
{
|
||||
static bool F(int i) {...}
|
||||
static bool G(string s) {...}
|
||||
}
|
||||
```
|
||||
|
||||
The method `X.F` is compatible with the delegate type `Predicate<int>` and the method `X.G` is compatible with the delegate type `Predicate<string>` .
|
||||
|
||||
The only way to declare a delegate type is via a *delegate_declaration*. A delegate type is a class type that is derived from `System.Delegate`. Delegate types are implicitly `sealed`, so it is not permissible to derive any type from a delegate type. It is also not permissible to derive a non-delegate class type from `System.Delegate`. Note that `System.Delegate` is not itself a delegate type; it is a class type from which all delegate types are derived.
|
||||
|
||||
C# provides special syntax for delegate instantiation and invocation. Except for instantiation, any operation that can be applied to a class or class instance can also be applied to a delegate class or instance, respectively. In particular, it is possible to access members of the `System.Delegate` type via the usual member access syntax.
|
||||
|
||||
The set of methods encapsulated by a delegate instance is called an invocation list. When a delegate instance is created ([Delegate compatibility](delegates.md#delegate-compatibility)) from a single method, it encapsulates that method, and its invocation list contains only one entry. However, when two non-null delegate instances are combined, their invocation lists are concatenated -- in the order left operand then right operand -- to form a new invocation list, which contains two or more entries.
|
||||
|
||||
Delegates are combined using the binary `+` ([Addition operator](expressions.md#addition-operator)) and `+=` operators ([Compound assignment](expressions.md#compound-assignment)). A delegate can be removed from a combination of delegates, using the binary `-` ([Subtraction operator](expressions.md#subtraction-operator)) and `-=` operators ([Compound assignment](expressions.md#compound-assignment)). Delegates can be compared for equality ([Delegate equality operators](expressions.md#delegate-equality-operators)).
|
||||
|
||||
The following example shows the instantiation of a number of delegates, and their corresponding invocation lists:
|
||||
|
||||
```csharp
|
||||
delegate void D(int x);
|
||||
|
||||
class C
|
||||
{
|
||||
public static void M1(int i) {...}
|
||||
public static void M2(int i) {...}
|
||||
|
||||
}
|
||||
|
||||
class Test
|
||||
{
|
||||
static void Main() {
|
||||
D cd1 = new D(C.M1); // M1
|
||||
D cd2 = new D(C.M2); // M2
|
||||
D cd3 = cd1 + cd2; // M1 + M2
|
||||
D cd4 = cd3 + cd1; // M1 + M2 + M1
|
||||
D cd5 = cd4 + cd3; // M1 + M2 + M1 + M1 + M2
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
When `cd1` and `cd2` are instantiated, they each encapsulate one method. When `cd3` is instantiated, it has an invocation list of two methods, `M1` and `M2`, in that order. `cd4`'s invocation list contains `M1`, `M2`, and `M1`, in that order. Finally, `cd5`'s invocation list contains `M1`, `M2`, `M1`, `M1`, and `M2`, in that order. For more examples of combining (as well as removing) delegates, see [Delegate invocation](delegates.md#delegate-invocation).
|
||||
|
||||
## Delegate compatibility
|
||||
|
||||
A method or delegate `M` is ***compatible*** with a delegate type `D` if all of the following are true:
|
||||
|
||||
* `D` and `M` have the same number of parameters, and each parameter in `D` has the same `ref` or `out` modifiers as the corresponding parameter in `M`.
|
||||
* For each value parameter (a parameter with no `ref` or `out` modifier), an identity conversion ([Identity conversion](conversions.md#identity-conversion)) or implicit reference conversion ([Implicit reference conversions](conversions.md#implicit-reference-conversions)) exists from the parameter type in `D` to the corresponding parameter type in `M`.
|
||||
* For each `ref` or `out` parameter, the parameter type in `D` is the same as the parameter type in `M`.
|
||||
* An identity or implicit reference conversion exists from the return type of `M` to the return type of `D`.
|
||||
|
||||
## Delegate instantiation
|
||||
|
||||
An instance of a delegate is created by a *delegate_creation_expression* ([Delegate creation expressions](expressions.md#delegate-creation-expressions)) or a conversion to a delegate type. The newly created delegate instance then refers to either:
|
||||
|
||||
* The static method referenced in the *delegate_creation_expression*, or
|
||||
* The target object (which cannot be `null`) and instance method referenced in the *delegate_creation_expression*, or
|
||||
* Another delegate.
|
||||
|
||||
For example:
|
||||
|
||||
```csharp
|
||||
delegate void D(int x);
|
||||
|
||||
class C
|
||||
{
|
||||
public static void M1(int i) {...}
|
||||
public void M2(int i) {...}
|
||||
}
|
||||
|
||||
class Test
|
||||
{
|
||||
static void Main() {
|
||||
D cd1 = new D(C.M1); // static method
|
||||
C t = new C();
|
||||
D cd2 = new D(t.M2); // instance method
|
||||
D cd3 = new D(cd2); // another delegate
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Once instantiated, delegate instances always refer to the same target object and method. Remember, when two delegates are combined, or one is removed from another, a new delegate results with its own invocation list; the invocation lists of the delegates combined or removed remain unchanged.
|
||||
|
||||
## Delegate invocation
|
||||
|
||||
C# provides special syntax for invoking a delegate. When a non-null delegate instance whose invocation list contains one entry is invoked, it invokes the one method with the same arguments it was given, and returns the same value as the referred to method. (See [Delegate invocations](expressions.md#delegate-invocations) for detailed information on delegate invocation.) If an exception occurs during the invocation of such a delegate, and that exception is not caught within the method that was invoked, the search for an exception catch clause continues in the method that called the delegate, as if that method had directly called the method to which that delegate referred.
|
||||
|
||||
Invocation of a delegate instance whose invocation list contains multiple entries proceeds by invoking each of the methods in the invocation list, synchronously, in order. Each method so called is passed the same set of arguments as was given to the delegate instance. If such a delegate invocation includes reference parameters ([Reference parameters](classes.md#reference-parameters)), each method invocation will occur with a reference to the same variable; changes to that variable by one method in the invocation list will be visible to methods further down the invocation list. If the delegate invocation includes output parameters or a return value, their final value will come from the invocation of the last delegate in the list.
|
||||
|
||||
If an exception occurs during processing of the invocation of such a delegate, and that exception is not caught within the method that was invoked, the search for an exception catch clause continues in the method that called the delegate, and any methods further down the invocation list are not invoked.
|
||||
|
||||
Attempting to invoke a delegate instance whose value is null results in an exception of type `System.NullReferenceException`.
|
||||
|
||||
The following example shows how to instantiate, combine, remove, and invoke delegates:
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
delegate void D(int x);
|
||||
|
||||
class C
|
||||
{
|
||||
public static void M1(int i) {
|
||||
Console.WriteLine("C.M1: " + i);
|
||||
}
|
||||
|
||||
public static void M2(int i) {
|
||||
Console.WriteLine("C.M2: " + i);
|
||||
}
|
||||
|
||||
public void M3(int i) {
|
||||
Console.WriteLine("C.M3: " + i);
|
||||
}
|
||||
}
|
||||
|
||||
class Test
|
||||
{
|
||||
static void Main() {
|
||||
D cd1 = new D(C.M1);
|
||||
cd1(-1); // call M1
|
||||
|
||||
D cd2 = new D(C.M2);
|
||||
cd2(-2); // call M2
|
||||
|
||||
D cd3 = cd1 + cd2;
|
||||
cd3(10); // call M1 then M2
|
||||
|
||||
cd3 += cd1;
|
||||
cd3(20); // call M1, M2, then M1
|
||||
|
||||
C c = new C();
|
||||
D cd4 = new D(c.M3);
|
||||
cd3 += cd4;
|
||||
cd3(30); // call M1, M2, M1, then M3
|
||||
|
||||
cd3 -= cd1; // remove last M1
|
||||
cd3(40); // call M1, M2, then M3
|
||||
|
||||
cd3 -= cd4;
|
||||
cd3(50); // call M1 then M2
|
||||
|
||||
cd3 -= cd2;
|
||||
cd3(60); // call M1
|
||||
|
||||
cd3 -= cd2; // impossible removal is benign
|
||||
cd3(60); // call M1
|
||||
|
||||
cd3 -= cd1; // invocation list is empty so cd3 is null
|
||||
|
||||
cd3(70); // System.NullReferenceException thrown
|
||||
|
||||
cd3 -= cd1; // impossible removal is benign
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
As shown in the statement `cd3 += cd1;`, a delegate can be present in an invocation list multiple times. In this case, it is simply invoked once per occurrence. In an invocation list such as this, when that delegate is removed, the last occurrence in the invocation list is the one actually removed.
|
||||
|
||||
Immediately prior to the execution of the final statement, `cd3 -= cd1;`, the delegate `cd3` refers to an empty invocation list. Attempting to remove a delegate from an empty list (or to remove a non-existent delegate from a non-empty list) is not an error.
|
||||
|
||||
The output produced is:
|
||||
|
||||
```
|
||||
C.M1: -1
|
||||
C.M2: -2
|
||||
C.M1: 10
|
||||
C.M2: 10
|
||||
C.M1: 20
|
||||
C.M2: 20
|
||||
C.M1: 20
|
||||
C.M1: 30
|
||||
C.M2: 30
|
||||
C.M1: 30
|
||||
C.M3: 30
|
||||
C.M1: 40
|
||||
C.M2: 40
|
||||
C.M3: 40
|
||||
C.M1: 50
|
||||
C.M2: 50
|
||||
C.M1: 60
|
||||
C.M1: 60
|
||||
```
|
||||
1139
spec/documentation-comments.md
Normal file
1139
spec/documentation-comments.md
Normal file
File diff suppressed because it is too large
Load diff
199
spec/enums.md
Normal file
199
spec/enums.md
Normal file
|
|
@ -0,0 +1,199 @@
|
|||
# Enums
|
||||
|
||||
An ***enum type*** is a distinct value type ([Value types](types.md#value-types)) that declares a set of named constants.
|
||||
|
||||
The example
|
||||
|
||||
```csharp
|
||||
enum Color
|
||||
{
|
||||
Red,
|
||||
Green,
|
||||
Blue
|
||||
}
|
||||
```
|
||||
|
||||
declares an enum type named `Color` with members `Red`, `Green`, and `Blue`.
|
||||
|
||||
## Enum declarations
|
||||
|
||||
An enum declaration declares a new enum type. An enum declaration begins with the keyword `enum`, and defines the name, accessibility, underlying type, and members of the enum.
|
||||
|
||||
```antlr
|
||||
enum_declaration
|
||||
: attributes? enum_modifier* 'enum' identifier enum_base? enum_body ';'?
|
||||
;
|
||||
|
||||
enum_base
|
||||
: ':' integral_type
|
||||
;
|
||||
|
||||
enum_body
|
||||
: '{' enum_member_declarations? '}'
|
||||
| '{' enum_member_declarations ',' '}'
|
||||
;
|
||||
```
|
||||
|
||||
Each enum type has a corresponding integral type called the ***underlying type*** of the enum type. This underlying type must be able to represent all the enumerator values defined in the enumeration. An enum declaration may explicitly declare an underlying type of `byte`, `sbyte`, `short`, `ushort`, `int`, `uint`, `long` or `ulong`. Note that `char` cannot be used as an underlying type. An enum declaration that does not explicitly declare an underlying type has an underlying type of `int`.
|
||||
|
||||
The example
|
||||
|
||||
```csharp
|
||||
enum Color: long
|
||||
{
|
||||
Red,
|
||||
Green,
|
||||
Blue
|
||||
}
|
||||
```
|
||||
|
||||
declares an enum with an underlying type of `long`. A developer might choose to use an underlying type of `long`, as in the example, to enable the use of values that are in the range of `long` but not in the range of `int`, or to preserve this option for the future.
|
||||
|
||||
## Enum modifiers
|
||||
|
||||
An *enum_declaration* may optionally include a sequence of enum modifiers:
|
||||
|
||||
```antlr
|
||||
enum_modifier
|
||||
: 'new'
|
||||
| 'public'
|
||||
| 'protected'
|
||||
| 'internal'
|
||||
| 'private'
|
||||
;
|
||||
```
|
||||
|
||||
It is a compile-time error for the same modifier to appear multiple times in an enum declaration.
|
||||
|
||||
The modifiers of an enum declaration have the same meaning as those of a class declaration ([Class modifiers](classes.md#class-modifiers)). Note, however, that the `abstract` and `sealed` modifiers are not permitted in an enum declaration. Enums cannot be abstract and do not permit derivation.
|
||||
|
||||
## Enum members
|
||||
|
||||
The body of an enum type declaration defines zero or more enum members, which are the named constants of the enum type. No two enum members can have the same name.
|
||||
|
||||
```antlr
|
||||
enum_member_declarations
|
||||
: enum_member_declaration (',' enum_member_declaration)*
|
||||
;
|
||||
|
||||
enum_member_declaration
|
||||
: attributes? identifier ('=' constant_expression)?
|
||||
;
|
||||
```
|
||||
|
||||
Each enum member has an associated constant value. The type of this value is the underlying type for the containing enum. The constant value for each enum member must be in the range of the underlying type for the enum. The example
|
||||
|
||||
```csharp
|
||||
enum Color: uint
|
||||
{
|
||||
Red = -1,
|
||||
Green = -2,
|
||||
Blue = -3
|
||||
}
|
||||
```
|
||||
|
||||
results in a compile-time error because the constant values `-1`, `-2`, and `-3` are not in the range of the underlying integral type `uint`.
|
||||
|
||||
Multiple enum members may share the same associated value. The example
|
||||
|
||||
```csharp
|
||||
enum Color
|
||||
{
|
||||
Red,
|
||||
Green,
|
||||
Blue,
|
||||
|
||||
Max = Blue
|
||||
}
|
||||
```
|
||||
|
||||
shows an enum in which two enum members -- `Blue` and `Max` -- have the same associated value.
|
||||
|
||||
The associated value of an enum member is assigned either implicitly or explicitly. If the declaration of the enum member has a *constant_expression* initializer, the value of that constant expression, implicitly converted to the underlying type of the enum, is the associated value of the enum member. If the declaration of the enum member has no initializer, its associated value is set implicitly, as follows:
|
||||
|
||||
* If the enum member is the first enum member declared in the enum type, its associated value is zero.
|
||||
* Otherwise, the associated value of the enum member is obtained by increasing the associated value of the textually preceding enum member by one. This increased value must be within the range of values that can be represented by the underlying type, otherwise a compile-time error occurs.
|
||||
|
||||
The example
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
enum Color
|
||||
{
|
||||
Red,
|
||||
Green = 10,
|
||||
Blue
|
||||
}
|
||||
|
||||
class Test
|
||||
{
|
||||
static void Main() {
|
||||
Console.WriteLine(StringFromColor(Color.Red));
|
||||
Console.WriteLine(StringFromColor(Color.Green));
|
||||
Console.WriteLine(StringFromColor(Color.Blue));
|
||||
}
|
||||
|
||||
static string StringFromColor(Color c) {
|
||||
switch (c) {
|
||||
case Color.Red:
|
||||
return String.Format("Red = {0}", (int) c);
|
||||
|
||||
case Color.Green:
|
||||
return String.Format("Green = {0}", (int) c);
|
||||
|
||||
case Color.Blue:
|
||||
return String.Format("Blue = {0}", (int) c);
|
||||
|
||||
default:
|
||||
return "Invalid color";
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
prints out the enum member names and their associated values. The output is:
|
||||
|
||||
```
|
||||
Red = 0
|
||||
Green = 10
|
||||
Blue = 11
|
||||
```
|
||||
|
||||
for the following reasons:
|
||||
|
||||
* the enum member `Red` is automatically assigned the value zero (since it has no initializer and is the first enum member);
|
||||
* the enum member `Green` is explicitly given the value `10`;
|
||||
* and the enum member `Blue` is automatically assigned the value one greater than the member that textually precedes it.
|
||||
|
||||
The associated value of an enum member may not, directly or indirectly, use the value of its own associated enum member. Other than this circularity restriction, enum member initializers may freely refer to other enum member initializers, regardless of their textual position. Within an enum member initializer, values of other enum members are always treated as having the type of their underlying type, so that casts are not necessary when referring to other enum members.
|
||||
|
||||
The example
|
||||
|
||||
```csharp
|
||||
enum Circular
|
||||
{
|
||||
A = B,
|
||||
B
|
||||
}
|
||||
```
|
||||
|
||||
results in a compile-time error because the declarations of `A` and `B` are circular. `A` depends on `B` explicitly, and `B` depends on `A` implicitly.
|
||||
|
||||
Enum members are named and scoped in a manner exactly analogous to fields within classes. The scope of an enum member is the body of its containing enum type. Within that scope, enum members can be referred to by their simple name. From all other code, the name of an enum member must be qualified with the name of its enum type. Enum members do not have any declared accessibility -- an enum member is accessible if its containing enum type is accessible.
|
||||
|
||||
## The System.Enum type
|
||||
|
||||
The type `System.Enum` is the abstract base class of all enum types (this is distinct and different from the underlying type of the enum type), and the members inherited from `System.Enum` are available in any enum type. A boxing conversion ([Boxing conversions](types.md#boxing-conversions)) exists from any enum type to `System.Enum`, and an unboxing conversion ([Unboxing conversions](types.md#unboxing-conversions)) exists from `System.Enum` to any enum type.
|
||||
|
||||
Note that `System.Enum` is not itself an *enum_type*. Rather, it is a *class_type* from which all *enum_type*s are derived. The type `System.Enum` inherits from the type `System.ValueType` ([The System.ValueType type](types.md#the-systemvaluetype-type)), which, in turn, inherits from type `object`. At run-time, a value of type `System.Enum` can be `null` or a reference to a boxed value of any enum type.
|
||||
|
||||
## Enum values and operations
|
||||
|
||||
Each enum type defines a distinct type; an explicit enumeration conversion ([Explicit enumeration conversions](conversions.md#explicit-enumeration-conversions)) is required to convert between an enum type and an integral type, or between two enum types. The set of values that an enum type can take on is not limited by its enum members. In particular, any value of the underlying type of an enum can be cast to the enum type, and is a distinct valid value of that enum type.
|
||||
|
||||
Enum members have the type of their containing enum type (except within other enum member initializers: see [Enum members](enums.md#enum-members)). The value of an enum member declared in enum type `E` with associated value `v` is `(E)v`.
|
||||
|
||||
The following operators can be used on values of enum types: `==`, `!=`, `<`, `>`, `<=`, `>=` ([Enumeration comparison operators](expressions.md#enumeration-comparison-operators)), binary `+` ([Addition operator](expressions.md#addition-operator)), binary `-` ([Subtraction operator](expressions.md#subtraction-operator)), `^`, `&`, `|` ([Enumeration logical operators](expressions.md#enumeration-logical-operators)), `~` ([Bitwise complement operator](expressions.md#bitwise-complement-operator)), `++` and `--` ([Postfix increment and decrement operators](expressions.md#postfix-increment-and-decrement-operators) and [Prefix increment and decrement operators](expressions.md#prefix-increment-and-decrement-operators)).
|
||||
|
||||
Every enum type automatically derives from the class `System.Enum` (which, in turn, derives from `System.ValueType` and `object`). Thus, inherited methods and properties of this class can be used on values of an enum type.
|
||||
55
spec/exceptions.md
Normal file
55
spec/exceptions.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
# Exceptions
|
||||
|
||||
Exceptions in C# provide a structured, uniform, and type-safe way of handling both system level and application level error conditions. The exception mechanism in C# is quite similar to that of C++, with a few important differences:
|
||||
|
||||
* In C#, all exceptions must be represented by an instance of a class type derived from `System.Exception`. In C++, any value of any type can be used to represent an exception.
|
||||
* In C#, a finally block ([The try statement](statements.md#the-try-statement)) can be used to write termination code that executes in both normal execution and exceptional conditions. Such code is difficult to write in C++ without duplicating code.
|
||||
* In C#, system-level exceptions such as overflow, divide-by-zero, and null dereferences have well defined exception classes and are on a par with application-level error conditions.
|
||||
|
||||
## Causes of exceptions
|
||||
|
||||
Exception can be thrown in two different ways.
|
||||
|
||||
* A `throw` statement ([The throw statement](statements.md#the-throw-statement)) throws an exception immediately and unconditionally. Control never reaches the statement immediately following the `throw`.
|
||||
* Certain exceptional conditions that arise during the processing of C# statements and expression cause an exception in certain circumstances when the operation cannot be completed normally. For example, an integer division operation ([Division operator](expressions.md#division-operator)) throws a `System.DivideByZeroException` if the denominator is zero. See [Common Exception Classes](exceptions.md#common-exception-classes) for a list of the various exceptions that can occur in this way.
|
||||
|
||||
## The System.Exception class
|
||||
|
||||
The `System.Exception` class is the base type of all exceptions. This class has a few notable properties that all exceptions share:
|
||||
|
||||
* `Message` is a read-only property of type `string` that contains a human-readable description of the reason for the exception.
|
||||
* `InnerException` is a read-only property of type `Exception`. If its value is non-null, it refers to the exception that caused the current exception—that is, the current exception was raised in a catch block handling the `InnerException`. Otherwise, its value is null, indicating that this exception was not caused by another exception. The number of exception objects chained together in this manner can be arbitrary.
|
||||
|
||||
The value of these properties can be specified in calls to the instance constructor for `System.Exception`.
|
||||
|
||||
## How exceptions are handled
|
||||
|
||||
Exceptions are handled by a `try` statement ([The try statement](statements.md#the-try-statement)).
|
||||
|
||||
When an exception occurs, the system searches for the nearest `catch` clause that can handle the exception, as determined by the run-time type of the exception. First, the current method is searched for a lexically enclosing `try` statement, and the associated catch clauses of the try statement are considered in order. If that fails, the method that called the current method is searched for a lexically enclosing `try` statement that encloses the point of the call to the current method. This search continues until a `catch` clause is found that can handle the current exception, by naming an exception class that is of the same class, or a base class, of the run-time type of the exception being thrown. A `catch` clause that doesn't name an exception class can handle any exception.
|
||||
|
||||
Once a matching catch clause is found, the system prepares to transfer control to the first statement of the catch clause. Before execution of the catch clause begins, the system first executes, in order, any `finally` clauses that were associated with try statements more nested that than the one that caught the exception.
|
||||
|
||||
If no matching catch clause is found, one of two things occurs:
|
||||
|
||||
* If the search for a matching catch clause reaches a static constructor ([Static constructors](classes.md#static-constructors)) or static field initializer, then a `System.TypeInitializationException` is thrown at the point that triggered the invocation of the static constructor. The inner exception of the `System.TypeInitializationException` contains the exception that was originally thrown.
|
||||
* If the search for matching catch clauses reaches the code that initially started the thread, then execution of the thread is terminated. The impact of such termination is implementation-defined.
|
||||
|
||||
Exceptions that occur during destructor execution are worth special mention. If an exception occurs during destructor execution, and that exception is not caught, then the execution of that destructor is terminated and the destructor of the base class (if any) is called. If there is no base class (as in the case of the `object` type) or if there is no base class destructor, then the exception is discarded.
|
||||
|
||||
## Common Exception Classes
|
||||
|
||||
The following exceptions are thrown by certain C# operations.
|
||||
|
||||
| | |
|
||||
|--------------------------------------|----------------|
|
||||
| `System.ArithmeticException` | A base class for exceptions that occur during arithmetic operations, such as `System.DivideByZeroException` and `System.OverflowException`. |
|
||||
| `System.ArrayTypeMismatchException` | Thrown when a store into an array fails because the actual type of the stored element is incompatible with the actual type of the array. |
|
||||
| `System.DivideByZeroException` | Thrown when an attempt to divide an integral value by zero occurs. |
|
||||
| `System.IndexOutOfRangeException` | Thrown when an attempt to index an array via an index that is less than zero or outside the bounds of the array. |
|
||||
| `System.InvalidCastException` | Thrown when an explicit conversion from a base type or interface to a derived type fails at run time. |
|
||||
| `System.NullReferenceException` | Thrown when a `null` reference is used in a way that causes the referenced object to be required. |
|
||||
| `System.OutOfMemoryException` | Thrown when an attempt to allocate memory (via `new`) fails. |
|
||||
| `System.OverflowException` | Thrown when an arithmetic operation in a `checked` context overflows. |
|
||||
| `System.StackOverflowException` | Thrown when the execution stack is exhausted by having too many pending method calls; typically indicative of very deep or unbounded recursion. |
|
||||
| `System.TypeInitializationException` | Thrown when a static constructor throws an exception, and no `catch` clauses exists to catch it. |
|
||||
4885
spec/expressions.md
Normal file
4885
spec/expressions.md
Normal file
File diff suppressed because it is too large
Load diff
998
spec/interfaces.md
Normal file
998
spec/interfaces.md
Normal file
|
|
@ -0,0 +1,998 @@
|
|||
# Interfaces
|
||||
|
||||
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.
|
||||
|
||||
Interfaces can contain methods, properties, events, and indexers. The interface itself does not provide implementations for the members that it defines. The interface merely specifies the members that must be supplied by classes or structs that implement the interface.
|
||||
|
||||
## Interface declarations
|
||||
|
||||
An *interface_declaration* is a *type_declaration* ([Type declarations](namespaces.md#type-declarations)) that declares a new interface type.
|
||||
|
||||
```antlr
|
||||
interface_declaration
|
||||
: attributes? interface_modifier* 'partial'? 'interface'
|
||||
identifier variant_type_parameter_list? interface_base?
|
||||
type_parameter_constraints_clause* interface_body ';'?
|
||||
;
|
||||
```
|
||||
|
||||
An *interface_declaration* consists of an optional set of *attributes* ([Attributes](attributes.md#attributes)), followed by an optional set of *interface_modifier*s ([Interface modifiers](interfaces.md#interface-modifiers)), followed by an optional `partial` modifier, followed by the keyword `interface` and an *identifier* that names the interface, followed by an optional *variant_type_parameter_list* specification ([Variant type parameter lists](interfaces.md#variant-type-parameter-lists)), followed by an optional *interface_base* specification ([Base interfaces](interfaces.md#base-interfaces)), followed by an optional *type_parameter_constraints_clause*s specification ([Type parameter constraints](classes.md#type-parameter-constraints)), followed by an *interface_body* ([Interface body](interfaces.md#interface-body)), optionally followed by a semicolon.
|
||||
|
||||
### Interface modifiers
|
||||
|
||||
An *interface_declaration* may optionally include a sequence of interface modifiers:
|
||||
|
||||
```antlr
|
||||
interface_modifier
|
||||
: 'new'
|
||||
| 'public'
|
||||
| 'protected'
|
||||
| 'internal'
|
||||
| 'private'
|
||||
| interface_modifier_unsafe
|
||||
;
|
||||
```
|
||||
|
||||
It is a compile-time error for the same modifier to appear multiple times in an interface declaration.
|
||||
|
||||
The `new` modifier is only permitted on interfaces defined within a class. It specifies that the interface hides an inherited member by the same name, as described in [The new modifier](classes.md#the-new-modifier).
|
||||
|
||||
The `public`, `protected`, `internal`, and `private` modifiers control the accessibility of the interface. Depending on the context in which the interface declaration occurs, only some of these modifiers may be permitted ([Declared accessibility](basic-concepts.md#declared-accessibility)).
|
||||
|
||||
### Partial modifier
|
||||
|
||||
The `partial` modifier indicates that this *interface_declaration* is a partial type declaration. Multiple partial interface declarations with the same name within an enclosing namespace or type declaration combine to form one interface declaration, following the rules specified in [Partial types](classes.md#partial-types).
|
||||
|
||||
### Variant type parameter lists
|
||||
|
||||
Variant type parameter lists can only occur on interface and delegate types. The difference from ordinary *type_parameter_list*s is the optional *variance_annotation* on each type parameter.
|
||||
|
||||
```antlr
|
||||
variant_type_parameter_list
|
||||
: '<' variant_type_parameters '>'
|
||||
;
|
||||
|
||||
variant_type_parameters
|
||||
: attributes? variance_annotation? type_parameter
|
||||
| variant_type_parameters ',' attributes? variance_annotation? type_parameter
|
||||
;
|
||||
|
||||
variance_annotation
|
||||
: 'in'
|
||||
| 'out'
|
||||
;
|
||||
```
|
||||
|
||||
If the variance annotation is `out`, the type parameter is said to be ***covariant***. If the variance annotation is `in`, the type parameter is said to be ***contravariant***. If there is no variance annotation, the type parameter is said to be ***invariant***.
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
interface C<out X, in Y, Z>
|
||||
{
|
||||
X M(Y y);
|
||||
Z P { get; set; }
|
||||
}
|
||||
```
|
||||
`X` is covariant, `Y` is contravariant and `Z` is invariant.
|
||||
|
||||
#### Variance safety
|
||||
|
||||
The occurrence of variance annotations in the type parameter list of a type restricts the places where types can occur within the type declaration.
|
||||
|
||||
A type `T` is ***output-unsafe*** if one of the following holds:
|
||||
|
||||
* `T` is a contravariant type parameter
|
||||
* `T` is an array type with an output-unsafe element type
|
||||
* `T` is an interface or delegate type `S<A1,...,Ak>` constructed from a generic type `S<X1,...,Xk>` where for at least one `Ai` one of the following holds:
|
||||
* `Xi` is covariant or invariant and `Ai` is output-unsafe.
|
||||
* `Xi` is contravariant or invariant and `Ai` is input-safe.
|
||||
|
||||
A type `T` is ***input-unsafe*** if one of the following holds:
|
||||
|
||||
* `T` is a covariant type parameter
|
||||
* `T` is an array type with an input-unsafe element type
|
||||
* `T` is an interface or delegate type `S<A1,...,Ak>` constructed from a generic type `S<X1,...,Xk>` where for at least one `Ai` one of the following holds:
|
||||
* `Xi` is covariant or invariant and `Ai` is input-unsafe.
|
||||
* `Xi` is contravariant or invariant and `Ai` is output-unsafe.
|
||||
|
||||
Intuitively, an output-unsafe type is prohibited in an output position, and an input-unsafe type is prohibited in an input position.
|
||||
|
||||
A type is ***output-safe*** if it is not output-unsafe, and ***input-safe*** if it is not input-unsafe.
|
||||
|
||||
#### Variance conversion
|
||||
|
||||
The purpose of variance annotations is to provide for more lenient (but still type safe) conversions to interface and delegate types. To this end the definitions of implicit ([Implicit conversions](conversions.md#implicit-conversions)) and explicit conversions ([Explicit conversions](conversions.md#explicit-conversions)) make use of the notion of variance-convertibility, which is defined as follows:
|
||||
|
||||
A type `T<A1,...,An>` is variance-convertible to a type `T<B1,...,Bn>` if `T` is either an interface or a delegate type declared with the variant type parameters `T<X1,...,Xn>`, and for each variant type parameter `Xi` one of the following holds:
|
||||
|
||||
* `Xi` is covariant and an implicit reference or identity conversion exists from `Ai` to `Bi`
|
||||
* `Xi` is contravariant and an implicit reference or identity conversion exists from `Bi` to `Ai`
|
||||
* `Xi` is invariant and an identity conversion exists from `Ai` to `Bi`
|
||||
|
||||
### Base interfaces
|
||||
|
||||
An interface can inherit from zero or more interface types, which are called the ***explicit base interfaces*** of the interface. When an interface has one or more explicit base interfaces, then in the declaration of that interface, the interface identifier is followed by a colon and a comma separated list of base interface types.
|
||||
|
||||
```antlr
|
||||
interface_base
|
||||
: ':' interface_type_list
|
||||
;
|
||||
```
|
||||
|
||||
For a constructed interface type, the explicit base interfaces are formed by taking the explicit base interface declarations on the generic type declaration, and substituting, for each *type_parameter* in the base interface declaration, the corresponding *type_argument* of the constructed type.
|
||||
|
||||
The explicit base interfaces of an interface must be at least as accessible as the interface itself ([Accessibility constraints](basic-concepts.md#accessibility-constraints)). For example, it is a compile-time error to specify a `private` or `internal` interface in the *interface_base* of a `public` interface.
|
||||
|
||||
It is a compile-time error for an interface to directly or indirectly inherit from itself.
|
||||
|
||||
The ***base interfaces*** of an interface are the explicit base interfaces and their base interfaces. In other words, the set of base interfaces is the complete transitive closure of the explicit base interfaces, their explicit base interfaces, and so on. An interface inherits all members of its base interfaces. In the example
|
||||
```csharp
|
||||
interface IControl
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
interface ITextBox: IControl
|
||||
{
|
||||
void SetText(string text);
|
||||
}
|
||||
|
||||
interface IListBox: IControl
|
||||
{
|
||||
void SetItems(string[] items);
|
||||
}
|
||||
|
||||
interface IComboBox: ITextBox, IListBox {}
|
||||
```
|
||||
the base interfaces of `IComboBox` are `IControl`, `ITextBox`, and `IListBox`.
|
||||
|
||||
In other words, the `IComboBox` interface above inherits members `SetText` and `SetItems` as well as `Paint`.
|
||||
|
||||
Every base interface of an interface must be output-safe ([Variance safety](interfaces.md#variance-safety)). A class or struct that implements an interface also implicitly implements all of the interface's base interfaces.
|
||||
|
||||
### Interface body
|
||||
|
||||
The *interface_body* of an interface defines the members of the interface.
|
||||
|
||||
```antlr
|
||||
interface_body
|
||||
: '{' interface_member_declaration* '}'
|
||||
;
|
||||
```
|
||||
|
||||
## Interface members
|
||||
|
||||
The members of an interface are the members inherited from the base interfaces and the members declared by the interface itself.
|
||||
|
||||
```antlr
|
||||
interface_member_declaration
|
||||
: interface_method_declaration
|
||||
| interface_property_declaration
|
||||
| interface_event_declaration
|
||||
| interface_indexer_declaration
|
||||
;
|
||||
```
|
||||
|
||||
An interface declaration may declare zero or more members. The members of an interface must be methods, properties, events, or indexers. An interface cannot contain constants, fields, operators, instance constructors, destructors, or types, nor can an interface contain static members of any kind.
|
||||
|
||||
All interface members implicitly have public access. It is a compile-time error for interface member declarations to include any modifiers. In particular, interfaces members cannot be declared with the modifiers `abstract`, `public`, `protected`, `internal`, `private`, `virtual`, `override`, or `static`.
|
||||
|
||||
The example
|
||||
```csharp
|
||||
public delegate void StringListEvent(IStringList sender);
|
||||
|
||||
public interface IStringList
|
||||
{
|
||||
void Add(string s);
|
||||
int Count { get; }
|
||||
event StringListEvent Changed;
|
||||
string this[int index] { get; set; }
|
||||
}
|
||||
```
|
||||
declares an interface that contains one each of the possible kinds of members: A method, a property, an event, and an indexer.
|
||||
|
||||
An *interface_declaration* creates a new declaration space ([Declarations](basic-concepts.md#declarations)), and the *interface_member_declaration*s immediately contained by the *interface_declaration* introduce new members into this declaration space. The following rules apply to *interface_member_declaration*s:
|
||||
|
||||
* The name of a method must differ from the names of all properties and events declared in the same interface. In addition, the signature ([Signatures and overloading](basic-concepts.md#signatures-and-overloading)) of a method must differ from the signatures of all other methods declared in the same interface, and two methods declared in the same interface may not have signatures that differ solely by `ref` and `out`.
|
||||
* The name of a property or event must differ from the names of all other members declared in the same interface.
|
||||
* The signature of an indexer must differ from the signatures of all other indexers declared in the same interface.
|
||||
|
||||
The inherited members of an interface are specifically not part of the declaration space of the interface. Thus, an interface is allowed to declare a member with the same name or signature as an inherited member. When this occurs, the derived interface member is said to hide the base interface member. Hiding an inherited member is not considered an error, but it does cause the compiler to issue a warning. To suppress the warning, the declaration of the derived interface member must include a `new` modifier to indicate that the derived member is intended to hide the base member. This topic is discussed further in [Hiding through inheritance](basic-concepts.md#hiding-through-inheritance).
|
||||
|
||||
If a `new` modifier is included in a declaration that doesn't hide an inherited member, a warning is issued to that effect. This warning is suppressed by removing the `new` modifier.
|
||||
|
||||
Note that the members in class `object` are not, strictly speaking, members of any interface ([Interface members](interfaces.md#interface-members)). However, the members in class `object` are available via member lookup in any interface type ([Member lookup](expressions.md#member-lookup)).
|
||||
|
||||
### Interface methods
|
||||
|
||||
Interface methods are declared using *interface_method_declaration*s:
|
||||
|
||||
```antlr
|
||||
interface_method_declaration
|
||||
: attributes? 'new'? return_type identifier type_parameter_list
|
||||
'(' formal_parameter_list? ')' type_parameter_constraints_clause* ';'
|
||||
;
|
||||
```
|
||||
|
||||
The *attributes*, *return_type*, *identifier*, and *formal_parameter_list* of an interface method declaration have the same meaning as those of a method declaration in a class ([Methods](classes.md#methods)). An interface method declaration is not permitted to specify a method body, and the declaration therefore always ends with a semicolon.
|
||||
|
||||
Each formal parameter type of an interface method must be input-safe ([Variance safety](interfaces.md#variance-safety)), and the return type must be either `void` or output-safe. Furthermore, each class type constraint, interface type constraint and type parameter constraint on any type parameter of the method must be input-safe.
|
||||
|
||||
These rules ensure that any covariant or contravariant usage of the interface remains typesafe. For example,
|
||||
```csharp
|
||||
interface I<out T> { void M<U>() where U : T; }
|
||||
```
|
||||
is illegal because the usage of `T` as a type parameter constraint on `U` is not input-safe.
|
||||
|
||||
Were this restriction not in place it would be possible to violate type safety in the following manner:
|
||||
```csharp
|
||||
class B {}
|
||||
class D : B{}
|
||||
class E : B {}
|
||||
class C : I<D> { public void M<U>() {...} }
|
||||
...
|
||||
I<B> b = new C();
|
||||
b.M<E>();
|
||||
```
|
||||
This is actually a call to `C.M<E>`. But that call requires that `E` derive from `D`, so type safety would be violated here.
|
||||
|
||||
### Interface properties
|
||||
|
||||
Interface properties are declared using *interface_property_declaration*s:
|
||||
|
||||
```antlr
|
||||
interface_property_declaration
|
||||
: attributes? 'new'? type identifier '{' interface_accessors '}'
|
||||
;
|
||||
|
||||
interface_accessors
|
||||
: attributes? 'get' ';'
|
||||
| attributes? 'set' ';'
|
||||
| attributes? 'get' ';' attributes? 'set' ';'
|
||||
| attributes? 'set' ';' attributes? 'get' ';'
|
||||
;
|
||||
```
|
||||
|
||||
The *attributes*, *type*, and *identifier* of an interface property declaration have the same meaning as those of a property declaration in a class ([Properties](classes.md#properties)).
|
||||
|
||||
The accessors of an interface property declaration correspond to the accessors of a class property declaration ([Accessors](classes.md#accessors)), except that the accessor body must always be a semicolon. Thus, the accessors simply indicate whether the property is read-write, read-only, or write-only.
|
||||
|
||||
The type of an interface property must be output-safe if there is a get accessor, and must be input-safe if there is a set accessor.
|
||||
|
||||
### Interface events
|
||||
|
||||
Interface events are declared using *interface_event_declaration*s:
|
||||
|
||||
```antlr
|
||||
interface_event_declaration
|
||||
: attributes? 'new'? 'event' type identifier ';'
|
||||
;
|
||||
```
|
||||
|
||||
The *attributes*, *type*, and *identifier* of an interface event declaration have the same meaning as those of an event declaration in a class ([Events](classes.md#events)).
|
||||
|
||||
The type of an interface event must be input-safe.
|
||||
|
||||
### Interface indexers
|
||||
|
||||
Interface indexers are declared using *interface_indexer_declaration*s:
|
||||
|
||||
```antlr
|
||||
interface_indexer_declaration
|
||||
: attributes? 'new'? type 'this' '[' formal_parameter_list ']' '{' interface_accessors '}'
|
||||
;
|
||||
```
|
||||
|
||||
The *attributes*, *type*, and *formal_parameter_list* of an interface indexer declaration have the same meaning as those of an indexer declaration in a class ([Indexers](classes.md#indexers)).
|
||||
|
||||
The accessors of an interface indexer declaration correspond to the accessors of a class indexer declaration ([Indexers](classes.md#indexers)), except that the accessor body must always be a semicolon. Thus, the accessors simply indicate whether the indexer is read-write, read-only, or write-only.
|
||||
|
||||
All the formal parameter types of an interface indexer must be input-safe . In addition, any `out` or `ref` formal parameter types must also be output-safe. Note that even `out` parameters are required to be input-safe, due to a limitiation of the underlying execution platform.
|
||||
|
||||
The type of an interface indexer must be output-safe if there is a get accessor, and must be input-safe if there is a set accessor.
|
||||
|
||||
### Interface member access
|
||||
|
||||
Interface members are accessed through member access ([Member access](expressions.md#member-access)) and indexer access ([Indexer access](expressions.md#indexer-access)) expressions of the form `I.M` and `I[A]`, where `I` is an interface type, `M` is a method, property, or event of that interface type, and `A` is an indexer argument list.
|
||||
|
||||
For interfaces that are strictly single-inheritance (each interface in the inheritance chain has exactly zero or one direct base interface), the effects of the member lookup ([Member lookup](expressions.md#member-lookup)), method invocation ([Method invocations](expressions.md#method-invocations)), and indexer access ([Indexer access](expressions.md#indexer-access)) rules are exactly the same as for classes and structs: More derived members hide less derived members with the same name or signature. However, for multiple-inheritance interfaces, ambiguities can occur when two or more unrelated base interfaces declare members with the same name or signature. This section shows several examples of such situations. In all cases, explicit casts can be used to resolve the ambiguities.
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
interface IList
|
||||
{
|
||||
int Count { get; set; }
|
||||
}
|
||||
|
||||
interface ICounter
|
||||
{
|
||||
void Count(int i);
|
||||
}
|
||||
|
||||
interface IListCounter: IList, ICounter {}
|
||||
|
||||
class C
|
||||
{
|
||||
void Test(IListCounter x) {
|
||||
x.Count(1); // Error
|
||||
x.Count = 1; // Error
|
||||
((IList)x).Count = 1; // Ok, invokes IList.Count.set
|
||||
((ICounter)x).Count(1); // Ok, invokes ICounter.Count
|
||||
}
|
||||
}
|
||||
```
|
||||
the first two statements cause compile-time errors because the member lookup ([Member lookup](expressions.md#member-lookup)) of `Count` in `IListCounter` is ambiguous. As illustrated by the example, the ambiguity is resolved by casting `x` to the appropriate base interface type. Such casts have no run-time costs—they merely consist of viewing the instance as a less derived type at compile-time.
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
interface IInteger
|
||||
{
|
||||
void Add(int i);
|
||||
}
|
||||
|
||||
interface IDouble
|
||||
{
|
||||
void Add(double d);
|
||||
}
|
||||
|
||||
interface INumber: IInteger, IDouble {}
|
||||
|
||||
class C
|
||||
{
|
||||
void Test(INumber n) {
|
||||
n.Add(1); // Invokes IInteger.Add
|
||||
n.Add(1.0); // Only IDouble.Add is applicable
|
||||
((IInteger)n).Add(1); // Only IInteger.Add is a candidate
|
||||
((IDouble)n).Add(1); // Only IDouble.Add is a candidate
|
||||
}
|
||||
}
|
||||
```
|
||||
the invocation `n.Add(1)` selects `IInteger.Add` by applying the overload resolution rules of [Overload resolution](expressions.md#overload-resolution). Similarly the invocation `n.Add(1.0)` selects `IDouble.Add`. When explicit casts are inserted, there is only one candidate method, and thus no ambiguity.
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
interface IBase
|
||||
{
|
||||
void F(int i);
|
||||
}
|
||||
|
||||
interface ILeft: IBase
|
||||
{
|
||||
new void F(int i);
|
||||
}
|
||||
|
||||
interface IRight: IBase
|
||||
{
|
||||
void G();
|
||||
}
|
||||
|
||||
interface IDerived: ILeft, IRight {}
|
||||
|
||||
class A
|
||||
{
|
||||
void Test(IDerived d) {
|
||||
d.F(1); // Invokes ILeft.F
|
||||
((IBase)d).F(1); // Invokes IBase.F
|
||||
((ILeft)d).F(1); // Invokes ILeft.F
|
||||
((IRight)d).F(1); // Invokes IBase.F
|
||||
}
|
||||
}
|
||||
```
|
||||
the `IBase.F` member is hidden by the `ILeft.F` member. The invocation `d.F(1)` thus selects `ILeft.F`, even though `IBase.F` appears to not be hidden in the access path that leads through `IRight`.
|
||||
|
||||
The intuitive rule for hiding in multiple-inheritance interfaces is simply this: If a member is hidden in any access path, it is hidden in all access paths. Because the access path from `IDerived` to `ILeft` to `IBase` hides `IBase.F`, the member is also hidden in the access path from `IDerived` to `IRight` to `IBase`.
|
||||
|
||||
## Fully qualified interface member names
|
||||
|
||||
An interface member is sometimes referred to by its ***fully qualified name***. The fully qualified name of an interface member consists of the name of the interface in which the member is declared, followed by a dot, followed by the name of the member. The fully qualified name of a member references the interface in which the member is declared. For example, given the declarations
|
||||
```csharp
|
||||
interface IControl
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
interface ITextBox: IControl
|
||||
{
|
||||
void SetText(string text);
|
||||
}
|
||||
```
|
||||
the fully qualified name of `Paint` is `IControl.Paint` and the fully qualified name of `SetText` is `ITextBox.SetText`.
|
||||
|
||||
In the example above, it is not possible to refer to `Paint` as `ITextBox.Paint`.
|
||||
|
||||
When an interface is part of a namespace, the fully qualified name of an interface member includes the namespace name. For example
|
||||
```csharp
|
||||
namespace System
|
||||
{
|
||||
public interface ICloneable
|
||||
{
|
||||
object Clone();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Here, the fully qualified name of the `Clone` method is `System.ICloneable.Clone`.
|
||||
|
||||
## Interface implementations
|
||||
|
||||
Interfaces may be implemented by classes and structs. To indicate that a class or struct directly implements an interface, the interface identifier is included in the base class list of the class or struct. For example:
|
||||
```csharp
|
||||
interface ICloneable
|
||||
{
|
||||
object Clone();
|
||||
}
|
||||
|
||||
interface IComparable
|
||||
{
|
||||
int CompareTo(object other);
|
||||
}
|
||||
|
||||
class ListEntry: ICloneable, IComparable
|
||||
{
|
||||
public object Clone() {...}
|
||||
public int CompareTo(object other) {...}
|
||||
}
|
||||
```
|
||||
|
||||
A class or struct that directly implements an interface also directly implements all of the interface's base interfaces implicitly. This is true even if the class or struct doesn't explicitly list all base interfaces in the base class list. For example:
|
||||
```csharp
|
||||
interface IControl
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
interface ITextBox: IControl
|
||||
{
|
||||
void SetText(string text);
|
||||
}
|
||||
|
||||
class TextBox: ITextBox
|
||||
{
|
||||
public void Paint() {...}
|
||||
public void SetText(string text) {...}
|
||||
}
|
||||
```
|
||||
|
||||
Here, class `TextBox` implements both `IControl` and `ITextBox`.
|
||||
|
||||
When a class `C` directly implements an interface, all classes derived from C also implement the interface implicitly. The base interfaces specified in a class declaration can be constructed interface types ([Constructed types](types.md#constructed-types)). A base interface cannot be a type parameter on its own, though it can involve the type parameters that are in scope. The following code illustrates how a class can implement and extend constructed types:
|
||||
```csharp
|
||||
class C<U,V> {}
|
||||
|
||||
interface I1<V> {}
|
||||
|
||||
class D: C<string,int>, I1<string> {}
|
||||
|
||||
class E<T>: C<int,T>, I1<T> {}
|
||||
```
|
||||
|
||||
The base interfaces of a generic class declaration must satisfy the uniqueness rule described in [Uniqueness of implemented interfaces](interfaces.md#uniqueness-of-implemented-interfaces).
|
||||
|
||||
### Explicit interface member implementations
|
||||
|
||||
For purposes of implementing interfaces, a class or struct may declare ***explicit interface member implementations***. An explicit interface member implementation is a method, property, event, or indexer declaration that references a fully qualified interface member name. For example
|
||||
```csharp
|
||||
interface IList<T>
|
||||
{
|
||||
T[] GetElements();
|
||||
}
|
||||
|
||||
interface IDictionary<K,V>
|
||||
{
|
||||
V this[K key];
|
||||
void Add(K key, V value);
|
||||
}
|
||||
|
||||
class List<T>: IList<T>, IDictionary<int,T>
|
||||
{
|
||||
T[] IList<T>.GetElements() {...}
|
||||
T IDictionary<int,T>.this[int index] {...}
|
||||
void IDictionary<int,T>.Add(int index, T value) {...}
|
||||
}
|
||||
```
|
||||
|
||||
Here `IDictionary<int,T>.this` and `IDictionary<int,T>.Add` are explicit interface member implementations.
|
||||
|
||||
In some cases, the name of an interface member may not be appropriate for the implementing class, in which case the interface member may be implemented using explicit interface member implementation. A class implementing a file abstraction, for example, would likely implement a `Close` member function that has the effect of releasing the file resource, and implement the `Dispose` method of the `IDisposable` interface using explicit interface member implementation:
|
||||
```csharp
|
||||
interface IDisposable
|
||||
{
|
||||
void Dispose();
|
||||
}
|
||||
|
||||
class MyFile: IDisposable
|
||||
{
|
||||
void IDisposable.Dispose() {
|
||||
Close();
|
||||
}
|
||||
|
||||
public void Close() {
|
||||
// Do what's necessary to close the file
|
||||
System.GC.SuppressFinalize(this);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is not possible to access an explicit interface member implementation through its fully qualified name in a method invocation, property access, or indexer access. An explicit interface member implementation can only be accessed through an interface instance, and is in that case referenced simply by its member name.
|
||||
|
||||
It is a compile-time error for an explicit interface member implementation to include access modifiers, and it is a compile-time error to include the modifiers `abstract`, `virtual`, `override`, or `static`.
|
||||
|
||||
Explicit interface member implementations have different accessibility characteristics than other members. Because explicit interface member implementations are never accessible through their fully qualified name in a method invocation or a property access, they are in a sense private. However, since they can be accessed through an interface instance, they are in a sense also public.
|
||||
|
||||
Explicit interface member implementations serve two primary purposes:
|
||||
|
||||
* Because explicit interface member implementations are not accessible through class or struct instances, they allow interface implementations to be excluded from the public interface of a class or struct. This is particularly useful when a class or struct implements an internal interface that is of no interest to a consumer of that class or struct.
|
||||
* Explicit interface member implementations allow disambiguation of interface members with the same signature. Without explicit interface member implementations it would be impossible for a class or struct to have different implementations of interface members with the same signature and return type, as would it be impossible for a class or struct to have any implementation at all of interface members with the same signature but with different return types.
|
||||
|
||||
For an explicit interface member implementation to be valid, the class or struct must name an interface in its base class list that contains a member whose fully qualified name, type, and parameter types exactly match those of the explicit interface member implementation. Thus, in the following class
|
||||
```csharp
|
||||
class Shape: ICloneable
|
||||
{
|
||||
object ICloneable.Clone() {...}
|
||||
int IComparable.CompareTo(object other) {...} // invalid
|
||||
}
|
||||
```
|
||||
the declaration of `IComparable.CompareTo` results in a compile-time error because `IComparable` is not listed in the base class list of `Shape` and is not a base interface of `ICloneable`. Likewise, in the declarations
|
||||
```csharp
|
||||
class Shape: ICloneable
|
||||
{
|
||||
object ICloneable.Clone() {...}
|
||||
}
|
||||
|
||||
class Ellipse: Shape
|
||||
{
|
||||
object ICloneable.Clone() {...} // invalid
|
||||
}
|
||||
```
|
||||
the declaration of `ICloneable.Clone` in `Ellipse` results in a compile-time error because `ICloneable` is not explicitly listed in the base class list of `Ellipse`.
|
||||
|
||||
The fully qualified name of an interface member must reference the interface in which the member was declared. Thus, in the declarations
|
||||
```csharp
|
||||
interface IControl
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
interface ITextBox: IControl
|
||||
{
|
||||
void SetText(string text);
|
||||
}
|
||||
|
||||
class TextBox: ITextBox
|
||||
{
|
||||
void IControl.Paint() {...}
|
||||
void ITextBox.SetText(string text) {...}
|
||||
}
|
||||
```
|
||||
the explicit interface member implementation of `Paint` must be written as `IControl.Paint`.
|
||||
|
||||
### Uniqueness of implemented interfaces
|
||||
|
||||
The interfaces implemented by a generic type declaration must remain unique for all possible constructed types. Without this rule, it would be impossible to determine the correct method to call for certain constructed types. For example, suppose a generic class declaration were permitted to be written as follows:
|
||||
```csharp
|
||||
interface I<T>
|
||||
{
|
||||
void F();
|
||||
}
|
||||
|
||||
class X<U,V>: I<U>, I<V> // Error: I<U> and I<V> conflict
|
||||
{
|
||||
void I<U>.F() {...}
|
||||
void I<V>.F() {...}
|
||||
}
|
||||
```
|
||||
|
||||
Were this permitted, it would be impossible to determine which code to execute in the following case:
|
||||
```csharp
|
||||
I<int> x = new X<int,int>();
|
||||
x.F();
|
||||
```
|
||||
|
||||
To determine if the interface list of a generic type declaration is valid, the following steps are performed:
|
||||
|
||||
* Let `L` be the list of interfaces directly specified in a generic class, struct, or interface declaration `C`.
|
||||
* Add to `L` any base interfaces of the interfaces already in `L`.
|
||||
* Remove any duplicates from `L`.
|
||||
* If any possible constructed type created from `C` would, after type arguments are substituted into `L`, cause two interfaces in `L` to be identical, then the declaration of `C` is invalid. Constraint declarations are not considered when determining all possible constructed types.
|
||||
|
||||
In the class declaration `X` above, the interface list `L` consists of `I<U>` and `I<V>`. The declaration is invalid because any constructed type with `U` and `V` being the same type would cause these two interfaces to be identical types.
|
||||
|
||||
It is possible for interfaces specified at different inheritance levels to unify:
|
||||
```csharp
|
||||
interface I<T>
|
||||
{
|
||||
void F();
|
||||
}
|
||||
|
||||
class Base<U>: I<U>
|
||||
{
|
||||
void I<U>.F() {...}
|
||||
}
|
||||
|
||||
class Derived<U,V>: Base<U>, I<V> // Ok
|
||||
{
|
||||
void I<V>.F() {...}
|
||||
}
|
||||
```
|
||||
|
||||
This code is valid even though `Derived<U,V>` implements both `I<U>` and `I<V>`. The code
|
||||
```csharp
|
||||
I<int> x = new Derived<int,int>();
|
||||
x.F();
|
||||
```
|
||||
invokes the method in `Derived`, since `Derived<int,int>` effectively re-implements `I<int>` ([Interface re-implementation](interfaces.md#interface-re-implementation)).
|
||||
|
||||
### Implementation of generic methods
|
||||
|
||||
When a generic method implicitly implements an interface method, the constraints given for each method type parameter must be equivalent in both declarations (after any interface type parameters are replaced with the appropriate type arguments), where method type parameters are identified by ordinal positions, left to right.
|
||||
|
||||
When a generic method explicitly implements an interface method, however, no constraints are allowed on the implementing method. Instead, the constraints are inherited from the interface method
|
||||
|
||||
```csharp
|
||||
interface I<A,B,C>
|
||||
{
|
||||
void F<T>(T t) where T: A;
|
||||
void G<T>(T t) where T: B;
|
||||
void H<T>(T t) where T: C;
|
||||
}
|
||||
|
||||
class C: I<object,C,string>
|
||||
{
|
||||
public void F<T>(T t) {...} // Ok
|
||||
public void G<T>(T t) where T: C {...} // Ok
|
||||
public void H<T>(T t) where T: string {...} // Error
|
||||
}
|
||||
```
|
||||
|
||||
The method `C.F<T>` implicitly implements `I<object,C,string>.F<T>`. In this case, `C.F<T>` is not required (nor permitted) to specify the constraint `T:object` since `object` is an implicit constraint on all type parameters. The method `C.G<T>` implicitly implements `I<object,C,string>.G<T>` because the constraints match those in the interface, after the interface type parameters are replaced with the corresponding type arguments. The constraint for method `C.H<T>` is an error because sealed types (`string` in this case) cannot be used as constraints. Omitting the constraint would also be an error since constraints of implicit interface method implementations are required to match. Thus, it is impossible to implicitly implement `I<object,C,string>.H<T>`. This interface method can only be implemented using an explicit interface member implementation:
|
||||
```csharp
|
||||
class C: I<object,C,string>
|
||||
{
|
||||
...
|
||||
|
||||
public void H<U>(U u) where U: class {...}
|
||||
|
||||
void I<object,C,string>.H<T>(T t) {
|
||||
string s = t; // Ok
|
||||
H<T>(t);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this example, the explicit interface member implementation invokes a public method having strictly weaker constraints. Note that the assignment from `t` to `s` is valid since `T` inherits a constraint of `T:string`, even though this constraint is not expressible in source code.
|
||||
|
||||
### Interface mapping
|
||||
|
||||
A class or struct must provide implementations of all members of the interfaces that are listed in the base class list of the class or struct. The process of locating implementations of interface members in an implementing class or struct is known as ***interface mapping***.
|
||||
|
||||
Interface mapping for a class or struct `C` locates an implementation for each member of each interface specified in the base class list of `C`. The implementation of a particular interface member `I.M`, where `I` is the interface in which the member `M` is declared, is determined by examining each class or struct `S`, starting with `C` and repeating for each successive base class of `C`, until a match is located:
|
||||
|
||||
* If `S` contains a declaration of an explicit interface member implementation that matches `I` and `M`, then this member is the implementation of `I.M`.
|
||||
* Otherwise, if `S` contains a declaration of a non-static public member that matches `M`, then this member is the implementation of `I.M`. If more than one member matches, it is unspecified which member is the implementation of `I.M`. This situation can only occur if `S` is a constructed type where the two members as declared in the generic type have different signatures, but the type arguments make their signatures identical.
|
||||
|
||||
A compile-time error occurs if implementations cannot be located for all members of all interfaces specified in the base class list of `C`. Note that the members of an interface include those members that are inherited from base interfaces.
|
||||
|
||||
For purposes of interface mapping, a class member `A` matches an interface member `B` when:
|
||||
|
||||
* `A` and `B` are methods, and the name, type, and formal parameter lists of `A` and `B` are identical.
|
||||
* `A` and `B` are properties, the name and type of `A` and `B` are identical, and `A` has the same accessors as `B` (`A` is permitted to have additional accessors if it is not an explicit interface member implementation).
|
||||
* `A` and `B` are events, and the name and type of `A` and `B` are identical.
|
||||
* `A` and `B` are indexers, the type and formal parameter lists of `A` and `B` are identical, and `A` has the same accessors as `B` (`A` is permitted to have additional accessors if it is not an explicit interface member implementation).
|
||||
|
||||
Notable implications of the interface mapping algorithm are:
|
||||
|
||||
* Explicit interface member implementations take precedence over other members in the same class or struct when determining the class or struct member that implements an interface member.
|
||||
* Neither non-public nor static members participate in interface mapping.
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
interface ICloneable
|
||||
{
|
||||
object Clone();
|
||||
}
|
||||
|
||||
class C: ICloneable
|
||||
{
|
||||
object ICloneable.Clone() {...}
|
||||
public object Clone() {...}
|
||||
}
|
||||
```
|
||||
the `ICloneable.Clone` member of `C` becomes the implementation of `Clone` in `ICloneable` because explicit interface member implementations take precedence over other members.
|
||||
|
||||
If a class or struct implements two or more interfaces containing a member with the same name, type, and parameter types, it is possible to map each of those interface members onto a single class or struct member. For example
|
||||
```csharp
|
||||
interface IControl
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
interface IForm
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
class Page: IControl, IForm
|
||||
{
|
||||
public void Paint() {...}
|
||||
}
|
||||
```
|
||||
|
||||
Here, the `Paint` methods of both `IControl` and `IForm` are mapped onto the `Paint` method in `Page`. It is of course also possible to have separate explicit interface member implementations for the two methods.
|
||||
|
||||
If a class or struct implements an interface that contains hidden members, then some members must necessarily be implemented through explicit interface member implementations. For example
|
||||
```csharp
|
||||
interface IBase
|
||||
{
|
||||
int P { get; }
|
||||
}
|
||||
|
||||
interface IDerived: IBase
|
||||
{
|
||||
new int P();
|
||||
}
|
||||
```
|
||||
|
||||
An implementation of this interface would require at least one explicit interface member implementation, and would take one of the following forms
|
||||
```csharp
|
||||
class C: IDerived
|
||||
{
|
||||
int IBase.P { get {...} }
|
||||
int IDerived.P() {...}
|
||||
}
|
||||
|
||||
class C: IDerived
|
||||
{
|
||||
public int P { get {...} }
|
||||
int IDerived.P() {...}
|
||||
}
|
||||
|
||||
class C: IDerived
|
||||
{
|
||||
int IBase.P { get {...} }
|
||||
public int P() {...}
|
||||
}
|
||||
```
|
||||
|
||||
When a class implements multiple interfaces that have the same base interface, there can be only one implementation of the base interface. In the example
|
||||
```csharp
|
||||
interface IControl
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
interface ITextBox: IControl
|
||||
{
|
||||
void SetText(string text);
|
||||
}
|
||||
|
||||
interface IListBox: IControl
|
||||
{
|
||||
void SetItems(string[] items);
|
||||
}
|
||||
|
||||
class ComboBox: IControl, ITextBox, IListBox
|
||||
{
|
||||
void IControl.Paint() {...}
|
||||
void ITextBox.SetText(string text) {...}
|
||||
void IListBox.SetItems(string[] items) {...}
|
||||
}
|
||||
```
|
||||
it is not possible to have separate implementations for the `IControl` named in the base class list, the `IControl` inherited by `ITextBox`, and the `IControl` inherited by `IListBox`. Indeed, there is no notion of a separate identity for these interfaces. Rather, the implementations of `ITextBox` and `IListBox` share the same implementation of `IControl`, and `ComboBox` is simply considered to implement three interfaces, `IControl`, `ITextBox`, and `IListBox`.
|
||||
|
||||
The members of a base class participate in interface mapping. In the example
|
||||
```csharp
|
||||
interface Interface1
|
||||
{
|
||||
void F();
|
||||
}
|
||||
|
||||
class Class1
|
||||
{
|
||||
public void F() {}
|
||||
public void G() {}
|
||||
}
|
||||
|
||||
class Class2: Class1, Interface1
|
||||
{
|
||||
new public void G() {}
|
||||
}
|
||||
```
|
||||
the method `F` in `Class1` is used in `Class2`'s implementation of `Interface1`.
|
||||
|
||||
### Interface implementation inheritance
|
||||
|
||||
A class inherits all interface implementations provided by its base classes.
|
||||
|
||||
Without explicitly ***re-implementing*** an interface, a derived class cannot in any way alter the interface mappings it inherits from its base classes. For example, in the declarations
|
||||
```csharp
|
||||
interface IControl
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
class Control: IControl
|
||||
{
|
||||
public void Paint() {...}
|
||||
}
|
||||
|
||||
class TextBox: Control
|
||||
{
|
||||
new public void Paint() {...}
|
||||
}
|
||||
```
|
||||
the `Paint` method in `TextBox` hides the `Paint` method in `Control`, but it does not alter the mapping of `Control.Paint` onto `IControl.Paint`, and calls to `Paint` through class instances and interface instances will have the following effects
|
||||
```csharp
|
||||
Control c = new Control();
|
||||
TextBox t = new TextBox();
|
||||
IControl ic = c;
|
||||
IControl it = t;
|
||||
c.Paint(); // invokes Control.Paint();
|
||||
t.Paint(); // invokes TextBox.Paint();
|
||||
ic.Paint(); // invokes Control.Paint();
|
||||
it.Paint(); // invokes Control.Paint();
|
||||
```
|
||||
|
||||
However, when an interface method is mapped onto a virtual method in a class, it is possible for derived classes to override the virtual method and alter the implementation of the interface. For example, rewriting the declarations above to
|
||||
```csharp
|
||||
interface IControl
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
class Control: IControl
|
||||
{
|
||||
public virtual void Paint() {...}
|
||||
}
|
||||
|
||||
class TextBox: Control
|
||||
{
|
||||
public override void Paint() {...}
|
||||
}
|
||||
```
|
||||
the following effects will now be observed
|
||||
```csharp
|
||||
Control c = new Control();
|
||||
TextBox t = new TextBox();
|
||||
IControl ic = c;
|
||||
IControl it = t;
|
||||
c.Paint(); // invokes Control.Paint();
|
||||
t.Paint(); // invokes TextBox.Paint();
|
||||
ic.Paint(); // invokes Control.Paint();
|
||||
it.Paint(); // invokes TextBox.Paint();
|
||||
```
|
||||
|
||||
Since explicit interface member implementations cannot be declared virtual, it is not possible to override an explicit interface member implementation. However, it is perfectly valid for an explicit interface member implementation to call another method, and that other method can be declared virtual to allow derived classes to override it. For example
|
||||
```csharp
|
||||
interface IControl
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
class Control: IControl
|
||||
{
|
||||
void IControl.Paint() { PaintControl(); }
|
||||
protected virtual void PaintControl() {...}
|
||||
}
|
||||
|
||||
class TextBox: Control
|
||||
{
|
||||
protected override void PaintControl() {...}
|
||||
}
|
||||
```
|
||||
|
||||
Here, classes derived from `Control` can specialize the implementation of `IControl.Paint` by overriding the `PaintControl` method.
|
||||
|
||||
### Interface re-implementation
|
||||
|
||||
A class that inherits an interface implementation is permitted to ***re-implement*** the interface by including it in the base class list.
|
||||
|
||||
A re-implementation of an interface follows exactly the same interface mapping rules as an initial implementation of an interface. Thus, the inherited interface mapping has no effect whatsoever on the interface mapping established for the re-implementation of the interface. For example, in the declarations
|
||||
```csharp
|
||||
interface IControl
|
||||
{
|
||||
void Paint();
|
||||
}
|
||||
|
||||
class Control: IControl
|
||||
{
|
||||
void IControl.Paint() {...}
|
||||
}
|
||||
|
||||
class MyControl: Control, IControl
|
||||
{
|
||||
public void Paint() {}
|
||||
}
|
||||
```
|
||||
the fact that `Control` maps `IControl.Paint` onto `Control.IControl.Paint` doesn't affect the re-implementation in `MyControl`, which maps `IControl.Paint` onto `MyControl.Paint`.
|
||||
|
||||
Inherited public member declarations and inherited explicit interface member declarations participate in the interface mapping process for re-implemented interfaces. For example
|
||||
```csharp
|
||||
interface IMethods
|
||||
{
|
||||
void F();
|
||||
void G();
|
||||
void H();
|
||||
void I();
|
||||
}
|
||||
|
||||
class Base: IMethods
|
||||
{
|
||||
void IMethods.F() {}
|
||||
void IMethods.G() {}
|
||||
public void H() {}
|
||||
public void I() {}
|
||||
}
|
||||
|
||||
class Derived: Base, IMethods
|
||||
{
|
||||
public void F() {}
|
||||
void IMethods.H() {}
|
||||
}
|
||||
```
|
||||
|
||||
Here, the implementation of `IMethods` in `Derived` maps the interface methods onto `Derived.F`, `Base.IMethods.G`, `Derived.IMethods.H`, and `Base.I`.
|
||||
|
||||
When a class implements an interface, it implicitly also implements all of that interface's base interfaces. Likewise, a re-implementation of an interface is also implicitly a re-implementation of all of the interface's base interfaces. For example
|
||||
```csharp
|
||||
interface IBase
|
||||
{
|
||||
void F();
|
||||
}
|
||||
|
||||
interface IDerived: IBase
|
||||
{
|
||||
void G();
|
||||
}
|
||||
|
||||
class C: IDerived
|
||||
{
|
||||
void IBase.F() {...}
|
||||
void IDerived.G() {...}
|
||||
}
|
||||
|
||||
class D: C, IDerived
|
||||
{
|
||||
public void F() {...}
|
||||
public void G() {...}
|
||||
}
|
||||
```
|
||||
|
||||
Here, the re-implementation of `IDerived` also re-implements `IBase`, mapping `IBase.F` onto `D.F`.
|
||||
|
||||
### Abstract classes and interfaces
|
||||
|
||||
Like a non-abstract class, an abstract class must provide implementations of all members of the interfaces that are listed in the base class list of the class. However, an abstract class is permitted to map interface methods onto abstract methods. For example
|
||||
```csharp
|
||||
interface IMethods
|
||||
{
|
||||
void F();
|
||||
void G();
|
||||
}
|
||||
|
||||
abstract class C: IMethods
|
||||
{
|
||||
public abstract void F();
|
||||
public abstract void G();
|
||||
}
|
||||
```
|
||||
|
||||
Here, the implementation of `IMethods` maps `F` and `G` onto abstract methods, which must be overridden in non-abstract classes that derive from `C`.
|
||||
|
||||
Note that explicit interface member implementations cannot be abstract, but explicit interface member implementations are of course permitted to call abstract methods. For example
|
||||
```csharp
|
||||
interface IMethods
|
||||
{
|
||||
void F();
|
||||
void G();
|
||||
}
|
||||
|
||||
abstract class C: IMethods
|
||||
{
|
||||
void IMethods.F() { FF(); }
|
||||
void IMethods.G() { GG(); }
|
||||
protected abstract void FF();
|
||||
protected abstract void GG();
|
||||
}
|
||||
```
|
||||
|
||||
Here, non-abstract classes that derive from `C` would be required to override `FF` and `GG`, thus providing the actual implementation of `IMethods`.
|
||||
1627
spec/introduction.md
Normal file
1627
spec/introduction.md
Normal file
File diff suppressed because it is too large
Load diff
1282
spec/lexical-structure.md
Normal file
1282
spec/lexical-structure.md
Normal file
File diff suppressed because it is too large
Load diff
605
spec/namespaces.md
Normal file
605
spec/namespaces.md
Normal file
|
|
@ -0,0 +1,605 @@
|
|||
# Namespaces
|
||||
|
||||
C# programs are organized using namespaces. Namespaces are used both as an "internal" organization system for a program, and as an "external" organization system—a way of presenting program elements that are exposed to other programs.
|
||||
|
||||
Using directives ([Using directives](namespaces.md#using-directives)) are provided to facilitate the use of namespaces.
|
||||
|
||||
## Compilation units
|
||||
|
||||
A *compilation_unit* defines the overall structure of a source file. A compilation unit consists of zero or more *using_directive*s followed by zero or more *global_attributes* followed by zero or more *namespace_member_declaration*s.
|
||||
|
||||
```antlr
|
||||
compilation_unit
|
||||
: extern_alias_directive* using_directive* global_attributes? namespace_member_declaration*
|
||||
;
|
||||
```
|
||||
|
||||
A C# program consists of one or more compilation units, each contained in a separate source file. When a C# program is compiled, all of the compilation units are processed together. Thus, compilation units can depend on each other, possibly in a circular fashion.
|
||||
|
||||
The *using_directive*s of a compilation unit affect the *global_attributes* and *namespace_member_declaration*s of that compilation unit, but have no effect on other compilation units.
|
||||
|
||||
The *global_attributes* ([Attributes](attributes.md#attributes)) of a compilation unit permit the specification of attributes for the target assembly and module. Assemblies and modules act as physical containers for types. An assembly may consist of several physically separate modules.
|
||||
|
||||
The *namespace_member_declaration*s of each compilation unit of a program contribute members to a single declaration space called the global namespace. For example:
|
||||
|
||||
File `A.cs`:
|
||||
```csharp
|
||||
class A {}
|
||||
```
|
||||
|
||||
File `B.cs`:
|
||||
```csharp
|
||||
class B {}
|
||||
```
|
||||
|
||||
The two compilation units contribute to the single global namespace, in this case declaring two classes with the fully qualified names `A` and `B`. Because the two compilation units contribute to the same declaration space, it would have been an error if each contained a declaration of a member with the same name.
|
||||
|
||||
## Namespace declarations
|
||||
|
||||
A *namespace_declaration* consists of the keyword `namespace`, followed by a namespace name and body, optionally followed by a semicolon.
|
||||
|
||||
```antlr
|
||||
namespace_declaration
|
||||
: 'namespace' qualified_identifier namespace_body ';'?
|
||||
;
|
||||
|
||||
qualified_identifier
|
||||
: identifier ('.' identifier)*
|
||||
;
|
||||
|
||||
namespace_body
|
||||
: '{' extern_alias_directive* using_directive* namespace_member_declaration* '}'
|
||||
;
|
||||
```
|
||||
|
||||
A *namespace_declaration* may occur as a top-level declaration in a *compilation_unit* or as a member declaration within another *namespace_declaration*. When a *namespace_declaration* occurs as a top-level declaration in a *compilation_unit*, the namespace becomes a member of the global namespace. When a *namespace_declaration* occurs within another *namespace_declaration*, the inner namespace becomes a member of the outer namespace. In either case, the name of a namespace must be unique within the containing namespace.
|
||||
|
||||
Namespaces are implicitly `public` and the declaration of a namespace cannot include any access modifiers.
|
||||
|
||||
Within a *namespace_body*, the optional *using_directive*s import the names of other namespaces, types and members, allowing them to be referenced directly instead of through qualified names. The optional *namespace_member_declaration*s contribute members to the declaration space of the namespace. Note that all *using_directive*s must appear before any member declarations.
|
||||
|
||||
The *qualified_identifier* of a *namespace_declaration* may be a single identifier or a sequence of identifiers separated by "`.`" tokens. The latter form permits a program to define a nested namespace without lexically nesting several namespace declarations. For example,
|
||||
|
||||
```csharp
|
||||
namespace N1.N2
|
||||
{
|
||||
class A {}
|
||||
|
||||
class B {}
|
||||
}
|
||||
```
|
||||
is semantically equivalent to
|
||||
```csharp
|
||||
namespace N1
|
||||
{
|
||||
namespace N2
|
||||
{
|
||||
class A {}
|
||||
|
||||
class B {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Namespaces are open-ended, and two namespace declarations with the same fully qualified name contribute to the same declaration space ([Declarations](basic-concepts.md#declarations)). In the example
|
||||
```csharp
|
||||
namespace N1.N2
|
||||
{
|
||||
class A {}
|
||||
}
|
||||
|
||||
namespace N1.N2
|
||||
{
|
||||
class B {}
|
||||
}
|
||||
```
|
||||
the two namespace declarations above contribute to the same declaration space, in this case declaring two classes with the fully qualified names `N1.N2.A` and `N1.N2.B`. Because the two declarations contribute to the same declaration space, it would have been an error if each contained a declaration of a member with the same name.
|
||||
|
||||
## Extern aliases
|
||||
|
||||
An *extern_alias_directive* introduces an identifier that serves as an alias for a namespace. The specification of the aliased namespace is external to the source code of the program and applies also to nested namespaces of the aliased namespace.
|
||||
|
||||
```antlr
|
||||
extern_alias_directive
|
||||
: 'extern' 'alias' identifier ';'
|
||||
;
|
||||
```
|
||||
|
||||
The scope of an *extern_alias_directive* extends over the *using_directive*s, *global_attributes* and *namespace_member_declaration*s of its immediately containing compilation unit or namespace body.
|
||||
|
||||
Within a compilation unit or namespace body that contains an *extern_alias_directive*, the identifier introduced by the *extern_alias_directive* can be used to reference the aliased namespace. It is a compile-time error for the *identifier* to be the word `global`.
|
||||
|
||||
An *extern_alias_directive* makes an alias available within a particular compilation unit or namespace body, but it 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 following program declares and uses two extern aliases, `X` and `Y`, each of which represent the root of a distinct namespace hierarchy:
|
||||
```csharp
|
||||
extern alias X;
|
||||
extern alias Y;
|
||||
|
||||
class Test
|
||||
{
|
||||
X::N.A a;
|
||||
X::N.B b1;
|
||||
Y::N.B b2;
|
||||
Y::N.C c;
|
||||
}
|
||||
```
|
||||
|
||||
The program declares the existence of the extern aliases `X` and `Y`, but the actual definitions of the aliases are external to the program. The identically named `N.B` classes can now be referenced as `X.N.B` and `Y.N.B`, or, using the namespace alias qualifier, `X::N.B` and `Y::N.B`. An error occurs if a program declares an extern alias for which no external definition is provided.
|
||||
|
||||
## Using directives
|
||||
|
||||
***Using directives*** facilitate the use of namespaces and types defined in other namespaces. Using directives impact the name resolution process of *namespace_or_type_name*s ([Namespace and type names](basic-concepts.md#namespace-and-type-names)) and *simple_name*s ([Simple names](expressions.md#simple-names)), but unlike declarations, using directives do not contribute new members to the underlying declaration spaces of the compilation units or namespaces within which they are used.
|
||||
|
||||
```antlr
|
||||
using_directive
|
||||
: using_alias_directive
|
||||
| using_namespace_directive
|
||||
| using_static_directive
|
||||
;
|
||||
```
|
||||
|
||||
A *using_alias_directive* ([Using alias directives](namespaces.md#using-alias-directives)) introduces an alias for a namespace or type.
|
||||
|
||||
A *using_namespace_directive* ([Using namespace directives](namespaces.md#using-namespace-directives)) imports the type members of a namespace.
|
||||
|
||||
A *using_static_directive* ([Using static directives](namespaces.md#using-static-directives)) imports the nested types and static members of a type.
|
||||
|
||||
The scope of a *using_directive* extends over the *namespace_member_declaration*s of its immediately containing compilation unit or namespace body. The scope of a *using_directive* specifically does not include its peer *using_directive*s. Thus, peer *using_directive*s do not affect each other, and the order in which they are written is insignificant.
|
||||
|
||||
### Using alias directives
|
||||
|
||||
A *using_alias_directive* introduces an identifier that serves as an alias for a namespace or type within the immediately enclosing compilation unit or namespace body.
|
||||
|
||||
```antlr
|
||||
using_alias_directive
|
||||
: 'using' identifier '=' namespace_or_type_name ';'
|
||||
;
|
||||
```
|
||||
|
||||
Within member declarations in a compilation unit or namespace body that contains a *using_alias_directive*, the identifier introduced by the *using_alias_directive* can be used to reference the given namespace or type. For example:
|
||||
```csharp
|
||||
namespace N1.N2
|
||||
{
|
||||
class A {}
|
||||
}
|
||||
|
||||
namespace N3
|
||||
{
|
||||
using A = N1.N2.A;
|
||||
|
||||
class B: A {}
|
||||
}
|
||||
```
|
||||
|
||||
Above, within member declarations in the `N3` namespace, `A` is an alias for `N1.N2.A`, and thus class `N3.B` derives from class `N1.N2.A`. The same effect can be obtained by creating an alias `R` for `N1.N2` and then referencing `R.A`:
|
||||
```csharp
|
||||
namespace N3
|
||||
{
|
||||
using R = N1.N2;
|
||||
|
||||
class B: R.A {}
|
||||
}
|
||||
```
|
||||
|
||||
The *identifier* of a *using_alias_directive* must be unique within the declaration space of the compilation unit or namespace that immediately contains the *using_alias_directive*. For example:
|
||||
```csharp
|
||||
namespace N3
|
||||
{
|
||||
class A {}
|
||||
}
|
||||
|
||||
namespace N3
|
||||
{
|
||||
using A = N1.N2.A; // Error, A already exists
|
||||
}
|
||||
```
|
||||
|
||||
Above, `N3` already contains a member `A`, so it is a compile-time error for a *using_alias_directive* to use that identifier. Likewise, it is a compile-time error for two or more *using_alias_directive*s in the same compilation unit or namespace body to declare aliases by the same name.
|
||||
|
||||
A *using_alias_directive* makes an alias available within a particular compilation unit or namespace body, but it does not contribute any new members to the underlying declaration space. In other words, a *using_alias_directive* is not transitive but rather affects only the compilation unit or namespace body in which it occurs. In the example
|
||||
```csharp
|
||||
namespace N3
|
||||
{
|
||||
using R = N1.N2;
|
||||
}
|
||||
|
||||
namespace N3
|
||||
{
|
||||
class B: R.A {} // Error, R unknown
|
||||
}
|
||||
```
|
||||
the scope of the *using_alias_directive* that introduces `R` only extends to member declarations in the namespace body in which it is contained, so `R` is unknown in the second namespace declaration. However, placing the *using_alias_directive* in the containing compilation unit causes the alias to become available within both namespace declarations:
|
||||
```csharp
|
||||
using R = N1.N2;
|
||||
|
||||
namespace N3
|
||||
{
|
||||
class B: R.A {}
|
||||
}
|
||||
|
||||
namespace N3
|
||||
{
|
||||
class C: R.A {}
|
||||
}
|
||||
```
|
||||
|
||||
Just like regular members, names introduced by *using_alias_directive*s are hidden by similarly named members in nested scopes. In the example
|
||||
```csharp
|
||||
using R = N1.N2;
|
||||
|
||||
namespace N3
|
||||
{
|
||||
class R {}
|
||||
|
||||
class B: R.A {} // Error, R has no member A
|
||||
}
|
||||
```
|
||||
the reference to `R.A` in the declaration of `B` causes a compile-time error because `R` refers to `N3.R`, not `N1.N2`.
|
||||
|
||||
The order in which *using_alias_directive*s are written has no significance, and resolution of the *namespace_or_type_name* referenced by a *using_alias_directive* is not affected by the *using_alias_directive* itself or by other *using_directive*s in the immediately containing compilation unit or namespace body. In other words, the *namespace_or_type_name* of a *using_alias_directive* is resolved as if the immediately containing compilation unit or namespace body had no *using_directive*s. A *using_alias_directive* may however be affected by *extern_alias_directive*s in the immediately containing compilation unit or namespace body. In the example
|
||||
```csharp
|
||||
namespace N1.N2 {}
|
||||
|
||||
namespace N3
|
||||
{
|
||||
extern alias E;
|
||||
|
||||
using R1 = E.N; // OK
|
||||
|
||||
using R2 = N1; // OK
|
||||
|
||||
using R3 = N1.N2; // OK
|
||||
|
||||
using R4 = R2.N2; // Error, R2 unknown
|
||||
}
|
||||
```
|
||||
the last *using_alias_directive* results in a compile-time error because it is not affected by the first *using_alias_directive*. The first *using_alias_directive* does not result in an error since the scope of the extern alias `E` includes the *using_alias_directive*.
|
||||
|
||||
A *using_alias_directive* can create an alias for any namespace or type, including the namespace within which it appears and any namespace or type nested within that namespace.
|
||||
|
||||
Accessing a namespace or type through an alias yields exactly the same result as accessing that namespace or type through its declared name. For example, given
|
||||
```csharp
|
||||
namespace N1.N2
|
||||
{
|
||||
class A {}
|
||||
}
|
||||
|
||||
namespace N3
|
||||
{
|
||||
using R1 = N1;
|
||||
using R2 = N1.N2;
|
||||
|
||||
class B
|
||||
{
|
||||
N1.N2.A a; // refers to N1.N2.A
|
||||
R1.N2.A b; // refers to N1.N2.A
|
||||
R2.A c; // refers to N1.N2.A
|
||||
}
|
||||
}
|
||||
```
|
||||
the names `N1.N2.A`, `R1.N2.A`, and `R2.A` are equivalent and all refer to the class whose fully qualified name is `N1.N2.A`.
|
||||
|
||||
Using aliases can name a closed constructed type, but cannot name an unbound generic type declaration without supplying type arguments. For example:
|
||||
```csharp
|
||||
namespace N1
|
||||
{
|
||||
class A<T>
|
||||
{
|
||||
class B {}
|
||||
}
|
||||
}
|
||||
|
||||
namespace N2
|
||||
{
|
||||
using W = N1.A; // Error, cannot name unbound generic type
|
||||
|
||||
using X = N1.A.B; // Error, cannot name unbound generic type
|
||||
|
||||
using Y = N1.A<int>; // Ok, can name closed constructed type
|
||||
|
||||
using Z<T> = N1.A<T>; // Error, using alias cannot have type parameters
|
||||
}
|
||||
```
|
||||
|
||||
### Using namespace directives
|
||||
|
||||
A *using_namespace_directive* imports the types contained in a namespace into the immediately enclosing compilation unit or namespace body, enabling the identifier of each type to be used without qualification.
|
||||
|
||||
```antlr
|
||||
using_namespace_directive
|
||||
: 'using' namespace_name ';'
|
||||
;
|
||||
```
|
||||
|
||||
Within member declarations in a compilation unit or namespace body that contains a *using_namespace_directive*, the types contained in the given namespace can be referenced directly. For example:
|
||||
```csharp
|
||||
namespace N1.N2
|
||||
{
|
||||
class A {}
|
||||
}
|
||||
|
||||
namespace N3
|
||||
{
|
||||
using N1.N2;
|
||||
|
||||
class B: A {}
|
||||
}
|
||||
```
|
||||
|
||||
Above, within member declarations in the `N3` namespace, the type members of `N1.N2` are directly available, and thus class `N3.B` derives from class `N1.N2.A`.
|
||||
|
||||
A *using_namespace_directive* imports the types contained in the given namespace, but specifically does not import nested namespaces. In the example
|
||||
```csharp
|
||||
namespace N1.N2
|
||||
{
|
||||
class A {}
|
||||
}
|
||||
|
||||
namespace N3
|
||||
{
|
||||
using N1;
|
||||
|
||||
class B: N2.A {} // Error, N2 unknown
|
||||
}
|
||||
```
|
||||
the *using_namespace_directive* imports the types contained in `N1`, but not the namespaces nested in `N1`. Thus, the reference to `N2.A` in the declaration of `B` results in a compile-time error because no members named `N2` are in scope.
|
||||
|
||||
Unlike a *using_alias_directive*, a *using_namespace_directive* may import types whose identifiers are already defined within the enclosing compilation unit or namespace body. In effect, names imported by a *using_namespace_directive* are hidden by similarly named members in the enclosing compilation unit or namespace body. For example:
|
||||
```csharp
|
||||
namespace N1.N2
|
||||
{
|
||||
class A {}
|
||||
|
||||
class B {}
|
||||
}
|
||||
|
||||
namespace N3
|
||||
{
|
||||
using N1.N2;
|
||||
|
||||
class A {}
|
||||
}
|
||||
```
|
||||
|
||||
Here, within member declarations in the `N3` namespace, `A` refers to `N3.A` rather than `N1.N2.A`.
|
||||
|
||||
When more than one namespace or type imported by *using_namespace_directive*s or *using_static_directive*s in the same compilation unit or namespace body contain types by the same name, references to that name as a *type_name* are considered ambiguous. In the example
|
||||
```csharp
|
||||
namespace N1
|
||||
{
|
||||
class A {}
|
||||
}
|
||||
|
||||
namespace N2
|
||||
{
|
||||
class A {}
|
||||
}
|
||||
|
||||
namespace N3
|
||||
{
|
||||
using N1;
|
||||
|
||||
using N2;
|
||||
|
||||
class B: A {} // Error, A is ambiguous
|
||||
}
|
||||
```
|
||||
both `N1` and `N2` contain a member `A`, and because `N3` imports both, referencing `A` in `N3` is a compile-time error. In this situation, the conflict can be resolved either through qualification of references to `A`, or by introducing a *using_alias_directive* that picks a particular `A`. For example:
|
||||
```csharp
|
||||
namespace N3
|
||||
{
|
||||
using N1;
|
||||
|
||||
using N2;
|
||||
|
||||
using A = N1.A;
|
||||
|
||||
class B: A {} // A means N1.A
|
||||
}
|
||||
```
|
||||
|
||||
Furthermore, when more than one namespace or type imported by *using_namespace_directive*s or *using_static_directive*s in the same compilation unit or namespace body contain types or members by the same name, references to that name as a *simple_name* are considered ambiguous. In the example
|
||||
```csharp
|
||||
namespace N1
|
||||
{
|
||||
class A {}
|
||||
}
|
||||
|
||||
class C
|
||||
{
|
||||
public static int A
|
||||
}
|
||||
|
||||
namespace N2
|
||||
{
|
||||
using N1;
|
||||
using static C;
|
||||
|
||||
class B
|
||||
{
|
||||
void M()
|
||||
{
|
||||
A a = new A(); // Ok, A is unambiguous as a type-name
|
||||
A.Equals(2); // Error, A is ambiguous as a simple-name
|
||||
}
|
||||
}
|
||||
```
|
||||
`N1` contains a type member `A`, and `C` contains a static method `A`, and because `N2` imports both, referencing `A` as a *simple_name* is ambiguous and a compile-time error.
|
||||
|
||||
Like a *using_alias_directive*, a *using_namespace_directive* does not contribute any new members to the underlying declaration space of the compilation unit or namespace, but rather affects only the compilation unit or namespace body in which it appears.
|
||||
|
||||
The *namespace_name* referenced by a *using_namespace_directive* is resolved in the same way as the *namespace_or_type_name* referenced by a *using_alias_directive*. Thus, *using_namespace_directive*s in the same compilation unit or namespace body do not affect each other and can be written in any order.
|
||||
|
||||
### Using static directives
|
||||
|
||||
A *using_static_directive* imports the nested types and static members contained directly in a type declaration into the immediately enclosing compilation unit or namespace body, enabling the identifier of each member and type to be used without qualification.
|
||||
|
||||
```antlr
|
||||
using_static_directive
|
||||
: 'using' 'static' type_name ';'
|
||||
;
|
||||
```
|
||||
|
||||
Within member declarations in a compilation unit or namespace body that contains a *using_static_directive*, the accessible nested types and static members (except extension methods) contained directly in the declaration of the given type can be referenced directly. For example:
|
||||
|
||||
```csharp
|
||||
namespace N1
|
||||
{
|
||||
class A
|
||||
{
|
||||
public class B{}
|
||||
public static B M(){ return new B(); }
|
||||
}
|
||||
}
|
||||
|
||||
namespace N2
|
||||
{
|
||||
using static N1.A;
|
||||
class C
|
||||
{
|
||||
void N() { B b = M(); }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Above, within member declarations in the `N2` namespace, the static members and nested types of `N1.A` are directly available, and thus the method `N` is able to reference both the `B` and `M` members of `N1.A`.
|
||||
|
||||
A *using_static_directive` specifically does not import extension methods directly as static methods, but makes them available for extension method invocation ([Extension method invocations](expressions.md#extension-method-invocations)). In the example
|
||||
|
||||
```csharp
|
||||
namespace N1
|
||||
{
|
||||
static class A
|
||||
{
|
||||
public static void M(this string s){}
|
||||
}
|
||||
}
|
||||
|
||||
namespace N2
|
||||
{
|
||||
using static N1.A;
|
||||
|
||||
class B
|
||||
{
|
||||
void N()
|
||||
{
|
||||
M("A"); // Error, M unknown
|
||||
"B".M(); // Ok, M known as extension method
|
||||
N1.A.M("C"); // Ok, fully qualified
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
the *using_static_directive* imports the extension method `M` contained in `N1.A`, but only as an extension method. Thus, the first reference to `M` in the body of `B.N` results in a compile-time error because no members named `M` are in scope.
|
||||
|
||||
A *using_static_directive* only imports members and types declared directly in the given type, not members and types declared in base classes.
|
||||
|
||||
TODO: Example
|
||||
|
||||
Ambiguities between multiple *using_namespace_directives* and *using_static_directives* are discussed in [Using namespace directives](namespaces.md#using-namespace-directives).
|
||||
|
||||
## Namespace members
|
||||
|
||||
A *namespace_member_declaration* is either a *namespace_declaration* ([Namespace declarations](namespaces.md#namespace-declarations)) or a *type_declaration* ([Type declarations](namespaces.md#type-declarations)).
|
||||
|
||||
```antlr
|
||||
namespace_member_declaration
|
||||
: namespace_declaration
|
||||
| type_declaration
|
||||
;
|
||||
```
|
||||
|
||||
A compilation unit or a namespace body can contain *namespace_member_declaration*s, and such declarations contribute new members to the underlying declaration space of the containing compilation unit or namespace body.
|
||||
|
||||
## Type declarations
|
||||
|
||||
A *type_declaration* is a *class_declaration* ([Class declarations](classes.md#class-declarations)), a *struct_declaration* ([Struct declarations](structs.md#struct-declarations)), an *interface_declaration* ([Interface declarations](interfaces.md#interface-declarations)), an *enum_declaration* ([Enum declarations](enums.md#enum-declarations)), or a *delegate_declaration* ([Delegate declarations](delegates.md#delegate-declarations)).
|
||||
|
||||
```antlr
|
||||
type_declaration
|
||||
: class_declaration
|
||||
| struct_declaration
|
||||
| interface_declaration
|
||||
| enum_declaration
|
||||
| delegate_declaration
|
||||
;
|
||||
```
|
||||
|
||||
A *type_declaration* can occur as a top-level declaration in a compilation unit or as a member declaration within a namespace, class, or struct.
|
||||
|
||||
When a type declaration for a type `T` occurs as a top-level declaration in a compilation unit, the fully qualified name of the newly declared type is simply `T`. When a type declaration for a type `T` occurs within a namespace, class, or struct, the fully qualified name of the newly declared type is `N.T`, where `N` is the fully qualified name of the containing namespace, class, or struct.
|
||||
|
||||
A type declared within a class or struct is called a nested type ([Nested types](classes.md#nested-types)).
|
||||
|
||||
The permitted access modifiers and the default access for a type declaration depend on the context in which the declaration takes place ([Declared accessibility](basic-concepts.md#declared-accessibility)):
|
||||
|
||||
* Types declared in compilation units or namespaces can have `public` or `internal` access. The default is `internal` access.
|
||||
* Types declared in classes can have `public`, `protected internal`, `protected`, `internal`, or `private` access. The default is `private` access.
|
||||
* Types declared in structs can have `public`, `internal`, or `private` access. The default is `private` access.
|
||||
|
||||
## Namespace alias qualifiers
|
||||
|
||||
The ***namespace alias qualifier*** `::` makes it possible to guarantee that type name lookups are unaffected by the introduction of new types and members. The namespace alias qualifier always appears between two identifiers referred to as the left-hand and right-hand identifiers. Unlike the regular `.` qualifier, the left-hand identifier of the `::` qualifier is looked up only as an extern or using alias.
|
||||
|
||||
A *qualified_alias_member* is defined as follows:
|
||||
|
||||
```antlr
|
||||
qualified_alias_member
|
||||
: identifier '::' identifier type_argument_list?
|
||||
;
|
||||
```
|
||||
|
||||
A *qualified_alias_member* can be used as a *namespace_or_type_name* ([Namespace and type names](basic-concepts.md#namespace-and-type-names)) or as the left operand in a *member_access* ([Member access](expressions.md#member-access)).
|
||||
|
||||
A *qualified_alias_member* has one of two forms:
|
||||
|
||||
* `N::I<A1, ..., Ak>`, where `N` and `I` represent identifiers, and `<A1, ..., Ak>` is a type argument list. (`K` is always at least one.)
|
||||
* `N::I`, where `N` and `I` represent identifiers. (In this case, `K` is considered to be zero.)
|
||||
|
||||
Using this notation, the meaning of a *qualified_alias_member* is determined as follows:
|
||||
|
||||
* If `N` is the identifier `global`, then the global namespace is searched for `I`:
|
||||
* If the global namespace contains a namespace named `I` and `K` is zero, then the *qualified_alias_member* refers to that namespace.
|
||||
* Otherwise, if the global namespace contains a non-generic type named `I` and `K` is zero, then the *qualified_alias_member* refers to that type.
|
||||
* Otherwise, if the global namespace contains a type named `I` that has `K` type parameters, then the *qualified_alias_member* refers to that type constructed with the given type arguments.
|
||||
* Otherwise, the *qualified_alias_member* is undefined and a compile-time error occurs.
|
||||
|
||||
* Otherwise, starting with the namespace declaration ([Namespace declarations](namespaces.md#namespace-declarations)) immediately containing the *qualified_alias_member* (if any), continuing with each enclosing namespace declaration (if any), and ending with the compilation unit containing the *qualified_alias_member*, the following steps are evaluated until an entity is located:
|
||||
|
||||
* If the namespace declaration or compilation unit contains a *using_alias_directive* that associates `N` with a type, then the *qualified_alias_member* is undefined and a compile-time error occurs.
|
||||
* Otherwise, if the namespace declaration or compilation unit contains an *extern_alias_directive* or *using_alias_directive* that associates `N` with a namespace, then:
|
||||
* If the namespace associated with `N` contains a namespace named `I` and `K` is zero, then the *qualified_alias_member* refers to that namespace.
|
||||
* Otherwise, if the namespace associated with `N` contains a non-generic type named `I` and `K` is zero, then the *qualified_alias_member* refers to that type.
|
||||
* Otherwise, if the namespace associated with `N` contains a type named `I` that has `K` type parameters, then the *qualified_alias_member* refers to that type constructed with the given type arguments.
|
||||
* Otherwise, the *qualified_alias_member* is undefined and a compile-time error occurs.
|
||||
* Otherwise, the *qualified_alias_member* is undefined and a compile-time error occurs.
|
||||
|
||||
Note that using the namespace alias qualifier with an alias that references a type causes a compile-time error. Also note that if the identifier `N` is `global`, then lookup is performed in the global namespace, even if there is a using alias associating `global` with a type or namespace.
|
||||
|
||||
### Uniqueness of aliases
|
||||
|
||||
Each compilation unit and namespace body has a separate declaration space for extern aliases and using aliases. Thus, while the name of an extern alias or using alias must be unique within the set of extern aliases and using aliases declared in the immediately containing compilation unit or namespace body, an alias is permitted to have the same name as a type or namespace as long as it is used only with the `::` qualifier.
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
namespace N
|
||||
{
|
||||
public class A {}
|
||||
|
||||
public class B {}
|
||||
}
|
||||
|
||||
namespace N
|
||||
{
|
||||
using A = System.IO;
|
||||
|
||||
class X
|
||||
{
|
||||
A.Stream s1; // Error, A is ambiguous
|
||||
|
||||
A::Stream s2; // Ok
|
||||
}
|
||||
}
|
||||
```
|
||||
the name `A` has two possible meanings in the second namespace body because both the class `A` and the using alias `A` are in scope. For this reason, use of `A` in the qualified name `A.Stream` is ambiguous and causes a compile-time error to occur. However, use of `A` with the `::` qualifier is not an error because `A` is looked up only as a namespace alias.
|
||||
1439
spec/statements.md
Normal file
1439
spec/statements.md
Normal file
File diff suppressed because it is too large
Load diff
618
spec/structs.md
Normal file
618
spec/structs.md
Normal file
|
|
@ -0,0 +1,618 @@
|
|||
# Structs
|
||||
|
||||
Structs are similar to classes in that they represent data structures that can contain data members and function members. However, unlike classes, structs are value types and do not require heap allocation. A variable of a struct type directly contains the data of the struct, whereas a variable of a class type contains a reference to the data, the latter known as an object.
|
||||
|
||||
Structs are particularly useful for small data structures that have value semantics. Complex numbers, points in a coordinate system, or key-value pairs in a dictionary are all good examples of structs. Key to these data structures is that they have few data members, that they do not require use of inheritance or referential identity, and that they can be conveniently implemented using value semantics where assignment copies the value instead of the reference.
|
||||
|
||||
As described in [Simple types](types.md#simple-types), the simple types provided by C#, such as `int`, `double`, and `bool`, are in fact all struct types. Just as these predefined types are structs, it is also possible to use structs and operator overloading to implement new "primitive" types in the C# language. Two examples of such types are given at the end of this chapter ([Struct examples](structs.md#struct-examples)).
|
||||
|
||||
## Struct declarations
|
||||
|
||||
A *struct_declaration* is a *type_declaration* ([Type declarations](namespaces.md#type-declarations)) that declares a new struct:
|
||||
|
||||
```antlr
|
||||
struct_declaration
|
||||
: attributes? struct_modifier* 'partial'? 'struct' identifier type_parameter_list?
|
||||
struct_interfaces? type_parameter_constraints_clause* struct_body ';'?
|
||||
;
|
||||
```
|
||||
|
||||
A *struct_declaration* consists of an optional set of *attributes* ([Attributes](attributes.md#attributes)), followed by an optional set of *struct_modifier*s ([Struct modifiers](structs.md#struct-modifiers)), followed by an optional `partial` modifier, followed by the keyword `struct` and an *identifier* that names the struct, followed by an optional *type_parameter_list* specification ([Type parameters](classes.md#type-parameters)), followed by an optional *struct_interfaces* specification ([Partial modifier](structs.md#partial-modifier)) ), followed by an optional *type_parameter_constraints_clause*s specification ([Type parameter constraints](classes.md#type-parameter-constraints)), followed by a *struct_body* ([Struct body](structs.md#struct-body)), optionally followed by a semicolon.
|
||||
|
||||
### Struct modifiers
|
||||
|
||||
A *struct_declaration* may optionally include a sequence of struct modifiers:
|
||||
|
||||
```antlr
|
||||
struct_modifier
|
||||
: 'new'
|
||||
| 'public'
|
||||
| 'protected'
|
||||
| 'internal'
|
||||
| 'private'
|
||||
| struct_modifier_unsafe
|
||||
;
|
||||
```
|
||||
|
||||
It is a compile-time error for the same modifier to appear multiple times in a struct declaration.
|
||||
|
||||
The modifiers of a struct declaration have the same meaning as those of a class declaration ([Class declarations](classes.md#class-declarations)).
|
||||
|
||||
### Partial modifier
|
||||
|
||||
The `partial` modifier indicates that this *struct_declaration* is a partial type declaration. Multiple partial struct declarations with the same name within an enclosing namespace or type declaration combine to form one struct declaration, following the rules specified in [Partial types](classes.md#partial-types).
|
||||
|
||||
### Struct interfaces
|
||||
|
||||
A struct declaration may include a *struct_interfaces* specification, in which case the struct is said to directly implement the given interface types.
|
||||
|
||||
```antlr
|
||||
struct_interfaces
|
||||
: ':' interface_type_list
|
||||
;
|
||||
```
|
||||
|
||||
Interface implementations are discussed further in [Interface implementations](interfaces.md#interface-implementations).
|
||||
|
||||
### Struct body
|
||||
|
||||
The *struct_body* of a struct defines the members of the struct.
|
||||
|
||||
```antlr
|
||||
struct_body
|
||||
: '{' struct_member_declaration* '}'
|
||||
;
|
||||
```
|
||||
|
||||
## Struct members
|
||||
|
||||
The members of a struct consist of the members introduced by its *struct_member_declaration*s and the members inherited from the type `System.ValueType`.
|
||||
|
||||
```antlr
|
||||
struct_member_declaration
|
||||
: constant_declaration
|
||||
| field_declaration
|
||||
| method_declaration
|
||||
| property_declaration
|
||||
| event_declaration
|
||||
| indexer_declaration
|
||||
| operator_declaration
|
||||
| constructor_declaration
|
||||
| static_constructor_declaration
|
||||
| type_declaration
|
||||
| struct_member_declaration_unsafe
|
||||
;
|
||||
```
|
||||
|
||||
Except for the differences noted in [Class and struct differences](structs.md#class-and-struct-differences), the descriptions of class members provided in [Class members](classes.md#class-members) through [Iterators](classes.md#iterators) apply to struct members as well.
|
||||
|
||||
## Class and struct differences
|
||||
|
||||
Structs differ from classes in several important ways:
|
||||
|
||||
* Structs are value types ([Value semantics](structs.md#value-semantics)).
|
||||
* All struct types implicitly inherit from the class `System.ValueType` ([Inheritance](structs.md#inheritance)).
|
||||
* Assignment to a variable of a struct type creates a copy of the value being assigned ([Assignment](structs.md#assignment)).
|
||||
* The default value of a struct is the value produced by setting all value type fields to their default value and all reference type fields to `null` ([Default values](structs.md#default-values)).
|
||||
* Boxing and unboxing operations are used to convert between a struct type and `object` ([Boxing and unboxing](structs.md#boxing-and-unboxing)).
|
||||
* The meaning of `this` is different for structs ([This access](expressions.md#this-access)).
|
||||
* Instance field declarations for a struct are not permitted to include variable initializers ([Field initializers](structs.md#field-initializers)).
|
||||
* A struct is not permitted to declare a parameterless instance constructor ([Constructors](structs.md#constructors)).
|
||||
* A struct is not permitted to declare a destructor ([Destructors](structs.md#destructors)).
|
||||
|
||||
### Value semantics
|
||||
|
||||
Structs are value types ([Value types](types.md#value-types)) and are said to have value semantics. Classes, on the other hand, are reference types ([Reference types](types.md#reference-types)) and are said to have reference semantics.
|
||||
|
||||
A variable of a struct type directly contains the data of the struct, whereas a variable of a class type contains a reference to the data, the latter known as an object. When a struct `B` contains an instance field of type `A` and `A` is a struct type, it is a compile-time error for `A` to depend on `B` or a type constructed from `B`. A struct `X` ***directly depends on*** a struct `Y` if `X` contains an instance field of type `Y`. Given this definition, the complete set of structs upon which a struct depends is the transitive closure of the ***directly depends on*** relationship. For example
|
||||
```csharp
|
||||
struct Node
|
||||
{
|
||||
int data;
|
||||
Node next; // error, Node directly depends on itself
|
||||
}
|
||||
```
|
||||
is an error because `Node` contains an instance field of its own type. Another example
|
||||
```csharp
|
||||
struct A { B b; }
|
||||
|
||||
struct B { C c; }
|
||||
|
||||
struct C { A a; }
|
||||
```
|
||||
is an error because each of the types `A`, `B`, and `C` depend on each other.
|
||||
|
||||
With classes, 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 structs, the variables each have their own copy of the data (except in the case of `ref` and `out` parameter variables), and it is not possible for operations on one to affect the other. Furthermore, because structs are not reference types, it is not possible for values of a struct type to be `null`.
|
||||
|
||||
Given the declaration
|
||||
```csharp
|
||||
struct Point
|
||||
{
|
||||
public int x, y;
|
||||
|
||||
public Point(int x, int y) {
|
||||
this.x = x;
|
||||
this.y = y;
|
||||
}
|
||||
}
|
||||
```
|
||||
the code fragment
|
||||
```csharp
|
||||
Point a = new Point(10, 10);
|
||||
Point b = a;
|
||||
a.x = 100;
|
||||
System.Console.WriteLine(b.x);
|
||||
```
|
||||
outputs the value `10`. The assignment of `a` to `b` creates a copy of the value, and `b` is thus unaffected by the assignment to `a.x`. Had `Point` instead been declared as a class, the output would be `100` because `a` and `b` would reference the same object.
|
||||
|
||||
### Inheritance
|
||||
|
||||
All struct types implicitly inherit from the class `System.ValueType`, which, in turn, inherits from class `object`. A struct declaration may specify a list of implemented interfaces, but it is not possible for a struct declaration to specify a base class.
|
||||
|
||||
Struct types are never abstract and are always implicitly sealed. The `abstract` and `sealed` modifiers are therefore not permitted in a struct declaration.
|
||||
|
||||
Since inheritance isn't supported for structs, the declared accessibility of a struct member cannot be `protected` or `protected internal`.
|
||||
|
||||
Function members in a struct cannot be `abstract` or `virtual`, and the `override` modifier is allowed only to override methods inherited from `System.ValueType`.
|
||||
|
||||
### Assignment
|
||||
|
||||
Assignment to a variable of a struct type creates a copy of the value being assigned. This differs from assignment to a variable of a class type, which copies the reference but not the object identified by the reference.
|
||||
|
||||
Similar to an assignment, when a struct is passed as a value parameter or returned as the result of a function member, a copy of the struct is created. A struct may be passed by reference to a function member using a `ref` or `out` parameter.
|
||||
|
||||
When a property or indexer of a struct is the target of an assignment, the instance expression associated with the property or indexer access must be classified as a variable. If the instance expression is classified as a value, a compile-time error occurs. This is described in further detail in [Simple assignment](expressions.md#simple-assignment).
|
||||
|
||||
### Default values
|
||||
|
||||
As described in [Default values](variables.md#default-values), several kinds of variables are automatically initialized to their default value when they are created. For variables of class types and other reference types, this default value is `null`. However, since structs are value types that cannot be `null`, the default value of a struct is the value produced by setting all value type fields to their default value and all reference type fields to `null`.
|
||||
|
||||
Referring to the `Point` struct declared above, the example
|
||||
```csharp
|
||||
Point[] a = new Point[100];
|
||||
```
|
||||
initializes each `Point` in the array to the value produced by setting the `x` and `y` fields to zero.
|
||||
|
||||
The default value of a struct corresponds to the value returned by the default constructor of the struct ([Default constructors](types.md#default-constructors)). Unlike a class, a struct is not permitted to declare a parameterless instance constructor. Instead, every struct implicitly has a parameterless instance constructor which always returns the value that results from setting all value type fields to their default value and all reference type fields to `null`.
|
||||
|
||||
Structs should be designed to consider the default initialization state a valid state. In the example
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
struct KeyValuePair
|
||||
{
|
||||
string key;
|
||||
string value;
|
||||
|
||||
public KeyValuePair(string key, string value) {
|
||||
if (key == null || value == null) throw new ArgumentException();
|
||||
this.key = key;
|
||||
this.value = value;
|
||||
}
|
||||
}
|
||||
```
|
||||
the user-defined instance constructor protects against null values only where it is explicitly called. In cases where a `KeyValuePair` variable is subject to default value initialization, the `key` and `value` fields will be null, and the struct must be prepared to handle this state.
|
||||
|
||||
### Boxing and unboxing
|
||||
|
||||
A value of a class type can be converted to type `object` or to an interface type that is implemented by the class simply by treating the reference as another type at compile-time. Likewise, a value of type `object` or a value of an interface type can be converted back to a class type without changing the reference (but of course a run-time type check is required in this case).
|
||||
|
||||
Since structs are not reference types, these operations are implemented differently for struct types. When a value of a struct type is converted to type `object` or to an interface type that is implemented by the struct, a boxing operation takes place. Likewise, when a value of type `object` or a value of an interface type is converted back to a struct type, an unboxing operation takes place. A key difference from the same operations on class types is that boxing and unboxing copies the struct value either into or out of the boxed instance. Thus, following a boxing or unboxing operation, changes made to the unboxed struct are not reflected in the boxed struct.
|
||||
|
||||
When a struct type overrides a virtual method inherited from `System.Object` (such as `Equals`, `GetHashCode`, or `ToString`), invocation of the virtual method through an instance of the struct type does not cause boxing to occur. This is true even when the struct is used as a type parameter and the invocation occurs through an instance of the type parameter type. For example:
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
struct Counter
|
||||
{
|
||||
int value;
|
||||
|
||||
public override string ToString() {
|
||||
value++;
|
||||
return value.ToString();
|
||||
}
|
||||
}
|
||||
|
||||
class Program
|
||||
{
|
||||
static void Test<T>() where T: new() {
|
||||
T x = new T();
|
||||
Console.WriteLine(x.ToString());
|
||||
Console.WriteLine(x.ToString());
|
||||
Console.WriteLine(x.ToString());
|
||||
}
|
||||
|
||||
static void Main() {
|
||||
Test<Counter>();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The output of the program is:
|
||||
```
|
||||
1
|
||||
2
|
||||
3
|
||||
```
|
||||
|
||||
Although it is bad style for `ToString` to have side effects, the example demonstrates that no boxing occurred for the three invocations of `x.ToString()`.
|
||||
|
||||
Similarly, boxing never implicitly occurs when accessing a member on a constrained type parameter. For example, suppose an interface `ICounter` contains a method `Increment` which can be used to modify a value. If `ICounter` is used as a constraint, the implementation of the `Increment` method is called with a reference to the variable that `Increment` was called on, never a boxed copy.
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
interface ICounter
|
||||
{
|
||||
void Increment();
|
||||
}
|
||||
|
||||
struct Counter: ICounter
|
||||
{
|
||||
int value;
|
||||
|
||||
public override string ToString() {
|
||||
return value.ToString();
|
||||
}
|
||||
|
||||
void ICounter.Increment() {
|
||||
value++;
|
||||
}
|
||||
}
|
||||
|
||||
class Program
|
||||
{
|
||||
static void Test<T>() where T: ICounter, new() {
|
||||
T x = new T();
|
||||
Console.WriteLine(x);
|
||||
x.Increment(); // Modify x
|
||||
Console.WriteLine(x);
|
||||
((ICounter)x).Increment(); // Modify boxed copy of x
|
||||
Console.WriteLine(x);
|
||||
}
|
||||
|
||||
static void Main() {
|
||||
Test<Counter>();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The first call to `Increment` modifies the value in the variable `x`. This is not equivalent to the second call to `Increment`, which modifies the value in a boxed copy of `x`. Thus, the output of the program is:
|
||||
```
|
||||
0
|
||||
1
|
||||
1
|
||||
```
|
||||
|
||||
For further details on boxing and unboxing, see [Boxing and unboxing](types.md#boxing-and-unboxing).
|
||||
|
||||
### Meaning of this
|
||||
|
||||
Within an instance constructor or instance function member of a class, `this` is classified as a value. Thus, while `this` can be used to refer to the instance for which the function member was invoked, it is not possible to assign to `this` in a function member of a class.
|
||||
|
||||
Within an instance constructor of a struct, `this` corresponds to an `out` parameter of the struct type, and within an instance function member of a struct, `this` corresponds to a `ref` parameter of the struct type. In both cases, `this` is classified as a variable, and it is possible to modify the entire struct for which the function member was invoked by assigning to `this` or by passing this as a `ref` or `out` parameter.
|
||||
|
||||
### Field initializers
|
||||
|
||||
As described in [Default values](structs.md#default-values), the default value of a struct consists of the value that results from setting all value type fields to their default value and all reference type fields to `null`. For this reason, a struct does not permit instance field declarations to include variable initializers. This restriction applies only to instance fields. Static fields of a struct are permitted to include variable initializers.
|
||||
|
||||
The example
|
||||
```csharp
|
||||
struct Point
|
||||
{
|
||||
public int x = 1; // Error, initializer not permitted
|
||||
public int y = 1; // Error, initializer not permitted
|
||||
}
|
||||
```
|
||||
is in error because the instance field declarations include variable initializers.
|
||||
|
||||
### Constructors
|
||||
|
||||
Unlike a class, a struct is not permitted to declare a parameterless instance constructor. Instead, every struct implicitly has a parameterless instance constructor which always returns the value that results from setting all value type fields to their default value and all reference type fields to null ([Default constructors](types.md#default-constructors)). A struct can declare instance constructors having parameters. For example
|
||||
```csharp
|
||||
struct Point
|
||||
{
|
||||
int x, y;
|
||||
|
||||
public Point(int x, int y) {
|
||||
this.x = x;
|
||||
this.y = y;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Given the above declaration, the statements
|
||||
```csharp
|
||||
Point p1 = new Point();
|
||||
Point p2 = new Point(0, 0);
|
||||
```
|
||||
both create a `Point` with `x` and `y` initialized to zero.
|
||||
|
||||
A struct instance constructor is not permitted to include a constructor initializer of the form `base(...)`.
|
||||
|
||||
If the struct instance constructor doesn't specify a constructor initializer, the `this` variable corresponds to an `out` parameter of the struct type, and similar to an `out` parameter, `this` must be definitely assigned ([Definite assignment](variables.md#definite-assignment)) at every location where the constructor returns. If the struct instance constructor specifies a constructor initializer, the `this` variable corresponds to a `ref` parameter of the struct type, and similar to a `ref` parameter, `this` is considered definitely assigned on entry to the constructor body. Consider the instance constructor implementation below:
|
||||
```csharp
|
||||
struct Point
|
||||
{
|
||||
int x, y;
|
||||
|
||||
public int X {
|
||||
set { x = value; }
|
||||
}
|
||||
|
||||
public int Y {
|
||||
set { y = value; }
|
||||
}
|
||||
|
||||
public Point(int x, int y) {
|
||||
X = x; // error, this is not yet definitely assigned
|
||||
Y = y; // error, this is not yet definitely assigned
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
No instance member function (including the set accessors for the properties `X` and `Y`) can be called until all fields of the struct being constructed have been definitely assigned. The only exception involves automatically implemented properties ([Automatically implemented properties](classes.md#automatically-implemented-properties)). The definite assignment rules ([Simple assignment expressions](variables.md#simple-assignment-expressions)) specifically exempt assignment to an auto-property of a struct type within an instance constructor of that struct type: such an assignment is considered a definite assignment of the hidden backing field of the auto-property. Thus, the following is allowed:
|
||||
|
||||
```csharp
|
||||
struct Point
|
||||
{
|
||||
public int X { get; set; }
|
||||
public int Y { get; set; }
|
||||
|
||||
public Point(int x, int y) {
|
||||
X = x; // allowed, definitely assigns backing field
|
||||
Y = y; // allowed, definitely assigns backing field
|
||||
}
|
||||
```
|
||||
|
||||
### Destructors
|
||||
|
||||
A struct is not permitted to declare a destructor.
|
||||
|
||||
### Static constructors
|
||||
|
||||
Static constructors for structs follow most of the same rules as for classes. The execution of a static constructor for a struct type is triggered by the first of the following events to occur within an application domain:
|
||||
|
||||
* A static member of the struct type is referenced.
|
||||
* An explicitly declared constructor of the struct type is called.
|
||||
|
||||
The creation of default values ([Default values](structs.md#default-values)) of struct types does not trigger the static constructor. (An example of this is the initial value of elements in an array.)
|
||||
|
||||
## Struct examples
|
||||
|
||||
The following shows two significant examples of using `struct` types to create types that can be used similarly to the predefined types of the language, but with modified semantics.
|
||||
|
||||
### Database integer type
|
||||
|
||||
The `DBInt` struct below implements an integer type that can represent the complete set of values of the `int` type, plus an additional state that indicates an unknown value. A type with these characteristics is commonly used in databases.
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
public struct DBInt
|
||||
{
|
||||
// The Null member represents an unknown DBInt value.
|
||||
|
||||
public static readonly DBInt Null = new DBInt();
|
||||
|
||||
// When the defined field is true, this DBInt represents a known value
|
||||
// which is stored in the value field. When the defined field is false,
|
||||
// this DBInt represents an unknown value, and the value field is 0.
|
||||
|
||||
int value;
|
||||
bool defined;
|
||||
|
||||
// Private instance constructor. Creates a DBInt with a known value.
|
||||
|
||||
DBInt(int value) {
|
||||
this.value = value;
|
||||
this.defined = true;
|
||||
}
|
||||
|
||||
// The IsNull property is true if this DBInt represents an unknown value.
|
||||
|
||||
public bool IsNull { get { return !defined; } }
|
||||
|
||||
// The Value property is the known value of this DBInt, or 0 if this
|
||||
// DBInt represents an unknown value.
|
||||
|
||||
public int Value { get { return value; } }
|
||||
|
||||
// Implicit conversion from int to DBInt.
|
||||
|
||||
public static implicit operator DBInt(int x) {
|
||||
return new DBInt(x);
|
||||
}
|
||||
|
||||
// Explicit conversion from DBInt to int. Throws an exception if the
|
||||
// given DBInt represents an unknown value.
|
||||
|
||||
public static explicit operator int(DBInt x) {
|
||||
if (!x.defined) throw new InvalidOperationException();
|
||||
return x.value;
|
||||
}
|
||||
|
||||
public static DBInt operator +(DBInt x) {
|
||||
return x;
|
||||
}
|
||||
|
||||
public static DBInt operator -(DBInt x) {
|
||||
return x.defined ? -x.value : Null;
|
||||
}
|
||||
|
||||
public static DBInt operator +(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value + y.value: Null;
|
||||
}
|
||||
|
||||
public static DBInt operator -(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value - y.value: Null;
|
||||
}
|
||||
|
||||
public static DBInt operator *(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value * y.value: Null;
|
||||
}
|
||||
|
||||
public static DBInt operator /(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value / y.value: Null;
|
||||
}
|
||||
|
||||
public static DBInt operator %(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value % y.value: Null;
|
||||
}
|
||||
|
||||
public static DBBool operator ==(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value == y.value: DBBool.Null;
|
||||
}
|
||||
|
||||
public static DBBool operator !=(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value != y.value: DBBool.Null;
|
||||
}
|
||||
|
||||
public static DBBool operator >(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value > y.value: DBBool.Null;
|
||||
}
|
||||
|
||||
public static DBBool operator <(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value < y.value: DBBool.Null;
|
||||
}
|
||||
|
||||
public static DBBool operator >=(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value >= y.value: DBBool.Null;
|
||||
}
|
||||
|
||||
public static DBBool operator <=(DBInt x, DBInt y) {
|
||||
return x.defined && y.defined? x.value <= y.value: DBBool.Null;
|
||||
}
|
||||
|
||||
public override bool Equals(object obj) {
|
||||
if (!(obj is DBInt)) return false;
|
||||
DBInt x = (DBInt)obj;
|
||||
return value == x.value && defined == x.defined;
|
||||
}
|
||||
|
||||
public override int GetHashCode() {
|
||||
return value;
|
||||
}
|
||||
|
||||
public override string ToString() {
|
||||
return defined? value.ToString(): "DBInt.Null";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Database boolean type
|
||||
|
||||
The `DBBool` struct below implements a three-valued logical type. The possible values of this type are `DBBool.True`, `DBBool.False`, and `DBBool.Null`, where the `Null` member indicates an unknown value. Such three-valued logical types are commonly used in databases.
|
||||
|
||||
```csharp
|
||||
using System;
|
||||
|
||||
public struct DBBool
|
||||
{
|
||||
// The three possible DBBool values.
|
||||
|
||||
public static readonly DBBool Null = new DBBool(0);
|
||||
public static readonly DBBool False = new DBBool(-1);
|
||||
public static readonly DBBool True = new DBBool(1);
|
||||
|
||||
// Private field that stores -1, 0, 1 for False, Null, True.
|
||||
|
||||
sbyte value;
|
||||
|
||||
// Private instance constructor. The value parameter must be -1, 0, or 1.
|
||||
|
||||
DBBool(int value) {
|
||||
this.value = (sbyte)value;
|
||||
}
|
||||
|
||||
// Properties to examine the value of a DBBool. Return true if this
|
||||
// DBBool has the given value, false otherwise.
|
||||
|
||||
public bool IsNull { get { return value == 0; } }
|
||||
|
||||
public bool IsFalse { get { return value < 0; } }
|
||||
|
||||
public bool IsTrue { get { return value > 0; } }
|
||||
|
||||
// Implicit conversion from bool to DBBool. Maps true to DBBool.True and
|
||||
// false to DBBool.False.
|
||||
|
||||
public static implicit operator DBBool(bool x) {
|
||||
return x? True: False;
|
||||
}
|
||||
|
||||
// Explicit conversion from DBBool to bool. Throws an exception if the
|
||||
// given DBBool is Null, otherwise returns true or false.
|
||||
|
||||
public static explicit operator bool(DBBool x) {
|
||||
if (x.value == 0) throw new InvalidOperationException();
|
||||
return x.value > 0;
|
||||
}
|
||||
|
||||
// Equality operator. Returns Null if either operand is Null, otherwise
|
||||
// returns True or False.
|
||||
|
||||
public static DBBool operator ==(DBBool x, DBBool y) {
|
||||
if (x.value == 0 || y.value == 0) return Null;
|
||||
return x.value == y.value? True: False;
|
||||
}
|
||||
|
||||
// Inequality operator. Returns Null if either operand is Null, otherwise
|
||||
// returns True or False.
|
||||
|
||||
public static DBBool operator !=(DBBool x, DBBool y) {
|
||||
if (x.value == 0 || y.value == 0) return Null;
|
||||
return x.value != y.value? True: False;
|
||||
}
|
||||
|
||||
// Logical negation operator. Returns True if the operand is False, Null
|
||||
// if the operand is Null, or False if the operand is True.
|
||||
|
||||
public static DBBool operator !(DBBool x) {
|
||||
return new DBBool(-x.value);
|
||||
}
|
||||
|
||||
// Logical AND operator. Returns False if either operand is False,
|
||||
// otherwise Null if either operand is Null, otherwise True.
|
||||
|
||||
public static DBBool operator &(DBBool x, DBBool y) {
|
||||
return new DBBool(x.value < y.value? x.value: y.value);
|
||||
}
|
||||
|
||||
// Logical OR operator. Returns True if either operand is True, otherwise
|
||||
// Null if either operand is Null, otherwise False.
|
||||
|
||||
public static DBBool operator |(DBBool x, DBBool y) {
|
||||
return new DBBool(x.value > y.value? x.value: y.value);
|
||||
}
|
||||
|
||||
// Definitely true operator. Returns true if the operand is True, false
|
||||
// otherwise.
|
||||
|
||||
public static bool operator true(DBBool x) {
|
||||
return x.value > 0;
|
||||
}
|
||||
|
||||
// Definitely false operator. Returns true if the operand is False, false
|
||||
// otherwise.
|
||||
|
||||
public static bool operator false(DBBool x) {
|
||||
return x.value < 0;
|
||||
}
|
||||
|
||||
public override bool Equals(object obj) {
|
||||
if (!(obj is DBBool)) return false;
|
||||
return value == ((DBBool)obj).value;
|
||||
}
|
||||
|
||||
public override int GetHashCode() {
|
||||
return value;
|
||||
}
|
||||
|
||||
public override string ToString() {
|
||||
if (value > 0) return "DBBool.True";
|
||||
if (value < 0) return "DBBool.False";
|
||||
return "DBBool.Null";
|
||||
}
|
||||
}
|
||||
```
|
||||
663
spec/types.md
Normal file
663
spec/types.md
Normal file
|
|
@ -0,0 +1,663 @@
|
|||
# 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.
|
||||
|
||||
```antlr
|
||||
type
|
||||
: value_type
|
||||
| reference_type
|
||||
| type_parameter
|
||||
| type_unsafe
|
||||
;
|
||||
```
|
||||
|
||||
The final category of types, pointers, is available only in unsafe code. This is discussed further in [Pointer types](unsafe-code.md#pointer-types).
|
||||
|
||||
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 ([Boxing and unboxing](types.md#boxing-and-unboxing)).
|
||||
|
||||
## 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.
|
||||
|
||||
```antlr
|
||||
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 ([Sealed classes](classes.md#sealed-classes)).
|
||||
|
||||
Note that `System.ValueType` is not itself a *value_type*. Rather, it is a *class_type* from which all *value_type*s 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_type*s, the default value is the value produced by a bit pattern of all zeros:
|
||||
* For `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`, the default value is `0`.
|
||||
* For `char`, the default value is `'\x0000'`.
|
||||
* For `float`, the default value is `0.0f`.
|
||||
* For `double`, the default value is `0.0d`.
|
||||
* For `decimal`, the default value is `0.0m`.
|
||||
* 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.
|
||||
|
||||
```csharp
|
||||
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 ([Constructors](structs.md#constructors)).
|
||||
|
||||
### 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 [Struct declarations](structs.md#struct-declarations).
|
||||
|
||||
### 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:
|
||||
|
||||
```csharp
|
||||
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* ([Literals](lexical-structure.md#literals)). 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* ([Constant expressions](expressions.md#constant-expressions)). 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 ([Constants](classes.md#constants)). 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 ([Evaluation of user-defined conversions](conversions.md#evaluation-of-user-defined-conversions)).
|
||||
|
||||
### 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_literal*s or as *integer_literal*s 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 ([The checked and unchecked operators](expressions.md#the-checked-and-unchecked-operators)). 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 ([Division operator](expressions.md#division-operator)).
|
||||
* 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^24` and `-149 <= e <= 104`, and for `double`, `0 < m < 2^53` 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^-45` to `3.4 * 10^38` with a precision of 7 digits.
|
||||
|
||||
The `double` type can represent values ranging from approximately `5.0 * 10^-324` to `1.7 × 10^308` 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^-28` to approximately `7.9 * 10^28` 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^96`, 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 `decimal`s with an absolute value less than `1.0m`, the value is exact to the 28th decimal place, but no further. For `decimal`s 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 ([Enum declarations](enums.md#enum-declarations)).
|
||||
|
||||
### 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` ([Type parameter constraints](classes.md#type-parameter-constraints)), 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
|
||||
|
||||
```csharp
|
||||
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?` ([Null literal conversions](conversions.md#null-literal-conversions)) and from `T` to `T?` ([Implicit nullable conversions](conversions.md#implicit-nullable-conversions)).
|
||||
|
||||
## Reference types
|
||||
|
||||
A reference type is a class type, an interface type, an array type, or a delegate type.
|
||||
|
||||
```antlr
|
||||
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_specifier+
|
||||
;
|
||||
|
||||
non_array_type
|
||||
: type
|
||||
;
|
||||
|
||||
rank_specifier
|
||||
: '[' dim_separator* ']'
|
||||
;
|
||||
|
||||
dim_separator
|
||||
: ','
|
||||
;
|
||||
|
||||
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_expression*s ([Object creation expressions](expressions.md#object-creation-expressions)).
|
||||
|
||||
Class types are described in [Classes](classes.md#classes).
|
||||
|
||||
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 [The object type](types.md#the-object-type). |
|
||||
| `System.String` | The string type of the C# language. See [The string type](types.md#the-string-type). |
|
||||
| `System.ValueType` | The base class of all value types. See [The System.ValueType type](types.md#the-systemvaluetype-type). |
|
||||
| `System.Enum` | The base class of all enum types. See [Enums](enums.md#enums). |
|
||||
| `System.Array` | The base class of all array types. See [Arrays](arrays.md#arrays). |
|
||||
| `System.Delegate` | The base class of all delegate types. See [Delegates](delegates.md#delegates). |
|
||||
| `System.Exception` | The base class of all exception types. See [Exceptions](exceptions.md#exceptions). |
|
||||
|
||||
### 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.
|
||||
|
||||
Its purpose is to allow dynamic binding, which is described in detail in [Dynamic binding](expressions.md#dynamic-binding).
|
||||
|
||||
`dynamic` is considered identical to `object` except in the following respects:
|
||||
|
||||
* Operations on expressions of type `dynamic` can be dynamically bound ([Dynamic binding](expressions.md#dynamic-binding)).
|
||||
* Type inference ([Type inference](expressions.md#type-inference)) will prefer `dynamic` over `object` if both are candidates.
|
||||
|
||||
Because of this equivalence, the following holds:
|
||||
|
||||
* There is an implicit identity conversion between `object` and `dynamic`, and between constructed types that are the same when replacing `dynamic` with `object`
|
||||
* Implicit and explicit conversions to and from `object` also apply to and from `dynamic`.
|
||||
* Method signatures that are the same when replacing `dynamic` with `object` are considered the same signature
|
||||
* The type `dynamic` is indistinguishable from `object` at run-time.
|
||||
* An expression of the type `dynamic` is referred to as a ***dynamic expression***.
|
||||
|
||||
### 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 ([String literals](lexical-structure.md#string-literals)).
|
||||
|
||||
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 [Interfaces](interfaces.md#interfaces).
|
||||
|
||||
### 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 [Arrays](arrays.md#arrays).
|
||||
|
||||
### 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 [Delegates](delegates.md#delegates).
|
||||
|
||||
## Boxing and unboxing
|
||||
|
||||
The concept of boxing and unboxing is central to C#'s type system. It provides a bridge between *value_type*s and *reference_type*s by permitting any value of a *value_type* to be converted to and from type `object`. Boxing and unboxing enables a unified view of the type system wherein a value of any type can ultimately be treated as an object.
|
||||
|
||||
### Boxing conversions
|
||||
|
||||
A boxing conversion permits a *value_type* to be implicitly converted to a *reference_type*. The following boxing conversions exist:
|
||||
|
||||
* From any *value_type* to the type `object`.
|
||||
* From any *value_type* to the type `System.ValueType`.
|
||||
* From any *non_nullable_value_type* to any *interface_type* implemented by the *value_type*.
|
||||
* From any *nullable_type* to any *interface_type* implemented by the underlying type of the *nullable_type*.
|
||||
* From any *enum_type* to the type `System.Enum`.
|
||||
* From any *nullable_type* with an underlying *enum_type* to the type `System.Enum`.
|
||||
* Note that an implicit conversion from a type parameter will be executed as a boxing conversion if at run-time it ends up converting from a value type to a reference type ([Implicit conversions involving type parameters](conversions.md#implicit-conversions-involving-type-parameters)).
|
||||
|
||||
Boxing a value of a *non_nullable_value_type* consists of allocating an object instance and copying the *non_nullable_value_type* value into that instance.
|
||||
|
||||
Boxing a value of a *nullable_type* produces a null reference if it is the `null` value (`HasValue` is `false`), or the result of unwrapping and boxing the underlying value otherwise.
|
||||
|
||||
The actual process of boxing a value of a *non_nullable_value_type* is best explained by imagining the existence of a generic ***boxing class***, which behaves as if it were declared as follows:
|
||||
|
||||
```csharp
|
||||
sealed class Box<T>: System.ValueType
|
||||
{
|
||||
T value;
|
||||
|
||||
public Box(T t) {
|
||||
value = t;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Boxing of a value `v` of type `T` now consists of executing the expression `new Box<T>(v)`, and returning the resulting instance as a value of type `object`. Thus, the statements
|
||||
```csharp
|
||||
int i = 123;
|
||||
object box = i;
|
||||
```
|
||||
conceptually correspond to
|
||||
```csharp
|
||||
int i = 123;
|
||||
object box = new Box<int>(i);
|
||||
```
|
||||
|
||||
A boxing class like `Box<T>` above doesn't actually exist and the dynamic type of a boxed value isn't actually a class type. Instead, a boxed value of type `T` has the dynamic type `T`, and a dynamic type check using the `is` operator can simply reference type `T`. For example,
|
||||
```csharp
|
||||
int i = 123;
|
||||
object box = i;
|
||||
if (box is int) {
|
||||
Console.Write("Box contains an int");
|
||||
}
|
||||
```
|
||||
will output the string "`Box contains an int`" on the console.
|
||||
|
||||
A boxing conversion implies making a copy of the value being boxed. This is different from a conversion of a *reference_type* to type `object`, in which the value continues to reference the same instance and simply is regarded as the less derived type `object`. For example, given the declaration
|
||||
```csharp
|
||||
struct Point
|
||||
{
|
||||
public int x, y;
|
||||
|
||||
public Point(int x, int y) {
|
||||
this.x = x;
|
||||
this.y = y;
|
||||
}
|
||||
}
|
||||
```
|
||||
the following statements
|
||||
```csharp
|
||||
Point p = new Point(10, 10);
|
||||
object box = p;
|
||||
p.x = 20;
|
||||
Console.Write(((Point)box).x);
|
||||
```
|
||||
will output the value 10 on the console because the implicit boxing operation that occurs in the assignment of `p` to `box` causes the value of `p` to be copied. Had `Point` been declared a `class` instead, the value 20 would be output because `p` and `box` would reference the same instance.
|
||||
|
||||
### Unboxing conversions
|
||||
|
||||
An unboxing conversion permits a *reference_type* to be explicitly converted to a *value_type*. The following unboxing conversions exist:
|
||||
|
||||
* From the type `object` to any *value_type*.
|
||||
* From the type `System.ValueType` to any *value_type*.
|
||||
* From any *interface_type* to any *non_nullable_value_type* that implements the *interface_type*.
|
||||
* From any *interface_type* to any *nullable_type* whose underlying type implements the *interface_type*.
|
||||
* From the type `System.Enum` to any *enum_type*.
|
||||
* From the type `System.Enum` to any *nullable_type* with an underlying *enum_type*.
|
||||
* Note that an explicit conversion to a type parameter will be executed as an unboxing conversion if at run-time it ends up converting from a reference type to a value type ([Explicit dynamic conversions](conversions.md#explicit-dynamic-conversions)).
|
||||
|
||||
An unboxing operation to a *non_nullable_value_type* consists of first checking that the object instance is a boxed value of the given *non_nullable_value_type*, and then copying the value out of the instance.
|
||||
|
||||
Unboxing to a *nullable_type* produces the null value of the *nullable_type* if the source operand is `null`, or the wrapped result of unboxing the object instance to the underlying type of the *nullable_type* otherwise.
|
||||
|
||||
Referring to the imaginary boxing class described in the previous section, an unboxing conversion of an object `box` to a *value_type* `T` consists of executing the expression `((Box<T>)box).value`. Thus, the statements
|
||||
```csharp
|
||||
object box = 123;
|
||||
int i = (int)box;
|
||||
```
|
||||
conceptually correspond to
|
||||
```csharp
|
||||
object box = new Box<int>(123);
|
||||
int i = ((Box<int>)box).value;
|
||||
```
|
||||
|
||||
For an unboxing conversion to a given *non_nullable_value_type* to succeed at run-time, the value of the source operand must be a reference to a boxed value of that *non_nullable_value_type*. If the source operand is `null`, a `System.NullReferenceException` is thrown. If the source operand is a reference to an incompatible object, a `System.InvalidCastException` is thrown.
|
||||
|
||||
For an unboxing conversion to a given *nullable_type* to succeed at run-time, the value of the source operand must be either `null` or a reference to a boxed value of the underlying *non_nullable_value_type* of the *nullable_type*. If the source operand is a reference to an incompatible object, a `System.InvalidCastException` is thrown.
|
||||
|
||||
## Constructed types
|
||||
|
||||
A generic type declaration, by itself, denotes an ***unbound generic type*** that is used as a "blueprint" to form many different types, by way of applying ***type arguments***. The type arguments are written within angle brackets (`<` and `>`) immediately following the name of the generic type. A type that includes at least one type argument is called a ***constructed type***. A constructed type can be used in most places in the language in which a type name can appear. An unbound generic type can only be used within a *typeof_expression* ([The typeof operator](expressions.md#the-typeof-operator)).
|
||||
|
||||
Constructed types can also be used in expressions as simple names ([Simple names](expressions.md#simple-names)) or when accessing a member ([Member access](expressions.md#member-access)).
|
||||
|
||||
When a *namespace_or_type_name* is evaluated, only generic types with the correct number of type parameters are considered. Thus, it is possible to use the same identifier to identify different types, as long as the types have different numbers of type parameters. This is useful when mixing generic and non-generic classes in the same program:
|
||||
|
||||
```csharp
|
||||
namespace Widgets
|
||||
{
|
||||
class Queue {...}
|
||||
class Queue<TElement> {...}
|
||||
}
|
||||
|
||||
namespace MyApplication
|
||||
{
|
||||
using Widgets;
|
||||
|
||||
class X
|
||||
{
|
||||
Queue q1; // Non-generic Widgets.Queue
|
||||
Queue<int> q2; // Generic Widgets.Queue
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A *type_name* might identify a constructed type even though it doesn't specify type parameters directly. This can occur where a type is nested within a generic class declaration, and the instance type of the containing declaration is implicitly used for name lookup ([Nested types in generic classes](classes.md#nested-types-in-generic-classes)):
|
||||
|
||||
```csharp
|
||||
class Outer<T>
|
||||
{
|
||||
public class Inner {...}
|
||||
|
||||
public Inner i; // Type of i is Outer<T>.Inner
|
||||
}
|
||||
```
|
||||
|
||||
In unsafe code, a constructed type cannot be used as an *unmanaged_type* ([Pointer types](unsafe-code.md#pointer-types)).
|
||||
|
||||
### Type arguments
|
||||
|
||||
Each argument in a type argument list is simply a *type*.
|
||||
|
||||
```antlr
|
||||
type_argument_list
|
||||
: '<' type_arguments '>'
|
||||
;
|
||||
|
||||
type_arguments
|
||||
: type_argument (',' type_argument)*
|
||||
;
|
||||
|
||||
type_argument
|
||||
: type
|
||||
;
|
||||
```
|
||||
|
||||
In unsafe code ([Unsafe code](unsafe-code.md#unsafe-code)), a *type_argument* may not be a pointer type. Each type argument must satisfy any constraints on the corresponding type parameter ([Type parameter constraints](classes.md#type-parameter-constraints)).
|
||||
|
||||
### Open and closed types
|
||||
|
||||
All types can be classified as either ***open types*** or ***closed types***. An open type is a type that involves type parameters. More specifically:
|
||||
|
||||
* A type parameter defines an open type.
|
||||
* An array type is an open type if and only if its element type is an open type.
|
||||
* A constructed type is an open type if and only if one or more of its type arguments is an open type. A constructed nested type is an open type if and only if one or more of its type arguments or the type arguments of its containing type(s) is an open type.
|
||||
|
||||
A closed type is a type that is not an open type.
|
||||
|
||||
At run-time, all of the code within a generic type declaration is executed in the context of a closed constructed type that was created by applying type arguments to the generic declaration. Each type parameter within the generic type is bound to a particular run-time type. The run-time processing of all statements and expressions always occurs with closed types, and open types occur only during compile-time processing.
|
||||
|
||||
Each closed constructed type has its own set of static variables, which are not shared with any other closed constructed types. Since an open type does not exist at run-time, there are no static variables associated with an open type. Two closed constructed types are the same type if they are constructed from the same unbound generic type, and their corresponding type arguments are the same type.
|
||||
|
||||
### Bound and unbound types
|
||||
|
||||
The term ***unbound type*** refers to a non-generic type or an unbound generic type. The term ***bound type*** refers to a non-generic type or a constructed type.
|
||||
|
||||
An unbound type refers to the entity declared by a type declaration. An unbound generic type is not itself a type, and cannot be used as the type of a variable, argument or return value, or as a base type. The only construct in which an unbound generic type can be referenced is the `typeof` expression ([The typeof operator](expressions.md#the-typeof-operator)).
|
||||
|
||||
### Satisfying constraints
|
||||
|
||||
Whenever a constructed type or generic method is referenced, the supplied type arguments are checked against the type parameter constraints declared on the generic type or method ([Type parameter constraints](classes.md#type-parameter-constraints)). For each `where` clause, the type argument `A` that corresponds to the named type parameter is checked against each constraint as follows:
|
||||
|
||||
* If the constraint is a class type, an interface type, or a type parameter, let `C` represent that constraint with the supplied type arguments substituted for any type parameters that appear in the constraint. To satisfy the constraint, it must be the case that type `A` is convertible to type `C` by one of the following:
|
||||
* An identity conversion ([Identity conversion](conversions.md#identity-conversion))
|
||||
* An implicit reference conversion ([Implicit reference conversions](conversions.md#implicit-reference-conversions))
|
||||
* A boxing conversion ([Boxing conversions](conversions.md#boxing-conversions)), provided that type A is a non-nullable value type.
|
||||
* An implicit reference, boxing or type parameter conversion from a type parameter `A` to `C`.
|
||||
* If the constraint is the reference type constraint (`class`), the type `A` must satisfy one of the following:
|
||||
* `A` is an interface type, class type, delegate type or array type. Note that `System.ValueType` and `System.Enum` are reference types that satisfy this constraint.
|
||||
* `A` is a type parameter that is known to be a reference type ([Type parameter constraints](classes.md#type-parameter-constraints)).
|
||||
* If the constraint is the value type constraint (`struct`), the type `A` must satisfy one of the following:
|
||||
* `A` is a struct type or enum type, but not a nullable type. Note that `System.ValueType` and `System.Enum` are reference types that do not satisfy this constraint.
|
||||
* `A` is a type parameter having the value type constraint ([Type parameter constraints](classes.md#type-parameter-constraints)).
|
||||
* If the constraint is the constructor constraint `new()`, the type `A` must not be `abstract` and must have a public parameterless constructor. This is satisfied if one of the following is true:
|
||||
* `A` is a value type, since all value types have a public default constructor ([Default constructors](types.md#default-constructors)).
|
||||
* `A` is a type parameter having the constructor constraint ([Type parameter constraints](classes.md#type-parameter-constraints)).
|
||||
* `A` is a type parameter having the value type constraint ([Type parameter constraints](classes.md#type-parameter-constraints)).
|
||||
* `A` is a class that is not `abstract` and contains an explicitly declared `public` constructor with no parameters.
|
||||
* `A` is not `abstract` and has a default constructor ([Default constructors](classes.md#default-constructors)).
|
||||
|
||||
A compile-time error occurs if one or more of a type parameter's constraints are not satisfied by the given type arguments.
|
||||
|
||||
Since type parameters are not inherited, constraints are never inherited either. In the example below, `D` needs to specify the constraint on its type parameter `T` so that `T` satisfies the constraint imposed by the base class `B<T>`. In contrast, class `E` need not specify a constraint, because `List<T>` implements `IEnumerable` for any `T`.
|
||||
|
||||
```csharp
|
||||
class B<T> where T: IEnumerable {...}
|
||||
|
||||
class D<T>: B<T> where T: IEnumerable {...}
|
||||
|
||||
class E<T>: B<List<T>> {...}
|
||||
```
|
||||
|
||||
## Type parameters
|
||||
|
||||
A type parameter is an identifier designating a value type or reference type that the parameter is bound to at run-time.
|
||||
|
||||
```antlr
|
||||
type_parameter
|
||||
: identifier
|
||||
;
|
||||
```
|
||||
|
||||
Since a type parameter can be instantiated with many different actual type arguments, type parameters have slightly different operations and restrictions than other types. These include:
|
||||
|
||||
* A type parameter cannot be used directly to declare a base class ([Base class](classes.md#base-class)) or interface ([Variant type parameter lists](interfaces.md#variant-type-parameter-lists)).
|
||||
* The rules for member lookup on type parameters depend on the constraints, if any, applied to the type parameter. They are detailed in [Member lookup](expressions.md#member-lookup).
|
||||
* The available conversions for a type parameter depend on the constraints, if any, applied to the type parameter. They are detailed in [Implicit conversions involving type parameters](conversions.md#implicit-conversions-involving-type-parameters) and [Explicit dynamic conversions](conversions.md#explicit-dynamic-conversions).
|
||||
* The literal `null` cannot be converted to a type given by a type parameter, except if the type parameter is known to be a reference type ([Implicit conversions involving type parameters](conversions.md#implicit-conversions-involving-type-parameters)). However, a `default` expression ([Default value expressions](expressions.md#default-value-expressions)) can be used instead. In addition, a value with a type given by a type parameter can be compared with `null` using `==` and `!=` ([Reference type equality operators](expressions.md#reference-type-equality-operators)) unless the type parameter has the value type constraint.
|
||||
* A `new` expression ([Object creation expressions](expressions.md#object-creation-expressions)) can only be used with a type parameter if the type parameter is constrained by a *constructor_constraint* or the value type constraint ([Type parameter constraints](classes.md#type-parameter-constraints)).
|
||||
* A type parameter cannot be used anywhere within an attribute.
|
||||
* A type parameter cannot be used in a member access ([Member access](expressions.md#member-access)) or type name ([Namespace and type names](basic-concepts.md#namespace-and-type-names)) to identify a static member or a nested type.
|
||||
* In unsafe code, a type parameter cannot be used as an *unmanaged_type* ([Pointer types](unsafe-code.md#pointer-types)).
|
||||
|
||||
As a type, type parameters are purely a compile-time construct. At run-time, each type parameter is bound to a run-time type that was specified by supplying a type argument to the generic type declaration. Thus, the type of a variable declared with a type parameter will, at run-time, be a closed constructed type ([Open and closed types](types.md#open-and-closed-types)). The run-time execution of all statements and expressions involving type parameters uses the actual type that was supplied as the type argument for that parameter.
|
||||
|
||||
## Expression tree types
|
||||
|
||||
***Expression trees*** permit lambda expressions to be represented as data structures instead of executable code. Expression trees are values of ***expression tree types*** of the form `System.Linq.Expressions.Expression<D>`, where `D` is any delegate type. For the remainder of this specification we will refer to these types using the shorthand `Expression<D>`.
|
||||
|
||||
If a conversion exists from a lambda expression to a delegate type `D`, a conversion also exists to the expression tree type `Expression<D>`. Whereas the conversion of a lambda expression to a delegate type generates a delegate that references executable code for the lambda expression, conversion to an expression tree type creates an expression tree representation of the lambda expression.
|
||||
|
||||
Expression trees are efficient in-memory data representations of lambda expressionsand make the structure of the lambda expressiontransparent and explicit.
|
||||
|
||||
Just like a delegate type `D`, `Expression<D>` is said to have parameter and return types, which are the same as those of `D`.
|
||||
|
||||
The following example represents a lambda expressionboth as executable code and as an expression tree. Because a conversion exists to `Func<int,int>`, a conversion also exists to `Expression<Func<int,int>>`:
|
||||
|
||||
```csharp
|
||||
Func<int,int> del = x => x + 1; // Code
|
||||
|
||||
Expression<Func<int,int>> exp = x => x + 1; // Data
|
||||
```
|
||||
|
||||
Following these assignments, the delegate `del` references a method that returns `x + 1`, and the expression tree `exp` references a data structure that describes the expression `x => x + 1`.
|
||||
|
||||
The exact definition of the generic type `Expression<D>` as well as the precise rules for constructing an expression tree when a lambda expressionis converted to an expression tree type, are both outside the scope of this specification.
|
||||
|
||||
Two things are important to make explicit:
|
||||
|
||||
* Not all lambda expressions can be converted to expression trees. For instance, lambda expressions with statement bodies, and lambda expressions containing assignment expressions cannot be represented. In these cases, a conversion still exists, but will fail at compile-time. These exceptions are detailed in [Anonymous function conversions](conversions.md#anonymous-function-conversions).
|
||||
* `Expression<D>` offers an instance method `Compile` which produces a delegate of type `D`:
|
||||
|
||||
```csharp
|
||||
Func<int,int> del2 = exp.Compile();
|
||||
```
|
||||
|
||||
Invoking this delegate causes the code represented by the expression tree to be executed. Thus, given the definitions above, del and del2 are equivalent, and the following two statements will have the same effect:
|
||||
|
||||
```csharp
|
||||
int i1 = del(1);
|
||||
|
||||
int i2 = del2(1);
|
||||
```
|
||||
|
||||
After executing this code, `i1` and `i2` will both have the value `2`.
|
||||
|
||||
1137
spec/unsafe-code.md
Normal file
1137
spec/unsafe-code.md
Normal file
File diff suppressed because it is too large
Load diff
642
spec/variables.md
Normal file
642
spec/variables.md
Normal file
|
|
@ -0,0 +1,642 @@
|
|||
# Variables
|
||||
|
||||
Variables represent storage locations. Every variable has a type that determines what values can be stored in the variable. C# is a type-safe language, and the C# compiler guarantees that values stored in variables are always of the appropriate type. The value of a variable can be changed through assignment or through use of the `++` and `--` operators.
|
||||
|
||||
A variable must be ***definitely assigned*** ([Definite assignment](variables.md#definite-assignment)) before its value can be obtained.
|
||||
|
||||
As described in the following sections, variables are either ***initially assigned*** or ***initially unassigned***. An initially assigned variable has a well-defined initial value and is always considered definitely assigned. An initially unassigned variable has no initial value. For an initially unassigned variable to be considered definitely assigned at a certain location, an assignment to the variable must occur in every possible execution path leading to that location.
|
||||
|
||||
## Variable categories
|
||||
|
||||
C# defines seven categories of variables: static variables, instance variables, array elements, value parameters, reference parameters, output parameters, and local variables. The sections that follow describe each of these categories.
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
class A
|
||||
{
|
||||
public static int x;
|
||||
int y;
|
||||
|
||||
void F(int[] v, int a, ref int b, out int c) {
|
||||
int i = 1;
|
||||
c = a + b++;
|
||||
}
|
||||
}
|
||||
```
|
||||
`x` is a static variable, `y` is an instance variable, `v[0]` is an array element, `a` is a value parameter, `b` is a reference parameter, `c` is an output parameter, and `i` is a local variable.
|
||||
|
||||
### Static variables
|
||||
|
||||
A field declared with the `static` modifier is called a ***static variable***. A static variable comes into existence before execution of the static constructor ([Static constructors](classes.md#static-constructors)) for its containing type, and ceases to exist when the associated application domain ceases to exist.
|
||||
|
||||
The initial value of a static variable is the default value ([Default values](variables.md#default-values)) of the variable's type.
|
||||
|
||||
For purposes of definite assignment checking, a static variable is considered initially assigned.
|
||||
|
||||
### Instance variables
|
||||
|
||||
A field declared without the `static` modifier is called an ***instance variable***.
|
||||
|
||||
#### Instance variables in classes
|
||||
|
||||
An instance variable of a class comes into existence when a new instance of that class is created, and ceases to exist when there are no references to that instance and the instance's destructor (if any) has executed.
|
||||
|
||||
The initial value of an instance variable of a class is the default value ([Default values](variables.md#default-values)) of the variable's type.
|
||||
|
||||
For the purpose of definite assignment checking, an instance variable of a class is considered initially assigned.
|
||||
|
||||
#### Instance variables in structs
|
||||
|
||||
An instance variable of a struct has exactly the same lifetime as the struct variable to which it belongs. In other words, when a variable of a struct type comes into existence or ceases to exist, so too do the instance variables of the struct.
|
||||
|
||||
The initial assignment state of an instance variable of a struct is the same as that of the containing struct variable. In other words, when a struct variable is considered initially assigned, so too are its instance variables, and when a struct variable is considered initially unassigned, its instance variables are likewise unassigned.
|
||||
|
||||
### Array elements
|
||||
|
||||
The elements of an array come into existence when an array instance is created, and cease to exist when there are no references to that array instance.
|
||||
|
||||
The initial value of each of the elements of an array is the default value ([Default values](variables.md#default-values)) of the type of the array elements.
|
||||
|
||||
For the purpose of definite assignment checking, an array element is considered initially assigned.
|
||||
|
||||
### Value parameters
|
||||
|
||||
A parameter declared without a `ref` or `out` modifier is a ***value parameter***.
|
||||
|
||||
A value parameter comes into existence upon invocation of the function member (method, instance constructor, accessor, or operator) or anonymous function to which the parameter belongs, and is initialized with the value of the argument given in the invocation. A value parameter normally ceases to exist upon return of the function member or anonymous function. However, if the value parameter is captured by an anonymous function ([Anonymous function expressions](expressions.md#anonymous-function-expressions)), its life time extends at least until the delegate or expression tree created from that anonymous function is eligible for garbage collection.
|
||||
|
||||
For the purpose of definite assignment checking, a value parameter is considered initially assigned.
|
||||
|
||||
### Reference parameters
|
||||
|
||||
A parameter declared with a `ref` modifier is a ***reference parameter***.
|
||||
|
||||
A reference parameter does not create a new storage location. Instead, a reference parameter represents the same storage location as the variable given as the argument in the function member or anonymous function invocation. Thus, the value of a reference parameter is always the same as the underlying variable.
|
||||
|
||||
The following definite assignment rules apply to reference parameters. Note the different rules for output parameters described in [Output parameters](variables.md#output-parameters).
|
||||
|
||||
* A variable must be definitely assigned ([Definite assignment](variables.md#definite-assignment)) before it can be passed as a reference parameter in a function member or delegate invocation.
|
||||
* Within a function member or anonymous function, a reference parameter is considered initially assigned.
|
||||
|
||||
Within an instance method or instance accessor of a struct type, the `this` keyword behaves exactly as a reference parameter of the struct type ([This access](expressions.md#this-access)).
|
||||
|
||||
### Output parameters
|
||||
|
||||
A parameter declared with an `out` modifier is an ***output parameter***.
|
||||
|
||||
An output parameter does not create a new storage location. Instead, an output parameter represents the same storage location as the variable given as the argument in the function member or delegate invocation. Thus, the value of an output parameter is always the same as the underlying variable.
|
||||
|
||||
The following definite assignment rules apply to output parameters. Note the different rules for reference parameters described in [Reference parameters](variables.md#reference-parameters).
|
||||
|
||||
* A variable need not be definitely assigned before it can be passed as an output parameter in a function member or delegate invocation.
|
||||
* Following the normal completion of a function member or delegate invocation, each variable that was passed as an output parameter is considered assigned in that execution path.
|
||||
* Within a function member or anonymous function, an output parameter is considered initially unassigned.
|
||||
* Every output parameter of a function member or anonymous function must be definitely assigned ([Definite assignment](variables.md#definite-assignment)) before the function member or anonymous function returns normally.
|
||||
|
||||
Within an instance constructor of a struct type, the `this` keyword behaves exactly as an output parameter of the struct type ([This access](expressions.md#this-access)).
|
||||
|
||||
### Local variables
|
||||
|
||||
A ***local variable*** is declared by a *local_variable_declaration*, which may occur in a *block*, a *for_statement*, a *switch_statement* or a *using_statement*; or by a *foreach_statement* or a *specific_catch_clause* for a *try_statement*.
|
||||
|
||||
The lifetime of a local variable is the portion of program execution during which storage is guaranteed to be reserved for it. This lifetime extends at least from entry into the *block*, *for_statement*, *switch_statement*, *using_statement*, *foreach_statement*, or *specific_catch_clause* with which it is associated, until execution of that *block*, *for_statement*, *switch_statement*, *using_statement*, *foreach_statement*, or *specific_catch_clause* ends in any way. (Entering an enclosed *block* or calling a method suspends, but does not end, execution of the current *block*, *for_statement*, *switch_statement*, *using_statement*, *foreach_statement*, or *specific_catch_clause*.) If the local variable is captured by an anonymous function ([Captured outer variables](expressions.md#captured-outer-variables)), its lifetime extends at least until the delegate or expression tree created from the anonymous function, along with any other objects that come to reference the captured variable, are eligible for garbage collection.
|
||||
|
||||
If the parent *block*, *for_statement*, *switch_statement*, *using_statement*, *foreach_statement*, or *specific_catch_clause* is entered recursively, a new instance of the local variable is created each time, and its *local_variable_initializer*, if any, is evaluated each time.
|
||||
|
||||
A local variable introduced by a *local_variable_declaration* is not automatically initialized and thus has no default value. For the purpose of definite assignment checking, a local variable introduced by a *local_variable_declaration* is considered initially unassigned. A *local_variable_declaration* may include a *local_variable_initializer*, in which case the variable is considered definitely assigned only after the initializing expression ([Declaration statements](variables.md#declaration-statements)).
|
||||
|
||||
Within the scope of a local variableintroduced by a *local_variable_declaration*, it is a compile-time error to refer to that local variable in a textual position that precedes its *local_variable_declarator*. If the local variable declaration is implicit ([Local variable declarations](statements.md#local-variable-declarations)), it is also an error to refer to the variable within its *local_variable_declarator*.
|
||||
|
||||
A local variable introduced by a *foreach_statement* or a *specific_catch_clause* is considered definitely assigned in its entire scope.
|
||||
|
||||
The actual lifetime of a local variable is implementation-dependent. For example, a compiler might statically determine that a local variable in a block is only used for a small portion of that block. Using this analysis, the compiler could generate code that results in the variable's storage having a shorter lifetime than its containing block.
|
||||
|
||||
The storage referred to by a local reference variable is reclaimed independently of the lifetime of that local reference variable ([Automatic memory management](basic-concepts.md#automatic-memory-management)).
|
||||
|
||||
## Default values
|
||||
|
||||
The following categories of variables are automatically initialized to their default values:
|
||||
|
||||
* Static variables.
|
||||
* Instance variables of class instances.
|
||||
* Array elements.
|
||||
|
||||
The default value of a variable depends on the type of the variable and is determined as follows:
|
||||
|
||||
* For a variable of a *value_type*, the default value is the same as the value computed by the *value_type*'s default constructor ([Default constructors](types.md#default-constructors)).
|
||||
* For a variable of a *reference_type*, the default value is `null`.
|
||||
|
||||
Initialization to default values is typically done by having the memory manager or garbage collector initialize memory to all-bits-zero before it is allocated for use. For this reason, it is convenient to use all-bits-zero to represent the null reference.
|
||||
|
||||
## Definite assignment
|
||||
|
||||
At a given location in the executable code of a function member, a variable is said to be ***definitely assigned*** if the compiler can prove, by a particular static flow analysis ([Precise rules for determining definite assignment](variables.md#precise-rules-for-determining-definite-assignment)), that the variable has been automatically initialized or has been the target of at least one assignment. Informally stated, the rules of definite assignment are:
|
||||
|
||||
* An initially assigned variable ([Initially assigned variables](variables.md#initially-assigned-variables)) is always considered definitely assigned.
|
||||
* An initially unassigned variable ([Initially unassigned variables](variables.md#initially-unassigned-variables)) is considered definitely assigned at a given location if all possible execution paths leading to that location contain at least one of the following:
|
||||
* A simple assignment ([Simple assignment](expressions.md#simple-assignment)) in which the variable is the left operand.
|
||||
* An invocation expression ([Invocation expressions](expressions.md#invocation-expressions)) or object creation expression ([Object creation expressions](expressions.md#object-creation-expressions)) that passes the variable as an output parameter.
|
||||
* For a local variable, a local variable declaration ([Local variable declarations](statements.md#local-variable-declarations)) that includes a variable initializer.
|
||||
|
||||
The formal specification underlying the above informal rules is described in [Initially assigned variables](variables.md#initially-assigned-variables), [Initially unassigned variables](variables.md#initially-unassigned-variables), and [Precise rules for determining definite assignment](variables.md#precise-rules-for-determining-definite-assignment).
|
||||
|
||||
The definite assignment states of instance variables of a *struct_type* variable are tracked individually as well as collectively. In additional to the rules above, the following rules apply to *struct_type* variables and their instance variables:
|
||||
|
||||
* An instance variable is considered definitely assigned if its containing *struct_type* variable is considered definitely assigned.
|
||||
* A *struct_type* variable is considered definitely assigned if each of its instance variables is considered definitely assigned.
|
||||
|
||||
Definite assignment is a requirement in the following contexts:
|
||||
|
||||
* A variable must be definitely assigned at each location where its value is obtained. This ensures that undefined values never occur. The occurrence of a variable in an expression is considered to obtain the value of the variable, except when
|
||||
* the variable is the left operand of a simple assignment,
|
||||
* the variable is passed as an output parameter, or
|
||||
* the variable is a *struct_type* variable and occurs as the left operand of a member access.
|
||||
* A variable must be definitely assigned at each location where it is passed as a reference parameter. This ensures that the function member being invoked can consider the reference parameter initially assigned.
|
||||
* All output parameters of a function member must be definitely assigned at each location where the function member returns (through a `return` statement or through execution reaching the end of the function member body). This ensures that function members do not return undefined values in output parameters, thus enabling the compiler to consider a function member invocation that takes a variable as an output parameter equivalent to an assignment to the variable.
|
||||
* The `this` variable of a *struct_type* instance constructor must be definitely assigned at each location where that instance constructor returns.
|
||||
|
||||
### Initially assigned variables
|
||||
|
||||
The following categories of variables are classified as initially assigned:
|
||||
|
||||
* Static variables.
|
||||
* Instance variables of class instances.
|
||||
* Instance variables of initially assigned struct variables.
|
||||
* Array elements.
|
||||
* Value parameters.
|
||||
* Reference parameters.
|
||||
* Variables declared in a `catch` clause or a `foreach` statement.
|
||||
|
||||
### Initially unassigned variables
|
||||
|
||||
The following categories of variables are classified as initially unassigned:
|
||||
|
||||
* Instance variables of initially unassigned struct variables.
|
||||
* Output parameters, including the `this` variable of struct instance constructors.
|
||||
* Local variables, except those declared in a `catch` clause or a `foreach` statement.
|
||||
|
||||
### Precise rules for determining definite assignment
|
||||
|
||||
In order to determine that each used variable is definitely assigned, the compiler must use a process that is equivalent to the one described in this section.
|
||||
|
||||
The compiler processes the body of each function member that has one or more initially unassigned variables. For each initially unassigned variable *v*, the compiler determines a ***definite assignment state*** for *v* at each of the following points in the function member:
|
||||
|
||||
* At the beginning of each statement
|
||||
* At the end point ([End points and reachability](statements.md#end-points-and-reachability)) of each statement
|
||||
* On each arc which transfers control to another statement or to the end point of a statement
|
||||
* At the beginning of each expression
|
||||
* At the end of each expression
|
||||
|
||||
The definite assignment state of *v* can be either:
|
||||
|
||||
* Definitely assigned. This indicates that on all possible control flows to this point, *v* has been assigned a value.
|
||||
* Not definitely assigned. For the state of a variable at the end of an expression of type `bool`, the state of a variable that isn't definitely assigned may (but doesn't necessarily) fall into one of the following sub-states:
|
||||
* Definitely assigned after true expression. This state indicates that *v* is definitely assigned if the boolean expression evaluated as true, but is not necessarily assigned if the boolean expression evaluated as false.
|
||||
* Definitely assigned after false expression. This state indicates that *v* is definitely assigned if the boolean expression evaluated as false, but is not necessarily assigned if the boolean expression evaluated as true.
|
||||
|
||||
The following rules govern how the state of a variable *v* is determined at each location.
|
||||
|
||||
#### General rules for statements
|
||||
|
||||
* *v* is not definitely assigned at the beginning of a function member body.
|
||||
* *v* is definitely assigned at the beginning of any unreachable statement.
|
||||
* The definite assignment state of *v* at the beginning of any other statement is determined by checking the definite assignment state of *v* on all control flow transfers that target the beginning of that statement. If (and only if) *v* is definitely assigned on all such control flow transfers, then *v* is definitely assigned at the beginning of the statement. The set of possible control flow transfers is determined in the same way as for checking statement reachability ([End points and reachability](statements.md#end-points-and-reachability)).
|
||||
* The definite assignment state of *v* at the end point of a block, `checked`, `unchecked`, `if`, `while`, `do`, `for`, `foreach`, `lock`, `using`, or `switch` statement is determined by checking the definite assignment state of *v* on all control flow transfers that target the end point of that statement. If *v* is definitely assigned on all such control flow transfers, then *v* is definitely assigned at the end point of the statement. Otherwise; *v* is not definitely assigned at the end point of the statement. The set of possible control flow transfers is determined in the same way as for checking statement reachability ([End points and reachability](statements.md#end-points-and-reachability)).
|
||||
|
||||
#### Block statements, checked, and unchecked statements
|
||||
|
||||
The definite assignment state of *v* on the control transfer to the first statement of the statement list in the block (or to the end point of the block, if the statement list is empty) is the same as the definite assignment statement of *v* before the block, `checked`, or `unchecked` statement.
|
||||
|
||||
#### Expression statements
|
||||
|
||||
For an expression statement *stmt* that consists of the expression *expr*:
|
||||
|
||||
* *v* has the same definite assignment state at the beginning of *expr* as at the beginning of *stmt*.
|
||||
* If *v* if definitely assigned at the end of *expr*, it is definitely assigned at the end point of *stmt*; otherwise; it is not definitely assigned at the end point of *stmt*.
|
||||
|
||||
#### Declaration statements
|
||||
|
||||
* If *stmt* is a declaration statement without initializers, then *v* has the same definite assignment state at the end point of *stmt* as at the beginning of *stmt*.
|
||||
* If *stmt* is a declaration statement with initializers, then the definite assignment state for *v* is determined as if *stmt* were a statement list, with one assignment statement for each declaration with an initializer (in the order of declaration).
|
||||
|
||||
#### If statements
|
||||
|
||||
For an `if` statement *stmt* of the form:
|
||||
```csharp
|
||||
if ( expr ) then_stmt else else_stmt
|
||||
```
|
||||
|
||||
* *v* has the same definite assignment state at the beginning of *expr* as at the beginning of *stmt*.
|
||||
* If *v* is definitely assigned at the end of *expr*, then it is definitely assigned on the control flow transfer to *then_stmt* and to either *else_stmt* or to the end-point of *stmt* if there is no else clause.
|
||||
* If *v* has the state "definitely assigned after true expression" at the end of *expr*, then it is definitely assigned on the control flow transfer to *then_stmt*, and not definitely assigned on the control flow transfer to either *else_stmt* or to the end-point of *stmt* if there is no else clause.
|
||||
* If *v* has the state "definitely assigned after false expression" at the end of *expr*, then it is definitely assigned on the control flow transfer to *else_stmt*, and not definitely assigned on the control flow transfer to *then_stmt*. It is definitely assigned at the end-point of *stmt* if and only if it is definitely assigned at the end-point of *then_stmt*.
|
||||
* Otherwise, *v* is considered not definitely assigned on the control flow transfer to either the *then_stmt* or *else_stmt*, or to the end-point of *stmt* if there is no else clause.
|
||||
|
||||
#### Switch statements
|
||||
|
||||
In a `switch` statement *stmt* with a controlling expression *expr*:
|
||||
|
||||
* The definite assignment state of *v* at the beginning of *expr* is the same as the state of *v* at the beginning of *stmt*.
|
||||
* The definite assignment state of *v* on the control flow transfer to a reachable switch block statement list is the same as the definite assignment state of *v* at the end of *expr*.
|
||||
|
||||
#### While statements
|
||||
|
||||
For a `while` statement *stmt* of the form:
|
||||
```csharp
|
||||
while ( expr ) while_body
|
||||
```
|
||||
|
||||
* *v* has the same definite assignment state at the beginning of *expr* as at the beginning of *stmt*.
|
||||
* If *v* is definitely assigned at the end of *expr*, then it is definitely assigned on the control flow transfer to *while_body* and to the end point of *stmt*.
|
||||
* If *v* has the state "definitely assigned after true expression" at the end of *expr*, then it is definitely assigned on the control flow transfer to *while_body*, but not definitely assigned at the end-point of *stmt*.
|
||||
* If *v* has the state "definitely assigned after false expression" at the end of *expr*, then it is definitely assigned on the control flow transfer to the end point of *stmt*, but not definitely assigned on the control flow transfer to *while_body*.
|
||||
|
||||
#### Do statements
|
||||
|
||||
For a `do` statement *stmt* of the form:
|
||||
```csharp
|
||||
do do_body while ( expr ) ;
|
||||
```
|
||||
|
||||
* *v* has the same definite assignment state on the control flow transfer from the beginning of *stmt* to *do_body* as at the beginning of *stmt*.
|
||||
* *v* has the same definite assignment state at the beginning of *expr* as at the end point of *do_body*.
|
||||
* If *v* is definitely assigned at the end of *expr*, then it is definitely assigned on the control flow transfer to the end point of *stmt*.
|
||||
* If *v* has the state "definitely assigned after false expression" at the end of *expr*, then it is definitely assigned on the control flow transfer to the end point of *stmt*.
|
||||
|
||||
#### For statements
|
||||
|
||||
Definite assignment checking for a `for` statement of the form:
|
||||
```csharp
|
||||
for ( for_initializer ; for_condition ; for_iterator ) embedded_statement
|
||||
```
|
||||
is done as if the statement were written:
|
||||
```csharp
|
||||
{
|
||||
for_initializer ;
|
||||
while ( for_condition ) {
|
||||
embedded_statement ;
|
||||
for_iterator ;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If the *for_condition* is omitted from the `for` statement, then evaluation of definite assignment proceeds as if *for_condition* were replaced with `true` in the above expansion.
|
||||
|
||||
#### Break, continue, and goto statements
|
||||
|
||||
The definite assignment state of *v* on the control flow transfer caused by a `break`, `continue`, or `goto` statement is the same as the definite assignment state of *v* at the beginning of the statement.
|
||||
|
||||
#### Throw statements
|
||||
|
||||
For a statement *stmt* of the form
|
||||
```csharp
|
||||
throw expr ;
|
||||
```
|
||||
|
||||
The definite assignment state of *v* at the beginning of *expr* is the same as the definite assignment state of *v* at the beginning of *stmt*.
|
||||
|
||||
#### Return statements
|
||||
|
||||
For a statement *stmt* of the form
|
||||
```csharp
|
||||
return expr ;
|
||||
```
|
||||
|
||||
* The definite assignment state of *v* at the beginning of *expr* is the same as the definite assignment state of *v* at the beginning of *stmt*.
|
||||
* If *v* is an output parameter, then it must be definitely assigned either:
|
||||
* after *expr*
|
||||
* or at the end of the `finally` block of a `try`-`finally` or `try`-`catch`-`finally` that encloses the `return` statement.
|
||||
|
||||
For a statement stmt of the form:
|
||||
```csharp
|
||||
return ;
|
||||
```
|
||||
|
||||
* If *v* is an output parameter, then it must be definitely assigned either:
|
||||
* before *stmt*
|
||||
* or at the end of the `finally` block of a `try`-`finally` or `try`-`catch`-`finally` that encloses the `return` statement.
|
||||
|
||||
#### Try-catch statements
|
||||
|
||||
For a statement *stmt* of the form:
|
||||
```csharp
|
||||
try try_block
|
||||
catch(...) catch_block_1
|
||||
...
|
||||
catch(...) catch_block_n
|
||||
```
|
||||
|
||||
* The definite assignment state of *v* at the beginning of *try_block* is the same as the definite assignment state of *v* at the beginning of *stmt*.
|
||||
* The definite assignment state of *v* at the beginning of *catch_block_i* (for any *i*) is the same as the definite assignment state of *v* at the beginning of *stmt*.
|
||||
* The definite assignment state of *v* at the end-point of *stmt* is definitely assigned if (and only if) *v* is definitely assigned at the end-point of *try_block* and every *catch_block_i* (for every *i* from 1 to *n*).
|
||||
|
||||
#### Try-finally statements
|
||||
|
||||
For a `try` statement *stmt* of the form:
|
||||
```csharp
|
||||
try try_block finally finally_block
|
||||
```
|
||||
|
||||
* The definite assignment state of *v* at the beginning of *try_block* is the same as the definite assignment state of *v* at the beginning of *stmt*.
|
||||
* The definite assignment state of *v* at the beginning of *finally_block* is the same as the definite assignment state of *v* at the beginning of *stmt*.
|
||||
* The definite assignment state of *v* at the end-point of *stmt* is definitely assigned if (and only if) at least one of the following is true:
|
||||
* *v* is definitely assigned at the end-point of *try_block*
|
||||
* *v* is definitely assigned at the end-point of *finally_block*
|
||||
|
||||
If a control flow transfer (for example, a `goto` statement) is made that begins within *try_block*, and ends outside of *try_block*, then *v* is also considered definitely assigned on that control flow transfer if *v* is definitely assigned at the end-point of *finally_block*. (This is not an only if—if *v* is definitely assigned for another reason on this control flow transfer, then it is still considered definitely assigned.)
|
||||
|
||||
#### Try-catch-finally statements
|
||||
|
||||
Definite assignment analysis for a `try`-`catch`-`finally` statement of the form:
|
||||
```csharp
|
||||
try try_block
|
||||
catch(...) catch_block_1
|
||||
...
|
||||
catch(...) catch_block_n
|
||||
finally *finally_block*
|
||||
```
|
||||
is done as if the statement were a `try`-`finally` statement enclosing a `try`-`catch` statement:
|
||||
```csharp
|
||||
try {
|
||||
try try_block
|
||||
catch(...) catch_block_1
|
||||
...
|
||||
catch(...) catch_block_n
|
||||
}
|
||||
finally finally_block
|
||||
```
|
||||
|
||||
The following example demonstrates how the different blocks of a `try` statement ([The try statement](statements.md#the-try-statement)) affect definite assignment.
|
||||
```csharp
|
||||
class A
|
||||
{
|
||||
static void F() {
|
||||
int i, j;
|
||||
try {
|
||||
goto LABEL;
|
||||
// neither i nor j definitely assigned
|
||||
i = 1;
|
||||
// i definitely assigned
|
||||
}
|
||||
|
||||
catch {
|
||||
// neither i nor j definitely assigned
|
||||
i = 3;
|
||||
// i definitely assigned
|
||||
}
|
||||
|
||||
finally {
|
||||
// neither i nor j definitely assigned
|
||||
j = 5;
|
||||
// j definitely assigned
|
||||
}
|
||||
// i and j definitely assigned
|
||||
LABEL:;
|
||||
// j definitely assigned
|
||||
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Foreach statements
|
||||
|
||||
For a `foreach` statement *stmt* of the form:
|
||||
```csharp
|
||||
foreach ( type identifier in expr ) embedded_statement
|
||||
```
|
||||
|
||||
* The definite assignment state of *v* at the beginning of *expr* is the same as the state of *v* at the beginning of *stmt*.
|
||||
* The definite assignment state of *v* on the control flow transfer to *embedded_statement* or to the end point of *stmt* is the same as the state of *v* at the end of *expr*.
|
||||
|
||||
#### Using statements
|
||||
|
||||
For a `using` statement *stmt* of the form:
|
||||
```csharp
|
||||
using ( resource_acquisition ) embedded_statement
|
||||
```
|
||||
|
||||
* The definite assignment state of *v* at the beginning of *resource_acquisition* is the same as the state of *v* at the beginning of *stmt*.
|
||||
* The definite assignment state of *v* on the control flow transfer to *embedded_statement* is the same as the state of *v* at the end of *resource_acquisition*.
|
||||
|
||||
#### Lock statements
|
||||
|
||||
For a `lock` statement *stmt* of the form:
|
||||
```csharp
|
||||
lock ( expr ) embedded_statement
|
||||
```
|
||||
|
||||
* The definite assignment state of *v* at the beginning of *expr* is the same as the state of *v* at the beginning of *stmt*.
|
||||
* The definite assignment state of *v* on the control flow transfer to *embedded_statement* is the same as the state of *v* at the end of *expr*.
|
||||
|
||||
#### Yield statements
|
||||
|
||||
For a `yield return` statement *stmt* of the form:
|
||||
```csharp
|
||||
yield return expr ;
|
||||
```
|
||||
|
||||
* The definite assignment state of *v* at the beginning of *expr* is the same as the state of *v* at the beginning of *stmt*.
|
||||
* The definite assignment state of *v* at the end of *stmt* is the same as the state of *v* at the end of *expr*.
|
||||
* A `yield break` statement has no effect on the definite assignment state.
|
||||
|
||||
#### General rules for simple expressions
|
||||
|
||||
The following rule applies to these kinds of expressions: literals ([Literals](expressions.md#literals)), simple names ([Simple names](expressions.md#simple-names)), member access expressions ([Member access](expressions.md#member-access)), non-indexed base access expressions ([Base access](expressions.md#base-access)), `typeof` expressions ([The typeof operator](expressions.md#the-typeof-operator)), default value expressions ([Default value expressions](expressions.md#default-value-expressions)) and `nameof` expressions ([Nameof expressions](expressions.md#nameof-expressions)).
|
||||
|
||||
* The definite assignment state of *v* at the end of such an expression is the same as the definite assignment state of *v* at the beginning of the expression.
|
||||
|
||||
#### General rules for expressions with embedded expressions
|
||||
|
||||
The following rules apply to these kinds of expressions: parenthesized expressions ([Parenthesized expressions](expressions.md#parenthesized-expressions)), element access expressions ([Element access](expressions.md#element-access)), base access expressions with indexing ([Base access](expressions.md#base-access)), increment and decrement expressions ([Postfix increment and decrement operators](expressions.md#postfix-increment-and-decrement-operators), [Prefix increment and decrement operators](expressions.md#prefix-increment-and-decrement-operators)), cast expressions ([Cast expressions](expressions.md#cast-expressions)), unary `+`, `-`, `~`, `*` expressions, binary `+`, `-`, `*`, `/`, `%`, `<<`, `>
|
||||
>`, `<`, `<=`, `>`, `>=`, `==`, `!=`, `is`, `as`, `&`, `|`, `^` expressions ([Arithmetic operators](expressions.md#arithmetic-operators), [Shift operators](expressions.md#shift-operators), [Relational and type-testing operators](expressions.md#relational-and-type-testing-operators), [Logical operators](expressions.md#logical-operators)), compound assignment expressions ([Compound assignment](expressions.md#compound-assignment)), `checked` and `unchecked` expressions ([The checked and unchecked operators](expressions.md#the-checked-and-unchecked-operators)), plus array and delegate creation expressions ([The new operator](expressions.md#the-new-operator)).
|
||||
|
||||
Each of these expressions has one or more sub-expressions that are unconditionally evaluated in a fixed order. For example, the binary `%` operator evaluates the left hand side of the operator, then the right hand side. An indexing operation evaluates the indexed expression, and then evaluates each of the index expressions, in order from left to right. For an expression *expr*, which has sub-expressions *e1, e2, ..., eN*, evaluated in that order:
|
||||
|
||||
* The definite assignment state of *v* at the beginning of *e1* is the same as the definite assignment state at the beginning of *expr*.
|
||||
* The definite assignment state of *v* at the beginning of *ei* (*i* greater than one) is the same as the definite assignment state at the end of the previous sub-expression.
|
||||
* The definite assignment state of *v* at the end of *expr* is the same as the definite assignment state at the end of *eN*
|
||||
|
||||
#### Invocation expressions and object creation expressions
|
||||
|
||||
For an invocation expression *expr* of the form:
|
||||
```csharp
|
||||
primary_expression ( arg1 , arg2 , ... , argN )
|
||||
```
|
||||
or an object creation expression of the form:
|
||||
```csharp
|
||||
new type ( arg1 , arg2 , ... , argN )
|
||||
```
|
||||
|
||||
* For an invocation expression, the definite assignment state of *v* before *primary_expression* is the same as the state of *v* before *expr*.
|
||||
* For an invocation expression, the definite assignment state of *v* before *arg1* is the same as the state of *v* after *primary_expression*.
|
||||
* For an object creation expression, the definite assignment state of *v* before *arg1* is the same as the state of *v* before *expr*.
|
||||
* For each argument *argi*, the definite assignment state of *v* after *argi* is determined by the normal expression rules, ignoring any `ref` or `out` modifiers.
|
||||
* For each argument *argi* for any *i* greater than one, the definite assignment state of *v* before *argi* is the same as the state of *v* after the previous *arg*.
|
||||
* If the variable *v* is passed as an `out` argument (i.e., an argument of the form `out v`) in any of the arguments, then the state of *v* after *expr* is definitely assigned. Otherwise; the state of *v* after *expr* is the same as the state of *v* after *argN*.
|
||||
* For array initializers ([Array creation expressions](expressions.md#array-creation-expressions)), object initializers ([Object initializers](expressions.md#object-initializers)), collection initializers ([Collection initializers](expressions.md#collection-initializers)) and anonymous object initializers ([Anonymous object creation expressions](expressions.md#anonymous-object-creation-expressions)), the definite assignment state is determined by the expansion that these constructs are defined in terms of.
|
||||
|
||||
#### Simple assignment expressions
|
||||
|
||||
For an expression *expr* of the form `w = expr_rhs`:
|
||||
|
||||
* The definite assignment state of *v* before *expr_rhs* is the same as the definite assignment state of *v* before *expr*.
|
||||
* The definite assignment state of *v* after *expr* is determined by:
|
||||
* If *w* is the same variable as *v*, then the definite assignment state of *v* after *expr* is definitely assigned.
|
||||
* Otherwise, if the assignment occurs within the instance constructor of a struct type, if *w* is a property access designating an automatically implemented property *P* on the instance being constructed and *v* is the hidden backing field of *P*, then the definite assignment state of *v* after *expr* is definitely assigned.
|
||||
* Otherwise, the definite assignment state of *v* after *expr* is the same as the definite assignment state of *v* after *expr_rhs*.
|
||||
|
||||
#### && (conditional AND) expressions
|
||||
|
||||
For an expression *expr* of the form `expr_first && expr_second`:
|
||||
|
||||
* The definite assignment state of *v* before *expr_first* is the same as the definite assignment state of *v* before *expr*.
|
||||
* The definite assignment state of *v* before *expr_second* is definitely assigned if the state of *v* after *expr_first* is either definitely assigned or "definitely assigned after true expression". Otherwise, it is not definitely assigned.
|
||||
* The definite assignment state of *v* after *expr* is determined by:
|
||||
* If *expr_first* is a constant expression with the value `false`, then the definite assignment state of *v* after *expr* is the same as the definite assignment state of *v* after *expr_first*.
|
||||
* Otherwise, if the state of *v* after *expr_first* is definitely assigned, then the state of *v* after *expr* is definitely assigned.
|
||||
* Otherwise, if the state of *v* after *expr_second* is definitely assigned, and the state of *v* after *expr_first* is "definitely assigned after false expression", then the state of *v* after *expr* is definitely assigned.
|
||||
* Otherwise, if the state of *v* after *expr_second* is definitely assigned or "definitely assigned after true expression", then the state of *v* after *expr* is "definitely assigned after true expression".
|
||||
* Otherwise, if the state of *v* after *expr_first* is "definitely assigned after false expression", and the state of *v* after *expr_second* is "definitely assigned after false expression", then the state of *v* after *expr* is "definitely assigned after false expression".
|
||||
* Otherwise, the state of *v* after *expr* is not definitely assigned.
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
class A
|
||||
{
|
||||
static void F(int x, int y) {
|
||||
int i;
|
||||
if (x >= 0 && (i = y) >= 0) {
|
||||
// i definitely assigned
|
||||
}
|
||||
else {
|
||||
// i not definitely assigned
|
||||
}
|
||||
// i not definitely assigned
|
||||
}
|
||||
}
|
||||
```
|
||||
the variable `i` is considered definitely assigned in one of the embedded statements of an `if` statement but not in the other. In the `if` statement in method `F`, the variable `i` is definitely assigned in the first embedded statement because execution of the expression `(i = y)` always precedes execution of this embedded statement. In contrast, the variable `i` is not definitely assigned in the second embedded statement, since `x >= 0` might have tested false, resulting in the variable `i` being unassigned.
|
||||
|
||||
#### || (conditional OR) expressions
|
||||
|
||||
For an expression *expr* of the form `expr_first || expr_second`:
|
||||
|
||||
* The definite assignment state of *v* before *expr_first* is the same as the definite assignment state of *v* before *expr*.
|
||||
* The definite assignment state of *v* before *expr_second* is definitely assigned if the state of *v* after *expr_first* is either definitely assigned or "definitely assigned after false expression". Otherwise, it is not definitely assigned.
|
||||
* The definite assignment statement of *v* after *expr* is determined by:
|
||||
* If *expr_first* is a constant expression with the value `true`, then the definite assignment state of *v* after *expr* is the same as the definite assignment state of *v* after *expr_first*.
|
||||
* Otherwise, if the state of *v* after *expr_first* is definitely assigned, then the state of *v* after *expr* is definitely assigned.
|
||||
* Otherwise, if the state of *v* after *expr_second* is definitely assigned, and the state of *v* after *expr_first* is "definitely assigned after true expression", then the state of *v* after *expr* is definitely assigned.
|
||||
* Otherwise, if the state of *v* after *expr_second* is definitely assigned or "definitely assigned after false expression", then the state of *v* after *expr* is "definitely assigned after false expression".
|
||||
* Otherwise, if the state of *v* after *expr_first* is "definitely assigned after true expression", and the state of *v* after *expr_second* is "definitely assigned after true expression", then the state of *v* after *expr* is "definitely assigned after true expression".
|
||||
* Otherwise, the state of *v* after *expr* is not definitely assigned.
|
||||
|
||||
In the example
|
||||
```csharp
|
||||
class A
|
||||
{
|
||||
static void G(int x, int y) {
|
||||
int i;
|
||||
if (x >= 0 || (i = y) >= 0) {
|
||||
// i not definitely assigned
|
||||
}
|
||||
else {
|
||||
// i definitely assigned
|
||||
}
|
||||
// i not definitely assigned
|
||||
}
|
||||
}
|
||||
```
|
||||
the variable `i` is considered definitely assigned in one of the embedded statements of an `if` statement but not in the other. In the `if` statement in method `G`, the variable `i` is definitely assigned in the second embedded statement because execution of the expression `(i = y)` always precedes execution of this embedded statement. In contrast, the variable `i` is not definitely assigned in the first embedded statement, since `x >= 0` might have tested true, resulting in the variable `i` being unassigned.
|
||||
|
||||
#### ! (logical negation) expressions
|
||||
|
||||
For an expression *expr* of the form `! expr_operand`:
|
||||
|
||||
* The definite assignment state of *v* before *expr_operand* is the same as the definite assignment state of *v* before *expr*.
|
||||
* The definite assignment state of *v* after *expr* is determined by:
|
||||
* If the state of *v* after *expr_operand *is definitely assigned, then the state of *v* after *expr* is definitely assigned.
|
||||
* If the state of *v* after *expr_operand *is not definitely assigned, then the state of *v* after *expr* is not definitely assigned.
|
||||
* If the state of *v* after *expr_operand *is "definitely assigned after false expression", then the state of *v* after *expr* is "definitely assigned after true expression".
|
||||
* If the state of *v* after *expr_operand *is "definitely assigned after true expression", then the state of *v* after *expr* is "definitely assigned after false expression".
|
||||
|
||||
#### ?? (null coalescing) expressions
|
||||
|
||||
For an expression *expr* of the form `expr_first ?? expr_second`:
|
||||
|
||||
* The definite assignment state of *v* before *expr_first* is the same as the definite assignment state of *v* before *expr*.
|
||||
* The definite assignment state of *v* before *expr_second* is the same as the definite assignment state of *v* after *expr_first*.
|
||||
* The definite assignment statement of *v* after *expr* is determined by:
|
||||
* If *expr_first* is a constant expression ([Constant expressions](expressions.md#constant-expressions)) with value null, then the the state of *v* after *expr* is the same as the state of *v* after *expr_second*.
|
||||
* Otherwise, the state of *v* after *expr* is the same as the definite assignment state of *v* after *expr_first*.
|
||||
|
||||
#### ?: (conditional) expressions
|
||||
|
||||
For an expression *expr* of the form `expr_cond ? expr_true : expr_false`:
|
||||
|
||||
* The definite assignment state of *v* before *expr_cond* is the same as the state of *v* before *expr*.
|
||||
* The definite assignment state of *v* before *expr_true* is definitely assigned if and only if one of the following holds:
|
||||
* *expr_cond* is a constant expression with the value `false`
|
||||
* the state of *v* after *expr_cond* is definitely assigned or "definitely assigned after true expression".
|
||||
* The definite assignment state of *v* before *expr_false* is definitely assigned if and only if one of the following holds:
|
||||
* *expr_cond* is a constant expression with the value `true`
|
||||
* the state of *v* after *expr_cond* is definitely assigned or "definitely assigned after false expression".
|
||||
* The definite assignment state of *v* after *expr* is determined by:
|
||||
* If *expr_cond* is a constant expression ([Constant expressions](expressions.md#constant-expressions)) with value `true` then the state of *v* after *expr* is the same as the state of *v* after *expr_true*.
|
||||
* Otherwise, if *expr_cond* is a constant expression ([Constant expressions](expressions.md#constant-expressions)) with value `false` then the state of *v* after *expr* is the same as the state of *v* after *expr_false*.
|
||||
* Otherwise, if the state of *v* after *expr_true* is definitely assigned and the state of *v* after *expr_false* is definitely assigned, then the state of *v* after *expr* is definitely assigned.
|
||||
* Otherwise, the state of *v* after *expr* is not definitely assigned.
|
||||
|
||||
#### Anonymous functions
|
||||
|
||||
For a *lambda_expression* or *anonymous_method_expression* *expr* with a body (either *block* or *expression*) *body*:
|
||||
|
||||
* The definite assignment state of an outer variable *v* before *body* is the same as the state of *v* before *expr*. That is, definite assignment state of outer variables is inherited from the context of the anonymous function.
|
||||
* The definite assignment state of an outer variable *v* after *expr* is the same as the state of *v* before *expr*.
|
||||
|
||||
The example
|
||||
```csharp
|
||||
delegate bool Filter(int i);
|
||||
|
||||
void F() {
|
||||
int max;
|
||||
|
||||
// Error, max is not definitely assigned
|
||||
Filter f = (int n) => n < max;
|
||||
|
||||
max = 5;
|
||||
DoWork(f);
|
||||
}
|
||||
```
|
||||
generates a compile-time error since `max` is not definitely assigned where the anonymous function is declared. The example
|
||||
```csharp
|
||||
delegate void D();
|
||||
|
||||
void F() {
|
||||
int n;
|
||||
D d = () => { n = 1; };
|
||||
|
||||
d();
|
||||
|
||||
// Error, n is not definitely assigned
|
||||
Console.WriteLine(n);
|
||||
}
|
||||
```
|
||||
also generates a compile-time error since the assignment to `n` in the anonymous function has no affect on the definite assignment state of `n` outside the anonymous function.
|
||||
|
||||
## Variable references
|
||||
|
||||
A *variable_reference* is an *expression* that is classified as a variable. A *variable_reference* denotes a storage location that can be accessed both to fetch the current value and to store a new value.
|
||||
|
||||
```antlr
|
||||
variable_reference
|
||||
: expression
|
||||
;
|
||||
```
|
||||
|
||||
In C and C++, a *variable_reference* is known as an *lvalue*.
|
||||
|
||||
## Atomicity of variable references
|
||||
|
||||
Reads and writes of the following data types are atomic: `bool`, `char`, `byte`, `sbyte`, `short`, `ushort`, `uint`, `int`, `float`, and reference types. In addition, reads and writes of enum types with an underlying type in the previous list are also atomic. Reads and writes of other types, including `long`, `ulong`, `double`, and `decimal`, as well as user-defined types, are not guaranteed to be atomic. Aside from the library functions designed for that purpose, there is no guarantee of atomic read-modify-write, such as in the case of increment or decrement.
|
||||
|
||||
Loading…
Reference in a new issue