- jsFiddle demo C# Language Specification

 

 

 

 

 

 

C#

Language Specification

Version 5.0


Notice

© 1999-2012 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.


Table of Contents

1. Introduction.......................................................................................................................................... 1

1.1 Hello world......................................................................................................................................... 1

1.2 Program structure............................................................................................................................... 2

1.3 Types and variables............................................................................................................................. 4

1.4 Expressions......................................................................................................................................... 6

1.5 Statements.......................................................................................................................................... 8

1.6 Classes and objects............................................................................................................................ 12

1.6.1 Members.................................................................................................................................... 12

1.6.2 Accessibility................................................................................................................................ 13

1.6.3 Type parameters......................................................................................................................... 13

1.6.4 Base classes............................................................................................................................... 14

1.6.5 Fields.......................................................................................................................................... 14

1.6.6 Methods..................................................................................................................................... 15

1.6.6.1 Parameters........................................................................................................................... 15

1.6.6.2 Method body and local variables............................................................................................. 16

1.6.6.3 Static and instance methods................................................................................................... 17

1.6.6.4 Virtual, override, and abstract methods................................................................................... 18

1.6.6.5 Method overloading............................................................................................................... 20

1.6.7 Other function members.............................................................................................................. 21

1.6.7.1 Constructors......................................................................................................................... 22

1.6.7.2 Properties............................................................................................................................. 23

1.6.7.3 Indexers............................................................................................................................... 23

1.6.7.4 Events.................................................................................................................................. 24

1.6.7.5 Operators............................................................................................................................. 24

1.6.7.6 Destructors........................................................................................................................... 25

1.7 Structs.............................................................................................................................................. 25

1.8 Arrays.............................................................................................................................................. 26

1.9 Interfaces......................................................................................................................................... 27

1.10 Enums............................................................................................................................................. 29

1.11 Delegates........................................................................................................................................ 30

1.12 Attributes........................................................................................................................................ 31

2. Lexical structure................................................................................................................................. 33

2.1 Programs.......................................................................................................................................... 33

2.2 Grammars......................................................................................................................................... 33

2.2.1 Grammar notation........................................................................................................................ 33

2.2.2 Lexical grammar......................................................................................................................... 34

2.2.3 Syntactic grammar...................................................................................................................... 34

2.3 Lexical analysis................................................................................................................................. 34

2.3.1 Line terminators.......................................................................................................................... 35

2.3.2 Comments.................................................................................................................................. 35

2.3.3 White space................................................................................................................................ 37

2.4 Tokens.............................................................................................................................................. 37

2.4.1 Unicode character escape sequences........................................................................................... 37

2.4.2 Identifiers................................................................................................................................... 38

2.4.3 Keywords................................................................................................................................... 39

2.4.4 Literals....................................................................................................................................... 40

2.4.4.1 Boolean literals...................................................................................................................... 40

2.4.4.2 Integer literals....................................................................................................................... 40

2.4.4.3 Real literals........................................................................................................................... 41

2.4.4.4 Character literals................................................................................................................... 42

2.4.4.5 String literals......................................................................................................................... 43

2.4.4.6 The null literal....................................................................................................................... 45

2.4.5 Operators and punctuators........................................................................................................... 45

2.5 Pre-processing directives................................................................................................................... 45

2.5.1 Conditional compilation symbols.................................................................................................... 46

2.5.2 Pre-processing expressions.......................................................................................................... 47

2.5.3 Declaration directives.................................................................................................................. 47

2.5.4 Conditional compilation directives................................................................................................. 48

2.5.5 Diagnostic directives.................................................................................................................... 51

2.5.6 Region directives......................................................................................................................... 51

2.5.7 Line directives............................................................................................................................. 52

2.5.8 Pragma directives........................................................................................................................ 52

2.5.8.1 Pragma warning.................................................................................................................... 53

3. Basic concepts.................................................................................................................................... 55

3.1 Application Startup............................................................................................................................ 55

3.2 Application termination....................................................................................................................... 56

3.3 Declarations...................................................................................................................................... 56

3.4 Members.......................................................................................................................................... 58

3.4.1 Namespace members.................................................................................................................. 58

3.4.2 Struct members........................................................................................................................... 59

3.4.3 Enumeration members................................................................................................................. 59

3.4.4 Class members............................................................................................................................ 59

3.4.5 Interface members...................................................................................................................... 60

3.4.6 Array members........................................................................................................................... 60

3.4.7 Delegate members...................................................................................................................... 60

3.5 Member access................................................................................................................................. 60

3.5.1 Declared accessibility.................................................................................................................. 60

3.5.2 Accessibility domains................................................................................................................... 61

3.5.3 Protected access for instance members........................................................................................ 63

3.5.4 Accessibility constraints............................................................................................................... 64

3.6 Signatures and overloading................................................................................................................. 65

3.7 Scopes.............................................................................................................................................. 66

3.7.1 Name hiding................................................................................................................................ 69

3.7.1.1 Hiding through nesting........................................................................................................... 69

3.7.1.2 Hiding through inheritance...................................................................................................... 70

3.8 Namespace and type names............................................................................................................... 71

3.8.1 Fully qualified names................................................................................................................... 73

3.9 Automatic memory management........................................................................................................ 73

3.10 Execution order............................................................................................................................... 76

4. Types................................................................................................................................................... 77

4.1 Value types....................................................................................................................................... 77

4.1.1 The System.ValueType type........................................................................................................ 78

4.1.2 Default constructors.................................................................................................................... 78

4.1.3 Struct types................................................................................................................................. 79

4.1.4 Simple types................................................................................................................................ 79

4.1.5 Integral types.............................................................................................................................. 80

4.1.6 Floating point types...................................................................................................................... 81

4.1.7 The decimal type......................................................................................................................... 82

4.1.8 The bool type.............................................................................................................................. 83

4.1.9 Enumeration types....................................................................................................................... 83

4.1.10 Nullable types............................................................................................................................ 83

4.2 Reference types................................................................................................................................ 83

4.2.1 Class types................................................................................................................................. 84

4.2.2 The object type........................................................................................................................... 85

4.2.3 The dynamic type........................................................................................................................ 85

4.2.4 The string type............................................................................................................................ 85

4.2.5 Interface types............................................................................................................................ 85

4.2.6 Array types................................................................................................................................. 85

4.2.7 Delegate types............................................................................................................................ 85

4.3 Boxing and unboxing.......................................................................................................................... 86

4.3.1 Boxing conversions...................................................................................................................... 86

4.3.2 Unboxing conversions.................................................................................................................. 87

4.4 Constructed types.............................................................................................................................. 88

4.4.1 Type arguments.......................................................................................................................... 89

4.4.2 Open and closed types................................................................................................................. 89

4.4.3 Bound and unbound types............................................................................................................ 89

4.4.4 Satisfying constraints................................................................................................................... 89

4.5 Type parameters............................................................................................................................... 90

4.6 Expression tree types......................................................................................................................... 91

4.7 The dynamic type.............................................................................................................................. 92

5. Variables............................................................................................................................................. 93

5.1 Variable categories............................................................................................................................ 93

5.1.1 Static variables............................................................................................................................ 93

5.1.2 Instance variables........................................................................................................................ 93

5.1.2.1 Instance variables in classes................................................................................................... 93

5.1.2.2 Instance variables in structs................................................................................................... 94

5.1.3 Array elements........................................................................................................................... 94

5.1.4 Value parameters........................................................................................................................ 94

5.1.5 Reference parameters................................................................................................................. 94

5.1.6 Output parameters....................................................................................................................... 94

5.1.7 Local variables............................................................................................................................ 95

5.2 Default values................................................................................................................................... 96

5.3 Definite assignment........................................................................................................................... 96

5.3.1 Initially assigned variables............................................................................................................ 97

5.3.2 Initially unassigned variables......................................................................................................... 97

5.3.3 Precise rules for determining definite assignment........................................................................... 97

5.3.3.1 General rules for statements................................................................................................... 98

5.3.3.2 Block statements, checked, and unchecked statements............................................................ 98

5.3.3.3 Expression statements........................................................................................................... 98

5.3.3.4 Declaration statements.......................................................................................................... 98

5.3.3.5 If statements......................................................................................................................... 98

5.3.3.6 Switch statements................................................................................................................. 99

5.3.3.7 While statements................................................................................................................... 99

5.3.3.8 Do statements....................................................................................................................... 99

5.3.3.9 For statements..................................................................................................................... 100

5.3.3.10 Break, continue, and goto statements................................................................................... 100

5.3.3.11 Throw statements.............................................................................................................. 100

5.3.3.12 Return statements.............................................................................................................. 100

5.3.3.13 Try-catch statements......................................................................................................... 100

5.3.3.14 Try-finally statements......................................................................................................... 101

5.3.3.15 Try-catch-finally statements............................................................................................... 101

5.3.3.16 Foreach statements............................................................................................................ 102

5.3.3.17 Using statements............................................................................................................... 102

5.3.3.18 Lock statements................................................................................................................ 102

5.3.3.19 Yield statements................................................................................................................ 103

5.3.3.20 General rules for simple expressions.................................................................................... 103

5.3.3.21 General rules for expressions with embedded expressions..................................................... 103

5.3.3.22 Invocation expressions and object creation expressions......................................................... 103

5.3.3.23 Simple assignment expressions............................................................................................ 104

5.3.3.24 && expressions................................................................................................................. 104

5.3.3.25 || expressions..................................................................................................................... 105

5.3.3.26 ! expressions..................................................................................................................... 106

5.3.3.27 ?? expressions................................................................................................................... 106

5.3.3.28 ?: expressions.................................................................................................................... 106

5.3.3.29 Anonymous functions......................................................................................................... 107

5.4 Variable references......................................................................................................................... 107

5.5 Atomicity of variable references....................................................................................................... 107

6. Conversions...................................................................................................................................... 109

6.1 Implicit conversions.......................................................................................................................... 109

6.1.1 Identity conversion..................................................................................................................... 109

6.1.2 Implicit numeric conversions....................................................................................................... 110

6.1.3 Implicit enumeration conversions................................................................................................ 110

6.1.4 Implicit nullable conversions....................................................................................................... 110

6.1.5 Null literal conversions............................................................................................................... 111

6.1.6 Implicit reference conversions.................................................................................................... 111

6.1.7 Boxing conversions.................................................................................................................... 111

6.1.8 Implicit dynamic conversions...................................................................................................... 112

6.1.9 Implicit constant expression conversions...................................................................................... 112

6.1.10 Implicit conversions involving type parameters........................................................................... 112

6.1.11 User-defined implicit conversions.............................................................................................. 113

6.1.12 Anonymous function conversions and method group conversions................................................. 113

6.2 Explicit conversions.......................................................................................................................... 113

6.2.1 Explicit numeric conversions....................................................................................................... 114

6.2.2 Explicit enumeration conversions................................................................................................ 115

6.2.3 Explicit nullable conversions....................................................................................................... 115

6.2.4 Explicit reference conversions.................................................................................................... 116

6.2.5 Unboxing conversions................................................................................................................ 117

6.2.6 Explicit dynamic conversions...................................................................................................... 117

6.2.7 Explicit conversions involving type parameters............................................................................. 118

6.2.8 User-defined explicit conversions................................................................................................ 119

6.3 Standard conversions....................................................................................................................... 119

6.3.1 Standard implicit conversions...................................................................................................... 119

6.3.2 Standard explicit conversions...................................................................................................... 119

6.4 User-defined conversions................................................................................................................. 119

6.4.1 Permitted user-defined conversions............................................................................................. 119

6.4.2 Lifted conversion operators........................................................................................................ 120

6.4.3 Evaluation of user-defined conversions........................................................................................ 120

6.4.4 User-defined implicit conversions................................................................................................ 121

6.4.5 User-defined explicit conversions................................................................................................ 122

6.5 Anonymous function conversions...................................................................................................... 123

6.5.1 Evaluation of anonymous function conversions to delegate types................................................... 124

6.5.2 Evaluation of anonymous function conversions to expression tree types......................................... 124

6.5.3 Implementation example............................................................................................................. 124

6.6 Method group conversions................................................................................................................ 127

7. Expressions...................................................................................................................................... 131

7.1 Expression classifications................................................................................................................. 131

7.1.1 Values of expressions................................................................................................................ 132

7.2 Static and Dynamic Binding.............................................................................................................. 132

7.2.1 Binding-time.............................................................................................................................. 133

7.2.2 Dynamic binding........................................................................................................................ 133

7.2.3 Types of constituent expressions................................................................................................. 133

7.3 Operators........................................................................................................................................ 134

7.3.1 Operator precedence and associativity........................................................................................ 134

7.3.2 Operator overloading................................................................................................................. 135

7.3.3 Unary operator overload resolution............................................................................................. 136

7.3.4 Binary operator overload resolution............................................................................................. 137

7.3.5 Candidate user-defined operators................................................................................................ 137

7.3.6 Numeric promotions................................................................................................................... 137

7.3.6.1 Unary numeric promotions................................................................................................... 138

7.3.6.2 Binary numeric promotions................................................................................................... 138

7.3.7 Lifted operators......................................................................................................................... 139

7.4 Member lookup................................................................................................................................ 139

7.4.1 Base types................................................................................................................................ 141

7.5 Function members............................................................................................................................ 141

7.5.1 Argument lists........................................................................................................................... 143

7.5.1.1 Corresponding parameters.................................................................................................... 144

7.5.1.2 Run-time evaluation of argument lists.................................................................................... 145

7.5.2 Type inference.......................................................................................................................... 147

7.5.2.1 The first phase.................................................................................................................... 147

7.5.2.2 The second phase................................................................................................................ 148

7.5.2.3 Input types.......................................................................................................................... 148

7.5.2.4 Output types........................................................................................................................ 148

7.5.2.5 Dependence........................................................................................................................ 148

7.5.2.6 Output type inferences......................................................................................................... 148

7.5.2.7 Explicit parameter type inferences........................................................................................ 148

7.5.2.8 Exact inferences.................................................................................................................. 149

7.5.2.9 Lower-bound inferences...................................................................................................... 149

7.5.2.10 Upper-bound inferences..................................................................................................... 150

7.5.2.11 Fixing................................................................................................................................ 150

7.5.2.12 Inferred return type............................................................................................................ 150

7.5.2.13 Type inference for conversion of method groups.................................................................. 151

7.5.2.14 Finding the best common type of a set of expressions........................................................... 152

7.5.3 Overload resolution.................................................................................................................... 152

7.5.3.1 Applicable function member................................................................................................. 153

7.5.3.2 Better function member....................................................................................................... 153

7.5.3.3 Better conversion from expression........................................................................................ 154

7.5.3.4 Better conversion from type................................................................................................. 155

7.5.3.5 Better conversion target....................................................................................................... 155

7.5.3.6 Overloading in generic classes.............................................................................................. 155

7.5.4 Compile-time checking of dynamic overload resolution................................................................. 155

7.5.5 Function member invocation....................................................................................................... 156

7.5.5.1 Invocations on boxed instances............................................................................................. 157

7.6 Primary expressions......................................................................................................................... 157

7.6.1 Literals..................................................................................................................................... 158

7.6.2 Simple names............................................................................................................................ 158

7.6.2.1 Invariant meaning in blocks.................................................................................................. 159

7.6.3 Parenthesized expressions.......................................................................................................... 160

7.6.4 Member access......................................................................................................................... 161

7.6.4.1 Identical simple names and type names................................................................................. 162

7.6.4.2 Grammar ambiguities........................................................................................................... 163

7.6.5 Invocation expressions............................................................................................................... 164

7.6.5.1 Method invocations.............................................................................................................. 164

7.6.5.2 Extension method invocations............................................................................................... 165

7.6.5.3 Delegate invocations............................................................................................................ 168

7.6.6 Element access......................................................................................................................... 168

7.6.6.1 Array access....................................................................................................................... 168

7.6.6.2 Indexer access.................................................................................................................... 169

7.6.7 This access............................................................................................................................... 170

7.6.8 Base access.............................................................................................................................. 170

7.6.9 Postfix increment and decrement operators................................................................................. 171

7.6.10 The new operator.................................................................................................................... 172

7.6.10.1 Object creation expressions................................................................................................ 172

7.6.10.2 Object initializers................................................................................................................ 173

7.6.10.3 Collection initializers........................................................................................................... 175

7.6.10.4 Array creation expressions................................................................................................. 176

7.6.10.5 Delegate creation expressions............................................................................................. 178

7.6.10.6 Anonymous object creation expressions............................................................................... 180

7.6.11 The typeof operator................................................................................................................. 181

7.6.12 The checked and unchecked operators...................................................................................... 183

7.6.13 Default value expressions......................................................................................................... 185

7.6.14 Anonymous method expressions............................................................................................... 185

7.7 Unary operators............................................................................................................................... 186

7.7.1 Unary plus operator................................................................................................................... 186

7.7.2 Unary minus operator................................................................................................................ 186

7.7.3 Logical negation operator........................................................................................................... 187

7.7.4 Bitwise complement operator..................................................................................................... 187

7.7.5 Prefix increment and decrement operators.................................................................................. 187

7.7.6 Cast expressions........................................................................................................................ 188

7.8 Arithmetic operators........................................................................................................................ 189

7.8.1 Multiplication operator................................................................................................................ 189

7.8.2 Division operator....................................................................................................................... 190

7.8.3 Remainder operator................................................................................................................... 191

7.8.4 Addition operator....................................................................................................................... 192

7.8.5 Subtraction operator................................................................................................................... 194

7.9 Shift operators................................................................................................................................. 195

7.10 Relational and type-testing operators............................................................................................... 197

7.10.1 Integer comparison operators.................................................................................................... 197

7.10.2 Floating-point comparison operators.......................................................................................... 198

7.10.3 Decimal comparison operators.................................................................................................. 199

7.10.4 Boolean equality operators........................................................................................................ 199

7.10.5 Enumeration comparison operators............................................................................................ 199

7.10.6 Reference type equality operators............................................................................................. 199

7.10.7 String equality operators........................................................................................................... 201

7.10.8 Delegate equality operators...................................................................................................... 201

7.10.9 Equality operators and null........................................................................................................ 202

7.10.10 The is operator....................................................................................................................... 202

7.10.11 The as operator...................................................................................................................... 202

7.11 Logical operators........................................................................................................................... 203

7.11.1 Integer logical operators........................................................................................................... 204

7.11.2 Enumeration logical operators................................................................................................... 204

7.11.3 Boolean logical operators.......................................................................................................... 204

7.11.4 Nullable boolean logical operators............................................................................................. 204

7.12 Conditional logical operators............................................................................................................ 205

7.12.1 Boolean conditional logical operators......................................................................................... 206

7.12.2 User-defined conditional logical operators.................................................................................. 206

7.13 The null coalescing operator............................................................................................................ 206

7.14 Conditional operator....................................................................................................................... 207

7.15 Anonymous function expressions..................................................................................................... 208

7.15.1 Anonymous function signatures................................................................................................. 210

7.15.2 Anonymous function bodies...................................................................................................... 210

7.15.3 Overload resolution.................................................................................................................. 211

7.15.4 Anonymous functions and dynamic binding................................................................................ 211

7.15.5 Outer variables........................................................................................................................ 211

7.15.5.1 Captured outer variables..................................................................................................... 212

7.15.5.2 Instantiation of local variables............................................................................................. 212

7.15.6 Evaluation of anonymous function expressions........................................................................... 214

7.16 Query expressions.......................................................................................................................... 215

7.16.1 Ambiguities in query expressions............................................................................................... 216

7.16.2 Query expression translation..................................................................................................... 216

7.16.2.1 Select and groupby clauses with continuations...................................................................... 217

7.16.2.2 Explicit range variable types............................................................................................... 217

7.16.2.3 Degenerate query expressions............................................................................................ 218

7.16.2.4 From, let, where, join and orderby clauses............................................................................ 218

7.16.2.5 Select clauses.................................................................................................................... 221

7.16.2.6 Groupby clauses................................................................................................................ 222

7.16.2.7 Transparent identifiers........................................................................................................ 222

7.16.3 The query expression pattern.................................................................................................... 223

7.17 Assignment operators..................................................................................................................... 224

7.17.1 Simple assignment.................................................................................................................... 225

7.17.2 Compound assignment.............................................................................................................. 227

7.17.3 Event assignment..................................................................................................................... 228

7.18 Expression..................................................................................................................................... 228

7.19 Constant expressions...................................................................................................................... 228

7.20 Boolean expressions....................................................................................................................... 230

8. Statements........................................................................................................................................ 231

8.1 End points and reachability............................................................................................................... 231

8.2 Blocks............................................................................................................................................. 233

8.2.1 Statement lists........................................................................................................................... 233

8.3 The empty statement........................................................................................................................ 234

8.4 Labeled statements.......................................................................................................................... 234

8.5 Declaration statements..................................................................................................................... 235

8.5.1 Local variable declarations......................................................................................................... 235

8.5.2 Local constant declarations........................................................................................................ 236

8.6 Expression statements...................................................................................................................... 237

8.7 Selection statements......................................................................................................................... 237

8.7.1 The if statement........................................................................................................................ 237

8.7.2 The switch statement................................................................................................................. 238

8.8 Iteration statements.......................................................................................................................... 241

8.8.1 The while statement................................................................................................................... 242

8.8.2 The do statement....................................................................................................................... 242

8.8.3 The for statement...................................................................................................................... 243

8.8.4 The foreach statement............................................................................................................... 244

8.9 Jump statements.............................................................................................................................. 246

8.9.1 The break statement.................................................................................................................. 247

8.9.2 The continue statement.............................................................................................................. 248

8.9.3 The goto statement.................................................................................................................... 248

8.9.4 The return statement.................................................................................................................. 250

8.9.5 The throw statement.................................................................................................................. 250

8.10 The try statement........................................................................................................................... 251

8.11 The checked and unchecked statements.......................................................................................... 254

8.12 The lock statement......................................................................................................................... 254

8.13 The using statement....................................................................................................................... 255

8.14 The yield statement........................................................................................................................ 257

9. Namespaces...................................................................................................................................... 259

9.1 Compilation units.............................................................................................................................. 259

9.2 Namespace declarations................................................................................................................... 259

9.3 Extern aliases.................................................................................................................................. 260

9.4 Using directives............................................................................................................................... 261

9.4.1 Using alias directives................................................................................................................. 262

9.4.2 Using namespace directives....................................................................................................... 264

9.5 Namespace members....................................................................................................................... 266

9.6 Type declarations............................................................................................................................. 266

9.7 Namespace alias qualifiers............................................................................................................... 267

9.7.1 Uniqueness of aliases................................................................................................................. 268

10. Classes............................................................................................................................................ 269

10.1 Class declarations.......................................................................................................................... 269

10.1.1 Class modifiers........................................................................................................................ 269

10.1.1.1 Abstract classes................................................................................................................ 270

10.1.1.2 Sealed classes................................................................................................................... 270

10.1.1.3 Static classes..................................................................................................................... 270

10.1.2 Partial modifier........................................................................................................................ 271

10.1.3 Type parameters...................................................................................................................... 271

10.1.4 Class base specification............................................................................................................ 272

10.1.4.1 Base classes...................................................................................................................... 272

10.1.4.2 Interface implementations................................................................................................... 274

10.1.5 Type parameter constraints...................................................................................................... 274

10.1.6 Class body............................................................................................................................... 278

10.2 Partial types................................................................................................................................... 278

10.2.1 Attributes................................................................................................................................ 278

10.2.2 Modifiers................................................................................................................................. 279

10.2.3 Type parameters and constraints............................................................................................... 279

10.2.4 Base class............................................................................................................................... 280

10.2.5 Base interfaces........................................................................................................................ 280

10.2.6 Members................................................................................................................................. 280

10.2.7 Partial methods........................................................................................................................ 281

10.2.8 Name binding.......................................................................................................................... 283

10.3 Class members.............................................................................................................................. 283

10.3.1 The instance type..................................................................................................................... 285

10.3.2 Members of constructed types.................................................................................................. 285

10.3.3 Inheritance.............................................................................................................................. 286

10.3.4 The new modifier..................................................................................................................... 287

10.3.5 Access modifiers..................................................................................................................... 287

10.3.6 Constituent types..................................................................................................................... 287

10.3.7 Static and instance members..................................................................................................... 287

10.3.8 Nested types........................................................................................................................... 288

10.3.8.1 Fully qualified name........................................................................................................... 289

10.3.8.2 Declared accessibility......................................................................................................... 289

10.3.8.3 Hiding............................................................................................................................... 289

10.3.8.4 this access......................................................................................................................... 290

10.3.8.5 Access to private and protected members of the containing type........................................... 290

10.3.8.6 Nested types in generic classes........................................................................................... 291

10.3.9 Reserved member names......................................................................................................... 292

10.3.9.1 Member names reserved for properties............................................................................... 292

10.3.9.2 Member names reserved for events.................................................................................... 293

10.3.9.3 Member names reserved for indexers................................................................................. 293

10.3.9.4 Member names reserved for destructors............................................................................. 293

10.4 Constants...................................................................................................................................... 293

10.5 Fields............................................................................................................................................ 295

10.5.1 Static and instance fields.......................................................................................................... 296

10.5.2 Readonly fields........................................................................................................................ 297

10.5.2.1 Using static readonly fields for constants............................................................................. 297

10.5.2.2 Versioning of constants and static readonly fields................................................................. 298

10.5.3 Volatile fields........................................................................................................................... 298

10.5.4 Field initialization...................................................................................................................... 299

10.5.5 Variable initializers................................................................................................................... 300

10.5.5.1 Static field initialization....................................................................................................... 301

10.5.5.2 Instance field initialization................................................................................................... 302

10.6 Methods........................................................................................................................................ 302

10.6.1 Method parameters.................................................................................................................. 304

10.6.1.1 Value parameters.............................................................................................................. 306

10.6.1.2 Reference parameters........................................................................................................ 306

10.6.1.3 Output parameters............................................................................................................. 307

10.6.1.4 Parameter arrays............................................................................................................... 308

10.6.2 Static and instance methods...................................................................................................... 310

10.6.3 Virtual methods....................................................................................................................... 310

10.6.4 Override methods.................................................................................................................... 312

10.6.5 Sealed methods........................................................................................................................ 314

10.6.6 Abstract methods..................................................................................................................... 315

10.6.7 External methods..................................................................................................................... 316

10.6.8 Partial methods........................................................................................................................ 317

10.6.9 Extension methods................................................................................................................... 317

10.6.10 Method body.......................................................................................................................... 318

10.6.11 Method overloading................................................................................................................ 318

10.7 Properties...................................................................................................................................... 318

10.7.1 Static and instance properties.................................................................................................... 320

10.7.2 Accessors............................................................................................................................... 320

10.7.3 Automatically implemented properties....................................................................................... 325

10.7.4 Accessibility............................................................................................................................ 325

10.7.5 Virtual, sealed, override, and abstract accessors......................................................................... 327

10.8 Events........................................................................................................................................... 328

10.8.1 Field-like events....................................................................................................................... 330

10.8.2 Event accessors....................................................................................................................... 331

10.8.3 Static and instance events......................................................................................................... 332

10.8.4 Virtual, sealed, override, and abstract accessors......................................................................... 333

10.9 Indexers........................................................................................................................................ 333

10.9.1 Indexer overloading.................................................................................................................. 336

10.10 Operators.................................................................................................................................... 337

10.10.1 Unary operators..................................................................................................................... 338

10.10.2 Binary operators.................................................................................................................... 339

10.10.3 Conversion operators.............................................................................................................. 339

10.11 Instance constructors.................................................................................................................... 342

10.11.1 Constructor initializers............................................................................................................ 343

10.11.2 Instance variable initializers..................................................................................................... 343

10.11.3 Constructor execution............................................................................................................. 344

10.11.4 Default constructors............................................................................................................... 345

10.11.5 Private constructors............................................................................................................... 346

10.11.6 Optional instance constructor parameters................................................................................. 346

10.12 Static constructors........................................................................................................................ 347

10.13 Destructors.................................................................................................................................. 349

10.14 Iterators....................................................................................................................................... 350

10.14.1 Enumerator interfaces............................................................................................................ 350

10.14.2 Enumerable interfaces............................................................................................................ 351

10.14.3 Yield type.............................................................................................................................. 351

10.14.4 Enumerator objects................................................................................................................ 351

10.14.4.1 The MoveNext method..................................................................................................... 351

10.14.4.2 The Current property........................................................................................................ 352

10.14.4.3 The Dispose method......................................................................................................... 353

10.14.5 Enumerable objects................................................................................................................ 353

10.14.5.1 The GetEnumerator method.............................................................................................. 353

10.14.6 Implementation example......................................................................................................... 354

11. Structs............................................................................................................................................. 360

11.1 Struct declarations.......................................................................................................................... 360

11.1.1 Struct modifiers....................................................................................................................... 360

11.1.2 Partial modifier........................................................................................................................ 361

11.1.3 Struct interfaces...................................................................................................................... 361

11.1.4 Struct body.............................................................................................................................. 361

11.2 Struct members.............................................................................................................................. 361

11.3 Class and struct differences............................................................................................................ 361

11.3.1 Value semantics...................................................................................................................... 362

11.3.2 Inheritance.............................................................................................................................. 363

11.3.3 Assignment............................................................................................................................. 363

11.3.4 Default values......................................................................................................................... 363

11.3.5 Boxing and unboxing................................................................................................................ 364

11.3.6 Meaning of this........................................................................................................................ 365

11.3.7 Field initializers........................................................................................................................ 365

11.3.8 Constructors............................................................................................................................ 366

11.3.9 Destructors............................................................................................................................. 367

11.3.10 Static constructors.................................................................................................................. 367

11.4 Struct examples............................................................................................................................. 367

11.4.1 Database integer type.............................................................................................................. 367

11.4.2 Database boolean type............................................................................................................. 369

12. Arrays.............................................................................................................................................. 371

12.1 Array types................................................................................................................................... 371

12.1.1 The System.Array type............................................................................................................ 372

12.1.2 Arrays and the generic IList interface....................................................................................... 372

12.2 Array creation............................................................................................................................... 372

12.3 Array element access..................................................................................................................... 373

12.4 Array members.............................................................................................................................. 373

12.5 Array covariance........................................................................................................................... 373

12.6 Array initializers............................................................................................................................. 373

13. Interfaces........................................................................................................................................ 377

13.1 Interface declarations..................................................................................................................... 377

13.1.1 Interface modifiers................................................................................................................... 377

13.1.2 Partial modifier........................................................................................................................ 377

13.1.3 Variant type parameter lists...................................................................................................... 378

13.1.3.1 Variance safety................................................................................................................. 378

13.1.3.2 Variance conversion.......................................................................................................... 379

13.1.4 Base interfaces........................................................................................................................ 379

13.1.5 Interface body......................................................................................................................... 380

13.2 Interface members......................................................................................................................... 380

13.2.1 Interface methods.................................................................................................................... 381

13.2.2 Interface properties.................................................................................................................. 381

13.2.3 Interface events....................................................................................................................... 382

13.2.4 Interface indexers.................................................................................................................... 382

13.2.5 Interface member access......................................................................................................... 382

13.3 Fully qualified interface member names........................................................................................... 384

13.4 Interface implementations............................................................................................................... 384

13.4.1 Explicit interface member implementations................................................................................ 385

13.4.2 Uniqueness of implemented interfaces....................................................................................... 387

13.4.3 Implementation of generic methods........................................................................................... 388

13.4.4 Interface mapping.................................................................................................................... 389

13.4.5 Interface implementation inheritance......................................................................................... 392

13.4.6 Interface re-implementation...................................................................................................... 393

13.4.7 Abstract classes and interfaces................................................................................................. 394

14. Enums............................................................................................................................................. 397

14.1 Enum declarations.......................................................................................................................... 397

14.2 Enum modifiers.............................................................................................................................. 397

14.3 Enum members.............................................................................................................................. 398

14.4 The System.Enum type................................................................................................................... 400

14.5 Enum values and operations............................................................................................................ 400

15. Delegates........................................................................................................................................ 401

15.1 Delegate declarations..................................................................................................................... 401

15.2 Delegate compatibility.................................................................................................................... 403

15.3 Delegate instantiation..................................................................................................................... 403

15.4 Delegate invocation........................................................................................................................ 404

16. Exceptions...................................................................................................................................... 407

16.1 Causes of exceptions...................................................................................................................... 407

16.2 The System.Exception class............................................................................................................ 407

16.3 How exceptions are handled........................................................................................................... 407

16.4 Common Exception Classes............................................................................................................ 408

17. Attributes........................................................................................................................................ 409

17.1 Attribute classes............................................................................................................................ 409

17.1.1 Attribute usage........................................................................................................................ 409

17.1.2 Positional and named parameters.............................................................................................. 410

17.1.3 Attribute parameter types......................................................................................................... 411

17.2 Attribute specification..................................................................................................................... 411

17.3 Attribute instances......................................................................................................................... 416

17.3.1 Compilation of an attribute........................................................................................................ 416

17.3.2 Run-time retrieval of an attribute instance.................................................................................. 417

17.4 Reserved attributes........................................................................................................................ 417

17.4.1 The AttributeUsage attribute.................................................................................................... 417

17.4.2 The Conditional attribute........................................................................................................... 418

17.4.2.1 Conditional methods........................................................................................................... 418

17.4.2.2 Conditional attribute classes................................................................................................ 420

17.4.3 The Obsolete attribute.............................................................................................................. 421

17.5 Attributes for Interoperation............................................................................................................ 422

17.5.1 Interoperation with COM and Win32 components...................................................................... 422

17.5.2 Interoperation with other .NET languages.................................................................................. 423

17.5.2.1 The IndexerName attribute................................................................................................. 423

18. Unsafe code..................................................................................................................................... 425

18.1 Unsafe contexts............................................................................................................................. 425

18.2 Pointer types.................................................................................................................................. 427

18.3 Fixed and moveable variables.......................................................................................................... 430

18.4 Pointer conversions........................................................................................................................ 430

18.4.1 Pointer arrays.......................................................................................................................... 431

18.5 Pointers in expressions................................................................................................................... 432

18.5.1 Pointer indirection.................................................................................................................... 433

18.5.2 Pointer member access............................................................................................................ 433

18.5.3 Pointer element access............................................................................................................. 434

18.5.4 The address-of operator........................................................................................................... 434

18.5.5 Pointer increment and decrement.............................................................................................. 435

18.5.6 Pointer arithmetic..................................................................................................................... 435

18.5.7 Pointer comparison.................................................................................................................. 436

18.5.8 The sizeof operator.................................................................................................................. 437

18.6 The fixed statement........................................................................................................................ 437

18.7 Fixed size buffers........................................................................................................................... 441

18.7.1 Fixed size buffer declarations.................................................................................................... 441

18.7.2 Fixed size buffers in expressions............................................................................................... 442

18.7.3 Definite assignment checking.................................................................................................... 443

18.8 Stack allocation.............................................................................................................................. 443

18.9 Dynamic memory allocation............................................................................................................ 444

A. Documentation comments............................................................................................................... 447

A.1 Introduction.................................................................................................................................... 447

A.2 Recommended tags......................................................................................................................... 448

A.2.1 <c>.......................................................................................................................................... 449

A.2.2 <code>.................................................................................................................................... 449

A.2.3 <example>............................................................................................................................... 450

A.2.4 <exception>............................................................................................................................. 450

A.2.5 <include>................................................................................................................................. 451

A.2.6 <list>....................................................................................................................................... 451

A.2.7 <para>..................................................................................................................................... 452

A.2.8 <param>.................................................................................................................................. 453

A.2.9 <paramref>.............................................................................................................................. 453

A.2.10 <permission>.......................................................................................................................... 453

A.2.11 <remark>............................................................................................................................... 454

A.2.12 <returns>............................................................................................................................... 454

A.2.13 <see>..................................................................................................................................... 455

A.2.14 <seealso>............................................................................................................................... 455

A.2.15 <summary>............................................................................................................................ 455

A.2.16 <value>.................................................................................................................................. 456

A.2.17 <typeparam>.......................................................................................................................... 456

A.2.18 <typeparamref>...................................................................................................................... 456

A.3 Processing the documentation file.................................................................................................... 457

A.3.1 ID string format........................................................................................................................ 457

A.3.2 ID string examples.................................................................................................................... 458

A.4 An example.................................................................................................................................... 462

A.4.1 C# source code........................................................................................................................ 462

A.4.2 Resulting XML......................................................................................................................... 464

B. Grammar........................................................................................................................................... 468

B.1 Lexical grammar............................................................................................................................. 468

B.1.1 Line terminators........................................................................................................................ 468

B.1.2 Comments................................................................................................................................ 468

B.1.3 White space............................................................................................................................. 469

B.1.4 Tokens..................................................................................................................................... 469

B.1.5 Unicode character escape sequences......................................................................................... 469

B.1.6 Identifiers................................................................................................................................. 469

B.1.7 Keywords................................................................................................................................ 470

B.1.8 Literals..................................................................................................................................... 471

B.1.9 Operators and punctuators......................................................................................................... 473

B.1.10 Pre-processing directives......................................................................................................... 473

B.2 Syntactic grammar.......................................................................................................................... 475

B.2.1 Basic concepts......................................................................................................................... 475

B.2.2 Types....................................................................................................................................... 475

B.2.3 Variables.................................................................................................................................. 477

B.2.4 Expressions.............................................................................................................................. 477

B.2.5 Statements............................................................................................................................... 484

B.2.6 Namespaces............................................................................................................................. 487

B.2.7 Classes.................................................................................................................................... 488

B.2.8 Structs..................................................................................................................................... 495

B.2.9 Arrays..................................................................................................................................... 496

B.2.10 Interfaces............................................................................................................................... 496

B.2.11 Enums.................................................................................................................................... 497

B.2.12 Delegates............................................................................................................................... 498

B.2.13 Attributes............................................................................................................................... 498

B.3 Grammar extensions for unsafe code................................................................................................ 500

C. References....................................................................................................................................... 503


1. Introduction

C# (pronounced “See Sharp”) is a simple, modern, object-oriented, and type-safe programming language. C# has its roots in the C family of languages and will be immediately familiar to C, C++, and Java programmers. C# is standardized by ECMA International as the ECMA-334 standard and by ISO/IEC as the ISO/IEC 23270 standard. Microsoft’s C# compiler for the .NET Framework is a conforming implementation of both of these standards.

C# is an object-oriented language, but C# further includes support for component-oriented programming. Contemporary software design increasingly relies on software components in the form of self-contained and self-describing packages of functionality. Key to such components is that they present a programming model with properties, methods, and events; they have attributes that provide declarative information about the component; and they incorporate their own documentation. C# provides language constructs to directly support these concepts, making C# a very natural language in which to create and use software components.

Several C# features aid in the construction of robust and durable applications: Garbage collection automatically reclaims memory occupied by unused objects; exception handling provides a structured and extensible approach to error detection and recovery; and the type-safe design of the language makes it impossible to read from uninitialized variables, to index arrays beyond their bounds, or to perform unchecked type casts.

C# has a unified type system. All C# types, including primitive types such as int and double, inherit from a single root object type. Thus, all types share a set of common operations, and values of any type can be stored, transported, and operated upon in a consistent manner. Furthermore, C# supports both user-defined reference types and value types, allowing dynamic allocation of objects as well as in-line storage of lightweight structures.

To ensure that C# programs and libraries can evolve over time in a compatible manner, much emphasis has been placed on versioning in C#’s design. Many programming languages pay little attention to this issue, and, as a result, programs written in those languages break more often than necessary when newer versions of dependent libraries are introduced. Aspects of C#’s design that were directly influenced by versioning considerations include the separate virtual and override modifiers, the rules for method overload resolution, and support for explicit interface member declarations.

The rest of this chapter describes the essential features of the C# language. Although later chapters describe rules and exceptions in a detail-oriented and sometimes mathematical manner, this chapter strives for clarity and brevity at the expense of completeness. The intent is to provide the reader with an introduction to the language that will facilitate the writing of early programs and the reading of later chapters.

1.1 Hello world

The “Hello, World” program is traditionally used to introduce a programming language. Here it is in C#:

using System;

class Hello
{
   static void Main() {
      Console.WriteLine("Hello, World");
   }
}

C# source files typically have the file extension .cs. Assuming that the “Hello, World” program is stored in the file hello.cs, the program can be compiled with the Microsoft C# compiler using the command line

csc hello.cs

which produces an executable assembly named hello.exe. The output produced by this application when it is run is

Hello, World

The “Hello, World” program starts with a using directive that references the System namespace. Namespaces provide a hierarchical means of organizing C# programs and libraries. Namespaces contain types and other namespaces—for example, the System namespace contains a number of types, such as the Console class referenced in the program, and a number of other namespaces, such as IO and Collections. A using directive that references a given namespace enables unqualified use of the types that are members of that namespace. Because of the using directive, the program can use Console.WriteLine as shorthand for System.Console.WriteLine.

The Hello class declared by the “Hello, World” program has a single member, the method named Main. The Main method is declared with the static modifier. While instance methods can reference a particular enclosing object instance using the keyword this, static methods operate without reference to a particular object. By convention, a static method named Main serves as the entry point of a program.

The output of the program is produced by the WriteLine method of the Console class in the System namespace. This class is provided by the .NET Framework class libraries, which, by default, are automatically referenced by the Microsoft C# compiler. Note that C# itself does not have a separate runtime library. Instead, the .NET Framework is the runtime library of C#.

1.2 Program structure

The key organizational concepts in C# are programs, namespaces, types, members, and assemblies. C# programs consist of one or more source files. Programs declare types, which contain members and can be organized into namespaces. Classes and interfaces are examples of types. Fields, methods, properties, and events are examples of members. When C# programs are compiled, they are physically packaged into assemblies. Assemblies typically have the file extension .exe or .dll, depending on whether they implement applications or libraries.

The example

using System;

namespace Acme.Collections
{
   public class Stack
   {
      Entry top;

      public void Push(object data) {
         top = new Entry(top, data);
      }

      public object Pop() {
         if (top == null) throw new InvalidOperationException();
         object result = top.data;
         top = top.next;
         return result;
      }

      class Entry
      {
         public Entry next;
         public object data;

         public Entry(Entry next, object data) {
            this.next = next;
            this.data = data;
         }
      }
   }
}

declares a class named Stack in a namespace called Acme.Collections. The fully qualified name of this class is Acme.Collections.Stack. The class contains several members: a field named top, two methods named Push and Pop, and a nested class named Entry. The Entry class further contains three members: a field named next, a field named data, and a constructor. Assuming that the source code of the example is stored in the file acme.cs, the command line

csc /t:library acme.cs

compiles the example as a library (code without a Main entry point) and produces an assembly named acme.dll.

Assemblies contain executable code in the form of Intermediate Language (IL) instructions, and symbolic information in the form of metadata. Before it is executed, the IL code in an assembly is automatically converted to processor-specific code by the Just-In-Time (JIT) compiler of .NET Common Language Runtime.

Because an assembly is a self-describing unit of functionality containing both code and metadata, there is no need for #include directives and header files in C#. The public types and members contained in a particular assembly are made available in a C# program simply by referencing that assembly when compiling the program. For example, this program uses the Acme.Collections.Stack class from the acme.dll assembly:

using System;
using Acme.Collections;

class Test
{
   static void Main() {
      Stack s = new Stack();
      s.Push(1);
      s.Push(10);
      s.Push(100);
      Console.WriteLine(s.Pop());
      Console.WriteLine(s.Pop());
      Console.WriteLine(s.Pop());
   }
}

If the program is stored in the file test.cs, when test.cs is compiled, the acme.dll assembly can be referenced using the compiler’s /r option:

csc /r:acme.dll test.cs

This creates an executable assembly named test.exe, which, when run, produces the output:

100
10
1

C# permits the source text of a program to be stored in several source files. When a multi-file C# program is compiled, all of the source files are processed together, and the source files can freely reference each other—conceptually, it is as if all the source files were concatenated into one large file before being processed. Forward declarations are never needed in C# because, with very few exceptions, declaration order is insignificant. C# does not limit a source file to declaring only one public type nor does it require the name of the source file to match a type declared in the source file.

1.3 Types and variables

There are two kinds of types in C#: value types and reference types. Variables of value types directly contain their data whereas variables of 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 (except in the case of ref and out parameter variables).

C#’s value types are further divided into simple types, enum types, struct types, and nullable types, and C#’s reference types are further divided into class types, interface types, array types, and delegate types.

The following table provides an overview of C#’s type system.

 

Category

Description

Value
types

Simple types

Signed integral: sbyte, short, int, long

Unsigned integral: byte, ushort, uint, ulong

Unicode characters: char

IEEE floating point: float, double

High-precision decimal: decimal

Boolean: bool

Enum types

User-defined types of the form enum E {...}

Struct types

User-defined types of the form struct S {...}

Nullable types

Extensions of all other value types with a null value

Reference
types

Class types

Ultimate base class of all other types: object

Unicode strings: string

User-defined types of the form class C {...}

Interface types

User-defined types of the form interface I {...}

Array types

Single- and multi-dimensional, for example, int[] and int[,]

Delegate types

User-defined types of the form e.g. delegate int D(...)

 

The eight integral types provide support for 8-bit, 16-bit, 32-bit, and 64-bit values in signed or unsigned form.

The two floating point types, float and double, are represented using the 32-bit single-precision and 64-bit double-precision IEEE 754 formats.

The decimal type is a 128-bit data type suitable for financial and monetary calculations.

C#’s bool type is used to represent boolean values—values that are either true or false.

Character and string processing in C# uses Unicode encoding. The char type represents a UTF-16 code unit, and the string type represents a sequence of UTF-16 code units.

The following table summarizes C#’s numeric types.

 

Category

Bits

Type

Range/Precision

Signed integral

8

sbyte

–128...127

16

short

–32,768...32,767

32

int

–2,147,483,648...2,147,483,647

64

long

–9,223,372,036,854,775,808...9,223,372,036,854,775,807

Unsigned integral

8

byte

0...255

16

ushort

0...65,535

32

uint

0...4,294,967,295

64

ulong

0...18,446,744,073,709,551,615

Floating point

32

float

1.5 × 10−45 to 3.4 × 1038, 7-digit precision

64

double

5.0 × 10−324 to 1.7 × 10308, 15-digit precision

Decimal

128

decimal

1.0 × 10−28 to 7.9 × 1028, 28-digit precision

 

C# programs use type declarations to create new types. A type declaration specifies the name and the members of the new type. Five of C#’s categories of types are user-definable: class types, struct types, interface types, enum types, and delegate types.

A class type defines a data structure that contains data members (fields) and function members (methods, properties, and others). Class types support single inheritance and polymorphism, mechanisms whereby derived classes can extend and specialize base classes.

A struct type is similar to a class type in that it represents a structure with data members and function members. However, unlike classes, structs are value types and do not require heap allocation. Struct types do not support user-specified inheritance, and all struct types implicitly inherit from type object.

An interface type defines a contract as a named set of public function members. A class or struct that implements an interface must provide implementations of the interface’s function members. An interface may inherit from multiple base interfaces, and a class or struct may implement multiple interfaces.

A delegate type represents references to methods with a particular parameter list and return type. Delegates make it possible to treat methods as entities that can be assigned to variables and passed as parameters. Delegates are similar to the concept of function pointers found in some other languages, but unlike function pointers, delegates are object-oriented and type-safe.

Class, struct, interface and delegate types all support generics, whereby they can be parameterized with other types.

An enum type is a distinct type with named constants. Every enum type has an underlying type, which must be one of the eight integral types. The set of values of an enum type is the same as the set of values of the underlying type.

C# supports single- and multi-dimensional arrays of any type. Unlike the types listed above, array types do not have to be declared before they can be used. Instead, array types are constructed by following a type name with square brackets. For example, int[] is a single-dimensional array of int, int[,] is a two-dimensional array of int, and int[][] is a single-dimensional array of single-dimensional arrays of int.

Nullable types also do not have to be declared before they can be used. For each non-nullable value type T there is a corresponding nullable type T?, which can hold an additional value null. For instance, int? is a type that can hold any 32 bit integer or the value null.

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. In the following example, an int value is converted to object and back again to int.

using System;

class Test
{
   static void Main() {
      int i = 123;
      object o = i;        // Boxing
      int j = (int)o;      // Unboxing
   }
}

When a value of a value type is converted to type object, an object instance, also called a “box,” is allocated to hold the value, and the value is copied into that box. Conversely, when an object reference is cast to a value type, a check is made that the referenced object is a box of the correct value type, and, if the check succeeds, the value in the box is copied out.

C#’s unified type system effectively means that value types can become objects “on demand.” Because of the unification, general-purpose libraries that use type object can be used with both reference types and value types.

There are several kinds of variables in C#, including fields, array elements, local variables, and parameters. Variables represent storage locations, and every variable has a type that determines what values can be stored in the variable, as shown by the following table.

 

Type of Variable

Possible Contents

Non-nullable value type

A value of that exact type

Nullable value type

A null value or a value of that exact type

object

A null reference, a reference to an object of any reference type, or a reference to a boxed value of any value type

Class type

A null reference, a reference to an instance of that class type, or a reference to an instance of a class derived from that class type

Interface type

A null reference, a reference to an instance of a class type that implements that interface type, or a reference to a boxed value of a value type that implements that interface type

Array type

A null reference, a reference to an instance of that array type, or a reference to an instance of a compatible array type

Delegate type

A null reference or a reference to an instance of that delegate type

 

1.4 Expressions

Expressions are constructed from operands and operators. The operators of an expression indicate which operations to apply to the operands. Examples of operators include +, -, *, /, and new. Examples of operands include literals, fields, local variables, and expressions.

When an expression contains multiple operators, the precedence of the operators controls the order in which the individual operators are evaluated. For example, the expression x + y * z is evaluated as x + (y * z) because the * operator has higher precedence than the + operator.

Most operators can be overloaded. Operator overloading permits user-defined operator implementations to be specified for operations where one or both of the operands are of a user-defined class or struct type.

The following table summarizes C#’s operators, listing the operator categories in order of precedence from highest to lowest. Operators in the same category have equal precedence.

 

 

Category

Expression

Description

Primary

x.m

Member access

x(...)

Method and delegate invocation

x[...]

Array and indexer access

x++

Post-increment

x--

Post-decrement

new T(...)

Object and delegate creation

new T(...){...}

Object creation with initializer

new {...}

Anonymous object initializer

new T[...]

Array creation

typeof(T)

Obtain System.Type object for T

checked(x)

Evaluate expression in checked context

unchecked(x)

Evaluate expression in unchecked context

default(T)

Obtain default value of type T

delegate {...}

Anonymous function (anonymous method)

Unary

+x

Identity

-x

Negation

!x

Logical negation

~x

Bitwise negation

++x

Pre-increment

--x

Pre-decrement

(T)x

Explicitly convert x to type T

await x

Asynchronously wait for x to complete

Multiplicative

x * y

Multiplication

x / y

Division

x % y

Remainder

 

Additive

x + y

Addition, string concatenation, delegate combination

x – y

Subtraction, delegate removal

Shift

x << y

Shift left

x >> y

Shift right

Relational and type testing

x < y

Less than

x > y

Greater than

x <= y

Less than or equal

x >= y

Greater than or equal

x is T

Return true if x is a T, false otherwise

x as T

Return x typed as T, or null if x is not a T

Equality

x == y

Equal

x != y

Not equal

Logical AND

x & y

Integer bitwise AND, boolean logical AND

Logical XOR

x ^ y

Integer bitwise XOR, boolean logical XOR

Logical OR

x | y

Integer bitwise OR, boolean logical OR

Conditional AND

x && y

Evaluates y only if x is true

Conditional OR

x || y

Evaluates y only if x is false

Null coalescing

X ?? y

Evaluates to y if x is null, to x otherwise

Conditional

x ? y : z

Evaluates y if x is true, z if x is false

Assignment or anonymous function

x = y

Assignment

x op= y

Compound assignment; supported operators are

*=   /=   %=   +=   -=   <<=   >>=   &=   ^=   |=

(T x) => y

Anonymous function (lambda expression)

 

1.5 Statements

The actions of a program are expressed using statements. C# supports several different kinds of statements, a number of which are defined in terms of embedded statements.

A block permits multiple statements to be written in contexts where a single statement is allowed. A block consists of a list of statements written between the delimiters { and }.

Declaration statements are used to declare local variables and constants.

Expression statements are used to evaluate expressions. Expressions that can be used as statements include method invocations, object allocations using the new operator, assignments using = and the compound assignment operators, increment and decrement operations using the ++ and -- operators and await expressions.

Selection statements are used to select one of a number of possible statements for execution based on the value of some expression. In this group are the if and switch statements.

Iteration statements are used to repeatedly execute an embedded statement. In this group are the while, do, for, and foreach statements.

Jump statements are used to transfer control. In this group are the break, continue, goto, throw, return, and yield statements.

The try...catch statement is used to catch exceptions that occur during execution of a block, and the try...finally statement is used to specify finalization code that is always executed, whether an exception occurred or not.

The checked and unchecked statements are used to control the overflow checking context for integral-type arithmetic operations and conversions.

The lock statement is used to obtain the mutual-exclusion lock for a given object, execute a statement, and then release the lock.

The using statement is used to obtain a resource, execute a statement, and then dispose of that resource.

The following table lists C#’s statements and provides an example for each one.

 

Statement

Example

Local variable declaration

static void Main() {
   int a;
   int b = 2, c = 3;
   a = 1;
   Console.WriteLine(a + b + c);
}

Local constant declaration

static void Main() {
   const float pi = 3.1415927f;
   const int r = 25;
   Console.WriteLine(pi * r * r);
}

Expression statement

static void Main() {
   int i;
   i = 123;                // Expression statement
   Console.WriteLine(i);   // Expression statement
   i++;                    // Expression statement
   Console.WriteLine(i);   // Expression statement
}

if statement

static void Main(string[] args) {
   if (args.Length == 0) {
      Console.WriteLine("No arguments");
   }
   else {
      Console.WriteLine("One or more arguments");
   }
}

 

switch statement

static void Main(string[] args) {
   int n = args.Length;
   switch (n) {
      case 0:
         Console.WriteLine("No arguments");
         break;
      case 1:
         Console.WriteLine("One argument");
         break;
      default:
         Console.WriteLine("{0} arguments", n);
         break;
      }
   }
}

while statement

static void Main(string[] args) {
   int i = 0;
   while (i < args.Length) {
      Console.WriteLine(args[i]);
      i++;
   }
}

do statement

static void Main() {
   string s;
   do {
      s = Console.ReadLine();
      if (s != null) Console.WriteLine(s);
   } while (s != null);
}

for statement

static void Main(string[] args) {
   for (int i = 0; i < args.Length; i++) {
      Console.WriteLine(args[i]);
   }
}

foreach statement

static void Main(string[] args) {
   foreach (string s in args) {
      Console.WriteLine(s);
   }
}

break statement

static void Main() {
   while (true) {
      string s = Console.ReadLine();
      if (s == null) break;
      Console.WriteLine(s);
   }
}

continue statement

static void Main(string[] args) {
   for (int i = 0; i < args.Length; i++) {
      if (args[i].StartsWith("/")) continue;
      Console.WriteLine(args[i]);
   }
}

 

goto statement

static void Main(string[] args) {
   int i = 0;
   goto check;
   loop:
   Console.WriteLine(args[i++]);
   check:
   if (i < args.Length) goto loop;
}

return statement

static int Add(int a, int b) {
   return a + b;
}

static void Main() {
   Console.WriteLine(Add(1, 2));
   return;
}

yield statement

static IEnumerable<int> Range(int from, int to) {
   for (int i = from; i < to; i++) {
      yield return i;
   }
   yield break;
}

static void Main() {
   foreach (int x in Range(-10,10)) {
      Console.WriteLine(x);
   }
}

throw and try
statements

static double Divide(double x, double y) {
   if (y == 0) throw new DivideByZeroException();
   return x / y;
}

static void Main(string[] args) {
   try {
      if (args.Length != 2) {
         throw new Exception("Two numbers required");
      }
      double x = double.Parse(args[0]);
      double y = double.Parse(args[1]);
      Console.WriteLine(Divide(x, y));
   }
   catch (Exception e) {
      Console.WriteLine(e.Message);
   }
   finally {
      Console.WriteLine(“Good bye!”);
   }
}

checked and unchecked statements

static void Main() {
   int i = int.MaxValue;
   checked {
      Console.WriteLine(i + 1);     // Exception
   }
   unchecked {
      Console.WriteLine(i + 1);     // Overflow
   }
}

 

lock statement

class Account
{
   decimal balance;

   public void Withdraw(decimal amount) {
      lock (this) {
         if (amount > balance) {
            throw new Exception("Insufficient funds");
         }
         balance -= amount;
      }
   }
}

using statement

static void Main() {
   using (TextWriter w = File.CreateText("test.txt")) {
      w.WriteLine("Line one");
      w.WriteLine("Line two");
      w.WriteLine("Line three");
   }
}

 

1.6 Classes and objects

Classes are the most fundamental of C#’s types. A class is a data structure that combines state (fields) and actions (methods and other function members) in a single unit. A class provides a definition for dynamically created instances of the class, also known as objects. Classes support inheritance and polymorphism, mechanisms whereby derived classes can extend and specialize base classes.

New classes are created using class declarations. A class declaration starts with a header that specifies the attributes and modifiers of the class, the name of the class, the base class (if given), and the interfaces implemented by the class. The header is followed by the class body, which consists of a list of member declarations written between the delimiters { and }.

The following is a declaration of a simple class named Point:

public class Point
{
   public int x, y;

   public Point(int x, int y) {
      this.x = x;
      this.y = y;
   }
}

Instances of classes are created using the new operator, which allocates memory for a new instance, invokes a constructor to initialize the instance, and returns a reference to the instance. The following statements create two Point objects and store references to those objects in two variables:

Point p1 = new Point(0, 0);
Point p2 = new Point(10, 20);

The memory occupied by an object is automatically reclaimed when the object is no longer in use. It is neither necessary nor possible to explicitly deallocate objects in C#.

1.6.1 Members

The members of a class are either static members or instance members. Static members belong to classes, and instance members belong to objects (instances of classes).

The following table provides an overview of the kinds of members a class can contain.

 

Member

Description

Constants

Constant values associated with the class

Fields

Variables of the class

Methods

Computations and actions that can be performed by the class

Properties

Actions associated with reading and writing named properties of the class

Indexers

Actions associated with indexing instances of the class like an array

Events

Notifications that can be generated by the class

Operators

Conversions and expression operators supported by the class

Constructors

Actions required to initialize instances of the class or the class itself

Destructors

Actions to perform before instances of the class are permanently discarded

Types

Nested types declared by the class

 

1.6.2 Accessibility

Each member of a class has an associated accessibility, which controls the regions of program text that are able to access the member. There are five possible forms of accessibility. These are summarized in the following table.

 

Accessibility

Meaning

public

Access not limited

protected

Access limited to this class or classes derived from this class

internal

Access limited to this program

protected internal

Access limited to this program or classes derived from this class

private

Access limited to this class

 

1.6.3 Type parameters

A class definition may specify a set of type parameters by following the class name with angle brackets enclosing a list of type parameter names. The type parameters can the be used in the body of the class declarations to define the members of the class. In the following example, the type parameters of Pair are TFirst and TSecond:

public class Pair<TFirst,TSecond>
{
   public TFirst First;

   public TSecond Second;
}

A class type that is declared to take type parameters is called a generic class type. Struct, interface and delegate types can also be generic.

When the generic class is used, type arguments must be provided for each of the type parameters:

Pair<int,string> pair = new Pair<int,string> { First = 1, Second = “two” };
int i = pair.First;     // TFirst is int
string s = pair.Second; // TSecond is string

A generic type with type arguments provided, like Pair<int,string> above, is called a constructed type.

1.6.4 Base classes

A class declaration may specify a base class by following the class name and type parameters with a colon and the name of the base class. Omitting a base class specification is the same as deriving from type object. In the following example, the base class of Point3D is Point, and the base class of Point is object:

public class Point
{
   public int x, y;

   public Point(int x, int y) {
      this.x = x;
      this.y = y;
   }
}

public class Point3D: Point
{
   public int z;

   public Point3D(int x, int y, int z): base(x, y) {
      this.z = z;
   }
}

A class inherits the members of its base class. Inheritance means that a class implicitly contains all members of its base class, except for the instance and static constructors, and the destructors of the base class. A derived class can add new members to those it inherits, but it cannot remove the definition of an inherited member. In the previous example, Point3D inherits the x and y fields from Point, and every Point3D instance contains three fields, x, y, and z.

An implicit conversion exists from a class type to any of its base class types. Therefore, a variable of a class type can reference an instance of that class or an instance of any derived class. For example, given the previous class declarations, a variable of type Point can reference either a Point or a Point3D:

Point a = new Point(10, 20);
Point b = new Point3D(10, 20, 30);

1.6.5 Fields

A field is a variable that is associated with a class or with an instance of a class.

A field declared with the static modifier defines a static field. A static field identifies exactly one storage location. No matter how many instances of a class are created, there is only ever one copy of a static field.

A field declared without the static modifier defines an instance field. Every instance of a class contains a separate copy of all the instance fields of that class.

In the following example, each instance of the Color class has a separate copy of the r, g, and b instance fields, but there is only one copy of the Black, White, Red, Green, and Blue static fields:

public class Color
{
   public static readonly Color Black = new Color(0, 0, 0);
   public static readonly Color White = new Color(255, 255, 255);
   public static readonly Color Red = new Color(255, 0, 0);
   public static readonly Color Green = new Color(0, 255, 0);
   public static readonly Color Blue = new Color(0, 0, 255);

   private byte r, g, b;

   public Color(byte r, byte g, byte b) {
      this.r = r;
      this.g = g;
      this.b = b;
   }
}

As shown in the previous example, read-only fields may be declared with a readonly modifier. Assignment to a readonly field can only occur as part of the field’s declaration or in a constructor in the same class.

1.6.6 Methods

A method is a member that implements a computation or action that can be performed by an object or class. Static methods are accessed through the class. Instance methods are accessed through instances of the class.

Methods have a (possibly empty) list of parameters, which represent values or variable references passed to the method, and a return type, which specifies the type of the value computed and returned by the method. A method’s return type is void if it does not return a value.

Like types, methods may also have a set of type parameters, for which type arguments must be specified when the method is called. Unlike types, the type arguments can often be inferred from the arguments of a method call and need not be explicitly given.

The signature of a method must be unique in the class in which the method is declared. The signature of a method consists of the name of the method, the number of type parameters and the number, modifiers, and types of its parameters. The signature of a method does not include the return type.

1.6.6.1 Parameters

Parameters are used to pass values or variable references to methods. The parameters of a method get their actual values from the arguments that are specified when the method is invoked. There are four kinds of parameters: value parameters, reference parameters, output parameters, and parameter arrays.

A value parameter is used for input parameter passing. A value parameter corresponds to a local variable that gets its initial value from the argument that was passed for the parameter. Modifications to a value parameter do not affect the argument that was passed for the parameter.

Value parameters can be optional, by specifying a default value so that corresponding arguments can be omitted.

A reference parameter is used for both input and output parameter passing. The argument passed for a reference parameter must be a variable, and during execution of the method, the reference parameter represents the same storage location as the argument variable. A reference parameter is declared with the ref modifier. The following example shows the use of ref parameters.

using System;

class Test
{
   static void Swap(ref int x, ref int y) {
      int temp = x;
      x = y;
      y = temp;
   }

   static void Main() {
      int i = 1, j = 2;
      Swap(ref i, ref j);
      Console.WriteLine("{0} {1}", i, j);       // Outputs "2 1"
   }
}

An output parameter is used for output parameter passing. An output parameter is similar to a reference parameter except that the initial value of the caller-provided argument is unimportant. An output parameter is declared with the out modifier. The following example shows the use of out parameters.

using System;

class Test
{
   static void Divide(int x, int y, out int result, out int remainder) {
      result = x / y;
      remainder = x % y;
   }

   static void Main() {
      int res, rem;
      Divide(10, 3, out res, out rem);
      Console.WriteLine("{0} {1}", res, rem);   // Outputs "3 1"
   }
}

A parameter array permits a variable number of arguments to be passed to a method. A parameter array is declared with the params modifier. Only the last parameter of a method can be a parameter array, and the type of a parameter array must be a single-dimensional array type. The Write and WriteLine methods of the System.Console class are good examples of parameter array usage. They are declared as follows.

public class Console
{
   public static void Write(string fmt, params object[] args) {...}

   public static void WriteLine(string fmt, params object[] args) {...}

   ...
}

Within a method that uses a parameter array, the parameter array behaves exactly like a regular parameter of an array type. However, in an invocation of a method with a parameter array, it is possible to pass either a single argument of the parameter array type or any number of arguments of the element type of the parameter array. In the latter case, an array instance is automatically created and initialized with the given arguments. This example

Console.WriteLine("x={0} y={1} z={2}", x, y, z);

is equivalent to writing the following.

string s = "x={0} y={1} z={2}";
object[] args = new object[3];
args[0] = x;
args[1] = y;
args[2] = z;
Console.WriteLine(s, args);

1.6.6.2 Method body and local variables

A method’s body specifies the statements to execute when the method is invoked.

A method body can declare variables that are specific to the invocation of the method. Such variables are called local variables. A local variable declaration specifies a type name, a variable name, and possibly an initial value. The following example declares a local variable i with an initial value of zero and a local variable j with no initial value.

using System;

class Squares
{
   static void Main() {
      int i = 0;
      int j;
      while (i < 10) {
         j = i * i;
         Console.WriteLine("{0} x {0} = {1}", i, j);
         i = i + 1;
      }
   }
}

C# requires a local variable to be definitely assigned before its value can be obtained. For example, if the declaration of the previous i did not include an initial value, the compiler would report an error for the subsequent usages of i because i would not be definitely assigned at those points in the program.

A method can use return statements to return control to its caller. In a method returning void, return statements cannot specify an expression. In a method returning non-void, return statements must include an expression that computes the return value.

1.6.6.3 Static and instance methods

A method declared with a static modifier is a static method. A static method does not operate on a specific instance and can only directly access static members.

A method declared without a static modifier is an instance method. An instance method operates on a specific instance and can access both static and instance members. The instance on which an instance method was invoked can be explicitly accessed as this. It is an error to refer to this in a static method.

The following Entity class has both static and instance members.

class Entity
{
   static int nextSerialNo;

   int serialNo;

   public Entity() {
      serialNo = nextSerialNo++;
   }

   public int GetSerialNo() {
      return serialNo;
   }

   public static int GetNextSerialNo() {
      return nextSerialNo;
   }

   public static void SetNextSerialNo(int value) {
      nextSerialNo = value;
   }
}

Each Entity instance contains a serial number (and presumably some other information that is not shown here). The Entity constructor (which is like an instance method) initializes the new instance with the next available serial number. Because the constructor is an instance member, it is permitted to access both the serialNo instance field and the nextSerialNo static field.

The GetNextSerialNo and SetNextSerialNo static methods can access the nextSerialNo static field, but it would be an error for them to directly access the serialNo instance field.

The following example shows the use of the Entity class.

using System;

class Test
{
   static void Main() {
      Entity.SetNextSerialNo(1000);

      Entity e1 = new Entity();
      Entity e2 = new Entity();

      Console.WriteLine(e1.GetSerialNo());            // Outputs "1000"
      Console.WriteLine(e2.GetSerialNo());            // Outputs "1001"
      Console.WriteLine(Entity.GetNextSerialNo());    // Outputs "1002"
   }
}

Note that the SetNextSerialNo and GetNextSerialNo static methods are invoked on the class whereas the GetSerialNo instance method is invoked on instances of the class.

1.6.6.4 Virtual, override, and abstract methods

When an instance method declaration includes a virtual modifier, the method is said to be a virtual method. When no virtual modifier is present, the method is said to be a non-virtual method.

When a virtual method is invoked, the run-time type of the instance for which that invocation takes place determines the actual method implementation to invoke. In a nonvirtual method invocation, the compile-time type of the instance is the determining factor.

A virtual method can be overridden in a derived class. When an instance method declaration includes an override modifier, the method overrides an inherited virtual method with the same signature. Whereas a virtual method declaration introduces a new method, an override method declaration specializes an existing inherited virtual method by providing a new implementation of that method.

An abstract method is a virtual method with no implementation. An abstract method is declared with the abstract modifier and is permitted only in a class that is also declared abstract. An abstract method must be overridden in every non-abstract derived class.

The following example declares an abstract class, Expression, which represents an expression tree node, and three derived classes, Constant, VariableReference, and Operation, which implement expression tree nodes for constants, variable references, and arithmetic operations. (This is similar to, but not to be confused with the expression tree types introduced in section §4.6).

using System;
using System.Collections;

public abstract class Expression
{
   public abstract double Evaluate(Hashtable vars);
}

public class Constant: Expression
{
   double value;

   public Constant(double value) {
      this.value = value;
   }

   public override double Evaluate(Hashtable vars) {
      return value;
   }
}

public class VariableReference: Expression
{
   string name;

   public VariableReference(string name) {
      this.name = name;
   }

   public override double Evaluate(Hashtable vars) {
      object value = vars[name];
      if (value == null) {
         throw new Exception("Unknown variable: " + name);
      }
      return Convert.ToDouble(value);
   }
}

public class Operation: Expression
{
   Expression left;
   char op;
   Expression right;

   public Operation(Expression left, char op, Expression right) {
      this.left = left;
      this.op = op;
      this.right = right;
   }

   public override double Evaluate(Hashtable vars) {
      double x = left.Evaluate(vars);
      double y = right.Evaluate(vars);
      switch (op) {
         case '+': return x + y;
         case '-': return x - y;
         case '*': return x * y;
         case '/': return x / y;
      }
      throw new Exception("Unknown operator");
   }
}

The previous four classes can be used to model arithmetic expressions. For example, using instances of these classes, the expression x + 3 can be represented as follows.

Expression e = new Operation(
   new VariableReference("x"),
   '+',
   new Constant(3));

The Evaluate method of an Expression instance is invoked to evaluate the given expression and produce a double value. The method takes as an argument a Hashtable that contains variable names (as keys of the entries) and values (as values of the entries). The Evaluate method is a virtual abstract method, meaning that non-abstract derived classes must override it to provide an actual implementation.

A Constant’s implementation of Evaluate simply returns the stored constant. A VariableReference’s implementation looks up the variable name in the hashtable and returns the resulting value. An Operation’s implementation first evaluates the left and right operands (by recursively invoking their Evaluate methods) and then performs the given arithmetic operation.

The following program uses the Expression classes to evaluate the expression x * (y + 2) for different values of x and y.

using System;
using System.Collections;

class Test
{
   static void Main() {

      Expression e = new Operation(
         new VariableReference("x"),
         '*',
         new Operation(
            new VariableReference("y"),
            '+',
            new Constant(2)
         )
      );

      Hashtable vars = new Hashtable();

      vars["x"] = 3;
      vars["y"] = 5;
      Console.WriteLine(e.Evaluate(vars));      // Outputs "21"

      vars["x"] = 1.5;
      vars["y"] = 9;
      Console.WriteLine(e.Evaluate(vars));      // Outputs "16.5"
   }
}

1.6.6.5 Method overloading

Method overloading permits multiple methods in the same class to have the same name as long as they have unique signatures. When compiling an invocation of an overloaded method, the compiler uses overload resolution to determine the specific method to invoke. Overload resolution finds the one method that best matches the arguments or reports an error if no single best match can be found. The following example shows overload resolution in effect. The comment for each invocation in the Main method shows which method is actually invoked.

class Test
{
   static void F() {
      Console.WriteLine("F()");
   }

   static void F(object x) {
      Console.WriteLine("F(object)");
   }

   static void F(int x) {
      Console.WriteLine("F(int)");
   }

   static void F(double x) {
      Console.WriteLine("F(double)");
   }

   static void F<T>(T x) {
      Console.WriteLine("F<T>(T)");
   }

   static void F(double x, double y) {
      Console.WriteLine("F(double, double)");
   }

   static void Main() {
      F();              // Invokes F()
      F(1);             // Invokes F(int)
      F(1.0);           // Invokes F(double)
      F("abc");         // Invokes F(object)
      F((double)1);     // Invokes F(double)
      F((object)1);     // Invokes F(object)
      F<int>(1);        // Invokes F<T>(T)
      F(1, 1);          // Invokes F(double, double)  }
}

As shown by the example, a particular method can always be selected by explicitly casting the arguments to the exact parameter types and/or explicitly supplying type arguments.

1.6.7 Other function members

Members that contain executable code are collectively known as the function members of a class. The preceding section describes methods, which are the primary kind of function members. This section describes the other kinds of function members supported by C#: constructors, properties, indexers, events, operators, and destructors.

The following table shows a generic class called List<T>, which implements a growable list of objects. The class contains several examples of the most common kinds of function members.

public class List<T>
{

   const int defaultCapacity = 4;

Constant

   T[] items;
   int count;

Fields

   public List(int capacity = defaultCapacity) {
      items = new T[capacity];
   }

Constructors

   public int Count {
      get { return count; }
   }

   public int Capacity {
      get {
         return items.Length;
      }
      set {
         if (value < count) value = count;
         if (value != items.Length) {
            T[] newItems = new T[value];
            Array.Copy(items, 0, newItems, 0, count);
            items = newItems;
         }
      }
   }

Properties

 

   public T this[int index] {
      get {
         return items[index];
      }
      set {
         items[index] = value;
         OnChanged();
      }
   }

Indexer

   public void Add(T item) {
      if (count == Capacity) Capacity = count * 2;
      items[count] = item;
      count++;
      OnChanged();
   }

   protected virtual void OnChanged() {
      if (Changed != null) Changed(this, EventArgs.Empty);
   }

   public override bool Equals(object other) {
      return Equals(this, other as List<T>);
   }

   static bool Equals(List<T> a, List<T> b) {
      if (a == null) return b == null;
      if (b == null || a.count != b.count) return false;
      for (int i = 0; i < a.count; i++) {
         if (!object.Equals(a.items[i], b.items[i])) {
            return false;
         }
      }
      return true;
   }

Methods

   public event EventHandler Changed;

Event

   public static bool operator ==(List<T> a, List<T> b) {
      return Equals(a, b);
   }

   public static bool operator !=(List<T> a, List<T> b) {
      return !Equals(a, b);
   }

Operators

}

 

1.6.7.1 Constructors

C# supports both instance and static constructors. An instance constructor is a member that implements the actions required to initialize an instance of a class. A static constructor is a member that implements the actions required to initialize a class itself when it is first loaded.

A constructor is declared like a method with no return type and the same name as the containing class. If a constructor declaration includes a static modifier, it declares a static constructor. Otherwise, it declares an instance constructor.

Instance constructors can be overloaded. For example, the List<T> class declares two instance constructors, one with no parameters and one that takes an int parameter. Instance constructors are invoked using the new operator. The following statements allocate two List<string> instances using each of the constructors of the List class.

List<string> list1 = new List<string>();
List<string> list2 = new List<string>(10);

Unlike other members, instance constructors are not inherited, and a class has no instance constructors other than those actually declared in the class. If no instance constructor is supplied for a class, then an empty one with no parameters is automatically provided.

1.6.7.2 Properties

Properties are a natural extension of fields. Both are named members with associated types, and the syntax for accessing fields and properties is the same. However, unlike fields, properties do not denote storage locations. Instead, properties have accessors that specify the statements to be executed when their values are read or written.

A property is declared like a field, except that the declaration ends with a get accessor and/or a set accessor written between the delimiters { and } instead of ending in a semicolon. A property that has both a get accessor and a set accessor is a read-write property, a property that has only a get accessor is a read-only property, and a property that has only a set accessor is a write-only property.

A get accessor corresponds to a parameterless method with a return value of the property type. Except as the target of an assignment, when a property is referenced in an expression, the get accessor of the property is invoked to compute the value of the property.

A set accessor corresponds to a method with a single parameter named value and no return type. When a property is referenced as the target of an assignment or as the operand of ++ or --, the set accessor is invoked with an argument that provides the new value.

The List<T> class declares two properties, Count and Capacity, which are read-only and read-write, respectively. The following is an example of use of these properties.

List<string> names = new List<string>();
names.Capacity = 100;         // Invokes set accessor
int i = names.Count;          // Invokes get accessor
int j = names.Capacity;       // Invokes get accessor

Similar to fields and methods, C# supports both instance properties and static properties. Static properties are declared with the static modifier, and instance properties are declared without it.

The accessor(s) of a property can be virtual. When a property declaration includes a virtual, abstract, or override modifier, it applies to the accessor(s) of the property.

1.6.7.3 Indexers

An indexer is a member that enables objects to be indexed in the same way as an array. An indexer is declared like a property except that the name of the member is this followed by a parameter list written between the delimiters [ and ]. The parameters are available in the accessor(s) of the indexer. Similar to properties, indexers can be read-write, read-only, and write-only, and the accessor(s) of an indexer can be virtual.

The List class declares a single read-write indexer that takes an int parameter. The indexer makes it possible to index List instances with int values. For example

List<string> names = new List<string>();
names.Add("Liz");
names.Add("Martha");
names.Add("Beth");
for (int i = 0; i < names.Count; i++) {
   string s = names[i];
   names[i] = s.ToUpper();
}

Indexers can be overloaded, meaning that a class can declare multiple indexers as long as the number or types of their parameters differ.

1.6.7.4 Events

An event is a member that enables a class or object to provide notifications. An event is declared like a field except that the declaration includes an event keyword and the type must be a delegate type.

Within a class that declares an event member, the event behaves just like a field of a delegate type (provided the event is not abstract and does not declare accessors). The field stores a reference to a delegate that represents the event handlers that have been added to the event. If no event handles are present, the field is null.

The List<T> class declares a single event member called Changed, which indicates that a new item has been added to the list. The Changed event is raised by the OnChanged virtual method, which first checks whether the event is null (meaning that no handlers are present). The notion of raising an event is precisely equivalent to invoking the delegate represented by the event—thus, there are no special language constructs for raising events.

Clients react to events through event handlers. Event handlers are attached using the += operator and removed using the -= operator. The following example attaches an event handler to the Changed event of a List<string>.

using System;

class Test
{
   static int changeCount;

   static void ListChanged(object sender, EventArgs e) {
      changeCount++;
   }

   static void Main() {
      List<string> names = new List<string>();
      names.Changed += new EventHandler(ListChanged);
      names.Add("Liz");
      names.Add("Martha");
      names.Add("Beth");
      Console.WriteLine(changeCount);     // Outputs "3"
   }
}

For advanced scenarios where control of the underlying storage of an event is desired, an event declaration can explicitly provide add and remove accessors, which are somewhat similar to the set accessor of a property.

1.6.7.5 Operators

An operator is a member that defines the meaning of applying a particular expression operator to instances of a class. Three kinds of operators can be defined: unary operators, binary operators, and conversion operators. All operators must be declared as public and static.

The List<T> class declares two operators, operator == and operator !=, and thus gives new meaning to expressions that apply those operators to List instances. Specifically, the operators define equality of two List<T> instances as comparing each of the contained objects using their Equals methods. The following example uses the == operator to compare two List<int> instances.

using System;

class Test
{
   static void Main() {
      List<int> a = new List<int>();
      a.Add(1);
      a.Add(2);
      List<int> b = new List<int>();
      b.Add(1);
      b.Add(2);
      Console.WriteLine(a == b);    // Outputs "True"
      b.Add(3);
      Console.WriteLine(a == b);    // Outputs "False"
   }
}

The first Console.WriteLine outputs True because the two lists contain the same number of objects with the same values in the same order. Had List<T> not defined operator ==, the first Console.WriteLine would have output False because a and b reference different List<int> instances.

1.6.7.6 Destructors

A destructor is a member that implements the actions required to destruct an instance of a class. Destructors cannot have parameters, they cannot have accessibility modifiers, and they cannot be invoked explicitly. The destructor for an instance is invoked automatically during garbage collection.

The garbage collector is allowed wide latitude in deciding when to collect objects and run destructors. Specifically, the timing of destructor invocations is not deterministic, and destructors may be executed on any thread. For these and other reasons, classes should implement destructors only when no other solutions are feasible.

The using statement provides a better approach to object destruction.

1.7 Structs

Like classes, structs are data structures that can contain data members and function members, but unlike classes, structs are value types and do not require heap allocation. A variable of a struct type directly stores the data of the struct, whereas a variable of a class type stores a reference to a dynamically allocated object. Struct types do not support user-specified inheritance, and all struct types implicitly inherit from type 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. The use of structs rather than classes for small data structures can make a large difference in the number of memory allocations an application performs. For example, the following program creates and initializes an array of 100 points. With Point implemented as a class, 101 separate objects are instantiated—one for the array and one each for the 100 elements.

class Point
{
   public int x, y;

   public Point(int x, int y) {
      this.x = x;
      this.y = y;
   }
}

class Test
{
   static void Main() {
      Point[] points = new Point[100];
      for (int i = 0; i < 100; i++) points[i] = new Point(i, i);
   }
}

An alternative is to make Point a struct.

struct Point
{
   public int x, y;

   public Point(int x, int y) {
      this.x = x;
      this.y = y;
   }
}

Now, only one object is instantiated—the one for the array—and the Point instances are stored in-line in the array.

Struct constructors are invoked with the new operator, but that does not imply that memory is being allocated. Instead of dynamically allocating an object and returning a reference to it, a struct constructor simply returns the struct value itself (typically in a temporary location on the stack), and this value is then copied as necessary.

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, and it is not possible for operations on one to affect the other. For example, the output produced by the following code fragment depends on whether Point is a class or a struct.

Point a = new Point(10, 10);
Point b = a;
a.x = 20;
Console.WriteLine(b.x);

If Point is a class, the output is 20 because a and b reference the same object. If Point is a struct, the output is 10 because the assignment of a to b creates a copy of the value, and this copy is unaffected by the subsequent assignment to a.x.

The previous example highlights two of the limitations of structs. First, copying an entire struct is typically less efficient than copying an object reference, so assignment and value parameter passing can be more expensive with structs than with reference types. Second, except for ref and out parameters, it is not possible to create references to structs, which rules out their usage in a number of situations.

1.8 Arrays

An array is a data structure that contains a number of variables that 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 reference types, and the declaration of an array variable simply sets aside space for a reference to an array instance. Actual array instances are created dynamically at run-time using the new operator. The new operation specifies the length of the new array instance, which is then fixed for the lifetime of the instance. The indices of the elements of an array range from 0 to Length - 1. The new operator automatically initializes the elements of an array to their default value, which, for example, is zero for all numeric types and null for all reference types.

The following example creates an array of int elements, initializes the array, and prints out the contents of the array.

using System;

class Test
{
   static void Main() {
      int[] a = new int[10];
      for (int i = 0; i < a.Length; i++) {
         a[i] = i * i;
      }
      for (int i = 0; i < a.Length; i++) {
         Console.WriteLine("a[{0}] = {1}", i, a[i]);
      }
   }
}

This example creates and operates on a single-dimensional array. C# also supports multi-dimensional arrays. The number of dimensions of an array type, also known as the rank of the array type, is one plus the number of commas written between the square brackets of the array type. The following example allocates a one-dimensional, a two-dimensional, and a three-dimensional array.

int[] a1 = new int[10];
int[,] a2 = new int[10, 5];
int[,,] a3 = new int[10, 5, 2];

The a1 array contains 10 elements, the a2 array contains 50 (10 × 5) elements, and the a3 array contains 100 (10 × 5 × 2) elements.

The element type of an array can be any type, including an array type. An array with elements of an array type is sometimes called a jagged array because the lengths of the element arrays do not all have to be the same. The following example allocates an array of arrays of int:

int[][] a = new int[3][];
a[0] = new int[10];
a[1] = new int[5];
a[2] = new int[20];

The first line creates an array with three elements, each of type int[] and each with an initial value of null. The subsequent lines then initialize the three elements with references to individual array instances of varying lengths.

The new operator permits the initial values of the array elements to be specified using an array initializer, which is a list of expressions written between the delimiters { and }. The following example allocates and initializes an int[] with three elements.

int[] a = new int[] {1, 2, 3};

Note that the length of the array is inferred from the number of expressions between { and }. Local variable and field declarations can be shortened further such that the array type does not have to be restated.

int[] a = {1, 2, 3};

Both of the previous examples are equivalent to the following:

int[] t = new int[3];
t[0] = 1;
t[1] = 2;
t[2] = 3;
int[] a = t;

1.9 Interfaces

An interface defines a contract that can be implemented by classes and structs. An interface can contain methods, properties, events, and indexers. An interface does not provide implementations of the members it defines—it merely specifies the members that must be supplied by classes or structs that implement the interface.

Interfaces may employ multiple inheritance. In the following example, the interface IComboBox inherits from both ITextBox and IListBox.

interface IControl
{
   void Paint();
}

interface ITextBox: IControl
{
   void SetText(string text);
}

interface IListBox: IControl
{
   void SetItems(string[] items);
}

interface IComboBox: ITextBox, IListBox {}

Classes and structs can implement multiple interfaces. In the following example, the class EditBox implements both IControl and IDataBound.

interface IDataBound
{
   void Bind(Binder b);
}

public class EditBox: IControl, IDataBound
{
   public void Paint() {...}

   public void Bind(Binder b) {...}
}

When a class or struct implements a particular interface, instances of that class or struct can be implicitly converted to that interface type. For example

EditBox editBox = new EditBox();
IControl control = editBox;
IDataBound dataBound = editBox;

In cases where an instance is not statically known to implement a particular interface, dynamic type casts can be used. For example, the following statements use dynamic type casts to obtain an object’s IControl and IDataBound interface implementations. Because the actual type of the object is EditBox, the casts succeed.

object obj = new EditBox();
IControl control = (IControl)obj;
IDataBound dataBound = (IDataBound)obj;

In the previous EditBox class, the Paint method from the IControl interface and the Bind method from the IDataBound interface are implemented using public members. C# also supports explicit interface member implementations, using which the class or struct can avoid making the members public. An explicit interface member implementation is written using the fully qualified interface member name. For example, the EditBox class could implement the IControl.Paint and IDataBound.Bind methods using explicit interface member implementations as follows.

public class EditBox: IControl, IDataBound
{
   void IControl.Paint() {...}

   void IDataBound.Bind(Binder b) {...}
}

Explicit interface members can only be accessed via the interface type. For example, the implementation of IControl.Paint provided by the previous EditBox class can only be invoked by first converting the EditBox reference to the IControl interface type.

EditBox editBox = new EditBox();
editBox.Paint();                 // Error, no such method
IControl control = editBox;
control.Paint();                 // Ok

1.10 Enums

An enum type is a distinct value type with a set of named constants. The following example declares and uses an enum type named Color with three constant values, Red, Green, and Blue.

using System;

enum Color
{
   Red,
   Green,
   Blue
}

class Test
{
   static void PrintColor(Color color) {
      switch (color) {
         case Color.Red:
            Console.WriteLine("Red");
            break;
         case Color.Green:
            Console.WriteLine("Green");
            break;
         case Color.Blue:
            Console.WriteLine("Blue");
            break;
         default:
            Console.WriteLine("Unknown color");
            break;
      }
   }

   static void Main() {
      Color c = Color.Red;
      PrintColor(c);
      PrintColor(Color.Blue);
   }
}

Each enum type has a corresponding integral type called the underlying type of the enum type. An enum type that does not explicitly declare an underlying type has an underlying type of int. An enum type’s storage format and range of possible values are determined by its underlying type. 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.

The following example declares an enum type named Alignment with an underlying type of sbyte.

enum Alignment: sbyte
{
   Left = -1,
   Center = 0,
   Right = 1
}

As shown by the previous example, an enum member declaration can include a constant expression that specifies the value of the member. The constant value for each enum member must be in the range of the underlying type of the enum. When an enum member declaration does not explicitly specify a value, the member is given the value zero (if it is the first member in the enum type) or the value of the textually preceding enum member plus one.

Enum values can be converted to integral values and vice versa using type casts. For example

int i = (int)Color.Blue;      // int i = 2;
Color c = (Color)2;           // Color c = Color.Blue;

The default value of any enum type is the integral value zero converted to the enum type. In cases where variables are automatically initialized to a default value, this is the value given to variables of enum types. In order for the default value of an enum type to be easily available, the literal 0 implicitly converts to any enum type. Thus, the following is permitted.

Color c = 0;

1.11 Delegates

A delegate type represents references to methods with a particular parameter list and return type. Delegates make it possible to treat methods as entities that can be assigned to variables and passed as parameters. Delegates are similar to the concept of function pointers found in some other languages, but unlike function pointers, delegates are object-oriented and type-safe.

The following example declares and uses a delegate type named Function.

using System;

delegate double Function(double x);

class Multiplier
{
   double factor;

   public Multiplier(double factor) {
      this.factor = factor;
   }

   public double Multiply(double x) {
      return x * factor;
   }
}

class Test
{
   static double Square(double x) {
      return x * x;
   }

   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 Main() {
      double[] a = {0.0, 0.5, 1.0};

      double[] squares = Apply(a, Square);

      double[] sines = Apply(a, Math.Sin);

      Multiplier m = new Multiplier(2.0);
      double[] doubles =  Apply(a, m.Multiply);
   }
}

An instance of the Function delegate type can reference any method that takes a double argument and returns a double value. The Apply method applies a given Function to the elements of a double[], returning a double[] with the results. In the Main method, Apply is used to apply three different functions to a double[].

A delegate can reference either a static method (such as Square or Math.Sin in the previous example) or an instance method (such as m.Multiply in the previous example). A delegate that references an instance method also references a particular object, and when the instance method is invoked through the delegate, that object becomes this in the invocation.

Delegates can also be created using anonymous functions, which are “inline methods” that are created on the fly. Anonymous functions can see the local variables of the sourrounding methods. Thus, the multiplier example above can be written more easily without using a Multiplier class:

      double[] doubles =  Apply(a, (double x) => x * 2.0);

An interesting and useful property of a delegate is that it does not know or care about the class of the method it references; all that matters is that the referenced method has the same parameters and return type as the delegate.

1.12 Attributes

Types, members, and other entities in a C# program support modifiers that control certain aspects of their behavior. For example, the accessibility of a method is controlled using the public, protected, internal, and private modifiers. C# generalizes this capability such that user-defined types of declarative information can be attached to program entities and retrieved at run-time. Programs specify this additional declarative information by defining and using attributes.

The following example declares a HelpAttribute attribute that can be placed on program entities to provide links to their associated documentation.

using System;

public class HelpAttribute: Attribute
{
   string url;
   string topic;

   public HelpAttribute(string url) {
      this.url = url;
   }

   public string Url {
      get { return url; }
   }

   public string Topic {
      get { return topic; }
      set { topic = value; }
   }
}

All attribute classes derive from the System.Attribute base class provided by the .NET Framework. Attributes can be applied by giving their name, along with any arguments, inside square brackets just before the associated declaration. If an attribute’s name ends in Attribute, that part of the name can be omitted when the attribute is referenced. For example, the HelpAttribute attribute can be used as follows.

[Help("http://msdn.microsoft.com/.../MyClass.htm")]
public class Widget
{
   [Help("http://msdn.microsoft.com/.../MyClass.htm", Topic = "Display")]
   public void Display(string text) {}
}

This example attaches a HelpAttribute to the Widget class and another HelpAttribute to the Display method in the class. The public constructors of an attribute class control the information that must be provided when the attribute is attached to a program entity. Additional information can be provided by referencing public read-write properties of the attribute class (such as the reference to the Topic property previously).

The following example shows how attribute information for a given program entity can be retrieved at run-time using reflection.

using System;
using System.Reflection;

class Test
{
   static void ShowHelp(MemberInfo member) {
      HelpAttribute a = Attribute.GetCustomAttribute(member,
         typeof(HelpAttribute)) as HelpAttribute;
      if (a == null) {
         Console.WriteLine("No help for {0}", member);
      }
      else {
         Console.WriteLine("Help for {0}:", member);
         Console.WriteLine("  Url={0}, Topic={1}", a.Url, a.Topic);
      }
   }

   static void Main() {
      ShowHelp(typeof(Widget));
      ShowHelp(typeof(Widget).GetMethod("Display"));
   }
}

When a particular attribute is requested through reflection, the constructor for the attribute class is invoked with the information provided in the program source, and the resulting attribute instance is returned. If additional information was provided through properties, those properties are set to the given values before the attribute instance is returned.


2. Lexical structure

2.1 Programs

A C# program consists of one or more source files, known formally as compilation units9.1). A source file is an ordered sequence of Unicode characters. Source files typically have a one-to-one correspondence with files in a file system, but this correspondence is not required. For maximal portability, it is recommended that files in a file system be encoded with the UTF-8 encoding.

Conceptually speaking, a program is compiled using three steps:

1.       Transformation, which converts a file from a particular character repertoire and encoding scheme into a sequence of Unicode characters.

2.       Lexical analysis, which translates a stream of Unicode input characters into a stream of tokens.

3.       Syntactic analysis, which translates the stream of tokens into executable code.

2.2 Grammars

This specification presents the syntax of the C# programming language using two grammars. The lexical grammar (§2.2.2) defines how Unicode characters are combined to form line terminators, white space, comments, tokens, and pre-processing directives. The syntactic grammar (§2.2.3) defines how the tokens resulting from the lexical grammar are combined to form C# programs.

2.2.1 Grammar notation

The lexical and syntactic grammars are presented using grammar productions. Each grammar production defines a non-terminal symbol and the possible expansions of that non-terminal symbol into sequences of non-terminal or terminal symbols. In grammar productions, non-terminal symbols are shown in italic type, and terminal symbols are shown in a fixed-width font.

The first line of a grammar production is the name of the non-terminal symbol being defined, followed by a colon. Each successive indented line contains a possible expansion of the non-terminal given as a sequence of non-terminal or terminal symbols. For example, the production:

while-statement:
while   (   boolean-expression   )   embedded-statement

defines a while-statement to consist of the token while, followed by the token “(”, followed by a boolean-expression, followed by the token “)”, followed by an embedded-statement.

When there is more than one possible expansion of a non-terminal symbol, the alternatives are listed on separate lines. For example, the production:

statement-list:
statement
statement-list   statement

defines a statement-list to either consist of a statement or consist of a statement-list followed by a statement. In other words, the definition is recursive and specifies that a statement list consists of one or more statements.

A subscripted suffix “opt” is used to indicate an optional symbol. The production:

block:
{   statement-listopt   }

is shorthand for:

block:
{   }
{   statement-list   }

and defines a block to consist of an optional statement-list enclosed in “{” and “}” tokens.

Alternatives are normally listed on separate lines, though in cases where there are many alternatives, the phrase “one of” may precede a list of expansions given on a single line. This is simply shorthand for listing each of the alternatives on a separate line. For example, the production:

real-type-suffix:  one of
F  f  D  d  M  m

is shorthand for:

real-type-suffix:
F
f
D
d
M
m

2.2.2 Lexical grammar

The lexical grammar of C# is presented in §2.3, §2.4, and §2.5. The terminal symbols of the lexical grammar are the characters of the Unicode character set, and the lexical grammar specifies how characters are combined to form tokens (§2.4), white space (§2.3.3), comments (§2.3.2), and pre-processing directives (§2.5).

Every source file in a C# program must conform to the input production of the lexical grammar (§2.3).

2.2.3 Syntactic grammar

The syntactic grammar of C# is presented in the chapters and appendices that follow this chapter. The terminal symbols of the syntactic grammar are the tokens defined by the lexical grammar, and the syntactic grammar specifies how tokens are combined to form C# programs.

Every source file in a C# program must conform to the compilation-unit production of the syntactic grammar (§9.1).

2.3 Lexical analysis

The input production defines the lexical structure of a C# source file. Each source file in a C# program must conform to this lexical grammar production.

input:
input-sectionopt

input-section:
input-section-part
input-section   input-section-part

input-section-part:
input-elementsopt   new-line
pp-directive

input-elements:
input-element
input-elements   input-element

input-element:
whitespace
comment
token

Five basic elements make up the lexical structure of a C# source file: Line terminators (§2.3.1), white space (§2.3.3), comments (§2.3.2), tokens (§2.4), and pre-processing directives (§2.5). Of these basic elements, only tokens are significant in the syntactic grammar of a C# program (§2.2.3).

The lexical processing of a C# source file consists of reducing the file into a sequence of tokens which becomes the input to the syntactic analysis. Line terminators, white space, and comments can serve to separate tokens, and pre-processing directives can cause sections of the source file to be skipped, but otherwise these lexical elements have no impact on the syntactic structure of a C# program.

When several lexical grammar productions match a sequence of characters in a source file, the lexical processing always forms the longest possible lexical element. For example, the character sequence // is processed as the beginning of a single-line comment because that lexical element is longer than a single / token.

2.3.1 Line terminators

Line terminators divide the characters of a C# source file into lines.

new-line:
Carriage return character (U+000D)
Line feed character (U+000A)
Carriage return character (U+000D) followed by line feed character (U+000A)
Next line character (U+0085)
Line separator character (U+2028)
Paragraph separator character (U+2029)

For compatibility with source code editing tools that add end-of-file markers, and to enable a source file to be viewed as a sequence of properly terminated lines, the following transformations are applied, in order, to every source file in a C# program:

·         If the last character of the source file is a Control-Z character (U+001A), this character is deleted.

·         A carriage-return character (U+000D) is added to the end of the source file if that source file is non-empty and if the last character of the source file is not a carriage return (U+000D), a line feed (U+000A), a line separator (U+2028), or a paragraph separator (U+2029).

2.3.2 Comments

Two forms of comments are supported: single-line comments and delimited comments. Single-line comments start with the characters // and extend to the end of the source line. Delimited comments start with the characters /* and end with the characters */. Delimited comments may span multiple lines.

comment:
single-line-comment
delimited-comment

single-line-comment:
//   input-charactersopt

input-characters:
input-character
input-characters   input-character

input-character:
Any Unicode character except a new-line-character

new-line-character:
Carriage return character (U+000D)
Line feed character (U+000A)
Next line character (U+0085)
Line separator character (U+2028)
Paragraph separator character (U+2029)

delimited-comment:
/*   delimited-comment-textopt   asterisks   /

delimited-comment-text:
delimited-comment-section
delimited-comment-text   delimited-comment-section

delimited-comment-section:
/
asterisksopt   not-slash-or-asterisk

asterisks:
*
asterisks   *

not-slash-or-asterisk:
Any Unicode character except / or *

Comments do not nest. The character sequences /* and */ have no special meaning within a // comment, and the character sequences // and /* have no special meaning within a delimited comment.

Comments are not processed within character and string literals.

The example

/* Hello, world program
   This program writes “hello, world” to the console
*/
class Hello
{
   static void Main() {
      System.Console.WriteLine("hello, world");
   }
}

includes a delimited comment.

The example

// Hello, world program
// This program writes “hello, world” to the console
//
class Hello // any name will do for this class
{
   static void Main() { // this method must be named "Main"
      System.Console.WriteLine("hello, world");
   }
}

shows several single-line comments.

2.3.3 White space

White space is defined as any character with Unicode class Zs (which includes the space character) as well as the horizontal tab character, the vertical tab character, and the form feed character.

whitespace:
Any character with Unicode class Zs
Horizontal tab character (U+0009)
Vertical tab character (U+000B)
Form feed character (U+000C)

2.4 Tokens

There are several kinds of tokens: identifiers, keywords, literals, operators, and punctuators. White space and comments are not tokens, though they act as separators for tokens.

token:
identifier
keyword
integer-literal
real-literal
character-literal
string-literal
operator-or-punctuator

2.4.1 Unicode character escape sequences

A Unicode character escape sequence represents a Unicode character. Unicode character escape sequences are processed in identifiers (§2.4.2), character literals (§2.4.4.4), and regular string literals (§2.4.4.5). A Unicode character escape is not processed in any other location (for example, to form an operator, punctuator, or keyword).

unicode-escape-sequence:
\u   hex-digit   hex-digit   hex-digit   hex-digit
\U   hex-digit   hex-digit   hex-digit  hex-digit   hex-digit   hex-digit   hex-digit   hex-digit

A Unicode escape sequence represents the single Unicode character formed by the hexadecimal number following the “\u” or “\U” characters. Since C# uses a 16-bit encoding of Unicode code points in characters and string values, a Unicode character in the range U+10000 to U+10FFFF is not permitted in a character literal and is represented using a Unicode surrogate pair in a string literal. Unicode characters with code points above 0x10FFFF are not supported.

Multiple translations are not performed. For instance, the string literal “\u005Cu005C” is equivalent to “\u005C” rather than “\”. The Unicode value \u005C is the character “\”.

The example

class Class1
{
   static void Test(bool \u0066) {
      char c = '\u0066';
      if (\u0066)
         System.Console.WriteLine(c.ToString());
   }    
}

shows several uses of \u0066, which is the escape sequence for the letter “f”. The program is equivalent to

class Class1
{
   static void Test(bool f) {
      char c = 'f';
      if (f)
         System.Console.WriteLine(c.ToString());
   }    
}

2.4.2 Identifiers

The rules for identifiers given in this section correspond exactly to those recommended by the Unicode Standard Annex 31, except that underscore is allowed as an initial character (as is traditional in the C programming language), Unicode escape sequences are permitted in identifiers, and the “@” character is allowed as a prefix to enable keywords to be used as identifiers.

identifier:
available-identifier
@   identifier-or-keyword

available-identifier:
An identifier-or-keyword that is not a keyword

identifier-or-keyword:
identifier-start-character   identifier-part-charactersopt

identifier-start-character:
letter-character
_ (the underscore character U+005F)

identifier-part-characters:
identifier-part-character
identifier-part-characters   identifier-part-character

identifier-part-character:
letter-character
decimal-digit-character
connecting-character
combining-character
formatting-character

letter-character:
A Unicode character of classes Lu, Ll, Lt, Lm, Lo, or Nl
A unicode-escape-sequence representing a character of classes Lu, Ll, Lt, Lm, Lo, or Nl

combining-character:
A Unicode character of classes Mn or Mc
A unicode-escape-sequence representing a character of classes Mn or Mc

decimal-digit-character:
A Unicode character of the class Nd
A unicode-escape-sequence representing a character of the class Nd

connecting-character: 
A Unicode character of the class Pc
A unicode-escape-sequence representing a character of the class Pc

formatting-character: 
A Unicode character of the class Cf
A unicode-escape-sequence representing a character of the class Cf

For information on the Unicode character classes mentioned above, see The Unicode Standard, Version 3.0, section 4.5.

Examples of valid identifiers include “identifier1”, “_identifier2”, and “@if”.

An identifier in a conforming program must be in the canonical format defined by Unicode Normalization Form C, as defined by Unicode Standard Annex 15. The behavior when encountering an identifier not in Normalization Form C is implementation-defined; however, a diagnostic is not required.

The prefix “@” enables the use of keywords as identifiers, which is useful when interfacing with other programming languages. The character @ is not actually part of the identifier, so the identifier might be seen in other languages as a normal identifier, without the prefix. An identifier with an @ prefix is called a verbatim identifier. Use of the @ prefix for identifiers that are not keywords is permitted, but strongly discouraged as a matter of style.

The example:

class @class
{
   public static void @static(bool @bool) {
      if (@bool)
         System.Console.WriteLine("true");
      else
         System.Console.WriteLine("false");
   } 
}

class Class1
{
   static void M() {
      cl\u0061ss.st\u0061tic(true);
   }
}

defines a class named “class” with a static method named “static” that takes a parameter named “bool”. Note that since Unicode escapes are not permitted in keywords, the token “cl\u0061ss” is an identifier, and is the same identifier as “@class”.

Two identifiers are considered the same if they are identical after the following transformations are applied, in order:

·         The prefix “@”, if used, is removed.

·         Each unicode-escape-sequence is transformed into its corresponding Unicode character.

·         Any formatting-characters are removed.

Identifiers containing two consecutive underscore characters (U+005F) are reserved for use by the implementation. For example, an implementation might provide extended keywords that begin with two underscores.

2.4.3 Keywords

A keyword is an identifier-like sequence of characters that is reserved, and cannot be used as an identifier except when prefaced by the @ character.

keyword:  one of
abstract    as          base        bool        break
byte        case        catch       char        checked
class       const       continue    decimal     default
delegate    do          double      else        enum
event       explicit    extern      false       finally
fixed       float       for         foreach     goto
if          implicit    in          int         interface
internal    is          lock        long        namespace
new         null        object      operator    out
override    params      private     protected   public
readonly    ref         return      sbyte       sealed
short       sizeof      stackalloc  static      string
struct      switch      this        throw       true
try         typeof      uint        ulong       unchecked
unsafe      ushort      using       virtual     void
volatile    while

In some places in the grammar, specific identifiers have special meaning, but are not keywords. Such identifiers are sometimes referred to as “contextual keywords”. For example, within a property declaration, the “get” and “set” identifiers have special meaning (§10.7.2). An identifier other than get or set is never permitted in these locations, so this use does not conflict with a use of these words as identifiers. In other cases, such as with the identifier “var” in implicitly typed local variable declarations (§8.5.1), a contectual keyword can conflict with declared names. In such cases, the declared name takes precedence over the use of the identifier as a contextual keyword.

2.4.4 Literals

A literal is a source code representation of a value.

literal:
boolean-literal
integer-literal
real-literal
character-literal
string-literal
null-literal

2.4.4.1 Boolean literals

There are two boolean literal values: true and false.

boolean-literal:
true
false

The type of a boolean-literal is bool.

2.4.4.2 Integer literals

Integer literals are used to write values of types int, uint, long, and ulong. Integer literals have two possible forms: decimal and hexadecimal.

integer-literal:
decimal-integer-literal
hexadecimal-integer-literal

decimal-integer-literal:
decimal-digits   integer-type-suffixopt

decimal-digits:
decimal-digit
decimal-digits   decimal-digit

decimal-digit:  one of
0  1  2  3  4  5  6  7  8  9

integer-type-suffix:  one of
U  u  L  l  UL  Ul  uL  ul  LU  Lu  lU  lu

hexadecimal-integer-literal:
0x   hex-digits   integer-type-suffixopt
0X   hex-digits   integer-type-suffixopt

hex-digits:
hex-digit
hex-digits   hex-digit

hex-digit:  one of
0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F  a  b  c  d  e  f

The type of an integer literal is determined as follows:

·         If the literal has no suffix, it has the first of these types in which its value can be represented: int, uint, long, ulong.

·         If the literal is suffixed by U or u, it has the first of these types in which its value can be represented: uint, ulong.

·         If the literal is suffixed by L or l, it has the first of these types in which its value can be represented: long, ulong.

·         If the literal is suffixed by UL, Ul, uL, ul, LU, Lu, lU, or lu, it is of type ulong.

If the value represented by an integer literal is outside the range of the ulong type, a compile-time error occurs.

As a matter of style, it is suggested that “L” be used instead of “l” when writing literals of type long, since it is easy to confuse the letter “l” with the digit “1”.

To permit the smallest possible int and long values to be written as decimal integer literals, the following two rules exist:

·         When a decimal-integer-literal with the value 2147483648 (231) and no integer-type-suffix appears as the token immediately following a unary minus operator token (§7.7.2), the result is a constant of type int with the value −2147483648 (−231). In all other situations, such a decimal-integer-literal is of type uint.

·         When a decimal-integer-literal with the value 9223372036854775808 (263) and no integer-type-suffix or the integer-type-suffix L or l appears as the token immediately following a unary minus operator token (§7.7.2), the result is a constant of type long with the value −9223372036854775808 (−263). In all other situations, such a decimal-integer-literal is of type ulong.

2.4.4.3 Real literals

Real literals are used to write values of types float, double, and decimal.

real-literal:
decimal-digits   .   decimal-digits   exponent-partopt   real-type-suffixopt
.   decimal-digits   exponent-partopt   real-type-suffixopt
decimal-digits   exponent-part   real-type-suffixopt
decimal-digits   real-type-suffix

exponent-part:
e   signopt   decimal-digits
E   signopt   decimal-digits

sign:  one of
+  -

real-type-suffix:  one of
F  f  D  d  M  m

If no real-type-suffix is specified, the type of the real literal is double. Otherwise, the real type suffix determines the type of the real literal, as follows:

·         A real literal suffixed by F or f is of type float. For example, the literals 1f, 1.5f, 1e10f, and 123.456F are all of type float.

·         A real literal suffixed by D or d is of type double. For example, the literals 1d, 1.5d, 1e10d, and 123.456D are all of type double.

·         A real literal suffixed by M or m is of type decimal. For example, the literals 1m, 1.5m, 1e10m, and 123.456M are all of type decimal. This literal is converted to a decimal value by taking the exact value, and, if necessary, rounding to the nearest representable value using banker's rounding (§4.1.7). Any scale apparent in the literal is preserved unless the value is rounded or the value is zero (in which latter case the sign and scale will be 0). Hence, the literal 2.900m will be parsed to form the decimal with sign 0, coefficient 2900, and scale 3.

If the specified literal cannot be represented in the indicated type, a compile-time error occurs.

The value of a real literal of type float or double is determined by using the IEEE “round to nearest” mode.

Note that in a real literal, decimal digits are always required after the decimal point. For example, 1.3F is a real literal but 1.F is not.

2.4.4.4 Character literals

A character literal represents a single character, and usually consists of a character in quotes, as in 'a'.

character-literal:
'   character   '

character:
single-character
simple-escape-sequence
hexadecimal-escape-sequence
unicode-escape-sequence

single-character:
 Any character except ' (U+0027), \ (U+005C), and new-line-character

simple-escape-sequence:  one of
\'  \"  \\  \0  \a  \b  \f  \n  \r  \t  \v

hexadecimal-escape-sequence:
\x   hex-digit   hex-digitopt   hex-digitopt   hex-digitopt

A character that follows a backslash character (\) in a character must be one of the following characters: ', ", \, 0, a, b, f, n, r, t, u, U, x, v. Otherwise, a compile-time error occurs.

A hexadecimal escape sequence represents a single Unicode character, with the value formed by the hexadecimal number following “\x”.

If the value represented by a character literal is greater than U+FFFF, a compile-time error occurs.

A Unicode character escape sequence (§2.4.1) in a character literal must be in the range U+0000 to U+FFFF.

A simple escape sequence represents a Unicode character encoding, as described in the table below.

 

Escape sequence

Character name

Unicode encoding

\'

Single quote

0x0027

\"

Double quote

0x0022

\\

Backslash

0x005C

\0

Null

0x0000

\a

Alert

0x0007

\b

Backspace

0x0008

\f

Form feed

0x000C

\n

New line

0x000A

\r

Carriage return

0x000D

\t

Horizontal tab

0x0009

\v

Vertical tab

0x000B

 

The type of a character-literal is char.

2.4.4.5 String literals

C# supports two forms of string literals: regular string literals and verbatim string literals.

A regular string literal consists of zero or more characters enclosed in double quotes, as in "hello", and may include both simple escape sequences (such as \t for the tab character), and hexadecimal and Unicode escape sequences.

A verbatim string literal consists of an @ character followed by a double-quote character, zero or more characters, and a closing double-quote character. A simple example is @"hello". In a verbatim string literal, the characters between the delimiters are interpreted verbatim, the only exception being a quote-escape-sequence. In particular, simple escape sequences, and hexadecimal and Unicode escape sequences are not processed in verbatim string literals. A verbatim string literal may span multiple lines.

string-literal:
regular-string-literal
verbatim-string-literal

regular-string-literal:
"   regular-string-literal-charactersopt   "

regular-string-literal-characters:
regular-string-literal-character
regular-string-literal-characters   regular-string-literal-character

regular-string-literal-character:
single-regular-string-literal-character
simple-escape-sequence
hexadecimal-escape-sequence
unicode-escape-sequence

single-regular-string-literal-character:
Any character except " (U+0022), \ (U+005C), and new-line-character

verbatim-string-literal:
@"   verbatim-string-literal-charactersopt   "

verbatim-string-literal-characters:
verbatim-string-literal-character
verbatim-string-literal-characters   verbatim-string-literal-character

verbatim-string-literal-character:
single-verbatim-string-literal-character
quote-escape-sequence

single-verbatim-string-literal-character:
Any character except "

quote-escape-sequence:
""

A character that follows a backslash character (\) in a regular-string-literal-character must be one of the following characters: ', ", \, 0, a, b, f, n, r, t, u, U, x, v. Otherwise, a compile-time error occurs.

The example

string a = "hello, world";                // hello, world
string b = @"hello, world";               // hello, world

string c = "hello \t world";              // hello     world
string d = @"hello \t world";             // hello \t world

string e = "Joe said \"Hello\" to me";    // Joe said "Hello" to me
string f = @"Joe said ""Hello"" to me";   // Joe said "Hello" to me

string g = "\\\\server\\share\\file.txt"; // \\server\share\file.txt
string h = @"\\server\share\file.txt";    // \\server\share\file.txt

string i = "one\r\ntwo\r\nthree";
string j = @"one
two
three";

shows a variety of string literals. The last string literal, j, is a verbatim string literal that spans multiple lines. The characters between the quotation marks, including white space such as new line characters, are preserved verbatim.

Since a hexadecimal escape sequence can have a variable number of hex digits, the string literal "\x123" contains a single character with hex value 123. To create a string containing the character with hex value 12 followed by the character 3, one could write "\x00123" or "\x12" + "3" instead.

The type of a string-literal is string.

Each string literal does not necessarily result in a new string instance. When two or more string literals that are equivalent according to the string equality operator (§7.10.7) appear in the same program, these string literals refer to the same string instance. For instance, the output produced by

class Test
{
   static void Main() {
      object a = "hello";
      object b = "hello";
      System.Console.WriteLine(a == b);
   }
}

is True because the two literals refer to the same string instance.

2.4.4.6 The null literal

null-literal:
null

The  null-literal can be implicitly converted to a reference type or nullable type.

2.4.5 Operators and punctuators

There are several kinds of operators and punctuators. Operators are used in expressions to describe operations involving one or more operands. For example, the expression a + b uses the + operator to add the two operands a and b. Punctuators are for grouping and separating.

operator-or-punctuator:  one of
{     }     [     ]     (     )     .     ,     :     ;
+     -     *     /     %     &     |     ^     !     ~
=     <     >     ?     ??    ::    ++    --    &&    ||
->    ==    !=    <=    >=    +=    -=    *=    /=    %=
&=    |=    ^=    <<    <<=   =>

right-shift:
>|>

right-shift-assignment:
>|>=

The vertical bar in the right-shift and right-shift-assignment productions are used to indicate that, unlike other productions in the syntactic grammar, no characters of any kind (not even whitespace) are allowed between the tokens. These productions are treated specially in order to enable the correct  handling of type-parameter-lists (§10.1.3).

2.5 Pre-processing directives

The pre-processing directives provide the ability to conditionally skip sections of source files, to report error and warning conditions, and to delineate distinct regions of source code. The term “pre-processing directives” is used only for consistency with the C and C++ programming languages. In C#, there is no separate pre-processing step; pre-processing directives are processed as part of the lexical analysis phase.

pp-directive:
pp-declaration
pp-conditional
pp-line
pp-diagnostic
pp-region
pp-pragma

The following pre-processing directives are available:

·         #define and #undef, which are used to define and undefine, respectively, conditional compilation symbols (§2.5.3).

·         #if, #elif, #else, and #endif, which are used to conditionally skip sections of source code (§2.5.4).

·         #line, which is used to control line numbers emitted for errors and warnings (§2.5.7).

·         #error and #warning, which are used to issue errors and warnings, respectively (§2.5.5).

·         #region and #endregion, which are used to explicitly mark sections of source code (§2.5.6).

·         #pragma, which is used to specify optional contextual information to the compiler (§2.5.8).

A pre-processing directive always occupies a separate line of source code and always begins with a # character and a pre-processing directive name. White space may occur before the # character and between the # character and the directive name.

A source line containing a #define, #undef, #if, #elif, #else, #endif, #line, or #endregion directive may end with a single-line comment. Delimited comments (the /* */ style of comments) are not permitted on source lines containing pre-processing directives.

Pre-processing directives are not tokens and are not part of the syntactic grammar of C#. However, pre-processing directives can be used to include or exclude sequences of tokens and can in that way affect the meaning of a C# program. For example, when compiled, the program:

#define A
#undef B

class C
{
#if A
   void F() {}
#else
   void G() {}
#endif

#if B
   void H() {}
#else
   void I() {}
#endif
}

results in the exact same sequence of tokens as the program:

class C
{
   void F() {}
   void I() {}
}

Thus, whereas lexically, the two programs are quite different, syntactically, they are identical.

2.5.1 Conditional compilation symbols

The conditional compilation functionality provided by the #if, #elif, #else, and #endif directives is controlled through pre-processing expressions (§2.5.2) and conditional compilation symbols.

conditional-symbol:
Any identifier-or-keyword except true or false

A conditional compilation symbol has two possible states: defined or undefined. At the beginning of the lexical processing of a source file, a conditional compilation symbol is undefined unless it has been explicitly defined by an external mechanism (such as a command-line compiler option). When a #define directive is processed, the conditional compilation symbol named in that directive becomes defined in that source file. The symbol remains defined until an #undef directive for that same symbol is processed, or until the end of the source file is reached. An implication of this is that #define and #undef directives in one source file have no effect on other source files in the same program.

When referenced in a pre-processing expression, a defined conditional compilation symbol has the boolean value true, and an undefined conditional compilation symbol has the boolean value false. There is no requirement that conditional compilation symbols be explicitly declared before they are referenced in pre-processing expressions. Instead, undeclared symbols are simply undefined and thus have the value false.

The name space for conditional compilation symbols is distinct and separate from all other named entities in a C# program. Conditional compilation symbols can only be referenced in #define and #undef directives and in pre-processing expressions.

2.5.2 Pre-processing expressions

Pre-processing expressions can occur in #if and #elif directives. The operators !, ==, !=, && and || are permitted in pre-processing expressions, and parentheses may be used for grouping.

pp-expression:
whitespaceopt   pp-or-expression   whitespaceopt

pp-or-expression:
pp-and-expression
pp-or-expression   whitespaceopt   ||   whitespaceopt   pp-and-expression

pp-and-expression:
pp-equality-expression
pp-and-expression   whitespaceopt   &&   whitespaceopt   pp-equality-expression

pp-equality-expression:
pp-unary-expression
pp-equality-expression   whitespaceopt   ==   whitespaceopt   pp-unary-expression
pp-equality-expression   whitespaceopt   !=   whitespaceopt   pp-unary-expression

pp-unary-expression:
pp-primary-expression
!   whitespaceopt   pp-unary-expression

pp-primary-expression:
true
false
conditional-symbol
(   whitespaceopt   pp-expression   whitespaceopt   )

When referenced in a pre-processing expression, a defined conditional compilation symbol has the boolean value true, and an undefined conditional compilation symbol has the boolean value false.

Evaluation of a pre-processing expression always yields a boolean value. The rules of evaluation for a pre-processing expression are the same as those for a constant expression (§7.19), except that the only user-defined entities that can be referenced are conditional compilation symbols.

2.5.3 Declaration directives

The declaration directives are used to define or undefine conditional compilation symbols.

pp-declaration:
whitespaceopt   #   whitespaceopt   define   whitespace   conditional-symbol   pp-new-line
whitespaceopt   #   whitespaceopt   undef   whitespace   conditional-symbol   pp-new-line

pp-new-line:
whitespaceopt   single-line-commentopt   new-line

The processing of a #define directive causes the given conditional compilation symbol to become defined, starting with the source line that follows the directive. Likewise, the processing of an #undef directive causes the given conditional compilation symbol to become undefined, starting with the source line that follows the directive.

Any #define and #undef directives in a source file must occur before the first token (§2.4) in the source file; otherwise a compile-time error occurs. In intuitive terms, #define and #undef directives must precede any “real code” in the source file.

The example:

#define Enterprise

#if Professional || Enterprise
   #define Advanced
#endif

namespace Megacorp.Data
{
   #if Advanced
   class PivotTable {...}
   #endif
}

is valid because the #define directives precede the first token (the namespace keyword) in the source file.

The following example results in a compile-time error because a #define follows real code:

#define A
namespace N
{
   #define B
   #if B
   class Class1 {}
   #endif
}

A #define may define a conditional compilation symbol that is already defined, without there being any intervening #undef for that symbol. The example below defines a conditional compilation symbol A and then defines it again.

#define A
#define A

A #undef may “undefine” a conditional compilation symbol that is not defined. The example below defines a conditional compilation symbol A and then undefines it twice; although the second #undef has no effect, it is still valid.

#define A
#undef A
#undef A

2.5.4 Conditional compilation directives

The conditional compilation directives are used to conditionally include or exclude portions of a source file.

pp-conditional:
pp-if-section   pp-elif-sectionsopt   pp-else-sectionopt   pp-endif

pp-if-section:
whitespaceopt   #   whitespaceopt   if   whitespace   pp-expression   pp-new-line   conditional-sectionopt

pp-elif-sections:
pp-elif-section
pp-elif-sections   pp-elif-section

pp-elif-section:
whitespaceopt   #   whitespaceopt   elif   whitespace   pp-expression   pp-new-line   conditional-sectionopt

pp-else-section:
whitespaceopt   #   whitespaceopt   else   pp-new-line   conditional-sectionopt

pp-endif:
whitespaceopt   #   whitespaceopt   endif   pp-new-line

conditional-section:
input-section
skipped-section

skipped-section:
skipped-section-part
skipped-section   skipped-section-part

skipped-section-part:
skipped-charactersopt   new-line
pp-directive

skipped-characters:
whitespaceopt   not-number-sign   input-charactersopt

not-number-sign:
Any input-character except #

As indicated by the syntax, conditional compilation directives must be written as sets consisting of, in order, an #if directive, zero or more #elif directives, zero or one #else directive, and an #endif directive. Between the directives are conditional sections of source code. Each section is controlled by the immediately preceding directive. A conditional section may itself contain nested conditional compilation directives provided these directives form complete sets.

A pp-conditional selects at most one of the contained conditional-sections for normal lexical processing:

·         The pp-expressions of the #if and #elif directives are evaluated in order until one yields true. If an expression yields true, the conditional-section of the corresponding directive is selected.

·         If all pp-expressions yield false, and if an #else directive is present, the conditional-section of the #else directive is selected.

·         Otherwise, no conditional-section is selected.

The selected conditional-section, if any, is processed as a normal input-section: the source code contained in the section must adhere to the lexical grammar; tokens are generated from the source code in the section; and pre-processing directives in the section have the prescribed effects.

The remaining conditional-sections, if any, are processed as skipped-sections: except for pre-processing directives, the source code in the section need not adhere to the lexical grammar; no tokens are generated from the source code in the section; and pre-processing directives in the section must be lexically correct but are not otherwise processed. Within a conditional-section that is being processed as a skipped-section, any nested conditional-sections (contained in nested #if...#endif and #region...#endregion constructs) are also processed as skipped-sections.

The following example illustrates how conditional compilation directives can nest:

#define Debug     // Debugging on
#undef Trace      // Tracing off

class PurchaseTransaction
{
   void Commit() {
      #if Debug
         CheckConsistency();
         #if Trace
            WriteToLog(this.ToString());
         #endif
      #endif
      CommitHelper();
   }
}

Except for pre-processing directives, skipped source code is not subject to lexical analysis. For example, the following is valid despite the unterminated comment in the #else section:

#define Debug     // Debugging on

class PurchaseTransaction
{
   void Commit() {
      #if Debug
         CheckConsistency();
      #else
         /* Do something else
      #endif
   }
}

Note, however, that pre-processing directives are required to be lexically correct even in skipped sections of source code.

Pre-processing directives are not processed when they appear inside multi-line input elements. For example, the program:

class Hello
{
   static void Main() {
      System.Console.WriteLine(@"hello,
#if Debug
      world
#else
      Nebraska
#endif
      ");
   }
}

results in the output:

hello,
#if Debug
      world
#else
      Nebraska
#endif

In peculiar cases, the set of pre-processing directives that is processed might depend on the evaluation of the pp-expression. The example:

#if X
   /*
#else
   /* */ class Q { }
#endif

always produces the same token stream (class Q { }), regardless of whether or not X is defined. If X is defined, the only processed directives are #if and #endif, due to the multi-line comment. If X is undefined, then three directives (#if, #else, #endif) are part of the directive set.

2.5.5 Diagnostic directives

The diagnostic directives are used to explicitly generate error and warning messages that are reported in the same way as other compile-time errors and warnings.

pp-diagnostic:
whitespaceopt   #   whitespaceopt   error   pp-message
whitespaceopt   #   whitespaceopt   warning   pp-message

pp-message:
new-line
whitespace   input-charactersopt   new-line

The example:

#warning Code review needed before check-in

#if Debug && Retail
   #error A build can't be both debug and retail
#endif

class Test {...}

always produces a warning (“Code review needed before check-in”), and produces a compile-time error (“A build can’t be both debug and retail”) if the conditional symbols Debug and Retail are both defined. Note that a pp-message can contain arbitrary text; specifically, it need not contain well-formed tokens, as shown by the single quote in the word can’t.

2.5.6 Region directives

The region directives are used to explicitly mark regions of source code.

pp-region:
pp-start-region   conditional-sectionopt   pp-end-region

pp-start-region:
whitespaceopt   #   whitespaceopt   region   pp-message

pp-end-region:
whitespaceopt   #   whitespaceopt   endregion   pp-message

No semantic meaning is attached to a region; regions are intended for use by the programmer or by automated tools to mark a section of source code. The message specified in a #region or #endregion directive likewise has no semantic meaning; it merely serves to identify the region. Matching #region and #endregion directives may have different pp-messages.

The lexical processing of a region:

#region
...
#endregion

corresponds exactly to the lexical processing of a conditional compilation directive of the form:

#if true
...
#endif

2.5.7 Line directives

Line directives may be used to alter the line numbers and source file names that are reported by the compiler in output such as warnings and errors, and that are used by caller info attributes (§17.4.4).

Line directives are most commonly used in meta-programming tools that generate C# source code from some other text input.

pp-line:
whitespaceopt   #   whitespaceopt   line   whitespace   line-indicator   pp-new-line

line-indicator:
decimal-digits   whitespace   file-name
decimal-digits
default
hidden

file-name:
"   file-name-characters   "

file-name-characters:
file-name-character
file-name-characters   file-name-character

file-name-character:
Any input-character except "

When no #line directives are present, the compiler reports true line numbers and source file names in its output. When processing a #line directive that includes a line-indicator that is not default, the compiler treats the line after the directive as having the given line number (and file name, if specified).

A #line default directive reverses the effect of all preceding #line directives. The compiler reports true line information for subsequent lines, precisely as if no #line directives had been processed.

A #line hidden directive has no effect on the file and line numbers reported in error messages, but does affect source level debugging. When debugging, all lines between a #line hidden directive and the subsequent #line directive (that is not #line hidden) have no line number information. When stepping through code in the debugger, these lines will be skipped entirely.

Note that a file-name differs from a regular string literal in that escape characters are not processed; the ‘\’ character simply designates an ordinary backslash character within a file-name.

2.5.8 Pragma directives

The #pragma preprocessing directive is used to specify optional contextual information to the compiler. The information supplied in a #pragma directive will never change program semantics.

pp-pragma:
whitespaceopt   #   whitespaceopt   pragma   whitespace   pragma-body   pp-new-line

pragma-body:
pragma-warning-body

C# provides #pragma directives to control compiler warnings. Future versions of the language may include additional #pragma directives. To ensure interoperability with other C# compilers, the Microsoft C# compiler does not issue compilation errors for unknown #pragma directives; such directives do however generate warnings.

2.5.8.1 Pragma warning

The #pragma warning directive is used to disable or restore all or a particular set of warning messages during compilation of the subsequent program text.

pragma-warning-body:
warning   whitespace   warning-action
warning   whitespace   warning-action   whitespace   warning-list

warning-action:
disable
restore

warning-list:
decimal-digits
warning-list   whitespaceopt   ,   whitespaceopt   decimal-digits

A #pragma warning directive that omits the warning list affects all warnings. A #pragma warning directive the includes a warning list affects only those warnings that are specified in the list.

A #pragma warning disable directive disables all or the given set of warnings.

A #pragma warning restore directive restores all or the given set of warnings to the state that was in effect at the beginning of the compilation unit. Note that if a particular warning was disabled externally, a #pragma warning restore (whether for all or the specific warning) will not re-enable that warning.

The following example shows use of #pragma warning to temporarily disable the warning reported when obsoleted members are referenced, using the warning number from the Microsoft C# compiler.

using System;

class Program
{
   [Obsolete]
   static void Foo() {}

   static void Main() {
#pragma warning disable 612
   Foo();
#pragma warning restore 612
   }
}


3. Basic concepts

3.1 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:

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 (§3.2).

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 (§3.5.1) of a method is determined by the access modifiers (§10.3.5) 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.

3.2 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).

3.3 Declarations

Declarations in a C# program define the constituent elements of the program. C# programs are organized using namespaces (§9), which can contain type declarations and nested namespace declarations. Type declarations (§9.6) are used to define classes (§10), structs (§10.14), interfaces (§13), enums (§14), and delegates (§15). 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 (§10.4), fields (§10.5), methods (§10.6), properties (§10.7), events (§10.8), indexers (§10.9), operators (§10.10), instance constructors (§10.11), static constructors (§10.12), destructors (§10.13), and nested types(§10.3.8).

A declaration defines a name in the declaration space to which the declaration belongs. Except for overloaded members (§3.6), 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-declarations 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-declarations within namespace-declarations 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-declarations, struct-member-declarations, interface-member-declarations, or type-parameters. 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 (§3.6). 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-parameters and parameter-arrays) and type-parameters.

·         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-parameters and parameter-arrays) and type-parameters. 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-declarations and local-constant-declarations. 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-statements, and the names are referenced through goto-statements. 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 (§3.7).

·         Declaration order for enum member declarations (§14.3) 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

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.

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();
   }
}

3.4 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 (§3.5.1) or because it is hidden by a declaration in the type itself (§3.7.1.2).

3.4.1 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.

3.4.2 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.

3.4.3 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.

3.4.4 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.

3.4.5 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 (§13.2). However, the members in class object are available via member lookup in any interface type (§7.4).

3.4.6 Array members

The members of an array are the members inherited from class System.Array.

3.4.7 Delegate members

The members of a delegate are the members inherited from class System.Delegate.

3.5 Member access

Declarations of members allow control over member access. The accessibility of a member is established by the declared accessibility (§3.5.1) 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 (§3.5.2) of the member.

3.5.1 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.

3.5.2 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-declarations 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 (§4.4.3) 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 (§3.5.3).

·         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 (§3.5.3).

·         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

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 §3.4, 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

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.

3.5.3 Protected access for instance members

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

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

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

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

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

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

In the example

public class A
{
   protected int x;

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

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

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

In the example

class C<T>
{
   protected T x;
}

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

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

3.5.4 Accessibility constraints

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

The following accessibility constraints exist:

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

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

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

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

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

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

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

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

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

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

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

In the example

class A {...}

public class B: A {...}

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

Likewise, in the example

class A {...}

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

   internal A G() {...}

   public A H() {...}
}

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

3.6 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.

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

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

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

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

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

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

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

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

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

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

3.7 Scopes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   int i = 0;
}

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

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

class A
{
   int i = 0;

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

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

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

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

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

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

using System;

class A {}

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

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

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

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

3.7.1 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.

3.7.1.1 Hiding through nesting

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

In the example

class A
{
   int i = 0;

   void F() {
      int i = 1;
   }

   void G() {
      i = 1;
   }
}

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

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

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

   static void F(string s) {}

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

      static void F(long l) {}
   }
}

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

3.7.1.2 Hiding through inheritance

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

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

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

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

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

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

class Base
{
   public void F() {}
}

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

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

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

class Base
{
   public void F() {}
}

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

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

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

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

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

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

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

3.8 Namespace and type names

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

namespace-name:
namespace-or-type-name

type-name:
namespace-or-type-name

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

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

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

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

·         I

·         I<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>:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

·         Otherwise, the namespace-or-type-name is of the form N.I or of the form N.I<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:

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

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

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

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

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

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

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

3.8.1 Fully qualified names

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

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

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

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

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

class A {}           // A

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

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

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

3.9 Automatic memory management

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

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

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

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

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

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

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

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

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

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

using System;

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

class B
{
   object Ref;

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

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

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

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

Destruct instance of A
Destruct instance of B

or

Destruct instance of B
Destruct instance of A

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

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

using System;

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

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

class B
{
   public A Ref;

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

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

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

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

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

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

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

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

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

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

3.10 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 (§10.5.3), lock statements (§8.12), and thread creation and termination. The execution environment is free to change the order of execution of a C# program, subject to the following constraints:

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

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

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


4. Types

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

type:
value-type
reference-type
type-parameter

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

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

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

4.1 Value types

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

value-type:
struct-type
enum-type

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

simple-type:
numeric-type
bool

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

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

floating-point-type:
float
double

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

non-nullable-value-type:
type

enum-type:
type-name

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

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

4.1.1 The System.ValueType type

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

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

4.1.2 Default constructors

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

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

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

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

o   For float, the default value is 0.0f.

o   For double, the default value is 0.0d.

o   For decimal, the default value is 0.0m.

o   For bool, the default value is false.

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

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

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

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

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

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

4.1.3 Struct types

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

4.1.4 Simple types

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

 

Reserved word

Aliased type

sbyte

System.SByte

byte

System.Byte

short

System.Int16

ushort

System.UInt16

int

System.Int32

uint

System.UInt32

long

System.Int64

ulong

System.UInt64

char

System.Char

float

System.Single

double

System.Double

bool

System.Boolean

decimal

System.Decimal

 

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

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

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

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

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

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

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

4.1.5 Integral types

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.1.6 Floating point types

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

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

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

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

·         The finite set of non-zero values of the form s × m × 2e, where s is 1 or −1, and m and e are determined by the particular floating-point type: For float, 0 < m < 224 and −149 ≤ e ≤ 104, and for double, 0 < m < 253 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 × 1038 with a precision of 7 digits.

The double type can represent values ranging from approximately 5.0 × 10−324 to 1.7 × 10308 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.

4.1.7 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 × 1028 with 28-29 significant digits.

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

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

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

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

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

4.1.8 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.

4.1.9 Enumeration types

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

4.1.10 Nullable types

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

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

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

·         A HasValue property of type bool

·         A Value property of type T

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

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

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

new T?(x)

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

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

4.2 Reference types

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

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

class-type:
type-name
object
dynamic

string

interface-type:
type-name

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

non-array-type:
type

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

rank-specifier:
[   dim-separatorsopt   ]

 dim-separators:
,
dim-separators   ,

delegate-type:
type-name

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

4.2.1 Class types

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

Class types are described in §10.

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

 

Class type

Description

System.Object

The ultimate base class of all other types. See §4.2.2.

System.String

The string type of the C# language. See §4.2.4.

System.ValueType

The base class of all value types. See §4.1.1.

System.Enum

The base class of all enum types. See §14.

System.Array

The base class of all array types. See §12.

System.Delegate

The base class of all delegate types. See §15.

System.Exception

The base class of all exception types. See §16.

 

4.2.2 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.

4.2.3 The dynamic type

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

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

4.2.4 The string type

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

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

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

4.2.5 Interface types

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

Interface types are described in §13.

4.2.6 Array types

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

Array types are described in §12.

4.2.7 Delegate types

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

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

Delegate types are described in §15.

4.3 Boxing and unboxing

The concept of boxing and unboxing is central to C#’s type system. It provides a bridge between value-types and reference-types by permitting any value of a value-type to be converted to and from 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.

4.3.1 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 (§6.1.10).

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:

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

int i = 123;
object box = i;

conceptually correspond to

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,

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

struct Point
{
   public int x, y;

   public Point(int x, int y) {
      this.x = x;
      this.y = y;
   }
}

the following statements

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.

4.3.2 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 (§6.2.6).

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

object box = 123;
int i = (int)box;

conceptually correspond to

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.

4.4 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 (§7.6.11).

Constructed types can also be used in expressions as simple names (§7.6.2) or when accessing a member (§7.6.4).

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:

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 (§10.3.8.6):

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 (§18.2).

4.4.1 Type arguments

Each argument in a type argument list is simply a type.

type-argument-list:
<   type-arguments   >

type-arguments:
type-argument
type-arguments   ,   type-argument

type-argument:
type

In unsafe code (§18), a type-argument may not be a pointer type. Each type argument must satisfy any constraints on the corresponding type parameter (§10.1.5).

4.4.2 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.

4.4.3 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 (§7.6.11).

4.4.4 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 (§10.1.5). 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:

o   An identity conversion (§6.1.1)

o   An implicit reference conversion (§6.1.6)

o   A boxing conversion (§6.1.7), provided that type A is a non-nullable value type.

o   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:

o   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.

o   A is a type parameter that is known to be a reference type (§10.1.5).

·         If the constraint is the value type constraint (struct), the type A must satisfy one of the following:

o   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.

o   A is a type parameter having the value type constraint (§10.1.5).

·         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:

o   A is a value type, since all value types have a public default constructor (§4.1.2).

o   A is a type parameter having the constructor constraint (§10.1.5).

o   A is a type parameter having the value type constraint (§10.1.5).

o   A is a class that is not abstract and contains an explicitly declared public constructor with no parameters.

o   A is not abstract and has a default constructor (§10.11.4).

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.

class B<T> where T: IEnumerable {...}

class D<T>: B<T> where T: IEnumerable {...}

class E<T>: B<List<T>> {...}

4.5 Type parameters

A type parameter is an identifier designating a value type or reference type that the parameter is bound to at run-time.

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 (§10.2.4) or interface (§13.1.3).

·         The rules for member lookup on type parameters depend on the constraints, if any, applied to the type parameter. They are detailed in §7.4.

·         The available conversions for a type parameter depend on the constraints, if any, applied to the type parameter. They are detailed in §6.1.10 and §6.2.6.

·         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 (§6.1.10). However, a default expression (§7.6.13) can be used instead. In addition, a value with a type given by a type parameter can be compared with null using == and != (§7.10.6) unless the type parameter has the value type constraint.

·         A new expression (§7.6.10.1) can only be used with a type parameter if the type parameter is constrained by a constructor-constraint or the value type constraint (§10.1.5).

·         A type parameter cannot be used anywhere within an attribute.

·         A type parameter cannot be used in a member access (§7.6.4) or type name (§3.8) to identify a static member or a nested type.

·         In unsafe code, a type parameter cannot be used as an unmanaged-type (§18.2).

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 (§4.4.2). 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.

4.6 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>>:

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:

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:

int i1 = del(1);

int i2 = del2(1);

            After executing this code,  i1 and i2 will both have the value 2.

4.7 The dynamic type

The type dynamic has special meaning in C#. Its purpose is to allow dynamic binding, which is described in detail in §7.2.2.

dynamic is considered identical to object except in the following respects:

·         Operations on expressions of type dynamic can be dynamically bound (§7.2.2).

·         Type inference (§7.5.2) 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.

5. 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 (§5.3) 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.

5.1 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

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.

5.1.1 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 (§10.12) 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 (§5.2) of the variable’s type.

For purposes of definite assignment checking, a static variable is considered initially assigned.

5.1.2 Instance variables

A field declared without the static modifier is called an instance variable.

5.1.2.1 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 (§5.2) of the variable’s type.

For the purpose of definite assignment checking, an instance variable of a class is considered initially assigned.

5.1.2.2 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.

5.1.3 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 (§5.2) of the type of the array elements.

For the purpose of definite assignment checking, an array element is considered initially assigned.

5.1.4 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 (§7.15), 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.

5.1.5 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 §5.1.6.

·         A variable must be definitely assigned (§5.3) 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 (§7.6.7).

5.1.6 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 §5.1.5.

·         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 (§5.3) 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 (§7.6.7).

5.1.7 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 (§7.15.5.1), 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 (§5.3.3.4).

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 (§8.5.1), 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 (§3.9).

5.2 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 (§4.1.2).

·         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.

5.3 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 (§5.3.3), 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 (§5.3.1) is always considered definitely assigned.

·         An initially unassigned variable (§5.3.2) is considered definitely assigned at a given location if all possible execution paths leading to that location contain at least one of the following:

o   A simple assignment (§7.17.1) in which the variable is the left operand.

o   An invocation expression (§7.6.5) or object creation expression (§7.6.10.1) that passes the variable as an output parameter.

o   For a local variable, a local variable declaration (§8.5.1) that includes a variable initializer.

The formal specification underlying the above informal rules is described in §5.3.1, §5.3.2, and §5.3.3.

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

o   the variable is the left operand of a simple assignment,

o   the variable is passed as an output parameter, or

o   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.

5.3.1 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.

5.3.2 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.

5.3.3 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 (§8.1) 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:

o   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.

o   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.

5.3.3.1 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 (§8.1).

·         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 (§8.1).

5.3.3.2 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.

5.3.3.3 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.

5.3.3.4 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).

5.3.3.5 If statements

For an if statement stmt of the form:

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.

5.3.3.6 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.

5.3.3.7 While statements

For a while statement stmt of the form:

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.

5.3.3.8 Do statements

For a do statement stmt of the form:

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.

5.3.3.9 For statements

Definite assignment checking for a for statement of the form:

for ( for-initializer ; for-condition ; for-iterator ) embedded-statement

is done as if the statement were written:

{
   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.

5.3.3.10 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.

5.3.3.11 Throw statements

For a statement stmt of the form

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.

5.3.3.12 Return statements

For a statement stmt of the form

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:

o   after expr

o   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:

return ;

·         If v is an output parameter, then it must be definitely assigned either:

o   before stmt

o   or at the end of the finally block of a try-finally or try-catch-finally that encloses the return statement.

5.3.3.13 Try-catch statements

For a statement stmt of the form:

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

5.3.3.14 Try-finally statements

For a try statement stmt of the form:

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:

o   v is definitely assigned at the end-point of try-block

o   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.)

5.3.3.15 Try-catch-finally statements

Definite assignment analysis for a try-catch-finally statement of the form:

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:

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 (§8.10) affect definite assignment.

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

   }
}

5.3.3.16 Foreach statements

For a foreach statement stmt of the form:

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.

5.3.3.17 Using statements

For a using statement stmt of the form:

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.

5.3.3.18 Lock statements

For a lock statement stmt of the form:

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.

5.3.3.19 Yield statements

For a yield return statement stmt of the form:

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.

5.3.3.20 General rules for simple expressions

The following rule applies to these kinds of expressions: literals (§7.6.1), simple names (§7.6.2), member access expressions (§7.6.4), non-indexed base access expressions (§7.6.8), typeof expressions (§7.6.11), and default value expressions (§7.6.13).

·         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.

5.3.3.21 General rules for expressions with embedded expressions

The following rules apply to these kinds of expressions: parenthesized expressions (§7.6.3), element access expressions (§7.6.6), base access expressions with indexing (§7.6.8), increment and decrement expressions (§7.6.9, §7.7.5), cast expressions (§7.7.6), unary +, -, ~, * expressions, binary +, -, *, /, %, <<, >>, <, <=, >, >=, ==, !=, is, as, &, |, ^ expressions (§7.8, §7.9, §7.10, §7.11), compound assignment expressions (§7.17.2), checked and unchecked expressions (§7.6.12), plus array and delegate creation expressions (§7.6.10).

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 expr1, expr2, ..., exprn, evaluated in that order:

·         The definite assignment state of v at the beginning of expr1 is the same as the definite assignment state at the beginning of expr.

·         The definite assignment state of v at the beginning of expri (i greater than one) is the same as the definite assignment state at the end of expri-1.

·         The definite assignment state of v at the end of expr is the same as the definite assignment state at the end of exprn.

5.3.3.22 Invocation expressions and object creation expressions

For an invocation expression expr of the form:

primary-expression ( arg1 , arg2 , … , argn )

or an object creation expression of the form:

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 argi-1.

·         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 (§7.6.10.4), object initializers (§7.6.10.2), collection initializers (§7.6.10.3) and anonymous object initializers (§7.6.10.6), the definite assignment state is determined by the expansion that these constructs are defined in terms of.

5.3.3.23 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.

·         If w is the same variable as v, 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.

5.3.3.24 && 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:

o   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.

o   Otherwise, if the state of v after expr-first is definitely assigned, then the state of v after expr is definitely assigned.

o   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.

o   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”.

o   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”.

o   Otherwise, the state of v after expr is not definitely assigned.

In the example

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.

5.3.3.25 || 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:

o   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.

o   Otherwise, if the state of v after expr-first is definitely assigned, then the state of v after expr is definitely assigned.

o   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.

o   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”.

o   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”.

o   Otherwise, the state of v after expr is not definitely assigned.

In the example

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.

5.3.3.26 ! 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:

o   If the state of v after expr-operand is definitely assigned, then the state of v after expr is definitely assigned.

o   If the state of v after expr-operand is not definitely assigned, then the state of v after expr is not definitely assigned.

o   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”.

o   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”.

5.3.3.27 ?? 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:

o   If expr-first is a constant expression (§7.19) 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.

5.3.3.28 ?: 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:

o   expr-cond is a constant expression with the value false

o   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:

o   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:

o   If expr-cond is a constant expression (§7.19) with value true then the state of v after expr is the same as the state of v after expr-true.

o   Otherwise, if expr-cond is a constant expression (§7.19) with value false then the state of v after expr is the same as the state of v after expr-false.

o   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.

o   Otherwise, the state of v after expr is not definitely assigned.

5.3.3.29 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

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

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.

 

5.4 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.

variable-reference:
expression

In C and C++, a variable-reference is known as an lvalue.

5.5 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.


6. 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.

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 (§6.4).

6.1 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 (§7.5.4), cast expressions (§7.7.6), and assignments (§7.17).

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 (§6.1.8 and §6.2.6) apply only to expressions of type dynamic (§4.7).

6.1.1 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.

6.1.2 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.

6.1.3 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 (§4.1.10).

6.1.4 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?:

o   If the source value is null (HasValue property is false), the result is the null value of type T?.

o   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 (§4.1.10) 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?.

6.1.5 Null literal conversions

An implicit conversion exists from the null literal to any nullable type. This conversion produces the null value (§4.1.10) of the given nullable type.

6.1.6 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:

o   S and T differ only in element type. In other words, S and T have the same number of dimensions.

o   Both SE and TE are reference-types.

o   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 (§13.1.3.2) to T.

·         Implicit conversions involving type parameters that are known to be reference types. See §6.1.10 for more details on implicit conversions involving type parameters.

The implicit reference conversions are those conversions between reference-types 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.

6.1.7 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 (§13.1.3.2) 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 (§11.3.2).

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 §4.3.1.

6.1.8 Implicit dynamic conversions

An implicit dynamic conversion exists from an expression of type dynamic to any type T. The conversion is dynamically bound (§7.2.2), 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 §6.1 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:

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 dstring – to the target type. A conversion is found to string but not to int.

6.1.9 Implicit constant expression conversions

An implicit constant expression conversion permits the following conversions:

·         A constant-expression (§7.19) 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.

6.1.10 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 (§10.1.5). 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