mcs/docs/ecma334/14.5.10.3.xml

   1 <?xml version="1.0"?>
   2 <clause number="14.5.10.3" title="Delegate creation expressions">
   3   <paragraph>A <non_terminal where="14.5.10.3">delegate-creation-expression</non_terminal> is used to create a new instance of a <non_terminal where="11.2">delegate-type</non_terminal>. <grammar_production><name><non_terminal where="14.5.10.3">delegate-creation-expression</non_terminal></name> : <rhs><keyword>new</keyword><non_terminal where="11.2">delegate-type</non_terminal><terminal>(</terminal><non_terminal where="14.14">expression</non_terminal><terminal>)</terminal></rhs></grammar_production></paragraph>
   4   <paragraph>The argument of a delegate creation expression must be a method group (<hyperlink>14.1</hyperlink>) or a value of a  <non_terminal where="11.2">delegate-type</non_terminal>. If the argument is a method group, it identifies the method and, for an instance method, the object for which to create a delegate. If the argument is a value of a <non_terminal where="11.2">delegate-type</non_terminal>, it identifies a delegate instance of which to create a copy. </paragraph>
   5   <paragraph>The compile-time processing of a <non_terminal where="14.5.10.3">delegate-creation-expression</non_terminal> of the form new D(E), where D is a <non_terminal where="11.2">delegate-type</non_terminal> and E is an expression, consists of the following steps: <list><list_item> If E is a method group: </list_item><list><list_item> The set of methods identified by E must include exactly one method that is compatible (<hyperlink>22.1</hyperlink>) with D, and this method becomes the one to which the newly created delegate refers. If no matching method exists, or if more than one matching method exists, a compile-time error occurs. If the selected method is an instance method, the instance expression associated with E determines the target object of the delegate. </list_item><list_item> As in a method invocation, the selected method must be compatible with the context of the method group: If the method is a static method, the method group must have resulted from a <non_terminal where="14.5.2">simple-name</non_terminal> or a <non_terminal where="14.5.4">member-access</non_terminal> through a type. If the method is an instance method, the method group must have resulted from a <non_terminal where="14.5.2">simple-name</non_terminal> or a <non_terminal where="14.5.4">member-access</non_terminal> through a variable or value. If the selected method does not match the context of the method group, a compile-time error occurs. </list_item><list_item> The result is a value of type D, namely a newly created delegate that refers to the selected method and target object. </list_item></list><list_item> Otherwise, if E is a value of a delegate-type: </list_item><list><list_item> D and E must be compatible (<hyperlink>22.1</hyperlink>); otherwise, a compile-time error occurs. </list_item><list_item> The result is a value of type D, namely a newly created delegate that refers to the same invocation list as E. </list_item></list><list_item> Otherwise, the delegate creation expression is invalid, and a compile-time error occurs. </list_item></list></paragraph>
   6   <paragraph>The run-time processing of a <non_terminal where="14.5.10.3">delegate-creation-expression</non_terminal> of the form new D(E), where D is a <non_terminal where="11.2">delegate-type</non_terminal> and E is an expression, consists of the following steps: <list><list_item> If E is a method group: </list_item><list><list_item> If the method selected at compile-time is a static method, the target object of the delegate is null. Otherwise, the selected method is an instance method, and the target object of the delegate is determined from the instance expression associated with E: </list_item><list><list_item> The instance expression is evaluated. If this evaluation causes an exception, no further steps are executed. </list_item><list_item> If the instance expression is of a <non_terminal where="11.2">reference-type</non_terminal>, the value computed by the instance expression becomes the target object. If the target object is null, a System.NullReferenceException is thrown and no further steps are executed. </list_item><list_item> If the instance expression is of a <non_terminal where="11.1">value-type</non_terminal>, a boxing operation (<hyperlink>11.3.1</hyperlink>) is performed to convert the value to an object, and this object becomes the target object. </list_item></list><list_item> A new instance of the delegate type D is allocated. If there is not enough memory available to allocate the new instance, a System.OutOfMemoryException is thrown and no further steps are executed. </list_item><list_item> The new delegate instance is initialized with a reference to the method that was determined at compile-time and a reference to the target object computed above. </list_item></list><list_item> If E is a value of a delegate-type: </list_item><list><list_item> E is evaluated. If this evaluation causes an exception, no further steps are executed. </list_item><list_item> If the value of E is null, a System.NullReferenceException is thrown and no further steps are executed. </list_item><list_item> A new instance of the delegate type D is allocated. If there is not enough memory available to allocate the new instance, a System.OutOfMemoryException is thrown and no further steps are executed. </list_item><list_item> The new delegate instance is initialized with references to the same invocation list as the delegate instance given by E. </list_item></list></list></paragraph>
   7   <paragraph>The method and object to which a delegate refers are determined when the delegate is instantiated and then remain constant for the entire lifetime of the delegate. In other words, it is not possible to change the target method or object of a delegate once it has been created. <note>[Note: Remember, when two delegates are combined or one is removed from another, a new delegate results; no existing delegate has its content changed. end note]</note> </paragraph>
   8   <paragraph>It is not possible to create a delegate that refers to a property, indexer, user-defined operator, instance constructor, destructor, or static constructor. </paragraph>
   9   <paragraph>
  10     <example>[Example: As described above, when a delegate is created from a method group, the formal parameter list and return type of the delegate determine which of the overloaded methods to select. In the example <code_example><![CDATA[
  11 delegate double DoubleFunc(double x);
  12 class A
  13 {
  14    DoubleFunc f = new DoubleFunc(Square);
  15    static float Square(float x) {
  16       return x * x;
  17    }
  18    static double Square(double x) {
  19       return x * x;
  20    }
  21 }
  22 ]]></code_example>the A.f field is initialized with a delegate that refers to the second Square method because that method exactly matches the formal parameter list and return type of DoubleFunc. Had the second Square method not been present, a compile-time error would have occurred. end example]</example>
  23   </paragraph>
  24 </clause>