jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update documentation to reflect fully qualifying the use of .NET types in the generated code.

Browse source
This commit is contained in:
Brant K. Kyser 2013-10-22 11:52:00 -05:00
commit 29c98fa7f8
1 changed files with 76 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

146
Doc/Manual/CSharp.html
View file

@ -10,6 +10,9 @@
<div class="sectiontoc"> <div class="sectiontoc">
<ul> <ul>
<li><a href="#CSharp_introduction">Introduction</a> <li><a href="#CSharp_introduction">Introduction</a>
<ul>
<li><a href="#CSharp_introduction_swig2_compatability">SWIG 2 Compatability</a>
</ul>
<li><a href="#CSharp_differences_java">Differences to the Java module</a> <li><a href="#CSharp_differences_java">Differences to the Java module</a>
<li><a href="#CSharp_void_pointers">Void pointers</a> <li><a href="#CSharp_void_pointers">Void pointers</a>
<li><a href="#CSharp_arrays">C# Arrays</a> <li><a href="#CSharp_arrays">C# Arrays</a>
@ -69,6 +72,12 @@ The <a href="http://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a> h
Monodoc, available from the Mono project, has a very useful section titled <a href="http://www.mono-project.com/Interop_with_Native_Libraries">Interop with native libraries</a>. Monodoc, available from the Mono project, has a very useful section titled <a href="http://www.mono-project.com/Interop_with_Native_Libraries">Interop with native libraries</a>.
</p> </p>
<H3><a name="CSharp_introduction_swig2_compatability"></a>19.1.1 SWIG 2 Compatability</H3>
<p>
In order to minimize name collisions between names generated based on input to SWIG and names used in the generated code from the .NET framework, SWIG 3 fully qualifies the use of all .NET types. Furthermore, SWIG 3 avoids <tt>using</tt> directives in generated code. This breaks backwards compatability with typemaps, pragmas, etc written for use with SWIG 2 that assume the presence of <tt>using System;</tt> or <tt>using System.Runtime.InteropServices;</tt> directives in the intermediate class imports, module imports, or proxy imports. SWIG 3 supports backwards compatability though the use of the <tt>SWIG2_CSHARP</tt> macro. If <tt>SWIG2_CSHARP</tt> is defined, SWIG 3 generates <tt>using</tt> directives in the intermediate class, module class, and proxy class code similar to those generated by SWIG 2. This can be done without modifying any of the input code by passing the <tt>-DSWIG2_CSHARP</tt> commandline parameter when executing <tt>swig</tt>.
</p>
<H2><a name="CSharp_differences_java"></a>19.2 Differences to the Java module</H2> <H2><a name="CSharp_differences_java"></a>19.2 Differences to the Java module</H2>
@ -262,7 +271,7 @@ An example shows that <tt>char *</tt> could be marshalled in different ways,
<div class="code"> <div class="code">
<pre> <pre>
%typemap(imtype, out="IntPtr") char * "string" %typemap(imtype, out="global::System.IntPtr") char * "string"
char * function(char *); char * function(char *);
</pre> </pre>
</div> </div>
@ -273,7 +282,7 @@ The output type is thus IntPtr and the input type is string. The resulting inter
<div class="code"> <div class="code">
<pre> <pre>
public static extern IntPtr function(string jarg1); public static extern global::System.IntPtr function(string jarg1);
</pre> </pre>
</div> </div>
@ -294,8 +303,8 @@ For example:
<div class="code"> <div class="code">
<pre> <pre>
%typemap(imtype, %typemap(imtype,
inattributes="[MarshalAs(UnmanagedType.LPStr)]", inattributes="[global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]",
outattributes="[return: MarshalAs(UnmanagedType.LPStr)]") const char * "String" outattributes="[return: global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]") const char * "String"
const char * GetMsg() {} const char * GetMsg() {}
void SetMsg(const char *msg) {} void SetMsg(const char *msg) {}
@ -310,12 +319,12 @@ The intermediary class will then have the marshalling as specified by everything
<pre> <pre>
class examplePINVOKE { class examplePINVOKE {
... ...
[DllImport("example", EntryPoint="CSharp_GetMsg")] [global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_GetMsg")]
[return: MarshalAs(UnmanagedType.LPStr)] [return: global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]
public static extern String GetMsg(); public static extern String GetMsg();
[DllImport("example", EntryPoint="CSharp_SetMsg")] [global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_SetMsg")]
public static extern void SetMsg([MarshalAs(UnmanagedType.LPStr)]String jarg1); public static extern void SetMsg([global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPStr)]String jarg1);
} }
</pre> </pre>
</div> </div>
@ -368,7 +377,7 @@ will generate a C# proxy class:
<div class="code"> <div class="code">
<pre> <pre>
[ThreadSafe] [ThreadSafe]
public class AClass : IDisposable { public class AClass : global::System.IDisposable {
... ...
[ThreadSafe(false)] [ThreadSafe(false)]
public AClass(double a) ... public AClass(double a) ...
@ -392,9 +401,9 @@ An example for attaching attributes to the enum and enum values is shown below.
<div class="code"> <div class="code">
<pre> <pre>
%typemap(csattributes) Couleur "[System.ComponentModel.Description(\"Colours\")]" %typemap(csattributes) Couleur "[global::System.ComponentModel.Description(\"Colours\")]"
%csattributes Rouge "[System.ComponentModel.Description(\"Red\")]" %csattributes Rouge "[global::System.ComponentModel.Description(\"Red\")]"
%csattributes Vert "[System.ComponentModel.Description(\"Green\")]" %csattributes Vert "[global::System.ComponentModel.Description(\"Green\")]"
%inline %{ %inline %{
enum Couleur { Rouge, Orange, Vert }; enum Couleur { Rouge, Orange, Vert };
%} %}
@ -407,12 +416,12 @@ which will result in the following C# enum:
<div class="code"> <div class="code">
<pre> <pre>
[System.ComponentModel.Description("Colours")] [global::System.ComponentModel.Description("Colours")]
public enum Couleur { public enum Couleur {
[System.ComponentModel.Description("Red")] [global::System.ComponentModel.Description("Red")]
Rouge, Rouge,
Orange, Orange,
[System.ComponentModel.Description("Green")] [global::System.ComponentModel.Description("Green")]
Vert Vert
} }
</pre> </pre>
@ -618,9 +627,9 @@ marshalling for the arrays:
<div class="code"> <div class="code">
<pre> <pre>
[DllImport("example", EntryPoint="CSharp_myArrayCopy")] [global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_myArrayCopy")]
public static extern void myArrayCopy([In, MarshalAs(UnmanagedType.LPArray)]int[] jarg1, public static extern void myArrayCopy([global::System.Runtime.InteropServices.In, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg1,
[Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2, [global::System.Runtime.InteropServices.Out, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
int jarg3); int jarg3);
</pre> </pre>
</div> </div>
@ -668,9 +677,9 @@ and intermediary class method
<div class="code"> <div class="code">
<pre> <pre>
[DllImport("example", EntryPoint="CSharp_myArraySwap")] [global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_myArraySwap")]
public static extern void myArraySwap([In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg1, public static extern void myArraySwap([global::System.Runtime.InteropServices.In, global::System.Runtime.InteropServices.Out, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg1,
[In, Out, MarshalAs(UnmanagedType.LPArray)]int[] jarg2, [global::System.Runtime.InteropServices.In, global::System.Runtime.InteropServices.Out, global::System.Runtime.InteropServices.MarshalAs(UnmanagedType.LPArray)]int[] jarg2,
int jarg3); int jarg3);
</pre> </pre>
</div> </div>
@ -743,7 +752,7 @@ As a result, we get the following method in the module class:
fixed ( int *swig_ptrTo_sourceArray = sourceArray ) { fixed ( int *swig_ptrTo_sourceArray = sourceArray ) {
fixed ( int *swig_ptrTo_targetArray = targetArray ) { fixed ( int *swig_ptrTo_targetArray = targetArray ) {
{ {
examplePINVOKE.myArrayCopy((IntPtr)swig_ptrTo_sourceArray, (IntPtr)swig_ptrTo_targetArray, examplePINVOKE.myArrayCopy((global::System.IntPtr)swig_ptrTo_sourceArray, (global::System.IntPtr)swig_ptrTo_targetArray,
nitems); nitems);
} }
} }
@ -764,8 +773,8 @@ example - the method is expecting an IntPtr as the parameter type.
<div class="code"> <div class="code">
<pre> <pre>
[DllImport("example", EntryPoint="CSharp_myArrayCopy")] [global::System.Runtime.InteropServices.DllImport("example", EntryPoint="CSharp_myArrayCopy")]
public static extern void myArrayCopy(IntPtr jarg1, IntPtr jarg2, int jarg3); public static extern void myArrayCopy(global::System.IntPtr jarg1, global::System.IntPtr jarg2, int jarg3);
</pre> </pre>
</div> </div>
@ -1220,7 +1229,7 @@ the C# code can be generated into the intermediary class using the <tt>imclassco
static CustomExceptionDelegate customDelegate = static CustomExceptionDelegate customDelegate =
new CustomExceptionDelegate(SetPendingCustomException); new CustomExceptionDelegate(SetPendingCustomException);
[DllImport("$dllimport", EntryPoint="CustomExceptionRegisterCallback")] [global::System.Runtime.InteropServices.DllImport("$dllimport", EntryPoint="CustomExceptionRegisterCallback")]
public static extern public static extern
void CustomExceptionRegisterCallback(CustomExceptionDelegate customCallback); void CustomExceptionRegisterCallback(CustomExceptionDelegate customCallback);
@ -1264,7 +1273,7 @@ The boiler plate code above must be used in addition to a handcrafted <tt>Custom
<div class="code"> <div class="code">
<pre> <pre>
// Custom C# Exception // Custom C# Exception
class CustomApplicationException : System.ApplicationException { class CustomApplicationException : global::System.ApplicationException {
public CustomApplicationException(string message) public CustomApplicationException(string message)
: base(message) { : base(message) {
} }
@ -1457,20 +1466,17 @@ Below is the generated C# <tt>Base</tt> director class.
<div class="code"> <div class="code">
<pre> <pre>
using System; public class Base : global::System.IDisposable {
using System.Runtime.InteropServices; private global::System.Runtime.InteropServices.HandleRef swigCPtr;
public class Base : IDisposable {
private HandleRef swigCPtr;
protected bool swigCMemOwn; protected bool swigCMemOwn;
internal Base(IntPtr cPtr, bool cMemoryOwn) { internal Base(global::System.IntPtr cPtr, bool cMemoryOwn) {
swigCMemOwn = cMemoryOwn; swigCMemOwn = cMemoryOwn;
swigCPtr = new HandleRef(this, cPtr); swigCPtr = new global::System.Runtime.InteropServices.HandleRef(this, cPtr);
} }
internal static HandleRef getCPtr(Base obj) { internal static global::System.Runtime.InteropServices.HandleRef getCPtr(Base obj) {
return (obj == null) ? new HandleRef(null, IntPtr.Zero) : obj.swigCPtr; return (obj == null) ? new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero) : obj.swigCPtr;
} }
~Base() { ~Base() {
@ -1479,12 +1485,12 @@ public class Base : IDisposable {
public virtual void Dispose() { public virtual void Dispose() {
lock(this) { lock(this) {
if(swigCPtr.Handle != IntPtr.Zero &amp;&amp; swigCMemOwn) { if(swigCPtr.Handle != global::System.IntPtr.Zero &amp;&amp; swigCMemOwn) {
swigCMemOwn = false; swigCMemOwn = false;
examplePINVOKE.delete_Base(swigCPtr); examplePINVOKE.delete_Base(swigCPtr);
} }
swigCPtr = new HandleRef(null, IntPtr.Zero); swigCPtr = new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero);
GC.SuppressFinalize(this); global::System.GC.SuppressFinalize(this);
} }
} }
@ -1511,7 +1517,7 @@ public class Base : IDisposable {
examplePINVOKE.Base_director_connect(swigCPtr, swigDelegate0, swigDelegate1); examplePINVOKE.Base_director_connect(swigCPtr, swigDelegate0, swigDelegate1);
} }
private bool SwigDerivedClassHasMethod(string methodName, Type[] methodTypes) { private bool SwigDerivedClassHasMethod(string methodName, global::System.global::System.Type[] methodTypes) {
System.Reflection.MethodInfo methodInfo = this.GetType().GetMethod(methodName, methodTypes); System.Reflection.MethodInfo methodInfo = this.GetType().GetMethod(methodName, methodTypes);
bool hasDerivedMethod = methodInfo.DeclaringType.IsSubclassOf(typeof(Base)); bool hasDerivedMethod = methodInfo.DeclaringType.IsSubclassOf(typeof(Base));
return hasDerivedMethod; return hasDerivedMethod;
@ -1521,18 +1527,18 @@ public class Base : IDisposable {
return UIntMethod(x); return UIntMethod(x);
} }
private void SwigDirectorBaseBoolMethod(IntPtr b, bool flag) { private void SwigDirectorBaseBoolMethod(global::System.IntPtr b, bool flag) {
BaseBoolMethod(new Base(b, false), flag); BaseBoolMethod(new Base(b, false), flag);
} }
internal delegate uint SwigDelegateBase_0(uint x); internal delegate uint SwigDelegateBase_0(uint x);
internal delegate void SwigDelegateBase_1(IntPtr b, bool flag); internal delegate void SwigDelegateBase_1(global::System.IntPtr b, bool flag);
private SwigDelegateBase_0 swigDelegate0; private SwigDelegateBase_0 swigDelegate0;
private SwigDelegateBase_1 swigDelegate1; private SwigDelegateBase_1 swigDelegate1;
private static Type[] swigMethodTypes0 = new Type[] { typeof(uint) }; private static global::System.Type[] swigMethodTypes0 = new global::System.Type[] { typeof(uint) };
private static Type[] swigMethodTypes1 = new Type[] { typeof(Base), typeof(bool) }; private static global::System.Type[] swigMethodTypes1 = new global::System.Type[] { typeof(Base), typeof(bool) };
} }
</pre> </pre>
</div> </div>
@ -1755,9 +1761,9 @@ and the following usage from C# after running the code through SWIG:
Wheel wheel = new Bike(10).getWheel(); Wheel wheel = new Bike(10).getWheel();
Console.WriteLine("wheel size: " + wheel.size); Console.WriteLine("wheel size: " + wheel.size);
// Simulate a garbage collection // Simulate a garbage collection
System.GC.Collect(); global::System.GC.Collect();
System.GC.WaitForPendingFinalizers(); global::System.GC.WaitForPendingFinalizers();
Console.WriteLine("wheel size: " + wheel.size); global::System.Console.WriteLine("wheel size: " + wheel.size);
</pre> </pre>
</div> </div>
@ -1795,9 +1801,9 @@ is called using the following typemaps.
// of dangling C++ pointer. Intended for methods that return pointers or // of dangling C++ pointer. Intended for methods that return pointers or
// references to a member variable. // references to a member variable.
%typemap(csout, excode=SWIGEXCODE) Wheel&amp; getWheel { %typemap(csout, excode=SWIGEXCODE) Wheel&amp; getWheel {
IntPtr cPtr = $imcall;$excode global::System.IntPtr cPtr = $imcall;$excode
$csclassname ret = null; $csclassname ret = null;
if (cPtr != IntPtr.Zero) { if (cPtr != global::System.IntPtr.Zero) {
ret = new $csclassname(cPtr, $owner); ret = new $csclassname(cPtr, $owner);
ret.addReference(this); ret.addReference(this);
} }
@ -1813,7 +1819,7 @@ The code in the second typemap constitutes the bulk of the code in the generated
<div class="code"> <div class="code">
<pre> <pre>
public class Wheel : IDisposable { public class Wheel : global::System.IDisposable {
... ...
// Ensure that the GC doesn't collect any Bike instance set from C# // Ensure that the GC doesn't collect any Bike instance set from C#
private Bike bikeReference; private Bike bikeReference;
@ -1822,12 +1828,12 @@ public class Wheel : IDisposable {
} }
} }
public class Bike : IDisposable { public class Bike : global::System.IDisposable {
... ...
public Wheel getWheel() { public Wheel getWheel() {
IntPtr cPtr = examplePINVOKE.Bike_getWheel(swigCPtr); global::System.IntPtr cPtr = examplePINVOKE.Bike_getWheel(swigCPtr);
Wheel ret = null; Wheel ret = null;
if (cPtr != IntPtr.Zero) { if (cPtr != global::System.IntPtr.Zero) {
ret = new Wheel(cPtr, false); ret = new Wheel(cPtr, false);
ret.addReference(this); ret.addReference(this);
} }
@ -1904,9 +1910,9 @@ In order to understand why, consider a garbage collection occuring...
container.setElement(element); container.setElement(element);
Console.WriteLine("element.value: " + container.getElement().value); Console.WriteLine("element.value: " + container.getElement().value);
// Simulate a garbage collection // Simulate a garbage collection
System.GC.Collect(); global::System.GC.Collect();
System.GC.WaitForPendingFinalizers(); global::System.GC.WaitForPendingFinalizers();
Console.WriteLine("element.value: " + container.getElement().value); global::System.Console.WriteLine("element.value: " + container.getElement().value);
</pre> </pre>
</div> </div>
@ -1918,14 +1924,14 @@ One solution is to add in the appropriate references in the C# layer...
<div class="code"> <div class="code">
<pre> <pre>
public class Container : IDisposable { public class Container : global::System.IDisposable {
... ...
// Ensure that the GC doesn't collect any Element set from C# // Ensure that the GC doesn't collect any Element set from C#
// as the underlying C++ class stores a shallow copy // as the underlying C++ class stores a shallow copy
private Element elementReference; private Element elementReference;
private HandleRef getCPtrAndAddReference(Element element) { private global::System.Runtime.InteropServices.HandleRef getCPtrAndAddReference(Element element) {
elementReference = element; elementReference = element;
return Element.getCPtr(element); return Element.getCPtr(element);
} }
@ -1951,7 +1957,7 @@ The 'cscode' typemap simply adds in the specified code into the C# proxy class.
// Ensure that the GC doesn't collect any Element set from C# // Ensure that the GC doesn't collect any Element set from C#
// as the underlying C++ class stores a shallow copy // as the underlying C++ class stores a shallow copy
private Element elementReference; private Element elementReference;
private HandleRef getCPtrAndAddReference(Element element) { private global::System.Runtime.InteropServices.HandleRef getCPtrAndAddReference(Element element) {
elementReference = element; elementReference = element;
return Element.getCPtr(element); return Element.getCPtr(element);
} }
@ -2000,7 +2006,7 @@ First let's look at the code that is generated by default, where the C# proxy cl
<div class="code"> <div class="code">
<pre> <pre>
public class Action : IDisposable { public class Action : global::System.IDisposable {
... ...
public Action(CDate dateIn, CDate dateOut) public Action(CDate dateIn, CDate dateOut)
: this(examplePINVOKE.new_Action(CDate.getCPtr(dateIn), CDate.getCPtr(dateOut)), true) { : this(examplePINVOKE.new_Action(CDate.getCPtr(dateIn), CDate.getCPtr(dateOut)), true) {
@ -2081,7 +2087,7 @@ The resulting generated proxy code in the <tt>Action</tt> class follows:
<div class="code"> <div class="code">
<pre> <pre>
public class Action : IDisposable { public class Action : global::System.IDisposable {
... ...
public int doSomething(System.DateTime dateIn, out System.DateTime dateOut) { public int doSomething(System.DateTime dateIn, out System.DateTime dateOut) {
CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day); CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
@ -2099,7 +2105,7 @@ public class Action : IDisposable {
} }
} }
static private IntPtr SwigConstructAction(System.DateTime dateIn, out System.DateTime dateOut) { static private global::System.IntPtr SwigConstructAction(System.DateTime dateIn, out System.DateTime dateOut) {
CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day); CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
CDate tempdateOut = new CDate(); CDate tempdateOut = new CDate();
try { try {
@ -2299,8 +2305,8 @@ The typemap type required is thus <tt>CDate *</tt>. Given that the previous sect
%typemap(csvarout, excode=SWIGEXCODE2) CDate * %{ %typemap(csvarout, excode=SWIGEXCODE2) CDate * %{
/* csvarout typemap code */ /* csvarout typemap code */
get { get {
IntPtr cPtr = $imcall; global::System.IntPtr cPtr = $imcall;
CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, $owner);$excode CDate tempDate = (cPtr == global::System.IntPtr.Zero) ? null : new CDate(cPtr, $owner);$excode
return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(), return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
0, 0, 0); 0, 0, 0);
} %} } %}
@ -2322,8 +2328,8 @@ public class example {
} }
/* csvarout typemap code */ /* csvarout typemap code */
get { get {
IntPtr cPtr = examplePINVOKE.ImportantDate_get(); global::System.IntPtr cPtr = examplePINVOKE.ImportantDate_get();
CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, false); CDate tempDate = (cPtr == global::System.IntPtr.Zero) ? null : new CDate(cPtr, false);
return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(), return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
0, 0, 0); 0, 0, 0);
} }
@ -2389,7 +2395,7 @@ The generated proxy class code will then contain the following wrapper for calli
<div class="code"><pre> <div class="code"><pre>
... ...
private void SwigDirectorsomeCallback(IntPtr date) { private void SwigDirectorsomeCallback(global::System.IntPtr date) {
System.DateTime tempdate = new System.DateTime(); System.DateTime tempdate = new System.DateTime();
try { try {
someCallback(out tempdate); someCallback(out tempdate);
@ -2432,7 +2438,7 @@ The default C# proxy class generated is:
<div class="code"> <div class="code">
<pre> <pre>
public class ExtendMe : IDisposable { public class ExtendMe : global::System.IDisposable {
... ...
public int Part1() { public int Part1() {
... ...
@ -2468,7 +2474,7 @@ The C# proxy class becomes a partial class:
<div class="code"> <div class="code">
<pre> <pre>
public partial class ExtendMe : IDisposable { public partial class ExtendMe : global::System.IDisposable {
... ...
public int Part1() { public int Part1() {
... ...
@ -2483,7 +2489,7 @@ You can then of course declare another part of the partial class elsewhere, for
<div class="code"> <div class="code">
<pre> <pre>
public partial class ExtendMe : IDisposable { public partial class ExtendMe : global::System.IDisposable {
public int Part2() { public int Part2() {
return 2; return 2;
} }
@ -2535,7 +2541,7 @@ The generated C# proxy class will instead be:
<div class="code"> <div class="code">
<pre> <pre>
public class ExtendMe : IDisposable { public class ExtendMe : global::System.IDisposable {
... ...
public int Part3() { public int Part3() {
return 3; return 3;