diff --git a/includes/provider-string-format.md b/includes/provider-string-format.md deleted file mode 100644 index 306d2b59430..00000000000 --- a/includes/provider-string-format.md +++ /dev/null @@ -1,4 +0,0 @@ - -However, when calling the **String.Format** method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with an object that provides culture-sensitive or custom formatting and a [composite format string](/dotnet/standard/base-types/composite-formatting) that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. Your language compiler will then resolve your method call to a particular overload of the **String.Format** method. - -For more detailed documentation on using the **String.Format** method, see [Getting started with the String.Format method](#Starting) and [Which method do I call?](#FTaskList). diff --git a/includes/remarks/System.Threading/WaitHandle/exit-context.md b/includes/remarks/System.Threading/WaitHandle/exit-context.md new file mode 100644 index 00000000000..e5fe17595a7 --- /dev/null +++ b/includes/remarks/System.Threading/WaitHandle/exit-context.md @@ -0,0 +1,7 @@ +## Exiting the context + +The `exitContext` parameter has no effect unless this method is called from inside a nondefault managed context. The managed context can be nondefault if your thread is inside a call to an instance of a class derived from . Even if you're currently executing a method on a class that isn't derived from , like , you can be in a nondefault context if a is on your stack in the current application domain. + +When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing this method. The thread returns to the original nondefault context after the call to this method completes. + +Exiting the context can be useful when the context-bound class has the attribute. In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls this method and specifies `true` for `exitContext`, the thread exits the synchronization domain, which allows a thread that's blocked on a call to any member of the object to proceed. When this method returns, the thread that made the call must wait to reenter the synchronization domain. diff --git a/includes/remarks/System/String/provider-string-format.md b/includes/remarks/System/String/provider-string-format.md new file mode 100644 index 00000000000..3cf9c93e3d9 --- /dev/null +++ b/includes/remarks/System/String/provider-string-format.md @@ -0,0 +1,4 @@ + +However, when calling the `String.Format` method, it's not necessary to focus on the particular overload that you want to call. Instead, you can call the method with an object that provides culture-sensitive or custom formatting and a [composite format string](/dotnet/standard/base-types/composite-formatting) that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. The language compiler will then resolve your method call to a particular overload of the `String.Format` method. + +For more detailed documentation on using the `String.Format` method, see [Get started with the String.Format method](/dotnet/fundamentals/runtime-libraries/system-string-format#get-started-with-the-stringformat-method) and [Which method do I call?](/dotnet/fundamentals/runtime-libraries/system-string-format#which-method-do-i-call). diff --git a/includes/remarks/System/String/simple-string-format.md b/includes/remarks/System/String/simple-string-format.md new file mode 100644 index 00000000000..945d27e76f1 --- /dev/null +++ b/includes/remarks/System/String/simple-string-format.md @@ -0,0 +1,4 @@ + +However, when calling the `String.Format` method, it's not necessary to focus on the particular overload that you want to call. Instead, you can call the method with a [composite format string](/dotnet/standard/base-types/composite-formatting) that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. The language compiler will then resolve your method call to a particular overload of the `String.Format` method. + +For more detailed documentation on using the `String.Format` method, see [Get started with the String.Format method](/dotnet/fundamentals/runtime-libraries/system-string-format#get-started-with-the-stringformat-method) and [Which method do I call?](/dotnet/fundamentals/runtime-libraries/system-string-format#which-method-do-i-call). diff --git a/includes/simple-string-format.md b/includes/simple-string-format.md deleted file mode 100644 index 69f532cb8a8..00000000000 --- a/includes/simple-string-format.md +++ /dev/null @@ -1,4 +0,0 @@ - -However, when calling the **String.Format** method, it is not necessary to focus on the particular overload that you want to call. Instead, you can call the method with a [composite format string](/dotnet/standard/base-types/composite-formatting) that includes one or more format items. You assign each format item a numeric index; the first index starts at 0. In addition to the initial string, your method call should have as many additional arguments as it has index values. For example, a string whose format items have indexes of 0 and 1 should have 2 arguments; one with indexes 0 through 5 should have 6 arguments. Your language compiler will then resolve your method call to a particular overload of the **String.Format** method. - -For more detailed documentation on using the **String.Format** method, see [Getting started with the String.Format method](#Starting) and [Which method do I call?](#FTaskList). diff --git a/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/sbyte_ctor1.cpp b/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/sbyte_ctor1.cpp deleted file mode 100644 index 73564560436..00000000000 --- a/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/sbyte_ctor1.cpp +++ /dev/null @@ -1,20 +0,0 @@ -// SByte_Ctor1.cpp : Defines the entry point for the console application. -// - -//#include "stdafx.h" - -// -using namespace System; - -void main() -{ - char chars[] = { 'a', 'b', 'c', 'd', '\x00' }; - - char* charPtr = chars; - String^ value = gcnew String(charPtr); - - Console::WriteLine(value); -} -// The example displays the following output: -// abcd -// \ No newline at end of file diff --git a/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/Async1.cs b/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/Async1.cs deleted file mode 100644 index 3d41682b13b..00000000000 --- a/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/Async1.cs +++ /dev/null @@ -1,45 +0,0 @@ -// -using System; -using System.Collections.Generic; -using System.Globalization; -using System.Runtime.Versioning; -using System.Threading; -using System.Threading.Tasks; - -public class Example14 -{ - public static async Task Main() - { - var tasks = new List(); - Console.WriteLine("The current culture is {0}", - Thread.CurrentThread.CurrentCulture.Name); - Thread.CurrentThread.CurrentCulture = new CultureInfo("pt-BR"); - // Change the current culture to Portuguese (Brazil). - Console.WriteLine("Current culture changed to {0}", - Thread.CurrentThread.CurrentCulture.Name); - Console.WriteLine("Application thread is thread {0}", - Thread.CurrentThread.ManagedThreadId); - // Launch six tasks and display their current culture. - for (int ctr = 0; ctr <= 5; ctr++) - tasks.Add(Task.Run(() => - { - Console.WriteLine("Culture of task {0} on thread {1} is {2}", - Task.CurrentId, - Thread.CurrentThread.ManagedThreadId, - Thread.CurrentThread.CurrentCulture.Name); - })); - - await Task.WhenAll(tasks.ToArray()); - } -} -// The example displays output like the following: -// The current culture is en-US -// Current culture changed to pt-BR -// Application thread is thread 9 -// Culture of task 2 on thread 11 is pt-BR -// Culture of task 1 on thread 10 is pt-BR -// Culture of task 3 on thread 11 is pt-BR -// Culture of task 5 on thread 11 is pt-BR -// Culture of task 6 on thread 11 is pt-BR -// Culture of task 4 on thread 10 is pt-BR -// diff --git a/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/Get1.cs b/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/Get1.cs deleted file mode 100644 index 98d2006ff12..00000000000 --- a/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/Get1.cs +++ /dev/null @@ -1,16 +0,0 @@ -// -using System; -using System.Globalization; - -public class Example5 -{ - public static void Main() - { - CultureInfo culture = CultureInfo.CurrentCulture; - Console.WriteLine("The current culture is {0} [{1}]", - culture.NativeName, culture.Name); - } -} -// The example displays output like the following: -// The current culture is English (United States) [en-US] -// diff --git a/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/aspculture13.cs b/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/aspculture13.cs deleted file mode 100644 index f35caeb4dc8..00000000000 --- a/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/aspculture13.cs +++ /dev/null @@ -1,20 +0,0 @@ -using System; -using System.Globalization; -using System.Threading; - -public class Example13 -{ - public static void Main() - { - // - CultureInfo.CurrentCulture = CultureInfo.CreateSpecificCulture(Request13.UserLanguages[0]); - // - } -} - -public class Request13 -{ - private static string[] langs = new string[3]; - - public static string[] UserLanguages { get { return langs; } } -} diff --git a/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/changeculture11.cs b/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/changeculture11.cs deleted file mode 100644 index a3fe1c883cd..00000000000 --- a/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/changeculture11.cs +++ /dev/null @@ -1,36 +0,0 @@ -// -using System; -using System.Globalization; -using System.Threading; - -public class Info11 : MarshalByRefObject -{ - public void ShowCurrentCulture() - { - Console.WriteLine("Culture of {0} in application domain {1}: {2}", - Thread.CurrentThread.Name, - AppDomain.CurrentDomain.FriendlyName, - CultureInfo.CurrentCulture.Name); - } -} - -public class Example11 -{ - public static void Main() - { - Info11 inf = new Info11(); - // Set the current culture to Dutch (Netherlands). - Thread.CurrentThread.Name = "MainThread"; - CultureInfo.CurrentCulture = CultureInfo.CreateSpecificCulture("nl-NL"); - inf.ShowCurrentCulture(); - - // Create a new application domain. - AppDomain ad = AppDomain.CreateDomain("Domain2"); - Info11 inf2 = (Info11)ad.CreateInstanceAndUnwrap(typeof(Info11).Assembly.FullName, "Info11"); - inf2.ShowCurrentCulture(); - } -} -// The example displays the following output: -// Culture of MainThread in application domain ChangeCulture1.exe: nl-NL -// Culture of MainThread in application domain Domain2: nl-NL -// diff --git a/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/specific12.cs b/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/specific12.cs deleted file mode 100644 index f399f3d8a11..00000000000 --- a/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/specific12.cs +++ /dev/null @@ -1,28 +0,0 @@ -// -using System; -using System.Globalization; -using System.Threading; - -public class Example12 -{ - public static void Main() - { - double value = 1634.92; - CultureInfo.CurrentCulture = new CultureInfo("fr-CA"); - Console.WriteLine("Current Culture: {0}", - CultureInfo.CurrentCulture.Name); - Console.WriteLine("{0:C2}\n", value); - - Thread.CurrentThread.CurrentCulture = new CultureInfo("fr"); - Console.WriteLine("Current Culture: {0}", - CultureInfo.CurrentCulture.Name); - Console.WriteLine("{0:C2}", value); - } -} -// The example displays the following output: -// Current Culture: fr-CA -// 1 634,92 $ -// -// Current Culture: fr -// 1 634,92 € -// diff --git a/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/Async1.cs b/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/Async1.cs deleted file mode 100644 index 7f27349f8ef..00000000000 --- a/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/Async1.cs +++ /dev/null @@ -1,46 +0,0 @@ -// -using System; -using System.Collections.Generic; -using System.Globalization; -using System.Runtime.Versioning; -using System.Threading; -using System.Threading.Tasks; - -[assembly:TargetFramework(".NETFramework,Version=v4.6")] - -public class Example -{ - public static async Task Main() - { - var tasks = new List(); - Console.WriteLine("The current UI culture is {0}", - Thread.CurrentThread.CurrentUICulture.Name); - Thread.CurrentThread.CurrentUICulture = new CultureInfo("pt-BR"); - // Change the current UI culture to Portuguese (Brazil). - Console.WriteLine("Current UI culture changed to {0}", - Thread.CurrentThread.CurrentUICulture.Name); - Console.WriteLine("Application thread is thread {0}", - Thread.CurrentThread.ManagedThreadId); - // Launch six tasks and display their current culture. - for (int ctr = 0; ctr <= 5; ctr++) - tasks.Add(Task.Run( () => { - Console.WriteLine("UI Culture of task {0} on thread {1} is {2}", - Task.CurrentId, - Thread.CurrentThread.ManagedThreadId, - Thread.CurrentThread.CurrentUICulture.Name); - } )); - - await Task.WhenAll(tasks.ToArray()); - } -} -// The example displays output like the following: -// The current UI culture is en-US -// Current UI culture changed to pt-BR -// Application thread is thread 9 -// UI Culture of task 2 on thread 11 is pt-BR -// UI Culture of task 1 on thread 10 is pt-BR -// UI Culture of task 3 on thread 11 is pt-BR -// UI Culture of task 5 on thread 11 is pt-BR -// UI Culture of task 6 on thread 11 is pt-BR -// UI Culture of task 4 on thread 10 is pt-BR -// diff --git a/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/Get1.cs b/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/Get1.cs deleted file mode 100644 index 4607fd1b8a3..00000000000 --- a/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/Get1.cs +++ /dev/null @@ -1,16 +0,0 @@ -// -using System; -using System.Globalization; - -public class Example -{ - public static void Main() - { - CultureInfo culture = CultureInfo.CurrentUICulture; - Console.WriteLine("The current UI culture is {0} [{1}]", - culture.NativeName, culture.Name); - } -} -// The example displays output like the following: -// The current UI culture is English (United States) [en-US] -// diff --git a/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/currentuiculture1.cs b/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/currentuiculture1.cs deleted file mode 100644 index 6d0bd894983..00000000000 --- a/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/currentuiculture1.cs +++ /dev/null @@ -1,20 +0,0 @@ -// -using System; -using System.Globalization; - -public class Example -{ - public static void Main() - { - Console.WriteLine("The current UI culture: {0}", - CultureInfo.CurrentUICulture.Name); - - CultureInfo.CurrentUICulture = CultureInfo.CreateSpecificCulture("fr-FR"); - Console.WriteLine("The current UI culture: {0}", - CultureInfo.CurrentUICulture.Name); - } -} -// The example displays output like the following: -// The current UI culture: en-US -// The current UI culture: fr-FR -// \ No newline at end of file diff --git a/snippets/csharp/System.Globalization/CultureInfo/InvariantCulture/persist1.cs b/snippets/csharp/System.Globalization/CultureInfo/InvariantCulture/persist1.cs deleted file mode 100644 index 4ef8155d425..00000000000 --- a/snippets/csharp/System.Globalization/CultureInfo/InvariantCulture/persist1.cs +++ /dev/null @@ -1,52 +0,0 @@ -// -using System; -using System.IO; -using System.Globalization; - -public class Example -{ - public static void Main() - { - // Persist the date and time data. - StreamWriter sw = new StreamWriter(@".\DateData.dat"); - - // Create a DateTime value. - DateTime dtIn = DateTime.Now; - // Retrieve a CultureInfo object. - CultureInfo invC = CultureInfo.InvariantCulture; - - // Convert the date to a string and write it to a file. - sw.WriteLine(dtIn.ToString("r", invC)); - sw.Close(); - - // Restore the date and time data. - StreamReader sr = new StreamReader(@".\DateData.dat"); - String input; - while ((input = sr.ReadLine()) != null) - { - Console.WriteLine("Stored data: {0}\n" , input); - - // Parse the stored string. - DateTime dtOut = DateTime.Parse(input, invC, DateTimeStyles.RoundtripKind); - - // Create a French (France) CultureInfo object. - CultureInfo frFr = new CultureInfo("fr-FR"); - // Displays the date formatted for the "fr-FR" culture. - Console.WriteLine("Date formatted for the {0} culture: {1}" , - frFr.Name, dtOut.ToString("f", frFr)); - - // Creates a German (Germany) CultureInfo object. - CultureInfo deDe= new CultureInfo("de-De"); - // Displays the date formatted for the "de-DE" culture. - Console.WriteLine("Date formatted for {0} culture: {1}" , - deDe.Name, dtOut.ToString("f", deDe)); - } - sr.Close(); - } -} -// The example displays the following output: -// Stored data: Tue, 15 May 2012 16:34:16 GMT -// -// Date formatted for the fr-FR culture: mardi 15 mai 2012 16:34 -// Date formatted for de-DE culture: Dienstag, 15. Mai 2012 16:34 -// diff --git a/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/showdate.cs b/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/showdate.cs deleted file mode 100644 index dc0cf267cbd..00000000000 --- a/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/showdate.cs +++ /dev/null @@ -1,41 +0,0 @@ -// -using System; -using System.Globalization; -using System.Resources; -using System.Threading; - -[assembly:NeutralResourcesLanguage("en")] - -public class Example -{ - public static void Main() - { - string[] cultureNames = { "en-US", "fr-FR", "ru-RU", "sv-SE" }; - ResourceManager rm = new ResourceManager("DateStrings", - typeof(Example).Assembly); - - foreach (var cultureName in cultureNames) { - CultureInfo culture = CultureInfo.CreateSpecificCulture(cultureName); - Thread.CurrentThread.CurrentCulture = culture; - Thread.CurrentThread.CurrentUICulture = culture; - - Console.WriteLine("Current UI Culture: {0}", - CultureInfo.CurrentUICulture.Name); - string dateString = rm.GetString("DateStart"); - Console.WriteLine("{0} {1:M}.\n", dateString, DateTime.Now); - } - } -} -// The example displays output similar to the following: -// Current UI Culture: en-US -// Today is February 03. -// -// Current UI Culture: fr-FR -// Aujourd'hui, c'est le 3 février -// -// Current UI Culture: ru-RU -// Сегодня февраля 03. -// -// Current UI Culture: sv-SE -// Today is den 3 februari. -// diff --git a/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/showdate2.cs b/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/showdate2.cs deleted file mode 100644 index 688376b31e7..00000000000 --- a/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/showdate2.cs +++ /dev/null @@ -1,33 +0,0 @@ -// -using System; -using System.Globalization; -using System.Resources; -using System.Threading; - -[assembly:NeutralResourcesLanguage("en")] - -public class Example -{ - public static void Main() - { - Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("ru-RU"); - Thread.CurrentThread.CurrentUICulture = CultureInfo.CreateSpecificCulture("ru-RU"); - - string[] cultureNames = { "fr-FR", "sv-SE" }; - ResourceManager rm = new ResourceManager("DateStrings", - typeof(Example).Assembly); - - foreach (var cultureName in cultureNames) { - CultureInfo culture = CultureInfo.CreateSpecificCulture(cultureName); - string dateString = rm.GetString("DateStart", culture); - Console.WriteLine("{0}: {1} {2}.", culture.DisplayName, dateString, - DateTime.Now.ToString("M", culture)); - Console.WriteLine(); - } - } -} -// The example displays output similar to the following: -// French (France): Aujourd'hui, c'est le 7 février. -// -// Swedish (Sweden): Today is den 7 februari. -// diff --git a/snippets/csharp/System.Resources/ResourceManager/.ctor/ctor1.cs b/snippets/csharp/System.Resources/ResourceManager/.ctor/ctor1.cs deleted file mode 100644 index 3c829904f4a..00000000000 --- a/snippets/csharp/System.Resources/ResourceManager/.ctor/ctor1.cs +++ /dev/null @@ -1,15 +0,0 @@ -using System; -using System.Resources; - -public class Example -{ - public static void Main() - { - // - ResourceManager rm = new ResourceManager(typeof(Resource1)); - // - } -} - -internal class Resource1 -{ } \ No newline at end of file diff --git a/snippets/csharp/System.Resources/ResourceManager/.ctor/example.cs b/snippets/csharp/System.Resources/ResourceManager/.ctor/example.cs deleted file mode 100644 index 4998d21f280..00000000000 --- a/snippets/csharp/System.Resources/ResourceManager/.ctor/example.cs +++ /dev/null @@ -1,23 +0,0 @@ -// -using System; -using System.Reflection; -using System.Resources; - -public class Example -{ - public static void Main() - { - // Retrieve the resource. - ResourceManager rm = new ResourceManager("ExampleResources" , - typeof(Example).Assembly); - string greeting = rm.GetString("Greeting"); - - Console.Write("Enter your name: "); - string name = Console.ReadLine(); - Console.WriteLine("{0} {1}!", greeting, name); - } -} -// The example produces output similar to the following: -// Enter your name: John -// Hello John! -// diff --git a/snippets/csharp/System.Resources/ResourceManager/.ctor/greet.cs b/snippets/csharp/System.Resources/ResourceManager/.ctor/greet.cs deleted file mode 100644 index a474415433b..00000000000 --- a/snippets/csharp/System.Resources/ResourceManager/.ctor/greet.cs +++ /dev/null @@ -1,51 +0,0 @@ -// -using System; -using System.Resources; -using System.Globalization; -using System.Threading; - -[assembly:NeutralResourcesLanguage("en")] - -public class Example -{ - public static void Main() - { - string[] cultureNames = {"en-US", "fr-FR", "ru-RU", "sv-SE" }; - DateTime noon = new DateTime(DateTime.Now.Year, DateTime.Now.Month, - DateTime.Now.Day, 12,0,0); - DateTime evening = new DateTime(DateTime.Now.Year, DateTime.Now.Month, - DateTime.Now.Day, 18, 0, 0); - - ResourceManager rm = new ResourceManager(typeof(GreetingResources)); - - foreach (var cultureName in cultureNames) { - Thread.CurrentThread.CurrentUICulture = CultureInfo.CreateSpecificCulture(cultureName); - Console.WriteLine("The current UI culture is {0}", - CultureInfo.CurrentUICulture.Name); - if (DateTime.Now < noon) - Console.WriteLine("{0}!", rm.GetString("Morning")); - else if (DateTime.Now < evening) - Console.WriteLine("{0}!", rm.GetString("Afternoon")); - else - Console.WriteLine("{0}!", rm.GetString("Evening")); - Console.WriteLine(); - } - } - - internal class GreetingResources - { - } -} -// The example displays output like the following: -// The current UI culture is en-US -// Good afternoon! -// -// The current UI culture is fr-FR -// Bonjour! -// -// The current UI culture is ru-RU -// Добрый день! -// -// The current UI culture is sv-SE -// Good afternoon! -// diff --git a/snippets/csharp/System.Resources/ResourceManager/GetObject/createresources.cs b/snippets/csharp/System.Resources/ResourceManager/GetObject/createresources.cs deleted file mode 100644 index 4863188be2e..00000000000 --- a/snippets/csharp/System.Resources/ResourceManager/GetObject/createresources.cs +++ /dev/null @@ -1,64 +0,0 @@ -// -using System; -using System.Resources; - -public class CreateResource -{ - public static void Main() - { - Numbers en = new Numbers("one", "two", "three", "four", "five", - "six", "seven", "eight", "nine", "ten"); - CreateResourceFile(en, "en"); - Numbers fr = new Numbers("un", "deux", "trois", "quatre", "cinq", - "six", "sept", "huit", "neuf", "dix"); - CreateResourceFile(fr, "fr"); - Numbers pt = new Numbers("um", "dois", "três", "quatro", "cinco", - "seis", "sete", "oito", "nove", "dez"); - CreateResourceFile(pt, "pt"); - Numbers ru = new Numbers("один", "два", "три", "четыре", "пять", - "шесть", "семь", "восемь", "девять", "десять"); - CreateResourceFile(ru, "ru"); - } - - public static void CreateResourceFile(Numbers n, string lang) - { - string filename = @".\NumberResources" + - (lang != "en" ? "." + lang : "" ) + - ".resx"; - ResXResourceWriter rr = new ResXResourceWriter(filename); - rr.AddResource("Numbers", n); - rr.Generate(); - rr.Close(); - } -} -// - -[Serializable] public class Numbers -{ - public readonly string One; - public readonly string Two; - public readonly string Three; - public readonly string Four; - public readonly string Five; - public readonly string Six; - public readonly string Seven; - public readonly string Eight; - public readonly string Nine; - public readonly string Ten; - - public Numbers(string one, string two, string three, string four, - string five, string six, string seven, string eight, - string nine, string ten) - { - this.One = one; - this.Two = two; - this.Three = three; - this.Four = four; - this.Five = five; - this.Six = six; - this.Seven = seven; - this.Eight = eight; - this.Nine = nine; - this.Ten = ten; - } -} diff --git a/snippets/csharp/System.Resources/ResourceManager/GetObject/numberinfo.cs b/snippets/csharp/System.Resources/ResourceManager/GetObject/numberinfo.cs deleted file mode 100644 index fc96b4a2381..00000000000 --- a/snippets/csharp/System.Resources/ResourceManager/GetObject/numberinfo.cs +++ /dev/null @@ -1,33 +0,0 @@ -// -using System; - -[Serializable] public class Numbers -{ - public readonly string One; - public readonly string Two; - public readonly string Three; - public readonly string Four; - public readonly string Five; - public readonly string Six; - public readonly string Seven; - public readonly string Eight; - public readonly string Nine; - public readonly string Ten; - - public Numbers(string one, string two, string three, string four, - string five, string six, string seven, string eight, - string nine, string ten) - { - this.One = one; - this.Two = two; - this.Three = three; - this.Four = four; - this.Five = five; - this.Six = six; - this.Seven = seven; - this.Eight = eight; - this.Nine = nine; - this.Ten = ten; - } -} -// diff --git a/snippets/csharp/System.Resources/ResourceManager/GetObject/shownumbers.cs b/snippets/csharp/System.Resources/ResourceManager/GetObject/shownumbers.cs deleted file mode 100644 index 257e539a32c..00000000000 --- a/snippets/csharp/System.Resources/ResourceManager/GetObject/shownumbers.cs +++ /dev/null @@ -1,74 +0,0 @@ -// -using System; -using System.Globalization; -using System.Resources; -using System.Threading; - -[assembly:NeutralResourcesLanguageAttribute("en-US")] - -public class Example -{ - static string[] cultureNames = { "fr-FR", "pt-BR", "ru-RU" }; - - public static void Main() - { - // Make any non-default culture the current culture. - Random rnd = new Random(); - CultureInfo culture = CultureInfo.CreateSpecificCulture(cultureNames[rnd.Next(0, cultureNames.Length)]); - Thread.CurrentThread.CurrentUICulture = culture; - Console.WriteLine("The current culture is {0}\n", CultureInfo.CurrentUICulture.Name); - CultureInfo enCulture = CultureInfo.CreateSpecificCulture("en-US"); - - ResourceManager rm = new ResourceManager(typeof(NumberResources)); - Numbers numbers = (Numbers) rm.GetObject("Numbers"); - Numbers numbersEn = (Numbers) rm.GetObject("Numbers", enCulture); - Console.WriteLine("{0} --> {1}", numbers.One, numbersEn.One); - Console.WriteLine("{0} --> {1}", numbers.Three, numbersEn.Three); - Console.WriteLine("{0} --> {1}", numbers.Five, numbersEn.Five); - Console.WriteLine("{0} --> {1}", numbers.Seven, numbersEn.Seven); - Console.WriteLine("{0} --> {1}\n", numbers.Nine, numbersEn.Nine); - } -} - -internal class NumberResources -{ -} -// The example displays output like the following: -// The current culture is pt-BR -// -// um --> one -// três --> three -// cinco --> five -// sete --> seven -// nove --> nine -// - -[Serializable] public class Numbers -{ - public readonly string One; - public readonly string Two; - public readonly string Three; - public readonly string Four; - public readonly string Five; - public readonly string Six; - public readonly string Seven; - public readonly string Eight; - public readonly string Nine; - public readonly string Ten; - - public Numbers(string one, string two, string three, string four, - string five, string six, string seven, string eight, - string nine, string ten) - { - this.One = one; - this.Two = two; - this.Three = three; - this.Four = four; - this.Five = five; - this.Six = six; - this.Seven = seven; - this.Eight = eight; - this.Nine = nine; - this.Ten = ten; - } -} diff --git a/snippets/csharp/System.Resources/ResourceManager/Overview/example1.cs b/snippets/csharp/System.Resources/ResourceManager/Overview/example1.cs deleted file mode 100644 index 1663582493b..00000000000 --- a/snippets/csharp/System.Resources/ResourceManager/Overview/example1.cs +++ /dev/null @@ -1,26 +0,0 @@ -// -using System; - -[Serializable] public struct PersonTable -{ - public readonly int nColumns; - public readonly string column1; - public readonly string column2; - public readonly string column3; - public readonly int width1; - public readonly int width2; - public readonly int width3; - - public PersonTable(string column1, string column2, string column3, - int width1, int width2, int width3) - { - this.column1 = column1; - this.column2 = column2; - this.column3 = column3; - this.width1 = width1; - this.width2 = width2; - this.width3 = width3; - this.nColumns = typeof(PersonTable).GetFields().Length / 2; - } -} -// diff --git a/snippets/csharp/System.Resources/ResourceManager/Overview/example11.cs b/snippets/csharp/System.Resources/ResourceManager/Overview/example11.cs deleted file mode 100644 index 0ba2c290fab..00000000000 --- a/snippets/csharp/System.Resources/ResourceManager/Overview/example11.cs +++ /dev/null @@ -1,41 +0,0 @@ -// -using System; -using System.Resources; - -public class CreateResource -{ - public static void Main() - { - PersonTable table = new PersonTable("Name", "Employee Number", - "Age", 30, 18, 5); - ResXResourceWriter rr = new ResXResourceWriter(@".\UIResources.resx"); - rr.AddResource("TableName", "Employees of Acme Corporation"); - rr.AddResource("Employees", table); - rr.Generate(); - rr.Close(); - } -} -// - -[Serializable] public struct PersonTable -{ - public readonly int nColumns; - public readonly string column1; - public readonly string column2; - public readonly string column3; - public readonly int width1; - public readonly int width2; - public readonly int width3; - - public PersonTable(string column1, string column2, string column3, - int width1, int width2, int width3) - { - this.column1 = column1; - this.column2 = column2; - this.column3 = column3; - this.width1 = width1; - this.width2 = width2; - this.width3 = width3; - this.nColumns = typeof(PersonTable).GetFields().Length / 2; - } -} \ No newline at end of file diff --git a/snippets/csharp/System.Resources/ResourceManager/Overview/example2.cs b/snippets/csharp/System.Resources/ResourceManager/Overview/example2.cs deleted file mode 100644 index f87dbd0d640..00000000000 --- a/snippets/csharp/System.Resources/ResourceManager/Overview/example2.cs +++ /dev/null @@ -1,56 +0,0 @@ -// -using System; -using System.Resources; - -[assembly: NeutralResourcesLanguageAttribute("en")] - -public class Example -{ - public static void Main() - { - string fmtString = String.Empty; - ResourceManager rm = new ResourceManager("UIResources", typeof(Example).Assembly); - string title = rm.GetString("TableName"); - PersonTable tableInfo = (PersonTable) rm.GetObject("Employees"); - - if (! String.IsNullOrEmpty(title)) { - fmtString = "{0," + ((Console.WindowWidth + title.Length) / 2).ToString() + "}"; - Console.WriteLine(fmtString, title); - Console.WriteLine(); - } - - for (int ctr = 1; ctr <= tableInfo.nColumns; ctr++) { - string columnName = "column" + ctr.ToString(); - string widthName = "width" + ctr.ToString(); - string value = tableInfo.GetType().GetField(columnName).GetValue(tableInfo).ToString(); - int width = (int) tableInfo.GetType().GetField(widthName).GetValue(tableInfo); - fmtString = "{0,-" + width.ToString() + "}"; - Console.Write(fmtString, value); - } - Console.WriteLine(); - } -} -// - -[Serializable] public struct PersonTable -{ - public readonly int nColumns; - public readonly string column1; - public readonly string column2; - public readonly string column3; - public readonly int width1; - public readonly int width2; - public readonly int width3; - - public PersonTable(string column1, string column2, string column3, - int width1, int width2, int width3) - { - this.column1 = column1; - this.column2 = column2; - this.column3 = column3; - this.width1 = width1; - this.width2 = width2; - this.width3 = width3; - this.nColumns = typeof(PersonTable).GetFields().Length / 2; - } -} \ No newline at end of file diff --git a/snippets/csharp/System.Runtime.CompilerServices/RuntimeHelpers/GetHashCode/gethashcodeex1.cs b/snippets/csharp/System.Runtime.CompilerServices/RuntimeHelpers/GetHashCode/gethashcodeex1.cs deleted file mode 100644 index c58d72ac74c..00000000000 --- a/snippets/csharp/System.Runtime.CompilerServices/RuntimeHelpers/GetHashCode/gethashcodeex1.cs +++ /dev/null @@ -1,51 +0,0 @@ -// -using System; -using System.Runtime.CompilerServices; - -public class Example -{ - public static void Main() - { - Console.WriteLine("{0,-18} {1,6} {2,18:N0} {3,6} {4,18:N0}\n", - "", "Var 1", "Hash Code", "Var 2", "Hash Code"); - - // Get hash codes of two different strings. - String sc1 = "String #1"; - String sc2 = "String #2"; - ShowHashCodes("sc1", sc1, "sc2", sc2); - - // Get hash codes of two identical non-interned strings. - String s1 = "This string"; - String s2 = String.Format("{0} {1}", "This", "string"); - ShowHashCodes("s1", s1, "s2", s2); - - // Get hash codes of two (evidently concatenated) strings. - String si1 = "This is a string!"; - String si2 = "This " + "is " + "a " + "string!"; - ShowHashCodes("si1", si1, "si2", si2); - } - - private static void ShowHashCodes(String var1, Object value1, - String var2, Object value2) - { - Console.WriteLine("{0,-18} {1,6} {2,18:X8} {3,6} {4,18:X8}", - "Obj.GetHashCode", var1, value1.GetHashCode(), - var2, value2.GetHashCode()); - - Console.WriteLine("{0,-18} {1,6} {2,18:X8} {3,6} {4,18:X8}\n", - "RTH.GetHashCode", var1, RuntimeHelpers.GetHashCode(value1), - var2, RuntimeHelpers.GetHashCode(value2)); - } -} -// The example displays output similar to the following: -// Var 1 Hash Code Var 2 Hash Code -// -// Obj.GetHashCode sc1 94EABD27 sc2 94EABD24 -// RTH.GetHashCode sc1 02BF8098 sc2 00BB8560 -// -// Obj.GetHashCode s1 29C5A397 s2 29C5A397 -// RTH.GetHashCode s1 0297B065 s2 03553390 -// -// Obj.GetHashCode si1 941BCEA5 si2 941BCEA5 -// RTH.GetHashCode si1 01FED012 si2 01FED012 -// diff --git a/snippets/csharp/System.Text.RegularExpressions/Regex/Match/startat.cs b/snippets/csharp/System.Text.RegularExpressions/Regex/Match/startat.cs deleted file mode 100644 index c5d4b2b8d84..00000000000 --- a/snippets/csharp/System.Text.RegularExpressions/Regex/Match/startat.cs +++ /dev/null @@ -1,20 +0,0 @@ -using System; -using System.Text.RegularExpressions; - -namespace Examples -{ - public class Example3 - { - public static void Main() - { - string input = "Zip code: 98052"; - var regex = new Regex(@"(?<=Zip code: )\d{5}"); - Match match = regex.Match(input, 5); - if (match.Success) - Console.WriteLine("Match found: {0}", match.Value); - } - } -} - -// This code prints the following output: -// Match found: 98052 diff --git a/snippets/csharp/System/DateTime/FromBinary/frombinary1.cs b/snippets/csharp/System/DateTime/FromBinary/frombinary1.cs deleted file mode 100644 index d84eeb42a62..00000000000 --- a/snippets/csharp/System/DateTime/FromBinary/frombinary1.cs +++ /dev/null @@ -1,23 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - DateTime localDate = new DateTime(2010, 3, 14, 2, 30, 0, DateTimeKind.Local); - long binLocal = localDate.ToBinary(); - if (TimeZoneInfo.Local.IsInvalidTime(localDate)) - Console.WriteLine("{0} is an invalid time in the {1} zone.", - localDate, - TimeZoneInfo.Local.StandardName); - - DateTime localDate2 = DateTime.FromBinary(binLocal); - Console.WriteLine("{0} = {1}: {2}", - localDate, localDate2, localDate.Equals(localDate2)); - } -} -// The example displays the following output: -// 3/14/2010 2:30:00 AM is an invalid time in the Pacific Standard Time zone. -// 3/14/2010 2:30:00 AM = 3/14/2010 3:30:00 AM: False -// diff --git a/snippets/csharp/System/Delegate/CreateDelegate/openClosedOver.cs b/snippets/csharp/System/Delegate/CreateDelegate/openClosedOver.cs deleted file mode 100644 index 45b92d61690..00000000000 --- a/snippets/csharp/System/Delegate/CreateDelegate/openClosedOver.cs +++ /dev/null @@ -1,136 +0,0 @@ -// All four permutations of instance/static with open/closed. -// -// -using System; -using System.Reflection; -using System.Security.Permissions; - -// Declare three delegate types for demonstrating the combinations -// of static versus instance methods and open versus closed -// delegates. -// -public delegate void D1(C c, string s); -public delegate void D2(string s); -public delegate void D3(); - -// A sample class with an instance method and a static method. -// -public class C -{ - private int id; - public C(int id) { this.id = id; } - - public void M1(string s) - { - Console.WriteLine("Instance method M1 on C: id = {0}, s = {1}", - this.id, s); - } - - public static void M2(string s) - { - Console.WriteLine("Static method M2 on C: s = {0}", s); - } -} - -public class Example -{ - public static void Main() - { - C c1 = new C(42); - - // Get a MethodInfo for each method. - // - MethodInfo mi1 = typeof(C).GetMethod("M1", - BindingFlags.Public | BindingFlags.Instance); - MethodInfo mi2 = typeof(C).GetMethod("M2", - BindingFlags.Public | BindingFlags.Static); - - D1 d1; - D2 d2; - D3 d3; - - Console.WriteLine("\nAn instance method closed over C."); - // In this case, the delegate and the - // method must have the same list of argument types; use - // delegate type D2 with instance method M1. - // - Delegate test = - Delegate.CreateDelegate(typeof(D2), c1, mi1, false); - - // Because false was specified for throwOnBindFailure - // in the call to CreateDelegate, the variable 'test' - // contains null if the method fails to bind (for - // example, if mi1 happened to represent a method of - // some class other than C). - // - if (test != null) - { - d2 = (D2) test; - - // The same instance of C is used every time the - // delegate is invoked. - d2("Hello, World!"); - d2("Hi, Mom!"); - } - - Console.WriteLine("\nAn open instance method."); - // In this case, the delegate has one more - // argument than the instance method; this argument comes - // at the beginning, and represents the hidden instance - // argument of the instance method. Use delegate type D1 - // with instance method M1. - // - d1 = (D1) Delegate.CreateDelegate(typeof(D1), null, mi1); - - // An instance of C must be passed in each time the - // delegate is invoked. - // - d1(c1, "Hello, World!"); - d1(new C(5280), "Hi, Mom!"); - - Console.WriteLine("\nAn open static method."); - // In this case, the delegate and the method must - // have the same list of argument types; use delegate type - // D2 with static method M2. - // - d2 = (D2) Delegate.CreateDelegate(typeof(D2), null, mi2); - - // No instances of C are involved, because this is a static - // method. - // - d2("Hello, World!"); - d2("Hi, Mom!"); - - Console.WriteLine("\nA static method closed over the first argument (String)."); - // The delegate must omit the first argument of the method. - // A string is passed as the firstArgument parameter, and - // the delegate is bound to this string. Use delegate type - // D3 with static method M2. - // - d3 = (D3) Delegate.CreateDelegate(typeof(D3), - "Hello, World!", mi2); - - // Each time the delegate is invoked, the same string is - // used. - d3(); - } -} - -/* This code example produces the following output: - -An instance method closed over C. -Instance method M1 on C: id = 42, s = Hello, World! -Instance method M1 on C: id = 42, s = Hi, Mom! - -An open instance method. -Instance method M1 on C: id = 42, s = Hello, World! -Instance method M1 on C: id = 5280, s = Hi, Mom! - -An open static method. -Static method M2 on C: s = Hello, World! -Static method M2 on C: s = Hi, Mom! - -A static method closed over the first argument (String). -Static method M2 on C: s = Hello, World! - */ -// diff --git a/snippets/csharp/System/Delegate/CreateDelegate/source.cs b/snippets/csharp/System/Delegate/CreateDelegate/source.cs deleted file mode 100644 index 53e12d6f3c8..00000000000 --- a/snippets/csharp/System/Delegate/CreateDelegate/source.cs +++ /dev/null @@ -1,166 +0,0 @@ -// Showing all the things D(A) can bind to. -// -// -using System; -using System.Reflection; -using System.Security.Permissions; - -// Declare a delegate type. The object of this code example -// is to show all the methods this delegate can bind to. -// -public delegate void D(C c); - -// Declare two sample classes, C and F. Class C has an ID -// property so instances can be identified. -// -public class C -{ - private int id; - public int ID { get { return id; }} - public C(int id) { this.id = id; } - - public void M1(C c) - { - Console.WriteLine("Instance method M1(C c) on C: this.id = {0}, c.ID = {1}", - this.id, c.ID); - } - - public void M2() - { - Console.WriteLine("Instance method M2() on C: this.id = {0}", - this.id); - } - - public static void M3(C c) - { - Console.WriteLine("Static method M3(C c) on C: c.ID = {0}", c.ID); - } - - public static void M4(C c1, C c2) - { - Console.WriteLine("Static method M4(C c1, C c2) on C: c1.ID = {0}, c2.ID = {1}", - c1.ID, c2.ID); - } -} - -public class F -{ - public void M1(C c) - { - Console.WriteLine("Instance method M1(C c) on F: c.ID = {0}", - c.ID); - } - - public static void M3(C c) - { - Console.WriteLine("Static method M3(C c) on F: c.ID = {0}", c.ID); - } - - public static void M4(F f, C c) - { - Console.WriteLine("Static method M4(F f, C c) on F: c.ID = {0}", - c.ID); - } -} - -public class Example -{ - public static void Main() - { - C c1 = new C(42); - C c2 = new C(1491); - F f1 = new F(); - - D d; - - // Instance method with one argument of type C. - MethodInfo cmi1 = typeof(C).GetMethod("M1"); - // Instance method with no arguments. - MethodInfo cmi2 = typeof(C).GetMethod("M2"); - // Static method with one argument of type C. - MethodInfo cmi3 = typeof(C).GetMethod("M3"); - // Static method with two arguments of type C. - MethodInfo cmi4 = typeof(C).GetMethod("M4"); - - // Instance method with one argument of type C. - MethodInfo fmi1 = typeof(F).GetMethod("M1"); - // Static method with one argument of type C. - MethodInfo fmi3 = typeof(F).GetMethod("M3"); - // Static method with an argument of type F and an argument - // of type C. - MethodInfo fmi4 = typeof(F).GetMethod("M4"); - - Console.WriteLine("\nAn instance method on any type, with an argument of type C."); - // D can represent any instance method that exactly matches its - // signature. Methods on C and F are shown here. - // - d = (D) Delegate.CreateDelegate(typeof(D), c1, cmi1); - d(c2); - d = (D) Delegate.CreateDelegate(typeof(D), f1, fmi1); - d(c2); - - Console.WriteLine("\nAn instance method on C with no arguments."); - // D can represent an instance method on C that has no arguments; - // in this case, the argument of D represents the hidden first - // argument of any instance method. The delegate acts like a - // static method, and an instance of C must be passed each time - // it is invoked. - // - d = (D) Delegate.CreateDelegate(typeof(D), null, cmi2); - d(c1); - - Console.WriteLine("\nA static method on any type, with an argument of type C."); - // D can represent any static method with the same signature. - // Methods on F and C are shown here. - // - d = (D) Delegate.CreateDelegate(typeof(D), null, cmi3); - d(c1); - d = (D) Delegate.CreateDelegate(typeof(D), null, fmi3); - d(c1); - - Console.WriteLine("\nA static method on any type, with an argument of"); - Console.WriteLine(" that type and an argument of type C."); - // D can represent any static method with one argument of the - // type the method belongs and a second argument of type C. - // In this case, the method is closed over the instance of - // supplied for the its first argument, and acts like an instance - // method. Methods on F and C are shown here. - // - d = (D) Delegate.CreateDelegate(typeof(D), c1, cmi4); - d(c2); - Delegate test = - Delegate.CreateDelegate(typeof(D), f1, fmi4, false); - - // This final example specifies false for throwOnBindFailure - // in the call to CreateDelegate, so the variable 'test' - // contains Nothing if the method fails to bind (for - // example, if fmi4 happened to represent a method of - // some class other than F). - // - if (test != null) - { - d = (D) test; - d(c2); - } - } -} - -/* This code example produces the following output: - -An instance method on any type, with an argument of type C. -Instance method M1(C c) on C: this.id = 42, c.ID = 1491 -Instance method M1(C c) on F: c.ID = 1491 - -An instance method on C with no arguments. -Instance method M2() on C: this.id = 42 - -A static method on any type, with an argument of type C. -Static method M3(C c) on C: c.ID = 42 -Static method M3(C c) on F: c.ID = 42 - -A static method on any type, with an argument of - that type and an argument of type C. -Static method M4(C c1, C c2) on C: c1.ID = 42, c2.ID = 1491 -Static method M4(F f, C c) on F: c.ID = 1491 -*/ -// diff --git a/snippets/csharp/System/Delegate/CreateDelegate/source1.cs b/snippets/csharp/System/Delegate/CreateDelegate/source1.cs deleted file mode 100644 index 12cfa273a7c..00000000000 --- a/snippets/csharp/System/Delegate/CreateDelegate/source1.cs +++ /dev/null @@ -1,58 +0,0 @@ -// -using System; -using System.Reflection; - -// Define two classes to use in the demonstration, a base class and -// a class that derives from it. -// -public class Base {} - -public class Derived : Base -{ - // Define a static method to use in the demonstration. The method - // takes an instance of Base and returns an instance of Derived. - // For the purposes of the demonstration, it is not necessary for - // the method to do anything useful. - // - public static Derived MyMethod(Base arg) - { - Base dummy = arg; - return new Derived(); - } -} - -// Define a delegate that takes an instance of Derived and returns an -// instance of Base. -// -public delegate Base Example(Derived arg); - -class Test -{ - public static void Main() - { - // The binding flags needed to retrieve MyMethod. - BindingFlags flags = BindingFlags.Public | BindingFlags.Static; - - // Get a MethodInfo that represents MyMethod. - MethodInfo minfo = typeof(Derived).GetMethod("MyMethod", flags); - - // Demonstrate contravariance of parameter types and covariance - // of return types by using the delegate Example to represent - // MyMethod. The delegate binds to the method because the - // parameter of the delegate is more restrictive than the - // parameter of the method (that is, the delegate accepts an - // instance of Derived, which can always be safely passed to - // a parameter of type Base), and the return type of MyMethod - // is more restrictive than the return type of Example (that - // is, the method returns an instance of Derived, which can - // always be safely cast to type Base). - // - Example ex = - (Example) Delegate.CreateDelegate(typeof(Example), minfo); - - // Execute MyMethod using the delegate Example. - // - Base b = ex(new Derived()); - } -} -// diff --git a/snippets/csharp/System/Double/CompareTo/compareto2.cs b/snippets/csharp/System/Double/CompareTo/compareto2.cs deleted file mode 100644 index 66739a5c857..00000000000 --- a/snippets/csharp/System/Double/CompareTo/compareto2.cs +++ /dev/null @@ -1,20 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - double value1 = 6.185; - double value2 = value1 * .1 / .1; - Console.WriteLine("Comparing {0} and {1}: {2}\n", - value1, value2, value1.CompareTo(value2)); - Console.WriteLine("Comparing {0:R} and {1:R}: {2}", - value1, value2, value1.CompareTo(value2)); - } -} -// The example displays the following output: -// Comparing 6.185 and 6.185: -1 -// -// Comparing 6.185 and 6.1850000000000005: -1 -// \ No newline at end of file diff --git a/snippets/csharp/System/Double/CompareTo/compareto3.cs b/snippets/csharp/System/Double/CompareTo/compareto3.cs deleted file mode 100644 index ddca9306760..00000000000 --- a/snippets/csharp/System/Double/CompareTo/compareto3.cs +++ /dev/null @@ -1,20 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - double value1 = 6.185; - object value2 = value1 * .1 / .1; - Console.WriteLine("Comparing {0} and {1}: {2}\n", - value1, value2, value1.CompareTo(value2)); - Console.WriteLine("Comparing {0:R} and {1:R}: {2}", - value1, value2, value1.CompareTo(value2)); - } -} -// The example displays the following output: -// Comparing 6.185 and 6.185: -1 -// -// Comparing 6.185 and 6.1850000000000005: -1 -// \ No newline at end of file diff --git a/snippets/csharp/System/Double/Epsilon/epsilon.cs b/snippets/csharp/System/Double/Epsilon/epsilon.cs deleted file mode 100644 index dbd908c4be8..00000000000 --- a/snippets/csharp/System/Double/Epsilon/epsilon.cs +++ /dev/null @@ -1,27 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - double[] values = { 0, Double.Epsilon, Double.Epsilon * .5 }; - - for (int ctr = 0; ctr <= values.Length - 2; ctr++) - { - for (int ctr2 = ctr + 1; ctr2 <= values.Length - 1; ctr2++) - { - Console.WriteLine("{0:r} = {1:r}: {2}", - values[ctr], values[ctr2], - values[ctr].Equals(values[ctr2])); - } - Console.WriteLine(); - } - } -} -// The example displays the following output: -// 0 = 4.94065645841247E-324: False -// 0 = 0: True -// -// 4.94065645841247E-324 = 0: False -// diff --git a/snippets/csharp/System/Double/Epsilon/epsilon1.cs b/snippets/csharp/System/Double/Epsilon/epsilon1.cs deleted file mode 100644 index 9edca37cfd4..00000000000 --- a/snippets/csharp/System/Double/Epsilon/epsilon1.cs +++ /dev/null @@ -1,54 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - double[] values = { 0.0, Double.Epsilon }; - foreach (var value in values) { - Console.WriteLine(GetComponentParts(value)); - Console.WriteLine(); - } - } - - private static string GetComponentParts(double value) - { - string result = String.Format("{0:R}: ", value); - int indent = result.Length; - - // Convert the double to an 8-byte array. - byte[] bytes = BitConverter.GetBytes(value); - // Get the sign bit (byte 7, bit 7). - result += String.Format("Sign: {0}\n", - (bytes[7] & 0x80) == 0x80 ? "1 (-)" : "0 (+)"); - - // Get the exponent (byte 6 bits 4-7 to byte 7, bits 0-6) - int exponent = (bytes[7] & 0x07F) << 4; - exponent = exponent | ((bytes[6] & 0xF0) >> 4); - int adjustment = exponent != 0 ? 1023 : 1022; - result += String.Format("{0}Exponent: 0x{1:X4} ({1})\n", new String(' ', indent), exponent - adjustment); - - // Get the significand (bits 0-51) - long significand = ((bytes[6] & 0x0F) << 48); - significand = significand | ((long) bytes[5] << 40); - significand = significand | ((long) bytes[4] << 32); - significand = significand | ((long) bytes[3] << 24); - significand = significand | ((long) bytes[2] << 16); - significand = significand | ((long) bytes[1] << 8); - significand = significand | bytes[0]; - result += String.Format("{0}Mantissa: 0x{1:X13}\n", new String(' ', indent), significand); - - return result; - } -} -// // The example displays the following output: -// 0: Sign: 0 (+) -// Exponent: 0xFFFFFC02 (-1022) -// Mantissa: 0x0000000000000 -// -// -// 4.94065645841247E-324: Sign: 0 (+) -// Exponent: 0xFFFFFC02 (-1022) -// Mantissa: 0x0000000000001 -// \ No newline at end of file diff --git a/snippets/csharp/System/Double/Equals/equalsabs1.cs b/snippets/csharp/System/Double/Equals/equalsabs1.cs deleted file mode 100644 index 641ed11b343..00000000000 --- a/snippets/csharp/System/Double/Equals/equalsabs1.cs +++ /dev/null @@ -1,41 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - double value1 = .1 * 10; - double value2 = 0; - for (int ctr = 0; ctr < 10; ctr++) - value2 += .1; - - Console.WriteLine("{0:R} = {1:R}: {2}", value1, value2, - HasMinimalDifference(value1, value2, 1)); - } - - public static bool HasMinimalDifference(double value1, double value2, int units) - { - long lValue1 = BitConverter.DoubleToInt64Bits(value1); - long lValue2 = BitConverter.DoubleToInt64Bits(value2); - - // If the signs are different, return false except for +0 and -0. - if ((lValue1 >> 63) != (lValue2 >> 63)) - { - if (value1 == value2) - return true; - - return false; - } - - long diff = Math.Abs(lValue1 - lValue2); - - if (diff <= (long) units) - return true; - - return false; - } -} -// The example displays the following output: -// 1 = 0.99999999999999989: True -// diff --git a/snippets/csharp/System/FormatException/Overview/FormatExample2.cs b/snippets/csharp/System/FormatException/Overview/FormatExample2.cs deleted file mode 100644 index 925589ccda8..00000000000 --- a/snippets/csharp/System/FormatException/Overview/FormatExample2.cs +++ /dev/null @@ -1,77 +0,0 @@ -// -using System; - -public class TestFormatter -{ - public static void Main() - { - int acctNumber = 79203159; - Console.WriteLine(String.Format(new CustomerFormatter(), "{0}", acctNumber)); - Console.WriteLine(String.Format(new CustomerFormatter(), "{0:G}", acctNumber)); - Console.WriteLine(String.Format(new CustomerFormatter(), "{0:S}", acctNumber)); - Console.WriteLine(String.Format(new CustomerFormatter(), "{0:P}", acctNumber)); - try { - Console.WriteLine(String.Format(new CustomerFormatter(), "{0:X}", acctNumber)); - } - catch (FormatException e) { - Console.WriteLine(e.Message); - } - } -} - -public class CustomerFormatter : IFormatProvider, ICustomFormatter -{ - public object GetFormat(Type formatType) - { - if (formatType == typeof(ICustomFormatter)) - return this; - else - return null; - } - - public string Format(string format, - object arg, - IFormatProvider formatProvider) - { - if (! this.Equals(formatProvider)) - { - return null; - } - else - { - if (String.IsNullOrEmpty(format)) - format = "G"; - - string customerString = arg.ToString(); - if (customerString.Length < 8) - customerString = customerString.PadLeft(8, '0'); - - format = format.ToUpper(); - switch (format) - { - case "G": - return customerString.Substring(0, 1) + "-" + - customerString.Substring(1, 5) + "-" + - customerString.Substring(6); - case "S": - return customerString.Substring(0, 1) + "/" + - customerString.Substring(1, 5) + "/" + - customerString.Substring(6); - case "P": - return customerString.Substring(0, 1) + "." + - customerString.Substring(1, 5) + "." + - customerString.Substring(6); - default: - throw new FormatException( - String.Format("The '{0}' format specifier is not supported.", format)); - } - } - } -} -// The example displays the following output: -// 7-92031-59 -// 7-92031-59 -// 7/92031/59 -// 7.92031.59 -// The 'X' format specifier is not supported. -// diff --git a/snippets/csharp/System/FormatException/Overview/formatoverload1.cs b/snippets/csharp/System/FormatException/Overview/formatoverload1.cs deleted file mode 100644 index 3ea3ef7a278..00000000000 --- a/snippets/csharp/System/FormatException/Overview/formatoverload1.cs +++ /dev/null @@ -1,18 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - DateTime dat = new DateTime(2012, 1, 17, 9, 30, 0); - string city = "Chicago"; - int temp = -16; - string output = String.Format("At {0} in {1}, the temperature was {2} degrees.", - dat, city, temp); - Console.WriteLine(output); - // The example displays output like the following: - // At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees. - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/formatoverload2.cs b/snippets/csharp/System/FormatException/Overview/formatoverload2.cs deleted file mode 100644 index 5d1d0a82367..00000000000 --- a/snippets/csharp/System/FormatException/Overview/formatoverload2.cs +++ /dev/null @@ -1,38 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - // Create array of 5-tuples with population data for three U.S. cities, 1940-1950. - Tuple[] cities = - { Tuple.Create("Los Angeles", new DateTime(1940, 1, 1), 1504277, - new DateTime(1950, 1, 1), 1970358), - Tuple.Create("New York", new DateTime(1940, 1, 1), 7454995, - new DateTime(1950, 1, 1), 7891957), - Tuple.Create("Chicago", new DateTime(1940, 1, 1), 3396808, - new DateTime(1950, 1, 1), 3620962), - Tuple.Create("Detroit", new DateTime(1940, 1, 1), 1623452, - new DateTime(1950, 1, 1), 1849568) }; - - // Display header - var header = String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}\n", - "City", "Year", "Population", "Change (%)"); - Console.WriteLine(header); - foreach (var city in cities) { - var output = String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}", - city.Item1, city.Item2, city.Item3, city.Item4, city.Item5, - (city.Item5 - city.Item3)/ (double)city.Item3); - Console.WriteLine(output); - } - // The example displays the following output: - // City Year Population Year Population Change (%) - // - // Los Angeles 1940 1,504,277 1950 1,970,358 31.0 % - // New York 1940 7,454,995 1950 7,891,957 5.9 % - // Chicago 1940 3,396,808 1950 3,620,962 6.6 % - // Detroit 1940 1,623,452 1950 1,849,568 13.9 % - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/formatsyntax1.cs b/snippets/csharp/System/FormatException/Overview/formatsyntax1.cs deleted file mode 100644 index 29f0a89414a..00000000000 --- a/snippets/csharp/System/FormatException/Overview/formatsyntax1.cs +++ /dev/null @@ -1,12 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { -// -var value = String.Format("{0,-10:C}", 126347.89m); -Console.WriteLine(value); -// - } -} diff --git a/snippets/csharp/System/FormatException/Overview/interceptor2.cs b/snippets/csharp/System/FormatException/Overview/interceptor2.cs deleted file mode 100644 index 1cf68478e37..00000000000 --- a/snippets/csharp/System/FormatException/Overview/interceptor2.cs +++ /dev/null @@ -1,119 +0,0 @@ -// -using System; -using System.Globalization; - -public class InterceptProvider : IFormatProvider, ICustomFormatter -{ - public object GetFormat(Type formatType) - { - if (formatType == typeof(ICustomFormatter)) - return this; - else - return null; - } - - public string Format(String format, Object obj, IFormatProvider provider) - { - // Display information about method call. - string formatString = format ?? ""; - Console.WriteLine("Provider: {0}, Object: {1}, Format String: {2}", - provider.GetType().Name, obj ?? "", formatString); - - if (obj == null) return String.Empty; - - // If this is a byte and the "R" format string, format it with Roman numerals. - if (obj is Byte && formatString.ToUpper().Equals("R")) { - Byte value = (Byte) obj; - int remainder; - int result; - String returnString = String.Empty; - - // Get the hundreds digit(s) - result = Math.DivRem(value, 100, out remainder); - if (result > 0) - returnString = new String('C', result); - value = (Byte) remainder; - // Get the 50s digit - result = Math.DivRem(value, 50, out remainder); - if (result == 1) - returnString += "L"; - value = (Byte) remainder; - // Get the tens digit. - result = Math.DivRem(value, 10, out remainder); - if (result > 0) - returnString += new String('X', result); - value = (Byte) remainder; - // Get the fives digit. - result = Math.DivRem(value, 5, out remainder); - if (result > 0) - returnString += "V"; - value = (Byte) remainder; - // Add the ones digit. - if (remainder > 0) - returnString += new String('I', remainder); - - // Check whether we have too many X characters. - int pos = returnString.IndexOf("XXXX"); - if (pos >= 0) { - int xPos = returnString.IndexOf("L"); - if (xPos >= 0 & xPos == pos - 1) - returnString = returnString.Replace("LXXXX", "XC"); - else - returnString = returnString.Replace("XXXX", "XL"); - } - // Check whether we have too many I characters - pos = returnString.IndexOf("IIII"); - if (pos >= 0) - if (returnString.IndexOf("V") >= 0) - returnString = returnString.Replace("VIIII", "IX"); - else - returnString = returnString.Replace("IIII", "IV"); - - return returnString; - } - - // Use default for all other formatting. - if (obj is IFormattable) - return ((IFormattable) obj).ToString(format, CultureInfo.CurrentCulture); - else - return obj.ToString(); - } -} - -public class Example -{ - public static void Main() - { - int n = 10; - double value = 16.935; - DateTime day = DateTime.Now; - InterceptProvider provider = new InterceptProvider(); - Console.WriteLine(String.Format(provider, "{0:N0}: {1:C2} on {2:d}\n", n, value, day)); - Console.WriteLine(String.Format(provider, "{0}: {1:F}\n", "Today: ", - (DayOfWeek) DateTime.Now.DayOfWeek)); - Console.WriteLine(String.Format(provider, "{0:X}, {1}, {2}\n", - (Byte) 2, (Byte) 12, (Byte) 199)); - Console.WriteLine(String.Format(provider, "{0:R}, {1:R}, {2:R}\n", - (Byte) 2, (Byte) 12, (Byte) 199)); - } -} -// The example displays the following output: -// Provider: InterceptProvider, Object: 10, Format String: N0 -// Provider: InterceptProvider, Object: 16.935, Format String: C2 -// Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d -// 10: $16.94 on 1/31/2013 -// -// Provider: InterceptProvider, Object: Today: , Format String: -// Provider: InterceptProvider, Object: Thursday, Format String: F -// Today: : Thursday -// -// Provider: InterceptProvider, Object: 2, Format String: X -// Provider: InterceptProvider, Object: 12, Format String: -// Provider: InterceptProvider, Object: 199, Format String: -// 2, 12, 199 -// -// Provider: InterceptProvider, Object: 2, Format String: R -// Provider: InterceptProvider, Object: 12, Format String: R -// Provider: InterceptProvider, Object: 199, Format String: R -// II, XII, CXCIX -// \ No newline at end of file diff --git a/snippets/csharp/System/FormatException/Overview/qa-interpolated1.cs b/snippets/csharp/System/FormatException/Overview/qa-interpolated1.cs deleted file mode 100644 index 0eb0c3b46fa..00000000000 --- a/snippets/csharp/System/FormatException/Overview/qa-interpolated1.cs +++ /dev/null @@ -1,23 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - string[] names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" }; - string output = names[0] + ", " + names[1] + ", " + names[2] + ", " + - names[3] + ", " + names[4] + ", " + names[5] + ", " + - names[6]; - - output += "\n"; - var date = DateTime.Now; - output += String.Format("It is {0:t} on {0:d}. The day of the week is {1}.", - date, date.DayOfWeek); - Console.WriteLine(output); - // The example displays the following output: - // Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma - // It is 10:29 AM on 1/8/2018. The day of the week is Monday. - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/qa-interpolated2.cs b/snippets/csharp/System/FormatException/Overview/qa-interpolated2.cs deleted file mode 100644 index 2693e81917b..00000000000 --- a/snippets/csharp/System/FormatException/Overview/qa-interpolated2.cs +++ /dev/null @@ -1,20 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - string[] names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" }; - string output = $"{names[0]}, {names[1]}, {names[2]}, {names[3]}, {names[4]}, " + - $"{names[5]}, {names[6]}"; - - var date = DateTime.Now; - output += $"\nIt is {date:t} on {date:d}. The day of the week is {date.DayOfWeek}."; - Console.WriteLine(output); - // The example displays the following output: - // Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma - // It is 10:29 AM on 1/8/2018. The day of the week is Monday. - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/qa11.cs b/snippets/csharp/System/FormatException/Overview/qa11.cs deleted file mode 100644 index 5345126e647..00000000000 --- a/snippets/csharp/System/FormatException/Overview/qa11.cs +++ /dev/null @@ -1,21 +0,0 @@ -using System; -using System.Collections.Generic; - -public class Example -{ - public static void Main() - { - // - Random rnd = new Random(); - int[] numbers = new int[4]; - int total = 0; - for (int ctr = 0; ctr <= 2; ctr++) { - int number = rnd.Next(1001); - numbers[ctr] = number; - total += number; - } - numbers[3] = total; - Console.WriteLine("{0} + {1} + {2} = {3}", numbers); - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/qa21.cs b/snippets/csharp/System/FormatException/Overview/qa21.cs deleted file mode 100644 index 3274ca05cf5..00000000000 --- a/snippets/csharp/System/FormatException/Overview/qa21.cs +++ /dev/null @@ -1,23 +0,0 @@ -using System; -using System.Collections.Generic; - -public class Example -{ - public static void Main() - { - // - Random rnd = new Random(); - int[] numbers = new int[4]; - int total = 0; - for (int ctr = 0; ctr <= 2; ctr++) { - int number = rnd.Next(1001); - numbers[ctr] = number; - total += number; - } - numbers[3] = total; - object[] values = new object[numbers.Length]; - numbers.CopyTo(values, 0); - Console.WriteLine("{0} + {1} + {2} = {3}", values); - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/qa26.cs b/snippets/csharp/System/FormatException/Overview/qa26.cs deleted file mode 100644 index 0f6691ef8dd..00000000000 --- a/snippets/csharp/System/FormatException/Overview/qa26.cs +++ /dev/null @@ -1,23 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - object[] values = { 1603, 1794.68235, 15436.14 }; - string result; - foreach (var value in values) { - result = String.Format("{0,12:C2} {0,12:E3} {0,12:F4} {0,12:N3} {1,12:P2}\n", - Convert.ToDouble(value), Convert.ToDouble(value) / 10000); - Console.WriteLine(result); - } - // The example displays output like the following: - // $1,603.00 1.603E+003 1603.0000 1,603.000 16.03 % - // - // $1,794.68 1.795E+003 1794.6824 1,794.682 17.95 % - // - // $15,436.14 1.544E+004 15436.1400 15,436.140 154.36 % - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/qa27.cs b/snippets/csharp/System/FormatException/Overview/qa27.cs deleted file mode 100644 index 25028482b4d..00000000000 --- a/snippets/csharp/System/FormatException/Overview/qa27.cs +++ /dev/null @@ -1,16 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - decimal value = 16309.5436m; - string result = String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}", - value); - Console.WriteLine(result); - // The example displays the following output: - // 16309.54360 16,309.54 16309.544 - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/qa28.cs b/snippets/csharp/System/FormatException/Overview/qa28.cs deleted file mode 100644 index 91a47bac4c2..00000000000 --- a/snippets/csharp/System/FormatException/Overview/qa28.cs +++ /dev/null @@ -1,16 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - int value = 16342; - string result = String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}", - value); - Console.WriteLine(result); - // The example displays the following output: - // 00016342 00016342.000 0,000,016,342.0 - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/qa29.cs b/snippets/csharp/System/FormatException/Overview/qa29.cs deleted file mode 100644 index 0c5234dbf7f..00000000000 --- a/snippets/csharp/System/FormatException/Overview/qa29.cs +++ /dev/null @@ -1,15 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - int value = 1326; - string result = String.Format("{0,10:D6} {0,10:X8}", value); - Console.WriteLine(result); - // The example displays the following output: - // 001326 0000052E - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/starting1.cs b/snippets/csharp/System/FormatException/Overview/starting1.cs deleted file mode 100644 index 6ba80a75ef2..00000000000 --- a/snippets/csharp/System/FormatException/Overview/starting1.cs +++ /dev/null @@ -1,57 +0,0 @@ -using System; -using System.Text; - -public class Example -{ - public static void Main() - { - // - decimal temp = 20.4m; - string s = String.Format("The temperature is {0}°C.", temp); - Console.WriteLine(s); - // Displays 'The temperature is 20.4°C.' - // - - Snippet31(); - Snippet32(); - Snippet34(); - } - - private static void Snippet31() - { - // - string s = String.Format("At {0}, the temperature is {1}°C.", - DateTime.Now, 20.4); - Console.WriteLine(s); - // Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.' - // - } - - private static void Snippet32() - { - // - string s = String.Format("It is now {0:d} at {0:t}", DateTime.Now); - Console.WriteLine(s); - // Output similar to: 'It is now 4/10/2015 at 10:04 AM' - // - } - - private static void Snippet34() - { - // - int[] years = { 2013, 2014, 2015 }; - int[] population = { 1025632, 1105967, 1148203 }; - String s = String.Format("{0,-10} {1,-10}\n\n", "Year", "Population"); - for(int index = 0; index < years.Length; index++) - s += String.Format("{0,-10} {1,-10:N0}\n", - years[index], population[index]); - Console.WriteLine($"\n{s}"); - // Result: - // Year Population - // - // 2013 1,025,632 - // 2014 1,105,967 - // 2015 1,148,203 - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/starting2.cs b/snippets/csharp/System/FormatException/Overview/starting2.cs deleted file mode 100644 index 3a293feab9d..00000000000 --- a/snippets/csharp/System/FormatException/Overview/starting2.cs +++ /dev/null @@ -1,28 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - Decimal pricePerOunce = 17.36m; - String s = String.Format("The current price is {0} per ounce.", - pricePerOunce); - Console.WriteLine(s); - // Result: The current price is 17.36 per ounce. - // - ShowFormatted(); - } - - private static void ShowFormatted() - { - // - Decimal pricePerOunce = 17.36m; - String s = String.Format("The current price is {0:C2} per ounce.", - pricePerOunce); - Console.WriteLine(s); - // Result if current culture is en-US: - // The current price is $17.36 per ounce. - // - } -} diff --git a/snippets/csharp/System/FormatException/Overview/starting3.cs b/snippets/csharp/System/FormatException/Overview/starting3.cs deleted file mode 100644 index d3109526128..00000000000 --- a/snippets/csharp/System/FormatException/Overview/starting3.cs +++ /dev/null @@ -1,26 +0,0 @@ -using System; -using System.Text; - -class Example -{ - public static void Main() - { - // - int[] years = { 2013, 2014, 2015 }; - int[] population = { 1025632, 1105967, 1148203 }; - var sb = new System.Text.StringBuilder(); - sb.Append(String.Format("{0,6} {1,15}\n\n", "Year", "Population")); - for (int index = 0; index < years.Length; index++) - sb.Append(String.Format("{0,6} {1,15:N0}\n", years[index], population[index])); - - Console.WriteLine(sb); - - // Result: - // Year Population - // - // 2013 1,025,632 - // 2014 1,105,967 - // 2015 1,148,203 - // - } -} diff --git a/snippets/csharp/System/Object/Equals/equals2.cs b/snippets/csharp/System/Object/Equals/equals2.cs deleted file mode 100644 index f07a560a41a..00000000000 --- a/snippets/csharp/System/Object/Equals/equals2.cs +++ /dev/null @@ -1,94 +0,0 @@ -// -using System; - -class Point -{ - protected int x, y; - - public Point() : this(0, 0) - { } - - public Point(int x, int y) - { - this.x = x; - this.y = y; - } - - public override bool Equals(Object obj) - { - //Check for null and compare run-time types. - if ((obj == null) || ! this.GetType().Equals(obj.GetType())) - { - return false; - } - else { - Point p = (Point) obj; - return (x == p.x) && (y == p.y); - } - } - - public override int GetHashCode() - { - return (x << 2) ^ y; - } - - public override string ToString() - { - return String.Format("Point({0}, {1})", x, y); - } -} - -sealed class Point3D: Point -{ - int z; - - public Point3D(int x, int y, int z) : base(x, y) - { - this.z = z; - } - - public override bool Equals(Object obj) - { - Point3D pt3 = obj as Point3D; - if (pt3 == null) - return false; - else - return base.Equals((Point)obj) && z == pt3.z; - } - - public override int GetHashCode() - { - return (base.GetHashCode() << 2) ^ z; - } - - public override String ToString() - { - return String.Format("Point({0}, {1}, {2})", x, y, z); - } -} - -class Example -{ - public static void Main() - { - Point point2D = new Point(5, 5); - Point3D point3Da = new Point3D(5, 5, 2); - Point3D point3Db = new Point3D(5, 5, 2); - Point3D point3Dc = new Point3D(5, 5, -1); - - Console.WriteLine("{0} = {1}: {2}", - point2D, point3Da, point2D.Equals(point3Da)); - Console.WriteLine("{0} = {1}: {2}", - point2D, point3Db, point2D.Equals(point3Db)); - Console.WriteLine("{0} = {1}: {2}", - point3Da, point3Db, point3Da.Equals(point3Db)); - Console.WriteLine("{0} = {1}: {2}", - point3Da, point3Dc, point3Da.Equals(point3Dc)); - } -} -// The example displays the following output: -// Point(5, 5) = Point(5, 5, 2): False -// Point(5, 5) = Point(5, 5, 2): False -// Point(5, 5, 2) = Point(5, 5, 2): True -// Point(5, 5, 2) = Point(5, 5, -1): False -// diff --git a/snippets/csharp/System/Object/Equals/equals3.cs b/snippets/csharp/System/Object/Equals/equals3.cs deleted file mode 100644 index e0419586b04..00000000000 --- a/snippets/csharp/System/Object/Equals/equals3.cs +++ /dev/null @@ -1,77 +0,0 @@ -// -using System; - -class Rectangle -{ - private Point a, b; - - public Rectangle(int upLeftX, int upLeftY, int downRightX, int downRightY) - { - this.a = new Point(upLeftX, upLeftY); - this.b = new Point(downRightX, downRightY); - } - - public override bool Equals(Object obj) - { - // Perform an equality check on two rectangles (Point object pairs). - if (obj == null || GetType() != obj.GetType()) - return false; - Rectangle r = (Rectangle)obj; - return a.Equals(r.a) && b.Equals(r.b); - } - - public override int GetHashCode() - { - return Tuple.Create(a, b).GetHashCode(); - } - - public override String ToString() - { - return String.Format("Rectangle({0}, {1}, {2}, {3})", - a.x, a.y, b.x, b.y); - } -} - -class Point -{ - internal int x; - internal int y; - - public Point(int X, int Y) - { - this.x = X; - this.y = Y; - } - - public override bool Equals (Object obj) - { - // Performs an equality check on two points (integer pairs). - if (obj == null || GetType() != obj.GetType()) return false; - Point p = (Point)obj; - return (x == p.x) && (y == p.y); - } - - public override int GetHashCode() - { - return Tuple.Create(x, y).GetHashCode(); - } -} - -class Example -{ - public static void Main() - { - Rectangle r1 = new Rectangle(0, 0, 100, 200); - Rectangle r2 = new Rectangle(0, 0, 100, 200); - Rectangle r3 = new Rectangle(0, 0, 150, 200); - - Console.WriteLine("{0} = {1}: {2}", r1, r2, r1.Equals(r2)); - Console.WriteLine("{0} = {1}: {2}", r1, r3, r1.Equals(r3)); - Console.WriteLine("{0} = {1}: {2}", r2, r3, r2.Equals(r3)); - } -} -// The example displays the following output: -// Rectangle(0, 0, 100, 200) = Rectangle(0, 0, 100, 200): True -// Rectangle(0, 0, 100, 200) = Rectangle(0, 0, 150, 200): False -// Rectangle(0, 0, 100, 200) = Rectangle(0, 0, 150, 200): False -// diff --git a/snippets/csharp/System/Object/Equals/equals4.cs b/snippets/csharp/System/Object/Equals/equals4.cs deleted file mode 100644 index b1ee81a3a58..00000000000 --- a/snippets/csharp/System/Object/Equals/equals4.cs +++ /dev/null @@ -1,60 +0,0 @@ -// -using System; - -public struct Complex -{ - public double re, im; - - public override bool Equals(Object obj) - { - return obj is Complex && this == (Complex)obj; - } - - public override int GetHashCode() - { - return Tuple.Create(re, im).GetHashCode(); - } - - public static bool operator ==(Complex x, Complex y) - { - return x.re == y.re && x.im == y.im; - } - - public static bool operator !=(Complex x, Complex y) - { - return !(x == y); - } - - public override String ToString() - { - return String.Format("({0}, {1})", re, im); - } -} - -class MyClass -{ - public static void Main() - { - Complex cmplx1, cmplx2; - - cmplx1.re = 4.0; - cmplx1.im = 1.0; - - cmplx2.re = 2.0; - cmplx2.im = 1.0; - - Console.WriteLine("{0} <> {1}: {2}", cmplx1, cmplx2, cmplx1 != cmplx2); - Console.WriteLine("{0} = {1}: {2}", cmplx1, cmplx2, cmplx1.Equals(cmplx2)); - - cmplx2.re = 4.0; - - Console.WriteLine("{0} = {1}: {2}", cmplx1, cmplx2, cmplx1 == cmplx2); - Console.WriteLine("{0} = {1}: {2}", cmplx1, cmplx2, cmplx1.Equals(cmplx2)); - } -} -// The example displays the following output: -// (4, 1) <> (2, 1): True -// (4, 1) = (2, 1): False -// (4, 1) = (4, 1): True -// (4, 1) = (4, 1): True -// diff --git a/snippets/csharp/System/Object/Equals/equals_ref.cs b/snippets/csharp/System/Object/Equals/equals_ref.cs deleted file mode 100644 index 4be41c87962..00000000000 --- a/snippets/csharp/System/Object/Equals/equals_ref.cs +++ /dev/null @@ -1,44 +0,0 @@ -// -using System; - -// Define a reference type that does not override Equals. -public class Person -{ - private string personName; - - public Person(string name) - { - this.personName = name; - } - - public override string ToString() - { - return this.personName; - } -} - -public class Example -{ - public static void Main() - { - Person person1a = new Person("John"); - Person person1b = person1a; - Person person2 = new Person(person1a.ToString()); - - Console.WriteLine("Calling Equals:"); - Console.WriteLine("person1a and person1b: {0}", person1a.Equals(person1b)); - Console.WriteLine("person1a and person2: {0}", person1a.Equals(person2)); - - Console.WriteLine("\nCasting to an Object and calling Equals:"); - Console.WriteLine("person1a and person1b: {0}", ((object) person1a).Equals((object) person1b)); - Console.WriteLine("person1a and person2: {0}", ((object) person1a).Equals((object) person2)); - } -} -// The example displays the following output: -// person1a and person1b: True -// person1a and person2: False -// -// Casting to an Object and calling Equals: -// person1a and person1b: True -// person1a and person2: False -// diff --git a/snippets/csharp/System/Object/Equals/equals_val1.cs b/snippets/csharp/System/Object/Equals/equals_val1.cs deleted file mode 100644 index 58ae86b4936..00000000000 --- a/snippets/csharp/System/Object/Equals/equals_val1.cs +++ /dev/null @@ -1,23 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - byte value1 = 12; - int value2 = 12; - - object object1 = value1; - object object2 = value2; - - Console.WriteLine("{0} ({1}) = {2} ({3}): {4}", - object1, object1.GetType().Name, - object2, object2.GetType().Name, - object1.Equals(object2)); - - // The example displays the following output: - // 12 (Byte) = 12 (Int32): False - // - } -} diff --git a/snippets/csharp/System/Object/Equals/equals_val2.cs b/snippets/csharp/System/Object/Equals/equals_val2.cs deleted file mode 100644 index c0240be4987..00000000000 --- a/snippets/csharp/System/Object/Equals/equals_val2.cs +++ /dev/null @@ -1,40 +0,0 @@ -// -using System; - -// Define a value type that does not override Equals. -public struct Person -{ - private string personName; - - public Person(string name) - { - this.personName = name; - } - - public override string ToString() - { - return this.personName; - } -} - -public struct Example -{ - public static void Main() - { - Person person1 = new Person("John"); - Person person2 = new Person("John"); - - Console.WriteLine("Calling Equals:"); - Console.WriteLine(person1.Equals(person2)); - - Console.WriteLine("\nCasting to an Object and calling Equals:"); - Console.WriteLine(((object) person1).Equals((object) person2)); - } -} -// The example displays the following output: -// Calling Equals: -// True -// -// Casting to an Object and calling Equals: -// True -// diff --git a/snippets/csharp/System/Object/Equals/equalsoverride.cs b/snippets/csharp/System/Object/Equals/equalsoverride.cs deleted file mode 100644 index 43a66368211..00000000000 --- a/snippets/csharp/System/Object/Equals/equalsoverride.cs +++ /dev/null @@ -1,43 +0,0 @@ -using System; - -// -public class Person -{ - private string idNumber; - private string personName; - - public Person(string name, string id) - { - this.personName = name; - this.idNumber = id; - } - - public override bool Equals(Object obj) - { - Person personObj = obj as Person; - if (personObj == null) - return false; - else - return idNumber.Equals(personObj.idNumber); - } - - public override int GetHashCode() - { - return this.idNumber.GetHashCode(); - } -} - -public class Example -{ - public static void Main() - { - Person p1 = new Person("John", "63412895"); - Person p2 = new Person("Jack", "63412895"); - Console.WriteLine(p1.Equals(p2)); - Console.WriteLine(Object.Equals(p1, p2)); - } -} -// The example displays the following output: -// True -// True -// diff --git a/snippets/csharp/System/Object/Equals/equalssb1.cs b/snippets/csharp/System/Object/Equals/equalssb1.cs deleted file mode 100644 index e4381993ee7..00000000000 --- a/snippets/csharp/System/Object/Equals/equalssb1.cs +++ /dev/null @@ -1,28 +0,0 @@ -// -using System; -using System.Text; - -public class Example -{ - public static void Main() - { - StringBuilder sb1 = new StringBuilder("building a string..."); - StringBuilder sb2 = new StringBuilder("building a string..."); - - Console.WriteLine("sb1.Equals(sb2): {0}", sb1.Equals(sb2)); - Console.WriteLine("((Object) sb1).Equals(sb2): {0}", - ((Object) sb1).Equals(sb2)); - Console.WriteLine("Object.Equals(sb1, sb2): {0}", - Object.Equals(sb1, sb2)); - - Object sb3 = new StringBuilder("building a string..."); - Console.WriteLine("\nsb3.Equals(sb2): {0}", sb3.Equals(sb2)); - } -} -// The example displays the following output: -// sb1.Equals(sb2): True -// ((Object) sb1).Equals(sb2): False -// Object.Equals(sb1, sb2): False -// -// sb3.Equals(sb2): False -// diff --git a/snippets/csharp/System/Object/Finalize/finalize_safe.cs b/snippets/csharp/System/Object/Finalize/finalize_safe.cs deleted file mode 100644 index 4d902d49106..00000000000 --- a/snippets/csharp/System/Object/Finalize/finalize_safe.cs +++ /dev/null @@ -1,152 +0,0 @@ -// -using Microsoft.Win32.SafeHandles; -using System; -using System.ComponentModel; -using System.IO; -using System.Runtime.InteropServices; - -public class FileAssociationInfo : IDisposable -{ - // Private variables. - private String ext; - private String openCmd; - private String args; - private SafeRegistryHandle hExtHandle, hAppIdHandle; - - // Windows API calls. - [DllImport("advapi32.dll", CharSet= CharSet.Auto, SetLastError=true)] - private static extern int RegOpenKeyEx(IntPtr hKey, - String lpSubKey, int ulOptions, int samDesired, - out IntPtr phkResult); - [DllImport("advapi32.dll", CharSet= CharSet.Unicode, EntryPoint = "RegQueryValueExW", - SetLastError=true)] - private static extern int RegQueryValueEx(IntPtr hKey, - string lpValueName, int lpReserved, out uint lpType, - string lpData, ref uint lpcbData); - [DllImport("advapi32.dll", SetLastError = true)] - private static extern int RegSetValueEx(IntPtr hKey, [MarshalAs(UnmanagedType.LPStr)] string lpValueName, - int Reserved, uint dwType, [MarshalAs(UnmanagedType.LPStr)] string lpData, - int cpData); - [DllImport("advapi32.dll", SetLastError=true)] - private static extern int RegCloseKey(UIntPtr hKey); - - // Windows API constants. - private const int HKEY_CLASSES_ROOT = unchecked((int) 0x80000000); - private const int ERROR_SUCCESS = 0; - - private const int KEY_QUERY_VALUE = 1; - private const int KEY_SET_VALUE = 0x2; - - private const uint REG_SZ = 1; - - private const int MAX_PATH = 260; - - public FileAssociationInfo(String fileExtension) - { - int retVal = 0; - uint lpType = 0; - - if (!fileExtension.StartsWith(".")) - fileExtension = "." + fileExtension; - ext = fileExtension; - - IntPtr hExtension = IntPtr.Zero; - // Get the file extension value. - retVal = RegOpenKeyEx(new IntPtr(HKEY_CLASSES_ROOT), fileExtension, 0, KEY_QUERY_VALUE, out hExtension); - if (retVal != ERROR_SUCCESS) - throw new Win32Exception(retVal); - // Instantiate the first SafeRegistryHandle. - hExtHandle = new SafeRegistryHandle(hExtension, true); - - string appId = new string(' ', MAX_PATH); - uint appIdLength = (uint) appId.Length; - retVal = RegQueryValueEx(hExtHandle.DangerousGetHandle(), String.Empty, 0, out lpType, appId, ref appIdLength); - if (retVal != ERROR_SUCCESS) - throw new Win32Exception(retVal); - // We no longer need the hExtension handle. - hExtHandle.Dispose(); - - // Determine the number of characters without the terminating null. - appId = appId.Substring(0, (int) appIdLength / 2 - 1) + @"\shell\open\Command"; - - // Open the application identifier key. - string exeName = new string(' ', MAX_PATH); - uint exeNameLength = (uint) exeName.Length; - IntPtr hAppId; - retVal = RegOpenKeyEx(new IntPtr(HKEY_CLASSES_ROOT), appId, 0, KEY_QUERY_VALUE | KEY_SET_VALUE, - out hAppId); - if (retVal != ERROR_SUCCESS) - throw new Win32Exception(retVal); - - // Instantiate the second SafeRegistryHandle. - hAppIdHandle = new SafeRegistryHandle(hAppId, true); - - // Get the executable name for this file type. - string exePath = new string(' ', MAX_PATH); - uint exePathLength = (uint) exePath.Length; - retVal = RegQueryValueEx(hAppIdHandle.DangerousGetHandle(), String.Empty, 0, out lpType, exePath, ref exePathLength); - if (retVal != ERROR_SUCCESS) - throw new Win32Exception(retVal); - - // Determine the number of characters without the terminating null. - exePath = exePath.Substring(0, (int) exePathLength / 2 - 1); - // Remove any environment strings. - exePath = Environment.ExpandEnvironmentVariables(exePath); - - int position = exePath.IndexOf('%'); - if (position >= 0) { - args = exePath.Substring(position); - // Remove command line parameters ('%0', etc.). - exePath = exePath.Substring(0, position).Trim(); - } - openCmd = exePath; - } - - public String Extension - { get { return ext; } } - - public String Open - { get { return openCmd; } - set { - if (hAppIdHandle.IsInvalid | hAppIdHandle.IsClosed) - throw new InvalidOperationException("Cannot write to registry key."); - if (! File.Exists(value)) { - string message = String.Format("'{0}' does not exist", value); - throw new FileNotFoundException(message); - } - string cmd = value + " %1"; - int retVal = RegSetValueEx(hAppIdHandle.DangerousGetHandle(), String.Empty, 0, - REG_SZ, value, value.Length + 1); - if (retVal != ERROR_SUCCESS) - throw new Win32Exception(retVal); - } } - - public void Dispose() - { - Dispose(disposing: true); - GC.SuppressFinalize(this); - } - - protected void Dispose(bool disposing) - { - // Ordinarily, we release unmanaged resources here; - // but all are wrapped by safe handles. - - // Release disposable objects. - if (disposing) { - if (hExtHandle != null) hExtHandle.Dispose(); - if (hAppIdHandle != null) hAppIdHandle.Dispose(); - } - } -} -// - -public class Example -{ - public static void Main() - { - FileAssociationInfo fa = new FileAssociationInfo(".txt"); - Console.WriteLine("{0} files are handled by '{1}'", fa.Extension, fa.Open); - fa.Dispose(); - } -} diff --git a/snippets/csharp/System/Object/GetHashCode/direct1.cs b/snippets/csharp/System/Object/GetHashCode/direct1.cs deleted file mode 100644 index 62a266de801..00000000000 --- a/snippets/csharp/System/Object/GetHashCode/direct1.cs +++ /dev/null @@ -1,60 +0,0 @@ -// -using System; - -public struct Number -{ - private int n; - - public Number(int value) - { - n = value; - } - - public int Value - { - get { return n; } - } - - public override bool Equals(Object obj) - { - if (obj == null || ! (obj is Number)) - return false; - else - return n == ((Number) obj).n; - } - - public override int GetHashCode() - { - return n; - } - - public override string ToString() - { - return n.ToString(); - } -} - -public class Example -{ - public static void Main() - { - Random rnd = new Random(); - for (int ctr = 0; ctr <= 9; ctr++) { - int randomN = rnd.Next(Int32.MinValue, Int32.MaxValue); - Number n = new Number(randomN); - Console.WriteLine("n = {0,12}, hash code = {1,12}", n, n.GetHashCode()); - } - } -} -// The example displays output like the following: -// n = -634398368, hash code = -634398368 -// n = 2136747730, hash code = 2136747730 -// n = -1973417279, hash code = -1973417279 -// n = 1101478715, hash code = 1101478715 -// n = 2078057429, hash code = 2078057429 -// n = -334489950, hash code = -334489950 -// n = -68958230, hash code = -68958230 -// n = -379951485, hash code = -379951485 -// n = -31553685, hash code = -31553685 -// n = 2105429592, hash code = 2105429592 -// diff --git a/snippets/csharp/System/Object/GetHashCode/shift1.cs b/snippets/csharp/System/Object/GetHashCode/shift1.cs deleted file mode 100644 index 8859faaa507..00000000000 --- a/snippets/csharp/System/Object/GetHashCode/shift1.cs +++ /dev/null @@ -1,72 +0,0 @@ -// -using System; - -public struct Point -{ - private int x; - private int y; - - public Point(int x, int y) - { - this.x = x; - this.y = y; - } - - public override bool Equals(Object obj) - { - if (!(obj is Point)) return false; - - Point p = (Point) obj; - return x == p.x & y == p.y; - } - - public override int GetHashCode() - { - return ShiftAndWrap(x.GetHashCode(), 2) ^ y.GetHashCode(); - } - - private int ShiftAndWrap(int value, int positions) - { - positions = positions & 0x1F; - - // Save the existing bit pattern, but interpret it as an unsigned integer. - uint number = BitConverter.ToUInt32(BitConverter.GetBytes(value), 0); - // Preserve the bits to be discarded. - uint wrapped = number >> (32 - positions); - // Shift and wrap the discarded bits. - return BitConverter.ToInt32(BitConverter.GetBytes((number << positions) | wrapped), 0); - } -} - -public class Example -{ - public static void Main() - { - Point pt = new Point(5, 8); - Console.WriteLine(pt.GetHashCode()); - - pt = new Point(8, 5); - Console.WriteLine(pt.GetHashCode()); - } -} -// The example displays the following output: -// 28 -// 37 -// - -public class Utility -{ - // - public int ShiftAndWrap(int value, int positions) - { - positions = positions & 0x1F; - - // Save the existing bit pattern, but interpret it as an unsigned integer. - uint number = BitConverter.ToUInt32(BitConverter.GetBytes(value), 0); - // Preserve the bits to be discarded. - uint wrapped = number >> (32 - positions); - // Shift and wrap the discarded bits. - return BitConverter.ToInt32(BitConverter.GetBytes((number << positions) | wrapped), 0); - } - // -} diff --git a/snippets/csharp/System/Object/GetHashCode/xor1.cs b/snippets/csharp/System/Object/GetHashCode/xor1.cs deleted file mode 100644 index f1888b9d1dc..00000000000 --- a/snippets/csharp/System/Object/GetHashCode/xor1.cs +++ /dev/null @@ -1,44 +0,0 @@ -// -using System; - -// A type that represents a 2-D point. -public struct Point -{ - private int x; - private int y; - - public Point(int x, int y) - { - this.x = x; - this.y = y; - } - - public override bool Equals(Object obj) - { - if (! (obj is Point)) return false; - - Point p = (Point) obj; - return x == p.x & y == p.y; - } - - public override int GetHashCode() - { - return x ^ y; - } -} - -public class Example -{ - public static void Main() - { - Point pt = new Point(5, 8); - Console.WriteLine(pt.GetHashCode()); - - pt = new Point(8, 5); - Console.WriteLine(pt.GetHashCode()); - } -} -// The example displays the following output: -// 13 -// 13 -// diff --git a/snippets/csharp/System/Object/GetHashCode/xor2.cs b/snippets/csharp/System/Object/GetHashCode/xor2.cs deleted file mode 100644 index 306d51eaa8d..00000000000 --- a/snippets/csharp/System/Object/GetHashCode/xor2.cs +++ /dev/null @@ -1,48 +0,0 @@ -// -using System; - -public struct Point -{ - private int x; - private int y; - - public Point(int x, int y) - { - this.x = x; - this.y = y; - } - - public override bool Equals(Object obj) - { - if (obj is Point) - { - Point p = (Point) obj; - return x == p.x & y == p.y; - } - else - { - return false; - } - } - - public override int GetHashCode() - { - return Tuple.Create(x, y).GetHashCode(); - } -} - -public class Example -{ - public static void Main() - { - Point pt = new Point(5, 8); - Console.WriteLine(pt.GetHashCode()); - - pt = new Point(8, 5); - Console.WriteLine(pt.GetHashCode()); - } -} -// The example displays the following output: -// 173 -// 269 -// diff --git a/snippets/csharp/System/Object/ToString/array1.cs b/snippets/csharp/System/Object/ToString/array1.cs deleted file mode 100644 index cf7b237be0c..00000000000 --- a/snippets/csharp/System/Object/ToString/array1.cs +++ /dev/null @@ -1,20 +0,0 @@ -using System; -using System.Collections.Generic; - -public class Example -{ - public static void Main() - { - // - int[] values = { 1, 2, 4, 8, 16, 32, 64, 128 }; - Console.WriteLine(values.ToString()); - - List list = new List(values); - Console.WriteLine(list.ToString()); - - // The example displays the following output: - // System.Int32[] - // System.Collections.Generic.List`1[System.Int32] - // - } -} diff --git a/snippets/csharp/System/Object/ToString/customize1.cs b/snippets/csharp/System/Object/ToString/customize1.cs deleted file mode 100644 index 6b160b6cf08..00000000000 --- a/snippets/csharp/System/Object/ToString/customize1.cs +++ /dev/null @@ -1,38 +0,0 @@ -// -using System; -using System.Collections.Generic; - -public class CList : List -{ - public CList(IEnumerable collection) : base(collection) - { } - - public CList() : base() - {} - - public override string ToString() - { - string retVal = string.Empty; - foreach (T item in this) { - if (string.IsNullOrEmpty(retVal)) - retVal += item.ToString(); - else - retVal += string.Format(", {0}", item); - } - return retVal; - } -} - -public class Example -{ - public static void Main() - { - var list2 = new CList(); - list2.Add(1000); - list2.Add(2000); - Console.WriteLine(list2.ToString()); - } -} -// The example displays the following output: -// 1000, 2000 -// diff --git a/snippets/csharp/System/Object/ToString/customize2.cs b/snippets/csharp/System/Object/ToString/customize2.cs deleted file mode 100644 index a6e5e0b652d..00000000000 --- a/snippets/csharp/System/Object/ToString/customize2.cs +++ /dev/null @@ -1,47 +0,0 @@ -// -using System; -using System.Collections.Generic; - -public static class StringExtensions -{ - public static string ToString2(this List l) - { - string retVal = string.Empty; - foreach (T item in l) - retVal += string.Format("{0}{1}", string.IsNullOrEmpty(retVal) ? - "" : ", ", - item); - return string.IsNullOrEmpty(retVal) ? "{}" : "{ " + retVal + " }"; - } - - public static string ToString(this List l, string fmt) - { - string retVal = string.Empty; - foreach (T item in l) { - IFormattable ifmt = item as IFormattable; - if (ifmt != null) - retVal += string.Format("{0}{1}", - string.IsNullOrEmpty(retVal) ? - "" : ", ", ifmt.ToString(fmt, null)); - else - retVal += ToString2(l); - } - return string.IsNullOrEmpty(retVal) ? "{}" : "{ " + retVal + " }"; - } -} - -public class Example -{ - public static void Main() - { - List list = new List(); - list.Add(1000); - list.Add(2000); - Console.WriteLine(list.ToString2()); - Console.WriteLine(list.ToString("N0")); - } -} -// The example displays the following output: -// { 1000, 2000 } -// { 1,000, 2,000 } -// diff --git a/snippets/csharp/System/Object/ToString/tostring1.cs b/snippets/csharp/System/Object/ToString/tostring1.cs deleted file mode 100644 index 4e1c698cdc2..00000000000 --- a/snippets/csharp/System/Object/ToString/tostring1.cs +++ /dev/null @@ -1,15 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - Object obj = new Object(); - Console.WriteLine(obj.ToString()); - - // The example displays the following output: - // System.Object - // - } -} diff --git a/snippets/csharp/System/Object/ToString/tostring2.cs b/snippets/csharp/System/Object/ToString/tostring2.cs deleted file mode 100644 index 261ca8191c8..00000000000 --- a/snippets/csharp/System/Object/ToString/tostring2.cs +++ /dev/null @@ -1,22 +0,0 @@ -// -using System; -using Examples; - -namespace Examples -{ - public class Object1 - { - } -} - -public class Example -{ - public static void Main() - { - object obj1 = new Object1(); - Console.WriteLine(obj1.ToString()); - } -} -// The example displays the following output: -// Examples.Object1 -// diff --git a/snippets/csharp/System/Object/ToString/tostring3.cs b/snippets/csharp/System/Object/ToString/tostring3.cs deleted file mode 100644 index 1f83443ed41..00000000000 --- a/snippets/csharp/System/Object/ToString/tostring3.cs +++ /dev/null @@ -1,29 +0,0 @@ -// -using System; - -public class Object2 -{ - private object value; - - public Object2(object value) - { - this.value = value; - } - - public override string ToString() - { - return base.ToString() + ": " + value.ToString(); - } -} - -public class Example -{ - public static void Main() - { - Object2 obj2 = new Object2('a'); - Console.WriteLine(obj2.ToString()); - } -} -// The example displays the following output: -// Object2: a -// diff --git a/snippets/csharp/System/Object/ToString/tostringoverload1.cs b/snippets/csharp/System/Object/ToString/tostringoverload1.cs deleted file mode 100644 index 527987dffc8..00000000000 --- a/snippets/csharp/System/Object/ToString/tostringoverload1.cs +++ /dev/null @@ -1,75 +0,0 @@ -// -using System; - -public class Automobile -{ - private int _doors; - private string _cylinders; - private int _year; - private string _model; - - public Automobile(string model, int year , int doors, - string cylinders) - { - _model = model; - _year = year; - _doors = doors; - _cylinders = cylinders; - } - - public int Doors - { get { return _doors; } } - - public string Model - { get { return _model; } } - - public int Year - { get { return _year; } } - - public string Cylinders - { get { return _cylinders; } } - - public override string ToString() - { - return ToString("G"); - } - - public string ToString(string fmt) - { - if (string.IsNullOrEmpty(fmt)) - fmt = "G"; - - switch (fmt.ToUpperInvariant()) - { - case "G": - return string.Format("{0} {1}", _year, _model); - case "D": - return string.Format("{0} {1}, {2} dr.", - _year, _model, _doors); - case "C": - return string.Format("{0} {1}, {2}", - _year, _model, _cylinders); - case "A": - return string.Format("{0} {1}, {2} dr. {3}", - _year, _model, _doors, _cylinders); - default: - string msg = string.Format("'{0}' is an invalid format string", - fmt); - throw new ArgumentException(msg); - } - } -} - -public class Example -{ - public static void Main() - { - var auto = new Automobile("Lynx", 2016, 4, "V8"); - Console.WriteLine(auto.ToString()); - Console.WriteLine(auto.ToString("A")); - } -} -// The example displays the following output: -// 2016 Lynx -// 2016 Lynx, 4 dr. V8 -// diff --git a/snippets/csharp/System/Object/ToString/tostringoverload2.cs b/snippets/csharp/System/Object/ToString/tostringoverload2.cs deleted file mode 100644 index df1d8674b4e..00000000000 --- a/snippets/csharp/System/Object/ToString/tostringoverload2.cs +++ /dev/null @@ -1,25 +0,0 @@ -// -using System; -using System.Globalization; - -public class Example -{ - public static void Main() - { - string[] cultureNames = { "en-US", "en-GB", "fr-FR", - "hr-HR", "ja-JP" }; - Decimal value = 1603.49m; - foreach (var cultureName in cultureNames) { - CultureInfo culture = new CultureInfo(cultureName); - Console.WriteLine("{0}: {1}", culture.Name, - value.ToString("C2", culture)); - } - } -} -// The example displays the following output: -// en-US: $1,603.49 -// en-GB: £1,603.49 -// fr-FR: 1 603,49 € -// hr-HR: 1.603,49 kn -// ja-JP: ¥1,603.49 -// diff --git a/snippets/csharp/System/Single/CompareTo/compareto2.cs b/snippets/csharp/System/Single/CompareTo/compareto2.cs deleted file mode 100644 index bf2bb4dae68..00000000000 --- a/snippets/csharp/System/Single/CompareTo/compareto2.cs +++ /dev/null @@ -1,21 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - float value1 = 16.5457f; - float operand = 3.8899982f; - float value2 = value1 * operand / operand; - Console.WriteLine("Comparing {0} and {1}: {2}\n", - value1, value2, value1.CompareTo(value2)); - Console.WriteLine("Comparing {0:R} and {1:R}: {2}", - value1, value2, value1.CompareTo(value2)); - } -} -// The example displays the following output: -// Comparing 16.5457 and 16.5457: -1 -// -// Comparing 16.5457 and 16.545702: -1 -// diff --git a/snippets/csharp/System/Single/CompareTo/compareto3.cs b/snippets/csharp/System/Single/CompareTo/compareto3.cs deleted file mode 100644 index e861477704a..00000000000 --- a/snippets/csharp/System/Single/CompareTo/compareto3.cs +++ /dev/null @@ -1,21 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - float value1 = 16.5457f; - float operand = 3.8899982f; - object value2 = value1 * operand / operand; - Console.WriteLine("Comparing {0} and {1}: {2}\n", - value1, value2, value1.CompareTo(value2)); - Console.WriteLine("Comparing {0:R} and {1:R}: {2}", - value1, value2, value1.CompareTo(value2)); - } -} -// The example displays the following output: -// Comparing 16.5457 and 16.5457: -1 -// -// Comparing 16.5457 and 16.545702: -1 -// diff --git a/snippets/csharp/System/Single/Epsilon/epsilon.cs b/snippets/csharp/System/Single/Epsilon/epsilon.cs deleted file mode 100644 index 7ae58110a93..00000000000 --- a/snippets/csharp/System/Single/Epsilon/epsilon.cs +++ /dev/null @@ -1,27 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - float[] values = { 0f, Single.Epsilon, Single.Epsilon * .5f }; - - for (int ctr = 0; ctr <= values.Length - 2; ctr++) - { - for (int ctr2 = ctr + 1; ctr2 <= values.Length - 1; ctr2++) - { - Console.WriteLine("{0:r} = {1:r}: {2}", - values[ctr], values[ctr2], - values[ctr].Equals(values[ctr2])); - } - Console.WriteLine(); - } - } -} -// The example displays the following output: -// 0 = 1.401298E-45: False -// 0 = 0: True -// -// 1.401298E-45 = 0: False -// diff --git a/snippets/csharp/System/Single/Epsilon/epsilon1.cs b/snippets/csharp/System/Single/Epsilon/epsilon1.cs deleted file mode 100644 index d82335360e0..00000000000 --- a/snippets/csharp/System/Single/Epsilon/epsilon1.cs +++ /dev/null @@ -1,50 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - float[] values = { 0.0f, Single.Epsilon }; - foreach (var value in values) { - Console.WriteLine(GetComponentParts(value)); - Console.WriteLine(); - } - } - - private static string GetComponentParts(float value) - { - string result = String.Format("{0:R}: ", value); - int indent = result.Length; - - // Convert the single to a 4-byte array. - byte[] bytes = BitConverter.GetBytes(value); - int formattedSingle = BitConverter.ToInt32(bytes, 0); - - // Get the sign bit (byte 3, bit 7). - result += String.Format("Sign: {0}\n", - (formattedSingle >> 31) != 0 ? "1 (-)" : "0 (+)"); - - // Get the exponent (byte 2 bit 7 to byte 3, bits 6) - int exponent = (formattedSingle >> 23) & 0x000000FF; - int adjustment = (exponent != 0) ? 127 : 126; - result += String.Format("{0}Exponent: 0x{1:X4} ({1})\n", new String(' ', indent), exponent - adjustment); - - // Get the significand (bits 0-22) - long significand = exponent != 0 ? - ((formattedSingle & 0x007FFFFF) | 0x800000) : - (formattedSingle & 0x007FFFFF); - result += String.Format("{0}Mantissa: 0x{1:X13}\n", new String(' ', indent), significand); - return result; - } -} -// // The example displays the following output: -// 0: Sign: 0 (+) -// Exponent: 0xFFFFFF82 (-126) -// Mantissa: 0x0000000000000 -// -// -// 1.401298E-45: Sign: 0 (+) -// Exponent: 0xFFFFFF82 (-126) -// Mantissa: 0x0000000000001 -// \ No newline at end of file diff --git a/snippets/csharp/System/Single/Equals/equalsabs1.cs b/snippets/csharp/System/Single/Equals/equalsabs1.cs deleted file mode 100644 index d30d6849ce0..00000000000 --- a/snippets/csharp/System/Single/Equals/equalsabs1.cs +++ /dev/null @@ -1,44 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - float value1 = .1f * 10f; - float value2 = 0f; - for (int ctr = 0; ctr < 10; ctr++) - value2 += .1f; - - Console.WriteLine("{0:R} = {1:R}: {2}", value1, value2, - HasMinimalDifference(value1, value2, 1)); - } - - public static bool HasMinimalDifference(float value1, float value2, int units) - { - byte[] bytes = BitConverter.GetBytes(value1); - int iValue1 = BitConverter.ToInt32(bytes, 0); - - bytes = BitConverter.GetBytes(value2); - int iValue2 = BitConverter.ToInt32(bytes, 0); - - // If the signs are different, return false except for +0 and -0. - if ((iValue1 >> 31) != (iValue2 >> 31)) - { - if (value1 == value2) - return true; - - return false; - } - - int diff = Math.Abs(iValue1 - iValue2); - - if (diff <= units) - return true; - - return false; - } -} -// The example displays the following output: -// 1 = 1.00000012: True -// \ No newline at end of file diff --git a/snippets/csharp/System/String/.ctor/char2_ctor.cs b/snippets/csharp/System/String/.ctor/char2_ctor.cs deleted file mode 100644 index 38354d0132c..00000000000 --- a/snippets/csharp/System/String/.ctor/char2_ctor.cs +++ /dev/null @@ -1,30 +0,0 @@ -// -using System; - -public class Example -{ - public static unsafe void Main() - { - char[] characters = { 'H', 'e', 'l', 'l', 'o', ' ', - 'w', 'o', 'r', 'l', 'd', '!', '\u0000' }; - String value; - - fixed (char* charPtr = characters) { - int length = 0; - Char* iterator = charPtr; - - while (*iterator != '\x0000') - { - if (*iterator == '!' || *iterator == '.') - break; - iterator++; - length++; - } - value = new String(charPtr, 0, length); - } - Console.WriteLine(value); - } -} -// The example displays the following output: -// Hello World -// diff --git a/snippets/csharp/System/String/.ctor/chptrctor_null.cs b/snippets/csharp/System/String/.ctor/chptrctor_null.cs deleted file mode 100644 index dc88c6c7971..00000000000 --- a/snippets/csharp/System/String/.ctor/chptrctor_null.cs +++ /dev/null @@ -1,31 +0,0 @@ -// -using System; - -public class Example -{ - public unsafe static void Main() - { - char[] chars = { 'a', 'b', 'c', 'd', '\0', 'A', 'B', 'C', 'D', '\0' }; - string s = null; - - fixed(char* chPtr = chars) { - s = new string(chPtr, 0, chars.Length); - } - - foreach (var ch in s) - Console.Write($"{(ushort)ch:X4} "); - Console.WriteLine(); - - fixed(char* chPtr = chars) { - s = new string(chPtr); - } - - foreach (var ch in s) - Console.Write($"{(ushort)ch:X4} "); - Console.WriteLine(); - } -} -// The example displays the following output: -// 0061 0062 0063 0064 0000 0041 0042 0043 0044 0000 -// 0061 0062 0063 0064 -// diff --git a/snippets/csharp/System/String/.ctor/ctor1.cs b/snippets/csharp/System/String/.ctor/ctor1.cs deleted file mode 100644 index 8ad8e8875e1..00000000000 --- a/snippets/csharp/System/String/.ctor/ctor1.cs +++ /dev/null @@ -1,17 +0,0 @@ -// -using System; - -public class Example -{ - public static void Main() - { - String value1 = "This is a string."; - String value2 = value1; - Console.WriteLine(value1); - Console.WriteLine(value2); - } -} -// The example displays the following output: -// This is a string. -// This is a string. -// diff --git a/snippets/csharp/System/String/.ctor/ctor2.cs b/snippets/csharp/System/String/.ctor/ctor2.cs deleted file mode 100644 index 6237cb1be8c..00000000000 --- a/snippets/csharp/System/String/.ctor/ctor2.cs +++ /dev/null @@ -1,20 +0,0 @@ -// -using System; - -public class Example -{ - public static unsafe void Main() - { - char[] characters = { 'H', 'e', 'l', 'l', 'o', ' ', - 'w', 'o', 'r', 'l', 'd', '!', '\u0000' }; - string value; - - fixed (char* charPtr = characters) { - value = new String(charPtr); - } - Console.WriteLine(value); - } -} -// The example displays the following output: -// Hello world! -// \ No newline at end of file diff --git a/snippets/csharp/System/String/.ctor/ptrctor_null.cs b/snippets/csharp/System/String/.ctor/ptrctor_null.cs deleted file mode 100644 index caf54ef4b3f..00000000000 --- a/snippets/csharp/System/String/.ctor/ptrctor_null.cs +++ /dev/null @@ -1,32 +0,0 @@ -// -using System; - -public class Example -{ - public unsafe static void Main() - { - sbyte[] bytes = { 0x61, 0x62, 0x063, 0x064, 0x00, 0x41, 0x42, 0x43, 0x44, 0x00 }; - - string s = null; - fixed (sbyte* bytePtr = bytes) { - s = new string(bytePtr, 0, bytes.Length); - } - - foreach (var ch in s) - Console.Write($"{(ushort)ch:X4} "); - - Console.WriteLine(); - - fixed(sbyte* bytePtr = bytes) { - s = new string(bytePtr); - } - - foreach (var ch in s) - Console.Write($"{(ushort)ch:X4} "); - Console.WriteLine(); - } -} -// The example displays the following output: -// 0061 0062 0063 0064 0000 0041 0042 0043 0044 0000 -// 0061 0062 0063 0064 -// diff --git a/snippets/csharp/System/String/.ctor/source.cs b/snippets/csharp/System/String/.ctor/source.cs deleted file mode 100644 index 7eebd4e46d9..00000000000 --- a/snippets/csharp/System/String/.ctor/source.cs +++ /dev/null @@ -1,91 +0,0 @@ -using System; -using System.Text; - -namespace Microsoft.Demo -{ - class ConsoleApp - { - [STAThread] - static void Main(string[] args) - { -// - // Unicode Mathematical operators - char [] charArr1 = {'\u2200','\u2202','\u200F','\u2205'}; - String szMathSymbols = new String(charArr1); - - // Unicode Letterlike Symbols - char [] charArr2 = {'\u2111','\u2118','\u2122','\u2126'}; - String szLetterLike = new String (charArr2); - - // Compare Strings - the result is false - Console.WriteLine("The Strings are equal? " + - (String.Compare(szMathSymbols, szLetterLike)==0?"true":"false") ); -// -// - unsafe - { - // Null terminated ASCII characters in an sbyte array - String szAsciiUpper = null; - sbyte[] sbArr1 = new sbyte[] { 0x41, 0x42, 0x43, 0x00 }; - // Instruct the Garbage Collector not to move the memory - fixed(sbyte* pAsciiUpper = sbArr1) - { - szAsciiUpper = new String(pAsciiUpper); - } - String szAsciiLower = null; - sbyte[] sbArr2 = { 0x61, 0x62, 0x63, 0x00 }; - // Instruct the Garbage Collector not to move the memory - fixed(sbyte* pAsciiLower = sbArr2) - { - szAsciiLower = new String(pAsciiLower, 0, sbArr2.Length); - } - // Prints "ABC abc" - Console.WriteLine(szAsciiUpper + " " + szAsciiLower); - - // Compare Strings - the result is true - Console.WriteLine("The Strings are equal when capitalized ? " + - (String.Compare(szAsciiUpper.ToUpper(), szAsciiLower.ToUpper())==0?"true":"false") ); - - // This is the effective equivalent of another Compare method, which ignores case - Console.WriteLine("The Strings are equal when capitalized ? " + - (String.Compare(szAsciiUpper, szAsciiLower, true)==0?"true":"false") ); - } -// -// - // Create a Unicode String with 5 Greek Alpha characters - String szGreekAlpha = new String('\u0391',5); - // Create a Unicode String with a Greek Omega character - String szGreekOmega = new String(new char [] {'\u03A9','\u03A9','\u03A9'},2,1); - - String szGreekLetters = String.Concat(szGreekOmega, szGreekAlpha, szGreekOmega.Clone()); - - // Examine the result - Console.WriteLine(szGreekLetters); - - // The first index of Alpha - int ialpha = szGreekLetters.IndexOf('\u0391'); - // The last index of Omega - int iomega = szGreekLetters.LastIndexOf('\u03A9'); - - Console.WriteLine("The Greek letter Alpha first appears at index " + ialpha + - " and Omega last appears at index " + iomega + " in this String."); -// - -// - unsafe - { - String utfeightstring = null; - sbyte [] asciiChars = new sbyte[] { 0x51,0x52,0x53,0x54,0x54,0x56 }; - UTF8Encoding encoding = new UTF8Encoding(true, true); - - // Instruct the Garbage Collector not to move the memory - fixed(sbyte* pAsciiChars = asciiChars) - { - utfeightstring = new String(pAsciiChars,0,asciiChars.Length,encoding); - } - Console.WriteLine("The UTF8 String is " + utfeightstring ); // prints "QRSTTV" - } -// - } - } -} \ No newline at end of file diff --git a/snippets/csharp/System/String/Format/Example1.cs b/snippets/csharp/System/String/Format/Example1.cs deleted file mode 100644 index 9eb74d2cf8e..00000000000 --- a/snippets/csharp/System/String/Format/Example1.cs +++ /dev/null @@ -1,25 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - short[] values= { Int16.MinValue, -27, 0, 1042, Int16.MaxValue }; - Console.WriteLine("{0,10} {1,10}\n", "Decimal", "Hex"); - foreach (short value in values) - { - string formatString = String.Format("{0,10:G}: {0,10:X}", value); - Console.WriteLine(formatString); - } - // The example displays the following output: - // Decimal Hex - // - // -32768: 8000 - // -27: FFE5 - // 0: 0 - // 1042: 412 - // 32767: 7FFF - // - } -} diff --git a/snippets/csharp/System/String/Intern/Intern1.cs b/snippets/csharp/System/String/Intern/Intern1.cs deleted file mode 100644 index fa3a57ae33a..00000000000 --- a/snippets/csharp/System/String/Intern/Intern1.cs +++ /dev/null @@ -1,17 +0,0 @@ -using System; -using System.Text; - -[assembly: CLSCompliant(true)] -public class Class1 -{ - public static void Main() - { - // - string s1 = "MyTest"; - string s2 = new StringBuilder().Append("My").Append("Test").ToString(); - string s3 = String.Intern(s2); - Console.WriteLine((Object)s2==(Object)s1); // Different references. - Console.WriteLine((Object)s3==(Object)s1); // The same reference. - // - } -} diff --git a/snippets/csharp/System/String/Intern/Intern2.cs b/snippets/csharp/System/String/Intern/Intern2.cs deleted file mode 100644 index 69f788f3f95..00000000000 --- a/snippets/csharp/System/String/Intern/Intern2.cs +++ /dev/null @@ -1,22 +0,0 @@ -using System; -using System.Text; - -[assembly: CLSCompliant(true)] -public class Class1 -{ - public static void Main() - { - // - string str1 = String.Empty; - string str2 = String.Empty; - - StringBuilder sb = new StringBuilder().Append(String.Empty); - str2 = String.Intern(sb.ToString()); - - if((object)str1==(object)str2) - Console.WriteLine("The strings are equal."); - else - Console.WriteLine("The strings are not equal."); - // - } -} diff --git a/snippets/csharp/System/String/IsNullOrEmpty/NullString1.cs b/snippets/csharp/System/String/IsNullOrEmpty/NullString1.cs deleted file mode 100644 index cbeb40830a9..00000000000 --- a/snippets/csharp/System/String/IsNullOrEmpty/NullString1.cs +++ /dev/null @@ -1,40 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - String s = null; - - Console.WriteLine("The value of the string is '{0}'", s); - - try - { - Console.WriteLine("String length is {0}", s.Length); - } - catch (NullReferenceException e) - { - Console.WriteLine(e.Message); - } - - // The example displays the following output: - // The value of the string is '' - // Object reference not set to an instance of an object. - // - } -} - -public class Empty -{ - public void Test() - { - // - String s = ""; - Console.WriteLine("The length of '{0}' is {1}.", s, s.Length); - - // The example displays the following output: - // The length of '' is 0. - // - } -} diff --git a/snippets/csharp/System/String/IsNullOrEmpty/isnullorempty1.cs b/snippets/csharp/System/String/IsNullOrEmpty/isnullorempty1.cs deleted file mode 100644 index 1172a58eaa3..00000000000 --- a/snippets/csharp/System/String/IsNullOrEmpty/isnullorempty1.cs +++ /dev/null @@ -1,25 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - bool TestForNullOrEmpty(string s) - { - bool result; - result = s == null || s == string.Empty; - return result; - } - - string s1 = null; - string s2 = ""; - Console.WriteLine(TestForNullOrEmpty(s1)); - Console.WriteLine(TestForNullOrEmpty(s2)); - - // The example displays the following output: - // True - // True - // - } -} diff --git a/snippets/csharp/System/TimeSpan/Parse/parsefailure1.cs b/snippets/csharp/System/TimeSpan/Parse/parsefailure1.cs deleted file mode 100644 index 23d1a7e3989..00000000000 --- a/snippets/csharp/System/TimeSpan/Parse/parsefailure1.cs +++ /dev/null @@ -1,31 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - string[] values = { "000000006", "12.12:12:12.12345678" }; - foreach (string value in values) - { - try { - TimeSpan interval = TimeSpan.Parse(value); - Console.WriteLine("{0} --> {1}", value, interval); - } - catch (FormatException) { - Console.WriteLine("{0}: Bad Format", value); - } - catch (OverflowException) { - Console.WriteLine("{0}: Overflow", value); - } - } - - // Output from .NET Framework 3.5 and earlier versions: - // 000000006 --> 6.00:00:00 - // 12.12:12:12.12345678: Bad Format - // Output from .NET Framework 4 and later versions or .NET Core: - // 000000006: Overflow - // 12.12:12:12.12345678: Overflow - // - } -} diff --git a/snippets/csharp/System/TimeSpan/TryParse/tryparsefailure1.cs b/snippets/csharp/System/TimeSpan/TryParse/tryparsefailure1.cs deleted file mode 100644 index 875605e60bf..00000000000 --- a/snippets/csharp/System/TimeSpan/TryParse/tryparsefailure1.cs +++ /dev/null @@ -1,21 +0,0 @@ -using System; - -public class Example -{ - public static void Main() - { - // - string value = "000000006"; - TimeSpan interval; - if (TimeSpan.TryParse(value, out interval)) - Console.WriteLine("{0} --> {1}", value, interval); - else - Console.WriteLine("Unable to parse '{0}'", value); - - // Output from .NET Framework 3.5 and earlier versions: - // 000000006 --> 6.00:00:00 - // Output from .NET Framework 4: - // Unable to parse //000000006// - // - } -} diff --git a/snippets/csharp/System/Type/GetType/source.cs b/snippets/csharp/System/Type/GetType/source.cs deleted file mode 100644 index c78a3b0df8a..00000000000 --- a/snippets/csharp/System/Type/GetType/source.cs +++ /dev/null @@ -1,32 +0,0 @@ -using System; -using System.Reflection; - -class Example -{ static void Main() - { - string test = "System.Collections.Generic.Dictionary`2[System.String,[MyNamespace.MyType, MyAssembly]]"; - // - Type t = Type.GetType(test, - (aName) => aName.Name == "MyAssembly" ? - Assembly.LoadFrom(@".\MyPath\v5.0\MyAssembly.dll") : null, - (assem, name, ignore) => assem == null ? - Type.GetType(name, false, ignore) : - assem.GetType(name, false, ignore) - ); - // - Console.WriteLine(t); - - test = "System.Collections.Generic.Dictionary`2[[YourNamespace.YourType, YourAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null], [MyNamespace.MyType, MyAssembly]]"; - // - Type t2 = Type.GetType(test, - (aName) => aName.Name == "MyAssembly" ? - Assembly.LoadFrom(@".\MyPath\v5.0\MyAssembly.dll") : - Assembly.Load(aName), - (assem, name, ignore) => assem == null ? - Type.GetType(name, false, ignore) : - assem.GetType(name, false, ignore), true - ); - // - Console.WriteLine(t2); - } -} diff --git a/snippets/csharp/System/Type/MakeGenericType/remarks.cs b/snippets/csharp/System/Type/MakeGenericType/remarks.cs deleted file mode 100644 index a9f8c04adb2..00000000000 --- a/snippets/csharp/System/Type/MakeGenericType/remarks.cs +++ /dev/null @@ -1,22 +0,0 @@ -using System; - -// -public class Base { } -public class Derived : Base { } -// - -// -public class Outermost -{ - public class Inner - { - public class Innermost1 {} - public class Innermost2 {} - } -} -// - -class ProgStubClass -{ - public static void Main() {} -} \ No newline at end of file diff --git a/snippets/fsharp/System/Delegate/CreateDelegate/openClosedOver.fs b/snippets/fsharp/System/Delegate/CreateDelegate/openClosedOver.fs deleted file mode 100644 index 9ed094ca96a..00000000000 --- a/snippets/fsharp/System/Delegate/CreateDelegate/openClosedOver.fs +++ /dev/null @@ -1,101 +0,0 @@ -module openClosedOver - -// All four permutations of instance/static with open/closed. -// -// -open System -open System.Reflection - -// A sample class with an instance method and a static method. -type C(id) = - member _.M1(s) = - printfn $"Instance method M1 on C: id = %i{id}, s = %s{s}" - - static member M2(s) = - printfn $"Static method M2 on C: s = %s{s}" - -// Declare three delegate types for demonstrating the combinations -// of static versus instance methods and open versus closed -// delegates. -type D1 = delegate of C * string -> unit -type D2 = delegate of string -> unit -type D3 = delegate of unit -> unit - -let c1 = C 42 - -// Get a MethodInfo for each method. -// -let mi1 = typeof.GetMethod("M1", BindingFlags.Public ||| BindingFlags.Instance) -let mi2 = typeof.GetMethod("M2", BindingFlags.Public ||| BindingFlags.Static) - -printfn "\nAn instance method closed over C." - -// In this case, the delegate and the -// method must have the same list of argument types use -// delegate type D2 with instance method M1. -let test = Delegate.CreateDelegate(typeof, c1, mi1, false) - -// Because false was specified for throwOnBindFailure -// in the call to CreateDelegate, the variable 'test' -// contains null if the method fails to bind (for -// example, if mi1 happened to represent a method of -// some class other than C). -if test <> null then - let d2 = test :?> D2 - - // The same instance of C is used every time the - // delegate is invoked. - d2.Invoke "Hello, World!" - d2.Invoke "Hi, Mom!" - -printfn "\nAn open instance method." - -// In this case, the delegate has one more -// argument than the instance method this argument comes -// at the beginning, and represents the hidden instance -// argument of the instance method. Use delegate type D1 -// with instance method M1. -let d1 = Delegate.CreateDelegate(typeof, null, mi1) :?> D1 - -// An instance of C must be passed in each time the -// delegate is invoked. -d1.Invoke(c1, "Hello, World!") -d1.Invoke(C 5280, "Hi, Mom!") - -printfn "\nAn open static method." -// In this case, the delegate and the method must -// have the same list of argument types use delegate type -// D2 with static method M2. -let d2 = Delegate.CreateDelegate(typeof, null, mi2) :?> D2 - -// No instances of C are involved, because this is a static -// method. -d2.Invoke "Hello, World!" -d2.Invoke "Hi, Mom!" - -printfn "\nA static method closed over the first argument (String)." -// The delegate must omit the first argument of the method. -// A string is passed as the firstArgument parameter, and -// the delegate is bound to this string. Use delegate type -// D3 with static method M2. -let d3 = Delegate.CreateDelegate(typeof, "Hello, World!", mi2) :?> D3 - -// Each time the delegate is invoked, the same string is used. -d3.Invoke() - -// This code example produces the following output: -// An instance method closed over C. -// Instance method M1 on C: id = 42, s = Hello, World! -// Instance method M1 on C: id = 42, s = Hi, Mom! -// -// An open instance method. -// Instance method M1 on C: id = 42, s = Hello, World! -// Instance method M1 on C: id = 5280, s = Hi, Mom! -// -// An open static method. -// Static method M2 on C: s = Hello, World! -// Static method M2 on C: s = Hi, Mom! -// -// A static method closed over the first argument (String). -// Static method M2 on C: s = Hello, World! -// \ No newline at end of file diff --git a/snippets/fsharp/System/Delegate/CreateDelegate/source.fs b/snippets/fsharp/System/Delegate/CreateDelegate/source.fs deleted file mode 100644 index 529381000b4..00000000000 --- a/snippets/fsharp/System/Delegate/CreateDelegate/source.fs +++ /dev/null @@ -1,126 +0,0 @@ -module source - -// Showing all the things D(A) can bind to. -// -open System - -// Declare two sample classes, C and F. Class C has an ID -// property so instances can be identified. -type C(id) = - member _.ID = id - - member _.M1(c: C) = - printfn $"Instance method M1(C c) on C: this.id = {id}, c.ID = {c.ID}" - - member _.M2() = - printfn $"Instance method M2() on C: this.id = {id}" - - static member M3(c: C) = - printfn $"Static method M3(C c) on C: c.ID = {c.ID}" - - static member M4(c1: C, c2: C) = - printfn $"Static method M4(C c1, C c2) on C: c1.ID = {c1.ID}, c2.ID = {c2.ID}" - -// Declare a delegate type. The object of this code example -// is to show all the methods this delegate can bind to. -type D = delegate of C -> unit - - -type F() = - member _.M1(c: C) = - printfn $"Instance method M1(C c) on F: c.ID = {c.ID}" - - member _.M3(c: C) = - printfn $"Static method M3(C c) on F: c.ID = {c.ID}" - - member _.M4(f: F, c: C) = - printfn $"Static method M4(F f, C c) on F: c.ID = {c.ID}" - -[] -let main _ = - let c1 = C 42 - let c2 = C 1491 - let f1 = F() - - // Instance method with one argument of type C. - let cmi1 = typeof.GetMethod "M1" - // Instance method with no arguments. - let cmi2 = typeof.GetMethod "M2" - // Static method with one argument of type C. - let cmi3 = typeof.GetMethod "M3" - // Static method with two arguments of type C. - let cmi4 = typeof.GetMethod "M4" - - // Instance method with one argument of type C. - let fmi1 = typeof.GetMethod "M1" - // Static method with one argument of type C. - let fmi3 = typeof.GetMethod "M3" - // Static method with an argument of type F and an argument - // of type C. - let fmi4 = typeof.GetMethod "M4" - - printfn "\nAn instance method on any type, with an argument of type C." - // D can represent any instance method that exactly matches its - // signature. Methods on C and F are shown here. - let d = Delegate.CreateDelegate(typeof, c1, cmi1) :?> D - d.Invoke c2 - let d = Delegate.CreateDelegate(typeof, f1, fmi1) :?> D - d.Invoke c2 - - Console.WriteLine("\nAn instance method on C with no arguments.") - // D can represent an instance method on C that has no arguments - // in this case, the argument of D represents the hidden first - // argument of any instance method. The delegate acts like a - // static method, and an instance of C must be passed each time - // it is invoked. - let d = Delegate.CreateDelegate(typeof, null, cmi2) :?> D - d.Invoke c1 - - printfn "\nA static method on any type, with an argument of type C." - // D can represent any static method with the same signature. - // Methods on F and C are shown here. - let d = Delegate.CreateDelegate(typeof, null, cmi3) :?> D - d.Invoke c1 - let d = Delegate.CreateDelegate(typeof, null, fmi3) :?> D - d.Invoke c1 - - printfn "\nA static method on any type, with an argument of" - printfn " that type and an argument of type C." - // D can represent any static method with one argument of the - // type the method belongs and a second argument of type C. - // In this case, the method is closed over the instance of - // supplied for the its first argument, and acts like an instance - // method. Methods on F and C are shown here. - let d = Delegate.CreateDelegate(typeof, c1, cmi4) :?> D - d.Invoke c2 - let test = - Delegate.CreateDelegate(typeof, f1, fmi4, false) - - // This final example specifies false for throwOnBindFailure - // in the call to CreateDelegate, so the variable 'test' - // contains Nothing if the method fails to bind (for - // example, if fmi4 happened to represent a method of - // some class other than F). - match test with - | :? D as d -> - d.Invoke c2 - | _ -> () - 0 - -// This code example produces the following output: -// An instance method on any type, with an argument of type C. -// Instance method M1(C c) on C: this.id = 42, c.ID = 1491 -// Instance method M1(C c) on F: c.ID = 1491 -// -// An instance method on C with no arguments. -// Instance method M2() on C: this.id = 42 -// -// A static method on any type, with an argument of type C. -// Static method M3(C c) on C: c.ID = 42 -// Static method M3(C c) on F: c.ID = 42 -// -// A static method on any type, with an argument of -// that type and an argument of type C. -// Static method M4(C c1, C c2) on C: c1.ID = 42, c2.ID = 1491 -// Static method M4(F f, C c) on F: c.ID = 1491 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Delegate/CreateDelegate/source1.fs b/snippets/fsharp/System/Delegate/CreateDelegate/source1.fs deleted file mode 100644 index fc02c8ebe28..00000000000 --- a/snippets/fsharp/System/Delegate/CreateDelegate/source1.fs +++ /dev/null @@ -1,45 +0,0 @@ -module source1 - -// -open System -open System.Reflection - -// Define two classes to use in the demonstration, a base class and -// a class that derives from it. -type Base() = class end - -type Derived() = - inherit Base() - - // Define a static method to use in the demonstration. The method - // takes an instance of Base and returns an instance of Derived. - // For the purposes of the demonstration, it is not necessary for - // the method to do anything useful. - static member MyMethod(arg: Base) = - Derived() - -// Define a delegate that takes an instance of Derived and returns an -// instance of Base. -type Example = delegate of Derived -> Base - -// The binding flags needed to retrieve MyMethod. -let flags = BindingFlags.Public ||| BindingFlags.Static - -// Get a MethodInfo that represents MyMethod. -let minfo = typeof.GetMethod("MyMethod", flags) - -// Demonstrate contravariance of parameter types and covariance -// of return types by using the delegate Example to represent -// MyMethod. The delegate binds to the method because the -// parameter of the delegate is more restrictive than the -// parameter of the method (that is, the delegate accepts an -// instance of Derived, which can always be safely passed to -// a parameter of type Base), and the return type of MyMethod -// is more restrictive than the return type of Example (that -// is, the method returns an instance of Derived, which can -// always be safely cast to type Base). -let ex = Delegate.CreateDelegate(typeof, minfo) :?> Example - -// Execute MyMethod using the delegate Example. -let b = Derived() |> ex.Invoke -// \ No newline at end of file diff --git a/snippets/fsharp/System/Double/CompareTo/compareto2.fs b/snippets/fsharp/System/Double/CompareTo/compareto2.fs deleted file mode 100644 index 7da23de2bac..00000000000 --- a/snippets/fsharp/System/Double/CompareTo/compareto2.fs +++ /dev/null @@ -1,12 +0,0 @@ -module compareto2 - -// -let value1 = 6.185 -let value2 = value1 * 0.1 / 0.1 -printfn $"Comparing {value1} and {value2}: {value1.CompareTo value2}\n" -printfn $"Comparing {value1:R} and {value2:R}: {value1.CompareTo value2}" -// The example displays the following output: -// Comparing 6.185 and 6.185: -1 -// -// Comparing 6.185 and 6.1850000000000005: -1 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Double/CompareTo/compareto3.fs b/snippets/fsharp/System/Double/CompareTo/compareto3.fs deleted file mode 100644 index 62f5503a469..00000000000 --- a/snippets/fsharp/System/Double/CompareTo/compareto3.fs +++ /dev/null @@ -1,12 +0,0 @@ -module compareto3 - -// -let value1 = 6.185 -let value2 = value1 * 0.1 / 0.1 |> box -printfn $"Comparing {value1} and {value2}: {value1.CompareTo value2}\n" -printfn $"Comparing {value1:R} and {value2:R}: {value1.CompareTo value2}" -// The example displays the following output: -// Comparing 6.185 and 6.185: -1 -// -// Comparing 6.185 and 6.1850000000000005: -1 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Double/Epsilon/epsilon.fs b/snippets/fsharp/System/Double/Epsilon/epsilon.fs deleted file mode 100644 index 650b9d3ae6e..00000000000 --- a/snippets/fsharp/System/Double/Epsilon/epsilon.fs +++ /dev/null @@ -1,17 +0,0 @@ -module epsilon - -// -open System - -let values = [| 0.; Double.Epsilon; Double.Epsilon * 0.5 |] - -for i = 0 to values.Length - 2 do - for i2 = i + 1 to values.Length - 1 do - printfn $"{values[i]:r} = {values[i2]:r}: {values[i].Equals values[i2]}" - printfn "" -// The example displays the following output: -// 0 = 4.94065645841247E-324: False -// 0 = 0: True -// -// 4.94065645841247E-324 = 0: False -// \ No newline at end of file diff --git a/snippets/fsharp/System/Double/Epsilon/epsilon1.fs b/snippets/fsharp/System/Double/Epsilon/epsilon1.fs deleted file mode 100644 index 8126fb46251..00000000000 --- a/snippets/fsharp/System/Double/Epsilon/epsilon1.fs +++ /dev/null @@ -1,46 +0,0 @@ -module epsilon1 - -// -open System - -let getComponentParts (value: double) = - let result = $"{value:R}: " - let indent = result.Length - - // Convert the double to an 8-byte array. - let bytes = BitConverter.GetBytes value - // Get the sign bit (byte 7, bit 7). - let result = result + $"""Sign: {if (bytes[7] &&& 0x80uy) = 0x80uy then "1 (-)" else "0 (+)"}\n""" - - // Get the exponent (byte 6 bits 4-7 to byte 7, bits 0-6) - let exponent = (bytes[7] &&& 0x07Fuy) <<< 4 - let exponent = exponent ||| ((bytes[6] &&& 0xF0uy) >>> 4) - let adjustment = if exponent <> 0uy then 1022 else 1023 - let result = result + $"{String(' ', indent)}Exponent: 0x{int exponent - adjustment:X4} ({int exponent - adjustment})\n" - - // Get the significand (bits 0-51) - let significand = (bytes[6] &&& 0x0Fuy) <<< 48 - let significand = significand ||| byte (int64 bytes[5] <<< 40) - let significand = significand ||| byte (int64 bytes[4] <<< 32) - let significand = significand ||| byte (int64 bytes[3] <<< 24) - let significand = significand ||| byte (int64 bytes[2] <<< 16) - let significand = significand ||| byte (int64 bytes[1] <<< 8) - let significand = significand ||| bytes[0] - result + $"{String(' ', indent)}Mantissa: 0x{significand:X13}\n" - -let values = [| 0.; Double.Epsilon |] -for value in values do - printfn $"{getComponentParts value}" - printfn "" - - -// // The example displays the following output: -// 0: Sign: 0 (+) -// Exponent: 0xFFFFFC02 (-1022) -// Mantissa: 0x0000000000000 -// -// -// 4.94065645841247E-324: Sign: 0 (+) -// Exponent: 0xFFFFFC02 (-1022) -// Mantissa: 0x0000000000001 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Double/Equals/equalsabs1.fs b/snippets/fsharp/System/Double/Equals/equalsabs1.fs deleted file mode 100644 index 59f4047a639..00000000000 --- a/snippets/fsharp/System/Double/Equals/equalsabs1.fs +++ /dev/null @@ -1,28 +0,0 @@ -module equalsabs - -// -open System - -let hasMinimalDifference (value1: double) (value2: double) (units: int) = - let lValue1 = BitConverter.DoubleToInt64Bits value1 - let lValue2 = BitConverter.DoubleToInt64Bits value2 - - // If the signs are different, return false except for +0 and -0. - if (lValue1 >>> 63) <> (lValue2 >>> 63) then - value1 = value2 - else - let diff = abs (lValue1 - lValue2) - - diff <= int64 units - -let value1 = 0.1 * 10. -let mutable value2 = 0. -for _ = 0 to 9 do - value2 <- value2 + 0.1 - -printfn $"{value1:R} = {value2:R}: {hasMinimalDifference value1 value2 1}" - - -// The example displays the following output: -// 1 = 0.99999999999999989: True -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/FormatExample2.fs b/snippets/fsharp/System/FormatException/Overview/FormatExample2.fs deleted file mode 100644 index 0cf9b0f18d8..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/FormatExample2.fs +++ /dev/null @@ -1,66 +0,0 @@ -module FormatExample2 - -// -open System - -type CustomerFormatter() = - interface IFormatProvider with - member this.GetFormat(formatType) = - if formatType = typeof then - this - else - null - - interface ICustomFormatter with - member this.Format(format, arg, formatProvider: IFormatProvider) = - if this.Equals formatProvider |> not then - null - else - let format = - if String.IsNullOrEmpty format then "G" - else format.ToUpper() - - let customerString = - let s = string arg - if s.Length < 8 then - s.PadLeft(8, '0') - else s - - match format with - | "G" -> - customerString.Substring(0, 1) + "-" + - customerString.Substring(1, 5) + "-" + - customerString.Substring 6 - | "S" -> - customerString.Substring(0, 1) + "/" + - customerString.Substring(1, 5) + "/" + - customerString.Substring 6 - | "P" -> - customerString.Substring(0, 1) + "." + - customerString.Substring(1, 5) + "." + - customerString.Substring 6 - | _ -> - raise (FormatException $"The '{format}' format specifier is not supported.") - -let acctNumber = 79203159 -String.Format(CustomerFormatter(), "{0}", acctNumber) -|> printfn "%s" -String.Format(CustomerFormatter(), "{0:G}", acctNumber) -|> printfn "%s" -String.Format(CustomerFormatter(), "{0:S}", acctNumber) -|> printfn "%s" -String.Format(CustomerFormatter(), "{0:P}", acctNumber) -|> printfn "%s" -try - String.Format(CustomerFormatter(), "{0:X}", acctNumber) - |> printfn "%s" -with :? FormatException as e -> - printfn $"{e.Message}" - -// The example displays the following output: -// 7-92031-59 -// 7-92031-59 -// 7/92031/59 -// 7.92031.59 -// The 'X' format specifier is not supported. -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/formatoverload1.fs b/snippets/fsharp/System/FormatException/Overview/formatoverload1.fs deleted file mode 100644 index 7365178fd89..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/formatoverload1.fs +++ /dev/null @@ -1,13 +0,0 @@ -module formatoverload1 - -// -open System - -let dat = DateTime(2012, 1, 17, 9, 30, 0) -let city = "Chicago" -let temp = -16 -String.Format("At {0} in {1}, the temperature was {2} degrees.", dat, city, temp) -|> printfn "%s" -// The example displays output like the following: -// At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees. -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/formatoverload2.fs b/snippets/fsharp/System/FormatException/Overview/formatoverload2.fs deleted file mode 100644 index 76ebd80b44e..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/formatoverload2.fs +++ /dev/null @@ -1,29 +0,0 @@ -module formatoverload2 - -open System - -// -// Create a list of 5-tuples with population data for three U.S. cities, 1940-1950. -let cities = - [ "Los Angeles", DateTime(1940, 1, 1), 1504277, DateTime(1950, 1, 1), 1970358 - "New York", DateTime(1940, 1, 1), 7454995, DateTime(1950, 1, 1), 7891957 - "Chicago", DateTime(1940, 1, 1), 3396808, DateTime(1950, 1, 1), 3620962 - "Detroit", DateTime(1940, 1, 1), 1623452, DateTime(1950, 1, 1), 1849568 ] - -// Display header -String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}\n", "City", "Year", "Population", "Change (%)") -|> printfn "%s" - -for name, year1, pop1, year2, pop2 in cities do - String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}", - name, year1, pop1, year2, pop2, - double (pop2 - pop1) / double pop1) - |> printfn "%s" -// The example displays the following output: -// City Year Population Year Population Change (%) -// -// Los Angeles 1940 1,504,277 1950 1,970,358 31.0 % -// New York 1940 7,454,995 1950 7,891,957 5.9 % -// Chicago 1940 3,396,808 1950 3,620,962 6.6 % -// Detroit 1940 1,623,452 1950 1,849,568 13.9 % -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/formatsyntax1.fs b/snippets/fsharp/System/FormatException/Overview/formatsyntax1.fs deleted file mode 100644 index a743dbc0b0d..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/formatsyntax1.fs +++ /dev/null @@ -1,8 +0,0 @@ -module formatsyntax1 - -// -open System - -String.Format("{0,-10:C}", 126347.89m) -|> printfn "%s" -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/interceptor2.fs b/snippets/fsharp/System/FormatException/Overview/interceptor2.fs deleted file mode 100644 index f45c4c0ea79..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/interceptor2.fs +++ /dev/null @@ -1,109 +0,0 @@ -module interceptor2 - -// -open System -open System.Globalization - -type InterceptProvider() = - interface IFormatProvider with - member this.GetFormat(formatType) = - if formatType = typeof then - this - else - null - interface ICustomFormatter with - member _.Format(format, obj, provider: IFormatProvider) = - // Display information about method call. - let formatString = - if format = null then "" else format - printfn $"Provider: {provider.GetType().Name}, Object: %A{obj}, Format String: %s{formatString}" - - if obj = null then - String.Empty - else - // If this is a byte and the "R" format string, format it with Roman numerals. - match obj with - | :? byte as value when formatString.ToUpper().Equals "R" -> - let mutable returnString = String.Empty - - // Get the hundreds digit(s) - let struct (result, remainder) = Math.DivRem(value, 100uy) - if result > 0uy then - returnString <- String('C', int result) - let value = byte remainder - // Get the 50s digit - let struct (result, remainder) = Math.DivRem(value, 50uy) - if result = 1uy then - returnString <- returnString + "L" - let value = byte remainder - // Get the tens digit. - let struct (result, remainder) = Math.DivRem(value, 10uy) - if result > 0uy then - returnString <- returnString + String('X', int result) - let value = byte remainder - // Get the fives digit. - let struct (result, remainder) = Math.DivRem(value, 5uy) - if result > 0uy then - returnString <- returnString + "V" - let value = byte remainder - // Add the ones digit. - if remainder > 0uy then - returnString <- returnString + String('I', int remainder) - - // Check whether we have too many X characters. - let pos = returnString.IndexOf "XXXX" - if pos >= 0 then - let xPos = returnString.IndexOf "L" - returnString <- - if xPos >= 0 && xPos = pos - 1 then - returnString.Replace("LXXXX", "XC") - else - returnString.Replace("XXXX", "XL") - // Check whether we have too many I characters - let pos = returnString.IndexOf "IIII" - if pos >= 0 then - returnString <- - if returnString.IndexOf "V" >= 0 then - returnString.Replace("VIIII", "IX") - else - returnString.Replace("IIII", "IV") - returnString - - // Use default for all other formatting. - | :? IFormattable as x -> - x.ToString(format, CultureInfo.CurrentCulture) - | _ -> - string obj - -let n = 10 -let value = 16.935 -let day = DateTime.Now -let provider = InterceptProvider() -String.Format(provider, "{0:N0}: {1:C2} on {2:d}\n", n, value, day) -|> printfn "%s" -String.Format(provider, "{0}: {1:F}\n", "Today: ", DateTime.Now.DayOfWeek) -|> printfn "%s" -String.Format(provider, "{0:X}, {1}, {2}\n", 2uy, 12uy, 199uy) -|> printfn "%s" -String.Format(provider, "{0:R}, {1:R}, {2:R}\n", 2uy, 12uy, 199uy) -|> printfn "%s" -// The example displays the following output: -// Provider: InterceptProvider, Object: 10, Format String: N0 -// Provider: InterceptProvider, Object: 16.935, Format String: C2 -// Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d -// 10: $16.94 on 1/31/2013 -// -// Provider: InterceptProvider, Object: Today: , Format String: -// Provider: InterceptProvider, Object: Thursday, Format String: F -// Today: : Thursday -// -// Provider: InterceptProvider, Object: 2, Format String: X -// Provider: InterceptProvider, Object: 12, Format String: -// Provider: InterceptProvider, Object: 199, Format String: -// 2, 12, 199 -// -// Provider: InterceptProvider, Object: 2, Format String: R -// Provider: InterceptProvider, Object: 12, Format String: R -// Provider: InterceptProvider, Object: 199, Format String: R -// II, XII, CXCIX -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/qa-interpolated1.fs b/snippets/fsharp/System/FormatException/Overview/qa-interpolated1.fs deleted file mode 100644 index f29e8e4b141..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/qa-interpolated1.fs +++ /dev/null @@ -1,18 +0,0 @@ -module qa_interpolated1 - -// -open System - -let names = [| "Balto"; "Vanya"; "Dakota"; "Samuel"; "Koani"; "Yiska"; "Yuma" |] -let output = - names[0] + ", " + names[1] + ", " + names[2] + ", " + - names[3] + ", " + names[4] + ", " + names[5] + ", " + - names[6] + "\n" - -let date = DateTime.Now -output + String.Format("It is {0:t} on {0:d}. The day of the week is {1}.", date, date.DayOfWeek) -|> printfn "%s" -// The example displays the following output: -// Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma -// It is 10:29 AM on 1/8/2018. The day of the week is Monday. -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/qa-interpolated2.fs b/snippets/fsharp/System/FormatException/Overview/qa-interpolated2.fs deleted file mode 100644 index a70413c32d7..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/qa-interpolated2.fs +++ /dev/null @@ -1,15 +0,0 @@ -module qa_interpolated2 - -// -open System - -let names = [| "Balto"; "Vanya"; "Dakota"; "Samuel"; "Koani"; "Yiska"; "Yuma" |] -let output = $"{names[0]}, {names[1]}, {names[2]}, {names[3]}, {names[4]}, {names[5]}, {names[6]}" - -let date = DateTime.Now -output + $"\nIt is {date:t} on {date:d}. The day of the week is {date.DayOfWeek}." -|> printfn "%s" -// The example displays the following output: -// Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma -// It is 10:29 AM on 1/8/2018. The day of the week is Monday. -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/qa11.fs b/snippets/fsharp/System/FormatException/Overview/qa11.fs deleted file mode 100644 index 3d152075bed..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/qa11.fs +++ /dev/null @@ -1,15 +0,0 @@ -module qa11 - -// -open System - -let rnd = Random() -let mutable total = 0 -let numbers = Array.zeroCreate 4 -for i = 0 to 2 do - let number = rnd.Next 1001 - numbers[i] <- number - total <- total + number -numbers[3] <- total -Console.WriteLine("{0} + {1} + {2} = {3}", numbers) -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/qa21.fs b/snippets/fsharp/System/FormatException/Overview/qa21.fs deleted file mode 100644 index 56dc9afe390..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/qa21.fs +++ /dev/null @@ -1,17 +0,0 @@ -module qa21 - -// -open System - -let rnd = Random() -let numbers = Array.zeroCreate 4 -let mutable total = 0 -for i = 0 to 2 do - let number = rnd.Next 1001 - numbers[i] <- number - total <- total + number -numbers[3] <- total -let values = Array.zeroCreate numbers.Length -numbers.CopyTo(values, 0) -Console.WriteLine("{0} + {1} + {2} = {3}", values) -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/qa26.fs b/snippets/fsharp/System/FormatException/Overview/qa26.fs deleted file mode 100644 index 308535944f9..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/qa26.fs +++ /dev/null @@ -1,16 +0,0 @@ -module qa26 - -// -open System - -let values: obj list = [ 1603, 1794.68235, 15436.14 ] -for value in values do - String.Format("{0,12:C2} {0,12:E3} {0,12:F4} {0,12:N3} {1,12:P2}\n", Convert.ToDouble(value), Convert.ToDouble(value) / 10000.) - |> printfn "%s" -// The example displays output like the following: -// $1,603.00 1.603E+003 1603.0000 1,603.000 16.03 % -// -// $1,794.68 1.795E+003 1794.6824 1,794.682 17.95 % -// -// $15,436.14 1.544E+004 15436.1400 15,436.140 154.36 % -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/qa27.fs b/snippets/fsharp/System/FormatException/Overview/qa27.fs deleted file mode 100644 index dde74671a0e..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/qa27.fs +++ /dev/null @@ -1,11 +0,0 @@ -module qa27 - -open System - -// -let value = 16309.5436m -String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}", value) -|> printfn "%s" -// The example displays the following output: -// 16309.54360 16,309.54 16309.544 -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/qa28.fs b/snippets/fsharp/System/FormatException/Overview/qa28.fs deleted file mode 100644 index dbb92793763..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/qa28.fs +++ /dev/null @@ -1,11 +0,0 @@ -module qa28 - -// -open System - -let value = 16342 -String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}", value) -|> printfn "%s" -// The example displays the following output: -// 00016342 00016342.000 0,000,016,342.0 -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/qa29.fs b/snippets/fsharp/System/FormatException/Overview/qa29.fs deleted file mode 100644 index 74ab5f7281b..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/qa29.fs +++ /dev/null @@ -1,11 +0,0 @@ -module qa29 - -// -open System - -let value = 1326 -String.Format("{0,10:D6} {0,10:X8}", value) -|> printfn "%s" -// The example displays the following output: -// 001326 0000052E -// \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/starting1.fs b/snippets/fsharp/System/FormatException/Overview/starting1.fs deleted file mode 100644 index 3ea79b6661f..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/starting1.fs +++ /dev/null @@ -1,44 +0,0 @@ -module starting1 - -open System - -let snippet31 () = - // - String.Format("At {0}, the temperature is {1}°C.", DateTime.Now, 20.4) - |> printfn "%s" - // Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.' - // - -let snippet32 () = - // - String.Format("It is now {0:d} at {0:t}", DateTime.Now) - |> printfn "%s" - // Output similar to: 'It is now 4/10/2015 at 10:04 AM' - // - -let snippet34 () = - // - let years = [| 2013; 2014; 2015 |] - let population = [| 1025632; 1105967; 1148203 |] - let mutable s = String.Format("{0,-10} {1,-10}\n\n", "Year", "Population") - for i = 0 to years.Length - 1 do - s <- s + String.Format("{0,-10} {1,-10:N0}\n", years[i], population[i]) - printfn $"\n{s}" - // Result: - // Year Population - // - // 2013 1,025,632 - // 2014 1,105,967 - // 2015 1,148,203 - // - -// -let temp = 20.4m -String.Format("The temperature is {0}°C.", temp) -|> printfn "%s" -// Displays 'The temperature is 20.4°C.' -// - -snippet31 () -snippet32 () -snippet34 () \ No newline at end of file diff --git a/snippets/fsharp/System/FormatException/Overview/starting2.fs b/snippets/fsharp/System/FormatException/Overview/starting2.fs deleted file mode 100644 index 9680d1bbabb..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/starting2.fs +++ /dev/null @@ -1,20 +0,0 @@ -module starting2 - -open System - -let showFormatted () = - // - let pricePerOunce = 17.36m - String.Format("The current price is {0:C2} per ounce.", pricePerOunce) - |> printfn "%s" - // Result if current culture is en-US: - // The current price is $17.36 per ounce. - // - -// -let pricePerOunce = 17.36m -String.Format("The current price is {0} per ounce.", pricePerOunce) -|> printfn "%s" -// Result: The current price is 17.36 per ounce. -// -showFormatted () diff --git a/snippets/fsharp/System/FormatException/Overview/starting3.fs b/snippets/fsharp/System/FormatException/Overview/starting3.fs deleted file mode 100644 index 0d881960c3a..00000000000 --- a/snippets/fsharp/System/FormatException/Overview/starting3.fs +++ /dev/null @@ -1,22 +0,0 @@ -module starting3 - -// -open System -open System.Text - -let years = [| 2013; 2014; 2015 |] -let population = [| 1025632; 1105967; 1148203 |] -let sb = StringBuilder() -sb.Append(String.Format("{0,6} {1,15}\n\n", "Year", "Population")) |> ignore -for i = 0 to years.Length - 1 do - sb.Append(String.Format("{0,6} {1,15:N0}\n", years[i], population[i])) |> ignore - -printfn $"{sb}" - -// Result: -// Year Population -// -// 2013 1,025,632 -// 2014 1,105,967 -// 2015 1,148,203 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/Equals/equals2.fs b/snippets/fsharp/System/Object/Equals/equals2.fs deleted file mode 100644 index fdfe5e871a4..00000000000 --- a/snippets/fsharp/System/Object/Equals/equals2.fs +++ /dev/null @@ -1,54 +0,0 @@ -module equals2 - -// -type Point(x, y) = - new () = Point(0, 0) - member _.X = x - member _.Y = y - - override _.Equals(obj) = - //Check for null and compare run-time types. - match obj with - | :? Point as p -> - x = p.X && y = p.Y - | _ -> - false - - override _.GetHashCode() = - (x <<< 2) ^^^ y - - override _.ToString() = - $"Point({x}, {y})" - -type Point3D(x, y, z) = - inherit Point(x, y) - member _.Z = z - - override _.Equals(obj) = - match obj with - | :? Point3D as pt3 -> - base.Equals(pt3 :> Point) && z = pt3.Z - | _ -> - false - - override _.GetHashCode() = - (base.GetHashCode() <<< 2) ^^^ z - - override _.ToString() = - $"Point({x}, {y}, {z})" - -let point2D = Point(5, 5) -let point3Da = Point3D(5, 5, 2) -let point3Db = Point3D(5, 5, 2) -let point3Dc = Point3D(5, 5, -1) - -printfn $"{point2D} = {point3Da}: {point2D.Equals point3Da}" -printfn $"{point2D} = {point3Db}: {point2D.Equals point3Db}" -printfn $"{point3Da} = {point3Db}: {point3Da.Equals point3Db}" -printfn $"{point3Da} = {point3Dc}: {point3Da.Equals point3Dc}" -// The example displays the following output: -// Point(5, 5) = Point(5, 5, 2): False -// Point(5, 5) = Point(5, 5, 2): False -// Point(5, 5, 2) = Point(5, 5, 2): True -// Point(5, 5, 2) = Point(5, 5, -1): False -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/Equals/equals3.fs b/snippets/fsharp/System/Object/Equals/equals3.fs deleted file mode 100644 index 4321df320d4..00000000000 --- a/snippets/fsharp/System/Object/Equals/equals3.fs +++ /dev/null @@ -1,51 +0,0 @@ -module equals3 - -// -type Point(x, y) = - member _.X = x - member _.Y = y - - override _.Equals(obj) = - // Performs an equality check on two points (integer pairs). - match obj with - | :? Point as p -> - x = p.X && y = p.Y - | _ -> - false - - override _.GetHashCode() = - (x, y).GetHashCode() - -type Rectangle(upLeftX, upLeftY, downRightX, downRightY) = - let a = Point(upLeftX, upLeftY) - let b = Point(downRightX, downRightY) - - member _.UpLeft = a - member _.DownRight = b - - override _.Equals(obj) = - // Perform an equality check on two rectangles (Point object pairs). - match obj with - | :? Rectangle as r -> - a.Equals(r.UpLeft) && b.Equals(r.DownRight) - | _ -> - false - - override _.GetHashCode() = - (a, b).GetHashCode() - - override _.ToString() = - $"Rectangle({a.X}, {a.Y}, {b.X}, {b.Y})" - -let r1 = Rectangle(0, 0, 100, 200) -let r2 = Rectangle(0, 0, 100, 200) -let r3 = Rectangle(0, 0, 150, 200) - -printfn $"{r1} = {r2}: {r1.Equals r2}" -printfn $"{r1} = {r3}: {r1.Equals r3}" -printfn $"{r2} = {r3}: {r2.Equals r3}" -// The example displays the following output: -// Rectangle(0, 0, 100, 200) = Rectangle(0, 0, 100, 200): True -// Rectangle(0, 0, 100, 200) = Rectangle(0, 0, 150, 200): False -// Rectangle(0, 0, 100, 200) = Rectangle(0, 0, 150, 200): False -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/Equals/equals4.fs b/snippets/fsharp/System/Object/Equals/equals4.fs deleted file mode 100644 index ecde006fa16..00000000000 --- a/snippets/fsharp/System/Object/Equals/equals4.fs +++ /dev/null @@ -1,48 +0,0 @@ -module equals4 - -// -[] -type Complex = - val mutable re: double - val mutable im: double - - override this.Equals(obj) = - match obj with - | :? Complex as c when c = this -> true - | _ -> false - - override this.GetHashCode() = - (this.re, this.im).GetHashCode() - - override this.ToString() = - $"({this.re}, {this.im})" - - static member op_Equality (x: Complex, y: Complex) = - x.re = y.re && x.im = y.im - - static member op_Inequality (x: Complex, y: Complex) = - x = y |> not - -let mutable cmplx1 = Complex() -let mutable cmplx2 = Complex() - -cmplx1.re <- 4.0 -cmplx1.im <- 1.0 - -cmplx2.re <- 2.0 -cmplx2.im <- 1.0 - -printfn $"{cmplx1} <> {cmplx2}: {cmplx1 <> cmplx2}" -printfn $"{cmplx1} = {cmplx2}: {cmplx1.Equals cmplx2}" - -cmplx2.re <- 4.0 - -printfn $"{cmplx1} = {cmplx2}: {cmplx1 = cmplx2}" -printfn $"{cmplx1} = {cmplx2}: {cmplx1.Equals cmplx2}" - -// The example displays the following output: -// (4, 1) <> (2, 1): True -// (4, 1) = (2, 1): False -// (4, 1) = (4, 1): True -// (4, 1) = (4, 1): True -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/Equals/equals_ref.fs b/snippets/fsharp/System/Object/Equals/equals_ref.fs deleted file mode 100644 index 230ddffa411..00000000000 --- a/snippets/fsharp/System/Object/Equals/equals_ref.fs +++ /dev/null @@ -1,27 +0,0 @@ -module equals_ref - -// -// Define a reference type that does not override Equals. -type Person(name) = - override _.ToString() = - name - -let person1a = Person "John" -let person1b = person1a -let person2 = Person(string person1a) - -printfn "Calling Equals:" -printfn $"person1a and person1b: {person1a.Equals person1b}" -printfn $"person1a and person2: {person1a.Equals person2}" - -printfn "\nCasting to an Object and calling Equals:" -printfn $"person1a and person1b: {(person1a :> obj).Equals(person1b :> obj)}" -printfn $"person1a and person2: {(person1a :> obj).Equals(person2 :> obj)}" -// The example displays the following output: -// person1a and person1b: True -// person1a and person2: False -// -// Casting to an Object and calling Equals: -// person1a and person1b: True -// person1a and person2: False -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/Equals/equals_val1.fs b/snippets/fsharp/System/Object/Equals/equals_val1.fs deleted file mode 100644 index 1a3807394a7..00000000000 --- a/snippets/fsharp/System/Object/Equals/equals_val1.fs +++ /dev/null @@ -1,14 +0,0 @@ -module equals_val1 - -// -let value1 = 12uy -let value2 = 12 - -let object1 = value1 :> obj -let object2 = value2 :> obj - -printfn $"{object1} ({object1.GetType().Name}) = {object2} ({object2.GetType().Name}): {object1.Equals object2}" - -// The example displays the following output: -// 12 (Byte) = 12 (Int32): False -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/Equals/equals_val2.fs b/snippets/fsharp/System/Object/Equals/equals_val2.fs deleted file mode 100644 index c41c65f0bb0..00000000000 --- a/snippets/fsharp/System/Object/Equals/equals_val2.fs +++ /dev/null @@ -1,24 +0,0 @@ -module equals_val2 - -// -// Define a value type that does not override Equals. -[] -type Person(personName: string) = - override _.ToString() = - personName - -let person1 = Person "John" -let person2 = Person "John" - -printfn "Calling Equals:" -printfn $"{person1.Equals person2}" - -printfn $"\nCasting to an Object and calling Equals:" -printfn $"{(person1 :> obj).Equals(person2 :> obj)}" -// The example displays the following output: -// Calling Equals: -// True -// -// Casting to an Object and calling Equals: -// True -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/Equals/equalsoverride.fs b/snippets/fsharp/System/Object/Equals/equalsoverride.fs deleted file mode 100644 index bf1d13a6fa8..00000000000 --- a/snippets/fsharp/System/Object/Equals/equalsoverride.fs +++ /dev/null @@ -1,27 +0,0 @@ -module equalsoverride - -// -open System - -type Person(name, id) = - member _.Name = name - member _.Id = id - - override _.Equals(obj) = - match obj with - | :? Person as personObj -> - id.Equals personObj.Id - | _ -> - false - - override _.GetHashCode() = - id.GetHashCode() - -let p1 = Person("John", "63412895") -let p2 = Person("Jack", "63412895") -printfn $"{p1.Equals p2}" -printfn $"{Object.Equals(p1, p2)}" -// The example displays the following output: -// True -// True -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/Equals/equalssb1.fs b/snippets/fsharp/System/Object/Equals/equalssb1.fs deleted file mode 100644 index 632f5045d98..00000000000 --- a/snippets/fsharp/System/Object/Equals/equalssb1.fs +++ /dev/null @@ -1,23 +0,0 @@ -module equalssb1 - -// -open System -open System.Text - -let sb1 = StringBuilder "building a string..." -let sb2 = StringBuilder "building a string..." - -printfn $"sb1.Equals(sb2): {sb1.Equals sb2}" -printfn $"((Object) sb1).Equals(sb2): {(sb1 :> obj).Equals sb2}" - -printfn $"Object.Equals(sb1, sb2): {Object.Equals(sb1, sb2)}" - -let sb3 = StringBuilder "building a string..." -printfn $"\nsb3.Equals(sb2): {sb3.Equals sb2}" -// The example displays the following output: -// sb1.Equals(sb2): True -// ((Object) sb1).Equals(sb2): False -// Object.Equals(sb1, sb2): False -// -// sb3.Equals(sb2): False -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/Finalize/finalize_safe.fs b/snippets/fsharp/System/Object/Finalize/finalize_safe.fs deleted file mode 100644 index 748b9a94823..00000000000 --- a/snippets/fsharp/System/Object/Finalize/finalize_safe.fs +++ /dev/null @@ -1,123 +0,0 @@ -module finalize_safe - -// -open Microsoft.Win32.SafeHandles -open System -open System.ComponentModel -open System.IO -open System.Runtime.InteropServices - -// Windows API constants. -let HKEY_CLASSES_ROOT = 0x80000000 -let ERROR_SUCCESS = 0 -let KEY_QUERY_VALUE = 1 -let KEY_SET_VALUE = 0x2 -let REG_SZ = 1u -let MAX_PATH = 260 - -// Windows API calls. -[] -extern int RegOpenKeyEx(nativeint hKey, string lpSubKey, int ulOptions, int samDesired, nativeint& phkResult) -[] -extern int RegQueryValueEx(nativeint hKey, string lpValueName, int lpReserved, uint& lpType, string lpData, uint& lpcbData) -[] -extern int RegSetValueEx(nativeint hKey, [] string lpValueName, int Reserved, uint dwType, [] string lpData, int cpData) -[] -extern int RegCloseKey(unativeint hKey) - -type FileAssociationInfo(fileExtension: string) = - // Private values. - let ext = - if fileExtension.StartsWith "." |> not then - "." + fileExtension - else - fileExtension - let mutable args = "" - let mutable hAppIdHandle = Unchecked.defaultof - let mutable hExtHandle = Unchecked.defaultof - let openCmd = - let mutable lpType = 0u - let mutable hExtension = 0n - // Get the file extension value. - let retVal = RegOpenKeyEx(nativeint HKEY_CLASSES_ROOT, fileExtension, 0, KEY_QUERY_VALUE, &hExtension) - if retVal <> ERROR_SUCCESS then - raise (Win32Exception retVal) - // Instantiate the first SafeRegistryHandle. - hExtHandle <- new SafeRegistryHandle(hExtension, true) - - let appId = String(' ', MAX_PATH) - let mutable appIdLength = uint appId.Length - let retVal = RegQueryValueEx(hExtHandle.DangerousGetHandle(), String.Empty, 0, &lpType, appId, &appIdLength) - if retVal <> ERROR_SUCCESS then - raise (Win32Exception retVal) - // We no longer need the hExtension handle. - hExtHandle.Dispose() - - // Determine the number of characters without the terminating null. - let appId = appId.Substring(0, int appIdLength / 2 - 1) + @"\shell\open\Command" - - // Open the application identifier key. - let exeName = String(' ', MAX_PATH) - let exeNameLength = uint exeName.Length - let mutable hAppId = 0n - let retVal = RegOpenKeyEx(nativeint HKEY_CLASSES_ROOT, appId, 0, KEY_QUERY_VALUE ||| KEY_SET_VALUE, &hAppId) - if retVal <> ERROR_SUCCESS then - raise (Win32Exception retVal) - - // Instantiate the second SafeRegistryHandle. - hAppIdHandle <- new SafeRegistryHandle(hAppId, true) - - // Get the executable name for this file type. - let exePath = String(' ', MAX_PATH) - let mutable exePathLength = uint exePath.Length - let retVal = RegQueryValueEx(hAppIdHandle.DangerousGetHandle(), String.Empty, 0, &lpType, exePath, &exePathLength) - if retVal <> ERROR_SUCCESS then - raise (Win32Exception retVal) - - // Determine the number of characters without the terminating null. - let exePath = - exePath.Substring(0, int exePathLength / 2 - 1) - // Remove any environment strings. - |> Environment.ExpandEnvironmentVariables - - let position = exePath.IndexOf '%' - if position >= 0 then - args <- exePath.Substring position - // Remove command line parameters ('%0', etc.). - exePath.Substring(0, position).Trim() - else - exePath - - member _.Extension = - ext - - member _.Open - with get () = openCmd - and set (value) = - if hAppIdHandle.IsInvalid || hAppIdHandle.IsClosed then - raise (InvalidOperationException "Cannot write to registry key.") - if not (File.Exists value) then - raise (FileNotFoundException $"'{value}' does not exist") - - let cmd = value + " %1" - let retVal = RegSetValueEx(hAppIdHandle.DangerousGetHandle(), String.Empty, 0, REG_SZ, value, value.Length + 1) - if retVal <> ERROR_SUCCESS then - raise (Win32Exception retVal) - - member this.Dispose() = - this.Dispose true - GC.SuppressFinalize this - - member _.Dispose(disposing) = - // Ordinarily, we release unmanaged resources here - // but all are wrapped by safe handles. - - // Release disposable objects. - if disposing then - if hExtHandle <> null then hExtHandle.Dispose() - if hAppIdHandle <> null then hAppIdHandle.Dispose() - - interface IDisposable with - member this.Dispose() = - this.Dispose() -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/GetHashCode/direct1.fs b/snippets/fsharp/System/Object/GetHashCode/direct1.fs deleted file mode 100644 index 49f21a4c4c2..00000000000 --- a/snippets/fsharp/System/Object/GetHashCode/direct1.fs +++ /dev/null @@ -1,38 +0,0 @@ -module direct1 - -// -open System - -[] -type Number(value: int) = - member _.Value = value - - override _.Equals(obj) = - match obj with - | :? Number as n -> - n.Value = value - | _ -> false - - override _.GetHashCode() = - value - - override _.ToString() = - string value - -let rnd = Random() -for _ = 0 to 9 do - let randomN = rnd.Next(Int32.MinValue, Int32.MaxValue) - let n = Number randomN - printfn $"n = {n,12}, hash code = {n.GetHashCode(),12}" -// The example displays output like the following: -// n = -634398368, hash code = -634398368 -// n = 2136747730, hash code = 2136747730 -// n = -1973417279, hash code = -1973417279 -// n = 1101478715, hash code = 1101478715 -// n = 2078057429, hash code = 2078057429 -// n = -334489950, hash code = -334489950 -// n = -68958230, hash code = -68958230 -// n = -379951485, hash code = -379951485 -// n = -31553685, hash code = -31553685 -// n = 2105429592, hash code = 2105429592 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/GetHashCode/shift1.fs b/snippets/fsharp/System/Object/GetHashCode/shift1.fs deleted file mode 100644 index 76c44fe52a7..00000000000 --- a/snippets/fsharp/System/Object/GetHashCode/shift1.fs +++ /dev/null @@ -1,50 +0,0 @@ -module shift1 - -// -open System - -[] -type Point(x: int, y: int) = - member _.X = x - member _.Y = y - override _.Equals(obj) = - match obj with - | :? Point as p -> - x = p.X && y = p.Y - | _ -> - false - - override this.GetHashCode() = - this.ShiftAndWrap(x.GetHashCode(), 2) ^^^ y.GetHashCode() - - member _.ShiftAndWrap(value, positions) = - let positions = positions &&& 0x1F - - // Save the existing bit pattern, but interpret it as an unsigned integer. - let number = BitConverter.ToUInt32(BitConverter.GetBytes value, 0) - // Preserve the bits to be discarded. - let wrapped = number >>> (32 - positions) - // Shift and wrap the discarded bits. - BitConverter.ToInt32(BitConverter.GetBytes((number <<< positions) ||| wrapped), 0) - -let pt = Point(5, 8) -printfn $"{pt.GetHashCode()}" - -let pt2 = Point(8, 5) -printfn $"{pt2.GetHashCode()}" -// The example displays the following output: -// 28 -// 37 -// - -// -let shiftAndWrap (value: int) positions = - let positions = positions &&& 0x1F - - // Save the existing bit pattern, but interpret it as an unsigned integer. - let number = BitConverter.ToUInt32(BitConverter.GetBytes value, 0) - // Preserve the bits to be discarded. - let wrapped = number >>> (32 - positions) - // Shift and wrap the discarded bits. - BitConverter.ToInt32(BitConverter.GetBytes((number <<< positions) ||| wrapped), 0) -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/GetHashCode/xor1.fs b/snippets/fsharp/System/Object/GetHashCode/xor1.fs deleted file mode 100644 index 98a461d9595..00000000000 --- a/snippets/fsharp/System/Object/GetHashCode/xor1.fs +++ /dev/null @@ -1,28 +0,0 @@ -module xor1 - -// -// A type that represents a 2-D point. -[] -type Point(x: int, y: int) = - member _.X = x - member _.Y = y - - override _.Equals(obj) = - match obj with - | :? Point as p -> - x = p.X && y = p.Y - | _ -> - false - - override _.GetHashCode() = - x ^^^ y - -let pt = Point(5, 8) -printfn $"{pt.GetHashCode()}" - -let pt2 = Point(8, 5) -printfn $"{pt.GetHashCode()}" -// The example displays the following output: -// 13 -// 13 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/GetHashCode/xor2.fs b/snippets/fsharp/System/Object/GetHashCode/xor2.fs deleted file mode 100644 index c83ecf87704..00000000000 --- a/snippets/fsharp/System/Object/GetHashCode/xor2.fs +++ /dev/null @@ -1,27 +0,0 @@ -module xor2 - -// -[] -type Point(x: int, y: int) = - member _.X = x - member _.Y = y - - override _.Equals(obj) = - match obj with - | :? Point as p -> - x = p.X && y = p.Y - | _ -> - false - - override _.GetHashCode() = - (x, y).GetHashCode() - -let pt = Point(5, 8) -printfn $"{pt.GetHashCode()}" - -let pt2 = Point(8, 5) -printfn $"{pt2.GetHashCode()}" -// The example displays the following output: -// 173 -// 269 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/ToString/array1.fs b/snippets/fsharp/System/Object/ToString/array1.fs deleted file mode 100644 index c9ab8a253ba..00000000000 --- a/snippets/fsharp/System/Object/ToString/array1.fs +++ /dev/null @@ -1,13 +0,0 @@ -module array1 - -// -let values = [| 1; 2; 4; 8; 16; 32; 64; 128 |] -printfn $"{values}" - -let list = ResizeArray values -printfn $"{list}" - -// The example displays the following output: -// System.Int32[] -// System.Collections.Generic.List`1[System.Int32] -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/ToString/customize1.fs b/snippets/fsharp/System/Object/ToString/customize1.fs deleted file mode 100644 index 24e73763274..00000000000 --- a/snippets/fsharp/System/Object/ToString/customize1.fs +++ /dev/null @@ -1,25 +0,0 @@ -module customize1 - -// -open System -open System.Collections.Generic - -type CList<'T>() = - inherit ResizeArray<'T>() - - override this.ToString() = - let mutable retVal = String.Empty - for item in this do - if String.IsNullOrEmpty retVal then - retVal <- retVal + string item - else - retVal <- retVal + $", {item}" - retVal - -let list2 = CList() -list2.Add 1000 -list2.Add 2000 -printfn $"{list2}" -// The example displays the following output: -// 1000, 2000 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/ToString/customize2.fs b/snippets/fsharp/System/Object/ToString/customize2.fs deleted file mode 100644 index b84893fde8c..00000000000 --- a/snippets/fsharp/System/Object/ToString/customize2.fs +++ /dev/null @@ -1,32 +0,0 @@ -module customize2 - -// -open System -open System.Collections.Generic - -type List<'T> with - member this.ToString2<'T>() = - let mutable retVal = String.Empty - for item in this do - retVal <- retVal + $"""{if String.IsNullOrEmpty retVal then "" else ", "}{item}""" - if String.IsNullOrEmpty retVal then "{}" else "{ " + retVal + " }" - - member this.ToString<'T>(fmt: string) = - let mutable retVal = String.Empty - for item in this do - match box item with - | :? IFormattable as ifmt -> - retVal <- retVal + $"""{if String.IsNullOrEmpty retVal then "" else ", "}{ifmt.ToString(fmt, null)}""" - | _ -> - retVal <- retVal + this.ToString2() - if String.IsNullOrEmpty retVal then "{}" else "{ " + retVal + " }" - -let list = ResizeArray() -list.Add 1000 -list.Add 2000 -printfn $"{list.ToString2()}" -printfn $"""{list.ToString "N0"}""" -// The example displays the following output: -// { 1000, 2000 } -// { 1,000, 2,000 } -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/ToString/tostring1.fs b/snippets/fsharp/System/Object/ToString/tostring1.fs deleted file mode 100644 index 85ffddd04a5..00000000000 --- a/snippets/fsharp/System/Object/ToString/tostring1.fs +++ /dev/null @@ -1,10 +0,0 @@ -module tostring1 - -// -let obj = obj () -printfn $"{obj.ToString()}" -// printfn $"{obj}" // Equivalent - -// The example displays the following output: -// System.Object -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/ToString/tostring2.fs b/snippets/fsharp/System/Object/ToString/tostring2.fs deleted file mode 100644 index 87dba31ebcf..00000000000 --- a/snippets/fsharp/System/Object/ToString/tostring2.fs +++ /dev/null @@ -1,10 +0,0 @@ -module tostring2 - -// -type Object1() = class end - -let obj1 = Object1() -printfn $"{obj1.ToString()}" -// The example displays the following output: -// Examples.Object1 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/ToString/tostring3.fs b/snippets/fsharp/System/Object/ToString/tostring3.fs deleted file mode 100644 index 28db439aa30..00000000000 --- a/snippets/fsharp/System/Object/ToString/tostring3.fs +++ /dev/null @@ -1,13 +0,0 @@ -module tostring3 - -// -type Object2(value: obj) = - inherit obj () - override _.ToString() = - base.ToString() + ": " + value.ToString() - -let obj2 = Object2 'a' -printfn $"{obj2.ToString()}" -// The example displays the following output: -// Object2: a -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/ToString/tostringoverload1.fs b/snippets/fsharp/System/Object/ToString/tostringoverload1.fs deleted file mode 100644 index 2c0cc99c7da..00000000000 --- a/snippets/fsharp/System/Object/ToString/tostringoverload1.fs +++ /dev/null @@ -1,38 +0,0 @@ -module tostringoverload1 - -// -open System - -type Automobile(model: string, year: int, doors: int, cylinders: string) = - member _.Doors = doors - member _.Model = model - member _.Year = year - member _.Cylinders = cylinders - - override this.ToString() = - this.ToString "G" - - member _.ToString(fmt) = - let fmt = - if String.IsNullOrEmpty fmt then "G" - else fmt.ToUpperInvariant() - - match fmt with - | "G" -> - $"{year} {model}" - | "D" -> - $"{year} {model}, {doors} dr." - | "C" -> - $"{year} {model}, {cylinders}" - | "A" -> - $"{year} {model}, {doors} dr. {cylinders}" - | _ -> - raise (ArgumentException $"'{fmt}' is an invalid format string") - -let auto = Automobile("Lynx", 2016, 4, "V8") -printfn $"{auto}" -printfn $"""{auto.ToString "A"}""" -// The example displays the following output: -// 2016 Lynx -// 2016 Lynx, 4 dr. V8 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Object/ToString/tostringoverload2.fs b/snippets/fsharp/System/Object/ToString/tostringoverload2.fs deleted file mode 100644 index c6e7e3e993a..00000000000 --- a/snippets/fsharp/System/Object/ToString/tostringoverload2.fs +++ /dev/null @@ -1,18 +0,0 @@ -module tostringoverload2 - -// -open System.Globalization - -let cultureNames = - [| "en-US"; "en-GB"; "fr-FR"; "hr-HR"; "ja-JP" |] -let value = 1603.49m -for cultureName in cultureNames do - let culture = CultureInfo cultureName - printfn $"""{culture.Name}: {value.ToString("C2", culture)}""" -// The example displays the following output: -// en-US: $1,603.49 -// en-GB: £1,603.49 -// fr-FR: 1 603,49 € -// hr-HR: 1.603,49 kn -// ja-JP: ¥1,603.49 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Single/CompareTo/compareto2.fs b/snippets/fsharp/System/Single/CompareTo/compareto2.fs deleted file mode 100644 index e097f734ffc..00000000000 --- a/snippets/fsharp/System/Single/CompareTo/compareto2.fs +++ /dev/null @@ -1,13 +0,0 @@ -module compareto2 - -// -let value1 = 16.5457f -let operand = 3.8899982f -let value2 = value1 * operand / operand -printfn $"Comparing {value1} and {value2}: {value1.CompareTo value2}\n" -printfn $"Comparing {value1:R} and {value2:R}: {value1.CompareTo value2}" -// The example displays the following output: -// Comparing 16.5457 and 16.5457: -1 -// -// Comparing 16.5457 and 16.545702: -1 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Single/CompareTo/compareto3.fs b/snippets/fsharp/System/Single/CompareTo/compareto3.fs deleted file mode 100644 index d541c895f14..00000000000 --- a/snippets/fsharp/System/Single/CompareTo/compareto3.fs +++ /dev/null @@ -1,13 +0,0 @@ -module compareto3 - -// -let value1 = 16.5457f -let operand = 3.8899982f -let value2 = box (value1 * operand / operand) -printfn $"Comparing {value1} and {value2}: {value1.CompareTo value2}\n" -printfn $"Comparing {value1:R} and {value2:R}: {value1.CompareTo value2}" -// The example displays the following output: -// Comparing 16.5457 and 16.5457: -1 -// -// Comparing 16.5457 and 16.545702: -1 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Single/Epsilon/epsilon.fs b/snippets/fsharp/System/Single/Epsilon/epsilon.fs deleted file mode 100644 index ef10b674b18..00000000000 --- a/snippets/fsharp/System/Single/Epsilon/epsilon.fs +++ /dev/null @@ -1,17 +0,0 @@ -module epsilon - -// -open System - -let values = [ 0f; Single.Epsilon; Single.Epsilon * 0.5f ] - -for i = 0 to values.Length - 2 do - for i2 = i + 1 to values.Length - 1 do - printfn $"{values[i]:r} = {values[i2]:r}: {values[i].Equals(values[i2])}" - printfn "" -// The example displays the following output: -// 0 = 1.401298E-45: False -// 0 = 0: True -// -// 1.401298E-45 = 0: False -// \ No newline at end of file diff --git a/snippets/fsharp/System/Single/Epsilon/epsilon1.fs b/snippets/fsharp/System/Single/Epsilon/epsilon1.fs deleted file mode 100644 index 71b536519fc..00000000000 --- a/snippets/fsharp/System/Single/Epsilon/epsilon1.fs +++ /dev/null @@ -1,44 +0,0 @@ -module epsilon1 - -// -open System - -let getComponentParts (value: float32) = - let result = $"{value:R}: " - let indent = result.Length - - // Convert the single to a 4-byte array. - let bytes = BitConverter.GetBytes value - let formattedSingle = BitConverter.ToInt32(bytes, 0) - - // Get the sign bit (byte 3, bit 7). - let result = result + $"""Sign: {if formattedSingle >>> 31 <> 0 then "1 (-)" else "0 (+)"}\n""" - - // Get the exponent (byte 2 bit 7 to byte 3, bits 6) - let exponent = (formattedSingle >>> 23) &&& 0x000000FF - let adjustment = if exponent <> 0 then 127 else 126 - let result = result + $"{String(' ', indent)}Exponent: 0x{1:X4} ({exponent - adjustment})\n" - - // Get the significand (bits 0-22) - let significand = - if exponent <> 0 then - (formattedSingle &&& 0x007FFFFF) ||| 0x800000 - else - formattedSingle &&& 0x007FFFFF - - result + $"{String(' ', indent)}Mantissa: 0x{significand:X13}\n" - - -let values = [ 0f; Single.Epsilon ] -for value in values do - printfn $"{getComponentParts value}\n" -// // The example displays the following output: -// 0: Sign: 0 (+) -// Exponent: 0xFFFFFF82 (-126) -// Mantissa: 0x0000000000000 -// -// -// 1.401298E-45: Sign: 0 (+) -// Exponent: 0xFFFFFF82 (-126) -// Mantissa: 0x0000000000001 -// \ No newline at end of file diff --git a/snippets/fsharp/System/Single/Equals/equalsabs1.fs b/snippets/fsharp/System/Single/Equals/equalsabs1.fs deleted file mode 100644 index be7777d1a44..00000000000 --- a/snippets/fsharp/System/Single/Equals/equalsabs1.fs +++ /dev/null @@ -1,27 +0,0 @@ -module equalsabs1 - -// -open System - -let hasMinimalDifference (value1: float32) (value2: float32) units = - let bytes = BitConverter.GetBytes value1 - let iValue1 = BitConverter.ToInt32(bytes, 0) - let bytes = BitConverter.GetBytes(value2) - let iValue2 = BitConverter.ToInt32(bytes, 0) - - // If the signs are different, return false except for +0 and -0. - if (iValue1 >>> 31) <> (iValue2 >>> 31) then - value1 = value2 - else - let diff = abs (iValue1 - iValue2) - diff <= units - -let value1 = 0.1f * 10f -let value2 = - List.replicate 10 0.1f - |> List.sum - -printfn $"{value1:R} = {value2:R}: {hasMinimalDifference value1 value2 1}" -// The example displays the following output: -// 1 = 1.0000001: True -// diff --git a/snippets/fsharp/System/String/.ctor/char2_ctor.fs b/snippets/fsharp/System/String/.ctor/char2_ctor.fs deleted file mode 100644 index 159ab3913a0..00000000000 --- a/snippets/fsharp/System/String/.ctor/char2_ctor.fs +++ /dev/null @@ -1,29 +0,0 @@ -module char2_ctor - -// -#nowarn "9" -open System -open FSharp.NativeInterop - -let characters = - [| 'H'; 'e'; 'l'; 'l'; 'o'; ' ' - 'w'; 'o'; 'r'; 'l'; 'd'; '!'; '\u0000' |] - -[] -let main _ = - use charPtr = fixed characters - let mutable length = 0 - let mutable iterator = charPtr - let mutable broken = false - while not broken && NativePtr.read iterator <> '\u0000' do - if NativePtr.read iterator = '!' || NativePtr.read iterator = '.' then - broken <- true - else - iterator <- NativePtr.add iterator 1 - length <- length + 1 - String(charPtr, 0, length) - |> printfn "%s" - 0 -// The example displays the following output: -// Hello World -// \ No newline at end of file diff --git a/snippets/fsharp/System/String/.ctor/chptrctor_null.fs b/snippets/fsharp/System/String/.ctor/chptrctor_null.fs deleted file mode 100644 index b973bca4ee7..00000000000 --- a/snippets/fsharp/System/String/.ctor/chptrctor_null.fs +++ /dev/null @@ -1,26 +0,0 @@ -module chptrctor_null - -// -#nowarn "9" -open System - -let chars = [| 'a'; 'b'; 'c'; 'd'; '\000'; 'A'; 'B'; 'C'; 'D'; '\000' |] -let s = - use chPtr = fixed chars - String(chPtr, 0, chars.Length) - -for ch in s do - printf $"{uint16 ch:X4} " -printfn "" - -let s2 = - use chPtr = fixed chars - String chPtr - -for ch in s2 do - printf $"{uint16 ch:X4} " -printfn "" -// The example displays the following output: -// 0061 0062 0063 0064 0000 0041 0042 0043 0044 0000 -// 0061 0062 0063 0064 -// \ No newline at end of file diff --git a/snippets/fsharp/System/String/.ctor/ctor1.fs b/snippets/fsharp/System/String/.ctor/ctor1.fs deleted file mode 100644 index b44b9bb30d6..00000000000 --- a/snippets/fsharp/System/String/.ctor/ctor1.fs +++ /dev/null @@ -1,11 +0,0 @@ -module ctor1 - -// -let value1 = "This is a string." -let value2 = value1 -printfn "%s" value1 -printfn "%s" value2 -// The example displays the following output: -// This is a string. -// This is a string. -// \ No newline at end of file diff --git a/snippets/fsharp/System/String/.ctor/ctor2.fs b/snippets/fsharp/System/String/.ctor/ctor2.fs deleted file mode 100644 index 1042312649a..00000000000 --- a/snippets/fsharp/System/String/.ctor/ctor2.fs +++ /dev/null @@ -1,18 +0,0 @@ -module ctor2 - -// -#nowarn "9" -open System - -let characters = - [| 'H'; 'e'; 'l'; 'l'; 'o'; ' ' - 'w'; 'o'; 'r'; 'l'; 'd'; '!'; '\u0000' |] - -let value = - use charPtr = fixed characters - String charPtr - -printfn $"{value}" -// The example displays the following output: -// Hello world! -// \ No newline at end of file diff --git a/snippets/fsharp/System/String/.ctor/ptrctor_null.fs b/snippets/fsharp/System/String/.ctor/ptrctor_null.fs deleted file mode 100644 index e3753c593e0..00000000000 --- a/snippets/fsharp/System/String/.ctor/ptrctor_null.fs +++ /dev/null @@ -1,28 +0,0 @@ -module ptrctor_null - -// -#nowarn "9" -open System - -let bytes = - [| 0x61y; 0x62y; 0x063y; 0x064y; 0x00y; 0x41y; 0x42y; 0x43y; 0x44y; 0x00y |] - -let s = - use bytePtr = fixed bytes - String(bytePtr, 0, bytes.Length) - -for ch in s do - printf $"{uint16 ch:X4} " -printfn "" - -let s2 = - use bytePtr = fixed bytes - String bytePtr - -for ch in s do - printf $"{uint16 ch:X4} " -printfn "" -// The example displays the following output: -// 0061 0062 0063 0064 0000 0041 0042 0043 0044 0000 -// 0061 0062 0063 0064 -// \ No newline at end of file diff --git a/snippets/fsharp/System/String/.ctor/source.fs b/snippets/fsharp/System/String/.ctor/source.fs deleted file mode 100644 index 017dbeeaaba..00000000000 --- a/snippets/fsharp/System/String/.ctor/source.fs +++ /dev/null @@ -1,70 +0,0 @@ -module source - -open System -open System.Text - -do -// - // Unicode Mathematical operators - let charArr1 = [| '\u2200'; '\u2202'; '\u200F'; '\u2205' |] - let szMathSymbols = String charArr1 - - // Unicode Letterlike Symbols - let charArr2 = [| '\u2111'; '\u2118'; '\u2122'; '\u2126' |] - let szLetterLike = String charArr2 - - // Compare Strings - the result is false - printfn $"The Strings are equal? %b{String.Compare(szMathSymbols, szLetterLike) = 0}" -// -// - // Null terminated ASCII characters in an sbyte array - let szAsciiUpper = - let sbArr1 = [| 0x41y; 0x42y; 0x43y; 0x00y |] - // Instruct the Garbage Collector not to move the memory - use pAsciiUpper = fixed sbArr1 - String pAsciiUpper - - let szAsciiLower = - let sbArr2 = [| 0x61y; 0x62y; 0x63y; 0x00y |] - // Instruct the Garbage Collector not to move the memory - use pAsciiLower = fixed sbArr2 - String(pAsciiLower, 0, sbArr2.Length) - - // Prints "ABC abc" - printfn $"{szAsciiUpper} {szAsciiLower}" - - // Compare Strings - the result is true - printfn $"The Strings are equal when capitalized ? %b{String.Compare(szAsciiUpper.ToUpper(), szAsciiLower.ToUpper()) = 0}" - - // This is the effective equivalent of another Compare method, which ignores case - printfn $"The Strings are equal when capitalized ? %b{String.Compare(szAsciiUpper, szAsciiLower, true) = 0}" -// -// - // Create a Unicode String with 5 Greek Alpha characters - let szGreekAlpha = String('\u0391',5) - // Create a Unicode String with a Greek Omega character - let szGreekOmega = String([| '\u03A9'; '\u03A9'; '\u03A9' |],2,1) - - let szGreekLetters = String.Concat(szGreekOmega, szGreekAlpha, szGreekOmega.Clone()) - - // Examine the result - printfn $"{szGreekLetters}" - - // The first index of Alpha - let ialpha = szGreekLetters.IndexOf '\u0391' - // The last index of Omega - let iomega = szGreekLetters.LastIndexOf '\u03A9' - - printfn $"The Greek letter Alpha first appears at index {ialpha} and Omega last appears at index {iomega} in this String." -// - -// - let utfeightstring = - let asciiChars = [| 0x51y; 0x52y; 0x53y; 0x54y; 0x54y; 0x56y |] - let encoding = UTF8Encoding(true, true) - - // Instruct the Garbage Collector not to move the memory - use pAsciiChars = fixed asciiChars - String(pAsciiChars,0,asciiChars.Length,encoding) - printfn $"The UTF8 String is {utfeightstring}" // prints "QRSTTV" -// \ No newline at end of file diff --git a/snippets/fsharp/System/String/Format/Example1.fs b/snippets/fsharp/System/String/Format/Example1.fs deleted file mode 100644 index 6f76849429c..00000000000 --- a/snippets/fsharp/System/String/Format/Example1.fs +++ /dev/null @@ -1,19 +0,0 @@ -module Example1 - -// -open System - -let values= [| Int16.MinValue; -27s; 0s; 1042s; Int16.MaxValue |] -printfn "%10s %10s\n" "Decimal" "Hex" -for value in values do - String.Format("{0,10:G}: {0,10:X}", value) - |> printfn "%s" -// The example displays the following output: -// Decimal Hex -// -// -32768: 8000 -// -27: FFE5 -// 0: 0 -// 1042: 412 -// 32767: 7FFF -// \ No newline at end of file diff --git a/snippets/fsharp/System/String/Intern/Intern1.fs b/snippets/fsharp/System/String/Intern/Intern1.fs deleted file mode 100644 index 8443ea61d61..00000000000 --- a/snippets/fsharp/System/String/Intern/Intern1.fs +++ /dev/null @@ -1,11 +0,0 @@ -module Intern1.fs -open System -open System.Text - -// -let s1 = "MyTest" -let s2 = StringBuilder().Append("My").Append("Test").ToString() -let s3 = String.Intern s2 -printfn $"{s2 :> obj = s1 :> obj}" // Different references. -printfn $"{s3 :> obj = s1 :> obj}" // The same reference. -// diff --git a/snippets/fsharp/System/String/Intern/Intern2.fs b/snippets/fsharp/System/String/Intern/Intern2.fs deleted file mode 100644 index 863f3dde291..00000000000 --- a/snippets/fsharp/System/String/Intern/Intern2.fs +++ /dev/null @@ -1,16 +0,0 @@ -module Intern2.fs -open System -open System.Text - -// -let str1 = String.Empty -let str2 = String.Empty - -let sb = StringBuilder().Append String.Empty -let str3 = String.Intern(string sb) - -if (str1 :> obj) = (str3 :> obj) then - printfn "The strings are equal." -else - printfn "The strings are not equal." -// diff --git a/snippets/fsharp/System/String/IsNullOrEmpty/NullString1.fs b/snippets/fsharp/System/String/IsNullOrEmpty/NullString1.fs deleted file mode 100644 index 21f1ee3462c..00000000000 --- a/snippets/fsharp/System/String/IsNullOrEmpty/NullString1.fs +++ /dev/null @@ -1,19 +0,0 @@ -namespace IsNullOrEmpty -open System - -module NullString1 = - - // - let (s: string) = null - - printfn "The value of the string is '%s'" s - - try - printfn "String length is %d" s.Length - with - | :? NullReferenceException as ex -> printfn "%s" ex.Message - - // The example displays the following output: - // The value of the string is '' - // Object reference not set to an instance of an object. - // diff --git a/snippets/fsharp/System/String/IsNullOrEmpty/NullString2.fs b/snippets/fsharp/System/String/IsNullOrEmpty/NullString2.fs deleted file mode 100644 index d8c8fad9c8c..00000000000 --- a/snippets/fsharp/System/String/IsNullOrEmpty/NullString2.fs +++ /dev/null @@ -1,12 +0,0 @@ -namespace IsNullOrEmpty -open System - -module NullString2 = - - // - let s = "" - printfn "The length of '%s' is %d." s s.Length - - // The example displays the following output: - // The length of '' is 0. - // diff --git a/snippets/fsharp/System/String/IsNullOrEmpty/isnullorempty1.fs b/snippets/fsharp/System/String/IsNullOrEmpty/isnullorempty1.fs deleted file mode 100644 index 7f4e29126fe..00000000000 --- a/snippets/fsharp/System/String/IsNullOrEmpty/isnullorempty1.fs +++ /dev/null @@ -1,19 +0,0 @@ -namespace IsNullOrEmpty -open System - -module IsNullOrEmpty1 = - - // - let testForNullOrEmpty (s: string): bool = - s = null || s = String.Empty - - let s1 = null - let s2 = "" - - printfn "%b" (testForNullOrEmpty s1) - printfn "%b" (testForNullOrEmpty s2) - - // The example displays the following output: - // true - // true - // diff --git a/snippets/fsharp/System/TimeSpan/Parse/parsefailure1.fs b/snippets/fsharp/System/TimeSpan/Parse/parsefailure1.fs deleted file mode 100644 index 54ff371765d..00000000000 --- a/snippets/fsharp/System/TimeSpan/Parse/parsefailure1.fs +++ /dev/null @@ -1,23 +0,0 @@ -module parsefailure1 - -// -open System - -let values = [| "000000006"; "12.12:12:12.12345678" |] -for value in values do - try - let interval = TimeSpan.Parse value - printfn $"{value} --> {interval}" - with - | :? FormatException -> - printfn $"{value}: Bad Format" - | :? OverflowException -> - printfn $"{value}: Overflow" - -// Output from .NET Framework 3.5 and earlier versions: -// 000000006 --> 6.00:00:00 -// 12.12:12:12.12345678: Bad Format -// Output from .NET Framework 4 and later versions or .NET Core: -// 000000006: Overflow -// 12.12:12:12.12345678: Overflow -// \ No newline at end of file diff --git a/snippets/fsharp/System/TimeSpan/TryParse/tryparsefailure1.fs b/snippets/fsharp/System/TimeSpan/TryParse/tryparsefailure1.fs deleted file mode 100644 index 8072ecefe27..00000000000 --- a/snippets/fsharp/System/TimeSpan/TryParse/tryparsefailure1.fs +++ /dev/null @@ -1,17 +0,0 @@ -module tryparsefailure - -open System - -// -let value = "000000006" -match TimeSpan.TryParse value with -| true, interval -> - printfn $"{value} --> {interval}" -| _ -> - printfn $"Unable to parse '{value}'" - -// Output from .NET Framework 3.5 and earlier versions: -// 000000006 --> 6.00:00:00 -// Output from .NET Framework 4: -// Unable to parse //000000006// -// \ No newline at end of file diff --git a/snippets/fsharp/System/Type/GetType/source.fs b/snippets/fsharp/System/Type/GetType/source.fs deleted file mode 100644 index 9ec4c202801..00000000000 --- a/snippets/fsharp/System/Type/GetType/source.fs +++ /dev/null @@ -1,37 +0,0 @@ -module source - -open System -open System.Reflection - -do - let test = "System.Collections.Generic.Dictionary`2[System.String,[MyNamespace.MyType, MyAssembly]]" - // - let t = - Type.GetType(test, - (fun aName -> - if aName.Name = "MyAssembly" then - Assembly.LoadFrom @".\MyPath\v5.0\MyAssembly.dll" - else null), - fun assem name ignr -> - if assem = null then - Type.GetType(name, false, ignr) - else - assem.GetType(name, false, ignr)) - // - printfn $"{t}" - - let test = "System.Collections.Generic.Dictionary`2[[YourNamespace.YourType, YourAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null], [MyNamespace.MyType, MyAssembly]]" - // - let t2 = - Type.GetType(test, - (fun aName -> - if aName.Name = "MyAssembly" then - Assembly.LoadFrom @".\MyPath\v5.0\MyAssembly.dll" - else Assembly.Load aName), - (fun assem name ignr -> - if assem = null then - Type.GetType(name, false, ignr) - else - assem.GetType(name, false, ignr)), true) - // - printfn $"{t2}" diff --git a/snippets/fsharp/System/Type/MakeGenericType/remarks.fs b/snippets/fsharp/System/Type/MakeGenericType/remarks.fs deleted file mode 100644 index bece475149a..00000000000 --- a/snippets/fsharp/System/Type/MakeGenericType/remarks.fs +++ /dev/null @@ -1,5 +0,0 @@ -module remarks -// -type Base<'T, 'U>() = class end -type Derived<'V>() = inherit Base() -// diff --git a/snippets/fsharp/VS_Snippets_CLR_System/system.datetime.frombinary/fs/frombinary1.fs b/snippets/fsharp/VS_Snippets_CLR_System/system.datetime.frombinary/fs/frombinary1.fs deleted file mode 100644 index 2a6c752eda8..00000000000 --- a/snippets/fsharp/VS_Snippets_CLR_System/system.datetime.frombinary/fs/frombinary1.fs +++ /dev/null @@ -1,15 +0,0 @@ -// -open System - -let localDate = DateTime(2010, 3, 14, 2, 30, 0, DateTimeKind.Local) -let binLocal = localDate.ToBinary() -if TimeZoneInfo.Local.IsInvalidTime localDate then - printfn $"{localDate} is an invalid time in the {TimeZoneInfo.Local.StandardName} zone." - -let localDate2 = DateTime.FromBinary binLocal -printfn $"{localDate} = {localDate2}: {localDate.Equals localDate2}" - -// The example displays the following output: -// 3/14/2010 2:30:00 AM is an invalid time in the Pacific Standard Time zone. -// 3/14/2010 2:30:00 AM = 3/14/2010 3:30:00 AM: False -// \ No newline at end of file diff --git a/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM/VB/openClosedOver.vb b/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM/VB/openClosedOver.vb deleted file mode 100644 index 693d86e5070..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM/VB/openClosedOver.vb +++ /dev/null @@ -1,137 +0,0 @@ -' All four permutations of instance/Shared with open/closed. -' -' -Imports System.Reflection -Imports System.Security.Permissions - -' Declare three delegate types for demonstrating the combinations -' of Shared versus instance methods and open versus closed -' delegates. -' -Public Delegate Sub D1(ByVal c As C, ByVal s As String) -Public Delegate Sub D2(ByVal s As String) -Public Delegate Sub D3() - -' A sample class with an instance method and a Shared method. -' -Public Class C - Private id As Integer - Public Sub New(ByVal id As Integer) - Me.id = id - End Sub - - Public Sub M1(ByVal s As String) - Console.WriteLine("Instance method M1 on C: id = {0}, s = {1}", _ - Me.id, s) - End Sub - - Public Shared Sub M2(ByVal s As String) - Console.WriteLine("Shared method M2 on C: s = {0}", s) - End Sub -End Class - -Public Class Example - - Public Shared Sub Main() - - Dim c1 As New C(42) - - ' Get a MethodInfo for each method. - ' - Dim mi1 As MethodInfo = GetType(C).GetMethod("M1", _ - BindingFlags.Public Or BindingFlags.Instance) - Dim mi2 As MethodInfo = GetType(C).GetMethod("M2", _ - BindingFlags.Public Or BindingFlags.Static) - - Dim d1 As D1 - Dim d2 As D2 - Dim d3 As D3 - - - Console.WriteLine(vbLf & "An instance method closed over C.") - ' In this case, the delegate and the - ' method must have the same list of argument types; use - ' delegate type D2 with instance method M1. - ' - Dim test As [Delegate] = _ - [Delegate].CreateDelegate(GetType(D2), c1, mi1, False) - - ' Because False was specified for throwOnBindFailure - ' in the call to CreateDelegate, the variable 'test' - ' contains Nothing if the method fails to bind (for - ' example, if mi1 happened to represent a method of - ' some class other than C). - ' - If test IsNot Nothing Then - d2 = CType(test, D2) - - ' The same instance of C is used every time the - ' delegate is invoked. - d2("Hello, World!") - d2("Hi, Mom!") - End If - - - Console.WriteLine(vbLf & "An open instance method.") - ' In this case, the delegate has one more - ' argument than the instance method; this argument comes - ' at the beginning, and represents the hidden instance - ' argument of the instance method. Use delegate type D1 - ' with instance method M1. - ' - d1 = CType([Delegate].CreateDelegate(GetType(D1), Nothing, mi1), D1) - - ' An instance of C must be passed in each time the - ' delegate is invoked. - ' - d1(c1, "Hello, World!") - d1(New C(5280), "Hi, Mom!") - - - Console.WriteLine(vbLf & "An open Shared method.") - ' In this case, the delegate and the method must - ' have the same list of argument types; use delegate type - ' D2 with Shared method M2. - ' - d2 = CType([Delegate].CreateDelegate(GetType(D2), Nothing, mi2), D2) - - ' No instances of C are involved, because this is a Shared - ' method. - ' - d2("Hello, World!") - d2("Hi, Mom!") - - - Console.WriteLine(vbLf & "A Shared method closed over the first argument (String).") - ' The delegate must omit the first argument of the method. - ' A string is passed as the firstArgument parameter, and - ' the delegate is bound to this string. Use delegate type - ' D3 with Shared method M2. - ' - d3 = CType([Delegate].CreateDelegate(GetType(D3), "Hello, World!", mi2), D3) - - ' Each time the delegate is invoked, the same string is - ' used. - d3() - - End Sub -End Class - -' This code example produces the following output: -' -'An instance method closed over C. -'Instance method M1 on C: id = 42, s = Hello, World! -'Instance method M1 on C: id = 42, s = Hi, Mom! -' -'An open instance method. -'Instance method M1 on C: id = 42, s = Hello, World! -'Instance method M1 on C: id = 5280, s = Hi, Mom! -' -'An open Shared method. -'Shared method M2 on C: s = Hello, World! -'Shared method M2 on C: s = Hi, Mom! -' -'A Shared method closed over the first argument (String). -'Shared method M2 on C: s = Hello, World! -' -' \ No newline at end of file diff --git a/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM_2/vb/source.vb b/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM_2/vb/source.vb deleted file mode 100644 index 659ae94b293..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM_2/vb/source.vb +++ /dev/null @@ -1,164 +0,0 @@ -' Showing all the things D(A) can bind to. -' -' -Imports System.Reflection -Imports System.Security.Permissions - -' Declare a delegate type. The object of this code example -' is to show all the methods this delegate can bind to. -' -Public Delegate Sub D(ByVal c As C) - -' Declare two sample classes, C and F. Class C has an ID -' property so instances can be identified. -' -Public Class C - - Private _id As Integer - - Public ReadOnly Property ID() As Integer - Get - Return _id - End Get - End Property - - Public Sub New(ByVal newId As Integer) - Me._id = newId - End Sub - - Public Sub M1(ByVal c As C) - Console.WriteLine("Instance method M1(c As C) on C: this.id = {0}, c.ID = {1}", _ - Me.id, c.ID) - End Sub - - Public Sub M2() - Console.WriteLine("Instance method M2() on C: this.id = {0}", Me.id) - End Sub - - Public Shared Sub M3(ByVal c As C) - Console.WriteLine("Shared method M3(c As C) on C: c.ID = {0}", c.ID) - End Sub - - Public Shared Sub M4(ByVal c1 As C, ByVal c2 As C) - Console.WriteLine("Shared method M4(c1 As C, c2 As C) on C: c1.ID = {0}, c2.ID = {1}", _ - c1.ID, c2.ID) - End Sub -End Class - - -Public Class F - - Public Sub M1(ByVal c As C) - Console.WriteLine("Instance method M1(c As C) on F: c.ID = {0}", c.ID) - End Sub - - Public Shared Sub M3(ByVal c As C) - Console.WriteLine("Shared method M3(c As C) on F: c.ID = {0}", c.ID) - End Sub - - Public Shared Sub M4(ByVal f As F, ByVal c As C) - Console.WriteLine("Shared method M4(f As F, c As C) on F: c.ID = {0}", c.ID) - End Sub -End Class - -Public Class Example - - Public Shared Sub Main() - - Dim c1 As New C(42) - Dim c2 As New C(1491) - Dim f1 As New F() - - Dim d As D - - ' Instance method with one argument of type C. - Dim cmi1 As MethodInfo = GetType(C).GetMethod("M1") - ' Instance method with no arguments. - Dim cmi2 As MethodInfo = GetType(C).GetMethod("M2") - ' Shared method with one argument of type C. - Dim cmi3 As MethodInfo = GetType(C).GetMethod("M3") - ' Shared method with two arguments of type C. - Dim cmi4 As MethodInfo = GetType(C).GetMethod("M4") - - ' Instance method with one argument of type C. - Dim fmi1 As MethodInfo = GetType(F).GetMethod("M1") - ' Shared method with one argument of type C. - Dim fmi3 As MethodInfo = GetType(F).GetMethod("M3") - ' Shared method with an argument of type F and an - ' argument of type C. - Dim fmi4 As MethodInfo = GetType(F).GetMethod("M4") - - Console.WriteLine(vbLf & "An instance method on any type, with an argument of type C.") - ' D can represent any instance method that exactly matches its - ' signature. Methods on C and F are shown here. - ' - d = CType([Delegate].CreateDelegate(GetType(D), c1, cmi1), D) - d(c2) - d = CType([Delegate].CreateDelegate(GetType(D), f1, fmi1), D) - d(c2) - - Console.WriteLine(vbLf & "An instance method on C with no arguments.") - ' D can represent an instance method on C that has no arguments; - ' in this case, the argument of D represents the hidden first - ' argument of any instance method. The delegate acts like a - ' Shared method, and an instance of C must be passed each time - ' it is invoked. - ' - d = CType([Delegate].CreateDelegate(GetType(D), Nothing, cmi2), D) - d(c1) - - Console.WriteLine(vbLf & "A Shared method on any type, with an argument of type C.") - ' D can represent any Shared method with the same signature. - ' Methods on F and C are shown here. - ' - d = CType([Delegate].CreateDelegate(GetType(D), Nothing, cmi3), D) - d(c1) - d = CType([Delegate].CreateDelegate(GetType(D), Nothing, fmi3), D) - d(c1) - - Console.WriteLine(vbLf & "A Shared method on any type, with an argument of") - Console.WriteLine(" that type and an argument of type C.") - ' D can represent any Shared method with one argument of the - ' type the method belongs and a second argument of type C. - ' In this case, the method is closed over the instance of - ' supplied for the its first argument, and acts like an instance - ' method. Methods on F and C are shown here. - ' - d = CType([Delegate].CreateDelegate(GetType(D), c1, cmi4), D) - d(c2) - Dim test As [Delegate] = _ - [Delegate].CreateDelegate(GetType(D), f1, fmi4, false) - - ' This final example specifies False for throwOnBindFailure - ' in the call to CreateDelegate, so the variable 'test' - ' contains Nothing if the method fails to bind (for - ' example, if fmi4 happened to represent a method of - ' some class other than F). - ' - If test IsNot Nothing Then - d = CType(test, D) - d(c2) - End If - - End Sub -End Class - -' This code example produces the following output: -' -'An instance method on any type, with an argument of type C. -'Instance method M1(c As C) on C: this.id = 42, c.ID = 1491 -'Instance method M1(c As C) on F: c.ID = 1491 -' -'An instance method on C with no arguments. -'Instance method M2() on C: this.id = 42 -' -'A Shared method on any type, with an argument of type C. -'Shared method M3(c As C) on C: c.ID = 42 -'Shared method M3(c As C) on F: c.ID = 42 -' -'A Shared method on any type, with an argument of -' that type and an argument of type C. -'Shared method M4(c1 As C, c2 As C) on C: c1.ID = 42, c2.ID = 1491 -'Shared method M4(f As F, c As C) on F: c.ID = 1491 -' -' \ No newline at end of file diff --git a/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/vb/source.vb b/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/vb/source.vb deleted file mode 100644 index 9964550f1d3..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/vb/source.vb +++ /dev/null @@ -1,63 +0,0 @@ -' -Imports System.Reflection - -' Define two classes to use in the demonstration, a base class and -' a class that derives from it. -' -Public Class Base -End Class - -Public Class Derived - Inherits Base - - ' Define a Shared method to use in the demonstration. The method - ' takes an instance of Base and returns an instance of Derived. - ' For the purposes of the demonstration, it is not necessary for - ' the method to do anything useful. - ' - Public Shared Function MyMethod(ByVal arg As Base) As Derived - Dim dummy As Base = arg - Return New Derived() - End Function - -End Class - -' Define a delegate that takes an instance of Derived and returns an -' instance of Base. -' -Public Delegate Function Example(ByVal arg As Derived) As Base - -Module Test - - Sub Main() - - ' The binding flags needed to retrieve MyMethod. - Dim flags As BindingFlags = _ - BindingFlags.Public Or BindingFlags.Static - - ' Get a MethodInfo that represents MyMethod. - Dim minfo As MethodInfo = _ - GetType(Derived).GetMethod("MyMethod", flags) - - ' Demonstrate contravariance of parameter types and covariance - ' of return types by using the delegate Example to represent - ' MyMethod. The delegate binds to the method because the - ' parameter of the delegate is more restrictive than the - ' parameter of the method (that is, the delegate accepts an - ' instance of Derived, which can always be safely passed to - ' a parameter of type Base), and the return type of MyMethod - ' is more restrictive than the return type of Example (that - ' is, the method returns an instance of Derived, which can - ' always be safely cast to type Base). - ' - Dim ex As Example = CType( _ - [Delegate].CreateDelegate(GetType(Example), minfo), _ - Example _ - ) - - ' Execute MyMethod using the delegate Example. - ' - Dim b As Base = ex(New Derived()) - End Sub -End Module -' diff --git a/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals2/VB/equals2.vb b/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals2/VB/equals2.vb deleted file mode 100644 index 168d44b8de2..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals2/VB/equals2.vb +++ /dev/null @@ -1,82 +0,0 @@ -' -Class Point - Protected x, y As Integer - - Public Sub New() - Me.x = 0 - Me.y = 0 - End Sub - - Public Sub New(x As Integer, y As Integer) - Me.x = x - Me.y = y - End Sub - - Public Overrides Function Equals(obj As Object) As Boolean - ' Check for null and compare run-time types. - If obj Is Nothing OrElse Not Me.GetType().Equals(obj.GetType()) Then - Return False - Else - Dim p As Point = DirectCast(obj, Point) - Return x = p.x AndAlso y = p.y - End If - End Function - - Public Overrides Function GetHashCode() As Integer - Return (x << 2) XOr y - End Function - - Public Overrides Function ToString() As String - Return String.Format("Point({0}, {1})", x, y) - End Function -End Class - -Class Point3D : Inherits Point - Private z As Integer - - Public Sub New(ByVal x As Integer, ByVal y As Integer, ByVal z As Integer) - MyBase.New(x, y) - Me.z = Z - End Sub - - Public Overrides Function Equals(ByVal obj As Object) As Boolean - Dim pt3 As Point3D = TryCast(obj, Point3D) - If pt3 Is Nothing Then - Return False - Else - Return MyBase.Equals(CType(pt3, Point)) AndAlso z = pt3.Z - End If - End Function - - Public Overrides Function GetHashCode() As Integer - Return (MyBase.GetHashCode() << 2) XOr z - End Function - - Public Overrides Function ToString() As String - Return String.Format("Point({0}, {1}, {2})", x, y, z) - End Function -End Class - -Module Example - Public Sub Main() - Dim point2D As New Point(5, 5) - Dim point3Da As New Point3D(5, 5, 2) - Dim point3Db As New Point3D(5, 5, 2) - Dim point3Dc As New Point3D(5, 5, -1) - - Console.WriteLine("{0} = {1}: {2}", - point2D, point3Da, point2D.Equals(point3Da)) - Console.WriteLine("{0} = {1}: {2}", - point2D, point3Db, point2D.Equals(point3Db)) - Console.WriteLine("{0} = {1}: {2}", - point3Da, point3Db, point3Da.Equals(point3Db)) - Console.WriteLine("{0} = {1}: {2}", - point3Da, point3Dc, point3Da.Equals(point3Dc)) - End Sub -End Module -' The example displays the following output -' Point(5, 5) = Point(5, 5, 2): False -' Point(5, 5) = Point(5, 5, 2): False -' Point(5, 5, 2) = Point(5, 5, 2): True -' Point(5, 5, 2) = Point(5, 5, -1): False -' \ No newline at end of file diff --git a/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals3/VB/equals3.vb b/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals3/VB/equals3.vb deleted file mode 100644 index 3c331248c67..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals3/VB/equals3.vb +++ /dev/null @@ -1,69 +0,0 @@ -' -Class Rectangle - Private a, b As Point - - Public Sub New(ByVal upLeftX As Integer, ByVal upLeftY As Integer, _ - ByVal downRightX As Integer, ByVal downRightY As Integer) - Me.a = New Point(upLeftX, upLeftY) - Me.b = New Point(downRightX, downRightY) - End Sub - - Public Overrides Function Equals(ByVal obj As [Object]) As Boolean - ' Performs an equality check on two rectangles (Point object pairs). - If obj Is Nothing OrElse Not [GetType]().Equals(obj.GetType()) Then - Return False - End If - Dim r As Rectangle = CType(obj, Rectangle) - Return a.Equals(r.a) AndAlso b.Equals(r.b) - End Function - - Public Overrides Function GetHashCode() As Integer - Return Tuple.Create(a, b).GetHashCode() - End Function - - Public Overrides Function ToString() As String - Return String.Format("Rectangle({0}, {1}, {2}, {3})", - a.x, a.y, b.x, b.y) - End Function -End Class - -Class Point - Friend x As Integer - Friend y As Integer - - Public Sub New(ByVal X As Integer, ByVal Y As Integer) - Me.x = X - Me.y = Y - End Sub - - Public Overrides Function Equals(ByVal obj As [Object]) As Boolean - ' Performs an equality check on two points (integer pairs). - If obj Is Nothing OrElse Not [GetType]().Equals(obj.GetType()) Then - Return False - Else - Dim p As Point = CType(obj, Point) - Return x = p.x AndAlso y = p.y - End If - End Function - - Public Overrides Function GetHashCode() As Integer - Return Tuple.Create(x, y).GetHashCode() - End Function -End Class - -Class Example - Public Shared Sub Main() - Dim r1 As New Rectangle(0, 0, 100, 200) - Dim r2 As New Rectangle(0, 0, 100, 200) - Dim r3 As New Rectangle(0, 0, 150, 200) - - Console.WriteLine("{0} = {1}: {2}", r1, r2, r1.Equals(r2)) - Console.WriteLine("{0} = {1}: {2}", r1, r3, r1.Equals(r3)) - Console.WriteLine("{0} = {1}: {2}", r2, r3, r2.Equals(r3)) - End Sub -End Class -' The example displays the following output: -' Rectangle(0, 0, 100, 200) = Rectangle(0, 0, 100, 200): True -' Rectangle(0, 0, 100, 200) = Rectangle(0, 0, 150, 200): False -' Rectangle(0, 0, 100, 200) = Rectangle(0, 0, 150, 200): False -' \ No newline at end of file diff --git a/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals4/vb/equals4.vb b/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals4/vb/equals4.vb deleted file mode 100644 index c94d90966dd..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals4/vb/equals4.vb +++ /dev/null @@ -1,50 +0,0 @@ -' -Public Structure Complex - Public re, im As Double - - Public Overrides Function Equals(ByVal obj As [Object]) As Boolean - Return TypeOf obj Is Complex AndAlso Me = CType(obj, Complex) - End Function - - Public Overrides Function GetHashCode() As Integer - Return Tuple.Create(re, im).GetHashCode() - End Function - - Public Shared Operator = (x As Complex, y As Complex) As Boolean - Return x.re = y.re AndAlso x.im = y.im - End Operator - - Public Shared Operator <> (x As Complex, y As Complex) As Boolean - Return Not (x = y) - End Operator - - Public Overrides Function ToString() As String - Return String.Format("({0}, {1})", re, im) - End Function -End Structure - -Class Example - Public Shared Sub Main() - Dim cmplx1, cmplx2 As Complex - - cmplx1.re = 4.0 - cmplx1.im = 1.0 - - cmplx2.re = 2.0 - cmplx2.im = 1.0 - - Console.WriteLine("{0} <> {1}: {2}", cmplx1, cmplx2, cmplx1 <> cmplx2) - Console.WriteLine("{0} = {1}: {2}", cmplx1, cmplx2, cmplx1.Equals(cmplx2)) - - cmplx2.re = 4.0 - - Console.WriteLine("{0} = {1}: {2}", cmplx1, cmplx2, cmplx1 = cmplx2) - Console.WriteLine("{0} = {1}: {2}", cmplx1, cmplx2, cmplx1.Equals(cmplx2)) - End Sub -End Class -' The example displays the following output: -' (4, 1) <> (2, 1): True -' (4, 1) = (2, 1): False -' (4, 1) = (4, 1): True -' (4, 1) = (4, 1): True -' \ No newline at end of file diff --git a/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example.vb b/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example.vb deleted file mode 100644 index c41a83a4758..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example.vb +++ /dev/null @@ -1,44 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' The following is CreateResources.* -' -Imports System.Resources - -Module CreateResource - Public Sub Main() - Dim table As New PersonTable("Name", "Employee Number", "Age", 30, 18, 5) - Dim rr As New ResXResourceWriter(".\UIResources.resx") - rr.AddResource("TableName", "Employees of Acme Corporation") - rr.AddResource("Employees", table) - rr.Generate() - rr.Close() - End Sub -End Module -' - - -' The following is UIElements.* -' - Public Structure PersonTable - Public ReadOnly nColumns As Integer - Public Readonly column1 As String - Public ReadOnly column2 As String - Public ReadOnly column3 As String - Public ReadOnly width1 As Integer - Public ReadOnly width2 As Integer - Public ReadOnly width3 As Integer - - Public Sub New(column1 As String, column2 As String, column3 As String, - width1 As Integer, width2 As Integer, width3 As Integer) - Me.column1 = column1 - Me.column2 = column2 - Me.column3 = column3 - Me.width1 = width1 - Me.width2 = width2 - Me.width3 = width3 - Me.nColumns = Me.GetType().GetFields().Count \ 2 - End Sub -End Structure -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example2.vb b/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example2.vb deleted file mode 100644 index e64ae2afeaf..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example2.vb +++ /dev/null @@ -1,55 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Resources - - - -Module Example - Public Sub Main() - Dim fmtString As String = String.Empty - Dim rm As New ResourceManager("UIResources", GetType(Example).Assembly) - Dim title As String = rm.GetString("TableName") - Dim tableInfo As PersonTable = DirectCast(rm.GetObject("Employees"), PersonTable) - - If Not String.IsNullOrEmpty(title) Then - fmtString = "{0," + ((Console.WindowWidth + title.Length) \ 2).ToString() + "}" - Console.WriteLine(fmtString, title) - Console.WriteLine() - End If - - For ctr As Integer = 1 To tableInfo.nColumns - Dim columnName As String = "column" + ctr.ToString() - Dim widthName As String = "width" + ctr.ToString() - Dim value As String = CStr(tableInfo.GetType().GetField(columnName).GetValue(tableInfo)) - Dim width As Integer = CInt(tableInfo.GetType().GetField(widthName).GetValue(tableInfo)) - fmtString = "{0,-" + width.ToString() + "}" - Console.Write(fmtString, value) - Next - Console.WriteLine() - End Sub -End Module -' - - Public Structure PersonTable - Public ReadOnly nColumns As Integer - Public Readonly column1 As String - Public ReadOnly column2 As String - Public ReadOnly column3 As String - Public ReadOnly width1 As Integer - Public ReadOnly width2 As Integer - Public ReadOnly width3 As Integer - - Public Sub New(column1 As String, column2 As String, column3 As String, - width1 As Integer, width2 As Integer, width3 As Integer) - Me.column1 = column1 - Me.column2 = column2 - Me.column3 = column3 - Me.width1 = width1 - Me.width2 = width2 - Me.width3 = width3 - Me.nColumns = Me.GetType().GetFields().Count \ 2 - End Sub -End Structure - diff --git a/snippets/visualbasic/VS_Snippets_CLR/stringexample1/VB/source.vb b/snippets/visualbasic/VS_Snippets_CLR/stringexample1/VB/source.vb deleted file mode 100644 index 822f09067ac..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR/stringexample1/VB/source.vb +++ /dev/null @@ -1,47 +0,0 @@ -Option Strict On - -Imports System.Text - -Class ConsoleApp - Public Shared Sub Main() - ' - ' Unicode Mathematical operators - Dim charArr1() As Char = {ChrW(&H2200), ChrW(&H2202), _ - ChrW(&H200F), ChrW(&H2205)} - Dim szMathSymbols As New String(charArr1) - - ' Unicode Letterlike Symbols - Dim charArr2() As Char = {ChrW(&H2111), ChrW(&H2118), _ - ChrW(&H2122), ChrW(&H2126)} - Dim szLetterLike As New String(charArr2) - - ' Compare Strings - the result is false - Console.WriteLine("The strings are equal? " & _ - CStr(szMathSymbols.Equals(szLetterLike))) - ' - - ' - ' Create a Unicode String with 5 Greek Alpha characters - Dim szGreekAlpha As New String(ChrW(&H0391), 5) - ' Create a Unicode String with a Greek Omega character - Dim szGreekOmega As New String(New Char() {ChrW(&H03A9), ChrW(&H03A9), _ - ChrW(&H03A9)}, 2, 1) - - Dim szGreekLetters As String = String.Concat(szGreekOmega, szGreekAlpha, _ - szGreekOmega.Clone()) - - ' Examine the result - Console.WriteLine(szGreekLetters) - - ' The first index of Alpha - Dim iAlpha As Integer = szGreekLetters.IndexOf(ChrW(&H0391)) - ' The last index of Omega - Dim iomega As Integer = szGreekLetters.LastIndexOf(ChrW(&H03A9)) - - Console.WriteLine("The Greek letter Alpha first appears at index {0}.", _ - ialpha) - Console.WriteLIne("The Greek letter Omega last appears at index {0}.", _ - iomega) - ' - End Sub -End Class diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.Double.Epsilon/vb/epsilon.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.Double.Epsilon/vb/epsilon.vb deleted file mode 100644 index 2d849282e55..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.Double.Epsilon/vb/epsilon.vb +++ /dev/null @@ -1,24 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim values() As Double = { 0, Double.Epsilon, Double.Epsilon * .5 } - - For ctr As Integer = 0 To values.Length - 2 - For ctr2 As Integer = ctr + 1 To values.Length - 1 - Console.WriteLine("{0:r} = {1:r}: {2}", _ - values(ctr), values(ctr2), _ - values(ctr).Equals(values(ctr2))) - Next - Console.WriteLine() - Next - End Sub -End Module -' The example displays the following output: -' 0 = 4.94065645841247E-324: False -' 0 = 0: True -' -' 4.94065645841247E-324 = 0: False -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.Double.Epsilon/vb/epsilon1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.Double.Epsilon/vb/epsilon1.vb deleted file mode 100644 index 4883ffefc32..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.Double.Epsilon/vb/epsilon1.vb +++ /dev/null @@ -1,57 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim values() As Double = { 0.0, Double.Epsilon } - For Each value In values - Console.WriteLine(GetComponentParts(value)) - Console.WriteLine() - Next - End Sub - - Private Function GetComponentParts(value As Double) As String - Dim result As String = String.Format("{0:R}: ", value) - Dim indent As Integer = result.Length - - ' Convert the double to an 8-byte array. - Dim bytes() As Byte = BitConverter.GetBytes(value) - ' Get the sign bit (byte 7, bit 7). - result += String.Format("Sign: {0}{1}", - If((bytes(7) And &H80) = &H80, "1 (-)", "0 (+)"), - vbCrLf) - - ' Get the exponent (byte 6 bits 4-7 to byte 7, bits 0-6) - Dim exponent As Integer = (bytes(7) And &H07F) << 4 - exponent = exponent Or ((bytes(6) And &HF0) >> 4) - Dim adjustment As Integer = If(exponent <> 0, 1023, 1022) - result += String.Format("{0}Exponent: 0x{1:X4} ({1}){2}", - New String(" "c, indent), exponent - adjustment, - vbCrLf) - - ' Get the significand (bits 0-51) - Dim significand As Long = ((bytes(6) And &H0F) << 48) - significand = significand Or (bytes(5) << 40) - significand = significand Or (bytes(4) << 32) - significand = significand Or (bytes(3) << 24) - significand = significand Or (bytes(2) << 16) - significand = significand Or (bytes(1) << 8) - significand = significand Or bytes(0) - result += String.Format("{0}Mantissa: 0x{1:X13}{2}", - New String(" "c, indent), significand, vbCrLf) - - Return result - End Function -End Module -' The example displays the following output: -' 0: Sign: 0 (+) -' Exponent: 0xFFFFFC02 (-1022) -' Mantissa: 0x0000000000000 -' -' -' 4.94065645841247E-324: Sign: 0 (+) -' Exponent: 0xFFFFFC02 (-1022) -' Mantissa: 0x0000000000001 -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.Single.Epsilon/vb/epsilon.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.Single.Epsilon/vb/epsilon.vb deleted file mode 100644 index 9b8718fa12c..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.Single.Epsilon/vb/epsilon.vb +++ /dev/null @@ -1,24 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim values() As Single = { 0, Single.Epsilon, Single.Epsilon * .5 } - - For ctr As Integer = 0 To values.Length - 2 - For ctr2 As Integer = ctr + 1 To values.Length - 1 - Console.WriteLine("{0:r} = {1:r}: {2}", _ - values(ctr), values(ctr2), _ - values(ctr).Equals(values(ctr2))) - Next - Console.WriteLine() - Next - End Sub -End Module -' The example displays the following output: -' 0 = 1.401298E-45: False -' 0 = 0: True -' -' 1.401298E-45 = 0: False -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.Single.Epsilon/vb/epsilon1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.Single.Epsilon/vb/epsilon1.vb deleted file mode 100644 index f7e7a5375ee..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.Single.Epsilon/vb/epsilon1.vb +++ /dev/null @@ -1,54 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim values() As Single = { 0.0, Single.Epsilon } - For Each value In values - Console.WriteLine(GetComponentParts(value)) - Console.WriteLine() - Next - End Sub - - Private Function GetComponentParts(value As Single) As String - Dim result As String = String.Format("{0:R}: ", value) - Dim indent As Integer = result.Length - - ' Convert the single to an 8-byte array. - Dim bytes() As Byte = BitConverter.GetBytes(value) - Dim formattedSingle As Integer = BitConverter.ToInt32(bytes, 0) - - ' Get the sign bit (byte 3, bit 7). - result += String.Format("Sign: {0}{1}", - If(formattedSingle >> 31 <> 0, "1 (-)", "0 (+)"), - vbCrLf) - - ' Get the exponent (byte 2 bit 7 to byte 3, bits 6) - Dim exponent As Integer = (formattedSingle >> 23) And &h000000FF - Dim adjustment As Integer = If(exponent <> 0, 127, 126) - result += String.Format("{0}Exponent: 0x{1:X4} ({1}){2}", - New String(" "c, indent), exponent - adjustment, - vbCrLf) - - ' Get the significand (bits 0-22) - Dim significand As Long = If(exponent <> 0, - (formattedSingle And &h007FFFFF) Or &h800000, - formattedSingle And &h007FFFFF) - result += String.Format("{0}Mantissa: 0x{1:X13}{2}", - New String(" "c, indent), significand, vbCrLf) - - Return result - End Function -End Module -' The example displays the following output: -' 0: Sign: 0 (+) -' Exponent: 0xFFFFFF82 (-126) -' Mantissa: 0x0000000000000 -' -' -' 1.401298E-45: Sign: 0 (+) -' Exponent: 0xFFFFFF82 (-126) -' Mantissa: 0x0000000000001 -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/FormatExample2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/FormatExample2.vb deleted file mode 100644 index 26b3a3e6e19..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/FormatExample2.vb +++ /dev/null @@ -1,69 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module TestFormatter - Public Sub Main() - Dim acctNumber As Integer = 79203159 - Console.WriteLine(String.Format(New CustomerFormatter, "{0}", acctNumber)) - Console.WriteLine(String.Format(New CustomerFormatter, "{0:G}", acctNumber)) - Console.WriteLine(String.Format(New CustomerFormatter, "{0:S}", acctNumber)) - Console.WriteLine(String.Format(New CustomerFormatter, "{0:P}", acctNumber)) - Try - Console.WriteLine(String.Format(New CustomerFormatter, "{0:X}", acctNumber)) - Catch e As FormatException - Console.WriteLine(e.Message) - End Try - End Sub -End Module - -Public Class CustomerFormatter : Implements IFormatProvider, ICustomFormatter - Public Function GetFormat(type As Type) As Object _ - Implements IFormatProvider.GetFormat - If type Is GetType(ICustomFormatter) Then - Return Me - Else - Return Nothing - End If - End Function - - Public Function Format(fmt As String, _ - arg As Object, _ - formatProvider As IFormatProvider) As String _ - Implements ICustomFormatter.Format - If Not Me.Equals(formatProvider) Then - Return Nothing - Else - If String.IsNullOrEmpty(fmt) Then fmt = "G" - - Dim customerString As String = arg.ToString() - if customerString.Length < 8 Then _ - customerString = customerString.PadLeft(8, "0"c) - - Select Case fmt - Case "G" - Return customerString.Substring(0, 1) & "-" & _ - customerString.Substring(1, 5) & "-" & _ - customerString.Substring(6) - Case "S" - Return customerString.Substring(0, 1) & "/" & _ - customerString.Substring(1, 5) & "/" & _ - customerString.Substring(6) - Case "P" - Return customerString.Substring(0, 1) & "." & _ - customerString.Substring(1, 5) & "." & _ - customerString.Substring(6) - Case Else - Throw New FormatException( _ - String.Format("The '{0}' format specifier is not supported.", fmt)) - End Select - End If - End Function -End Class -' The example displays the following output: -' 7-92031-59 -' 7-92031-59 -' 7/92031/59 -' 7.92031.59 -' The 'X' format specifier is not supported. -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatoverload1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatoverload1.vb deleted file mode 100644 index 1d08f31a665..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatoverload1.vb +++ /dev/null @@ -1,18 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -Module Example - Public Sub Main() - ' - Dim dat As Date = #1/17/2012 9:30AM# - Dim city As String = "Chicago" - Dim temp As Integer = -16 - Dim output As String = String.Format("At {0} in {1}, the temperature was {2} degrees.", - dat, city, temp) - Console.WriteLine(output) - ' The example displays the following output: - ' At 1/17/2012 9:30:00 AM in Chicago, the temperature was -16 degrees. - ' - End Sub -End Module - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatoverload2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatoverload2.vb deleted file mode 100644 index 56a542b9ffe..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatoverload2.vb +++ /dev/null @@ -1,35 +0,0 @@ -' Visual Basic .NET Document -Option Strict On -Option Infer On - -' -Module Example - Public Sub Main() - ' Create array of 5-tuples with population data for three U.S. cities, 1940-1950. - Dim cities() = _ - { Tuple.Create("Los Angeles", #1/1/1940#, 1504277, #1/1/1950#, 1970358), - Tuple.Create("New York", #1/1/1940#, 7454995, #1/1/1950#, 7891957), - Tuple.Create("Chicago", #1/1/1940#, 3396808, #1/1/1950#, 3620962), - Tuple.Create("Detroit", #1/1/1940#, 1623452, #1/1/1950#, 1849568) } - - ' Display header - Dim header As String = String.Format("{0,-12}{1,8}{2,12}{1,8}{2,12}{3,14}", - "City", "Year", "Population", "Change (%)") - Console.WriteLine(header) - Console.WriteLine() - For Each city In cities - Dim output = String.Format("{0,-12}{1,8:yyyy}{2,12:N0}{3,8:yyyy}{4,12:N0}{5,14:P1}", - city.Item1, city.Item2, city.Item3, city.Item4, city.Item5, - (city.Item5 - city.Item3)/city.Item3) - Console.WriteLine(output) - Next - End Sub -End Module -' The example displays the following output: -' City Year Population Year Population Change (%) -' -' Los Angeles 1940 1,504,277 1950 1,970,358 31.0 % -' New York 1940 7,454,995 1950 7,891,957 5.9 % -' Chicago 1940 3,396,808 1950 3,620,962 6.6 % -' Detroit 1940 1,623,452 1950 1,849,568 13.9 % -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatsyntax1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatsyntax1.vb deleted file mode 100644 index ac3c14b81ad..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatsyntax1.vb +++ /dev/null @@ -1,12 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -Module Example - Public Sub Main() - 'Dim value As String = -' -String.Format("{0,-10:C}", 126347.89d) -' - End Sub -End Module - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/interceptor2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/interceptor2.vb deleted file mode 100644 index 7636c4f7b27..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/interceptor2.vb +++ /dev/null @@ -1,120 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization - -Public Class InterceptProvider : Implements IFormatProvider, ICustomFormatter - Public Function GetFormat(formatType As Type) As Object _ - Implements IFormatProvider.GetFormat - If formatType Is GetType(ICustomFormatter) Then - Return Me - Else - Return Nothing - End If - End Function - - Public Function Format(fmt As String, obj As Object, provider As IFormatProvider) As String _ - Implements ICustomFormatter.Format - - Dim formatString As String = If(fmt IsNot Nothing, fmt, "") - Console.WriteLine("Provider: {0}, Object: {1}, Format String: {2}", - provider, If(obj IsNot Nothing, obj, ""), formatString) - - If obj Is Nothing Then Return String.Empty - - ' If this is a byte and the "R" format string, format it with Roman numerals. - If TypeOf(obj) Is Byte AndAlso formatString.ToUpper.Equals("R") Then - Dim value As Byte = CByte(obj) - Dim remainder As Integer - Dim result As Integer - Dim returnString As String = String.Empty - - ' Get the hundreds digit(s) - result = Math.DivRem(value, 100, remainder) - If result > 0 Then returnString = New String("C"c, result) - value = CByte(remainder) - ' Get the 50s digit - result = Math.DivRem(value, 50, remainder) - If result = 1 Then returnString += "L" - value = CByte(remainder) - ' Get the tens digit. - result = Math.DivRem(value, 10, remainder) - If result > 0 Then returnString += New String("X"c, result) - value = CByte(remainder) - ' Get the fives digit. - result = Math.DivRem(value, 5, remainder) - If result > 0 Then returnString += "V" - value = CByte(remainder) - ' Add the ones digit. - If remainder > 0 Then returnString += New String("I"c, remainder) - - ' Check whether we have too many X characters. - Dim pos As Integer = returnString.IndexOf("XXXX") - If pos >= 0 Then - Dim xPos As Integer = returnString.IndexOf("L") - If xPos >= 0 And xPos = pos - 1 Then - returnString = returnString.Replace("LXXXX", "XC") - Else - returnString = returnString.Replace("XXXX", "XL") - End If - End If - ' Check whether we have too many I characters - pos = returnString.IndexOf("IIII") - If pos >= 0 Then - If returnString.IndexOf("V") >= 0 Then - returnString = returnString.Replace("VIIII", "IX") - Else - returnString = returnString.Replace("IIII", "IV") - End If - End If - Return returnString - End If - - ' Use default for all other formatting. - If obj Is GetType(IFormattable) - Return CType(obj, IFormattable).ToString(fmt, CultureInfo.CurrentCulture) - Else - Return obj.ToString() - End If - End Function -End Class - -Module Example - Public Sub Main() - Dim n As Integer = 10 - Dim value As Double = 16.935 - Dim day As DateTime = Date.Now - Dim provider As New InterceptProvider() - Console.WriteLine(String.Format(provider, "{0:N0}: {1:C2} on {2:d}", n, value, day)) - Console.WriteLine() - Console.WriteLine(String.Format(provider, "{0}: {1:F}", "Today", - CType(Date.Now.DayOfWeek, DayOfWeek))) - Console.WriteLine() - Console.WriteLine(String.Format(provider, "{0:X}, {1}, {2}\n", - CByte(2), CByte(12), CByte(199))) - Console.WriteLine() - Console.WriteLine(String.Format(provider, "{0:R}, {1:R}, {2:R}", - CByte(2), CByte(12), CByte(199))) - End Sub -End Module -' The example displays the following output: -' Provider: InterceptProvider, Object: 10, Format String: N0 -' Provider: InterceptProvider, Object: 16.935, Format String: C2 -' Provider: InterceptProvider, Object: 1/31/2013 6:10:28 PM, Format String: d -' 10: $16.94 on 1/31/2013 -' -' Provider: InterceptProvider, Object: Today: , Format String: -' Provider: InterceptProvider, Object: Thursday, Format String: F -' Today: : Thursday -' -' Provider: InterceptProvider, Object: 2, Format String: X -' Provider: InterceptProvider, Object: 12, Format String: -' Provider: InterceptProvider, Object: 199, Format String: -' 2, 12, 199 -' -' Provider: InterceptProvider, Object: 2, Format String: R -' Provider: InterceptProvider, Object: 12, Format String: R -' Provider: InterceptProvider, Object: 199, Format String: R -' II, XII, CXCIX -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa-interpolated1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa-interpolated1.vb deleted file mode 100644 index e512279acb2..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa-interpolated1.vb +++ /dev/null @@ -1,20 +0,0 @@ - -Module Example - Public Sub Main() - Dim names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" } - Dim output = names(0) + ", " + names(1) + ", " + names(2) + ", " + - names(3) + ", " + names(4) + ", " + names(5) + ", " + - names(6) - - output += vbCrLf - Dim dat = DateTime.Now - output += String.Format("It is {0:t} on {0:d}. The day of the week is {1}.", - dat, dat.DayOfWeek) - Console.WriteLine(output) - End Sub -End Module -' The example displays the following output: -' Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma -' It is 10:29 AM on 1/8/2018. The day of the week is Monday. - - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa-interpolated2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa-interpolated2.vb deleted file mode 100644 index bbb11ab7696..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa-interpolated2.vb +++ /dev/null @@ -1,17 +0,0 @@ - -Module Example - Public Sub Main() - Dim names = { "Balto", "Vanya", "Dakota", "Samuel", "Koani", "Yiska", "Yuma" } - Dim output = $"{names(0)}, {names(1)}, {names(2)}, {names(3)}, {names(4)}, " + - $"{names(5)}, {names(6)}" - - Dim dat = DateTime.Now - output += $"{vbCrLf}It is {dat:t} on {dat:d}. The day of the week is {dat.DayOfWeek}." - Console.WriteLine(output) - End Sub -End Module -' The example displays the following output: -' Balto, Vanya, Dakota, Samuel, Koani, Yiska, Yuma -' It is 10:29 AM on 1/8/2018. The day of the week is Monday. - - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa1.vb deleted file mode 100644 index 0afdca7a6de..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa1.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Collections.Generic - -Module Example - Public Sub Main() - Dim rnd As New Random() - Dim numbers(3) As Integer - Dim total As Integer = 0 - For ctr = 0 To 2 - Dim number As Integer = rnd.Next(1001) - numbers(ctr) = number - total += number - Next - numbers(3) = total - Console.WriteLine("{0} + {1} + {2} = {3}", numbers) - End Sub -End Module -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa2.vb deleted file mode 100644 index b4e619a49d3..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa2.vb +++ /dev/null @@ -1,25 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Collections.Generic - -Module Example - Public Sub Main() - Dim rnd As New Random() - Dim numbers(3) As Integer - Dim total As Integer = 0 - For ctr = 0 To 2 - Dim number As Integer = rnd.Next(1001) - numbers(ctr) = number - total += number - Next - numbers(3) = total - Dim values(numbers.Length - 1) As Object - numbers.CopyTo(values, 0) - Console.WriteLine("{0} + {1} + {2} = {3}", values) - End Sub -End Module -' - - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa26.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa26.vb deleted file mode 100644 index 1eff8aeaba5..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa26.vb +++ /dev/null @@ -1,23 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim values() As Object = { 1603, 1794.68235, 15436.14 } - Dim result As String - For Each value In values - result = String.Format("{0,12:C2} {0,12:E3} {0,12:F4} {0,12:N3} {1,12:P2}", - value, CDbl(value) / 10000) - Console.WriteLine(result) - Console.WriteLine() - Next - End Sub -End Module -' The example displays the following output: -' $1,603.00 1.603E+003 1603.0000 1,603.000 16.03 % -' -' $1,794.68 1.795E+003 1794.6824 1,794.682 17.95 % -' -' $15,436.14 1.544E+004 15436.1400 15,436.140 154.36 % -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa27.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa27.vb deleted file mode 100644 index 2ab7e6c9930..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa27.vb +++ /dev/null @@ -1,16 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim value As Decimal = 16309.5436d - Dim result As String = String.Format("{0,12:#.00000} {0,12:0,000.00} {0,12:000.00#}", - value) - Console.WriteLine(result) - End Sub -End Module -' The example displays the following output: -' 16309.54360 16,309.54 16309.544 -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa28.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa28.vb deleted file mode 100644 index d87306fa9e7..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa28.vb +++ /dev/null @@ -1,16 +0,0 @@ -Visual Basic .NET Document - -Option Strict On - -' -Module Example - Public Sub Main() - Dim value As Integer = 16342 - Dim result As String = String.Format("{0,18:00000000} {0,18:00000000.000} {0,18:000,0000,000.0}", - value) - Console.WriteLine(result) - End Sub -End Module -' The example displays the following output: -' 00016342 00016342.000 0,000,016,342.0 -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa29.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa29.vb deleted file mode 100644 index 85b194b7173..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa29.vb +++ /dev/null @@ -1,14 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim value As Integer = 1326 - Dim result As String = String.Format("{0,10:D6} {0,10:X8}", value) - Console.WriteLine(result) - End Sub -End Module -' The example displays the following output: -' 001326 0000052E -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting1.vb deleted file mode 100644 index 53a9b43e639..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting1.vb +++ /dev/null @@ -1,80 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -Imports System.Text - -Module Example - Public Sub Main() - ' - Dim temp As Decimal = 20.4d - Dim s As String = String.Format("The temperature is {0}°C.", temp) - Console.WriteLine(s) - ' Displays 'The temperature is 20.4°C.' - ' - - Snippet31() - Snippet32() - Snippet33() - Snippet34() - End Sub - - Private Sub Snippet31() - ' - Dim s As String = String.Format("At {0}, the temperature is {1}°C.", - Date.Now, 20.4) - ' Output similar to: 'At 4/10/2015 9:29:41 AM, the temperature is 20.4°C.' - ' - Console.WriteLine(s) - End Sub - - Private Sub Snippet32() - ' - Dim s As String = String.Format("It is now {0:d} at {0:t}", - Date.Now) - ' Output similar to: 'It is now 4/10/2015 at 10:04 AM' - ' - Console.WriteLine(s) - End Sub - - Private Sub Snippet33() - ' - Dim years() As Integer = { 2013, 2014, 2015 } - Dim population() As Integer = { 1025632, 1105967, 1148203 } - Dim sb As New StringBuilder() - sb.Append(String.Format("{0,6} {1,15}{2}{2}", - "Year", "Population", vbCrLf)) - For index As Integer = 0 To years.Length - 1 - sb.AppendFormat("{0,6} {1,15:N0}{2}", - years(index), population(index), vbCrLf) - Next - ' Result: - ' Year Population - ' - ' 2013 1,025,632 - ' 2014 1,105,967 - ' 2015 1,148,203 - ' - Console.WriteLine(sb) - End Sub - - Private Sub Snippet34() - ' - Dim years() As Integer = { 2013, 2014, 2015 } - Dim population() As Integer = { 1025632, 1105967, 1148203 } - Dim s As String = String.Format("{0,-10} {1,-10}{2}{2}", - "Year", "Population", vbCrLf) - For index As Integer = 0 To years.Length - 1 - s += String.Format("{0,-10} {1,-10:N0}{2}", - years(index), population(index), vbCrLf) - Next - ' Result: - ' Year Population - ' - ' 2013 1,025,632 - ' 2014 1,105,967 - ' 2015 1,148,203 - ' - Console.WriteLine(vbCrLf + s) - End Sub -End Module - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting2.vb deleted file mode 100644 index 38a59cde929..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting2.vb +++ /dev/null @@ -1,27 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -Module Example - Public Sub Main() - ' - Dim pricePerOunce As Decimal = 17.36d - Dim s As String = String.Format("The current price is {0} per ounce.", - pricePerOunce) - ' Result: The current price is 17.36 per ounce. - ' - Console.WriteLine(s) - ShowFormatted() - End Sub - - Private Sub ShowFormatted() - ' - Dim pricePerOunce As Decimal = 17.36d - Dim s As String = String.Format("The current price is {0:C2} per ounce.", - pricePerOunce) - ' Result if current culture is en-US: - ' The current price is $17.36 per ounce. - ' - Console.WriteLine(s) - End Sub -End Module - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format2/vb/Example1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format2/vb/Example1.vb deleted file mode 100644 index d0bc66c06a8..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format2/vb/Example1.vb +++ /dev/null @@ -1,24 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim values() As Short = { Int16.MinValue, -27, 0, 1042, Int16.MaxValue } - Console.WriteLine("{0,10} {1,10}", "Decimal", "Hex") - Console.WriteLine() - For Each value As Short In values - Dim formatString As String = String.Format("{0,10:G}: {0,10:X}", value) - Console.WriteLine(formatString) - Next - End Sub -End Module -' The example displays the following output: -' Decimal Hex -' -' -32768: 8000 -' -27: FFE5 -' 0: 0 -' 1042: 412 -' 32767: 7FFF -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Intern/vb/Intern1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Intern/vb/Intern1.vb deleted file mode 100644 index cf5eb1e1d28..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Intern/vb/Intern1.vb +++ /dev/null @@ -1,18 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -Imports System.Text - - -Module modMain - Public Sub Main() - ' - Dim s1 As String = "MyTest" - Dim s2 As String = New StringBuilder().Append("My").Append("Test").ToString() - Dim s3 As String = String.Intern(s2) - Console.WriteLine(CObj(s2) Is CObj(s1)) ' Different references. - Console.WriteLine(CObj(s3) Is CObj(s1)) ' The same reference. - ' - End Sub -End Module - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Intern/vb/Intern2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Intern/vb/Intern2.vb deleted file mode 100644 index 6b39790369e..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Intern/vb/Intern2.vb +++ /dev/null @@ -1,24 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -Imports System.Text - - -Module modMain - Public Sub Main() - ' - Dim str1 As String = String.Empty - Dim str2 As String = String.Empty - - Dim sb As StringBuilder = New StringBuilder().Append(String.Empty) - str2 = String.Intern(sb.ToString()) - - If CObj(str1) Is CObj(str2) Then - Console.WriteLine("The strings are equal.") - Else - Console.WriteLine("The strings are not equal.") - End If - ' - End Sub -End Module - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeSpan.TryParse/vb/tryparsefailure1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeSpan.TryParse/vb/tryparsefailure1.vb deleted file mode 100644 index 892c56a694f..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeSpan.TryParse/vb/tryparsefailure1.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -Module Example - Public Sub Main() - ' - Dim value As String = "000000006" - Dim interval As TimeSpan - If TimeSpan.TryParse(value, interval) Then - Console.WriteLine("{0} --> {1}", value, interval) - Else - Console.WriteLine("Unable to parse '{0}'", value) - End If - ' Output from .NET Framework 3.5 and earlier versions: - ' 000000006 --> 6.00:00:00 - ' Output from .NET Framework 4: - ' Unable to parse '000000006' - ' - End Sub -End Module - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.datetime.frombinary/vb/frombinary1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.datetime.frombinary/vb/frombinary1.vb deleted file mode 100644 index 1f0f3e918e7..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.datetime.frombinary/vb/frombinary1.vb +++ /dev/null @@ -1,22 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim localDate As Date = DateTime.SpecifyKind(#03/14/2010 2:30AM#, DateTimeKind.Local) - Dim binLocal As Long = localDate.ToBinary() - If TimeZoneInfo.Local.IsInvalidTime(localDate) Then - Console.WriteLine("{0} is an invalid time in the {1} zone.", _ - localDate, _ - TimeZoneInfo.Local.StandardName) - End If - Dim localDate2 As Date = DateTime.FromBinary(binLocal) - Console.WriteLine("{0} = {1}: {2}", _ - localDate, localDate2, localDate.Equals(localDate2)) - End Sub -End Module -' The example displays the following output: -' 3/14/2010 2:30:00 AM is an invalid time in the Pacific Standard Time zone. -' 3/14/2010 2:30:00 AM = 3/14/2010 3:30:00 AM: False -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.double.compareto/vb/compareto2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.double.compareto/vb/compareto2.vb deleted file mode 100644 index abffb304b54..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.double.compareto/vb/compareto2.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim value1 As Double = 6.185 - Dim value2 As Double = value1 * .1 / .1 - Console.WriteLine("Comparing {0} and {1}: {2}", - value1, value2, value1.CompareTo(value2)) - Console.WriteLine() - Console.WriteLine("Comparing {0:R} and {1:R}: {2}", - value1, value2, value1.CompareTo(value2)) - End Sub -End Module -' The example displays the following output: -' Comparing 6.185 and 6.185: -1 -' -' Comparing 6.185 and 6.1850000000000005: -1 -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.double.compareto/vb/compareto3.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.double.compareto/vb/compareto3.vb deleted file mode 100644 index 3b357e27174..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.double.compareto/vb/compareto3.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim value1 As Double = 6.185 - Dim value2 As Object = value1 * .1 / .1 - Console.WriteLine("Comparing {0} and {1}: {2}", - value1, value2, value1.CompareTo(value2)) - Console.WriteLine() - Console.WriteLine("Comparing {0:R} and {1:R}: {2}", - value1, value2, value1.CompareTo(value2)) - End Sub -End Module -' The example displays the following output: -' Comparing 6.185 and 6.185: -1 -' -' Comparing 6.185 and 6.1850000000000005: -1 -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.double.equals/vb/equalsabs1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.double.equals/vb/equalsabs1.vb deleted file mode 100644 index 0551459c5a6..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.double.equals/vb/equalsabs1.vb +++ /dev/null @@ -1,41 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim value1 As Double = .1 * 10 - Dim value2 As Double = 0 - For ctr As Integer = 0 To 9 - value2 += .1 - Next - - Console.WriteLine("{0:R} = {1:R}: {2}", value1, value2, - HasMinimalDifference(value1, value2, 1)) - End Sub - - Public Function HasMinimalDifference(value1 As Double, value2 As Double, units As Integer) As Boolean - Dim lValue1 As long = BitConverter.DoubleToInt64Bits(value1) - Dim lValue2 As long = BitConverter.DoubleToInt64Bits(value2) - - ' If the signs are different, Return False except for +0 and -0. - If ((lValue1 >> 63) <> (lValue2 >> 63)) Then - If value1 = value2 Then - Return True - End If - Return False - End If - - Dim diff As Long = Math.Abs(lValue1 - lValue2) - - If diff <= units Then - Return True - End If - - Return False - End Function -End Module -' The example displays the following output: -' 1 = 0.99999999999999989: True -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/Async1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/Async1.vb deleted file mode 100644 index 7fad3bf8785..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/Async1.vb +++ /dev/null @@ -1,47 +0,0 @@ -' Visual Basic .NET Document -Option Infer On -Option Strict On - -' -Imports System.Collections.Generic -Imports System.Globalization -Imports System.Runtime.Versioning -Imports System.Threading -Imports System.Threading.Tasks - - - -Module Example - Public Sub Main() - Dim tasks As New List(Of Task) - Console.WriteLine("The current culture is {0}", - Thread.CurrentThread.CurrentCulture.Name) - Thread.CurrentThread.CurrentCulture = New CultureInfo("pt-BR") - ' Change the current culture to Portuguese (Brazil). - Console.WriteLine("Current culture changed to {0}", - Thread.CurrentThread.CurrentCulture.Name) - Console.WriteLine("Application thread is thread {0}", - Thread.CurrentThread.ManagedThreadId) - ' Launch six tasks and display their current culture. - For ctr As Integer = 0 to 5 - tasks.Add(Task.Run(Sub() - Console.WriteLine("Culture of task {0} on thread {1} is {2}", - Task.CurrentId, - Thread.CurrentThread.ManagedThreadId, - Thread.CurrentThread.CurrentCulture.Name) - End Sub)) - Next - Task.WaitAll(tasks.ToArray()) - End Sub -End Module -' The example displays output like the following: -' The current culture is en-US -' Current culture changed to pt-BR -' Application thread is thread 9 -' Culture of task 2 on thread 11 is pt-BR -' Culture of task 1 on thread 10 is pt-BR -' Culture of task 3 on thread 11 is pt-BR -' Culture of task 5 on thread 11 is pt-BR -' Culture of task 6 on thread 11 is pt-BR -' Culture of task 4 on thread 10 is pt-BR -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/Get1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/Get1.vb deleted file mode 100644 index d808559398e..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/Get1.vb +++ /dev/null @@ -1,16 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization - -Module Example - Public Sub Main() - Dim culture As CultureInfo = CultureInfo.CurrentCulture - Console.WriteLine("The current culture is {0} [{1}]", - culture.NativeName, culture.Name) - End Sub -End Module -' The example displays output like the following: -' The current culture is English (United States) [en-US] -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/aspculture13.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/aspculture13.vb deleted file mode 100644 index 4b211dd405d..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/aspculture13.vb +++ /dev/null @@ -1,23 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -Imports System.Globalization -Imports System.Threading - -Module Example - Public Sub Main() - ' - Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(Request.UserLanguages(0)) - ' - End Sub -End Module - - -Public Class Request - Private Shared langs(3) As String - Public Shared ReadOnly Property UserLanguages As String() - Get - Return langs - End Get - End Property -End Class diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/changeculture11.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/changeculture11.vb deleted file mode 100644 index 54d7739c11c..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/changeculture11.vb +++ /dev/null @@ -1,35 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization -Imports System.Threading - -Public Class Info : Inherits MarshalByRefObject - Public Sub ShowCurrentCulture() - Console.WriteLine("Culture of {0} in application domain {1}: {2}", - Thread.CurrentThread.Name, - AppDomain.CurrentDomain.FriendlyName, - CultureInfo.CurrentCulture.Name) - End Sub -End Class - -Module Example - Public Sub Main() - Dim inf As New Info() - ' Set the current culture to Dutch (Netherlands). - Thread.CurrentThread.Name = "MainThread" - CultureInfo.CurrentCulture = CultureInfo.CreateSpecificCulture("nl-NL") - inf.ShowCurrentCulture() - - ' Create a new application domain. - Dim ad As AppDomain = AppDomain.CreateDomain("Domain2") - Dim inf2 As Info = CType(ad.CreateInstanceAndUnwrap(GetType(Info).Assembly.FullName, "Info"), - Info) - inf2.ShowCurrentCulture() - End Sub -End Module -' This example displays the following output: -' Culture of MainThread in application domain Example.exe: nl-NL -' Culture of MainThread in application domain Domain2: nl-NL -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/specific12.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/specific12.vb deleted file mode 100644 index ae947d15d02..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/specific12.vb +++ /dev/null @@ -1,30 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization -Imports System.Threading - -Module Example - Public Sub Main() - Dim value As Double = 1634.92 - CultureInfo.CurrentCulture = New CultureInfo("fr-CA") - Console.WriteLine("Current Culture: {0}", - CultureInfo.CurrentCulture.Name) - Console.WriteLine("{0:C2}", value) - Console.WriteLine() - - Thread.CurrentThread.CurrentCulture = New CultureInfo("fr") - Console.WriteLine("Current Culture: {0}", - CultureInfo.CurrentCulture.Name) - Console.WriteLine("{0:C2}", value) - End Sub -End Module -' The example displays the following output: -' Current Culture: fr-CA -' 1 634,92 $ -' -' Current Culture: fr -' 1 634,92 € -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/Async1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/Async1.vb deleted file mode 100644 index 61366ace2a7..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/Async1.vb +++ /dev/null @@ -1,47 +0,0 @@ -' Visual Basic .NET Document -Option Infer On -Option Strict On - -' -Imports System.Collections.Generic -Imports System.Globalization -Imports System.Runtime.Versioning -Imports System.Threading -Imports System.Threading.Tasks - - - -Module Example - Public Sub Main() - Dim tasks As New List(Of Task) - Console.WriteLine("The current UI culture is {0}", - Thread.CurrentThread.CurrentUICulture.Name) - Thread.CurrentThread.CurrentUICulture = New CultureInfo("pt-BR") - ' Change the current UI culture to Portuguese (Brazil). - Console.WriteLine("Current culture changed to {0}", - Thread.CurrentThread.CurrentUICulture.Name) - Console.WriteLine("Application thread is thread {0}", - Thread.CurrentThread.ManagedThreadId) - ' Launch six tasks and display their current culture. - For ctr As Integer = 0 to 5 - tasks.Add(Task.Run(Sub() - Console.WriteLine("Culture of task {0} on thread {1} is {2}", - Task.CurrentId, - Thread.CurrentThread.ManagedThreadId, - Thread.CurrentThread.CurrentUICulture.Name) - End Sub)) - Next - Task.WaitAll(tasks.ToArray()) - End Sub -End Module -' The example displays output like the following: -' The current culture is en-US -' Current culture changed to pt-BR -' Application thread is thread 9 -' Culture of task 2 on thread 11 is pt-BR -' Culture of task 1 on thread 10 is pt-BR -' Culture of task 3 on thread 11 is pt-BR -' Culture of task 5 on thread 11 is pt-BR -' Culture of task 6 on thread 11 is pt-BR -' Culture of task 4 on thread 10 is pt-BR -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/Get1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/Get1.vb deleted file mode 100644 index 43acf8fb46c..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/Get1.vb +++ /dev/null @@ -1,16 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization - -Module Example - Public Sub Main() - Dim culture As CultureInfo = CultureInfo.CurrentCulture - Console.WriteLine("The current UI culture is {0} [{1}]", - culture.NativeName, culture.Name) - End Sub -End Module -' The example displays output like the following: -' The current UI culture is English (United States) [en-US] -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/currentuiculture1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/currentuiculture1.vb deleted file mode 100644 index 3f458113b1e..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/currentuiculture1.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization -Imports System.Threading - -Module Example - Public Sub Main() - Console.WriteLine("The current UI culture: {0}", - CultureInfo.CurrentUICulture.Name) - - CultureInfo.CurrentUICulture = CultureInfo.CreateSpecificCulture("fr-FR") - Console.WriteLine("The current UI culture: {0}", - CultureInfo.CurrentUICulture.Name) - End Sub -End Module -' The example displays output like the following: -' The current UI culture: en-US -' The current UI culture: fr-FR -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.invariantculture/vb/persist1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.invariantculture/vb/persist1.vb deleted file mode 100644 index cb6e6ef721d..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.invariantculture/vb/persist1.vb +++ /dev/null @@ -1,53 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization -Imports System.IO - -Module Example - Public Sub Main() - ' Persist the date and time data. - Dim sw As New StreamWriter(".\DateData.dat") - - ' Create a DateTime value. - Dim dtIn As DateTime = DateTime.Now - ' Retrieve a CultureInfo object. - Dim invC As CultureInfo = CultureInfo.InvariantCulture - - ' Convert the date to a string and write it to a file. - sw.WriteLine(dtIn.ToString("r", invC)) - sw.Close() - - ' Restore the date and time data. - Dim sr As New StreamReader(".\DateData.dat") - Dim input As String = String.Empty - Do While sr.Peek() >= 0 - input = sr.ReadLine() - Console.WriteLine("Stored data: {0}" , input) - Console.WriteLine() - - ' Parse the stored string. - Dim dtOut As DateTime = DateTime.Parse(input, invC, DateTimeStyles.RoundtripKind) - - ' Create a French (France) CultureInfo object. - Dim frFr As New CultureInfo("fr-FR") - ' Displays the date formatted for the "fr-FR" culture. - Console.WriteLine("Date formatted for the {0} culture: {1}" , - frFr.Name, dtOut.ToString("f", frFr)) - - ' Creates a German (Germany) CultureInfo object. - Dim deDe As New CultureInfo("de-De") - ' Displays the date formatted for the "de-DE" culture. - Console.WriteLine("Date formatted for {0} culture: {1}" , - deDe.Name, dtOut.ToString("f", deDe)) - Loop - sr.Close() - End Sub -End Module -' The example displays the following output: -' Stored data: Tue, 15 May 2012 16:34:16 GMT -' -' Date formatted for the fr-FR culture: mardi 15 mai 2012 16:34 -' Date formatted for de-DE culture: Dienstag, 15. Mai 2012 16:34 -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_ref.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_ref.vb deleted file mode 100644 index 68962bd4153..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_ref.vb +++ /dev/null @@ -1,43 +0,0 @@ -' Visual Basic .NET Document -' Illustrates reference equality with reference types. -Option Strict On - -' -' Define a reference type that does not override Equals. -Public Class Person - Private personName As String - - Public Sub New(name As String) - Me.personName = name - End Sub - - Public Overrides Function ToString() As String - Return Me.personName - End Function -End Class - -Module Example - Public Sub Main() - Dim person1a As New Person("John") - Dim person1b As Person = person1a - Dim person2 As New Person(person1a.ToString()) - - Console.WriteLine("Calling Equals:") - Console.WriteLine("person1a and person1b: {0}", person1a.Equals(person1b)) - Console.WriteLine("person1a and person2: {0}", person1a.Equals(person2)) - Console.WriteLine() - - Console.WriteLine("Casting to an Object and calling Equals:") - Console.WriteLine("person1a and person1b: {0}", CObj(person1a).Equals(CObj(person1b))) - Console.WriteLine("person1a and person2: {0}", CObj(person1a).Equals(CObj(person2))) - End Sub -End Module -' The example displays the following output: -' Calling Equals: -' person1a and person1b: True -' person1a and person2: False -' -' Casting to an Object and calling Equals: -' person1a and person1b: True -' person1a and person2: False -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_val1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_val1.vb deleted file mode 100644 index 9f9a3e7cbf4..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_val1.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim value1 As Byte = 12 - Dim value2 As Integer = 12 - - Dim object1 As Object = value1 - Dim object2 As Object = value2 - - Console.WriteLine("{0} ({1}) = {2} ({3}): {4}", - object1, object1.GetType().Name, - object2, object2.GetType().Name, - object1.Equals(object2)) - End Sub -End Module -' The example displays the following output: -' 12 (Byte) = 12 (Int32): False -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_val2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_val2.vb deleted file mode 100644 index e03d32d990a..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_val2.vb +++ /dev/null @@ -1,37 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -' Define a value type that does not override Equals. -Public Structure Person - Private personName As String - - Public Sub New(name As String) - Me.personName = name - End Sub - - Public Overrides Function ToString() As String - Return Me.personName - End Function -End Structure - -Module Example - Public Sub Main() - Dim p1 As New Person("John") - Dim p2 As New Person("John") - - Console.WriteLine("Calling Equals:") - Console.WriteLine(p1.Equals(p2)) - Console.WriteLine() - - Console.WriteLine("Casting to an Object and calling Equals:") - Console.WriteLine(CObj(p1).Equals(p2)) - End Sub -End Module -' The example displays the following output: -' Calling Equals: -' True -' -' Casting to an Object and calling Equals: -' True -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equalsoverride.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equalsoverride.vb deleted file mode 100644 index 70e98d28757..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equalsoverride.vb +++ /dev/null @@ -1,39 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Public Class Person - Private idNumber As String - Private personName As String - - Public Sub New(name As String, id As String) - Me.personName = name - Me.idNumber = id - End Sub - - Public Overrides Function Equals(obj As Object) As Boolean - Dim personObj As Person = TryCast(obj, Person) - If personObj Is Nothing Then - Return False - Else - Return idNumber.Equals(personObj.idNumber) - End If - End Function - - Public Overrides Function GetHashCode() As Integer - Return Me.idNumber.GetHashCode() - End Function -End Class - -Module Example - Public Sub Main() - Dim p1 As New Person("John", "63412895") - Dim p2 As New Person("Jack", "63412895") - Console.WriteLine(p1.Equals(p2)) - Console.WriteLine(Object.Equals(p1, p2)) - End Sub -End Module -' The example displays the following output: -' True -' True -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equalssb1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equalssb1.vb deleted file mode 100644 index 87a74f9c6d9..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equalssb1.vb +++ /dev/null @@ -1,29 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Text - -Module Example - Public Sub Main() - Dim sb1 As New StringBuilder("building a string...") - Dim sb2 As New StringBuilder("building a string...") - - Console.WriteLine("sb1.Equals(sb2): {0}", sb1.Equals(sb2)) - Console.WriteLine("CObj(sb1).Equals(sb2): {0}", - CObj(sb1).Equals(sb2)) - Console.WriteLine("Object.Equals(sb1, sb2): {0}", - Object.Equals(sb1, sb2)) - - Console.WriteLine() - Dim sb3 As Object = New StringBuilder("building a string...") - Console.WriteLine("sb3.Equals(sb2): {0}", sb3.Equals(sb2)) - End Sub -End Module -' The example displays the following output: -' sb1.Equals(sb2): True -' CObj(sb1).Equals(sb2): False -' Object.Equals(sb1, sb2): False -' -' sb3.Equals(sb2): False -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.finalize/vb/finalize_safe.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.finalize/vb/finalize_safe.vb deleted file mode 100644 index 72f4f3ad207..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.finalize/vb/finalize_safe.vb +++ /dev/null @@ -1,167 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports Microsoft.Win32.SafeHandles -Imports System.ComponentModel -Imports System.IO -Imports System.Runtime.InteropServices -Imports System.Text - -Public Class FileAssociationInfo : Implements IDisposable - ' Private variables. - Private ext As String - Private openCmd As String - Private args As String - Private hExtHandle, hAppIdHandle As SafeRegistryHandle - - ' Windows API calls. - Private Declare Unicode Function RegOpenKeyEx Lib"advapi32.dll" _ - Alias "RegOpenKeyExW" (hKey As IntPtr, lpSubKey As String, _ - ulOptions As Integer, samDesired As Integer, _ - ByRef phkResult As IntPtr) As Integer - Private Declare Unicode Function RegQueryValueEx Lib "advapi32.dll" _ - Alias "RegQueryValueExW" (hKey As IntPtr, _ - lpValueName As String, lpReserved As Integer, _ - ByRef lpType As UInteger, lpData As String, _ - ByRef lpcbData As UInteger) As Integer - Private Declare Function RegSetValueEx Lib "advapi32.dll" _ - (hKey As IntPtr, _ - lpValueName As String, _ - reserved As Integer, dwType As UInteger, _ - lpData As String, _ - cpData As Integer) As Integer - Private Declare Function RegCloseKey Lib "advapi32.dll" _ - (hKey As IntPtr) As Integer - - ' Windows API constants. - Private Const HKEY_CLASSES_ROOT As Integer = &h80000000 - Private Const ERROR_SUCCESS As Integer = 0 - - Private Const KEY_QUERY_VALUE As Integer = 1 - Private Const KEY_SET_VALUE As Integer = &h2 - - Private REG_SZ As UInteger = 1 - - Private Const MAX_PATH As Integer = 260 - - Public Sub New(fileExtension As String) - Dim retVal As Integer = 0 - Dim lpType As UInteger = 0 - - If Not fileExtension.StartsWith(".") Then - fileExtension = "." + fileExtension - End If - ext = fileExtension - - Dim hExtension As IntPtr = IntPtr.Zero - ' Get the file extension value. - retVal = RegOpenKeyEx(New IntPtr(HKEY_CLASSES_ROOT), fileExtension, 0, - KEY_QUERY_VALUE, hExtension) - if retVal <> ERROR_SUCCESS Then - Throw New Win32Exception(retVal) - End If - ' Instantiate the first SafeRegistryHandle. - hExtHandle = New SafeRegistryHandle(hExtension, True) - - Dim appId As New String(" "c, MAX_PATH) - Dim appIdLength As UInteger = CUInt(appId.Length) - retVal = RegQueryValueEx(hExtHandle.DangerousGetHandle(), String.Empty, _ - 0, lpType, appId, appIdLength) - if retVal <> ERROR_SUCCESS Then - Throw New Win32Exception(retVal) - End If - ' We no longer need the hExtension handle. - hExtHandle.Dispose() - - ' Determine the number of characters without the terminating null. - appId = appId.Substring(0, CInt(appIdLength) \ 2 - 1) + "\shell\open\Command" - - ' Open the application identifier key. - Dim exeName As New string(" "c, MAX_PATH) - Dim exeNameLength As UInteger = CUInt(exeName.Length) - Dim hAppId As IntPtr - retVal = RegOpenKeyEx(New IntPtr(HKEY_CLASSES_ROOT), appId, 0, - KEY_QUERY_VALUE Or KEY_SET_VALUE, hAppId) - If retVal <> ERROR_SUCCESS Then - Throw New Win32Exception(retVal) - End If - - ' Instantiate the second SafeRegistryHandle. - hAppIdHandle = New SafeRegistryHandle(hAppId, True) - - ' Get the executable name for this file type. - Dim exePath As New string(" "c, MAX_PATH) - Dim exePathLength As UInteger = CUInt(exePath.Length) - retVal = RegQueryValueEx(hAppIdHandle.DangerousGetHandle(), _ - String.Empty, 0, lpType, exePath, exePathLength) - If retVal <> ERROR_SUCCESS Then - Throw New Win32Exception(retVal) - End If - ' Determine the number of characters without the terminating null. - exePath = exePath.Substring(0, CInt(exePathLength) \ 2 - 1) - - exePath = Environment.ExpandEnvironmentVariables(exePath) - Dim position As Integer = exePath.IndexOf("%"c) - If position >= 0 Then - args = exePath.Substring(position) - ' Remove command line parameters ('%0', etc.). - exePath = exePath.Substring(0, position).Trim() - End If - openCmd = exePath - End Sub - - Public ReadOnly Property Extension As String - Get - Return ext - End Get - End Property - - Public Property Open As String - Get - Return openCmd - End Get - Set - If hAppIdHandle.IsInvalid Or hAppIdHandle.IsClosed Then - Throw New InvalidOperationException("Cannot write to registry key.") - End If - If Not File.Exists(value) Then - Dim message As String = String.Format("'{0}' does not exist", value) - Throw New FileNotFoundException(message) - End If - Dim cmd As String = value + " %1" - Dim retVal As Integer = RegSetValueEx(hAppIdHandle.DangerousGetHandle(), String.Empty, 0, - REG_SZ, value, value.Length + 1) - If retVal <> ERROR_SUCCESS Then - Throw New Win32Exception(retVal) - End If - End Set - End Property - - Public Sub Dispose() _ - Implements IDisposable.Dispose - Dispose(disposing:=True) - GC.SuppressFinalize(Me) - End Sub - - Protected Sub Dispose(disposing As Boolean) - ' Ordinarily, we release unmanaged resources here - ' but all are wrapped by safe handles. - - ' Release disposable objects. - If disposing Then - If hExtHandle IsNot Nothing Then hExtHandle.Dispose() - If hAppIdHandle IsNot Nothing Then hAppIdHandle.Dispose() - End If - End Sub -End Class -' - -Module Example - Public Sub Main() - Dim fa As New FileAssociationInfo(".txt") - Console.WriteLine("{0} files are handled by '{1}'", fa.Extension, fa.Open) - fa.Dispose() - End Sub -End Module - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/direct1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/direct1.vb deleted file mode 100644 index 664b4d3b96a..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/direct1.vb +++ /dev/null @@ -1,56 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Public Structure Number - Private n As Integer - - Public Sub New(value As Integer) - n = value - End Sub - - Public ReadOnly Property Value As Integer - Get - Return n - End Get - End Property - - Public Overrides Function Equals(obj As Object) As Boolean - If obj Is Nothing OrElse Not TypeOf obj Is Number Then - Return False - Else - Return n = CType(obj, Number).n - End If - End Function - - Public Overrides Function GetHashCode() As Integer - Return n - End Function - - Public Overrides Function ToString() As String - Return n.ToString() - End Function -End Structure - -Module Example - Public Sub Main() - Dim rnd As New Random() - For ctr As Integer = 0 To 9 - Dim randomN As Integer = rnd.Next(Int32.MinValue, Int32.MaxValue) - Dim n As New Number(randomN) - Console.WriteLine("n = {0,12}, hash code = {1,12}", n, n.GetHashCode()) - Next - End Sub -End Module -' The example displays output like the following: -' n = -634398368, hash code = -634398368 -' n = 2136747730, hash code = 2136747730 -' n = -1973417279, hash code = -1973417279 -' n = 1101478715, hash code = 1101478715 -' n = 2078057429, hash code = 2078057429 -' n = -334489950, hash code = -334489950 -' n = -68958230, hash code = -68958230 -' n = -379951485, hash code = -379951485 -' n = -31553685, hash code = -31553685 -' n = 2105429592, hash code = 2105429592 -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/shift1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/shift1.vb deleted file mode 100644 index b4d66d61bb5..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/shift1.vb +++ /dev/null @@ -1,64 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Public Structure Point - Private x As Integer - Private y As Integer - - Public Sub New(x As Integer, y As Integer) - Me.x = x - Me.y = y - End Sub - - Public Overrides Function Equals(obj As Object) As Boolean - If Not TypeOf obj Is Point Then Return False - - Dim p As Point = CType(obj, Point) - Return x = p.x And y = p.y - End Function - - Public Overrides Function GetHashCode() As Integer - Return ShiftAndWrap(x.GetHashCode(), 2) XOr y.GetHashCode() - End Function - - Private Function ShiftAndWrap(value As Integer, positions As Integer) As Integer - positions = positions And &h1F - - ' Save the existing bit pattern, but interpret it as an unsigned integer. - Dim number As UInteger = BitConverter.ToUInt32(BitConverter.GetBytes(value), 0) - ' Preserve the bits to be discarded. - Dim wrapped AS UInteger = number >> (32 - positions) - ' Shift and wrap the discarded bits. - Return BitConverter.ToInt32(BitConverter.GetBytes((number << positions) Or wrapped), 0) - End Function -End Structure - -Module Example - Public Sub Main() - Dim pt As New Point(5, 8) - Console.WriteLine(pt.GetHashCode()) - - pt = New Point(8, 5) - Console.WriteLine(pt.GetHashCode()) - End Sub -End Module -' The example displays the following output: -' 28 -' 37 -' - -Public Class Utility - ' - Public Function ShiftAndWrap(value As Integer, positions As Integer) As Integer - positions = positions And &h1F - - ' Save the existing bit pattern, but interpret it as an unsigned integer. - Dim number As UInteger = BitConverter.ToUInt32(BitConverter.GetBytes(value), 0) - ' Preserve the bits to be discarded. - Dim wrapped AS UInteger = number >> (32 - positions) - ' Shift and wrap the discarded bits. - Return BitConverter.ToInt32(BitConverter.GetBytes((number << positions) Or wrapped), 0) - End Function - ' -End Class diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/xor1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/xor1.vb deleted file mode 100644 index bfd660ab2b5..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/xor1.vb +++ /dev/null @@ -1,34 +0,0 @@ -' -' A type that represents a 2-D point. -Public Structure Point - Private x As Integer - Private y As Integer - - Public Sub New(x As Integer, y As Integer) - Me.x = x - Me.y = y - End Sub - - Public Overrides Function Equals(obj As Object) As Boolean - If Not TypeOf obj Is Point Then Return False - - Dim p As Point = CType(obj, Point) - Return x = p.x And y = p.y - End Function - - Public Overrides Function GetHashCode() As Integer - Return x Xor y - End Function -End Structure - -Public Module Example - Public Sub Main() - Dim pt As New Point(5, 8) - Console.WriteLine(pt.GetHashCode()) - - pt = New Point(8, 5) - Console.WriteLine(pt.GetHashCode()) - End Sub -End Module -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/xor2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/xor2.vb deleted file mode 100644 index 58e5e6afeec..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/xor2.vb +++ /dev/null @@ -1,35 +0,0 @@ -' -Public Structure Point - Private x As Integer - Private y As Integer - - Public Sub New(x As Integer, y As Integer) - Me.x = x - Me.y = y - End Sub - - Public Overrides Function Equals(obj As Object) As Boolean - If Not TypeOf obj Is Point Then Return False - - Dim p As Point = CType(obj, Point) - Return x = p.x And y = p.y - End Function - - Public Overrides Function GetHashCode() As Integer - Return Tuple.Create(x, y).GetHashCode() - End Function -End Structure - -Public Module Example - Public Sub Main() - Dim pt As New Point(5, 8) - Console.WriteLine(pt.GetHashCode()) - - pt = New Point(8, 5) - Console.WriteLine(pt.GetHashCode()) - End Sub -End Module -' The example displays the following output: -' 173 -' 269 -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/array1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/array1.vb deleted file mode 100644 index 22c69d9d017..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/array1.vb +++ /dev/null @@ -1,19 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Collections.Generic - -Module Example - Public Sub Main() - Dim values() As Integer = { 1, 2, 4, 8, 16, 32, 64, 128 } - Console.WriteLine(values.ToString()) - - Dim list As New List(Of Integer)(values) - Console.WriteLine(list.ToString()) - End Sub -End Module -' The example displays the following output: -' System.Int32[] -' System.Collections.Generic.List`1[System.Int32] -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/customize1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/customize1.vb deleted file mode 100644 index 295e5f2e487..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/customize1.vb +++ /dev/null @@ -1,43 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Collections.Generic - -Public Class CList(Of T) : Inherits List(Of T) - Public Sub New(capacity As Integer) - MyBase.New(capacity) - End Sub - - Public Sub New(collection As IEnumerable(Of T)) - MyBase.New(collection) - End Sub - - Public Sub New() - MyBase.New() - End Sub - - Public Overrides Function ToString() As String - Dim retVal As String = String.Empty - For Each item As T In Me - If String.IsNullOrEmpty(retval) Then - retVal += item.ToString() - Else - retval += String.Format(", {0}", item) - End If - Next - Return retVal - End Function -End Class - -Module Example - Public Sub Main() - Dim list2 As New CList(Of Integer) - list2.Add(1000) - list2.Add(2000) - Console.WriteLine(list2.ToString()) - End Sub -End Module -' The example displays the following output: -' 1000, 2000 -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/customize2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/customize2.vb deleted file mode 100644 index 74d3e321993..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/customize2.vb +++ /dev/null @@ -1,49 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Collections.Generic -Imports System.Runtime.CompilerServices - -Public Module StringExtensions - - Public Function ToString2(Of T)(l As List(Of T)) As String - Dim retVal As String = "" - For Each item As T In l - retVal += String.Format("{0}{1}", If(String.IsNullOrEmpty(retVal), - "", ", "), - item) - Next - Return If(String.IsNullOrEmpty(retVal), "{}", "{ " + retVal + " }") - End Function - - - Public Function ToString(Of T)(l As List(Of T), fmt As String) As String - Dim retVal As String = String.Empty - For Each item In l - Dim ifmt As IFormattable = TryCast(item, IFormattable) - If ifmt IsNot Nothing Then - retVal += String.Format("{0}{1}", - If(String.IsNullOrEmpty(retval), - "", ", "), ifmt.ToString(fmt, Nothing)) - Else - retVal += ToString2(l) - End If - Next - Return If(String.IsNullOrEmpty(retVal), "{}", "{ " + retVal + " }") - End Function -End Module - -Module Example - Public Sub Main() - Dim list As New List(Of Integer) - list.Add(1000) - list.Add(2000) - Console.WriteLine(list.ToString2()) - Console.WriteLine(list.ToString("N0")) - End Sub -End Module -' The example displays the following output: -' { 1000, 2000 } -' { 1,000, 2,000 } -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring1.vb deleted file mode 100644 index eadad7a54dc..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring1.vb +++ /dev/null @@ -1,14 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim obj As New Object() - Console.WriteLine(obj.ToString()) - End Sub -End Module -' The example displays the following output: -' System.Object -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring2.vb deleted file mode 100644 index 30e0d6c1bbb..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring2.vb +++ /dev/null @@ -1,20 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports Examples - -Namespace Examples - Public Class Object1 - End Class -End Namespace - -Module Example - Public Sub Main() - Dim obj1 As New Object1() - Console.WriteLine(obj1.ToString()) - End Sub -End Module -' The example displays the following output: -' Examples.Object1 -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring3.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring3.vb deleted file mode 100644 index fb70cb4f2d7..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring3.vb +++ /dev/null @@ -1,25 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Public Class Object2 - Private value As Object - - Public Sub New(value As Object) - Me.value = value - End Sub - - Public Overrides Function ToString() As String - Return MyBase.ToString + ": " + value.ToString() - End Function -End Class - -Module Example - Public Sub Main() - Dim obj2 As New Object2("a"c) - Console.WriteLine(obj2.ToString()) - End Sub -End Module -' The example displays the following output: -' Object2: a -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostringoverload1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostringoverload1.vb deleted file mode 100644 index a540766f0e0..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostringoverload1.vb +++ /dev/null @@ -1,80 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Public Class Automobile - Private _doors As Integer - Private _cylinders As String - Private _year As Integer - Private _model As String - - Public Sub New(model As String, year As Integer, doors As Integer, - cylinders As String) - _model = model - _year = year - _doors = doors - _cylinders = cylinders - End Sub - - Public ReadOnly Property Doors As Integer - Get - Return _doors - End Get - End Property - - Public ReadOnly Property Model As String - Get - Return _model - End Get - End Property - - Public ReadOnly Property Year As Integer - Get - Return _year - End Get - End Property - - Public ReadOnly Property Cylinders As String - Get - Return _cylinders - End Get - End Property - - Public Overrides Function ToString() As String - Return ToString("G") - End Function - - Public Overloads Function ToString(fmt As String) As String - If String.IsNullOrEmpty(fmt) Then fmt = "G" - - Select Case fmt.ToUpperInvariant() - Case "G" - Return String.Format("{0} {1}", _year, _model) - Case "D" - Return String.Format("{0} {1}, {2} dr.", - _year, _model, _doors) - Case "C" - Return String.Format("{0} {1}, {2}", - _year, _model, _cylinders) - Case "A" - Return String.Format("{0} {1}, {2} dr. {3}", - _year, _model, _doors, _cylinders) - Case Else - Dim msg As String = String.Format("'{0}' is an invalid format string", - fmt) - Throw New ArgumentException(msg) - End Select - End Function -End Class - -Module Example - Public Sub Main() - Dim auto As New Automobile("Lynx", 2016, 4, "V8") - Console.WriteLine(auto.ToString()) - Console.WriteLine(auto.ToString("A")) - End Sub -End Module -' The example displays the following output: -' 2016 Lynx -' 2016 Lynx, 4 dr. V8 -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostringoverload2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostringoverload2.vb deleted file mode 100644 index 01f23f2b13a..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostringoverload2.vb +++ /dev/null @@ -1,26 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization - -Module Example - Public Sub Main() - Dim cultureNames() As String = { "en-US", "en-GB", "fr-FR", - "hr-HR", "ja-JP" } - Dim value As Decimal = 1603.49d - For Each cultureName In cultureNames - Dim culture As New CultureInfo(cultureName) - Console.WriteLine("{0}: {1}", culture.Name, - value.ToString("C2", culture)) - Next - End Sub -End Module -' The example displays the following output: -' en-US: $1,603.49 -' en-GB: £1,603.49 -' fr-FR: 1 603,49 € -' hr-HR: 1.603,49 kn -' ja-JP: ¥1,603.49 -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/showdate.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/showdate.vb deleted file mode 100644 index 5b75d8c8c38..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/showdate.vb +++ /dev/null @@ -1,42 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization -Imports System.Resources -Imports System.Threading - - - -Module Example - Public Sub Main() - Dim cultureNames() As String = { "en-US", "fr-FR", "ru-RU", "sv-SE" } - Dim rm As New ResourceManager("DateStrings", - GetType(Example).Assembly) - - For Each cultureName In cultureNames - Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture(cultureName) - Thread.CurrentThread.CurrentCulture = culture - Thread.CurrentThread.CurrentUICulture = culture - - Console.WriteLine("Current UI Culture: {0}", - CultureInfo.CurrentUICulture.Name) - Dim dateString As String = rm.GetString("DateStart") - Console.WriteLine("{0} {1:M}.", dateString, Date.Now) - Console.WriteLine() - Next - End Sub -End Module -' The example displays output similar to the following: -' Current UI Culture: en-US -' Today is February 03. -' -' Current UI Culture: fr-FR -' Aujourd'hui, c'est le 3 février -' -' Current UI Culture: ru-RU -' Сегодня февраля 03. -' -' Current UI Culture: sv-SE -' Today is den 3 februari. -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/showdate2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/showdate2.vb deleted file mode 100644 index 2f5293878bd..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/showdate2.vb +++ /dev/null @@ -1,33 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization -Imports System.Resources -Imports System.Threading - - - -Module Example - Public Sub Main() - Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("ru-RU") - Thread.CurrentThread.CurrentUICulture = CultureInfo.CreateSpecificCulture("ru-RU") - - Dim cultureNames() As String = { "fr-FR", "sv-SE" } - Dim rm As New ResourceManager("DateStrings", - GetType(Example).Assembly) - - For Each cultureName In cultureNames - Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture(cultureName) - Dim dateString As String = rm.GetString("DateStart", culture) - Console.WriteLine("{0}: {1} {2}.", culture.DisplayName, dateString, - Date.Now.ToString("M", culture)) - Console.WriteLine() - Next - End Sub -End Module -' The example displays output similar to the following: -' French (France): Aujourd'hui, c'est le 7 février. -' -' Swedish (Sweden): Today is den 7 februari. -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.ctor/vb/example.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.ctor/vb/example.vb deleted file mode 100644 index 07ac3725e27..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.ctor/vb/example.vb +++ /dev/null @@ -1,24 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization -Imports System.Reflection -Imports System.Resources - -Module Example - Public Sub Main() - ' Retrieve the resource. - Dim rm As New ResourceManager("ExampleResources", - GetType(Example).Assembly) - Dim greeting As String = rm.GetString("Greeting") - - Console.Write("Enter your name: ") - Dim name As String = Console.ReadLine() - Console.WriteLine("{0} {1}!", greeting, name) - End Sub -End Module -' The example produces output similar to the following: -' Enter your name: John -' Hello John! -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.ctor/vb/greet.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.ctor/vb/greet.vb deleted file mode 100644 index cca544a6a4e..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.ctor/vb/greet.vb +++ /dev/null @@ -1,51 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Resources -Imports System.Globalization -Imports System.Threading - - - -Module Example - Public Sub Main() - Dim cultureNames() As String = {"en-US", "fr-FR", "ru-RU", "sv-SE" } - Dim noon As New Date(Date.Now.Year, Date.Now.Month, - Date.Now.Day, 12,0,0) - Dim evening As New Date(Date.Now.Year, Date.Now.Month, - Date.Now.Day, 18, 0, 0) - - Dim rm As New ResourceManager(GetType(GreetingResources)) - - For Each cultureName In cultureNames - Thread.CurrentThread.CurrentUICulture = CultureInfo.CreateSpecificCulture(cultureName) - Console.WriteLine("The current UI culture is {0}", - CultureInfo.CurrentUICulture.Name) - If Date.Now < noon Then - Console.WriteLine("{0}!", rm.GetString("Morning")) - ElseIf Date.Now < evening Then - Console.WriteLine("{0}!", rm.GetString("Afternoon")) - Else - Console.WriteLine("{0}!", rm.GetString("Evening")) - End If - Console.WriteLine() - Next - End Sub -End Module - -Friend Class GreetingResources -End Class -' The example displays output like the following: -' The current UI culture is en-US -' Good afternoon! -' -' The current UI culture is fr-FR -' Bonjour! -' -' The current UI culture is ru-RU -' Добрый день! -' -' The current UI culture is sv-SE -' Good afternoon! -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/createresources.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/createresources.vb deleted file mode 100644 index 34da5fc0ed4..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/createresources.vb +++ /dev/null @@ -1,61 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Resources - -Module CreateResource - Public Sub Main() - Dim en As New Numbers("one", "two", "three", "four", "five", - "six", "seven", "eight", "nine", "ten") - CreateResourceFile(en, "en") - Dim fr As New Numbers("un", "deux", "trois", "quatre", "cinq", - "six", "sept", "huit", "neuf", "dix") - CreateResourceFile(fr, "fr") - Dim pt As New Numbers("um", "dois", "três", "quatro", "cinco", - "seis", "sete", "oito", "nove", "dez") - CreateResourceFile(pt, "pt") - Dim ru As New Numbers("один", "два", "три", "четыре", "пять", - "шесть", "семь", "восемь", "девять", "десять") - CreateResourceFile(ru, "ru") - End Sub - - Public Sub CreateResourceFile(n As Numbers, lang As String) - Dim filename As String = ".\NumberResources" + - If(lang <> "en", "." + lang, "") + - ".resx" - Dim rr As New ResXResourceWriter(filename) - rr.AddResource("Numbers", n) - rr.Generate() - rr.Close() - End Sub -End Module -' - - Public Class Numbers - Public Readonly One As String - Public ReadOnly Two As String - Public ReadOnly Three As String - Public ReadOnly Four As String - Public ReadOnly Five As String - Public ReadOnly Six As String - Public ReadOnly Seven As String - Public ReadOnly Eight As String - Public ReadOnly Nine As String - Public ReadOnly Ten As String - - Public Sub New(one As String, two As String, three As String, four As String, - five As String, six As String, seven As String, eight As String, - nine As String, ten As String) - Me.One = one - Me.Two = two - Me.Three = three - Me.Four = four - Me.Five = five - Me.Six = six - Me.Seven = seven - Me.Eight = eight - Me.Nine = nine - Me.Ten = ten - End Sub -End Class diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/numberinfo.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/numberinfo.vb deleted file mode 100644 index 865fd86caa6..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/numberinfo.vb +++ /dev/null @@ -1,29 +0,0 @@ -' - Public Class Numbers - Public Readonly One As String - Public ReadOnly Two As String - Public ReadOnly Three As String - Public ReadOnly Four As String - Public ReadOnly Five As String - Public ReadOnly Six As String - Public ReadOnly Seven As String - Public ReadOnly Eight As String - Public ReadOnly Nine As String - Public ReadOnly Ten As String - - Public Sub New(one As String, two As String, three As String, four As String, - five As String, six As String, seven As String, eight As String, - nine As String, ten As String) - Me.One = one - Me.Two = two - Me.Three = three - Me.Four = four - Me.Five = five - Me.Six = six - Me.Seven = seven - Me.Eight = eight - Me.Nine = nine - Me.Ten = ten - End Sub -End Class -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/shownumbers.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/shownumbers.vb deleted file mode 100644 index 88578453f97..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/shownumbers.vb +++ /dev/null @@ -1,75 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Globalization -Imports System.Resources -Imports System.Threading - - - -Module Example - Dim cultureNames() As String = { "fr-FR", "pt-BR", "ru-RU" } - - Public Sub Main() - ' Make any non-default culture the current culture. - Dim rnd As New Random - Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture(cultureNames(rnd.Next(0, cultureNames.Length))) - Thread.CurrentThread.CurrentUICulture = culture - Console.WriteLine("The current culture is {0}", CultureInfo.CurrentUICulture.Name) - Console.WriteLine() - Dim enCulture As CultureInfo = CultureInfo.CreateSpecificCulture("en-US") - - Dim rm As New ResourceManager(GetType(NumberResources)) - Dim numbers As Numbers = CType(rm.GetObject("Numbers"), Numbers) - Dim numbersEn As Numbers = CType(rm.GetObject("Numbers", enCulture), Numbers) - Console.WriteLine("{0} --> {1}", numbers.One, numbersEn.One) - Console.WriteLine("{0} --> {1}", numbers.Three, numbersEn.Three) - Console.WriteLine("{0} --> {1}", numbers.Five, numbersEn.Five) - Console.WriteLine("{0} --> {1}", numbers.Seven, numbersEn.Seven) - Console.WriteLine("{0} --> {1}", numbers.Nine, numbersEn.Nine) - Console.WriteLine() - End Sub -End Module - - -Friend Class NumberResources -End Class - -' The example displays output like the following: -' The current culture is pt-BR -' -' um --> one -' três --> three -' cinco --> five -' sete --> seven -' nove --> nine -' - - Public Class Numbers - Public Readonly One As String - Public ReadOnly Two As String - Public ReadOnly Three As String - Public ReadOnly Four As String - Public ReadOnly Five As String - Public ReadOnly Six As String - Public ReadOnly Seven As String - Public ReadOnly Eight As String - Public ReadOnly Nine As String - Public ReadOnly Ten As String - - Public Sub New(one As String, two As String, three As String, four As String, - five As String, six As String, seven As String, eight As String, - nine As String, ten As String) - Me.One = one - Me.Two = two - Me.Three = three - Me.Four = four - Me.Five = five - Me.Six = six - Me.Seven = seven - Me.Eight = eight - Me.Nine = nine - Me.Ten = ten - End Sub -End Class diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.runtimehelpers.gethashcode/vb/gethashcodeex1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.runtimehelpers.gethashcode/vb/gethashcodeex1.vb deleted file mode 100644 index 23afc1bd622..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.runtimehelpers.gethashcode/vb/gethashcodeex1.vb +++ /dev/null @@ -1,52 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Runtime.CompilerServices - -Module Example - Public Sub Main() - Console.WriteLine("{0,-18} {1,6} {2,18:N0} {3,6} {4,18:N0}", - "", "Var 1", "Hash Code", "Var 2", "Hash Code") - Console.WriteLine() - - ' Get hash codes of two different strings. - Dim sc1 As String = "String #1" - Dim sc2 As String = "String #2" - ShowHashCodes("sc1", sc1, "sc2", sc2) - - ' Get hash codes of two identical non-interned strings. - Dim s1 As String = "This string" - Dim s2 As String = String.Format("{0} {1}", "This", "string") - ShowHashCodes("s1", s1, "s2", s2) - - ' Get hash codes of two (evidently concatenated) strings. - Dim si1 As String = "This is a string!" - Dim si2 As String = "This " + "is " + "a " + "string!" - ShowHashCodes("si1", si1, "si2", si2) - End Sub - - Private Sub ShowHashCodes(var1 As String, value1 As Object, - var2 As String, value2 As Object) - Console.WriteLine("{0,-18} {1,6} {2,18:X8} {3,6} {4,18:X8}", - "Obj.GetHashCode", var1, value1.GetHashCode, - var2, value2.GetHashCode) - - Console.WriteLine("{0,-18} {1,6} {2,18:X8} {3,6} {4,18:X8}", - "RTH.GetHashCode", var1, RuntimeHelpers.GetHashCode(value1), - var2, RuntimeHelpers.GetHashCode(value2)) - Console.WriteLine() - End Sub -End Module -' The example displays output similar to the following: -' Var 1 Hash Code Var 2 Hash Code -' -' Obj.GetHashCode sc1 94EABD27 sc2 94EABD24 -' RTH.GetHashCode sc1 02BF8098 sc2 00BB8560 -' -' Obj.GetHashCode s1 29C5A397 s2 29C5A397 -' RTH.GetHashCode s1 0297B065 s2 03553390 -' -' Obj.GetHashCode si1 941BCEA5 si2 941BCEA5 -' RTH.GetHashCode si1 01FED012 si2 01FED012 -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.single.compareto/vb/compareto2.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.single.compareto/vb/compareto2.vb deleted file mode 100644 index 11204a93390..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.single.compareto/vb/compareto2.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim value1 As Single = 16.5457 - Dim value2 As Single = value1 * CSng(3.8899982) / CSng(3.8899982) - Console.WriteLine("Comparing {0} and {1}: {2}", - value1, value2, value1.CompareTo(value2)) - Console.WriteLine() - Console.WriteLine("Comparing {0:R} and {1:R}: {2}", - value1, value2, value1.CompareTo(value2)) - End Sub -End Module -' The example displays the following output: -' Comparing 16.5457 and 16.5457: -1 -' -' Comparing 16.5457 and 16.545702: -1 -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.single.compareto/vb/compareto3.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.single.compareto/vb/compareto3.vb deleted file mode 100644 index 39f1771e102..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.single.compareto/vb/compareto3.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim value1 As Single = 16.5457 - Dim value2 As Object = value1 * CSng(3.8899982) / CSng(3.8899982) - Console.WriteLine("Comparing {0} and {1}: {2}", - value1, value2, value1.CompareTo(value2)) - Console.WriteLine() - Console.WriteLine("Comparing {0:R} and {1:R}: {2}", - value1, value2, value1.CompareTo(value2)) - End Sub -End Module -' The example displays the following output: -' Comparing 16.5457 and 16.5457: -1 -' -' Comparing 16.5457 and 16.545702: -1 -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.single.equals/vb/equalsabs1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.single.equals/vb/equalsabs1.vb deleted file mode 100644 index 7d623e79d33..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.single.equals/vb/equalsabs1.vb +++ /dev/null @@ -1,44 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim value1 As Single = .1 * 10 - Dim value2 As Single = 0 - For ctr As Integer = 0 To 9 - value2 += CSng(.1) - Next - - Console.WriteLine("{0:R} = {1:R}: {2}", value1, value2, - HasMinimalDifference(value1, value2, 1)) - End Sub - - Public Function HasMinimalDifference(value1 As Single, value2 As Single, units As Integer) As Boolean - Dim bytes() As Byte = BitConverter.GetBytes(value1) - Dim iValue1 As Integer = BitConverter.ToInt32(bytes, 0) - - bytes = BitConverter.GetBytes(value2) - Dim iValue2 As Integer = BitConverter.ToInt32(bytes, 0) - - ' If the signs are different, Return False except for +0 and -0. - If ((iValue1 >> 31) <> (iValue2 >> 31)) Then - If value1 = value2 Then - Return True - End If - Return False - End If - - Dim diff As Integer = Math.Abs(iValue1 - iValue2) - - If diff <= units Then - Return True - End If - - Return False - End Function -End Module -' The example displays the following output: -' 1 = 1.00000012: True -' - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.string.ctor/vb/ctor1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.string.ctor/vb/ctor1.vb deleted file mode 100644 index 07eb0b334d4..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.string.ctor/vb/ctor1.vb +++ /dev/null @@ -1,16 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim value1 As String = "This is a string." - Dim value2 As String = value1 - Console.WriteLine(value1) - Console.WriteLine(value2) - End Sub -End Module -' The example displays the following output: -' This is a string. -' This is a string. -' diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorempty/vb/NullString1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorempty/vb/NullString1.vb deleted file mode 100644 index 30fcd45a409..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorempty/vb/NullString1.vb +++ /dev/null @@ -1,34 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Module Example - Public Sub Main() - Dim s As String - - Console.WriteLine("The value of the string is '{0}'", s) - - Try - Console.WriteLine("String length is {0}", s.Length) - Catch e As NullReferenceException - Console.WriteLine(e.Message) - End Try - End Sub -End Module -' The example displays the following output: -' The value of the string is '' -' Object reference not set to an instance of an object. -' - -Public Class Empty - Public Sub Test() - ' - Dim s As String = "" - Console.WriteLine("The length of '{0}' is {1}.", s, s.Length) - ' The example displays the following output: - ' The length of '' is 0. - ' - End Sub -End Class - - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorempty/vb/isnullorempty1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorempty/vb/isnullorempty1.vb deleted file mode 100644 index 97b5f1b30ea..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorempty/vb/isnullorempty1.vb +++ /dev/null @@ -1,20 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -Module Example - Public Sub Main() - Dim s1 As String = Nothing - Dim s2 As String = "" - Console.WriteLine(TestForNullOrEmpty(s1)) - Console.WriteLine(TestForNullOrEmpty(s2)) - End Sub - - Private Function TestForNullOrEmpty(s As String) As Boolean - Dim result As Boolean - ' - result = s Is Nothing OrElse s = String.Empty - ' - Return result - End Function -End Module - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.timespan.parse/vb/parsefailure1.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.timespan.parse/vb/parsefailure1.vb deleted file mode 100644 index 9aeb188c916..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.timespan.parse/vb/parsefailure1.vb +++ /dev/null @@ -1,27 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -Module Example - Public Sub Main() - ' - Dim values() As String = { "000000006", "12.12:12:12.12345678" } - For Each value As String In values - Try - Dim interval As TimeSpan = TimeSpan.Parse(value) - Console.WriteLine("{0} --> {1}", value, interval) - Catch e As FormatException - Console.WriteLine("{0}: Bad Format", value) - Catch e As OverflowException - Console.WriteLine("{0}: Overflow", value) - End Try - Next - ' Output from .NET Framework 3.5 and earlier versions: - ' 000000006 --> 6.00:00:00 - ' 12.12:12:12.12345678: Bad Format - ' Output from .NET Framework 4: - ' 000000006: Overflow - ' 12.12:12:12.12345678: Overflow - ' - End Sub -End Module - diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.type.makegenerictype/vb/remarks.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.type.makegenerictype/vb/remarks.vb deleted file mode 100644 index 718a6eba3d1..00000000000 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.type.makegenerictype/vb/remarks.vb +++ /dev/null @@ -1,23 +0,0 @@ -' -Public Class Base(Of T, U) -End Class -Public Class Derived(Of V) - Inherits Base(Of Integer, V) -End Class -' - -' -Public Class Outermost(Of T) - Public Class Inner(Of U) - Public Class Innermost1(Of V) - End Class - Public Class Innermost2 - End Class - End Class -End Class -' - -Public Class ProgStubClass - Shared Sub Main() - End Sub -End Class \ No newline at end of file diff --git a/xml/System.Collections.ObjectModel/KeyedCollection`2.xml b/xml/System.Collections.ObjectModel/KeyedCollection`2.xml index a6caa537fc2..e49295e3f99 100644 --- a/xml/System.Collections.ObjectModel/KeyedCollection`2.xml +++ b/xml/System.Collections.ObjectModel/KeyedCollection`2.xml @@ -85,51 +85,51 @@ The type of items in the collection. Provides the abstract base class for a collection whose keys are embedded in the values. - class provides both O(1) indexed retrieval and keyed retrieval that approaches O(1). It is an abstract type, or more accurately an infinite set of abstract types, because each of its constructed generic types is an abstract base class. To use , derive your collection type from the appropriate constructed type. - - The class is a hybrid between a collection based on the generic interface and a collection based on the generic interface. Like collections based on the generic interface, is an indexed list of items. Like collections based on the generic interface, has a key associated with each element. - - Unlike dictionaries, an element of is not a key/value pair; instead, the entire element is the value and the key is embedded within the value. For example, an element of a collection derived from `KeyedCollection\` (`KeyedCollection(Of String, String)` in Visual Basic) might be "John Doe Jr." where the value is "John Doe Jr." and the key is "Doe"; or a collection of employee records containing integer keys could be derived from `KeyedCollection\`. The abstract method extracts the key from the element. - - By default, the includes a lookup dictionary that you can obtain with the property. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior is overridden by specifying a dictionary creation threshold when you create the . The lookup dictionary is created the first time the number of elements exceeds that threshold. If you specify -1 as the threshold, the lookup dictionary is never created. - + class provides both O(1) indexed retrieval and keyed retrieval that approaches O(1). It is an abstract type, or more accurately an infinite set of abstract types, because each of its constructed generic types is an abstract base class. To use , derive your collection type from the appropriate constructed type. + + The class is a hybrid between a collection based on the generic interface and a collection based on the generic interface. Like collections based on the generic interface, is an indexed list of items. Like collections based on the generic interface, has a key associated with each element. + + Unlike dictionaries, an element of is not a key/value pair; instead, the entire element is the value and the key is embedded within the value. For example, an element of a collection derived from `KeyedCollection\` (`KeyedCollection(Of String, String)` in Visual Basic) might be "John Doe Jr." where the value is "John Doe Jr." and the key is "Doe"; or a collection of employee records containing integer keys could be derived from `KeyedCollection\`. The abstract method extracts the key from the element. + + By default, the includes a lookup dictionary that you can obtain with the property. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior is overridden by specifying a dictionary creation threshold when you create the . The lookup dictionary is created the first time the number of elements exceeds that threshold. If you specify -1 as the threshold, the lookup dictionary is never created. + > [!NOTE] -> When the internal lookup dictionary is used, it contains references to all the items in the collection if `TItem` is a reference type, or copies of all the items in the collection if `TItem` is a value type. Thus, using the lookup dictionary may not be appropriate if `TItem` is a value type. - - You can access an item by its index or key by using the property. You can add items without a key, but these items can subsequently be accessed only by index. - - - -## Examples - This section contains two code examples. The first example shows the minimum code required to derive from , and demonstrates many of the inherited methods. The second example shows how to override the protected methods of to provide custom behavior. - - **Example 1** - - This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. - - The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . - +> When the internal lookup dictionary is used, it contains references to all the items in the collection if `TItem` is a reference type, or copies of all the items in the collection if `TItem` is a value type. Thus, using the lookup dictionary may not be appropriate if `TItem` is a value type. + + You can access an item by its index or key by using the property. You can add items without a key, but these items can subsequently be accessed only by index. + + + +## Examples + This section contains two code examples. The first example shows the minimum code required to derive from , and demonstrates many of the inherited methods. The second example shows how to override the protected methods of to provide custom behavior. + + **Example 1** + + This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. + + The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: - - **Example 2** - - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. - - The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. - - The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. - - This code example uses objects with immutable keys. For a code example that uses mutable keys, see . - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: + + **Example 2** + + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + + The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. + + The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. + + This code example uses objects with immutable keys. For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection2/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: + ]]> @@ -180,29 +180,29 @@ Initializes a new instance of the class that uses the default equality comparer. - created with this constructor uses the default generic equality comparer for the type of the key, obtained from . To specify a different generic equality comparer, use the constructor or the constructor. - - By default, the includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior can be overridden by using the constructor and specifying a dictionary creation threshold. - + created with this constructor uses the default generic equality comparer for the type of the key, obtained from . To specify a different generic equality comparer, use the constructor or the constructor. + + By default, the includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior can be overridden by using the constructor and specifying a dictionary creation threshold. + > [!NOTE] -> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. - - This constructor is an O(1) operation. - - - -## Examples - This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. - - The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . - +> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. + + This constructor is an O(1) operation. + + + +## Examples + This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. + + The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: + ]]> @@ -254,16 +254,16 @@ The implementation of the generic interface to use when comparing keys, or to use the default equality comparer for the type of the key, obtained from . Initializes a new instance of the class that uses the specified equality comparer. - includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior can be overridden by using the constructor and specifying a dictionary creation threshold. - + includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior can be overridden by using the constructor and specifying a dictionary creation threshold. + > [!NOTE] -> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. - - This constructor is an O(1) operation. - +> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. + + This constructor is an O(1) operation. + ]]> @@ -317,35 +317,35 @@ The number of elements the collection can hold without creating a lookup dictionary (0 creates the lookup dictionary when the first item is added), or -1 to specify that a lookup dictionary is never created. Initializes a new instance of the class that uses the specified equality comparer and creates a lookup dictionary when the specified threshold is exceeded. - includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This constructor allows you to override that behavior. Specify 0 to create the dictionary when the first element is added, 1 to create the dictionary when the second element is added, and so on. If you specify -1 as the threshold, the lookup dictionary is never created. - - For very small collections the improvement in retrieval speed provided by the lookup dictionary might not be worth the extra memory required by the dictionary. Setting a threshold allows you to decide when to make that tradeoff. - + includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This constructor allows you to override that behavior. Specify 0 to create the dictionary when the first element is added, 1 to create the dictionary when the second element is added, and so on. If you specify -1 as the threshold, the lookup dictionary is never created. + + For very small collections the improvement in retrieval speed provided by the lookup dictionary might not be worth the extra memory required by the dictionary. Setting a threshold allows you to decide when to make that tradeoff. + > [!NOTE] -> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. - - This constructor is an O(1) operation. - - - -## Examples - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. - - The code example uses the constructor with a threshold of 0, so that the internal dictionary is created the first time an object is added to the collection. - - The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. - - The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. - - This code example uses objects with immutable keys. For a code example that uses mutable keys, see . - +> Because the class is abstract (`MustInherit` in Visual Basic), you must derive from it in order to use it. In the constructor for your derived type, call the appropriate constructor. It is not necessary to expose functionality like the equality comparer or the dictionary creation threshold in your constructors. + + This constructor is an O(1) operation. + + + +## Examples + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + + The code example uses the constructor with a threshold of 0, so that the internal dictionary is created the first time an object is added to the collection. + + The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. + + The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. + + This code example uses objects with immutable keys. For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection2/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: + ]]> @@ -395,48 +395,30 @@ The element to change the key of. The new key for . Changes the key associated with the specified element in the lookup dictionary. - - . - - This method does nothing if the does not have a lookup dictionary. - - Every key in a must be unique. A key cannot be `null`. - - This method is an O(1) operation. - -## Notes for Implementers - Before modifying the key embedded in an item, you must call this method to update the key in the lookup dictionary. If the dictionary creation threshold is -1, calling this method is not necessary. - - Do not expose the method as a public method of a derived class. Misuse of this method puts the lookup dictionary out of sync with item keys. For example, setting the key to `null` and then setting it to another value adds multiple keys for an item to the lookup dictionary. Expose this method internally to allow mutable item keys: When the key for an item changes, this method is used to change the key in the lookup dictionary. - - - -## Examples - The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. - - The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. - - In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/ChangeItemKey/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for KeyedCollection<TKey,TItem>.ChangeItemKey. + + method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. + +The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. + +In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. + +:::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/ChangeItemKey/source.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: + ]]> + - is . - - -or- - + is . + + -or- + is . - is not found. - - -or- - + is not found. + + -or- + already exists in the . @@ -480,50 +462,51 @@ Removes all elements from the . - is using a lookup dictionary, it will continue to use a lookup dictionary even though the number of elements is again under the threshold. - - This method is an O(`n`) operation, where `n` is . - -## Notes for Implementers - Override this method to provide customized behavior for the method, inherited from the generic class. - - Call the base class implementation of this method to clear the underlying collection and to clear the lookup dictionary. - - - -## Examples - This section contains two code examples that demonstrate overriding the method to provide custom behavior for clearing all objects from the collection. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. - - Example 1 - - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. - - The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. - - The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. - - This code example uses objects with immutable keys. For a code example that uses mutable keys, see . - + is using a lookup dictionary, it will continue to use a lookup dictionary even though the number of elements is again under the threshold. + + This method is an O(`n`) operation, where `n` is . + +## Notes for Implementers + + Override this method to provide customized behavior for the method, inherited from the generic class. + + Call the base class implementation of this method to clear the underlying collection and to clear the lookup dictionary. + +## Examples + + This section contains two code examples that demonstrate overriding the method to provide custom behavior for clearing all objects from the collection. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. + + Example 1 + + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + + The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. + + The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. + + This code example uses objects with immutable keys. For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection2/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: - - Example 2 - - The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. - - The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. - - In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: + + Example 2 + + The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. + + The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. + + In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. + :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/ChangeItemKey/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: + ]]> @@ -568,11 +551,11 @@ Gets the generic equality comparer that is used to determine equality of keys in the collection. The implementation of the generic interface that is used to determine equality of keys in the collection. - @@ -620,24 +603,24 @@ if the contains an element with the specified key; otherwise, . - has a lookup dictionary, `key` is used to search the dictionary. If there is no lookup dictionary, the key of each element is extracted using the method and compared with the specified key. - - This method is an O(1) operation if the has a lookup dictionary; otherwise it is an O(`n`) operation, where `n` is . - - - -## Examples - This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. - - The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . - + has a lookup dictionary, `key` is used to search the dictionary. If there is no lookup dictionary, the key of each element is extracted using the method and compared with the specified key. + + This method is an O(1) operation if the has a lookup dictionary; otherwise it is an O(`n`) operation, where `n` is . + + + +## Examples + This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. + + The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: + ]]> @@ -690,25 +673,25 @@ Gets the lookup dictionary of the . The lookup dictionary of the , if it exists; otherwise, . - includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior can be overridden by using the constructor and specifying a dictionary creation threshold. - - Retrieving the value of this property is an O(1) operation. - - - -## Examples - The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. - - The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. - - In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. - + includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior can be overridden by using the constructor and specifying a dictionary creation threshold. + + Retrieving the value of this property is an O(1) operation. + + + +## Examples + The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. + + The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. + + In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. + :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/ChangeItemKey/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: + ]]> @@ -756,29 +739,30 @@ When implemented in a derived class, extracts the key from the specified element. The key for the specified element. - . - - You can implement this method to return `null` for a collection that contains items without keys, in which case the items can be accessed only by their index. This method is an O(1) operation. - -## Notes for Implementers - You must override this method to provide the dictionary with a way to extract keys from items in the dictionary. - - This method is called internally. It is not necessary for it to be public. - - - -## Examples - This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. - - The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . - + . + + You can implement this method to return `null` for a collection that contains items without keys, in which case the items can be accessed only by their index. This method is an O(1) operation. + +## Notes for Implementers + + You must override this method to provide the dictionary with a way to extract keys from items in the dictionary. + + This method is called internally. It is not necessary for it to be public. + +## Examples + + This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. + + The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: + ]]> @@ -828,57 +812,58 @@ The object to insert. Inserts an element into the at the specified index. - , `item` is added to the end of the . - - This method is an O(`n`) operation, where `n` is . - - is called by the and methods. - -## Notes for Implementers - Override this method to provide customized behavior for the and methods, inherited from the generic class. - - Call the base class implementation of this method to insert the item into the underlying collection and to update the lookup dictionary. - - - -## Examples - This section contains two code examples that demonstrate overriding the method to provide custom behavior for adding or inserting objects into the collection. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. - - Example 1 - - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. - - The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. - - The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. - - This code example uses objects with immutable keys. For a code example that uses mutable keys, see . - + , `item` is added to the end of the . + + This method is an O(`n`) operation, where `n` is . + + is called by the and methods. + +## Notes for Implementers + + Override this method to provide customized behavior for the and methods, inherited from the generic class. + + Call the base class implementation of this method to insert the item into the underlying collection and to update the lookup dictionary. + +## Examples + + This section contains two code examples that demonstrate overriding the method to provide custom behavior for adding or inserting objects into the collection. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. + + Example 1 + + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + + The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. + + The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. + + This code example uses objects with immutable keys. For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection2/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: - - Example 2 - - The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. - - The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. - - In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: + + Example 2 + + The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. + + The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. + + In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. + :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/ChangeItemKey/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: + ]]> - is less than 0. - - -or- - + is less than 0. + + -or- + is greater than . @@ -925,31 +910,31 @@ Gets the element with the specified key. The element with the specified key. If an element with the specified key is not found, an exception is thrown. - [!NOTE] -> This property is distinct from the inherited property, which gets and sets elements by numeric index. However, if `TKey` is of type , this property masks the inherited property. In that case, you can access the inherited property by casting the to its base type. For example, `KeyedCollection` (`KeyedCollection(Of Integer, MyType)` in Visual Basic, `KeyedCollection` in C++) can be cast to `Collection` (`Collection(Of MyType)` in Visual Basic, `Collection` in C++). - - If the has a lookup dictionary, `key` is used to retrieve the element from the dictionary. If there is no lookup dictionary, the key of each element is extracted using the method and compared with the specified key. - - The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. - +> This property is distinct from the inherited property, which gets and sets elements by numeric index. However, if `TKey` is of type , this property masks the inherited property. In that case, you can access the inherited property by casting the to its base type. For example, `KeyedCollection` (`KeyedCollection(Of Integer, MyType)` in Visual Basic, `KeyedCollection` in C++) can be cast to `Collection` (`Collection(Of MyType)` in Visual Basic, `Collection` in C++). + + If the has a lookup dictionary, `key` is used to retrieve the element from the dictionary. If there is no lookup dictionary, the key of each element is extracted using the method and compared with the specified key. + + The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + Retrieving the value of this property is an O(1) operation if the has a lookup dictionary; otherwise it is an O(`n`) operation, where `n` is . -## Examples - This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. - - The code example calls both the property, which is read-only and retrieves by key, and the property, which is settable and retrieves by index. It shows how to access the latter property when the objects in the derived collection have integer keys, indistinguishable from the integers used for indexed retrieval. - - The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . - +## Examples + This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. + + The code example calls both the property, which is read-only and retrieves by key, and the property, which is settable and retrieves by index. It shows how to access the latter property when the objects in the derived collection have integer keys, indistinguishable from the integers used for indexed retrieval. + + The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: + ]]> @@ -1001,31 +986,31 @@ if the element is successfully removed; otherwise, . This method also returns if is not found in the . - is using a lookup dictionary, it will continue to use a lookup dictionary even though the number of elements is again under the threshold. - + is using a lookup dictionary, it will continue to use a lookup dictionary even though the number of elements is again under the threshold. + > [!NOTE] -> To customize the behavior of this method, override the method. - - This method is an O(`n`) operation, where `n` is . - - - -## Examples - This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. - - The example demonstrates method inherited from , which removes the item with a specified key, and also the and methods inherited from , which remove by object and by index respectively. - - The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . - +> To customize the behavior of this method, override the method. + + This method is an O(`n`) operation, where `n` is . + + + +## Examples + This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. + + The example demonstrates method inherited from , which removes the item with a specified key, and also the and methods inherited from , which remove by object and by index respectively. + + The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection/VB/source.vb" id="Snippet1"::: + ]]> @@ -1075,50 +1060,51 @@ The index of the element to remove. Removes the element at the specified index of the . - is using a lookup dictionary, it will continue to use a lookup dictionary even though the number of elements is again under the threshold. - - This method is an O(`n`) operation, where `n` is . - -## Notes for Implementers - Override this method to provide customized behavior for the and methods, inherited from the generic class, and the method. - - Call the base class implementation of this method to remove the item from the underlying collection and to update the lookup dictionary. - - - -## Examples - This section contains two code examples that demonstrate overriding the method to provide custom behavior for removing objects from the collection. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. - - Example 1 - - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. - - The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. - - The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. - - This code example uses objects with immutable keys. For a code example that uses mutable keys, see . - + is using a lookup dictionary, it will continue to use a lookup dictionary even though the number of elements is again under the threshold. + + This method is an O(`n`) operation, where `n` is . + +## Notes for Implementers + + Override this method to provide customized behavior for the and methods, inherited from the generic class, and the method. + + Call the base class implementation of this method to remove the item from the underlying collection and to update the lookup dictionary. + +## Examples + + This section contains two code examples that demonstrate overriding the method to provide custom behavior for removing objects from the collection. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. + + Example 1 + + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + + The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. + + The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. + + This code example uses objects with immutable keys. For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection2/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: - - Example 2 - - The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. - - The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. - - In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: + + Example 2 + + The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. + + The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. + + In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. + :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/ChangeItemKey/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: + ]]> @@ -1168,51 +1154,52 @@ The new item. Replaces the item at the specified index with the specified item. - property inherited from the generic class. - + property inherited from the generic class. + > [!NOTE] -> This method does not affect the behavior of the property, which is read-only. - - Call the base class implementation of this method to set the item in the underlying collection and to update the lookup dictionary. - - - -## Examples - This section contains two code examples that demonstrate overriding the method to provide custom behavior for setting the property. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. - - Example 1 - - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. - - The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. - - The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. - - This code example uses objects with immutable keys. For a code example that uses mutable keys, see . - +> This method does not affect the behavior of the property, which is read-only. + + Call the base class implementation of this method to set the item in the underlying collection and to update the lookup dictionary. + +## Examples + + This section contains two code examples that demonstrate overriding the method to provide custom behavior for setting the property. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. + + Example 1 + + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + + The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. + + The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the `Main` method of the `Demo` class. + + This code example uses objects with immutable keys. For a code example that uses mutable keys, see . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/KeyedCollection2/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/Overview/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: - - Example 2 - - The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. - - The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. - - In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollection2/vb/source.vb" id="Snippet1"::: + + Example 2 + + The following code example shows how to override the protected method to support mutable keys, and how to override the protected , , , and methods to maintain the integrity of the keys and the collection. + + The code example creates the `MutableKeys` collection, which derives from , and the `MutableKey` class. The `MutableKey` class has a settable `Key` property. When a new key is assigned to the property, the property setter calls the `internal` (`Friend` in Visual Basic) `ChangeKey` method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed. + + In order to maintain the connection between a `MutableKey` object and the `MutableKeys` collection and to prevent an object from being inserted into two collections, the `MutableKey` class has an `internal` (`Friend` in Visual Basic) `Collection` field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the method. The field is set when the item is added to a collection and cleared when the item is removed. + :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/KeyedCollectionTKey,TItem/ChangeItemKey/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/KeyedCollectionMutable/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Collections/ArrayList.xml b/xml/System.Collections/ArrayList.xml index 0ad9264eae3..3bcc8bdb2ee 100644 --- a/xml/System.Collections/ArrayList.xml +++ b/xml/System.Collections/ArrayList.xml @@ -398,19 +398,13 @@ The wrapper around the . does not copy the contents of . Instead, it only creates an wrapper around ; therefore, changes to the also affect the . -## Remarks - does not copy the contents of . Instead, it only creates an wrapper around ; therefore, changes to the also affect the . - - The class provides generic , and methods. This wrapper can be a means to use those methods on ; however, performing these generic operations through the wrapper might be less efficient than operations applied directly on the . - - This method is an `O(1)` operation. - -## Version Compatibility - In the .NET Framework version 1.0 and 1.1, calling the method overload on the wrapper returned an enumerator that treated the second argument as an upper bound rather than as a count. In the .NET Framework 2.0 the second argument is correctly treated as a count. +The class provides generic , and methods. This wrapper can be a means to use those methods on ; however, performing these generic operations through the wrapper might be less efficient than operations applied directly on the . - ]]> - +This method is an `O(1)` operation. + ]]> + is . @@ -1837,11 +1831,6 @@ This method is an `O(1)` operation. -## Version Compatibility - In the .NET Framework versions 1.0 and 1.1, the enumerator for an wrapper returned by the method treated the second argument as an upper bound rather than as a count. In the .NET Framework 2.0 the second argument is correctly treated as a count. - - - ## Examples The following example gets the enumerator for an , and the enumerator for a range of elements in the . diff --git a/xml/System.ComponentModel.Composition.Hosting/AssemblyCatalog.xml b/xml/System.ComponentModel.Composition.Hosting/AssemblyCatalog.xml index 4fa37fb01d3..a77284271de 100644 --- a/xml/System.ComponentModel.Composition.Hosting/AssemblyCatalog.xml +++ b/xml/System.ComponentModel.Composition.Hosting/AssemblyCatalog.xml @@ -36,22 +36,22 @@ Discovers attributed parts in a managed code assembly. - is used to parse all the parts present in a specified assembly. The target assembly can be indicated either by object reference or by path. - + is used to parse all the parts present in a specified assembly. The target assembly can be indicated either by object reference or by path. + > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + This type is thread safe. - -## Examples - The following code demonstrates the common scenario of an application creating an to parse its own assembly. This is a straightforward way to load parts contained in a single project into the Managed Extensibility Framework (MEF). - + +## Examples + The following code demonstrates the common scenario of an application creating an to parse its own assembly. This is a straightforward way to load parts contained in a single project into the Managed Extensibility Framework (MEF). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Composition.Hosting/CompositionContainer/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/composition.compositioncontainer/vb/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/composition.compositioncontainer/vb/module1.vb" id="Snippet1"::: + ]]> @@ -94,10 +94,10 @@ Initializes a new instance of the class with the specified assembly. To be added. - is . - - -or- - + is . + + -or- + was loaded in the reflection-only context. @@ -128,25 +128,25 @@ A string that specifies the code base of the assembly (that is, the path to the assembly file) that contains the attributed objects to add to the object. Initializes a new instance of the class with the specified code base. - - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + Version 2.0 or earlier of the common language runtime is currently loaded and was compiled with a later version. The caller does not have path discovery permission. - could not be loaded. - - -or- - + could not be loaded. + + -or- + specified a directory. is . @@ -181,10 +181,10 @@ Initializes a new instance of the class with the specified assembly. To be added. - or is . - - -or- - + or is . + + -or- + was loaded in the reflection-only context. @@ -212,10 +212,10 @@ Initializes a new instance of the class with the specified assembly and reflection context. To be added. - or is . - - -or- - + or is . + + -or- + was loaded in the reflection-only context. @@ -247,17 +247,17 @@ The assembly referenced by `codeBase` is loaded into the Load context. ]]> - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + Version 2.0 or later of the common language runtime is currently loaded and was compiled with a later version. The caller does not have path discovery permission. - could not be loaded. - - -or- - + could not be loaded. + + -or- + specified a directory. or is . @@ -294,17 +294,17 @@ The assembly referenced by `codeBase` is loaded into the Load context. - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + Version 2.0 or later of the common language runtime is currently loaded and was compiled with a later version. The caller does not have path discovery permission. - could not be loaded. - - -or- - + could not be loaded. + + -or- + specified a directory. or is . @@ -341,10 +341,10 @@ The assembly referenced by `codeBase` is loaded into the Load context. Initializes a new instance of the class with the specified assembly and reflection context. To be added. - , , or is . - - -or- - + , , or is . + + -or- + was loaded in the reflection-only context. @@ -376,17 +376,17 @@ The assembly referenced by `codeBase` is loaded into the Load context. - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + Version 2.0 or later of the common language runtime is currently loaded and was compiled with a later version. The caller does not have path discovery permission. - could not be loaded. - - -or- - + could not be loaded. + + -or- + specified a directory. , or is . @@ -495,20 +495,10 @@ The assembly referenced by `codeBase` is loaded into the Load context. Conditions that specify which exports to match. Gets a collection of exports that match the conditions specified by the import definition. A collection of exports that match the conditions specified by . - - matches the conditions defined by -`definition`; instead, return an empty . - ]]> - + For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-hosting-assemblycatalog-getexports">Supplemental API remarks for System.ComponentModel.Composition.Hosting.AssemblyCatalog.GetExports</see>. - is . - - - The has been disposed. - + is . + The has been disposed. @@ -564,11 +554,11 @@ The assembly referenced by `codeBase` is loaded into the Load context. Gets the display name of the object. A string that represents the type and assembly of this object. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -604,11 +594,11 @@ The assembly referenced by `codeBase` is loaded into the Load context. Gets the composition element that this element originated from. Always . - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/CompositionScopeDefinition.xml b/xml/System.ComponentModel.Composition.Hosting/CompositionScopeDefinition.xml index 7d764f752ec..45aafa59503 100644 --- a/xml/System.ComponentModel.Composition.Hosting/CompositionScopeDefinition.xml +++ b/xml/System.ComponentModel.Composition.Hosting/CompositionScopeDefinition.xml @@ -36,13 +36,13 @@ Represents a node in a tree of scoped catalogs, reflecting an underlying catalog and its child scopes. - [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + ]]> @@ -242,15 +242,15 @@ to release managed and unmanaged resources; to release only unmanaged resources. Called by the and methods to release the managed and unmanaged resources used by the current instance of the class. - @@ -305,13 +305,7 @@ For more information, see [Implementing a Dispose method](/dotnet/standard/garba Conditions that specify which exports to match. Gets a collection of exports that match the conditions specified by the import definition. A collection of exports that match the specified conditions. - - that matches the conditions defined by `definition`, return an empty . - ]]> - + For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-hosting-compositionscopedefinition-getexports">Supplemental API remarks for System.ComponentModel.Composition.Hosting.CompositionScopeDefinition.GetExports</see>. is . diff --git a/xml/System.ComponentModel.Composition.Hosting/FilteredCatalog.xml b/xml/System.ComponentModel.Composition.Hosting/FilteredCatalog.xml index 377f5f21f5b..5fd56c58246 100644 --- a/xml/System.ComponentModel.Composition.Hosting/FilteredCatalog.xml +++ b/xml/System.ComponentModel.Composition.Hosting/FilteredCatalog.xml @@ -32,13 +32,13 @@ Represents a catalog after a filter function is applied to it. - [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + ]]> @@ -182,17 +182,17 @@ to release managed and unmanaged resources; to release only unmanaged resources. Called by the and methods to release the managed and unmanaged resources used by the current instance of the class. - @@ -245,13 +245,7 @@ The import to match. Gets the exported parts from this catalog that match the specified import. A collection of matching parts. - - matches the conditions defined by `definition`; instead, return an empty . - ]]> - + For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-hosting-filteredcatalog-getexports">Supplemental API remarks for System.ComponentModel.Composition.Hosting.FilteredCatalog.GetExports</see>. is . diff --git a/xml/System.ComponentModel.Composition.Primitives/ContractBasedImportDefinition.xml b/xml/System.ComponentModel.Composition.Primitives/ContractBasedImportDefinition.xml index 8c08df1bcc4..3c2ee6b4d2d 100644 --- a/xml/System.ComponentModel.Composition.Primitives/ContractBasedImportDefinition.xml +++ b/xml/System.ComponentModel.Composition.Primitives/ContractBasedImportDefinition.xml @@ -56,18 +56,7 @@ Initializes a new instance of the class. - - , , -, , -, -and properties. - ]]> - + For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-primitives-contractbasedimportdefinition--ctor">Supplemental API remarks for System.ComponentModel.Composition.Primitives.ContractBasedImportDefinition..ctor</see>. @@ -123,14 +112,14 @@ and is . - is an empty string (""). - - -or- - - contains an element that is . - - -or- - + is an empty string (""). + + -or- + + contains an element that is . + + -or- + is not one of the values. @@ -196,14 +185,14 @@ and is . - is an empty string (""). - - -or- - - contains an element that is . - - -or- - + is an empty string (""). + + -or- + + contains an element that is . + + -or- + is not one of the values. @@ -229,10 +218,10 @@ and An expression that contains a object that defines the conditions that must be matched for the to be satisfied by an . , , +This property returns an expression that defines conditions based on the +, , , and -properties. +properties. ]]> @@ -299,12 +288,12 @@ Overrides of this method can provide a more optimized execution of the Gets or sets a value that indicates that the importer requires a specific for the exports used to satisfy this import. - One of the following values: - - , if the importer does not require a specific . - - to require that all exports used should be shared by all importers in the container. - + One of the following values: + + , if the importer does not require a specific . + + to require that all exports used should be shared by all importers in the container. + to require that all exports used should be non-shared in the container. In this case, each importer receives a separate instance. To be added. @@ -336,11 +325,11 @@ Overrides of this method can provide a more optimized execution of the Gets the metadata names of the export required by the import definition. A collection of objects that contain the metadata names of the objects required by the . The default is an empty collection. - collection that contains an element that is `null`. If the definition does not contain required metadata, return an empty collection instead. - + collection that contains an element that is `null`. If the definition does not contain required metadata, return an empty collection instead. + ]]> diff --git a/xml/System.ComponentModel.Composition.Primitives/Export.xml b/xml/System.ComponentModel.Composition.Primitives/Export.xml index 2f9ebe355c1..bf9bb648226 100644 --- a/xml/System.ComponentModel.Composition.Primitives/Export.xml +++ b/xml/System.ComponentModel.Composition.Primitives/Export.xml @@ -57,11 +57,11 @@ Initializes a new instance of the class. - property and the method. - + property and the method. + ]]> @@ -98,10 +98,10 @@ Initializes a new instance of the class with the specified export definition and exported object getter. To be added. - is . - - -or- - + is . + + -or- + is . @@ -137,10 +137,10 @@ Initializes a new instance of the class with the specified contract name and exported value getter. To be added. - is . - - -or- - + is . + + -or- + is . is an empty string (""). @@ -187,10 +187,10 @@ Initializes a new instance of the class with the specified contract name, metadata, and exported value getter. To be added. - is . - - -or- - + is . + + -or- + is . is an empty string (""). @@ -217,11 +217,11 @@ Gets the definition that describes the contract that the export satisfies. A definition that describes the contract that the object satisfies. - This property was not overridden by a derived class. @@ -255,13 +255,7 @@ Returns the exported object the export provides. The exported object the export provides. - - - + For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-primitives-export-getexportedvaluecore">Supplemental API remarks for System.ComponentModel.Composition.Primitives.Export.GetExportedValueCore</see>. The method was not overridden by a derived class. An error occurred during composition. will contain a collection of errors that occurred. The current instance is an instance of , and the underlying exported value cannot be cast to T. @@ -296,11 +290,11 @@ Overrides of this method should never return `null`. Gets the metadata for the export. The metadata of the . - of the property. - + of the property. + ]]> The property was not overridden by a derived class. diff --git a/xml/System.ComponentModel.Composition.Primitives/ImportDefinition.xml b/xml/System.ComponentModel.Composition.Primitives/ImportDefinition.xml index a984bcc3d99..689296eb3af 100644 --- a/xml/System.ComponentModel.Composition.Primitives/ImportDefinition.xml +++ b/xml/System.ComponentModel.Composition.Primitives/ImportDefinition.xml @@ -57,11 +57,11 @@ Initializes a new instance of the class. - property, and optionally, the , and properties. - + property, and optionally, the , and properties. + ]]> @@ -211,11 +211,11 @@ Gets an expression that defines conditions that the import must satisfy to match the import definition. An expression that contains a object that defines the conditions an must satisfy to match the . - The property was not overridden by a derived class. @@ -275,13 +275,7 @@ Gets a value that indicates whether the export represented by the specified definition satisfies the constraints of this import definition. if the constraints are satisfied; otherwise, . - - property, but the result should remain consistent. - ]]> - + For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-primitives-importdefinition-isconstraintsatisfiedby">Supplemental API remarks for System.ComponentModel.Composition.Primitives.ImportDefinition.IsConstraintSatisfiedBy</see>. is . @@ -375,11 +369,11 @@ Overrides of this method can provide a more optimized execution of the Gets the metadata associated with this import. A collection that contains the metadata associated with this import. - collection. - + collection. + ]]> diff --git a/xml/System.ComponentModel.DataAnnotations/ValidationAttribute.xml b/xml/System.ComponentModel.DataAnnotations/ValidationAttribute.xml index 485bba8e675..31d9a54b8ce 100644 --- a/xml/System.ComponentModel.DataAnnotations/ValidationAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/ValidationAttribute.xml @@ -91,14 +91,7 @@ Initializes a new instance of the class. - - - + For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-dataannotations-validationattribute--ctor">Supplemental API remarks for System.ComponentModel.DataAnnotations.ValidationAttribute..ctor</see>. diff --git a/xml/System.Data.Objects/MergeOption.xml b/xml/System.Data.Objects/MergeOption.xml index 6cfc6721672..4d30ce1c719 100644 --- a/xml/System.Data.Objects/MergeOption.xml +++ b/xml/System.Data.Objects/MergeOption.xml @@ -30,12 +30,8 @@ If the state of the entity is . -To preserve the .NET Framework 3.5 SP1 behavior, set to `true`. The `PreserveChanges` option can be used to resolve optimistic concurrency exceptions while preserving changes in the local context. For more information, see [Saving Changes and Managing Concurrency](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738618(v=vs.100)). - ]]> diff --git a/xml/System.Data/DataColumn.xml b/xml/System.Data/DataColumn.xml index f2f4f2de653..2c75d8f7ab5 100644 --- a/xml/System.Data/DataColumn.xml +++ b/xml/System.Data/DataColumn.xml @@ -86,29 +86,29 @@ Represents the schema of a column in a . - is the fundamental building block for creating the schema of a . You build the schema by adding one or more objects to the . For more information, see [Adding Columns to a DataTable](/dotnet/framework/data/adonet/dataset-datatable-dataview/adding-columns-to-a-datatable). - - Each has a property that determines the kind of data the contains. For example, you can restrict the data type to integers, or strings, or decimals. Because data that is contained by the is typically merged back into its original data source, you must match the data types to those in the data source. For more information, see [Data Type Mappings in ADO.NET](/dotnet/framework/data/adonet/data-type-mappings-in-ado-net). - - Properties such as , , and put restrictions on the entry and updating of data, thereby helping to guarantee data integrity. You can also use the , , and properties to control automatic data generation. For more information about columns, see [Creating AutoIncrement Columns](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-autoincrement-columns). For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - - You can also make sure that values in a are unique by creating a and adding it to the of the to which the belongs. For more information, see [DataTable Constraints](/dotnet/framework/data/adonet/dataset-datatable-dataview/datatable-constraints). - - To create a relation between objects, create a object and add it to the of a . - - You can use the property of the object to calculate the values in a column, or create an aggregate column. For more information, see [Creating Expression Columns](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-expression-columns). - - - -## Examples - The following example creates a with several objects. - + is the fundamental building block for creating the schema of a . You build the schema by adding one or more objects to the . For more information, see [Adding Columns to a DataTable](/dotnet/framework/data/adonet/dataset-datatable-dataview/adding-columns-to-a-datatable). + + Each has a property that determines the kind of data the contains. For example, you can restrict the data type to integers, or strings, or decimals. Because data that is contained by the is typically merged back into its original data source, you must match the data types to those in the data source. For more information, see [Data Type Mappings in ADO.NET](/dotnet/framework/data/adonet/data-type-mappings-in-ado-net). + + Properties such as , , and put restrictions on the entry and updating of data, thereby helping to guarantee data integrity. You can also use the , , and properties to control automatic data generation. For more information about columns, see [Creating AutoIncrement Columns](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-autoincrement-columns). For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + + You can also make sure that values in a are unique by creating a and adding it to the of the to which the belongs. For more information, see [DataTable Constraints](/dotnet/framework/data/adonet/dataset-datatable-dataview/datatable-constraints). + + To create a relation between objects, create a object and add it to the of a . + + You can use the property of the object to calculate the values in a column, or create an aggregate column. For more information, see [Creating Expression Columns](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-expression-columns). + + + +## Examples + The following example creates a with several objects. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn Example/VB/source.vb" id="Snippet1"::: + ]]> This type is safe for multithreaded read operations. You must synchronize any write operations. @@ -169,19 +169,19 @@ Initializes a new instance of the class as type string. - object has no default or . When you add it to a , a default name ("Column1", "Column2", and so on) will be generated if a name has not been assigned to the . - - - -## Examples - The following example creates a new , sets various properties, and adds it to a for the object. - + object has no default or . When you add it to a , a default name ("Column1", "Column2", and so on) will be generated if a name has not been assigned to the . + + + +## Examples + The following example creates a new , sets various properties, and adds it to a for the object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -236,19 +236,19 @@ A string that represents the name of the column to be created. If set to or an empty string (""), a default name will be specified when added to the columns collection. Initializes a new instance of the class, as type string, using the specified column name. - property value. - - - -## Examples - The following example creates a new with a specified . - + property value. + + + +## Examples + The following example creates a new with a specified . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -313,14 +313,14 @@ A supported . Initializes a new instance of the class using the specified column name and data type. - with a specified and . - + with a specified and . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn2 Example/VB/source.vb" id="Snippet1"::: + ]]> No was specified. @@ -395,14 +395,14 @@ The expression used to create this column. For more information, see the property. Initializes a new instance of the class using the specified name, data type, and expression. - No was specified. @@ -480,23 +480,23 @@ One of the values. Initializes a new instance of the class using the specified name, data type, expression, and value that determines whether the column is an attribute. - property. The property specifies how a is mapped when a is transformed into an XML document. For example, if the column is named "fName," and the value it contains is "Bob," and `type` is set to `MappingType.Attribute`, the XML element would be as follows: - - \ - - For more information about how columns are mapped to elements or attributes, see the property. - - - -## Examples - The following example constructs a computed column. - + property. The property specifies how a is mapped when a is transformed into an XML document. For example, if the column is named "fName," and the value it contains is "Bob," and `type` is set to `MappingType.Attribute`, the XML element would be as follows: + + \ + + For more information about how columns are mapped to elements or attributes, see the property. + + + +## Examples + The following example constructs a computed column. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn4 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn4 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataColumn4 Example/VB/source.vb" id="Snippet1"::: + ]]> No was specified. @@ -557,14 +557,14 @@ if null values are allowed; otherwise, . The default is . - and sets its property to `true`. - + and sets its property to `true`. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.AllowDBNull Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.AllowDBNull Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.AllowDBNull Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -623,27 +623,27 @@ if the value of the column increments automatically; otherwise, . The default is . - property is coerced to Int32. An exception is generated if this is a computed column. The property is set. The incremented value is used only if the row's value for this column, when added to the columns collection, is equal to the default value. - - You can create a new row using the property of the class and passing in an array of values. This is a potential problem for a column with its set to `true`, because its value is generated automatically. To use the property, place `null` in the column's position in the array. For more information, see the property of the class. - - If the type of the column is or , will not work. Use Int16 or Int32 instead. - - If the type of the column is or , will only partially work. Use Int64 or Decimal instead. - - When the value is added to the current value, the overflow check is suppressed. - - - -## Examples - The following example sets the , , and properties. - + property is coerced to Int32. An exception is generated if this is a computed column. The property is set. The incremented value is used only if the row's value for this column, when added to the columns collection, is equal to the default value. + + You can create a new row using the property of the class and passing in an array of values. This is a potential problem for a column with its set to `true`, because its value is generated automatically. To use the property, place `null` in the column's position in the array. For more information, see the property of the class. + + If the type of the column is or , will not work. Use Int16 or Int32 instead. + + If the type of the column is or , will only partially work. Use Int64 or Decimal instead. + + When the value is added to the current value, the overflow check is suppressed. + + + +## Examples + The following example sets the , , and properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/VB/source.vb" id="Snippet1"::: + ]]> The column is a computed column. @@ -702,14 +702,14 @@ Gets or sets the starting value for a column that has its property set to . The default is 0. The starting value for the feature. - , , and properties. - + , , and properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -766,14 +766,14 @@ Gets or sets the increment used by a column with its property set to . The number by which the value of the column is automatically incremented. The default is 1. - , , and properties. - + , , and properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.AutoIncrementSeed Example/VB/source.vb" id="Snippet1"::: + ]]> The value set is zero. @@ -827,19 +827,19 @@ Gets or sets the caption for the column. The caption of the column. If not set, returns the value. - property to display a descriptive or friendly name for a . - - - -## Examples - The following example creates a new . It then adds three objects to a and sets the property for each . - + property to display a descriptive or friendly name for a . + + + +## Examples + The following example creates a new . It then adds three objects to a and sets the property for each . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.Caption Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.Caption Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.Caption Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -971,47 +971,47 @@ Gets or sets the of the column. One of the values. - property determines how a is mapped when a is saved as an XML document using the method. - - For example, if a is named "customerID," and its property is set to `MappingType.Element`, the column value will produce the following XML: - -``` - - ALFKI -...... - - - 12345 - ALFKI -...... - -``` - - However, if the same column is mapped to `MappingType.Attribute`, the following XML is produced: - -``` - - - -...... More orders for this customer - -``` - - Use the constructor that contains the `type` argument to specify how the is mapped when its is transformed to an XML document. - - The property corresponds to the constructor argument `type`. - - - -## Examples - The following example sets the type property of new . - + property determines how a is mapped when a is saved as an XML document using the method. + + For example, if a is named "customerID," and its property is set to `MappingType.Element`, the column value will produce the following XML: + +``` + + ALFKI +...... + + + 12345 + ALFKI +...... + +``` + + However, if the same column is mapped to `MappingType.Attribute`, the following XML is produced: + +``` + + + +...... More orders for this customer + +``` + + Use the constructor that contains the `type` argument to specify how the is mapped when its is transformed to an XML document. + + The property corresponds to the constructor argument `type`. + + + +## Examples + The following example sets the type property of new . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.ColumnMapping Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ColumnMapping Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ColumnMapping Example/VB/source.vb" id="Snippet1"::: + ]]> Using DataSets in ADO.NET @@ -1068,21 +1068,21 @@ Gets or sets the name of the column in the . The name of the column. - is created, it has no value. However, when the is added to a for a object, it is given a default name ("Column1", "Column2", and so on). - - By default, the value is set to the value. - - - -## Examples - The following examples gets the for every column in every table in a . The example also shows how to create a with a new . - + is created, it has no value. However, when the is added to a for a object, it is given a default name ("Column1", "Column2", and so on). + + By default, the value is set to the value. + + + +## Examples + The following examples gets the for every column in every table in a . The example also shows how to create a with a new . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.ColumnName Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ColumnName Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ColumnName Example/VB/source.vb" id="Snippet1"::: + ]]> The property is set to or an empty string and the column belongs to a collection. @@ -1150,86 +1150,86 @@ Gets or sets the type of data stored in the column. A object that represents the column data type. - value is very important to guaranteeing the correct creation and updating of data in a data source. - - The property supports the following base .NET Framework data types: - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - - as well as the following array type: - -- `Byte[]` - - An exception is generated when changing this property after the column has begun storing data. - - If is set to `true` before setting the property, and you try to set the type to anything except an integer type, an exception is generated. - + value is very important to guaranteeing the correct creation and updating of data in a data source. + + The property supports the following base .NET Framework data types: + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + + as well as the following array type: + +- `Byte[]` + + An exception is generated when changing this property after the column has begun storing data. + + If is set to `true` before setting the property, and you try to set the type to anything except an integer type, an exception is generated. + > [!NOTE] -> A column of data type `Byte[]` requires special treatment in certain cases since, unlike the base .NET Framework data types, it is a reference data type. If a column of data type `Byte[]` is used as a , or as a or key for a , any change to the column value must involve assigning the `Byte[]` column value to a separately instantiated `Byte[]` object. This assignment is required to trigger the update of the internal indexes used by sorting, filtering, and primary key operations. This is illustrated by the following example: - -```csharp -byte[] columnValue = (byte[])myDataTable.Rows[0][0]; -byte[] newValue = (byte[])columnValue.Clone(); -newValue[1] = 2; -myDataTable.Rows[0][0] = newValue; -``` - +> A column of data type `Byte[]` requires special treatment in certain cases since, unlike the base .NET Framework data types, it is a reference data type. If a column of data type `Byte[]` is used as a , or as a or key for a , any change to the column value must involve assigning the `Byte[]` column value to a separately instantiated `Byte[]` object. This assignment is required to trigger the update of the internal indexes used by sorting, filtering, and primary key operations. This is illustrated by the following example: + +```csharp +byte[] columnValue = (byte[])myDataTable.Rows[0][0]; +byte[] newValue = (byte[])columnValue.Clone(); +newValue[1] = 2; +myDataTable.Rows[0][0] = newValue; +``` + > [!NOTE] -> Although it is possible to define a column as data type other than the base .NET Framework data types and `Byte[]`, such a column will be treated as a user-defined type, subject to the following usage restrictions. (For more information on user-defined types, see [Creating and Using User-Defined Types](/previous-versions/9a81d32x(v=vs.85))) - -- The column cannot be part of a or expression. - -- If the column is used as a , or as a or for a , it must be treated as an immutable field; the column data must not be changed once it has been added to the table. - -- Its can be only set to `MappingType.Element`. - -- The class that implements the column's data type must be marked with the , and if necessary implement the or interface. - -- Support for change tracking is limited. To utilize the class' change tracking mechanism, the class that implements the column's data type must either implement the interface, or take over the responsibility for informing the when the column value has been modified, either by calling on the row or by assigning the column value object to a separately instantiated column value object. - - - -## Examples - The following example adds columns of several data types to a , and then adds one row to the table. - +> Although it is possible to define a column as data type other than the base .NET Framework data types and `Byte[]`, such a column will be treated as a user-defined type, subject to the following usage restrictions. (For more information on user-defined types, see [Creating and Using User-Defined Types](/previous-versions/9a81d32x(v=vs.85))) + +- The column cannot be part of a or expression. + +- If the column is used as a , or as a or for a , it must be treated as an immutable field; the column data must not be changed once it has been added to the table. + +- Its can be only set to `MappingType.Element`. + +- The class that implements the column's data type must be marked with the , and if necessary implement the or interface. + +- Support for change tracking is limited. To utilize the class' change tracking mechanism, the class that implements the column's data type must either implement the interface, or take over the responsibility for informing the when the column value has been modified, either by calling on the row or by assigning the column value object to a separately instantiated column value object. + + + +## Examples + The following example adds columns of several data types to a , and then adds one row to the table. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataType Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DataType Example/VB/source.vb" id="Snippet1"::: + ]]> The column already has data stored. @@ -1284,11 +1284,11 @@ myDataTable.Rows[0][0] = newValue; Gets or sets the for the column. The for the specified column. - cannot be modified after rows are added to a , except for modifying from and or vice-versa. The modification from `UnspecifiedLocal` to `Unspecified` and vice-versa is allowed as the difference between these two options is only during serialization and does not affect the storage. - + cannot be modified after rows are added to a , except for modifying from and or vice-versa. The modification from `UnspecifiedLocal` to `Unspecified` and vice-versa is allowed as the difference between these two options is only during serialization and does not affect the storage. + ]]> Using DataSets in ADO.NET @@ -1341,22 +1341,22 @@ myDataTable.Rows[0][0] = newValue; Gets or sets the default value for the column when you are creating new rows. A value appropriate to the column's . - is created (for example, the date and time when the was created. - - When is set to true, there can be no default value. - - You can create a new row using the property of the class and passing the method an array of values. This is a potential problem for a column with a default value because its value is generated automatically. To use the property with such a column, place `null` in the column's position in the array. For more information, see the property. - - - -## Examples - The following example creates several objects that have different data types, and sets appropriate default values to each column. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DefaultValue Example/VB/source.vb" id="Snippet1"::: - + is created (for example, the date and time when the was created. + + When is set to true, there can be no default value. + + You can create a new row using the property of the class and passing the method an array of values. This is a potential problem for a column with a default value because its value is generated automatically. To use the property with such a column, place `null` in the column's position in the array. For more information, see the property. + + + +## Examples + The following example creates several objects that have different data types, and sets appropriate default values to each column. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.DefaultValue Example/VB/source.vb" id="Snippet1"::: + ]]> When you are adding a row, the default value is not an instance of the column's data type. @@ -1421,285 +1421,22 @@ myDataTable.Rows[0][0] = newValue; Gets or sets the expression used to filter rows, calculate the values in a column, or create an aggregate column. An expression to calculate the value of a column, or create an aggregate column. The return type of an expression is determined by the of the column. - - property is to create calculated columns. For example, to calculate a tax value, the unit price is multiplied by a tax rate of a specific region. Because tax rates vary from region to region, it would be impossible to put a single tax rate in a column; instead, the value is calculated using the property, as shown in the Visual Basic code in the following section: - - DataSet1.Tables("Products").Columns("tax").Expression = "UnitPrice * 0.086" - - A second use is to create an aggregate column. Similar to a calculated value, an aggregate performs an operation based on the complete set of rows in the . A simple example is to count the number of rows returned in the set. This is the method you would use to count the number of transactions completed by a particular salesperson, as shown in this Visual Basic code: - -```vb -DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" -``` - -## Expression Syntax - When you create an expression, use the property to refer to columns. For example, if the for one column is "UnitPrice", and another "Quantity", the expression would be as follows: - - "UnitPrice * Quantity" - -> [!NOTE] -> If a column is used in an expression, then the expression is said to have a dependency on that column. If a dependent column is renamed or removed, no exception is thrown. An exception will be thrown when the now-broken expression column is accessed. - - When you create an expression for a filter, enclose strings with single quotation marks: - - "LastName = 'Jones'" - - If a column name contains any non-alphanumeric characters or starts with a digit or matches (case-insensitively) any of the following reserved words, it requires special handling, as described in the following paragraphs. - - And - - Between - - Child - - False - - In - - Is - - Like - - Not - - Null - - Or - - Parent - - True - - If a column name satisfies one of the above conditions, it must be wrapped in either square brackets or the "`" (grave accent) quotes. For example, to use a column named "Column#" in an expression, you would write either "[Column#]": - - Total * [Column#] - - or "\`Column#`": - - Total * \`Column#` - - If the column name is enclosed in square brackets then any ']' and '\\' characters (but not any other characters) in it must be escaped by prepending them with the backslash ("\\") character. If the column name is enclosed in grave accent characters then it must not contain any grave accent characters in it. For example, a column named "Column[]\\" would be written: - - Total * [Column[\\]\\\\] - - or - - Total * \`Column[]\\` - -## User-Defined Values - User-defined values may be used within expressions to be compared with column values. String values should be enclosed within single quotation marks (and each single quotation character in a string value has to be escaped by prepending it with another single quotation character). Date values should be enclosed within pound signs (#) or single quotes (') based on the data provider. Decimals and scientific notation are permissible for numeric values. For example: - - "FirstName = 'John'" - - "Price <= 50.00" - - "Birthdate < #1/31/82#" - - For columns that contain enumeration values, cast the value to an integer data type. For example: - - "EnumColumn = 5" - -## Parsing Literal Expressions - All literal expressions must be expressed in the invariant culture locale. When `DataSet` parses and converts literal expressions, it always uses the invariant culture, not the current culture. - - String literals are identified when there are single quotes surrounding the value. For example: - - 'John' - - `Boolean` literals are true and false; they are not quoted in expressions. - - `Integer` literals [+-]?[0-9]+ are treated as `System.Int32`, `System.Int64` or `System.Double`. `System.Double` can lose precision depending on how large the number is. For example, if the number in the literal is 2147483650, `DataSet` will first attempt to parse the number as an `Int32`. This will not succeed because the number is too large. In this case `DataSet` will parse the number as an `Int64`, which will succeed. If the literal was a number larger than the maximum value of an Int64, `DataSet` will parse the literal using `Double`. - - Real literals using scientific notation, such as 4.42372E-30, are parsed using `System.Double`. - - Real literals without scientific notation, but with a decimal point, are treated as `System.Decimal`. If the number exceeds the maximum or minimum values supported by `System.Decimal`, then it is parsed as a `System.Double`. For example: - - 142526.144524 will be converted to a `Decimal`. - - 345262.78036719560925667 will be treated as a `Double`. - -## Operators - Concatenation is allowed using Boolean AND, OR, and NOT operators. You can use parentheses to group clauses and force precedence. The AND operator has precedence over other operators. For example: - - (LastName = 'Smith' OR LastName = 'Jones') AND FirstName = 'John' - - When you create comparison expressions, the following operators are allowed: - - \< - - \> - - \<= - - \>= - - <> - - = - - IN - - LIKE - - The following arithmetic operators are also supported in expressions: - - \+ (addition) - - \- (subtraction) - - \* (multiplication) - - / (division) - - % (modulus) - -## String Operators - To concatenate a string, use the + character. The value of the property of the class determines whether string comparisons are case-sensitive. However, you can override that value with the property of the class. - -## Wildcard Characters - Both the * and % can be used interchangeably for wildcard characters in a LIKE comparison. If the string in a LIKE clause contains a * or %, those characters should be enclosed in brackets ([]). If a bracket is in the clause, each bracket character should be enclosed in brackets (for example [[] or []]). A wildcard is allowed at the start and end of a pattern, or at the end of a pattern, or at the start of a pattern. For example: - - "ItemName LIKE '*product\*'" - - "ItemName LIKE '*product'" - - "ItemName LIKE 'product*'" - - Wildcard characters are not allowed in the middle of a string. For example, 'te*xt' is not allowed. - -## Parent/Child Relation Referencing - A parent table may be referenced in an expression by prepending the column name with `Parent`. For example, the `Parent.Price` references the parent table's column named `Price`. - - When a child has more than one parent row, use Parent(RelationName).ColumnName. For example, the Parent(RelationName).Price references the parent table's column named Price via the relation. - - A column in a child table may be referenced in an expression by prepending the column name with `Child`. However, because child relationships may return multiple rows, you must include the reference to the child column in an aggregate function. For example, `Sum(Child.Price)` would return the sum of the column named `Price` in the child table. - - If a table has more than one child, the syntax is: `Child(RelationName)`. For example, if a table has two child tables named `Customers` and `Orders`, and the object is named `Customers2Orders`, the reference would be as follows: - - Avg(Child(Customers2Orders).Quantity) - -## Aggregates - The following aggregate types are supported: - - Sum (Sum) - - Avg (Average) - - Min (Minimum) - - Max (Maximum) - - Count (Count) - - StDev (Statistical standard deviation) - - Var (Statistical variance). - - Aggregates are ordinarily performed along relationships. Create an aggregate expression by using one of the functions listed earlier and a child table column as detailed in Parent/Child Relation Referencing that was discussed earlier. For example: - - Avg(Child.Price) - - Avg(Child(Orders2Details).Price) - - An aggregate can also be performed on a single table. For example, to create a summary of figures in a column named "Price": - - Sum(Price) - -> [!NOTE] -> If you use a single table to create an aggregate, there would be no group-by functionality. Instead, all rows would display the same value in the column. - - If a table has no rows, the aggregate functions will return `null`. - - Data types can always be determined by examining the property of a column. You can also convert data types using the Convert function, shown in the following section. - - An aggregate can only be applied to a single column and no other expressions can be used inside the aggregate. - -## Functions - The following functions are also supported: - - `CONVERT` - -||| -|-|-| -|Description|Converts particular expression to a specified .NET Framework Type.| -|Syntax|Convert(`expression`, `type`)| -|Arguments|`expression` -- The expression to convert.

`type` -- .NET type to which the value will be converted.| - - Example: myDataColumn.Expression="Convert(total, 'System.Int32')" - - All conversions are valid with the following exceptions: `Boolean` can be coerced to and from `Byte`, `SByte`, `Int16`, `Int32`, `Int64`, `UInt16`, `UInt32`, `UInt64`, `String` and itself only. `Char` can be coerced to and from `Int32`, `UInt32`, `String`, and itself only. `DateTime` can be coerced to and from `String` and itself only. `TimeSpan` can be coerced to and from `String` and itself only. - - `LEN` - -||| -|-|-| -|Description|Gets the length of a string| -|Syntax|LEN(`expression`)| -|Arguments|`expression` -- The string to be evaluated.| - - Example: myDataColumn.Expression="Len(ItemName)" - - `ISNULL` - -||| -|-|-| -|Description|Checks an expression and either returns the checked expression or a replacement value.| -|Syntax|ISNULL(`expression`, `replacementvalue`)| -|Arguments|`expression` -- The expression to check.

`replacementvalue` -- If expression is `null`, `replacementvalue` is returned.| - - Example: myDataColumn.Expression="IsNull(price, -1)" - - `IIF` - -||| -|-|-| -|Description|Gets one of two values depending on the result of a logical expression.| -|Syntax|IIF(`expr`, `truepart`, `falsepart`)| -|Arguments|`expr` -- The expression to evaluate.

`truepart` -- The value to return if the expression is true.

`falsepart` -- The value to return if the expression is false.| - - Example: myDataColumn.Expression = "IIF(total>1000, 'expensive', 'dear') - - `TRIM` - -||| -|-|-| -|Description|Removes all leading and trailing blank characters like \r, \n, \t, ' '| -|Syntax|TRIM(`expression`)| -|Arguments|`expression` -- The expression to trim.| - - `SUBSTRING` - -||| -|-|-| -|Description|Gets a sub-string of a specified length, starting at a specified point in the string.| -|Syntax|SUBSTRING(`expression`, `start`, `length`)| -|Arguments|`expression` -- The source string for the substring.

`start` -- Integer that specifies where the substring starts.

`length` -- Integer that specifies the length of the substring.| - - Example: myDataColumn.Expression = "SUBSTRING(phone, 7, 8)" - -> [!NOTE] -> You can reset the property by assigning it a null value or empty string. If a default value is set on the expression column, all previously filled rows are assigned the default value after the property is reset. - - - -## Examples - The following example creates three columns in a . The second and third columns contain expressions; the second calculates tax using a variable tax rate, and the third adds the result of the calculation to the value of the first column. The resulting table is displayed in a control. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.Expression Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.Expression Example/VB/source.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for DataColumn.Expression. + + . The second and third columns contain expressions; the second calculates tax using a variable tax rate, and the third adds the result of the calculation to the value of the first column. The resulting table is displayed in a control. + +:::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.Expression Example/CS/source.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.Expression Example/VB/source.vb" id="Snippet1"::: + ]]> + The or property is set to . When you are using the CONVERT function, the expression evaluates to a string, but the string does not contain a representation that can be converted to the type parameter. When you are using the CONVERT function, the requested cast is not possible. See the Conversion function in the following section for detailed information about possible casts. - When you use the SUBSTRING function, the start argument is out of range. - - -Or- - + When you use the SUBSTRING function, the start argument is out of range. + + -Or- + When you use the SUBSTRING function, the length argument is out of range. When you use the LEN function or the TRIM function, the expression does not evaluate to a string. This includes expressions that evaluate to . Using DataSets in ADO.NET @@ -1752,21 +1489,21 @@ DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" Gets the collection of custom user information associated with a . A of custom information. - property lets you store custom information with the object. For example, you may store a time when the data should be refreshed. - - Extended properties must be of type . Properties that are not of type are not persisted when the is written as XML. - - - -## Examples - The following example adds a custom property to the returned by the property. The second example retrieves the custom property. - + property lets you store custom information with the object. For example, you may store a time when the data should be refreshed. + + Extended properties must be of type . Properties that are not of type are not persisted when the is written as XML. + + + +## Examples + The following example adds a custom property to the returned by the property. The second example retrieves the custom property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.ExtendedProperties Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ExtendedProperties Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ExtendedProperties Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1820,11 +1557,11 @@ DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" Gets or sets the maximum length of a text column. The maximum length of the column in characters. If the column has no maximum length, the value is -1 (default). - property is ignored for non-text columns. A exception is raised if you assign to a non-string column. - + property is ignored for non-text columns. A exception is raised if you assign to a non-string column. + ]]> Using DataSets in ADO.NET @@ -1873,13 +1610,13 @@ DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" Gets or sets the namespace of the . The namespace of the . - property is used when reading and writing an XML document into a in the using the , , , or methods. - - The namespace of an XML document is used to scope XML attributes and elements when read into a . For example, a contains a schema read from a document that has the namespace "myCompany," and an attempt is made to read data (with the method) from a document that has the namespace "theirCompany." Any data that does not correspond to the existing schema will be ignored. - + property is used when reading and writing an XML document into a in the using the , , , or methods. + + The namespace of an XML document is used to scope XML attributes and elements when read into a . For example, a contains a schema read from a document that has the namespace "myCompany," and an attempt is made to read data (with the method) from a document that has the namespace "theirCompany." Any data that does not correspond to the existing schema will be ignored. + ]]> The namespace already has data. @@ -1983,14 +1720,14 @@ DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" Gets the (zero-based) position of the column in the collection. The position of the column. Gets -1 if the column is not a member of a collection. - Using DataSets in ADO.NET @@ -2043,11 +1780,11 @@ DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" Gets or sets an XML prefix that aliases the namespace of the . The XML prefix for the namespace. - is used throughout an XML document to identify elements which belong to the namespace for a object (as set by the property). - + is used throughout an XML document to identify elements which belong to the namespace for a object (as set by the property). + ]]> Using DataSets in ADO.NET @@ -2143,14 +1880,14 @@ DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" if the column is read only; otherwise, . The default is . - and sets its property `true`. - + and sets its property `true`. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.ReadOnly Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ReadOnly Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ReadOnly Example/VB/source.vb" id="Snippet1"::: + ]]> The property is set to on a computed column. @@ -2198,13 +1935,13 @@ DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" The specified ordinal. Changes the ordinal or position of the to the specified ordinal or position. - to the specified ordinal or position. If ordinal is less than 0 or greater than the existing number of columns - 1 (greater than the ordinal of the last column) then an Invalid is thrown. - - When you change a column's ordinal, the column is moved to the new position in the collection of columns. Any columns between the previous and new ordinal will be renumbered, to adjust for a column's new ordinal. - + to the specified ordinal or position. If ordinal is less than 0 or greater than the existing number of columns - 1 (greater than the ordinal of the last column) then an Invalid is thrown. + + When you change a column's ordinal, the column is moved to the new position in the collection of columns. Any columns between the previous and new ordinal will be renumbered, to adjust for a column's new ordinal. + ]]> Using DataSets in ADO.NET @@ -2270,14 +2007,14 @@ DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" Gets the to which the column belongs to. The that the belongs to. - through its property. - + through its property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.Table Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.Table Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.Table Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2322,14 +2059,14 @@ DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" Gets the of the column, if one exists. The value, if the property is set; otherwise, the property. - property to return the default string of each member of a collection of objects. - + property to return the default string of each member of a collection of objects. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.ToString Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ToString Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.ToString Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2389,19 +2126,19 @@ DataSet1.Tables("Orders").Columns("OrderCount").Expression = "Count(OrderID)" if the value must be unique; otherwise, . The default is . - , sets its properties, and adds it to a table's columns collection. - + , sets its properties, and adds it to a table's columns collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.Unique Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.Unique Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataColumn.Unique Example/VB/source.vb" id="Snippet1"::: + ]]> The column is a calculated column. diff --git a/xml/System.Diagnostics/ProcessStartInfo.xml b/xml/System.Diagnostics/ProcessStartInfo.xml index a41ab5b979c..7b84f3abdad 100644 --- a/xml/System.Diagnostics/ProcessStartInfo.xml +++ b/xml/System.Diagnostics/ProcessStartInfo.xml @@ -1895,35 +1895,14 @@ You can use asynchronous read operations to avoid these dependencies and their d Gets or sets a value indicating whether to use the operating system shell to start the process. if the shell should be used when starting the process; if the process should be created directly from the executable file. The default is on .NET Framework apps and on .NET Core apps. - - [!NOTE] -> must be `false` if the property is not `null` or an empty string, or an will be thrown when the method is called. - -When you use the operating system shell to start processes, you can start any document (which is any registered file type associated with an executable that has a default open action) and perform operations on the file, such as printing, by using the object. When is `false`, you can start only executables by using the object. - -> [!NOTE] -> must be `true` if you set the property to `true`. - -### WorkingDirectory - -The property behaves differently depending on the value of the property. When is `true`, the property specifies the location of the executable. If is an empty string, it is assumed that the current directory contains the executable. - -When is `false`, the property is not used to find the executable. Instead, it is used only by the process that is started and has meaning only within the context of the new process. When is `false`, the property can be either a fully qualified path to the executable, or a simple executable name that the system will attempt to find within folders specified by the `PATH` environment variable. The interpretation of the search path depends on the operating system. For more information, enter [`HELP PATH`](/windows-server/administration/windows-commands/path) or [`man sh`](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03) at a command prompt. - -## Examples - + For more information about this API, see Supplemental API remarks for ProcessStartInfo.UseShellExecute. + + - + ]]> + An attempt to set the value to on Universal Windows Platform (UWP) apps occurs. diff --git a/xml/System.DirectoryServices.ActiveDirectory/Domain.xml b/xml/System.DirectoryServices.ActiveDirectory/Domain.xml index 80e488af956..2bcc9aa5dae 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/Domain.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/Domain.xml @@ -739,15 +739,10 @@ A object that represents the domain for the specified user credentials in effect for the security context under which the application is running. method is determined by the domain credentials under which the application is running. To retrieve the object representing the domain to which the computer running the application is joined, regardless of the credentials associated with that application, use the method instead. - -## See Also - - - ]]> + method is determined by the domain credentials under which the application is running. To retrieve the object representing the domain to which the computer running the application is joined, regardless of the credentials associated with that application, use the method instead. + ]]> + A connection to the current context could not be made. diff --git a/xml/System.Globalization/CultureAndRegionInfoBuilder.xml b/xml/System.Globalization/CultureAndRegionInfoBuilder.xml index e19036d02c6..ecc5589c4d2 100644 --- a/xml/System.Globalization/CultureAndRegionInfoBuilder.xml +++ b/xml/System.Globalization/CultureAndRegionInfoBuilder.xml @@ -27,8 +27,7 @@ - + ]]> For more information about this API, see Supplemental API remarks for CultureAndRegionInfoBuilder. @@ -53,42 +52,16 @@ The name of a culture. One of the values that specifies whether the new object is a neutral culture, replaces an existing culture and country/region, or is a new culture. Initializes a new instance of the class. - + For more information about this API, see Supplemental API remarks for System.Globalization.CultureAndRegionInfoBuilder constructor. + object. - - The `flags` parameter is used for a value that specifies whether the new object is a new custom culture, or replaces an existing neutral culture, specific culture, or Windows locale. - - If the `cultureName` parameter specifies an existing .NET Framework culture, registered custom culture, or culture generated from a Windows locale, the constructor automatically populates the new object with culture and country/region information. - - Populate the new object with culture and country/region information by invoking the and methods. - -## Custom Culture Names - The preferred format of the `cultureName` parameter for a new, custom culture is "[`prefix`-]`language`[-`region`][-`suffix`[`…`]]", where the `language` component is required and the `prefix`, `region`, and `suffix` components are optional. The maximum length of each component is 8 characters and the maximum length of the entire `cultureName` parameter is 84 characters. - - The `prefix` component is the Internet Assigned Numbers Authority (IANA) identification. Specify "i-" or "I-" for culture names registered with the IANA, or "x-" or "X-" for culture names reserved for private use. Otherwise, the prefix is not required. For more information, see RFC 4646, "Tags for the Identification of Languages." - - The `language` component of the `cultureName` parameter specifies a lowercase two-letter code derived from ISO 639-1, and `region` specifies an uppercase two-letter code derived from ISO 3166. For example, en-US stands for English as spoken in the United States. The absence of the `region` component signifies a neutral culture. - - A `cultureName` that is the same as the name of a culture included with the .NET Framework signifies a replacement (override) culture. The values that can be assigned to the properties of a replacement culture are limited. For more information about such limitations, see the exceptions for each property. - - The application uses the `suffix` component to distinguish similar cultures. For example, two companies, ABC and XYZ, create and share a new ASP.NET Web service to promote their products in different markets around the world. The Web pages for the service display information such as the regional logo and local telephone number of each company depending on the user's culture. The culture-specific content for each Web page is in separate resource files identified by culture name and qualified by company name. For example, resource files for the en-US and ja-JP cultures are named en-US-ABC, en-US-XYZ, ja-JP-ABC, and ja-JP-XYZ. The "ABC" and "XYZ" suffixes enable the Web service to use the same application logic to display different market-specific information. - - The `suffix` component can consist of subcomponents, where each subcomponent is delimited by a hyphen and the maximum length of each subcomponent is 8 characters. For example, if "en-US-honda-cars" is the `cultureName` parameter, "-honda-cars" is the `suffix` component. - - - -## Examples - The following code example creates a custom culture with a private use prefix, then lists a set of its properties. The first property lists the name of the culture. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/sys.glob.carib1/CPP/carib.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureAndRegionInfoBuilder/.ctor/carib.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.glob.carib1/VB/carib.vb" id="Snippet1"::: - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/sys.glob.carib1/CPP/carib.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureAndRegionInfoBuilder/.ctor/carib.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.glob.carib1/VB/carib.vb" id="Snippet1"::: + ]]> + is . diff --git a/xml/System.Globalization/CultureInfo.xml b/xml/System.Globalization/CultureInfo.xml index 25a63e0fe35..108afb4b493 100644 --- a/xml/System.Globalization/CultureInfo.xml +++ b/xml/System.Globalization/CultureInfo.xml @@ -91,8 +91,7 @@ :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CultureInfo_esES/CPP/spanishspain.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/Overview/spanishspain.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo_esES/VB/spanishspain.vb" id="Snippet1"::: - ]]> - + ]]> For more information about this API, see Supplemental API remarks for CultureInfo. @@ -926,113 +925,16 @@ If `name` is , the constr Gets or sets the object that represents the culture used by the current thread and task-based asynchronous operations. The culture used by the current thread and task-based asynchronous operations. - + For more information about this API, see Supplemental API remarks for CultureInfo.CurrentCulture. + object that's returned by this property and its associated objects determine the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons. - -The current culture is a property of the executing thread. When you set this property to a object that represents a new culture, the value of the `Thread.CurrentThread.CurrentCulture` property also changes. However, we recommend that you always use the property to retrieve and set the current culture. - -The `CultureInfo` object that this property returns is read-only. That means you can't mutate the existing object, for example, by changing the `DateTimeFormat`. To change the date-time format or some other aspect of the current culture, create a new `CultureInfo` object and assign it to the property. - -> [!NOTE] -> In .NET Framework 4.5.2 and earlier versions, the property is read-only; that is, you can retrieve the property value, but you cannot set it. - -In this section: - - [How a Thread's Culture Is Determined](#ThreadCulture)\ - [Get the Current Culture](#Getting)\ - [Set the CurrentCulture Property Explicitly](#ExplicitSetting)\ - [User Overrides](#Overrides)\ - [Culture and Windows Apps](#WindowsAndCurr) - - -## How a Thread's Culture Is Determined - -When a thread is started, its culture is initially determined as follows: - -- By retrieving the culture that is specified by the property in the application domain in which the thread is executing, if the property value is not `null`. - -- If the thread is a thread pool thread that is executing a task-based asynchronous operation and the app targets the .NET Framework 4.6 or a later version of the .NET Framework, its culture is determined by the culture of the calling thread. The following example changes the current culture to Portuguese (Brazil) and launches six tasks, each of which displays its thread ID, its task ID, and its current culture. Each of the tasks (and the threads) has inherited the culture of the calling thread. - - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/Async1.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/Async1.vb" id="Snippet14"::: - - For more information, see the "Culture and task-based asynchronous operations" section in the topic. - -- By calling the `GetUserDefaultLocaleName` function on Windows or the `uloc_getDefault` function from [ICU](https://icu-project.org/), which currently calls the POSIX `setlocale` function with category `LC_MESSAGES`, on Unix-like systems. - - Note that if you set a specific culture that is different from the system-installed culture or the user's preferred culture, and your application starts multiple threads, the current culture of those threads will be the culture that is returned by the `GetUserDefaultLocaleName` function, unless you assign a culture to the property in the application domain in which the thread is executing. - - For more information about how the culture of a thread is determined, see the "Culture and threads" section in the reference page. - - -## Get the Current Culture - -The property is a per-thread setting; that is, each thread can have its own culture. You get the culture of the current thread by retrieving the value of the property, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/Get1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/Get1.vb" id="Snippet5"::: - - -## Set the CurrentCulture Property Explicitly - -To change the culture that's used by an existing thread, you set the property to the new culture. If you explicitly change a thread's culture in this way, that change persists if the thread crosses application domain boundaries. The following example changes the current thread culture to Dutch (Netherlands). It also shows that, when the current thread crosses application domain boundaries, its current culture remains changed. - - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/changeculture11.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/changeculture11.vb" id="Snippet11"::: - -> [!NOTE] -> Changing the culture by using the property requires a permission with the value set. Manipulating threads is dangerous because of the security state associated with threads. Therefore, this permission should be given only to trustworthy code, and then only as necessary. You cannot change thread culture in semi-trusted code. - - Starting with .NET Framework 4, you can explicitly change the current thread culture to either a specific culture (such as French (Canada)) or a neutral culture (such as French). When a object represents a neutral culture, the values of properties such as , , , , and reflect the specific culture that is associated with the neutral culture. For example, the dominant culture for the English neutral culture is English (United States); the dominant culture for the German culture is German (Germany). The following example illustrates the difference in formatting when the current culture is set to a specific culture, French (Canada), and a neutral culture, French. - - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/specific12.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/specific12.vb" id="Snippet12"::: - - You can also use the property along with the property to set the property of an ASP.NET application to the user's preferred culture, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/aspculture13.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/aspculture13.vb" id="Snippet13"::: - - -## The Current Culture and User Overrides - -Windows allows users to override the standard property values of the object and its associated objects by using **Regional and Language Options** in Control Panel. The object returned by the property reflects these user overrides in the following cases: - -- If the current thread culture is set implicitly by the Windows `GetUserDefaultLocaleName` function. - -- If the current thread culture defined by the property corresponds to the current Windows system culture. - -- If the current thread culture is set explicitly to a culture returned by the method, and that culture corresponds to the current Windows system culture. - -- If the current thread culture is set explicitly to a culture instantiated by the constructor, and that culture corresponds to the current Windows system culture. - - In some cases, particularly for server applications, setting the current culture to a object that reflects user overrides may be undesirable. Instead, you can set the current culture to a object that does not reflect user overrides in the following ways: - -- By calling the constructor with a value of `false` for the `useUserOverride` argument. - -- By calling the method, which returns a cached, read-only object. - - -## The current culture and UWP apps - -In Universal Windows Platform (UWP) apps, the property is read-write, just as it is in .NET Framework and .NET Core apps; you can use it both to get and to set the current culture. However, UWP apps do not distinguish between the current culture and the current UI culture. The and properties map to the first value in the [Windows.ApplicationModel.Resources.Core.ResourceManager.DefaultContext.Languages](https://docs.microsoft.com/uwp/api/windows.applicationmodel.resources.core.resourcecontext#properties_) collection. - -In .NET Framework and .NET Core apps, the current culture is a per-thread setting, and the property reflects the culture of the current thread only. In UWP apps, the current culture maps to the [Windows.ApplicationModel.Resources.Core.ResourceManager.DefaultContext.Languages](https://docs.microsoft.com/uwp/api/windows.applicationmodel.resources.core.resourcecontext#properties_) property, which is a global setting. Setting the property changes the culture of the entire app; culture cannot be set on a per-thread basis. - -## Examples - The following example demonstrates how to change the and of the current thread. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CultureInfo.CurrentCulture2/CPP/currentculture.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/currentculture.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.CurrentCulture2/VB/currentculture.vb" id="Snippet11"::: - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CultureInfo.CurrentCulture2/CPP/currentculture.cpp" id="Snippet11"::: +:::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/currentculture.cs" id="Snippet11"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.CurrentCulture2/VB/currentculture.vb" id="Snippet11"::: + ]]> + The property is set to . @@ -1095,92 +997,16 @@ The following example demonstrates how to change the Gets or sets the object that represents the current user interface culture used by the Resource Manager to look up culture-specific resources at run time. The culture used by the Resource Manager to look up culture-specific resources at run time. - + For more information about this API, see Supplemental API remarks for CultureInfo.CurrentUICulture. + and of the current thread. -## Remarks - The current UI culture is a per-thread property. That is, each thread has its own current UI culture. This property is equivalent to retrieving or, starting with the .NET Framework 4.6, setting the object assigned to the `System.Threading.Thread.CurrentThread.CurrentUICulture` property. When a thread is started, its UI culture is initially determined as follows: - -- By retrieving the culture that is specified by the property in the application domain in which the thread is executing, if the property value is not `null`. - -- If the thread is a thread pool thread that is executing a task-based asynchronous operation and the app targets the .NET Framework 4.6 or a later version of the .NET Framework, its UI culture is determined by the UI culture of the calling thread. The following example changes the current UI culture to Portuguese (Brazil) and launches six tasks, each of which displays its thread ID, its task ID, and its current UI culture. Each of the tasks (and the threads) has inherited the UI culture of the calling thread. - - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/Async1.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/Async1.vb" id="Snippet14"::: - - For more information, see the "Culture and task-based asynchronous operations" section in the topic. - -- By calling the Windows `GetUserDefaultUILanguage` function. - -> [!NOTE] -> In the .NET Compact Framework, the property is read-only. The current UI culture is determined by the system's regional settings and cannot be changed programmatically. - - Starting with the .NET Framework 4.6, to change the user interface culture used by a thread, set the property to the new culture. If you explicitly change a thread's UI culture in this way, that change persists if the thread crosses application domain boundaries. - -> [!NOTE] -> In the .NET Framework 4.5.2 and earlier versions, the property is read-only; that is, you can retrieve the property value, but you cannot set it. To change the current UI culture, you assign the object that represents the new UI culture to the `Thread.CurrentThread.CurrentUICulture` property. Starting with the .NET Framework 4.6, the property is read-write; you can both set and retrieve the property's value. If you do set the property value to a object that represents a new culture, the value of the `Thread.CurrentThread.CurrentCulture` property also changes. - - In this section: - - [Getting the Current UI Culture](#Getting)\ - [Explicitly Setting the Current UI Culture](#Explicit)\ - [Implicitly Setting the Current UI Culture](#Implicit)\ - [Security Considerations](#Security)\ - [The Current UI Culture and Windows apps](#WindowsAndCurrUI)\ - - -## Getting the Current UI Culture - The property is a per-thread setting; that is, each thread can have its own UI culture. You get the UI culture of the current thread by retrieving the value of the property, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/Get1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/Get1.vb" id="Snippet5"::: - - You can also retrieve the value of the current thread's UI culture from the property. - - -## Explicitly Setting the Current UI Culture - Starting with the .NET Framework 4.6, you can change the current UI culture by assigning a object that represents the new culture to the property. The current UI culture can be set to either a specific culture (such as en-US or de-DE) or to a neutral culture (such as en or de). The following example sets the current UI culture to fr-FR or French (France). - - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentUICulture/currentuiculture1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/currentuiculture1.vb" id="Snippet1"::: - - In a multithreaded application, you can explicitly set the UI culture of any thread by assigning a object that represents that culture to the thread's property. If the thread whose culture you want to set is the current thread, you can assign the new culture to the property. When the UI culture of a thread is set explicitly, that thread retains the same culture even if it crosses application domain boundaries and executes code in another application domain. - - -## Implicitly Setting the Current UI Culture - When a thread, including the main application thread, is first created, by default its current UI culture is set as follows: - -- By using the culture defined by the property for the current application domain if the property value is not `null`. - -- By using the system's default culture. On systems that use the Windows operating system, the common language runtime calls the Windows `GetUserDefaultUILanguage` function to set the current UI culture. `GetUserDefaultUILanguage` returns the default UI culture set by the user. If the user has not set a default UI language, it returns the culture originally installed on the system. - - If the thread crosses application boundaries and executes code in another application domain, its culture is determined in the same way as that of a newly created thread. - - Note that if you set a specific UI culture that is different from the system-installed UI culture or the user's preferred UI culture, and your application starts multiple threads, the current UI culture of those threads will be the culture returned by the `GetUserDefaultUILanguage` function, unless you assign a culture to the property in the application domain in which the thread is executing. - - -## Security Considerations - Changing the culture of the current thread requires a permission with the value set. - -> [!CAUTION] -> Manipulating threads is dangerous because of the security state associated with threads. Therefore, this permission should be given only to trustworthy code, and then only as necessary. You cannot change thread culture in semi-trusted code. - - -## The current UI culture and UWP apps - -In Universal Windows Platform (UWP) apps, the property is read-write, just as it is in .NET Framework and .NET Core apps; you can use it both to get and to set the current culture. However, UWP apps do not distinguish between the current culture and the current UI culture. The and properties map to the first value in the [Windows.ApplicationModel.Resources.Core.ResourceManager.DefaultContext.Languages](https://docs.microsoft.com/uwp/api/windows.applicationmodel.resources.core.resourcecontext#properties_) collection. - -In .NET Framework and .NET Core apps, the current UI culture is a per-thread setting, and the property reflects the UI culture of the current thread only. In UWP apps, the current culture maps to the [Windows.ApplicationModel.Resources.Core.ResourceManager.DefaultContext.Languages](https://docs.microsoft.com/uwp/api/windows.applicationmodel.resources.core.resourcecontext#properties_) property, which is a global setting. Setting the property changes the culture of the entire app; culture cannot be set on a per-thread basis. - -## Examples - The following code example demonstrates how to change the and of the current thread. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CultureInfo.CurrentCulture2/CPP/currentculture.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/currentculture.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.CurrentCulture2/VB/currentculture.vb" id="Snippet11"::: - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CultureInfo.CurrentCulture2/CPP/currentculture.cpp" id="Snippet11"::: +:::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CurrentCulture/currentculture.cs" id="Snippet11"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.CurrentCulture2/VB/currentculture.vb" id="Snippet11"::: + ]]> + The property is set to . The property is set to a culture name that cannot be used to locate a resource file. Resource filenames can include only letters, numbers, hyphens, or underscores. @@ -1240,24 +1066,23 @@ In .NET Framework and .NET Core apps, the current UI culture is a per-thread set is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. The value of the property and the property is not calculated until your application accesses the property. If the user can change the current culture to a new culture while the application is running and then the application accesses the or property, the application retrieves the defaults for the new culture instead of the overrides for the original culture. To preserve the overrides for the original current culture, the application should access the and properties before changing the current culture. -## Examples + ]]> + + + and instances associated with the . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CultureInfo.Clone/CPP/yslin_cultureinfo_clone.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/Clone/yslin_cultureinfo_clone.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.Clone/VB/yslin_cultureinfo_clone.vb" id="Snippet1"::: - - ]]> - + ]]> + The property is set to null. The property or any of the properties is set, and the is read-only. @@ -2615,32 +2440,7 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the Gets the object that is culture-independent (invariant). The object that is culture-independent (invariant). - - instantiation method. also retrieves an instance of the invariant culture. It can be used in almost any method in the namespace that requires a culture. The objects returned by properties such as , , and also reflect the string comparison and formatting conventions of the invariant culture. - - Unlike culture-sensitive data, which is subject to change by user customization or by updates to the .NET Framework or the operating system, invariant culture data is stable over time and across installed cultures and cannot be customized by users. This makes the invariant culture particularly useful for operations that require culture-independent results, such as formatting and parsing operations that persist formatted data, or sorting and ordering operations that require that data be displayed in a fixed order regardless of culture. - -## String Operations - You can use the invariant culture for culture-sensitive string operations that are not affected by the conventions of the current culture and that are consistent across cultures. For example, you may want sorted data to appear in a fixed order or apply a standard set of casing conventions to strings regardless of the current culture. To do this, you pass the object to a method that has a parameter, such as and . - -## Persisting Data - The property can be used to persist data in a culture-independent format. This provides a known format that does not change and that can be used to serialize and deserialize data across cultures. After the data is deserialized, it can be formatted appropriately based on the cultural conventions of the current user. - - For example, if you choose to persist date and time data in string form, you can pass the object to the or method to create the string, and you can pass the object to the or method to convert the string back to a date and time value. This technique ensures that the underlying date and time values do not change when the data is read or written by users from different cultures. - - The following example uses the invariant culture to persist a value as a string. It then parses the string and displays its value by using the formatting conventions of the French (France) and German (Germany) cultures. - - :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/InvariantCulture/persist1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.invariantculture/vb/persist1.vb" id="Snippet1"::: - -## Security Decisions - If you are making a security decision (such as whether to allow access to a system resource) based on the result of a string comparison or a case change, you should not use the invariant culture. Instead, you should perform a case-sensitive or case-insensitive ordinal comparison by calling a method that includes a parameter and supplying either or as an argument. Code that performs culture-sensitive string operations can cause security vulnerabilities if the current culture is changed or if the culture on the computer that is running the code differs from the culture that is used to test the code. In contrast, an ordinal comparison depends solely on the binary value of the compared characters. - - ]]> - + For more information about this API, see Supplemental API remarks for CultureInfo.InvariantCulture. @@ -3084,26 +2884,23 @@ For a list of predefined culture names and identifiers that the is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. The values of the property and the property are not calculated until the user accesses the property. If the user uses the Control Panel to change the current culture to a new culture while the application is running and then accesses the or property, the application retrieves the defaults for the new culture. not the overrides for the original culture. To preserve the overrides for the original current culture, the application should access the and properties before changing the current culture. - - -## Examples - The following code example shows that CultureInfo.Clone also clones the and instances associated with the . + ]]> + + + and instances associated with the . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CultureInfo.Clone/CPP/yslin_cultureinfo_clone.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/Clone/yslin_cultureinfo_clone.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.Clone/VB/yslin_cultureinfo_clone.vb" id="Snippet1"::: - - ]]> - + ]]> + The property is set to null. The property or any of the properties is set, and the is read-only. diff --git a/xml/System.Linq.Expressions/Expression.xml b/xml/System.Linq.Expressions/Expression.xml index 6ac811c1158..89fb97f6fdb 100644 --- a/xml/System.Linq.Expressions/Expression.xml +++ b/xml/System.Linq.Expressions/Expression.xml @@ -53,14 +53,14 @@ Provides the base class from which the classes that represent expression tree nodes are derived. It also contains ( in Visual Basic) factory methods to create the various node types. This is an class. - objects and one object. - + objects and one object. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet13"::: + ]]> @@ -167,11 +167,11 @@ The of this . Initializes a new instance of the class. - @@ -218,11 +218,11 @@ Dispatches to the specific visit method for this node type. For example, calls the . The result of visiting this node. - nodes calls . Override this method to call into a more specific method on a derived visitor class of the class. However, it should still support unknown visitors by calling . - + nodes calls . Override this method to call into a more specific method on a derived visitor class of the class. However, it should still support unknown visitors by calling . + ]]> @@ -289,48 +289,15 @@ A to set the property equal to. Creates a that represents an arithmetic addition operation that does not have overflow checking. A that has the property equal to and the and properties set to the specified values. - - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the selected implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the addition operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined addition operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined addition operator. - - - -## Examples - The following code example shows how to create an expression that adds two integers. - - :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for Expression.Add. + + + or is . The addition operator is not defined for .Type and .Type. @@ -390,42 +357,7 @@ A to set the property equal to. Creates a that represents an arithmetic addition operation that does not have overflow checking. The implementing method can be specified. A that has the property equal to and the , and properties set to the specified values. - - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the addition operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined addition operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined addition operator. - - ]]> - + For more information about this API, see Supplemental API remarks for Expression.Add. or is . @@ -496,14 +428,14 @@ Creates a that represents an addition assignment operation that does not have overflow checking. A that has the property equal to and the and properties set to the specified values. - @@ -889,37 +821,37 @@ Creates a that represents an arithmetic addition operation that has overflow checking. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the addition operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined addition operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined addition operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the addition operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined addition operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined addition operator. + ]]> @@ -982,39 +914,39 @@ Creates a that represents an arithmetic addition operation that has overflow checking. The implementing method can be specified. A that has the property equal to and the , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The implementing method for the operation is chosen based on the following rules: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the addition operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined addition operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined addition operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The implementing method for the operation is chosen based on the following rules: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the addition operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined addition operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined addition operator. + ]]> @@ -1088,45 +1020,45 @@ Creates a that represents a bitwise operation. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined bitwise `AND` operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined bitwise `AND` operator. - - - -## Examples - The following code example shows how to create an expression that represents a logical AND operation on two Boolean values. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined bitwise `AND` operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined bitwise `AND` operator. + + + +## Examples + The following code example shows how to create an expression that represents a logical AND operation on two Boolean values. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet2"::: + ]]> @@ -1189,39 +1121,39 @@ Creates a that represents a bitwise operation. The implementing method can be specified. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The implementing method for the operation is chosen based on the following rules: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined bitwise `AND` operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined bitwise `AND` operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The implementing method for the operation is chosen based on the following rules: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined bitwise `AND` operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined bitwise `AND` operator. + ]]> @@ -1295,58 +1227,58 @@ Creates a that represents a conditional operation that evaluates the second operand only if the first operand evaluates to . A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. + > [!NOTE] - > The conditional `AND` operator cannot be overloaded in C# or Visual Basic. However, the conditional `AND` operator is evaluated by using the bitwise `AND` operator. Thus, a user-defined overload of the bitwise `AND` operator can be the implementing method for this node type. - -- Otherwise, if `left`.Type and `right`.Type are Boolean types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- `left`.Type and `right`.Type are the same Boolean type. - -- If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `AND` operator. - -- If `left`.Type and `right`.Type are nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined conditional `AND` operator. - - - -## Examples - The following code example shows how to create an expression that performs a logical AND operation on its two operands only if the first operand evaluates to `true`. - + > The conditional `AND` operator cannot be overloaded in C# or Visual Basic. However, the conditional `AND` operator is evaluated by using the bitwise `AND` operator. Thus, a user-defined overload of the bitwise `AND` operator can be the implementing method for this node type. + +- Otherwise, if `left`.Type and `right`.Type are Boolean types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- `left`.Type and `right`.Type are the same Boolean type. + +- If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `AND` operator. + +- If `left`.Type and `right`.Type are nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined conditional `AND` operator. + + + +## Examples + The following code example shows how to create an expression that performs a logical AND operation on its two operands only if the first operand evaluates to `true`. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet19"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet19"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet19"::: + ]]> or is . - The bitwise operator is not defined for .Type and .Type. - - -or- - + The bitwise operator is not defined for .Type and .Type. + + -or- + .Type and .Type are not the same Boolean type. @@ -1405,44 +1337,44 @@ Creates a that represents a conditional operation that evaluates the second operand only if the first operand is resolved to true. The implementing method can be specified. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The implementing method for the operation is chosen based on the following rules: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The implementing method for the operation is chosen based on the following rules: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. + > [!NOTE] - > The conditional `AND` operator cannot be overloaded in C# or Visual Basic. However, the conditional `AND` operator is evaluated by using the bitwise `AND` operator. Thus, a user-defined overload of the bitwise `AND` operator can be the implementing method for this node type. - -- Otherwise, if `left`.Type and `right`.Type are Boolean types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- `left`.Type and `right`.Type are the same Boolean type. - -- If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `AND` operator. - -- If `left`.Type and `right`.Type are nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined conditional `AND` operator. - + > The conditional `AND` operator cannot be overloaded in C# or Visual Basic. However, the conditional `AND` operator is evaluated by using the bitwise `AND` operator. Thus, a user-defined overload of the bitwise `AND` operator can be the implementing method for this node type. + +- Otherwise, if `left`.Type and `right`.Type are Boolean types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- `left`.Type and `right`.Type are the same Boolean type. + +- If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `AND` operator. + +- If `left`.Type and `right`.Type are nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined conditional `AND` operator. + ]]> @@ -1450,10 +1382,10 @@ is not and the method it represents returns , is not ( in Visual Basic), or does not take exactly two arguments. - is and the bitwise operator is not defined for .Type and .Type. - - -or- - + is and the bitwise operator is not defined for .Type and .Type. + + -or- + is and .Type and .Type are not the same Boolean type. @@ -1712,19 +1644,19 @@ Creates an to access a multidimensional array. The created . - method, or through or . - - - -## Examples - The following code example shows how to change the value of an element in a multidimensional array by using the `ArrayAccess` method. - + method, or through or . + + + +## Examples + The following code example shows how to change the value of an element in a multidimensional array by using the `ArrayAccess` method. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet21"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet21"::: + ]]> @@ -1785,21 +1717,21 @@ Creates an to access an array. The created . - method, or through or . - - For multidimensional arrays, use the method. - - - -## Examples - The following code example shows how to change a value of an array element by using the `ArrayAccess` method. - + method, or through or . + + For multidimensional arrays, use the method. + + + +## Examples + The following code example shows how to change a value of an array element by using the `ArrayAccess` method. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet20"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet20"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet20"::: + ]]> @@ -1861,36 +1793,36 @@ Creates a that represents applying an array index operator to an array of rank more than one. A that has the property equal to and the and properties set to the specified values. - equal to . The property of `array` must represent an array type whose rank matches the number of elements in `indexes`. - - If the rank of `array`.Type is 1, this method returns a . The property is set to `array` and the property is set to the single element of `indexes`. The property of the represents the element type of `array`.Type. - - If the rank of `array`.Type is more than one, this method returns a . The property is set to the that describes the public instance method `Get` on the type represented by the property of `array`. - - - -## Examples - The following example demonstrates how to use the method to create a that represents indexing into a two-dimensional array. - + equal to . The property of `array` must represent an array type whose rank matches the number of elements in `indexes`. + + If the rank of `array`.Type is 1, this method returns a . The property is set to `array` and the property is set to the single element of `indexes`. The property of the represents the element type of `array`.Type. + + If the rank of `array`.Type is more than one, this method returns a . The property is set to the that describes the public instance method `Get` on the type represented by the property of `array`. + + + +## Examples + The following example demonstrates how to use the method to create a that represents indexing into a two-dimensional array. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet3"::: + ]]> or is . - .Type does not represent an array type. - - -or- - - The rank of .Type does not match the number of elements in . - - -or- - + .Type does not represent an array type. + + -or- + + The rank of .Type does not match the number of elements in . + + -or- + The property of one or more elements of does not represent the type. @@ -1939,26 +1871,26 @@ Creates a that represents applying an array index operator to an array of rank one. A that has the property equal to and the and properties set to the specified values. - . - - The property of the resulting is `null`, and both and are set to `false`. The property is equal to the element type of `array`.Type. The property is `null`. - + . + + The property of the resulting is `null`, and both and are set to `false`. The property is equal to the element type of `array`.Type. The property is `null`. + ]]> or is . - .Type does not represent an array type. - - -or- - - .Type represents an array type whose rank is not 1. - - -or- - + .Type does not represent an array type. + + -or- + + .Type represents an array type whose rank is not 1. + + -or- + .Type does not represent the type. @@ -2014,36 +1946,36 @@ Creates a that represents applying an array index operator to a multidimensional array. A that has the property equal to and the and properties set to the specified values. - equal to . The property of `array` must represent an array type whose rank matches the number of elements in `indexes`. - - If the rank of `array`.Type is 1, this method returns a . The property is set to `array` and the property is set to the single element of `indexes`. The property of the represents the element type of `array`.Type. - - If the rank of `array`.Type is more than one, this method returns a . The property is set to the that describes the public instance method `Get` on the type represented by the property of `array`. - - - -## Examples - The following example demonstrates how to use the method to create a that represents indexing into a two-dimensional array. - + equal to . The property of `array` must represent an array type whose rank matches the number of elements in `indexes`. + + If the rank of `array`.Type is 1, this method returns a . The property is set to `array` and the property is set to the single element of `indexes`. The property of the represents the element type of `array`.Type. + + If the rank of `array`.Type is more than one, this method returns a . The property is set to the that describes the public instance method `Get` on the type represented by the property of `array`. + + + +## Examples + The following example demonstrates how to use the method to create a that represents indexing into a two-dimensional array. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet3"::: + ]]> or is . - .Type does not represent an array type. - - -or- - - The rank of .Type does not match the number of elements in . - - -or- - + .Type does not represent an array type. + + -or- + + The rank of .Type does not match the number of elements in . + + -or- + The property of one or more elements of does not represent the type. @@ -2090,13 +2022,13 @@ Creates a that represents an expression for obtaining the length of a one-dimensional array. A that has the property equal to and the property equal to . - property of `array` must represent an array type. - - The property of the resulting is equal to . The property is `null`, and both and are set to `false`. - + property of `array` must represent an array type. + + The property of the resulting is equal to . The property is `null`, and both and are set to `false`. + ]]> @@ -2149,19 +2081,19 @@ Creates a that represents an assignment operation. A that has the property equal to and the and properties set to the specified values. - @@ -2223,24 +2155,24 @@ Creates a that represents the initialization of a field or property. A that has equal to and the and properties set to the specified values. - property of `expression` must be assignable to the type represented by the or property of `member`. - + property of `expression` must be assignable to the type represented by the or property of `member`. + ]]> or is . - does not represent a field or property. - - -or- - - The property represented by does not have a accessor. - - -or- - + does not represent a field or property. + + -or- + + The property represented by does not have a accessor. + + -or- + .Type is not assignable to the type of the field or property that represents. @@ -2295,24 +2227,24 @@ Creates a that represents the initialization of a member by using a property accessor method. A that has the property equal to , the property set to the that represents the property accessed in , and the property set to . - property of `expression` must be assignable to the type represented by the property of the property accessed in `propertyAccessor`. - + property of `expression` must be assignable to the type represented by the property of the property accessed in `propertyAccessor`. + ]]> or is . - does not represent a property accessor method. - - -or- - - The property accessed by does not have a accessor. - - -or- - + does not represent a property accessor method. + + -or- + + The property accessed by does not have a accessor. + + -or- + .Type is not assignable to the type of the field or property that represents. @@ -2370,11 +2302,11 @@ Creates a that contains the given expressions and has no variables. The created . - @@ -2428,19 +2360,19 @@ Creates a that contains the given expressions and has no variables. The created . - objects and one object. - + objects and one object. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet13"::: + ]]> @@ -2497,19 +2429,19 @@ Creates a that contains the given variables and expressions. The created . - @@ -2573,11 +2505,11 @@ Creates a that contains the given variables and expressions. The created . - @@ -2626,11 +2558,11 @@ Creates a that contains two expressions and has no variables. The created . - @@ -2780,11 +2712,11 @@ Creates a that contains three expressions and has no variables. The created . - @@ -2956,11 +2888,11 @@ Creates a that contains four expressions and has no variables. The created . - @@ -3015,11 +2947,11 @@ Creates a that contains five expressions and has no variables. The created . - @@ -3078,14 +3010,14 @@ Creates a representing a break statement. A with equal to Break, the property set to , and a null value to be passed to the target label upon jumping. - object that uses the method. - + object that uses the method. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet44"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet44"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet44"::: + ]]> @@ -3323,30 +3255,30 @@ Creates a that represents a call to a method that takes no arguments. A that has the property equal to and the and properties set to the specified values. - property of `instance` must be assignable to the declaring type of the method represented by `method`. - - The property of the resulting is empty. The property is equal to the return type of the method represented by `method`. - - - -## Examples - The following code example shows how to create an expression that calls a method without arguments. - + property of `instance` must be assignable to the declaring type of the method represented by `method`. + + The property of the resulting is empty. The property is equal to the return type of the method represented by `method`. + + + +## Examples + The following code example shows how to create an expression that calls a method without arguments. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet15"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet15"::: + ]]> - is . - - -or- - + is . + + -or- + is and represents an instance method. .Type is not assignable to the declaring type of the method represented by . @@ -3456,14 +3388,14 @@ Creates a that represents a call to a ( in Visual Basic) method that takes one argument. A that has the property equal to and the and properties set to the specified values. - @@ -3533,26 +3465,26 @@ Creates a that represents a call to a ( in Visual Basic) method that has arguments. A that has the property equal to and the and properties set to the specified values. - [!NOTE] -> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. - - The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. - - The property of the resulting is equal to the return type of the method represented by `method`. The property is `null`. - - ]]> - +> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. + + The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. + + The property of the resulting is equal to the return type of the method represented by `method`. The property is `null`. + + ]]> + is . - The number of elements in does not equal the number of parameters for the method represented by . - - -or- - + The number of elements in does not equal the number of parameters for the method represented by . + + -or- + One or more of the elements of is not assignable to the corresponding parameter for the method represented by . @@ -3618,39 +3550,39 @@ Creates a that represents a call to a method that takes arguments. A that has the property equal to and the , , and properties set to the specified values. - instead. - - If `method` represents an instance method, the property of `instance` must be assignable to the declaring type of the method represented by `method`. - - If `arguments` is not `null`, it must have the same number of elements as the number of parameters for the method represented by `method`. Each element in `arguments` must not be `null` and must be assignable to the corresponding parameter of `method`, possibly after *quoting*. - + instead. + + If `method` represents an instance method, the property of `instance` must be assignable to the declaring type of the method represented by `method`. + + If `arguments` is not `null`, it must have the same number of elements as the number of parameters for the method represented by `method`. Each element in `arguments` must not be `null` and must be assignable to the corresponding parameter of `method`, possibly after *quoting*. + > [!NOTE] -> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. - - The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. - - The property of the resulting is equal to the return type of the method represented by `method`. - +> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. + + The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. + + The property of the resulting is equal to the return type of the method represented by `method`. + ]]> - is . - - -or- - + is . + + -or- + is and represents an instance method. - .Type is not assignable to the declaring type of the method represented by . - - -or- - - The number of elements in does not equal the number of parameters for the method represented by . - - -or- - + .Type is not assignable to the declaring type of the method represented by . + + -or- + + The number of elements in does not equal the number of parameters for the method represented by . + + -or- + One or more of the elements of is not assignable to the corresponding parameter for the method represented by . @@ -3720,43 +3652,43 @@ Creates a that represents a call to a method that takes arguments. A that has the property equal to and the , , and properties set to the specified values. - instead. - - If `method` represents an instance method, the property of `instance` must be assignable to the declaring type of the method represented by `method`. - - If `arguments` is not `null`, it must have the same number of elements as the number of parameters for the method represented by `method`. Each element in `arguments` must not be `null` and must be assignable to the corresponding parameter of `method`, possibly after *quoting*. - + instead. + + If `method` represents an instance method, the property of `instance` must be assignable to the declaring type of the method represented by `method`. + + If `arguments` is not `null`, it must have the same number of elements as the number of parameters for the method represented by `method`. Each element in `arguments` must not be `null` and must be assignable to the corresponding parameter of `method`, possibly after *quoting*. + > [!NOTE] -> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. - - The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. - - The property of the resulting is equal to the return type of the method represented by `method`. - +> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. + + The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. + + The property of the resulting is equal to the return type of the method represented by `method`. + ]]> - is . - - -or- - - is and represents an instance method. - - -or- - + is . + + -or- + + is and represents an instance method. + + -or- + is not and one or more of its elements is . - .Type is not assignable to the declaring type of the method represented by . - - -or- - - The number of elements in does not equal the number of parameters for the method represented by . - - -or- - + .Type is not assignable to the declaring type of the method represented by . + + -or- + + The number of elements in does not equal the number of parameters for the method represented by . + + -or- + One or more of the elements of is not assignable to the corresponding parameter for the method represented by . @@ -3866,14 +3798,14 @@ Creates a that represents a call to a method that takes two arguments. A that has the property equal to and the and properties set to the specified values. - @@ -3952,19 +3884,19 @@ Creates a that represents a call to a method by calling the appropriate factory method. A that has the property equal to , the property equal to , set to the that represents the specified instance method, and set to the specified arguments. - property of the resulting is equal to the return type of the method denoted by `methodName`. - + property of the resulting is equal to the return type of the method denoted by `methodName`. + ]]> or is . - No method whose name is , whose type parameters match , and whose parameter types match is found in .Type or its base types. - - -or- - + No method whose name is , whose type parameters match , and whose parameter types match is found in .Type or its base types. + + -or- + More than one method whose name is , whose type parameters match , and whose parameter types match is found in .Type or its base types. @@ -4101,19 +4033,19 @@ Creates a that represents a call to a ( in Visual Basic) method by calling the appropriate factory method. A that has the property equal to , the property set to the that represents the specified ( in Visual Basic) method, and the property set to the specified arguments. - property of the resulting is equal to the return type of the method denoted by `methodName`. The property is `null`. - + property of the resulting is equal to the return type of the method denoted by `methodName`. The property is `null`. + ]]> or is . - No method whose name is , whose type parameters match , and whose parameter types match is found in or its base types. - - -or- - + No method whose name is , whose type parameters match , and whose parameter types match is found in or its base types. + + -or- + More than one method whose name is , whose type parameters match , and whose parameter types match is found in or its base types. @@ -4436,11 +4368,11 @@ Creates a representing a catch statement. The created . - of to be caught can be specified but no reference to the object will be available for use in the . - + of to be caught can be specified but no reference to the object will be available for use in the . + ]]> @@ -4670,20 +4602,20 @@ Creates a that represents a coalescing operation. A that has the property equal to and the and properties set to the specified values. - property of the resulting is `null` and both and are set to `false`. The property is equal to the result type of the coalescing operation. The property is `null`. - -#### Result Type - The following rules determine the result type: - -- If `left`.Type represents a nullable type and `right`.Type is implicitly convertible to the corresponding non-nullable type, the result type is the non-nullable equivalent of `left`.Type. - -- Otherwise, if `right`.Type is implicitly convertible to `left`.Type, the result type is `left`.Type. - -- Otherwise, if the non-nullable equivalent of `left`.Type is implicitly convertible to `right`.Type, the result type is `right`.Type. - + property of the resulting is `null` and both and are set to `false`. The property is equal to the result type of the coalescing operation. The property is `null`. + +#### Result Type + The following rules determine the result type: + +- If `left`.Type represents a nullable type and `right`.Type is implicitly convertible to the corresponding non-nullable type, the result type is the non-nullable equivalent of `left`.Type. + +- Otherwise, if `right`.Type is implicitly convertible to `left`.Type, the result type is `left`.Type. + +- Otherwise, if the non-nullable equivalent of `left`.Type is implicitly convertible to `right`.Type, the result type is `right`.Type. + ]]> @@ -4749,39 +4681,39 @@ Creates a that represents a coalescing operation, given a conversion function. A that has the property equal to and the , and properties set to the specified values. - property of the resulting is `null` and both and are set to `false`. - - The property of the resulting is equal to the result type of the coalescing operation. - - The following rules determine the result type: - -- If `left`.Type represents a nullable type and `right`.Type is implicitly convertible to the corresponding non-nullable type, the result type is the non-nullable equivalent of `left`.Type. - -- Otherwise, if `right`.Type is implicitly convertible to `left`.Type, the result type is `left`.Type. - -- Otherwise, if the non-nullable equivalent of `left`.Type is implicitly convertible to `right`.Type, the result type is `right`.Type. - + property of the resulting is `null` and both and are set to `false`. + + The property of the resulting is equal to the result type of the coalescing operation. + + The following rules determine the result type: + +- If `left`.Type represents a nullable type and `right`.Type is implicitly convertible to the corresponding non-nullable type, the result type is the non-nullable equivalent of `left`.Type. + +- Otherwise, if `right`.Type is implicitly convertible to `left`.Type, the result type is `left`.Type. + +- Otherwise, if the non-nullable equivalent of `left`.Type is implicitly convertible to `right`.Type, the result type is `right`.Type. + ]]> or is . - .Type and .Type are not convertible to each other. - - -or- - + .Type and .Type are not convertible to each other. + + -or- + is not and .Type is a delegate type that does not take exactly one argument. - The property of does not represent a reference type or a nullable value type. - - -or- - - The property of represents a type that is not assignable to the parameter type of the delegate type .Type. - - -or- - + The property of does not represent a reference type or a nullable value type. + + -or- + + The property of represents a type that is not assignable to the parameter type of the delegate type .Type. + + -or- + The property of is not equal to the return type of the delegate type .Type. @@ -4844,28 +4776,28 @@ Creates a that represents a conditional statement. A that has the property equal to and the , , and properties set to the specified values. - property of the resulting is equal to the property of `ifTrue`. - - - -## Examples - The following code example shows how to create an expression that represents a conditional statement. If the first argument evaluates to `true`, the second argument is executed; otherwise, the third argument is executed. - + property of the resulting is equal to the property of `ifTrue`. + + + +## Examples + The following code example shows how to create an expression that represents a conditional statement. If the first argument evaluates to `true`, the second argument is executed; otherwise, the third argument is executed. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet3"::: + ]]> or or is . - .Type is not . - - -or- - + .Type is not . + + -or- + .Type is not equal to .Type. @@ -4919,11 +4851,11 @@ Creates a that represents a conditional statement. A that has the property equal to and the , , and properties set to the specified values. - . - + . + ]]> @@ -4991,21 +4923,21 @@ Creates a that has the property set to the specified value. A that has the property equal to and the property set to the specified value. - property of the resulting is equal to the type of `value`. If `value` is `null`, is equal to . - - To represent `null`, you can also use the method, with which you can explicitly specify the type. - - - -## Examples - The following code example shows how to create an expression that represents a constant value. - + property of the resulting is equal to the type of `value`. If `value` is `null`, is equal to . + + To represent `null`, you can also use the method, with which you can explicitly specify the type. + + + +## Examples + The following code example shows how to create an expression that represents a constant value. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet4"::: + ]]> @@ -5063,19 +4995,19 @@ Creates a that has the and properties set to the specified values. A that has the property equal to and the and properties set to the specified values. - @@ -5138,14 +5070,14 @@ Creates a representing a continue statement. A with equal to Continue, the property set to , and a null value to be passed to the target label upon jumping. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet46"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet46"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet46"::: + ]]> @@ -5265,43 +5197,43 @@ Creates a that represents a type conversion operation. A that has the property equal to and the and properties set to the specified values. - property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If either `expression`.Type or `type` is a user-defined type that defines an implicit or explicit conversion operator, the that represents that operator is the implementing method. - -- Otherwise: - - - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. - - - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. - -#### Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method and the return type of the implementing method is assignable to `type`, the node is not lifted. - -- If one or both of `expression`.Type or `type` is a nullable value type and the corresponding non-nullable value types are equal to the argument type and the return type of the implementing method respectively, the node is lifted. - - If the implementing method is `null`: - -- If both `expression`.Type and `type` are non-nullable, the node is not lifted. - -- Otherwise the node is lifted. - - - -## Examples - The following code example shows how to create an expression that represents a type conversion operation. - + property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If either `expression`.Type or `type` is a user-defined type that defines an implicit or explicit conversion operator, the that represents that operator is the implementing method. + +- Otherwise: + + - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. + + - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. + +#### Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method and the return type of the implementing method is assignable to `type`, the node is not lifted. + +- If one or both of `expression`.Type or `type` is a nullable value type and the corresponding non-nullable value types are equal to the argument type and the return type of the implementing method respectively, the node is lifted. + + If the implementing method is `null`: + +- If both `expression`.Type and `type` are non-nullable, the node is not lifted. + +- Otherwise the node is lifted. + + + +## Examples + The following code example shows how to create an expression that represents a type conversion operation. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet23"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet23"::: + ]]> @@ -5364,55 +5296,55 @@ Creates a that represents a conversion operation for which the implementing method is specified. A that has the property equal to and the , , and properties set to the specified values. - property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If method is not `null`, it is the implementing method. It must represent a non-void, `static` (`Shared` in Visual Basic) method that takes one argument. - -- Otherwise, if either `expression`.Type or `type` is a user-defined type that defines an implicit or explicit conversion operator, the that represents that operator is the implementing method. - -- Otherwise: - - - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. - - - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. - -#### Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method and the return type of the implementing method is assignable to `type`, the node is not lifted. - -- If either or both of `expression`.Type or `type` are a nullable value type and the corresponding non-nullable value types are equal to the argument type and the return type of the implementing method respectively, the node is lifted. - - If the implementing method is `null`: - -- If both `expression`.Type and `type` are non-nullable, the node is not lifted. - -- Otherwise the node is lifted. - + property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If method is not `null`, it is the implementing method. It must represent a non-void, `static` (`Shared` in Visual Basic) method that takes one argument. + +- Otherwise, if either `expression`.Type or `type` is a user-defined type that defines an implicit or explicit conversion operator, the that represents that operator is the implementing method. + +- Otherwise: + + - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. + + - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. + +#### Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method and the return type of the implementing method is assignable to `type`, the node is not lifted. + +- If either or both of `expression`.Type or `type` are a nullable value type and the corresponding non-nullable value types are equal to the argument type and the return type of the implementing method respectively, the node is lifted. + + If the implementing method is `null`: + +- If both `expression`.Type and `type` are non-nullable, the node is not lifted. + +- Otherwise the node is lifted. + ]]> or is . is not and the method it represents returns , is not ( in Visual Basic), or does not take exactly one argument. - No conversion operator is defined between .Type and . - - -or- - - .Type is not assignable to the argument type of the method represented by . - - -or- - - The return type of the method represented by is not assignable to . - - -or- - + No conversion operator is defined between .Type and . + + -or- + + .Type is not assignable to the argument type of the method represented by . + + -or- + + The return type of the method represented by is not assignable to . + + -or- + .Type or is a nullable value type and the corresponding non-nullable value type does not equal the argument type or the return type, respectively, of the method represented by . More than one method that matches the description was found. @@ -5480,35 +5412,35 @@ Creates a that represents a conversion operation that throws an exception if the target type is overflowed. A that has the property equal to and the and properties set to the specified values. - property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If either `expression`.Type or `type` is a user-defined type that defines an implicit or explicit conversion operator, the that represents that operator is the implementing method. - -- Otherwise: - - - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. - - - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. - -#### Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method and the return type of the implementing method is assignable to `type`, the node is not lifted. - -- If either or both of `expression`.Type or `type` are a nullable value type and the corresponding non-nullable value types are equal to the argument type and the return type of the implementing method respectively, the node is lifted. - - If the implementing method is `null`: - -- If both `expression`.Type and `type` are non-nullable, the node is not lifted. - -- Otherwise the node is lifted. - + property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If either `expression`.Type or `type` is a user-defined type that defines an implicit or explicit conversion operator, the that represents that operator is the implementing method. + +- Otherwise: + + - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. + + - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. + +#### Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method and the return type of the implementing method is assignable to `type`, the node is not lifted. + +- If either or both of `expression`.Type or `type` are a nullable value type and the corresponding non-nullable value types are equal to the argument type and the return type of the implementing method respectively, the node is lifted. + + If the implementing method is `null`: + +- If both `expression`.Type and `type` are non-nullable, the node is not lifted. + +- Otherwise the node is lifted. + ]]> @@ -5571,55 +5503,55 @@ Creates a that represents a conversion operation that throws an exception if the target type is overflowed and for which the implementing method is specified. A that has the property equal to and the , , and properties set to the specified values. - property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If method is not `null`, it is the implementing method. It must represent a non-void, `static` (`Shared` in Visual Basic) method that takes one argument. - -- Otherwise, if either `expression`.Type or `type` is a user-defined type that defines an implicit or explicit conversion operator, the that represents that operator is the implementing method. - -- Otherwise: - - - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. - - - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. - -#### Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method and the return type of the implementing method is assignable to `type`, the node is not lifted. - -- If either or both of `expression`.Type or `type` are a nullable value type and the corresponding non-nullable value types are equal to the argument type and the return type of the implementing method respectively, the node is lifted. - - If the implementing method is `null`: - -- If both `expression`.Type and `type` are non-nullable, the node is not lifted. - -- Otherwise the node is lifted. - + property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If method is not `null`, it is the implementing method. It must represent a non-void, `static` (`Shared` in Visual Basic) method that takes one argument. + +- Otherwise, if either `expression`.Type or `type` is a user-defined type that defines an implicit or explicit conversion operator, the that represents that operator is the implementing method. + +- Otherwise: + + - If both `expression`.Type and `type` represent numeric or Boolean types, or nullable or non-nullable enumeration types, the implementing method is `null`. + + - If either `expression`.Type or `type` is a reference type and an explicit boxing, unboxing, or reference conversion exists from `expression`.Type to `type`, the implementing method is `null`. + +#### Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method and the return type of the implementing method is assignable to `type`, the node is not lifted. + +- If either or both of `expression`.Type or `type` are a nullable value type and the corresponding non-nullable value types are equal to the argument type and the return type of the implementing method respectively, the node is lifted. + + If the implementing method is `null`: + +- If both `expression`.Type and `type` are non-nullable, the node is not lifted. + +- Otherwise the node is lifted. + ]]> or is . is not and the method it represents returns , is not ( in Visual Basic), or does not take exactly one argument. - No conversion operator is defined between .Type and . - - -or- - - .Type is not assignable to the argument type of the method represented by . - - -or- - - The return type of the method represented by is not assignable to . - - -or- - + No conversion operator is defined between .Type and . + + -or- + + .Type is not assignable to the argument type of the method represented by . + + -or- + + The return type of the method represented by is not assignable to . + + -or- + .Type or is a nullable value type and the corresponding non-nullable value type does not equal the argument type or the return type, respectively, of the method represented by . More than one method that matches the description was found. @@ -5736,19 +5668,19 @@ Creates a that represents the decrementing of the expression by 1. A that represents the decremented expression. - @@ -5805,11 +5737,11 @@ Creates a that represents the decrementing of the expression by 1. A that represents the decremented expression. - @@ -5856,14 +5788,14 @@ Creates a that has the property set to the specified type. A that has the property equal to and the property set to the specified type. - @@ -5931,45 +5863,45 @@ Creates a that represents an arithmetic division operation. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the division operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined division operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined division operator. - - - -## Examples - The following code example shows how to create an expression that divides its first argument by its second argument. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the division operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined division operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined division operator. + + + +## Examples + The following code example shows how to create an expression that divides its first argument by its second argument. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet7"::: + ]]> @@ -6032,39 +5964,39 @@ Creates a that represents an arithmetic division operation. The implementing method can be specified. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the division operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined division operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined division operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the division operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined division operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined division operator. + ]]> @@ -6319,11 +6251,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to and has the and set to the specified values. - property of the result will be inferred from the types of the arguments and the specified return type. - + property of the result will be inferred from the types of the arguments and the specified return type. + ]]> @@ -6371,11 +6303,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to and has the and set to the specified values. - property of the result will be inferred from the types of the arguments and the specified return type. - + property of the result will be inferred from the types of the arguments and the specified return type. + ]]> @@ -6430,11 +6362,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to and has the and set to the specified values. - property of the result will be inferred from the types of the arguments and the specified return type. - + property of the result will be inferred from the types of the arguments and the specified return type. + ]]> @@ -6484,11 +6416,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to and has the and set to the specified values. - property of the result will be inferred from the types of the arguments and the specified return type. - + property of the result will be inferred from the types of the arguments and the specified return type. + ]]> @@ -6540,11 +6472,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to and has the and set to the specified values. - property of the result will be inferred from the types of the arguments and the specified return type. - + property of the result will be inferred from the types of the arguments and the specified return type. + ]]> @@ -6598,11 +6530,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to and has the and set to the specified values. - property of the result will be inferred from the types of the arguments and the specified return type. - + property of the result will be inferred from the types of the arguments and the specified return type. + ]]> @@ -6664,42 +6596,42 @@ Creates an , given an as the second argument. An that has the and properties set to the specified values. - property of each element in `arguments` must be assignable to the type of the corresponding parameter of the add method, possibly after *quoting*. - + property of each element in `arguments` must be assignable to the type of the corresponding parameter of the add method, possibly after *quoting*. + > [!NOTE] -> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. - - - -## Examples - The following example demonstrates how to use the method to create an that represents calling the method to initialize an element of a dictionary collection. - +> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. + + + +## Examples + The following example demonstrates how to use the method to create an that represents calling the method to initialize an element of a dictionary collection. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet4"::: + ]]> or is . - The method that represents is not named "Add" (case insensitive). - - -or- - - The method that represents is not an instance method. - - -or- - - does not contain the same number of elements as the number of parameters for the method that represents. - - -or- - - The property of one or more elements of is not assignable to the type of the corresponding parameter of the method that represents. - - - + The method that represents is not named "Add" (case insensitive). + + -or- + + The method that represents is not an instance method. + + -or- + + does not contain the same number of elements as the number of parameters for the method that represents. + + -or- + + The property of one or more elements of is not assignable to the type of the corresponding parameter of the method that represents. + + + @@ -6757,38 +6689,38 @@ Creates an , given an array of values as the second argument. An that has the and properties set to the specified values. - property of each element in `arguments` must be assignable to the type of the corresponding parameter of the add method, possibly after *quoting*. - + property of each element in `arguments` must be assignable to the type of the corresponding parameter of the add method, possibly after *quoting*. + > [!NOTE] -> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. - - - -## Examples - The following example demonstrates how to use the method to create an that represents calling the method to initialize an element of a dictionary collection. - +> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. + + + +## Examples + The following example demonstrates how to use the method to create an that represents calling the method to initialize an element of a dictionary collection. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet4"::: + ]]> or is . - The method that addMethod represents is not named "Add" (case insensitive). - - -or- - - The method that addMethod represents is not an instance method. - - -or- - - arguments does not contain the same number of elements as the number of parameters for the method that addMethod represents. - - -or- - + The method that addMethod represents is not named "Add" (case insensitive). + + -or- + + The method that addMethod represents is not an instance method. + + -or- + + arguments does not contain the same number of elements as the number of parameters for the method that addMethod represents. + + -or- + The property of one or more elements of is not assignable to the type of the corresponding parameter of the method that represents. @@ -6831,19 +6763,19 @@ Creates an empty expression that has type. A that has the property equal to and the property set to . - @@ -6911,43 +6843,43 @@ Creates a that represents an equality comparison. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the equality operator, the that represents that method is the implementing method. - -- Otherwise, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is : - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . - - - -## Examples - The following code example shows how to create an expression that checks whether the values of its two arguments are equal. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the equality operator, the that represents that method is the implementing method. + +- Otherwise, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is : + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . + + + +## Examples + The following code example shows how to create an expression that checks whether the values of its two arguments are equal. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet8"::: + ]]> @@ -7013,37 +6945,37 @@ Creates a that represents an equality comparison. The implementing method can be specified. A that has the property equal to and the , , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the equality operator, the that represents that method is the implementing method. - -- Otherwise, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the equality operator, the that represents that method is the implementing method. + +- Otherwise, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. + ]]> @@ -7117,45 +7049,45 @@ Creates a that represents a bitwise operation, using op_ExclusiveOr for user-defined types. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the `XOR` operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined `XOR` operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined `XOR` operator. - - - -## Examples - The following code example shows how to create an expression that represents the logical XOR operation. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the `XOR` operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined `XOR` operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined `XOR` operator. + + + +## Examples + The following code example shows how to create an expression that represents the logical XOR operation. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet9"::: + ]]> @@ -7218,39 +7150,39 @@ Creates a that represents a bitwise operation, using op_ExclusiveOr for user-defined types. The implementing method can be specified. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the chosen implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the `XOR` operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined `XOR` operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined `XOR` operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the chosen implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the `XOR` operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined `XOR` operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined `XOR` operator. + ]]> @@ -7517,18 +7449,18 @@ Creates a that represents accessing a field. A that has the property equal to and the and properties set to the specified values. - property of the resulting is equal to the property of `field`. - + property of the resulting is equal to the property of `field`. + ]]> - is . - - -or- - + is . + + -or- + The field represented by is not ( in Visual Basic) and is . .Type is not assignable to the declaring type of the field represented by . @@ -7585,21 +7517,21 @@ Creates a that represents accessing a field given the name of the field. A that has the property equal to , the property set to , and the property set to the that represents the field denoted by . - property of the resulting is equal to the property of the that represents the field denoted by `fieldName`. - - This method searches `expression`.Type and its base types for a field that has the name `fieldName`. Public fields are given preference over non-public fields. If a matching field is found, this method passes `expression` and the that represents that field to . - - - -## Examples - The following code example shows how to create an expression that represents accessing a field. - + property of the resulting is equal to the property of the that represents the field denoted by `fieldName`. + + This method searches `expression`.Type and its base types for a field that has the name `fieldName`. Public fields are given preference over non-public fields. If a matching field is found, this method passes `expression` and the that represents that field to . + + + +## Examples + The following code example shows how to create an expression that represents accessing a field. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet37"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet37"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet37"::: + ]]> @@ -7725,12 +7657,12 @@ Creates a object that represents a generic delegate type that has specific type arguments. The type of a delegate that has the specified type arguments. - object represents the constructed delegate type `System.Action` in C# or `System.Action(Of T1,…,Tn)` in Visual Basic. - + ]]> @@ -7788,8 +7720,8 @@ As an example, if the elements of `typeArgs` represent the types `T1…Tn`, the Gets a object that represents a generic or delegate type that has specific type arguments. The delegate type. - Creates a object that represents a generic delegate type that has specific type arguments. The last type argument specifies the return type of the created delegate. The type of a delegate that has the specified type arguments. - object represents the constructed delegate type `System.Func` in C# or `System.Func(Of T1,…,Tn)` in Visual Basic. - + object represents the constructed delegate type `System.Func` in C# or `System.Func(Of T1,…,Tn)` in Visual Basic. + ]]> @@ -7924,14 +7856,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a representing a "go to" statement. A with equal to Goto, the property set to the specified value, and a null value to be passed to the target label upon jumping. - object. - + object. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet45"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet45"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet45"::: + ]]> @@ -8167,45 +8099,45 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a "greater than" numeric comparison. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the "greater than" operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is : - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . - - - -## Examples - The following code example shows how to create an expression that compares two integers. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the "greater than" operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is : + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . + + + +## Examples + The following code example shows how to create an expression that compares two integers. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet10"::: + ]]> @@ -8271,39 +8203,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a "greater than" numeric comparison. The implementing method can be specified. A that has the property equal to and the , , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation : - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "greater than" operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation : + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "greater than" operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. + ]]> @@ -8377,45 +8309,45 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a "greater than or equal" numeric comparison. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the "greater than or equal" operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is : - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . - - - -## Examples - The following code example shows how to create an expression that compares two integers. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the "greater than or equal" operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is : + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . + + + +## Examples + The following code example shows how to create an expression that compares two integers. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet11"::: + ]]> @@ -8481,39 +8413,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a "greater than or equal" numeric comparison. A that has the property equal to and the , , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "greater than or equal" operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "greater than or equal" operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. + ]]> @@ -8568,14 +8500,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a conditional block with an statement. A that has the property equal to and the , , properties set to the specified values. The property is set to default expression and the type of the resulting returned by this method is . - @@ -8626,14 +8558,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a conditional block with and statements. A that has the property equal to and the , , and properties set to the specified values. The type of the resulting returned by this method is . - @@ -8698,19 +8630,19 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents the incrementing of the expression value by 1. A that represents the incremented expression. - @@ -8767,11 +8699,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents the incrementing of the expression by 1. A that represents the incremented expression. - @@ -8841,33 +8773,33 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates an that applies a delegate or lambda expression to a list of argument expressions. An that applies the specified delegate or lambda expression to the provided arguments. - property of the resulting represents the return type of the delegate that is represented by `expression`.Type. - - The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments` except that some of these objects may be *quoted*. - + property of the resulting represents the return type of the delegate that is represented by `expression`.Type. + + The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments` except that some of these objects may be *quoted*. + > [!NOTE] -> An element will be quoted only if the corresponding parameter of the delegate represented by `expression` is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. - - - -## Examples - The following example demonstrates how to use the method to create an that represents the invocation of a lambda expression with specified arguments. - +> An element will be quoted only if the corresponding parameter of the delegate represented by `expression` is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. + + + +## Examples + The following example demonstrates how to use the method to create an that represents the invocation of a lambda expression with specified arguments. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet6"::: + ]]> is . - .Type does not represent a delegate type or an . - - -or- - + .Type does not represent a delegate type or an . + + -or- + The property of an element of is not assignable to the type of the corresponding parameter of the delegate represented by . does not contain the same number of elements as the list of parameters for the delegate represented by . @@ -8930,33 +8862,33 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates an that applies a delegate or lambda expression to a list of argument expressions. An that applies the specified delegate or lambda expression to the provided arguments. - property of the resulting represents the return type of the delegate that is represented by `expression`.Type. - - The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments` except that some of these objects may be *quoted*. - + property of the resulting represents the return type of the delegate that is represented by `expression`.Type. + + The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments` except that some of these objects may be *quoted*. + > [!NOTE] -> An element will be quoted only if the corresponding parameter of the delegate represented by `expression` is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. - - - -## Examples - The following example demonstrates how to use the method to create an that represents the invocation of a lambda expression with specified arguments. - +> An element will be quoted only if the corresponding parameter of the delegate represented by `expression` is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. + + + +## Examples + The following example demonstrates how to use the method to create an that represents the invocation of a lambda expression with specified arguments. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet6"::: + ]]> is . - .Type does not represent a delegate type or an . - - -or- - + .Type does not represent a delegate type or an . + + -or- + The property of an element of is not assignable to the type of the corresponding parameter of the delegate represented by . does not contain the same number of elements as the list of parameters for the delegate represented by . @@ -9245,14 +9177,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a representing a label with void type and no name. The new . - object. - + object. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet43"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet43"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet43"::: + ]]> @@ -9407,14 +9339,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a representing a label with the given type. The new . - object in a loop expression. - + object in a loop expression. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet44"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet44"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet44"::: + ]]> @@ -9656,22 +9588,22 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a by first constructing a delegate type from the expression body, and an array of parameter expressions. It can be used when the delegate type is not known at compile time. A that has the property equal to and the and properties set to the specified values. - factory methods to create a . - + factory methods to create a . + ]]> - is . - - -or- - + is . + + -or- + One or more elements of are . contains more than sixteen elements. @@ -9929,47 +9861,47 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a where the delegate type is known at compile time, with an enumerable collection of parameter expressions. An object that represents a lambda expression which has the property equal to and the and properties set to the specified values. - . The type is used to represent the returned object because the concrete type of the lambda expression is not known at compile time. - - The number of parameters for the delegate type represented by`delegateType` must equal the length of `parameters`. - - The elements of `parameters` must be reference equal to the parameter expressions in `body`. - - The property of the resulting object is equal to `delegateType`. If `parameters` is `null`, the property of the resulting object is an empty collection. - - - -## Examples - The following example demonstrates how to create an expression that represents a lambda expression that adds 1 to the passed argument. - + . The type is used to represent the returned object because the concrete type of the lambda expression is not known at compile time. + + The number of parameters for the delegate type represented by`delegateType` must equal the length of `parameters`. + + The elements of `parameters` must be reference equal to the parameter expressions in `body`. + + The property of the resulting object is equal to `delegateType`. If `parameters` is `null`, the property of the resulting object is an empty collection. + + + +## Examples + The following example demonstrates how to create an expression that represents a lambda expression that adds 1 to the passed argument. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet42"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet42"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet42"::: + ]]> - or is . - - -or- - + or is . + + -or- + One or more elements in are . - does not represent a delegate type. - - -or- - - .Type represents a type that is not assignable to the return type of the delegate type represented by . - - -or- - - does not contain the same number of elements as the list of parameters for the delegate type represented by . - - -or- - - The property of an element of is not assignable from the type of the corresponding parameter type of the delegate type represented by . + does not represent a delegate type. + + -or- + + .Type represents a type that is not assignable to the return type of the delegate type represented by . + + -or- + + does not contain the same number of elements as the list of parameters for the delegate type represented by . + + -or- + + The property of an element of is not assignable from the type of the corresponding parameter type of the delegate type represented by . @@ -10037,38 +9969,38 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a where the delegate type is known at compile time, with an array of parameter expressions. An object that represents a lambda expression which has the property equal to and the and properties set to the specified values. - . The type is used to represent the returned object because the concrete type of the lambda expression is not known at compile time. - - The number of parameters for the delegate type represented by `delegateType` must equal the length of `parameters`. - - The elements of `parameters` must be reference equal to the parameter expressions in `body`. - - The property of the resulting object is equal to `delegateType`. If `parameters` is `null`, the property of the resulting object is an empty collection. - + . The type is used to represent the returned object because the concrete type of the lambda expression is not known at compile time. + + The number of parameters for the delegate type represented by `delegateType` must equal the length of `parameters`. + + The elements of `parameters` must be reference equal to the parameter expressions in `body`. + + The property of the resulting object is equal to `delegateType`. If `parameters` is `null`, the property of the resulting object is an empty collection. + ]]> - or is . - - -or- - + or is . + + -or- + One or more elements in are . - does not represent a delegate type. - - -or- - - .Type represents a type that is not assignable to the return type of the delegate type represented by . - - -or- - - does not contain the same number of elements as the list of parameters for the delegate type represented by . - - -or- - + does not represent a delegate type. + + -or- + + .Type represents a type that is not assignable to the return type of the delegate type represented by . + + -or- + + does not contain the same number of elements as the list of parameters for the delegate type represented by . + + -or- + The property of an element of is not assignable from the type of the corresponding parameter type of the delegate type represented by . @@ -10471,36 +10403,36 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates an where the delegate type is known at compile time, with an enumerable collection of parameter expressions. An that has the property equal to and the and properties set to the specified values. - property of the resulting object represents the type `TDelegate`. If `parameters` is `null`, the property of the resulting object is an empty collection. - + property of the resulting object represents the type `TDelegate`. If `parameters` is `null`, the property of the resulting object is an empty collection. + ]]> - is . - - -or- - + is . + + -or- + One or more elements in are . - is not a delegate type. - - -or- - - .Type represents a type that is not assignable to the return type of . - - -or- - - does not contain the same number of elements as the list of parameters for . - - -or- - + is not a delegate type. + + -or- + + .Type represents a type that is not assignable to the return type of . + + -or- + + does not contain the same number of elements as the list of parameters for . + + -or- + The property of an element of is not assignable from the type of the corresponding parameter type of . @@ -10572,36 +10504,36 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates an where the delegate type is known at compile time, with an array of parameter expressions. An that has the property equal to and the and properties set to the specified values. - property of the resulting object represents the type `TDelegate`. If `parameters` is `null`, the property of the resulting object is an empty collection. - + property of the resulting object represents the type `TDelegate`. If `parameters` is `null`, the property of the resulting object is an empty collection. + ]]> - is . - - -or- - + is . + + -or- + One or more elements in are . - is not a delegate type. - - -or- - - .Type represents a type that is not assignable to the return type of . - - -or- - - does not contain the same number of elements as the list of parameters for . - - -or- - + is not a delegate type. + + -or- + + .Type represents a type that is not assignable to the return type of . + + -or- + + does not contain the same number of elements as the list of parameters for . + + -or- + The property of an element of is not assignable from the type of the corresponding parameter type of . @@ -10968,37 +10900,37 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a bitwise left-shift operation. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the selected implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the left-shift operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined left-shift operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined left-shift operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the selected implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the left-shift operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined left-shift operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined left-shift operator. + ]]> @@ -11061,39 +10993,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a bitwise left-shift operation. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the selected implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the left-shift operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined left-shift operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined left-shift operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the selected implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the left-shift operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined left-shift operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined left-shift operator. + ]]> @@ -11358,45 +11290,45 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a "less than" numeric comparison. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The implementing method for the operation is chosen based on the following rules: - -- If the property of either `left` or `right` represents a user-defined type that overloads the "less than" operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is : - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . - - - -## Examples - The following code example shows how to create an expression that compares two integers. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The implementing method for the operation is chosen based on the following rules: + +- If the property of either `left` or `right` represents a user-defined type that overloads the "less than" operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is : + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . + + + +## Examples + The following code example shows how to create an expression that compares two integers. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet25"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet25"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet25"::: + ]]> @@ -11462,39 +11394,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a "less than" numeric comparison. A that has the property equal to and the , , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "less than" operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "less than" operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. + ]]> @@ -11568,45 +11500,45 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a " less than or equal" numeric comparison. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the "less than or equal" operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is : - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . - - - -## Examples - The following code example shows how to create an expression that compares two integers. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the "less than or equal" operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is : + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . + + + +## Examples + The following code example shows how to create an expression that compares two integers. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet26"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet26"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet26"::: + ]]> @@ -11672,39 +11604,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a "less than or equal" numeric comparison. A that has the property equal to and the , , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "less than or equal" operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "less than or equal" operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. + ]]> @@ -11773,16 +11705,16 @@ As with `Func`, the last argument is the return type. It can be set to `System.V A that has the property equal to and the and properties set to the specified values. To be added. - is . - - -or- - + is . + + -or- + One or more elements of are . - does not represent a field or property. - - -or- - + does not represent a field or property. + + -or- + The or of the field or property that represents does not implement . @@ -11839,16 +11771,16 @@ As with `Func`, the last argument is the return type. It can be set to `System.V A that has the property equal to and the and properties set to the specified values. To be added. - is . - - -or- - + is . + + -or- + One or more elements of are . - does not represent a field or property. - - -or- - + does not represent a field or property. + + -or- + The or of the field or property that represents does not implement . @@ -11904,16 +11836,16 @@ As with `Func`, the last argument is the return type. It can be set to `System.V A that has the property equal to , the property set to the that represents the property accessed in , and populated with the elements of . To be added. - is . - - -or- - + is . + + -or- + One or more elements of are . - does not represent a property accessor method. - - -or- - + does not represent a property accessor method. + + -or- + The of the property that the method represented by accesses does not implement . @@ -11976,16 +11908,16 @@ As with `Func`, the last argument is the return type. It can be set to `System.V A that has the property equal to , the property set to the that represents the property accessed in , and populated with the elements of . To be added. - is . - - -or- - + is . + + -or- + One or more elements of are . - does not represent a property accessor method. - - -or- - + does not represent a property accessor method. + + -or- + The of the property that the method represented by accesses does not implement . @@ -12046,28 +11978,28 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that uses specified objects to initialize a collection. A that has the property equal to and the and properties set to the specified values. - property of `newExpression` must represent a type that implements . - - The property of the resulting is equal to `newExpression`.Type. - - - -## Examples - The following example demonstrates how to use the method to create a that represents the initialization of a new dictionary instance with two key-value pairs. - + property of `newExpression` must represent a type that implements . + + The property of the resulting is equal to `newExpression`.Type. + + + +## Examples + The following example demonstrates how to use the method to create a that represents the initialization of a new dictionary instance with two key-value pairs. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet7"::: + ]]> - or is . - - -or- - + or is . + + -or- + One or more elements of are . .Type does not implement . @@ -12124,39 +12056,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that uses a method named "Add" to add elements to a collection. A that has the property equal to and the property set to the specified value. - property of `newExpression` must represent a type that implements . - - In order to use this overload of , `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. The type of the argument must be assignable from the type represented by the property of the first element of `initializers`. - - The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of represents the add method that was discovered on `newExpression`.Type or its base type. - - The property of the resulting is equal to `newExpression`.Type. - + property of `newExpression` must represent a type that implements . + + In order to use this overload of , `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. The type of the argument must be assignable from the type represented by the property of the first element of `initializers`. + + The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of represents the add method that was discovered on `newExpression`.Type or its base type. + + The property of the resulting is equal to `newExpression`.Type. + ]]> - or is . - - -or- - + or is . + + -or- + One or more elements of are . .Type does not implement . - There is no instance method named "Add" (case insensitive) declared in .Type or its base type. - - -or- - - The add method on .Type or its base type does not take exactly one argument. - - -or- - - The type represented by the property of the first element of is not assignable to the argument type of the add method on .Type or its base type. - - -or- - + There is no instance method named "Add" (case insensitive) declared in .Type or its base type. + + -or- + + The add method on .Type or its base type does not take exactly one argument. + + -or- + + The type represented by the property of the first element of is not assignable to the argument type of the add method on .Type or its base type. + + -or- + More than one argument-compatible method named "Add" (case-insensitive) exists on .Type and/or its base type. @@ -12212,28 +12144,28 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that uses specified objects to initialize a collection. A that has the property equal to and the and properties set to the specified values. - property of `newExpression` must represent a type that implements . - - The property of the resulting is equal to `newExpression`.Type. - - - -## Examples - The following example demonstrates how to use the method to create a that represents the initialization of a new dictionary instance with two key-value pairs. - + property of `newExpression` must represent a type that implements . + + The property of the resulting is equal to `newExpression`.Type. + + + +## Examples + The following example demonstrates how to use the method to create a that represents the initialization of a new dictionary instance with two key-value pairs. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet7"::: + ]]> - or is . - - -or- - + or is . + + -or- + One or more elements of are . .Type does not implement . @@ -12297,39 +12229,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that uses a method named "Add" to add elements to a collection. A that has the property equal to and the property set to the specified value. - property of `newExpression` must represent a type that implements . - - In order to use this overload of , `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. The type of the argument must be assignable from the type represented by the property of the first element of `initializers`. - - The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of represents the add method that was discovered on `newExpression`.Type or its base type. - - The property of the resulting is equal to `newExpression`.Type. - + property of `newExpression` must represent a type that implements . + + In order to use this overload of , `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. The type of the argument must be assignable from the type represented by the property of the first element of `initializers`. + + The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of represents the add method that was discovered on `newExpression`.Type or its base type. + + The property of the resulting is equal to `newExpression`.Type. + ]]> - or is . - - -or- - + or is . + + -or- + One or more elements of are . .Type does not implement . - There is no instance method named "Add" (case insensitive) declared in .Type or its base type. - - -or- - - The add method on .Type or its base type does not take exactly one argument. - - -or- - - The type represented by the property of the first element of is not assignable to the argument type of the add method on .Type or its base type. - - -or- - + There is no instance method named "Add" (case insensitive) declared in .Type or its base type. + + -or- + + The add method on .Type or its base type does not take exactly one argument. + + -or- + + The type represented by the property of the first element of is not assignable to the argument type of the add method on .Type or its base type. + + -or- + More than one argument-compatible method named "Add" (case-insensitive) exists on .Type and/or its base type. @@ -12394,34 +12326,34 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that uses a specified method to add elements to a collection. A that has the property equal to and the property set to the specified value. - property of `newExpression` must represent a type that implements . - - If `addMethod` is `null`, `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. If `addMethod` is not `null`, it must represent an instance method named "Add" (case insensitive) that has exactly one parameter. The type represented by the property of each element of `initializers` must be assignable to the argument type of the add method. - - The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of is equal to `addMethod`. - - The property of the resulting is equal to `newExpression`.Type. - + property of `newExpression` must represent a type that implements . + + If `addMethod` is `null`, `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. If `addMethod` is not `null`, it must represent an instance method named "Add" (case insensitive) that has exactly one parameter. The type represented by the property of each element of `initializers` must be assignable to the argument type of the add method. + + The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of is equal to `addMethod`. + + The property of the resulting is equal to `newExpression`.Type. + ]]> - or is . - - -or- - + or is . + + -or- + One or more elements of are . - .Type does not implement . - - -or- - - is not and it does not represent an instance method named "Add" (case insensitive) that takes exactly one argument. - - -or- - + .Type does not implement . + + -or- + + is not and it does not represent an instance method named "Add" (case insensitive) that takes exactly one argument. + + -or- + is not and the type represented by the property of one or more elements of is not assignable to the argument type of the method that represents. is and no instance method named "Add" that takes one type-compatible argument exists on .Type or its base type. @@ -12495,34 +12427,34 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that uses a specified method to add elements to a collection. A that has the property equal to and the property set to the specified value. - property of `newExpression` must represent a type that implements . - - If `addMethod` is `null`, `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. If `addMethod` is not `null`, it must represent an instance method named "Add" (case insensitive) that has exactly one parameter. The type represented by the property of each element of `initializers` must be assignable to the argument type of the add method. - - The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of is equal to `addMethod`. - - The property of the resulting is equal to `newExpression`.Type. - + property of `newExpression` must represent a type that implements . + + If `addMethod` is `null`, `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. If `addMethod` is not `null`, it must represent an instance method named "Add" (case insensitive) that has exactly one parameter. The type represented by the property of each element of `initializers` must be assignable to the argument type of the add method. + + The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of is equal to `addMethod`. + + The property of the resulting is equal to `newExpression`.Type. + ]]> - or is . - - -or- - + or is . + + -or- + One or more elements of are . - .Type does not implement . - - -or- - - is not and it does not represent an instance method named "Add" (case insensitive) that takes exactly one argument. - - -or- - + .Type does not implement . + + -or- + + is not and it does not represent an instance method named "Add" (case insensitive) that takes exactly one argument. + + -or- + is not and the type represented by the property of one or more elements of is not assignable to the argument type of the method that represents. is and no instance method named "Add" that takes one type-compatible argument exists on .Type or its base type. @@ -12648,14 +12580,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a with the given body and break target. The created . - object. - + object. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet44"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet44"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet44"::: + ]]> @@ -12788,19 +12720,19 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a , given the left and right operands, by calling an appropriate factory method. The that results from calling the appropriate factory method. - factory method this method calls. For example, if `binaryType` is , this method invokes . - - - -## Examples - The following example demonstrates how to use the method to create a that represents the subtraction of one number from another. - + factory method this method calls. For example, if `binaryType` is , this method invokes . + + + +## Examples + The following example demonstrates how to use the method to create a that represents the subtraction of one number from another. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet8"::: + ]]> @@ -12875,11 +12807,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a , given the left operand, right operand and implementing method, by calling the appropriate factory method. The that results from calling the appropriate factory method. - factory method this method will call. For example, if `binaryType` is , this method invokes . The `liftToNull` and `method` parameters are ignored if the appropriate factory method does not have a corresponding parameter. - + factory method this method will call. For example, if `binaryType` is , this method invokes . The `liftToNull` and `method` parameters are ignored if the appropriate factory method does not have a corresponding parameter. + ]]> @@ -12957,11 +12889,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a , given the left operand, right operand, implementing method and type conversion function, by calling the appropriate factory method. The that results from calling the appropriate factory method. - factory method this method will call. For example, if `binaryType` is , this method invokes . The `liftToNull`, `method` and `conversion` parameters are ignored if the appropriate factory method does not have a corresponding parameter. - + factory method this method will call. For example, if `binaryType` is , this method invokes . The `liftToNull`, `method` and `conversion` parameters are ignored if the appropriate factory method does not have a corresponding parameter. + ]]> @@ -13033,11 +12965,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a representing a catch statement with the specified elements. The created . - @@ -13528,12 +13460,12 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents accessing either a field or a property. The that results from calling the appropriate factory method. - that represents accessing either a field or a property, depending on the type of `member`. If `member` is of type , this method calls to create the . If `member` is of type , this method calls to create the . - - ]]> + that represents accessing either a field or a property, depending on the type of `member`. If `member` is of type , this method calls to create the . If `member` is of type , this method calls to create the . + + ]]> is . @@ -13679,10 +13611,10 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a , given an operand, by calling the appropriate factory method. The that results from calling the appropriate factory method. - factory method this method calls. For example, if `unaryType` is equal to , this method invokes . The `type`parameter is ignored if it does not apply to the factory method that is called. + factory method this method calls. For example, if `unaryType` is equal to , this method invokes . The `type`parameter is ignored if it does not apply to the factory method that is called. ]]> @@ -13749,11 +13681,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a , given an operand and implementing method, by calling the appropriate factory method. The that results from calling the appropriate factory method. - factory method this method calls. For example, if `unaryType` is equal to , this method invokes . The `type` and `method` parameters are ignored if they do not apply to the factory method that is called. - + factory method this method calls. For example, if `unaryType` is equal to , this method invokes . The `type` and `method` parameters are ignored if they do not apply to the factory method that is called. + ]]> @@ -13819,20 +13751,20 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents the recursive initialization of members of a field or property. A that has the property equal to and the and properties set to the specified values. - or is . - does not represent a field or property. - - -or- - + does not represent a field or property. + + -or- + The property of an element of does not represent a member of the type of the field or property that represents. @@ -13888,20 +13820,20 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents the recursive initialization of members of a field or property. A that has the property equal to and the and properties set to the specified values. - or is . - does not represent a field or property. - - -or- - + does not represent a field or property. + + -or- + The property of an element of does not represent a member of the type of the field or property that represents. @@ -13959,10 +13891,10 @@ As with `Func`, the last argument is the return type. It can be set to `System.V or is . - does not represent a property accessor method. - - -or- - + does not represent a property accessor method. + + -or- + The property of an element of does not represent a member of the type of the property accessed by the method that represents. @@ -14027,10 +13959,10 @@ As with `Func`, the last argument is the return type. It can be set to `System.V or is . - does not represent a property accessor method. - - -or- - + does not represent a property accessor method. + + -or- + The property of an element of does not represent a member of the type of the property accessed by the method that represents. @@ -14091,19 +14023,19 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Represents an expression that creates a new object and initializes a property of the object. A that has the property equal to and the and properties set to the specified values. - property of the resulting is equal to the property of `newExpression`. - - - -## Examples - The following example demonstrates an expression that creates a new object and initializes a property of the object. - + property of the resulting is equal to the property of `newExpression`. + + + +## Examples + The following example demonstrates an expression that creates a new object and initializes a property of the object. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet40"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet40"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet40"::: + ]]> @@ -14163,19 +14095,19 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a . A that has the property equal to and the and properties set to the specified values. - property of the resulting is equal to the property of `newExpression`. - - - -## Examples - The following example demonstrates how to use the method to create a that represents the initialization of two members of a new object. - + property of the resulting is equal to the property of `newExpression`. + + + +## Examples + The following example demonstrates how to use the method to create a that represents the initialization of two members of a new object. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet9"::: + ]]> @@ -14246,37 +14178,37 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic remainder operation. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the selected implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the modulus operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined modulus operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined modulus operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the selected implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the modulus operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined modulus operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined modulus operator. + ]]> @@ -14339,39 +14271,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic remainder operation. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The implementing method for the operation is chosen based on the following rules: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the modulus operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined modulus operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined modulus operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The implementing method for the operation is chosen based on the following rules: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the modulus operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined modulus operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined modulus operator. + ]]> @@ -14636,45 +14568,45 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic multiplication operation that does not have overflow checking. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the selected implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined multiplication operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined multiplication operator. - - - -## Examples - The following code example shows how to create an expression that multiplies two values. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the selected implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined multiplication operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined multiplication operator. + + + +## Examples + The following code example shows how to create an expression that multiplies two values. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet27"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet27"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet27"::: + ]]> @@ -14737,39 +14669,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic multiplication operation that does not have overflow checking. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined multiplication operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined multiplication operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined multiplication operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined multiplication operator. + ]]> @@ -15225,37 +15157,37 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic multiplication operation that has overflow checking. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the selected implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined multiplication operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined multiplication operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the selected implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined multiplication operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined multiplication operator. + ]]> @@ -15318,39 +15250,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic multiplication operation that has overflow checking. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined multiplication operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined multiplication operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined multiplication operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined multiplication operator. + ]]> @@ -15422,39 +15354,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic negation operation. A that has the property equal to and the property set to the specified value. - property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `expression`.Type is a user-defined type that defines the unary minus operator, the that represents that operator is the implementing method. - -- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. - - - -## Examples - The following example demonstrates how to create an expression that represents an arithmetic negation operation. - + property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `expression`.Type is a user-defined type that defines the unary minus operator, the that represents that operator is the implementing method. + +- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. + + + +## Examples + The following example demonstrates how to create an expression that represents an arithmetic negation operation. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet50"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet50"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet50"::: + ]]> @@ -15515,33 +15447,33 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic negation operation. A that has the property equal to and the and properties set to the specified values. - property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes one argument, it is the implementing method for the node. - -- If `expression`.Type is a user-defined type that defines the unary minus operator, the that represents that operator is the implementing method. - -- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. - + property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes one argument, it is the implementing method for the node. + +- If `expression`.Type is a user-defined type that defines the unary minus operator, the that represents that operator is the implementing method. + +- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. + ]]> @@ -15549,10 +15481,10 @@ As with `Func`, the last argument is the return type. It can be set to `System.V is not and the method it represents returns , is not ( in Visual Basic), or does not take exactly one argument. - is and the unary minus operator is not defined for .Type. - - -or- - + is and the unary minus operator is not defined for .Type. + + -or- + .Type (or its corresponding non-nullable type if it is a nullable value type) is not assignable to the argument type of the method represented by . @@ -15617,31 +15549,31 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic negation operation that has overflow checking. A that has the property equal to and the property set to the specified value. - property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `expression`.Type is a user-defined type that defines the unary minus operator, the that represents that operator is the implementing method. - -- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. - + property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `expression`.Type is a user-defined type that defines the unary minus operator, the that represents that operator is the implementing method. + +- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. + ]]> @@ -15702,33 +15634,33 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic negation operation that has overflow checking. The implementing method can be specified. A that has the property equal to and the and properties set to the specified values. - property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes one argument, it is the implementing method for the node. - -- If `expression`.Type is a user-defined type that defines the unary minus operator, the that represents that operator is the implementing method. - -- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. - + property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes one argument, it is the implementing method for the node. + +- If `expression`.Type is a user-defined type that defines the unary minus operator, the that represents that operator is the implementing method. + +- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. + ]]> @@ -15736,10 +15668,10 @@ As with `Func`, the last argument is the return type. It can be set to `System.V is not and the method it represents returns , is not ( in Visual Basic), or does not take exactly one argument. - is and the unary minus operator is not defined for .Type. - - -or- - + is and the unary minus operator is not defined for .Type. + + -or- + .Type (or its corresponding non-nullable type if it is a nullable value type) is not assignable to the argument type of the method represented by . @@ -15804,11 +15736,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents calling the specified constructor that takes no arguments. A that has the property equal to and the property set to the specified value. - and properties of the resulting are empty collections. The property represents the declaring type of the constructor represented by `constructor`. - + and properties of the resulting are empty collections. The property represents the declaring type of the constructor represented by `constructor`. + ]]> @@ -15866,21 +15798,21 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents calling the parameterless constructor of the specified type. A that has the property equal to and the property set to the that represents the constructor without parameters for the specified type. - and properties of the resulting are empty collections. The property is equal to `type`. - - - -## Examples - The following example demonstrates how to use the method to create a that represents constructing a new instance of a dictionary object by calling the constructor without parameters. - + and properties of the resulting are empty collections. The property is equal to `type`. + + + +## Examples + The following example demonstrates how to use the method to create a that represents constructing a new instance of a dictionary object by calling the constructor without parameters. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet10"::: + ]]> @@ -15941,25 +15873,25 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents calling the specified constructor with the specified arguments. A that has the property equal to and the and properties set to the specified values. - property of the resulting is an empty collection. - - The property of the resulting represents the declaring type of the constructor represented by `constructor`. The property is an empty collection. - + property of the resulting is an empty collection. + + The property of the resulting represents the declaring type of the constructor represented by `constructor`. The property is an empty collection. + ]]> - is . - - -or- - + is . + + -or- + An element of is . - The parameter does not contain the same number of elements as the number of parameters for the constructor that represents. - - -or- - + The parameter does not contain the same number of elements as the number of parameters for the constructor that represents. + + -or- + The property of an element of is not assignable to the type of the corresponding parameter of the constructor that represents. @@ -16020,25 +15952,25 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents calling the specified constructor with the specified arguments. A that has the property equal to and the and properties set to the specified values. - property of the resulting is an empty collection. - - The property of the resulting represents the declaring type of the constructor represented by `constructor`. The property is an empty collection. - + property of the resulting is an empty collection. + + The property of the resulting represents the declaring type of the constructor represented by `constructor`. The property is an empty collection. + ]]> - is . - - -or- - + is . + + -or- + An element of is . - The length of does match the number of parameters for the constructor that represents. - - -or- - + The length of does match the number of parameters for the constructor that represents. + + -or- + The property of an element of is not assignable to the type of the corresponding parameter of the constructor that represents. @@ -16110,39 +16042,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents calling the specified constructor with the specified arguments. The members that access the constructor initialized fields are specified. A that has the property equal to and the , and properties set to the specified values. - property of the resulting is an empty collection. - - If `members` is `null`, the property of the resulting is an empty collection. If `members` is not `null`, it must have the same number of elements as `arguments` and each element must not be `null`. Each element of `members` must be a , or that represents an instance member on the declaring type of the constructor represented by `constructor`. If it represents a property, the property must have a `get` accessor. The corresponding element of `arguments` for each element of `members` must have a property that represents a type that is assignable to the type of the member that the `members` element represents. - - The property of the resulting represents the declaring type of the constructor that `constructor` represents. - + property of the resulting is an empty collection. + + If `members` is `null`, the property of the resulting is an empty collection. If `members` is not `null`, it must have the same number of elements as `arguments` and each element must not be `null`. Each element of `members` must be a , or that represents an instance member on the declaring type of the constructor represented by `constructor`. If it represents a property, the property must have a `get` accessor. The corresponding element of `arguments` for each element of `members` must have a property that represents a type that is assignable to the type of the member that the `members` element represents. + + The property of the resulting represents the declaring type of the constructor that `constructor` represents. + ]]> - is . - - -or- - - An element of is . - - -or- - + is . + + -or- + + An element of is . + + -or- + An element of is . - The parameter does not contain the same number of elements as the number of parameters for the constructor that represents. - - -or- - - The property of an element of is not assignable to the type of the corresponding parameter of the constructor that represents. - - -or- - - The parameter does not have the same number of elements as . - - -or- - + The parameter does not contain the same number of elements as the number of parameters for the constructor that represents. + + -or- + + The property of an element of is not assignable to the type of the corresponding parameter of the constructor that represents. + + -or- + + The parameter does not have the same number of elements as . + + -or- + An element of has a property that represents a type that is not assignable to the type of the member that is represented by the corresponding element of . @@ -16218,39 +16150,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents calling the specified constructor with the specified arguments. The members that access the constructor initialized fields are specified as an array. A that has the property equal to and the , and properties set to the specified values. - property of the resulting is an empty collection. - - If `members` is `null`, the property of the resulting is an empty collection. If `members` is not `null`, it must have the same number of elements as `arguments` and each element must not be `null`. Each element of `members` must be a , or that represents an instance member on the declaring type of the constructor represented by `constructor`. If it represents a property, the property must be able to retrieve the value of the associated field. The corresponding element of `arguments` for each element of `members` must have a property that represents a type that is assignable to the type of the member that the `members` element represents. - - The property of the resulting represents the declaring type of the constructor that `constructor` represents. - + property of the resulting is an empty collection. + + If `members` is `null`, the property of the resulting is an empty collection. If `members` is not `null`, it must have the same number of elements as `arguments` and each element must not be `null`. Each element of `members` must be a , or that represents an instance member on the declaring type of the constructor represented by `constructor`. If it represents a property, the property must be able to retrieve the value of the associated field. The corresponding element of `arguments` for each element of `members` must have a property that represents a type that is assignable to the type of the member that the `members` element represents. + + The property of the resulting represents the declaring type of the constructor that `constructor` represents. + ]]> - is . - - -or- - - An element of is . - - -or- - + is . + + -or- + + An element of is . + + -or- + An element of is . - The parameter does not contain the same number of elements as the number of parameters for the constructor that represents. - - -or- - - The property of an element of is not assignable to the type of the corresponding parameter of the constructor that represents. - - -or- - - The parameter does not have the same number of elements as . - - -or- - + The parameter does not contain the same number of elements as the number of parameters for the constructor that represents. + + -or- + + The property of an element of is not assignable to the type of the corresponding parameter of the constructor that represents. + + -or- + + The parameter does not have the same number of elements as . + + -or- + An element of has a property that represents a type that is not assignable to the type of the member that is represented by the corresponding element of . @@ -16317,28 +16249,28 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents creating an array that has a specified rank. A that has the property equal to and the property set to the specified value. - property of the resulting represents an array type whose rank is equal to the length of `bounds` and whose element type is `type`. - - The property of each element of `bounds` must represent an integral type. - - - -## Examples - The following example demonstrates how to use the method to create an expression tree that represents creating a string array that has a rank of 2. - + property of the resulting represents an array type whose rank is equal to the length of `bounds` and whose element type is `type`. + + The property of each element of `bounds` must represent an integral type. + + + +## Examples + The following example demonstrates how to use the method to create an expression tree that represents creating a string array that has a rank of 2. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet2"::: + ]]> - or is . - - -or- - + or is . + + -or- + An element of is . The property of an element of does not represent an integral type. @@ -16401,28 +16333,28 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents creating an array that has a specified rank. A that has the property equal to and the property set to the specified value. - property of the resulting represents an array type whose rank is equal to the length of `bounds` and whose element type is `type`. - - The property of each element of `bounds` must represent an integral type. - - - -## Examples - The following example demonstrates how to use the method to create an expression tree that represents creating a string array that has a rank of 2. - + property of the resulting represents an array type whose rank is equal to the length of `bounds` and whose element type is `type`. + + The property of each element of `bounds` must represent an integral type. + + + +## Examples + The following example demonstrates how to use the method to create an expression tree that represents creating a string array that has a rank of 2. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet2"::: + ]]> - or is . - - -or- - + or is . + + -or- + An element of is . The property of an element of does not represent an integral type. @@ -16490,31 +16422,31 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents creating a one-dimensional array and initializing it from a list of elements. A that has the property equal to and the property set to the specified value. - property of each element of `initializers` must represent a type that is assignable to the type represented by `type`, possibly after it is *quoted*. - + property of each element of `initializers` must represent a type that is assignable to the type represented by `type`, possibly after it is *quoted*. + > [!NOTE] -> An element will be quoted only if `type` is . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `initializers`. - - The property of the resulting represents an array type whose rank is 1 and whose element type is `type`. - - - -## Examples - The following example demonstrates how to use the method to create an expression tree that represents creating a one-dimensional string array that is initialized with a list of string expressions. - +> An element will be quoted only if `type` is . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `initializers`. + + The property of the resulting represents an array type whose rank is 1 and whose element type is `type`. + + + +## Examples + The following example demonstrates how to use the method to create an expression tree that represents creating a one-dimensional string array that is initialized with a list of string expressions. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet1"::: + ]]> - or is . - - -or- - + or is . + + -or- + An element of is . The property of an element of represents a type that is not assignable to the type that represents. @@ -16577,31 +16509,31 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents creating a one-dimensional array and initializing it from a list of elements. A that has the property equal to and the property set to the specified value. - property of each element of `initializers` must represent a type that is assignable to the type represented by `type`, possibly after it is *quoted*. - + property of each element of `initializers` must represent a type that is assignable to the type represented by `type`, possibly after it is *quoted*. + > [!NOTE] -> An element will be quoted only if `type` is . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `initializers`. - - The property of the resulting represents an array type whose rank is 1 and whose element type is `type`. - - - -## Examples - The following example demonstrates how to use the method to create an expression tree that represents creating a one-dimensional string array that is initialized with a list of string expressions. - +> An element will be quoted only if `type` is . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `initializers`. + + The property of the resulting represents an array type whose rank is 1 and whose element type is `type`. + + + +## Examples + The following example demonstrates how to use the method to create an expression tree that represents creating a one-dimensional string array that is initialized with a list of string expressions. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet1"::: + ]]> - or is . - - -or- - + or is . + + -or- + An element of is . The property of an element of represents a type that is not assignable to the type . @@ -16648,13 +16580,13 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Gets the node type of this . One of the values. - property provides a more specialized description of an than just its derived type. For example, a can be used to represent many different kinds of binary expressions, such as a division operation or a "greater than" operation. The property would describe these binary expressions as and , respectively. - - The static CLR type of the expression that the object represents is represented by the property. - + property provides a more specialized description of an than just its derived type. For example, a can be used to represent many different kinds of binary expressions, such as a division operation or a "greater than" operation. The property would describe these binary expressions as and , respectively. + + The static CLR type of the expression that the object represents is represented by the property. + ]]> @@ -16720,39 +16652,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a bitwise complement operation. A that has the property equal to and the property set to the specified value. - property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `expression`.Type is a user-defined type that defines the unary not operator, the that represents that operator is the implementing method. - -- Otherwise, if `expression`.Type is a numeric or Boolean type, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `expression`.Type is a nullable value type and the corresponding non-nullable type is equal to the argument type of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. - - - -## Examples - The following example demonstrates how to create an expression that represents a logical NOT operation. - + property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `expression`.Type is a user-defined type that defines the unary not operator, the that represents that operator is the implementing method. + +- Otherwise, if `expression`.Type is a numeric or Boolean type, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `expression`.Type is a nullable value type and the corresponding non-nullable type is equal to the argument type of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. + + + +## Examples + The following example demonstrates how to create an expression that represents a logical NOT operation. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet51"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet51"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet51"::: + ]]> @@ -16813,33 +16745,33 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a bitwise complement operation. The implementing method can be specified. A that has the property equal to and the and properties set to the specified values. - property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes one argument, it is the implementing method for the node. - -- If `expression`.Type is a user-defined type that defines the unary not operator, the that represents that operator is the implementing method. - -- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. - + property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes one argument, it is the implementing method for the node. + +- If `expression`.Type is a user-defined type that defines the unary not operator, the that represents that operator is the implementing method. + +- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. + ]]> @@ -16847,10 +16779,10 @@ As with `Func`, the last argument is the return type. It can be set to `System.V is not and the method it represents returns , is not ( in Visual Basic), or does not take exactly one argument. - is and the unary not operator is not defined for .Type. - - -or- - + is and the unary not operator is not defined for .Type. + + -or- + .Type (or its corresponding non-nullable type if it is a nullable value type) is not assignable to the argument type of the method represented by . @@ -16917,37 +16849,37 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an inequality comparison. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the inequality operator, the that represents that method is the implementing method. - -- Otherwise, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is : - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the inequality operator, the that represents that method is the implementing method. + +- Otherwise, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is : + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is . + ]]> @@ -17013,39 +16945,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an inequality comparison. A that has the property equal to and the , , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the inequality operator, the that represents that method is the implementing method. - -- Otherwise, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is . - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the inequality operator, the that represents that method is the implementing method. + +- Otherwise, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted; also, the type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is . + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is . + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is nullable if `liftToNull` is `true` or if `liftToNull` is `false`. + ]]> @@ -17235,45 +17167,45 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a bitwise operation. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined bitwise `OR` operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined bitwise `OR` operator. - - - -## Examples - The following code example shows how to create an expression that represents a logical OR operation. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined bitwise `OR` operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined bitwise `OR` operator. + + + +## Examples + The following code example shows how to create an expression that represents a logical OR operation. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet28"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet28"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet28"::: + ]]> @@ -17336,39 +17268,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a bitwise operation. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined bitwise `OR` operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined bitwise `OR` operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined bitwise `OR` operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined bitwise `OR` operator. + ]]> @@ -17633,58 +17565,58 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a conditional operation that evaluates the second operand only if the first operand evaluates to . A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. + > [!NOTE] - > The conditional `OR` operator cannot be overloaded in C# or Visual Basic. However, the conditional `OR` operator is evaluated by using the bitwise `OR` operator. Thus, a user-defined overload of the bitwise `OR` operator can be the implementing method for this node type. - -- Otherwise, if `left`.Type and `right`.Type are Boolean types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- `left`.Type and `right`.Type are the same Boolean type. - -- If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `OR` operator. - -- If `left`.Type and `right`.Type are nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined conditional `OR` operator. - - - -## Examples - The following code example shows how to create an expression that represents a logical `OR` operation that evaluates the second operand only if the first operand evaluates to `false`. - + > The conditional `OR` operator cannot be overloaded in C# or Visual Basic. However, the conditional `OR` operator is evaluated by using the bitwise `OR` operator. Thus, a user-defined overload of the bitwise `OR` operator can be the implementing method for this node type. + +- Otherwise, if `left`.Type and `right`.Type are Boolean types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- `left`.Type and `right`.Type are the same Boolean type. + +- If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `OR` operator. + +- If `left`.Type and `right`.Type are nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined conditional `OR` operator. + + + +## Examples + The following code example shows how to create an expression that represents a logical `OR` operation that evaluates the second operand only if the first operand evaluates to `false`. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet29"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet29"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet29"::: + ]]> or is . - The bitwise operator is not defined for .Type and .Type. - - -or- - + The bitwise operator is not defined for .Type and .Type. + + -or- + .Type and .Type are not the same Boolean type. @@ -17743,44 +17675,44 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a conditional operation that evaluates the second operand only if the first operand evaluates to . A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. + > [!NOTE] - > The conditional `OR` operator cannot be overloaded in C# or Visual Basic. However, the conditional `OR` operator is evaluated by using the bitwise `OR` operator. Thus, a user-defined overload of the bitwise `OR` operator can be the implementing method for this node type. - -- Otherwise, if `left`.Type and `right`.Type are Boolean types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- `left`.Type and `right`.Type are the same Boolean type. - -- If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `OR` operator. - -- If `left`.Type and `right`.Type are nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined conditional `OR` operator. - + > The conditional `OR` operator cannot be overloaded in C# or Visual Basic. However, the conditional `OR` operator is evaluated by using the bitwise `OR` operator. Thus, a user-defined overload of the bitwise `OR` operator can be the implementing method for this node type. + +- Otherwise, if `left`.Type and `right`.Type are Boolean types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable, and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- `left`.Type and `right`.Type are the same Boolean type. + +- If `left`.Type and `right`.Type are non-nullable, the node is not lifted. The type of the node is the result type of the predefined conditional `OR` operator. + +- If `left`.Type and `right`.Type are nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined conditional `OR` operator. + ]]> @@ -17788,10 +17720,10 @@ As with `Func`, the last argument is the return type. It can be set to `System.V is not and the method it represents returns , is not ( in Visual Basic), or does not take exactly two arguments. - is and the bitwise operator is not defined for .Type and .Type. - - -or- - + is and the bitwise operator is not defined for .Type and .Type. + + -or- + is and .Type and .Type are not the same Boolean type. @@ -17855,14 +17787,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a node that can be used to identify a parameter or a variable in an expression tree. A node with the specified name and type. - object that prints the value of a object. - + object that prints the value of a object. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet49"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet49"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet49"::: + ]]> @@ -18231,38 +18163,38 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents raising a number to a power. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the exponentiation operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are both , the implementing method is . - -#### Node Type and Lifted versus Non-Lifted - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the exponentiation operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are both , the implementing method is . + +#### Node Type and Lifted versus Non-Lifted + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + ]]> or is . - The exponentiation operator is not defined for .Type and .Type. - - -or- - + The exponentiation operator is not defined for .Type and .Type. + + -or- + .Type and/or .Type are not . @@ -18321,32 +18253,32 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents raising a number to a power. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the exponentiation operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are both , the implementing method is . - -#### Node Type and Lifted versus Non-Lifted - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the exponentiation operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are both , the implementing method is . + +#### Node Type and Lifted versus Non-Lifted + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + ]]> @@ -18354,10 +18286,10 @@ As with `Func`, the last argument is the return type. It can be set to `System.V is not and the method it represents returns , is not ( in Visual Basic), or does not take exactly two arguments. - is and the exponentiation operator is not defined for .Type and .Type. - - -or- - + is and the exponentiation operator is not defined for .Type and .Type. + + -or- + is and .Type and/or .Type are not . @@ -18867,26 +18799,26 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents accessing a property by using a property accessor method. A that has the property equal to , the property set to and the property set to the that represents the property accessed in . - property of the resulting is equal to the property of . - - If the method represented by `propertyAccessor` is `static` (`Shared` in Visual Basic), `expression` can be `null`. - + property of the resulting is equal to the property of . + + If the method represented by `propertyAccessor` is `static` (`Shared` in Visual Basic), `expression` can be `null`. + ]]> - is . - - -or- - + is . + + -or- + The method that represents is not ( in Visual Basic) and is . - .Type is not assignable to the declaring type of the method represented by . - - -or- - + .Type is not assignable to the declaring type of the method represented by . + + -or- + The method that represents is not a property accessor method. @@ -18943,20 +18875,20 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents accessing a property. A that has the property equal to and the and properties set to the specified values. - property of the resulting is equal to the property of . - - If the property represented by `property` is `static` (`Shared` in Visual Basic), `expression` can be `null`. - + property of the resulting is equal to the property of . + + If the property represented by `property` is `static` (`Shared` in Visual Basic), `expression` can be `null`. + ]]> - is . - - -or- - + is . + + -or- + The property that represents is not ( in Visual Basic) and is . .Type is not assignable to the declaring type of the property that represents. @@ -19013,21 +18945,21 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents accessing a property. A that has the property equal to , the property set to , and the property set to the that represents the property denoted by . - property of the resulting is equal to the property of the that represents the property denoted by `propertyName`. - - This method searches `expression`.Type and its base types for a property that has the name `propertyName`. Public properties are given preference over non-public properties. If a matching property is found, this method passes `expression` and the that represents that property to . - - - -## Examples - The following example shows how to create an expression that represents accessing a property. - + property of the resulting is equal to the property of the that represents the property denoted by `propertyName`. + + This method searches `expression`.Type and its base types for a property that has the name `propertyName`. Public properties are given preference over non-public properties. If a matching property is found, this method passes `expression` and the that represents that property to . + + + +## Examples + The following example shows how to create an expression that represents accessing a property. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet38"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet38"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet38"::: + ]]> @@ -19345,21 +19277,21 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents accessing a property or field. A that has the property equal to , the property set to , and the property set to the or that represents the property or field denoted by . - property of the resulting is equal to the or properties of the or , respectively, that represents the property or field denoted by `propertyOrFieldName`. - + property of the resulting is equal to the or properties of the or , respectively, that represents the property or field denoted by `propertyOrFieldName`. + This method searches `expression`.Type and its base types for an instance property or field that has the name `propertyOrFieldName`. Static properties or fields are not supported. Public properties and fields are given preference over non-public properties and fields. Also, properties are given preference over fields. If a matching property or field is found, this method passes `expression` and the or that represents that property or field to or , respectively. - - - -## Examples - The following example shows how to create an expression that represents accessing a property or field. - + + + +## Examples + The following example shows how to create an expression that represents accessing a property or field. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet39"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet39"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet39"::: + ]]> @@ -19410,11 +19342,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an expression that has a constant value of type . A that has the property equal to and the property set to the specified value. - property of the resulting represents the constructed type , where the type argument is the type represented by `expression`.Type. The property is `null`. Both and are `false`. - + property of the resulting represents the constructed type , where the type argument is the type represented by `expression`.Type. The property is `null`. Both and are `false`. + ]]> @@ -19501,11 +19433,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Reduces this node to a simpler expression. If CanReduce returns true, this should return a valid expression. This method can return another node which itself must be reduced. The reduced expression. - @@ -19860,14 +19792,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a representing a return statement. The value passed to the label upon jumping can be specified. A with equal to Continue, the property set to , and to be passed to the target label upon jumping. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet43"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet43"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet43"::: + ]]> @@ -20049,37 +19981,37 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a bitwise right-shift operation. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the selected implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the right-shift operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined right-shift operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined right-shift operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the selected implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the right-shift operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined right-shift operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined right-shift operator. + ]]> @@ -20142,39 +20074,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a bitwise right-shift operation. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the selected implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the right-shift operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined right-shift operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined right-shift operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the selected implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the right-shift operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined right-shift operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined right-shift operator. + ]]> @@ -20546,45 +20478,45 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic subtraction operation that does not have overflow checking. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the selected implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined subtraction operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined subtraction operator. - - - -## Examples - The following code example shows how to create an expression that subtracts the argument from the first argument. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the selected implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined subtraction operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined subtraction operator. + + + +## Examples + The following code example shows how to create an expression that subtracts the argument from the first argument. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet30"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet30"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet30"::: + ]]> @@ -20647,39 +20579,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic subtraction operation that does not have overflow checking. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined subtraction operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined subtraction operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined subtraction operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined subtraction operator. + ]]> @@ -21135,37 +21067,37 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic subtraction operation that has overflow checking. A that has the property equal to and the and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the selected implementing method for the operation: - -- If the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined subtraction operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined subtraction operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the selected implementing method for the operation: + +- If the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined subtraction operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined subtraction operator. + ]]> @@ -21228,39 +21160,39 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an arithmetic subtraction operation that has overflow checking. A that has the property equal to and the , , and properties set to the specified values. - has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. - - The following information describes the implementing method, the node type, and whether a node is lifted. - -#### Implementing Method - The following rules determine the implementing method for the operation : - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. - -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. - -- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`: - -- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined subtraction operator. - -- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined subtraction operator. - + has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + + The following information describes the implementing method, the node type, and whether a node is lifted. + +#### Implementing Method + The following rules determine the implementing method for the operation : + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. + +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. + +- Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `left`.Type and `right`.Type are assignable to the corresponding argument types of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `left`.Type and `right`.Type are both value types of which at least one is nullable and the corresponding non-nullable types are equal to the corresponding argument types of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`: + +- If `left`.Type and `right`.Type are both non-nullable, the node is not lifted. The type of the node is the result type of the predefined subtraction operator. + +- If `left`.Type and `right`.Type are both nullable, the node is lifted. The type of the node is the nullable type that corresponds to the result type of the predefined subtraction operator. + ]]> @@ -21339,23 +21271,23 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a statement without a default case. The created . - objects in a object must have the same type, unless the has the type `void`. - - Each object has an implicit `break` statement, which means that there is no implicit fall through from one case label to another. - - If `switchValue` does not match any of the cases, no exception is thrown. - - - -## Examples - The following example demonstrates how to create an expression that represents a switch statement without a default case. - + objects in a object must have the same type, unless the has the type `void`. + + Each object has an implicit `break` statement, which means that there is no implicit fall through from one case label to another. + + If `switchValue` does not match any of the cases, no exception is thrown. + + + +## Examples + The following example demonstrates how to create an expression that represents a switch statement without a default case. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet34"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet34"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet34"::: + ]]> @@ -21425,23 +21357,23 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a statement that has a default case. The created . - objects in a object must have the same type, unless the has the type `void`. - - Each object has an implicit `break` statement, which means that there is no implicit fall through from one case label to another. - - If `switchValue` does not match any of the cases, the default case represented by `defaultBody` is run. - - - -## Examples - The following example demonstrates how to create an expression that represents a switch statement that has a default case. - + objects in a object must have the same type, unless the has the type `void`. + + Each object has an implicit `break` statement, which means that there is no implicit fall through from one case label to another. + + If `switchValue` does not match any of the cases, the default case represented by `defaultBody` is run. + + + +## Examples + The following example demonstrates how to create an expression that represents a switch statement that has a default case. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet35"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet35"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet35"::: + ]]> @@ -21806,21 +21738,21 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a object to be used in a object. The created . - objects in a object must have the same type, unless the has the type `void`. - - Each object has an implicit `break` statement, which means that there is no implicit fall through from one case label to another. - - - -## Examples - The following example demonstrates how to create an expression that represents a switch statement that has a default case. - + objects in a object must have the same type, unless the has the type `void`. + + Each object has an implicit `break` statement, which means that there is no implicit fall through from one case label to another. + + + +## Examples + The following example demonstrates how to create an expression that represents a switch statement that has a default case. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet35"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet35"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet35"::: + ]]> @@ -22140,14 +22072,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a throwing of an exception. A that represents the exception. - object that uses the method. - + object that uses the method. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet47"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet47"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet47"::: + ]]> @@ -22310,14 +22242,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a representing a try block with any number of catch statements and neither a fault nor finally block. The created . - object that contains a catch statement. - + object that contains a catch statement. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet47"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet47"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet47"::: + ]]> @@ -22393,14 +22325,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a representing a try block with any number of catch statements and a finally block. The created . - object that contains a catch statement and a finally statement. - + object that contains a catch statement and a finally statement. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet48"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet48"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet48"::: + ]]> @@ -22685,14 +22617,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Gets the static type of the expression that this represents. The that represents the static type of the expression. - is the type of the expression tree node, whereas the represents the static common language runtime (CLR) type of the expression that the node represents. For example, two nodes with different node types can have the same , as shown in the following code example. - + is the type of the expression tree node, whereas the represents the static common language runtime (CLR) type of the expression that the node represents. For example, two nodes with different node types can have the same , as shown in the following code example. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet36"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet36"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet36"::: + ]]> @@ -22742,19 +22674,19 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents an explicit reference or boxing conversion where is supplied if the conversion fails. A that has the property equal to and the and properties set to the specified values. - property of the resulting is `null`. The and properties are both `false`. - - - -## Examples - The following example demonstrates how to use the method to create a that represents the reference conversion of a non-nullable integer expression to the nullable integer type. - + property of the resulting is `null`. The and properties are both `false`. + + + +## Examples + The following example demonstrates how to use the method to create a that represents the reference conversion of a non-nullable integer expression to the nullable integer type. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet11"::: + ]]> @@ -22852,19 +22784,19 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a . A for which the property is equal to and for which the and properties are set to the specified values. - property of the resulting represents . - - - -## Examples - The following example demonstrates how to use the method to create a that represents a type test of a string value against the type. - + property of the resulting represents . + + + +## Examples + The following example demonstrates how to use the method to create a that represents a type test of a string value against the type. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet12"::: + ]]> @@ -22932,31 +22864,31 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a unary plus operation. A that has the property equal to and the property set to the specified value. - property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `expression`.Type is a user-defined type that defines the unary plus operator, the that represents that operator is the implementing method. - -- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. - + property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `expression`.Type is a user-defined type that defines the unary plus operator, the that represents that operator is the implementing method. + +- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. + ]]> @@ -23017,33 +22949,33 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Creates a that represents a unary plus operation. A that has the property equal to and the and properties set to the specified values. - property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. - -#### Implementing Method - The following rules determine the implementing method for the operation: - -- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes one argument, it is the implementing method for the node. - -- If `expression`.Type is a user-defined type that defines the unary plus operator, the that represents that operator is the implementing method. - -- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. - -#### Node Type and Lifted versus Non-Lifted - If the implementing method is not `null`: - -- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. - -- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: - - - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. - - - The return type of the implementing method is a non-nullable value type. - - If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. - + property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + +#### Implementing Method + The following rules determine the implementing method for the operation: + +- If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes one argument, it is the implementing method for the node. + +- If `expression`.Type is a user-defined type that defines the unary plus operator, the that represents that operator is the implementing method. + +- Otherwise, if `expression`.Type is a numeric type, the implementing method is `null`. + +#### Node Type and Lifted versus Non-Lifted + If the implementing method is not `null`: + +- If `expression`.Type is assignable to the argument type of the implementing method, the node is not lifted. The type of the node is the return type of the implementing method. + +- If the following two conditions are satisfied, the node is lifted and the type of the node is the nullable type that corresponds to the return type of the implementing method: + + - `expression`.Type is a nullable value type and the corresponding non-nullable value type is equal to the argument type of the implementing method. + + - The return type of the implementing method is a non-nullable value type. + + If the implementing method is `null`, the type of the node is `expression`.Type. If `expression`.Type is non-nullable, the node is not lifted. Otherwise, the node is lifted. + ]]> @@ -23051,10 +22983,10 @@ As with `Func`, the last argument is the return type. It can be set to `System.V is not and the method it represents returns , is not ( in Visual Basic), or does not take exactly one argument. - is and the unary plus operator is not defined for .Type. - - -or- - + is and the unary plus operator is not defined for .Type. + + -or- + .Type (or its corresponding non-nullable type if it is a nullable value type) is not assignable to the argument type of the method represented by . @@ -23262,11 +23194,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V Reduces the node and then calls the visitor delegate on the reduced expression. The method throws an exception if the node is not reducible. The expression being visited, or an expression which should replace it in the tree. - diff --git a/xml/System.Net/FtpWebRequest.xml b/xml/System.Net/FtpWebRequest.xml index a162e5d8c32..9a94e015a64 100644 --- a/xml/System.Net/FtpWebRequest.xml +++ b/xml/System.Net/FtpWebRequest.xml @@ -49,60 +49,60 @@ Implements a File Transfer Protocol (FTP) client. - [!IMPORTANT] > We don't recommend that you use the `FtpWebRequest` class for new development. For more information and alternatives to `FtpWebRequest`, see [WebRequest shouldn't be used](https://github.com/dotnet/platform-compat/blob/master/docs/DE0003.md) on GitHub. - To obtain an instance of , use the method. You can also use the class to upload and download information from an FTP server. Using either of these approaches, when you specify a network resource that uses the FTP scheme (for example, `"ftp://contoso.com"`) the class provides the ability to programmatically interact with FTP servers. - - The URI may be relative or absolute. If the URI is of the form `"ftp://contoso.com/%2fpath"` (%2f is an escaped '/'), then the URI is absolute, and the current directory is `/path`. If, however, the URI is of the form `"ftp://contoso.com/path"`, first the .NET Framework logs into the FTP server (using the user name and password set by the property), then the current directory is set to `/path`. - - You must have a valid user name and password for the server or the server must allow anonymous logon. You can specify the credentials used to connect to the server by setting the property or you can include them in the portion of the URI passed to the method. If you include information in the URI, the property is set to a new network credential with the specified user name and password information. - + To obtain an instance of , use the method. You can also use the class to upload and download information from an FTP server. Using either of these approaches, when you specify a network resource that uses the FTP scheme (for example, `"ftp://contoso.com"`) the class provides the ability to programmatically interact with FTP servers. + + The URI may be relative or absolute. If the URI is of the form `"ftp://contoso.com/%2fpath"` (%2f is an escaped '/'), then the URI is absolute, and the current directory is `/path`. If, however, the URI is of the form `"ftp://contoso.com/path"`, first the .NET Framework logs into the FTP server (using the user name and password set by the property), then the current directory is set to `/path`. + + You must have a valid user name and password for the server or the server must allow anonymous logon. You can specify the credentials used to connect to the server by setting the property or you can include them in the portion of the URI passed to the method. If you include information in the URI, the property is set to a new network credential with the specified user name and password information. + > [!CAUTION] -> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports Secure Sockets Layer (SSL), you should set to `true`. - - You must have to access the FTP resource; otherwise, a exception is thrown. - - Specify the FTP command to send to the server by setting the property to a value defined in the structure. To transmit text data, change the property from its default value (`true`) to `false`. For details and restrictions, see . - - When using an object to upload a file to a server, you must write the file content to the request stream obtained by calling the method or its asynchronous counterparts, the and methods. You must write to the stream and close the stream before sending the request. - - Requests are sent to the server by calling the method or its asynchronous counterparts, the and methods. When the requested operation completes, an object is returned. The object provides the status of the operation and any data downloaded from the server. - - You can set a time-out value for reading or writing to the server by using the property. If the time-out period is exceeded, the calling method throws a with set to . - - When downloading a file from an FTP server, if the command was successful, the contents of the requested file are available in the response object's stream. You can access this stream by calling the method. For more information, see . - - If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. If the specified proxy is an HTTP proxy, only the , , and commands are supported. - - Only downloaded binary content is cached; that is, content received using the command with the property set to `true`. - - Multiple s reuse existing connections, if possible. - - For more information about the FTP protocol, see [RFC 959: File Transfer Protocol](https://www.ietf.org/rfc/rfc959.txt). - - - -## Examples - The following code example demonstrates deleting a file from an FTP server. - +> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports Secure Sockets Layer (SSL), you should set to `true`. + + You must have to access the FTP resource; otherwise, a exception is thrown. + + Specify the FTP command to send to the server by setting the property to a value defined in the structure. To transmit text data, change the property from its default value (`true`) to `false`. For details and restrictions, see . + + When using an object to upload a file to a server, you must write the file content to the request stream obtained by calling the method or its asynchronous counterparts, the and methods. You must write to the stream and close the stream before sending the request. + + Requests are sent to the server by calling the method or its asynchronous counterparts, the and methods. When the requested operation completes, an object is returned. The object provides the status of the operation and any data downloaded from the server. + + You can set a time-out value for reading or writing to the server by using the property. If the time-out period is exceeded, the calling method throws a with set to . + + When downloading a file from an FTP server, if the command was successful, the contents of the requested file are available in the response object's stream. You can access this stream by calling the method. For more information, see . + + If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. If the specified proxy is an HTTP proxy, only the , , and commands are supported. + + Only downloaded binary content is cached; that is, content received using the command with the property set to `true`. + + Multiple s reuse existing connections, if possible. + + For more information about the FTP protocol, see [RFC 959: File Transfer Protocol](https://www.ietf.org/rfc/rfc959.txt). + + + +## Examples + The following code example demonstrates deleting a file from an FTP server. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet4"::: - - The following code example demonstrates downloading a file from an FTP server by using the class. - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet4"::: + + The following code example demonstrates downloading a file from an FTP server by using the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet5"::: - - The following code example demonstrates using asynchronous operations to upload a file to an FTP server. - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet5"::: + + The following code example demonstrates using asynchronous operations to upload a file to an FTP server. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpAsync/CPP/async.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpWebRequest/Overview/async.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpWebRequest/Overview/async.cs" id="Snippet1"::: + ]]> @@ -149,22 +149,22 @@ Terminates an asynchronous FTP operation. - [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following code example demonstrates how the user can terminate an asynchronous upload of a file from the local directory to the server. - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + + + +## Examples + The following code example demonstrates how the user can terminate an asynchronous upload of a file from the local directory to the server. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet10"::: + ]]> @@ -218,26 +218,26 @@ Begins asynchronously opening a request's content stream for writing. An instance that indicates the status of the operation. - method. Typically, is called by the method referenced by `callback`. To determine the state of the operation, check the properties in the object returned by this method. - - This method does not block while waiting for the stream. To block, call in place of this method. - - For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - + method. Typically, is called by the method referenced by `callback`. To determine the state of the operation, check the properties in the object returned by this method. + + This method does not block while waiting for the stream. To block, call in place of this method. + + For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following code example demonstrates beginning an asynchronous operation to get a request's stream. This code example is part of a larger example provided for the class overview. - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + + + +## Examples + The following code example demonstrates beginning an asynchronous operation to get a request's stream. This code example is part of a larger example provided for the class overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpAsync/CPP/async.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpWebRequest/Overview/async.cs" id="Snippet4"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpWebRequest/Overview/async.cs" id="Snippet4"::: + ]]> A previous call to this method or has not yet completed. @@ -297,30 +297,30 @@ Begins sending a request and receiving a response from an FTP server asynchronously. An instance that indicates the status of the operation. - method. Typically, is called by the method referenced by `callback`. To determine the state of the operation, check the properties in the object returned by the method. - - If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. - - does not block while waiting for the response from the server. To block, call the method in place of . - - For more information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - + method. Typically, is called by the method referenced by `callback`. To determine the state of the operation, check the properties in the object returned by the method. + + If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. + + does not block while waiting for the response from the server. To block, call the method in place of . + + For more information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + + This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + > [!NOTE] -> If a is thrown, use the and properties of the exception to determine the response from the server. - - - -## Examples - The following code example demonstrates ending an asynchronous operation to get a request's stream, and then starting a request to get the response. This code example is part of a larger example provided for the class overview. - +> If a is thrown, use the and properties of the exception to determine the response from the server. + + + +## Examples + The following code example demonstrates ending an asynchronous operation to get a request's stream, and then starting a request to get the response. This code example is part of a larger example provided for the class overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpAsync/CPP/async.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpWebRequest/Overview/async.cs" id="Snippet5"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpWebRequest/Overview/async.cs" id="Snippet5"::: + ]]> @@ -386,14 +386,14 @@ Gets or sets the certificates used for establishing an encrypted connection to the FTP server. An object that contains the client certificates. - . - + . + > [!NOTE] -> The .NET Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the .NET Framework uses the first element of (if there is one), or tries to reuse an anonymous session if is empty. - +> The .NET Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the .NET Framework uses the first element of (if there is one), or tries to reuse an anonymous session if is empty. + ]]> The value specified for a set operation is . @@ -448,23 +448,23 @@ Gets or sets the name of the connection group that contains the service point used to send the current request. A value that contains a connection group name. - property after calling the , , , or method causes an exception. - - - -## Examples - The following code example retrieves the value of this property. - + property after calling the , , , or method causes an exception. + + + +## Examples + The following code example retrieves the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet16"::: + ]]> A new value was specified for this property for a request that is already in progress. @@ -523,11 +523,11 @@ Gets or sets a value that is ignored by the class. An value that should be ignored. - property is provided only for compatibility with other implementations of the and classes. There is no reason to use . - + property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + ]]> @@ -574,23 +574,23 @@ Gets or sets a byte offset into the file being downloaded by this request. An instance that specifies the file offset, in bytes. The default value is zero. - property when downloading a file from an FTP server. This offset indicates the position in the server's file that marks the start of the data to be downloaded. The offset is specified as the number of bytes from the start of the file; the offset of the first byte is zero. - - Setting causes the to send a restart (`REST`) command to the server. This command is ignored by most FTP server implementations if you are uploading data to the server. - - Changing after calling the , , , or method causes an exception. - - - -## Examples - The following code example demonstrates downloading part of a file from a server and appending the downloaded data to a local file. - + property when downloading a file from an FTP server. This offset indicates the position in the server's file that marks the start of the data to be downloaded. The offset is specified as the number of bytes from the start of the file; the offset of the first byte is zero. + + Setting causes the to send a restart (`REST`) command to the server. This command is ignored by most FTP server implementations if you are uploading data to the server. + + Changing after calling the , , , or method causes an exception. + + + +## Examples + The following code example demonstrates downloading part of a file from a server and appending the downloaded data to a local file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet7"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet7"::: + ]]> A new value was specified for this property for a request that is already in progress. @@ -640,11 +640,11 @@ Always throws a . Always throws a . - property is provided only for compatibility with other implementations of the and classes. There is no reason to use . - + property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + ]]> Content type information is not supported for FTP. @@ -693,24 +693,24 @@ Gets or sets the credentials used to communicate with the FTP server. An instance; otherwise, if the property has not been set. - property by using a credential of type ; this ensures that the user name and password can be read and sent to the server. - + property by using a credential of type ; this ensures that the user name and password can be read and sent to the server. + > [!CAUTION] -> Credentials information is not encrypted when transmitted to the server unless the property is set to `true`. - - Changing after calling the , , , or method causes an exception. - - - -## Examples - The following code example retrieves the value of this property and uses it to display the user name. - +> Credentials information is not encrypted when transmitted to the server unless the property is set to `true`. + + Changing after calling the , , , or method causes an exception. + + + +## Examples + The following code example retrieves the value of this property and uses it to display the user name. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet14"::: + ]]> The value specified for a set operation is . @@ -760,26 +760,26 @@ Defines the default cache policy for all FTP requests. A that defines the cache policy for FTP requests. - command is cached. - - The following table describes the effects of FTP caching policies on . - -|Policy|Effect| -|------------|------------| -||Returns the cached resource if the resource is fresh, the content length is accurate, and the expiration, modification, and content length attributes are present.| -||Returns the resource from the server.| -||Returns the cached resource if the content length is present and matches the entry size; otherwise, throws a .| -||Returns the cached resource if the content length is provided and matches the entry size; otherwise, the resource is downloaded from the server and is returned to the caller.| -||Returns the cached resource if the timestamp of the cached resource is the same as the time stamp of the resource on the server; otherwise, the resource is downloaded from the server, stored in the cache, and returned to the caller.| -||Downloads the resource from the server, stores it in the cache, and returns the resource to the caller.| -||If a cached resource exists, it is deleted. The resource is downloaded from the server and is returned to the caller.| - + command is cached. + + The following table describes the effects of FTP caching policies on . + +|Policy|Effect| +|------------|------------| +||Returns the cached resource if the resource is fresh, the content length is accurate, and the expiration, modification, and content length attributes are present.| +||Returns the resource from the server.| +||Returns the cached resource if the content length is present and matches the entry size; otherwise, throws a .| +||Returns the cached resource if the content length is provided and matches the entry size; otherwise, the resource is downloaded from the server and is returned to the caller.| +||Returns the cached resource if the timestamp of the cached resource is the same as the time stamp of the resource on the server; otherwise, the resource is downloaded from the server, stored in the cache, and returned to the caller.| +||Downloads the resource from the server, stores it in the cache, and returns the resource to the caller.| +||If a cached resource exists, it is deleted. The resource is downloaded from the server and is returned to the caller.| + > [!NOTE] -> Setting overrides any configuration setting. - +> Setting overrides any configuration setting. + ]]> The caller tried to set this property to . @@ -829,23 +829,23 @@ if control and data transmissions are encrypted; otherwise, . The default value is . - [!CAUTION] -> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports SSL, you should set to `true`. - - The `"AUTH TLS"` command is sent to the server to request an encrypted session. If the server does not recognize this command, you receive a exception. - - - -## Examples - The following code example uses an encrypted connection to download the directory listing from an FTP server. - +> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports SSL, you should set to `true`. + + The `"AUTH TLS"` command is sent to the server to request an encrypted session. If the server does not recognize this command, you receive a exception. + + + +## Examples + The following code example uses an encrypted connection to download the directory listing from an FTP server. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet8"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet8"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet8"::: + ]]> The connection to the FTP server has already been established. @@ -903,24 +903,24 @@ Ends a pending asynchronous operation started with . A writable instance associated with this instance. - method blocks until the operation completes. To determine whether the operation has completed, check the property before calling . - - In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while opening the stream for writing. - + method blocks until the operation completes. To determine whether the operation has completed, check the property before calling . + + In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while opening the stream for writing. + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following code example demonstrates ending an asynchronous operation to get a request's stream. This code example is part of a larger example provided for the class overview. - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + + + +## Examples + The following code example demonstrates ending an asynchronous operation to get a request's stream. This code example is part of a larger example provided for the class overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpAsync/CPP/async.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpWebRequest/Overview/async.cs" id="Snippet5"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpWebRequest/Overview/async.cs" id="Snippet5"::: + ]]> @@ -982,24 +982,24 @@ Ends a pending asynchronous operation started with . A reference that contains an instance. This object contains the FTP server's response to the request. - method is called, blocks until the operation completes. To prevent blocking, check the property before calling . - - In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while communicating with the server. - + method is called, blocks until the operation completes. To prevent blocking, check the property before calling . + + In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while communicating with the server. + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following code example demonstrates ending an asynchronous operation to get a response. This code example is part of a larger example provided for the class overview. - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + + + +## Examples + The following code example demonstrates ending an asynchronous operation to get a response. This code example is part of a larger example provided for the class overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpAsync/CPP/async.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpWebRequest/Overview/async.cs" id="Snippet6"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpWebRequest/Overview/async.cs" id="Snippet6"::: + ]]> @@ -1063,33 +1063,33 @@ Retrieves the stream used to upload data to an FTP server. A writable instance used to store data to be sent to the server by the current request. - method. After writing the data to the stream, you must close the stream prior to sending the request. - - If you have not set the property to or , you cannot get the stream. - - blocks while waiting for the stream. To prevent this, call the method in place of . - + method. After writing the data to the stream, you must close the stream prior to sending the request. + + If you have not set the property to or , you cannot get the stream. + + blocks while waiting for the stream. To prevent this, call the method in place of . + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following code example demonstrates copying a file to a request's data stream and sending a request to the server to upload the data and append it to a file. - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + + + +## Examples + The following code example demonstrates copying a file to a request's data stream and sending a request to the server to upload the data and append it to a file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet3"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet3"::: + ]]> - has been called and has not completed. - + has been called and has not completed. + -or- - + An HTTP proxy is enabled, and you attempted to use an FTP command other than , , or . A connection to the FTP server could not be established. The property is not set to or . @@ -1147,43 +1147,43 @@ Returns the FTP server response. A reference that contains an instance. This object contains the FTP server's response to the request. - object returned by this method to . - - causes a control connection to be established, and might also create a data connection. blocks until the response is received. To prevent this, you can perform this operation asynchronously by calling the and methods in place of . - - If the property is set, either directly or in a configuration file, communications with the FTP server are made through the proxy. - - If a is thrown, use the and properties of the exception to determine the response from the server. - - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - + object returned by this method to . + + causes a control connection to be established, and might also create a data connection. blocks until the response is received. To prevent this, you can perform this operation asynchronously by calling the and methods in place of . + + If the property is set, either directly or in a configuration file, communications with the FTP server are made through the proxy. + + If a is thrown, use the and properties of the exception to determine the response from the server. + + This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + > [!NOTE] -> Multiple calls to return the same response object; the request is not reissued. - - - -## Examples - The following code example demonstrates copying a file to a request's data stream and sending a request to append data to a file to the server. The example calls to send the request and block until the response is returned by the server. - +> Multiple calls to return the same response object; the request is not reissued. + + + +## Examples + The following code example demonstrates copying a file to a request's data stream and sending a request to append data to a file to the server. The example calls to send the request and block until the response is returned by the server. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet3"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet3"::: + ]]> - or has already been called for this instance. - + or has already been called for this instance. + -or- - + An HTTP proxy is enabled, and you attempted to use an FTP command other than , , or . - is set to , but the server does not support this feature. - + is set to , but the server does not support this feature. + -or- - + A was specified and the timeout has expired. This method generates network traffic. @@ -1246,11 +1246,11 @@ Gets an empty object. An empty object. - property is provided only for compatibility with other implementations of the and classes. There is no reason to use . - + property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + ]]> @@ -1298,21 +1298,21 @@ if the connection to the server should not be destroyed; otherwise, . The default value is . - property is set to `false`, the control connection is closed when you call the method. - - Changing after calling the , , , or method causes an exception. - - - -## Examples - The following code example retrieves and displays property values for a specified object. - + property is set to `false`, the control connection is closed when you call the method. + + Changing after calling the , , , or method causes an exception. + + + +## Examples + The following code example retrieves and displays property values for a specified object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet15"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet15"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet15"::: + ]]> A new value was specified for this property for a request that is already in progress. @@ -1374,36 +1374,36 @@ Gets or sets the command to send to the FTP server. A value that contains the FTP command to send to the server. The default value is . - property determines which command is sent to the server. You set the by using the strings defined in the public field members of the class. Note that the strings defined in the class are the only supported options for the property. Setting the property to any other value will result in an exception. - - When setting to , you must do so before calling the method. Failure to call these members in the correct order causes a exception when you attempt to get the request stream. - - The credentials supplied for the object must have permission to perform the specified method. If not, the FTP command fails. - - To determine the success or failure of a command, check the and properties. - - - -## Examples - The following code example sets this property to . - + property determines which command is sent to the server. You set the by using the strings defined in the public field members of the class. Note that the strings defined in the class are the only supported options for the property. Setting the property to any other value will result in an exception. + + When setting to , you must do so before calling the method. Failure to call these members in the correct order causes a exception when you attempt to get the request stream. + + The credentials supplied for the object must have permission to perform the specified method. If not, the FTP command fails. + + To determine the success or failure of a command, check the and properties. + + + +## Examples + The following code example sets this property to . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet4"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet4"::: + ]]> A new value was specified for this property for a request that is already in progress. - The method is invalid. - + The method is invalid. + -or- - - The method is not supported. - + + The method is not supported. + -or- - + Multiple methods were specified. @@ -1449,11 +1449,11 @@ Always throws a . Always throws a . - property is provided only for compatibility with other implementations of the and classes. - + property is provided only for compatibility with other implementations of the and classes. + ]]> Preauthentication is not supported for FTP. @@ -1496,33 +1496,21 @@ Gets or sets the proxy used to communicate with the FTP server. An instance responsible for communicating with the FTP server. On .NET Core, its value is . - property identifies the instance that communicates with the FTP server. The proxy is set by the system by using configuration files and the Internet Explorer Local Area Network settings. To specify that no proxy should be used, set to the proxy instance returned by the method. For more information about automatic proxy detection, see [Automatic Proxy Detection](/dotnet/framework/network-programming/automatic-proxy-detection). - - You must set before writing data to the request's stream or getting the response. Changing after calling the , , , or method causes an exception. - - The class supports HTTP and ISA Firewall Client proxies. - - If the specified proxy is an HTTP proxy, only the , , and commands are supported. - -### On .NET Core - -The `FtpWebRequest.Proxy` property is not supported. Setting the property has no effect. Getting the property value returns `null`. + [!NOTE] +> This property is not supported on .NET Core, and setting it has no effect. Getting the property value returns `null`. +For more information about this API, see [Supplemental API remarks for System.Net.FtpWebRequest.Proxy](/dotnet/fundamentals/runtime-libraries/system-net-ftpwebrequest-proxy). + ]]> + + + - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet16"::: +:::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet16"::: + ]]> + This property cannot be set to . A new value was specified for this property for a request that is already in progress. @@ -1577,15 +1565,15 @@ The `FtpWebRequest.Proxy` property is not supported. Setting the property has no Gets or sets a time-out when reading from or writing to a stream. The number of milliseconds before the reading or writing times out. The default value is 300,000 milliseconds (5 minutes). - is used when writing to the stream returned by the method or reading from the stream returned by the method. - - Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. If the time-out period is exceeded, the calling method throws a with set to . - - To specify the amount of time to wait for the request to complete, use the property. - + is used when writing to the stream returned by the method or reading from the stream returned by the method. + + Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. If the time-out period is exceeded, the calling method throws a with set to . + + To specify the amount of time to wait for the request to complete, use the property. + ]]> The request has already been sent. @@ -1689,19 +1677,19 @@ The `FtpWebRequest.Proxy` property is not supported. Setting the property has no Gets the URI requested by this instance. A instance that identifies a resource that is accessed using the File Transfer Protocol. - property is the URI specified when the method was called to obtain this instance. - - - -## Examples - The following code example displays this property value. - + property is the URI specified when the method was called to obtain this instance. + + + +## Examples + The following code example displays this property value. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet14"::: + ]]> @@ -1758,19 +1746,19 @@ The `FtpWebRequest.Proxy` property is not supported. Setting the property has no Gets the object used to connect to the FTP server. A object that can be used to customize connection behavior. - object exists, one is created for the FTP server. To set the maximum number of connections that can be open for an FTP server, set the property of the instance returned by this property. - - - -## Examples - The following code example retrieves the service point from a request and sets the maximum number of connections to one. - + object exists, one is created for the FTP server. To set the maximum number of connections that can be open for an FTP server, set the property of the instance returned by this property. + + + +## Examples + The following code example retrieves the service point from a request and sets the maximum number of connections to one. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet1"::: + ]]> @@ -1823,25 +1811,25 @@ The `FtpWebRequest.Proxy` property is not supported. Setting the property has no Gets or sets the number of milliseconds to wait for a request. An value that contains the number of milliseconds to wait before a request times out. The default value is . - property to (-1). This is the default value. - - is the number of milliseconds that a synchronous request made with the method waits for a response and that the method waits for a stream. If a resource does not respond within the time-out period, the request throws a with the property set to . - - Changing after calling the , , , or method causes an exception. - - A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a time-out on your request. - - - -## Examples - The following code example sets this property. - + property to (-1). This is the default value. + + is the number of milliseconds that a synchronous request made with the method waits for a response and that the method waits for a stream. If a resource does not respond within the time-out period, the request throws a with the property set to . + + Changing after calling the , , , or method causes an exception. + + A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a time-out on your request. + + + +## Examples + The following code example sets this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet23"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet23"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet23"::: + ]]> The value specified is less than zero and is not . @@ -1897,21 +1885,21 @@ The `FtpWebRequest.Proxy` property is not supported. Setting the property has no to indicate to the server that the data to be transferred is binary; to indicate that the data is text. The default value is . - to send a `"TYPE I"` command to the server. Specifying `false` causes the to send a `"Type A"` command to the server. FTP servers can ignore these commands. - - Changing after calling the , , , or method causes an exception. - - - -## Examples - The following code example retrieves and displays property values for a specified object. - + to send a `"TYPE I"` command to the server. Specifying `false` causes the to send a `"Type A"` command to the server. FTP servers can ignore these commands. + + Changing after calling the , , , or method causes an exception. + + + +## Examples + The following code example retrieves and displays property values for a specified object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet15"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet15"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet15"::: + ]]> A new value was specified for this property for a request that is already in progress. @@ -1959,11 +1947,11 @@ The `FtpWebRequest.Proxy` property is not supported. Setting the property has no Always throws a . Always throws a . - property is provided only for compatibility with other implementations of the and classes. There is no reason to use . - + property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + ]]> Default credentials are not supported for FTP. @@ -2012,25 +2000,25 @@ The `FtpWebRequest.Proxy` property is not supported. Setting the property has no if the client application's data transfer process listens for a connection on the data port; otherwise, if the client should initiate a connection on the data port. The default value is . - property to `true` sends the "`PASV"` command to the server. This command requests the server to listen on a data port and to wait for a connection rather than initiate one upon receipt of a transfer command. - - For a description of the behaviors that are specified using , see [RFC 959: "File Transfer Protocol", Section 3.2: "Establishing Data Connections" and Section 4.1.2: "Transfer Parameter Commands"](https://www.ietf.org/rfc/rfc959.txt). - - Changing after calling the , , , or method causes an exception. - - If is set to `true`, the FTP server may not send the size of the file, and download progress can always be zero. If is set to `false`, a firewall can raise an alert and block the file download. - - - -## Examples - The following code example retrieves and displays property values for a specified object. - + property to `true` sends the "`PASV"` command to the server. This command requests the server to listen on a data port and to wait for a connection rather than initiate one upon receipt of a transfer command. + + For a description of the behaviors that are specified using , see [RFC 959: "File Transfer Protocol", Section 3.2: "Establishing Data Connections" and Section 4.1.2: "Transfer Parameter Commands"](https://www.ietf.org/rfc/rfc959.txt). + + Changing after calling the , , , or method causes an exception. + + If is set to `true`, the FTP server may not send the size of the file, and download progress can always be zero. If is set to `false`, a firewall can raise an alert and block the file download. + + + +## Examples + The following code example retrieves and displays property values for a specified object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLFtpClient/CPP/ftptests.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet6"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet6"::: + ]]> A new value was specified for this property for a request that is already in progress. diff --git a/xml/System.Reflection.Emit/EnumBuilder.xml b/xml/System.Reflection.Emit/EnumBuilder.xml index 112ddced72b..ba038efcd5f 100644 --- a/xml/System.Reflection.Emit/EnumBuilder.xml +++ b/xml/System.Reflection.Emit/EnumBuilder.xml @@ -86,25 +86,25 @@ Describes and represents an enumeration type. - [!NOTE] -> In the .NET Framework versions 1.0 and 1.1, it is necessary to define enumerations using because emits enumerations whose elements are of type instead of the enumeration type. In the .NET Framework version 2.0, emits enumerations whose elements have the correct type. - - - -## Examples - The following code example demonstrates the construction of an enumeration within a dynamic assembly, using `EnumBuilder`. The example defines an enumeration named `Elevation`, with an underlying type of , and creates two elements: `Low`, with a value of 0, and `High`, with a value of 1. After the type has been created, the assembly is saved with the name `TempAssembly.dll`. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the contents of this assembly. - +> In the .NET Framework versions 1.0 and 1.1, it is necessary to define enumerations using because emits enumerations whose elements are of type instead of the enumeration type. In the .NET Framework version 2.0, emits enumerations whose elements have the correct type. + + + +## Examples + The following code example demonstrates the construction of an enumeration within a dynamic assembly, using `EnumBuilder`. The example defines an enumeration named `Elevation`, with an underlying type of , and creates two elements: `Low`, with a value of 0, and `High`, with a value of 1. After the type has been created, the assembly is saved with the name `TempAssembly.dll`. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the contents of this assembly. + > [!NOTE] -> Prior to the .NET Framework version 2.0, this code example does not produce a correct enumeration. - +> Prior to the .NET Framework version 2.0, this code example does not produce a correct enumeration. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_DefineEnum/CPP/modulebuilder_defineenum.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/EnumBuilder/Overview/modulebuilder_defineenum.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineEnum/VB/modulebuilder_defineenum.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineEnum/VB/modulebuilder_defineenum.vb" id="Snippet1"::: + ]]> @@ -170,15 +170,15 @@ Retrieves the dynamic assembly that contains this enum definition. Read-only. The dynamic assembly that contains this enum definition. - @@ -231,29 +231,23 @@ Returns the full path of this enum qualified by the display name of the parent assembly. Read-only. The full path of this enum qualified by the display name of the parent assembly. - , \ - - See for a description of the format of the display name of an assembly. - -## Version Information - In the .NET Framework version 1.1 and earlier, the return value of this property did not include the culture or public key. - - - -## Examples - The following code sample demonstrates the use of the `AssemblyQualifiedName` property to reference the qualified parent assembly name of the current `EnumBuilder`. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EnumBuilder_Properties_5/CPP/enumbuilder_properties_5.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/EnumBuilder/Assembly/enumbuilder_properties_5.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_Properties_5/VB/enumbuilder_properties_5.vb" id="Snippet2"::: - - ]]> + , \ + +See for a description of the format of the display name of an assembly. + ]]> + + + @@ -401,10 +395,10 @@ Creates a object for this enum. A object for this enum. To be added. - This type has been previously created. - - -or- - + This type has been previously created. + + -or- + The enclosing type has not been created. @@ -606,26 +600,26 @@ Defines the named static field in an enumeration type with the specified constant value. The defined field. - , , and set. - + , , and set. + > [!NOTE] -> In the .NET Framework versions 1.0 and 1.1, it is necessary to define enumerations using because emits enumerations whose elements are of type instead of the enumeration type. In the .NET Framework version 2.0, emits enumerations whose elements have the correct type. - - - -## Examples - The following code example demonstrates the construction of an enumeration within a dynamic assembly, using `EnumBuilder`. The example defines an enumeration named `Elevation`, with an underlying type of , and creates two elements: `Low`, with a value of 0, and `High`, with a value of 1. After the type has been created, the assembly is saved with the name `TempAssembly.dll`. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the contents of this assembly. - +> In the .NET Framework versions 1.0 and 1.1, it is necessary to define enumerations using because emits enumerations whose elements are of type instead of the enumeration type. In the .NET Framework version 2.0, emits enumerations whose elements have the correct type. + + + +## Examples + The following code example demonstrates the construction of an enumeration within a dynamic assembly, using `EnumBuilder`. The example defines an enumeration named `Elevation`, with an underlying type of , and creates two elements: `Low`, with a value of 0, and `High`, with a value of 1. After the type has been created, the assembly is saved with the name `TempAssembly.dll`. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the contents of this assembly. + > [!NOTE] -> Prior to the .NET Framework version 2.0, this code example does not produce a correct enumeration. - +> Prior to the .NET Framework version 2.0, this code example does not produce a correct enumeration. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_DefineEnum/CPP/modulebuilder_defineenum.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/EnumBuilder/Overview/modulebuilder_defineenum.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineEnum/VB/modulebuilder_defineenum.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineEnum/VB/modulebuilder_defineenum.vb" id="Snippet1"::: + ]]> @@ -715,11 +709,11 @@ Returns the full path of this enum. Read-only. The full path of this enum. - @@ -992,11 +986,11 @@ Returns an array of objects representing the public and non-public constructors defined for this class, as specified. Returns an array of objects representing the specified constructors defined for this class. If no constructors are defined, an empty array is returned. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -1052,17 +1046,17 @@ Returns all the custom attributes defined for this constructor. Returns an array of objects representing all the custom attributes of the constructor represented by this instance. - and call on the returned . - - The following code sample illustrates the use of `GetCustomAttribute` in the context of . - + and call on the returned . + + The following code sample illustrates the use of `GetCustomAttribute` in the context of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute2/CPP/enumbuilder_setcustomattribute2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/EnumBuilder/GetCustomAttributes/enumbuilder_setcustomattribute2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute2/VB/enumbuilder_setcustomattribute2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute2/VB/enumbuilder_setcustomattribute2.vb" id="Snippet1"::: + ]]> This method is not currently supported in types that are not complete. @@ -1110,17 +1104,17 @@ Returns the custom attributes identified by the given type. Returns an array of objects representing the attributes of this constructor that are of . - and call on the returned . - - The following code sample illustrates the use of `GetCustomAttribute` in the context of . - + and call on the returned . + + The following code sample illustrates the use of `GetCustomAttribute` in the context of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute1/CPP/enumbuilder_setcustomattribute1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/EnumBuilder/GetCustomAttributes/enumbuilder_setcustomattribute1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute1/VB/enumbuilder_setcustomattribute1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute1/VB/enumbuilder_setcustomattribute1.vb" id="Snippet2"::: + ]]> This method is not currently supported in types that are not complete. @@ -1260,11 +1254,11 @@ Returns the event with the specified name. Returns an object representing the event declared or inherited by this type with the specified name. If there are no matches, is returned. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -1323,11 +1317,11 @@ Returns the events for the public events declared or inherited by this type. Returns an array of objects representing the public events declared or inherited by this type. An empty array is returned if there are no public events. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -1379,11 +1373,11 @@ Returns the public and non-public events that are declared by this type. Returns an array of objects representing the public and non-public events declared or inherited by this type. An empty array is returned if there are no events, as specified. - or and use reflection on the retrieved type to retrieve the events. - + or and use reflection on the retrieved type to retrieve the events. + ]]> This method is not currently supported in types that are not complete. @@ -1438,11 +1432,11 @@ Returns the field specified by the given name. Returns the object representing the field declared or inherited by this type with the specified name and public or non-public modifier. If there are no matches, then null is returned. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -1494,13 +1488,13 @@ Returns the public and non-public fields that are declared by this type. Returns an array of objects representing the public and non-public fields declared or inherited by this type. An empty array is returned if there are no fields, as specified. - or and use reflection on the retrieved type. - - The method does not return fields in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which fields are returned, because that order can vary. - + or and use reflection on the retrieved type. + + The method does not return fields in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which fields are returned, because that order can vary. + ]]> This method is not currently supported in types that are not complete. @@ -1611,11 +1605,11 @@ Returns the interface implemented (directly or indirectly) by this type, with the specified fully-qualified name. Returns a object representing the implemented interface. Returns null if no interface matching name is found. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -1674,11 +1668,11 @@ Returns an interface mapping for the interface requested. The requested interface mapping. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> The type does not implement the interface. @@ -1727,11 +1721,11 @@ Returns an array of all the interfaces implemented on this a class and its base classes. Returns an array of objects representing the implemented interfaces. If none are defined, an empty array is returned. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> @@ -1790,11 +1784,11 @@ Returns all members with the specified name, type, and binding that are declared or inherited by this type. Returns an array of objects representing the public and non-public members defined on this type if is used; otherwise, only the public members are returned. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -1850,11 +1844,11 @@ Returns the specified members declared or inherited by this type. Returns an array of objects representing the public and non-public members declared or inherited by this type. An empty array is returned if there are no matching members. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -1984,11 +1978,11 @@ Returns all the public and non-public methods declared or inherited by this type, as specified. Returns an array of objects representing the public and non-public methods defined on this type if is used; otherwise, only the public methods are returned. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -2039,19 +2033,19 @@ The containing the name of the nested type to get. - A bitmask comprised of one or more that specify how the search is conducted. - - -or- - + A bitmask comprised of one or more that specify how the search is conducted. + + -or- + Zero, to conduct a case-sensitive search for public methods. Returns the specified nested type that is declared by this type. A object representing the nested type that matches the specified requirements, if found; otherwise, . - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -2101,15 +2095,15 @@ This must be a bit flag from , such as , , and so on. Returns the public and non-public nested types that are declared or inherited by this type. - An array of objects representing all the types nested within the current that match the specified binding constraints. - + An array of objects representing all the types nested within the current that match the specified binding constraints. + An empty array of type , if no types are nested within the current , or if none of the nested types match the binding constraints. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -2161,11 +2155,11 @@ Returns all the public and non-public properties declared or inherited by this type, as specified. Returns an array of objects representing the public and non-public properties defined on this type if is used; otherwise, only the public properties are returned. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -2286,15 +2280,15 @@ Returns the GUID of this enum. Read-only. The GUID of this enum. - of the current `EnumBuilder`. - + of the current `EnumBuilder`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EnumBuilder_Properties_4.cs/CPP/enumbuilder_properties_4.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/EnumBuilder/GUID/enumbuilder_properties_4.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_Properties_4.cs/VB/enumbuilder_properties_4.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_Properties_4.cs/VB/enumbuilder_properties_4.vb" id="Snippet4"::: + ]]> This method is not currently supported in types that are not complete. @@ -2419,11 +2413,11 @@ Invokes the specified member. The method that is to be invoked must be accessible and provide the most specific match with the specified argument list, under the constraints of the specified binder and invocation attributes. Returns the return value of the invoked member. - or and use reflection on the retrieved type. - + or and use reflection on the retrieved type. + ]]> This method is not currently supported in types that are not complete. @@ -2711,11 +2705,11 @@ if one or more instance of is defined on this member; otherwise, . - and call on the returned . - + and call on the returned . + ]]> This method is not currently supported in types that are not complete. @@ -3330,15 +3324,15 @@ Retrieves the dynamic module that contains this definition. Read-only. The dynamic module that contains this definition. - @@ -3380,15 +3374,15 @@ Returns the name of this enum. Read-only. The name of this enum. - @@ -3441,15 +3435,15 @@ Returns the namespace of this enum. Read-only. The namespace of this enum. - @@ -3553,15 +3547,15 @@ An instance of a helper class to define the custom attribute. Sets a custom attribute using a custom attribute builder. - , passing a . - + , passing a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute2/CPP/enumbuilder_setcustomattribute2.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/EnumBuilder/GetCustomAttributes/enumbuilder_setcustomattribute2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute2/VB/enumbuilder_setcustomattribute2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute2/VB/enumbuilder_setcustomattribute2.vb" id="Snippet2"::: + ]]> @@ -3620,21 +3614,21 @@ A byte blob representing the attributes. Sets a custom attribute using a specified custom attribute blob. - , passing a byte blob. - + + + +## Examples + The following code sample illustrates the use of `SetCustomAttribute` in the context of , passing a byte blob. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute2/CPP/enumbuilder_setcustomattribute2.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/EnumBuilder/GetCustomAttributes/enumbuilder_setcustomattribute2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute2/VB/enumbuilder_setcustomattribute2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EnumBuilder_SetCustomAttribute2/VB/enumbuilder_setcustomattribute2.vb" id="Snippet2"::: + ]]> @@ -3725,11 +3719,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - The method is called late-bound using the COM IDispatch interface. @@ -3773,11 +3767,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - The method is called late-bound using the COM IDispatch interface. @@ -3817,11 +3811,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - The method is called late-bound using the COM IDispatch interface. @@ -3875,11 +3869,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - The method is called late-bound using the COM IDispatch interface. @@ -3921,13 +3915,13 @@ For information on how to format `binaryAttribute`, see the metadata specificati Retrieves the internal handle for this enum. Read-only. The internal handle for this enum. - or and use reflection on the retrieved type. - - Use this handle to access the underlying metadata handle. - + or and use reflection on the retrieved type. + + Use this handle to access the underlying metadata handle. + ]]> This property is not currently supported. diff --git a/xml/System.Reflection.Emit/ILGenerator.xml b/xml/System.Reflection.Emit/ILGenerator.xml index c417272a8fb..10d2988b34a 100644 --- a/xml/System.Reflection.Emit/ILGenerator.xml +++ b/xml/System.Reflection.Emit/ILGenerator.xml @@ -76,13 +76,13 @@ Generates Microsoft intermediate language (MSIL) instructions. - is used to generate method bodies for methods and constructors in dynamic assemblies (represented by the and classes) and for standalone dynamic methods (represented by the class). To obtain an , use the , , and methods. - - MSIL is used as input to a just-in-time (JIT) compiler. - + is used to generate method bodies for methods and constructors in dynamic assemblies (represented by the and classes) and for standalone dynamic methods (represented by the class). To obtain an , use the , , and methods. + + MSIL is used as input to a just-in-time (JIT) compiler. + ]]> @@ -158,23 +158,23 @@ The object that represents the exception. Begins a catch block. - [!NOTE] -> If the filter exception block returns the `constant exception_execute_handler` (see the documentation for the Common Language Infrastructure Instruction Set), the argument to the `BeginCatchBlock` is not checked. - - - -## Examples - The code sample below demonstrates the contextual usage of the `BeginCatchBlock` method. - +> If the filter exception block returns the `constant exception_execute_handler` (see the documentation for the Common Language Infrastructure Instruction Set), the argument to the `BeginCatchBlock` is not checked. + + + +## Examples + The code sample below demonstrates the contextual usage of the `BeginCatchBlock` method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.ThrowException Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/BeginCatchBlock/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.ThrowException Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.ThrowException Example/VB/source.vb" id="Snippet1"::: + ]]> The catch block is within a filtered exception. @@ -224,19 +224,19 @@ Begins an exception block for a filtered exception. - is associated with a object, emitting filtered exception blocks is not supported. can be used to construct a dynamic method that uses filtered exception blocks. - + is associated with a object, emitting filtered exception blocks is not supported. can be used to construct a dynamic method that uses filtered exception blocks. + ]]> - The Microsoft intermediate language (MSIL) being generated is not currently in an exception block. - - -or- - + The Microsoft intermediate language (MSIL) being generated is not currently in an exception block. + + -or- + This belongs to a . @@ -282,20 +282,20 @@ Begins an exception block for a non-filtered exception. The label for the end of the block. This will leave you in the correct place to execute finally blocks or to finish the try. - @@ -341,26 +341,26 @@ Begins an exception fault block in the Microsoft intermediate language (MSIL) stream. - is associated with a object, emitting exception fault blocks is not supported. can be used to construct a dynamic method that uses exception fault blocks. - - - -## Examples - The following code sample illustrates the use of `BeginFaultBlock`. - + is associated with a object, emitting exception fault blocks is not supported. can be used to construct a dynamic method that uses exception fault blocks. + + + +## Examples + The following code sample illustrates the use of `BeginFaultBlock`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ILGenerator_BeginFaultBlock/CPP/ilgenerator_beginfaultblock.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/BeginFaultBlock/ilgenerator_beginfaultblock.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ILGenerator_BeginFaultBlock/VB/ilgenerator_beginfaultblock.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ILGenerator_BeginFaultBlock/VB/ilgenerator_beginfaultblock.vb" id="Snippet1"::: + ]]> - The MSIL being generated is not currently in an exception block. - - -or- - + The MSIL being generated is not currently in an exception block. + + -or- + This belongs to a . @@ -405,15 +405,15 @@ Begins a finally block in the Microsoft intermediate language (MSIL) instruction stream. - The MSIL being generated is not currently in an exception block. @@ -460,22 +460,22 @@ Begins a lexical scope. - are scoped until the corresponding is called. - - If the current is associated with a object, it does not support symbolic information. - - - -## Examples - The following code sample illustrates the use of `BeginScope` and `EndScope`. - + are scoped until the corresponding is called. + + If the current is associated with a object, it does not support symbolic information. + + + +## Examples + The following code sample illustrates the use of `BeginScope` and `EndScope`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ILGenerator_Begin_EndScope/CPP/ilgenerator_begin_endscope.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/BeginScope/ilgenerator_begin_endscope.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ILGenerator_Begin_EndScope/VB/ilgenerator_begin_endscope.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ILGenerator_Begin_EndScope/VB/ilgenerator_begin_endscope.vb" id="Snippet2"::: + ]]> This belongs to a . @@ -537,22 +537,22 @@ Declares a local variable of the specified type. The declared local variable. - method overload. - - - -## Examples - The following code example demonstrates the use of the `DeclareLocal` method. This code is part of a larger code example for the class. - + method overload. + + + +## Examples + The following code example demonstrates the use of the `DeclareLocal` method. This code is part of a larger code example for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/CPP/localbuilder_sample_4.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/DeclareLocal/localbuilder_sample_4.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/VB/localbuilder_sample_4.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/VB/localbuilder_sample_4.vb" id="Snippet2"::: + ]]> @@ -607,21 +607,21 @@ Declares a local variable of the specified type, optionally pinning the object referred to by the variable. A object that represents the local variable. - is . - The containing type has been created by the method. - - -or- - + The containing type has been created by the method. + + -or- + The method body of the enclosing method has been created by the method. The method with which this is associated is not represented by a . @@ -668,22 +668,22 @@ Declares a new label. A new label that can be used as a token for branching. - . Failure to do so will cause an when is called. - - This is just a token and does not yet represent any particular location within the stream. - - - -## Examples - The code sample below demonstrates the contextual usage of the `DefineLabel` method. - + + This is just a token and does not yet represent any particular location within the stream. + + + +## Examples + The code sample below demonstrates the contextual usage of the `DefineLabel` method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.Label Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/DefineLabel/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.Label Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.Label Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -742,22 +742,22 @@ The Microsoft Intermediate Language (MSIL) instruction to be put onto the stream. Puts the specified instruction onto the stream of instructions. - instructions. - - The instruction values are defined in . - - - -## Examples - The code sample below demonstrates the use of `Emit` to generate MSIL output via an instance of . - + instructions. + + The instruction values are defined in . + + + +## Examples + The code sample below demonstrates the use of `Emit` to generate MSIL output via an instance of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.Emit Example 2/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/Emit/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.Emit Example 2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.Emit Example 2/VB/source.vb" id="Snippet1"::: + ]]> @@ -808,11 +808,11 @@ The character argument pushed onto the stream immediately after the instruction. Puts the specified instruction and character argument onto the Microsoft intermediate language (MSIL) stream of instructions. - @@ -869,11 +869,11 @@ The numerical argument pushed onto the stream immediately after the instruction. Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions. - @@ -924,11 +924,11 @@ The argument pushed onto the stream immediately after the instruction. Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions. - @@ -979,11 +979,11 @@ The numerical argument pushed onto the stream immediately after the instruction. Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions. - @@ -1034,11 +1034,11 @@ The numerical argument pushed onto the stream immediately after the instruction. Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions. - @@ -1099,13 +1099,13 @@ A representing a constructor. Puts the specified instruction and metadata token for the specified constructor onto the Microsoft intermediate language (MSIL) stream of instructions. - @@ -1158,22 +1158,22 @@ The label to which to branch from this location. Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream and leaves space to include a label when fixes are done. - , and their location within the stream is fixed by using . If a single-byte instruction is used, the label can represent a jump of at most 127 bytes along the stream. `opcode` must represent a branch instruction. Because branches are relative instructions, `label` will be replaced with the correct offset to branch during the fixup process. - - - -## Examples - The code sample below illustrates the creation of a dynamic method with a jump table. The jump table is built using an array of . - + , and their location within the stream is fixed by using . If a single-byte instruction is used, the label can represent a jump of at most 127 bytes along the stream. `opcode` must represent a branch instruction. Because branches are relative instructions, `label` will be replaced with the correct offset to branch during the fixup process. + + + +## Examples + The code sample below illustrates the creation of a dynamic method with a jump table. The jump table is built using an array of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.Emit Example 2/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/Emit/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.Emit Example 2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.Emit Example 2/VB/source.vb" id="Snippet1"::: + ]]> @@ -1224,24 +1224,24 @@ The array of label objects to which to branch from this location. All of the labels will be used. Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream and leaves space to include a label when fixes are done. - and their location within the stream is fixed by using . If a single-byte instruction is used, the label can represent a jump of at most 127 bytes along the stream. `opcode` must represent a branch instruction. Because branches are relative instructions, `label` will be replaced with the correct offset to branch during the fixup process. - - - -## Examples - The code sample below illustrates the creation of a dynamic method with a jump table. The jump table is built using an array of . - + and their location within the stream is fixed by using . If a single-byte instruction is used, the label can represent a jump of at most 127 bytes along the stream. `opcode` must represent a branch instruction. Because branches are relative instructions, `label` will be replaced with the correct offset to branch during the fixup process. + + + +## Examples + The code sample below illustrates the creation of a dynamic method with a jump table. The jump table is built using an array of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.Emit Example 2/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/Emit/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.Emit Example 2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.Emit Example 2/VB/source.vb" id="Snippet1"::: + ]]> @@ -1294,11 +1294,11 @@ A local variable. Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the index of the given local variable. - The parent method of the parameter does not match the method associated with this . @@ -1354,11 +1354,11 @@ A helper for constructing a signature token. Puts the specified instruction and a signature token onto the Microsoft intermediate language (MSIL) stream of instructions. - @@ -1411,11 +1411,11 @@ A representing a field. Puts the specified instruction and metadata token for the specified field onto the Microsoft intermediate language (MSIL) stream of instructions. - @@ -1472,15 +1472,15 @@ A representing a method. Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the metadata token for the given method. - @@ -1537,11 +1537,11 @@ The character argument pushed onto the stream immediately after the instruction. Puts the specified instruction and character argument onto the Microsoft intermediate language (MSIL) stream of instructions. - @@ -1598,11 +1598,11 @@ The argument pushed onto the stream immediately after the instruction. Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions. - @@ -1653,11 +1653,11 @@ The to be emitted. Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the metadata token for the given string. - @@ -1714,11 +1714,11 @@ A . Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the metadata token for the given type. - @@ -1792,27 +1792,23 @@ The types of the optional arguments if the method is a method; otherwise, . Puts a or instruction onto the Microsoft intermediate language (MSIL) stream to call a method. - method is used to emit calls to `varargs` methods because there is no overload of the method that specifies the parameter types of the variable arguments. - - To emit calls to methods that do not use the calling convention, use the method overload. - -## Version Information - Beginning with the .NET Framework version 2.0, the method does not throw an exception when optional parameter types are specified for a method that is not `varargs`. is thrown when the call is executed. - - - -## Examples - The following code example emits two methods, a `varargs` method and a method that calls the `varargs` method. The `EmitCall` method is used to emit the call to the `varargs` method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Emit.ArgIterator/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/EmitCall/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Emit.ArgIterator/vb/source.vb" id="Snippet1"::: - - ]]> + method is used to emit calls to `varargs` methods because there is no overload of the method that specifies the parameter types of the variable arguments. + +To emit calls to methods that do not use the calling convention, use the method overload. + +The method does not throw an exception when optional parameter types are specified for a method that is not `varargs`. is thrown when the call is executed. + ]]> + + + does not specify a method call. @@ -1898,20 +1894,20 @@ The types of the required arguments to the instruction. Puts a instruction onto the Microsoft intermediate language (MSIL) stream, specifying an unmanaged calling convention for the indirect call. - to put a instruction onto the stream. Do not use . - - - -## Examples - The following code sample demonstrates the contextual usage of the method to call an unmanaged type method external to the dynamic class. - + to put a instruction onto the stream. Do not use . + + + +## Examples + The following code sample demonstrates the contextual usage of the method to call an unmanaged type method external to the dynamic class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.EmitCalli Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/EmitCalli/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.EmitCalli Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.EmitCalli Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1998,13 +1994,13 @@ The types of the optional arguments for calls. Puts a instruction onto the Microsoft intermediate language (MSIL) stream, specifying a managed calling convention for the indirect call. - to put a instruction onto the stream. Do not use . - - If `optionalParameterTypes` specifies optional arguments, `callingConvention` must include the flag. - + to put a instruction onto the stream. Do not use . + + If `optionalParameterTypes` specifies optional arguments, `callingConvention` must include the flag. + ]]> @@ -2067,26 +2063,26 @@ The local variable whose value is to be written to the console. Emits the Microsoft intermediate language (MSIL) necessary to call with the given local variable. - method. - - - -## Examples - The code sample below demonstrates the contextual usage of the method to write a string to the console in a dynamic method. - + method. + + + +## Examples + The code sample below demonstrates the contextual usage of the method to write a string to the console in a dynamic method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.OpCodes Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/EmitWriteLine/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.OpCodes Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.OpCodes Example/VB/source.vb" id="Snippet1"::: + ]]> - The type of is or , which are not supported. - - -or- - + The type of is or , which are not supported. + + -or- + There is no overload of that accepts the type of . is . @@ -2138,20 +2134,20 @@ The field whose value is to be written to the console. Emits the Microsoft intermediate language (MSIL) necessary to call with the given field. - method. - - - -## Examples - The following code sample demonstrates the use of the method to write a string to the console in a dynamic method. - + method. + + + +## Examples + The following code sample demonstrates the use of the method to write a string to the console in a dynamic method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.OpCodes Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/EmitWriteLine/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.OpCodes Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ILGenerator.OpCodes Example/VB/source.vb" id="Snippet1"::: + ]]> There is no overload of the method that accepts the type of the specified field. @@ -2206,20 +2202,20 @@ The string to be printed. Emits the Microsoft intermediate language (MSIL) to call with a string. - @@ -2265,15 +2261,15 @@ Ends an exception block. - The end exception block occurs in an unexpected place in the code stream. @@ -2321,22 +2317,22 @@ Ends a lexical scope. - . - - If the current is associated with a object, it does not support symbolic information. - - - -## Examples - The following code sample illustrates the use of `BeginScope` and `EndScope`. - + . + + If the current is associated with a object, it does not support symbolic information. + + + +## Examples + The following code sample illustrates the use of `BeginScope` and `EndScope`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ILGenerator_Begin_EndScope/CPP/ilgenerator_begin_endscope.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/BeginScope/ilgenerator_begin_endscope.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ILGenerator_Begin_EndScope/VB/ilgenerator_begin_endscope.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ILGenerator_Begin_EndScope/VB/ilgenerator_begin_endscope.vb" id="Snippet2"::: + ]]> This belongs to a . @@ -2383,15 +2379,15 @@ Gets the current offset, in bytes, in the Microsoft intermediate language (MSIL) stream that is being emitted by the . The offset in the MSIL stream at which the next instruction will be emitted. - property is accessed before any MSIL instructions have been emitted, it returns 0 (zero). - - When MSIL is generated for dynamic languages, this property can be used to map offsets in the MSIL stream to source code line numbers. The resulting information can be used to provide stack traces when exceptions are thrown. - + property is accessed before any MSIL instructions have been emitted, it returns 0 (zero). + + When MSIL is generated for dynamic languages, this property can be used to map offsets in the MSIL stream to source code line numbers. The resulting information can be used to provide stack traces when exceptions are thrown. + ]]> @@ -2440,27 +2436,27 @@ The label for which to set an index. Marks the Microsoft intermediate language (MSIL) stream's current position with the given label. - - represents an invalid index into the label array. - - -or- - + represents an invalid index into the label array. + + -or- + An index for has already been defined. @@ -2503,15 +2499,15 @@ The column in the line where the sequence point ends. Marks a sequence point in the Microsoft intermediate language (MSIL) stream. - is associated with a object, it does not support symbolic information. - + is associated with a object, it does not support symbolic information. + ]]> @@ -2561,11 +2557,11 @@ Caller-allocated array that receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - The method is called late-bound using the COM IDispatch interface. @@ -2609,11 +2605,11 @@ Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - The method is called late-bound using the COM IDispatch interface. @@ -2653,11 +2649,11 @@ Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - The method is called late-bound using the COM IDispatch interface. @@ -2711,11 +2707,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - The method is called late-bound using the COM IDispatch interface. @@ -2774,22 +2770,22 @@ The class of the type of exception to throw. Emits an instruction to throw an exception. - - is not the class or a derived class of . - - -or- - + is not the class or a derived class of . + + -or- + The type does not have a parameterless constructor. is . @@ -2844,11 +2840,11 @@ The namespace to be used in evaluating locals and watches for the current active lexical scope. Specifies the namespace to be used in evaluating locals and watches for the current active lexical scope. - is associated with a object, this method is not supported. - + is associated with a object, this method is not supported. + ]]> Length of is zero. diff --git a/xml/System.Reflection.Emit/TypeBuilder.xml b/xml/System.Reflection.Emit/TypeBuilder.xml index cb106ff255c..8f67fbf68fa 100644 --- a/xml/System.Reflection.Emit/TypeBuilder.xml +++ b/xml/System.Reflection.Emit/TypeBuilder.xml @@ -392,16 +392,10 @@ The following code sample demonstrates how to build a type dynamically by using Read-only. The full name of this type qualified by the display name of the assembly. ) and the display name of the assembly (), separated by a comma and a space. -## Remarks - The format of the returned string is the concatenation of the full name of the type () and the display name of the assembly (), separated by a comma and a space. - - See for a description of the format of the display name of an assembly. - -## Version Information - In the .NET Framework versions 1.0 and 1.1, the value of this property does not include the culture or public key. - - ]]> +See for a description of the format of the display name of an assembly. + ]]> diff --git a/xml/System.Resources/ResourceManager.xml b/xml/System.Resources/ResourceManager.xml index ca27a669f63..f1194d2d3de 100644 --- a/xml/System.Resources/ResourceManager.xml +++ b/xml/System.Resources/ResourceManager.xml @@ -180,82 +180,7 @@ A type from which the resource manager derives all information for finding .resources files. Initializes a new instance of the class that looks up resources in satellite assemblies based on information from the specified type object. - - attribute is not used to indicate that the resources of the default culture reside in a satellite assembly, the resource manager assumes that the resource file for the default culture is found in the same assembly as the type specified by the `resourceSource` parameter. - -- The resource manager assumes that the default resource file has the same base name as the type specified by the `resourceSource` parameter. - -- The resource manager uses the default class to manipulate the resource file. - - For example, given a type named MyCompany.MyProduct.MyType, the resource manager looks for a .resources file named MyCompany.MyProduct.MyType.resources in the assembly that defines MyType. - - In Visual Studio, the Resource Designer automatically generates code that defines an `internal` (in C#) or `Friend` (in Visual Basic) class whose name is the same as the base name of the .resources file for the default culture. This makes it possible to instantiate a object and couple it with a particular set of resources by getting a type object whose name corresponds to the name of the resource, because as long as the class is visible to the compiler, the resources must be as well. For example, if a .resources file is named Resource1, the following statement instantiates a object to manage the .resources file named Resource1: - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/.ctor/ctor1.cs" id="Snippet2"::: - - If you're not using Visual Studio, you can create a class with no members whose namespace and name are the same as that of the default .resources file. The example provides an illustration. - -## Windows 8.x Apps - -> [!IMPORTANT] -> Although the class is supported in Windows 8.x apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x apps. To retrieve resources from Windows 8.x apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. - - In Windows 8.x apps, uses the `resourceSource` parameter to infer the assembly, base name, and the namespace where the resource items can be located within the app's package resource index (PRI) file. For example, given a type named MyCompany.MyProduct.MyType that is defined in `MyAssembly`, the resource manager looks for a resource set identifier named MyAssembly and looks for a scope MyCompany.MyProduct.MyType within that resource set. The resource manager searches for resource items under the default context (current culture, current high contrast setting, and so on) within this scope. - - - -## Examples - The following example uses the constructor to instantiate a object. It consists of resources compiled from .txt files for the English (en), French (France) (fr-FR), and Russian (Russia) (ru-RU) cultures. The example changes the current culture and current UI culture to English (United States), French (France), Russian (Russia), and Swedish (Sweden). It then calls the method to retrieve the localized string, which displays a greeting that depends on the time of day. - - The example requires three text-based resource files, as listed in the following table. Each file includes string resources named `Morning`, `Afternoon`, and `Evening`. - -|Culture|File name|Resource name|Resource value| -|-------------|---------------|-------------------|--------------------| -|en-US|GreetingResources.txt|`Morning`|Good morning| -|en-US|GreetingResources.txt|`Afternoon`|Good afternoon| -|en-US|GreetingResources.txt|`Evening`|Good evening| -|fr-FR|GreetingResources.fr-FR.txt|`Morning`|Bonjour| -|fr-FR|GreetingResources.fr-FR.txt|`Afternoon`|Bonjour| -|fr-FR|GreetingResources.fr-FR.txt|`Evening`|Bonsoir| -|ru-RU|GreetingResources.ru-RU.txt|`Morning`|Доброе утро| -|ru-RU|GreetingResources.ru-RU.txt|`Afternoon`|Добрый день| -|ru-RU|GreetingResources.ru-RU.txt|`Evening`|Добрый вечер| - - You can use the following batch file to compile the Visual Basic example and create an executable named Greet.exe. To compile with C#, change the compiler name from `vbc` to `csc` and the file extension from `.vb` to `.cs`. - -``` - -resgen GreetingResources.txt -vbc Greet.vb /resource: GreetingResources.resources - -md fr-FR -resgen GreetingResources.fr-FR.txt -al /out:fr-FR\Greet.resources.dll /culture:fr-FR /embed: GreetingResources.fr-FR.resources - -md ru-RU -resgen GreetingResources.ru-RU.txt -al /out:ru-RU\Greet.resources.dll /culture:ru-RU /embed: GreetingResources.ru-RU.resources - -``` - - Here's the source code for the example (ShowDate.vb for the Visual Basic version or ShowDate.cs for the C# version of the code). - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/.ctor/greet.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.ctor/vb/greet.vb" id="Snippet3"::: - - In addition to defining an app class named `Example`, the source code defines an internal class whose name, `GreetingResources`, is the same as the base name of the resource files. This makes it possible to successfully instantiate a object by calling the constructor. - - Notice that the output displays the appropriate localized string except when the current UI culture is Swedish (Sweden), in which case it uses English language resources. Because Swedish language resources are unavailable, the app uses the resources of the default culture, as defined by the attribute, instead. - - ]]> - + For more information about this API, see Supplemental API remarks for ResourceManager constructor. The parameter is . @@ -307,62 +232,7 @@ al /out:ru-RU\Greet.resources.dll /culture:ru-RU /embed: GreetingResources.ru-RU The root name of the resource file without its extension but including any fully qualified namespace name. For example, the root name for the resource file named MyApplication.MyResource.en-US.resources is MyApplication.MyResource. The main assembly for the resources. Initializes a new instance of the class that looks up resources contained in files with the specified root name in the given assembly. - - [!NOTE] -> To retrieve resources from .resources files directly instead of retrieving them from assemblies, you must call the method instead to instantiate a object. - - If the resource file identified by `baseName` cannot be found in `assembly`, the method instantiates a object, but the attempt to retrieve a specific resource throws an exception, typically . For information about diagnosing the cause of the exception, see the "Handling the MissingManifestResourceException Exception" section of the class topic. - -## Windows 8.x Apps - -> [!IMPORTANT] -> Although the class is supported in Windows 8.x apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x apps. To retrieve resources from Windows 8.x apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. - - In Windows 8.x apps, the resource manager uses the simple name of the `assembly` parameter to look up a matching resource set in the app's package resource index (PRI) file. The `baseName` parameter is used to look up a resource item within the resource set. For example, the root name for PortableLibrary1.Resource1.de-DE.resources is PortableLibrary1.Resource1. - - - -## Examples - The following example uses a simple non-localized "Hello World" app to illustrate the constructor. The following shows the contents of a text file named ExampleResources.txt. When the app is compiled, the resource is embedded in the main app assembly. - -``` -Greeting=Hello -``` - - The text file can be converted to a binary resource file by using the [Resource File Generator (ResGen.exe)](/dotnet/framework/tools/resgen-exe-resource-file-generator) at the command prompt as follows: - -``` -resgen ExampleResources.txt -``` - - The following example provides the executable code that instantiates a object, prompts the user to enter a name, and displays a greeting. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/.ctor/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.ctor/vb/example.vb" id="Snippet1"::: - - It can be compiled by using the following command in Visual Basic: - -``` -vbc Example.vb /resource:ExampleResources.resources -``` - - or by using the following command in C#: - -``` -csc Example.cs /resource:ExampleResources.resources -``` - - Note that the example retrieves a reference to the assembly that contains the resource file by passing a type defined in that assembly to the `typeof` function (in C#) or the `GetType` function (in Visual Basic) and retrieving the value of its property. - - ]]> - + For more information about this API, see Supplemental API remarks for ResourceManager constructor. The or parameter is . This constructor uses the system-provided implementation. To use a custom resource file format, you should derive from the class, override the and methods, and pass that type to the constructor. Using a custom can be useful for controlling resource caching policy or supporting your own resource file format, but is generally not necessary. @@ -789,57 +659,7 @@ csc Example.cs /resource:ExampleResources.resources The name of the resource to get. Returns the value of the specified non-string resource. The value of the resource localized for the caller's current culture settings. If an appropriate resource set exists but cannot be found, the method returns . - - method is used to retrieve non-string resources. These include values that belong to primitive data types such as or , bitmaps (such as a object), or custom serialized objects. Typically, the returned object must be cast (in C#) or converted (in Visual Basic) to an object of the appropriate type. - - The returned resource is localized for the UI culture of the current thread, which is defined by the property. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. - - The property determines whether the comparison of `name` with the names of resources is case-insensitive or case-sensitive (the default). - -> [!CAUTION] -> This method can throw more exceptions than are listed. One reason this might occur is if a method that this method calls throws an exception. For example, a exception might be thrown if an error was made deploying or installing a satellite assembly, or a exception might be thrown if a user-defined type throws a user-defined exception when the type is deserialized. - -## Performance Considerations - If you call the method multiple times with the same `name` parameter, do not depend on the method returning a reference to the same object with each call. This is because the method can return a reference to an existing resource object in a cache, or it can reload the resource and return a reference to a new resource object. - - - -## Examples - The following example uses the method to deserialize a custom object. The example includes a source code file named UIElements.cs (UIElements.vb if you're using Visual Basic) that defines the following structure named `PersonTable`. This structure is intended to be used by a general table display routine that displays the localized names of table columns. Note that the `PersonTable` structure is marked with the attribute. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/Overview/example1.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example.vb" id="Snippet6"::: - - The following code from a file named CreateResources.cs (CreateResources.vb for Visual Basic) creates an XML resource file named UIResources.resx that stores a table title and a `PersonTable` object that contains information for an app that is localized for the English language. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/Overview/example11.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example.vb" id="Snippet7"::: - - The following code in a source code file named GetObject.cs (GetObject.vb) then retrieves the resources and displays them to the console. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/Overview/example2.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example2.vb" id="Snippet8"::: - - You can build the necessary resource file and assemblies and run the app by executing the following batch file. You must use the `/r` option to supply Resgen.exe with a reference to UIElements.dll so that it can access information about the `PersonTable` structure. If you're using C#, replace the `vbc` compiler name with `csc`, and replace the `.vb` extension with `.cs`. - -``` - -vbc /t:library UIElements.vb -vbc CreateResources.vb /r:UIElements.dll -CreateResources - -resgen UIResources.resx /r:UIElements.dll -vbc GetObject.vb /r:UIElements.dll /resource:UIResources.resources - -GetObject.exe - -``` - - ]]> - + For more information about this API, see Supplemental API remarks for ResourceManager.GetObject. The parameter is . No usable set of localized resources has been found, and there are no default culture resources. For information about how to handle this exception, see the "Handling MissingManifestResourceException and MissingSatelliteAssemblyException Exceptions" section in the class topic. The default culture's resources reside in a satellite assembly that could not be found. For information about how to handle this exception, see the "Handling MissingManifestResourceException and MissingSatelliteAssemblyException Exceptions" section in the class topic. @@ -908,69 +728,7 @@ GetObject.exe If this value is , the object is obtained by using the property. Gets the value of the specified non-string resource localized for the specified culture. The value of the resource, localized for the specified culture. If an appropriate resource set exists but cannot be found, the method returns . - - method is used to retrieve non-string resources. These include values that belong to primitive data types such as or , bitmaps (such as a object), or custom serialized objects. Typically, the returned object must be cast (in C#) or converted (in Visual Basic) to an object of the appropriate type. - - The returned resource is localized for the culture that is specified by `culture`, or for the culture that is specified by the property if `culture` is `null`. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the resource manager falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. - - The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. - -> [!CAUTION] -> This method can throw more exceptions than are listed. One reason this might occur is if a method that this method calls throws an exception. For example, a exception might be thrown if an error was made deploying or installing a satellite assembly, or a exception might be thrown if a user-defined type throws a user-defined exception when the type is deserialized. - -## Performance Considerations - If you call the method multiple times with the same `name` parameter, do not depend on the method returning a reference to the same object with each call. This is because the method can return a reference to an existing resource object in a cache, or it can reload the resource and return a reference to a new resource object. - - - -## Examples - The following example uses the method to deserialize a custom object. The example includes a source code file named NumberInfo.cs (NumberInfo.vb if you're using Visual Basic) that defines the following structure named `Numbers`. This structure is intended to be used by a simple educational app that teaches non-English speaking students to count to ten in English. Note that the `Numbers` class is marked with the attribute. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/GetObject/numberinfo.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/numberinfo.vb" id="Snippet1"::: - - The following source code from a file named CreateResources.cs (CreateResources.vb for Visual Basic) creates XML resource files for the default English language, as well as for the French, Portuguese, and Russian languages. - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/GetObject/createresources.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/createresources.vb" id="Snippet2"::: - - The resources are consumed by the following app, which sets the current UI culture to French (France), Portuguese (Brazil), or Russian (Russia). It calls the method to get a `Numbers` object that contains localized numbers and the method to get a `Numbers` object that contains English language numbers. It then displays odd numbers using the current UI culture and the English language. The source code file is named ShowNumbers.cs (ShowNumbers.vb). - - :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceManager/GetObject/shownumbers.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.getobject/vb/shownumbers.vb" id="Snippet3"::: - - You can use the following batch file to build and execute the Visual Basic version of the example. If you're using C#, replace `vbc` with `csc`, and replace the `.vb` extension with `.cs`. - -``` - -vbc /t:library NumberInfo.vb - -vbc CreateResources.vb /r:NumberInfo.dll -CreateResources - -resgen NumberResources.resx /r:NumberInfo.dll - -resgen NumberResources.fr.resx /r:Numberinfo.dll -Md fr -al /embed:NumberResources.fr.resources /culture:fr /t:lib /out:fr\ShowNumbers.resources.dll - -resgen NumberResources.pt.resx /r:Numberinfo.dll -Md pt -al /embed:NumberResources.pt.resources /culture:pt /t:lib /out:pt\ShowNumbers.resources.dll - -resgen NumberResources.ru.resx /r:Numberinfo.dll -Md ru -al /embed:NumberResources.ru.resources /culture:ru /t:lib /out:ru\ShowNumbers.resources.dll - -vbc ShowNumbers.vb /r:NumberInfo.dll /resource:NumberResources.resources -ShowNumbers.exe -``` - - ]]> - + For more information about this API, see Supplemental API remarks for ResourceManager.GetObject. The parameter is . No usable set of resources have been found, and there are no default culture resources. For information about how to handle this exception, see the "Handling MissingManifestResourceException and MissingSatelliteAssemblyException Exceptions" section in the class topic. The default culture's resources reside in a satellite assembly that could not be found. For information about how to handle this exception, see the "Handling MissingManifestResourceException and MissingSatelliteAssemblyException Exceptions" section in the class topic. @@ -1488,59 +1246,7 @@ csc GetStream.cs /resource:AppResources.resources The name of the resource to retrieve. Returns the value of the specified string resource. The value of the resource localized for the caller's current UI culture, or if cannot be found in a resource set. - - property. If the resource has not been localized for that culture, the resource manager probes for a resource by following the steps outlined in the "Resource Fallback Process" section of the [Packaging and Deploying Resources](/dotnet/framework/resources/packaging-and-deploying-resources-in-desktop-apps) article. If no usable set of localized resources is found, the resource manager falls back on the default culture's resources. If the resource manager cannot load the default culture's resource set, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. - - The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. - -> [!CAUTION] -> This method can throw more exceptions than are listed. One reason this might occur is if a method that this method calls throws an exception. For example, a exception might be thrown if an error was made deploying or installing a satellite assembly, or a exception might be thrown if a user-defined type throws a user-defined exception when the type is deserialized. - -## Windows 8.x Apps - -> [!IMPORTANT] -> Although the class is supported in Windows 8.x apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x apps. To retrieve resources from Windows 8.x apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. - - In Windows 8.x apps, the method returns the value of the `name` string resource, localized for the caller's current UI culture settings. The list of cultures is derived from the operating system's preferred UI language list. If the resource manager cannot match `name`, the method returns `null`. - - - -## Examples - The following example uses the method to retrieve culture-specific resources. It consists of resources compiled from .txt files for the English (en), French (France) (fr-FR), and Russian (Russia) (ru-RU) cultures. The example changes the current culture and current UI culture to English (United States), French (France), Russian (Russia), and Swedish (Sweden). It then calls the method to retrieve the localized string, which it displays along with the current day and month. Notice that the output displays the appropriate localized string except when the current UI culture is Swedish (Sweden). Because Swedish language resources are unavailable, the app instead uses the resources of the default culture, which is English. The example requires the text-based resource files listed in following table. Each has a single string resource named `DateStart`. - -|Culture|File name|Resource name|Resource value| -|-------------|---------------|-------------------|--------------------| -|en-US|DateStrings.txt|`DateStart`|Today is| -|fr-FR|DateStrings.fr-FR.txt|`DateStart`|Aujourd'hui, c'est le| -|ru-RU|DateStrings.ru-RU.txt|`DateStart`|Сегодня| - - You can use the following batch file to compile the C# example. For Visual Basic, change `csc` to `vbc`, and change the extension of the source code file from `.cs` to `.vb`. - -``` -resgen DateStrings.txt -csc showdate.cs /resource:DateStrings.resources - -md fr-FR -resgen DateStrings.fr-FR.txt -al /out:fr-FR\Showdate.resources.dll /culture:fr-FR /embed:DateStrings.fr-FR.resources - -md ru-RU -resgen DateStrings.ru-RU.txt -al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.resources -``` - - Here's the source code for the example (ShowDate.vb for the Visual Basic version or ShowDate.cs for the C# version). - - :::code language="csharp" source="~/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/showdate.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/showdate.vb" id="Snippet2"::: - - ]]> - + For more information about this API, see Supplemental API remarks for ResourceManager.GetString. The parameter is . The value of the specified resource is not a string. No usable set of resources has been found, and there are no resources for the default culture. For information about how to handle this exception, see the "Handling MissingManifestResourceException and MissingSatelliteAssemblyException Exceptions" section in the class topic. @@ -1615,63 +1321,7 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res An object that represents the culture for which the resource is localized. Returns the value of the string resource localized for the specified culture. The value of the resource localized for the specified culture, or if cannot be found in a resource set. - - method uses the current UI culture obtained from the property. - - The resource that is returned is localized for the culture specified by the `culture` parameter. If the resource has not been localized for `culture`, the resource manager probes for a resource by following the steps outlined in the "Resource Fallback Process" section of the [Packaging and Deploying Resources](/dotnet/framework/resources/packaging-and-deploying-resources-in-desktop-apps) topic. If no usable set of resources is found, the resource manager falls back on the default culture's resources. If the resource manager cannot load the default culture's resource set, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. - - The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. - -> [!CAUTION] -> This method can throw more exceptions than are listed. One reason this might occur is if a method that this method calls throws an exception. For example, a exception might be thrown if an error was made deploying or installing a satellite assembly, or a exception might be thrown if a user-defined type throws a user-defined exception when the type is deserialized. - -## Windows 8.x Apps - -> [!IMPORTANT] -> Although the class is supported in Windows 8.x apps, we do not recommend its use. Use this class only when you develop Portable Class Library projects that can be used with Windows 8.x apps. To retrieve resources from Windows 8.x apps, use the [Windows.ApplicationModel.Resources.ResourceLoader](https://go.microsoft.com/fwlink/p/?LinkId=238182) class instead. - - In Windows 8.x apps, the method returns the value of the `name` string resource, localized for the culture specified by the `culture` parameter. If the resource is not localized for the `culture` culture, the lookup uses the entire Windows 8 language fallback list, and stops after looking in the default culture. If the resource manager cannot match `name`, the method returns `null`. - - - -## Examples - The following example uses the method to retrieve culture-specific resources. The example's default culture is English (en), and it includes satellite assemblies for the French (France) (fr-FR) and Russian (Russia) (ru-RU) cultures. The example changes the current culture and current UI culture to Russian (Russia) before calling . It then calls the method and the method and passes objects that represent the French (France) and Swedish (Sweden) cultures to each method. In the output, the month and day of the month as well as the string that precedes them appear in French, because the method is able to retrieve the French language resource. However, when the Swedish (Sweden) culture is used, the month and day of the month appear in Swedish, although the string that precedes them is in English. This is because the resource manager cannot find localized Swedish language resources, so it returns a resource for the default English culture instead. - - The example requires the text-based resource files listed in following table. Each has a single string resource named `DateStart`. - -|Culture|File name|Resource name|Resource value| -|-------------|---------------|-------------------|--------------------| -|en-US|DateStrings.txt|`DateStart`|Today is| -|fr-FR|DateStrings.fr-FR.txt|`DateStart`|Aujourd'hui, c'est le| -|ru-RU|DateStrings.ru-RU.txt|`DateStart`|Сегодня| - - You can use the following batch file to compile the Visual Basic example. To compile in C#, change `vbc` to `csc`, and change the extension of the source code file from `.vb` to `.cs`. - -``` -resgen DateStrings.txt -vbc showdate.vb /resource:DateStrings.resources - -md fr-FR -resgen DateStrings.fr-FR.txt -al /out:fr-FR\Showdate.resources.dll /culture:fr-FR /embed:DateStrings.fr-FR.resources - -md ru-RU -resgen DateStrings.ru-RU.txt -al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.resources -``` - - Here's the source code for the example (ShowDate.vb for the Visual Basic version or ShowDate.cs for the C# version). - - :::code language="csharp" source="~/snippets/csharp/System.Resources/MissingManifestResourceException/Overview/showdate2.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/showdate2.vb" id="Snippet3"::: - - ]]> - + For more information about this API, see Supplemental API remarks for ResourceManager.GetString. The parameter is . The value of the specified resource is not a string. No usable set of resources has been found, and there are no resources for a default culture. For information about how to handle this exception, see the "Handling MissingManifestResourceException and MissingSatelliteAssemblyException Exceptions" section in the class topic. diff --git a/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml b/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml index 7617858de15..00d494d39ff 100644 --- a/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml +++ b/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml @@ -429,52 +429,7 @@ This method is intended for compiler use rather than use directly in code. `T` m An object to retrieve the hash code for. Serves as a hash function for a particular object, and is suitable for use in algorithms and data structures that use hash codes, such as a hash table. A hash code for the object identified by the parameter. - - method always calls the method non-virtually, even if the object's type has overridden the method. Therefore, using might differ from calling `GetHashCode` directly on the object with the method. - -> [!WARNING] -> Although the method returns identical hash codes for identical object references, you should not use this method to test for object identity, because this hash code does not uniquely identify an object reference. To test for object identify (that is, to test that two objects reference the same object in memory), call the method. Nor should you use to test whether two strings represent equal object references, because the string is interned. To test for string interning, call the method. - - The and methods differ as follows: - -- returns a hash code that is based on the object's definition of equality. For example, two strings with identical contents will return the same value for . - -- returns a hash code that indicates object identity. That is, two string variables whose contents are identical and that represent a string that is interned (see the [String Interning](#interning) section) or that represent a single string in memory return identical hash codes. - -> [!IMPORTANT] -> Note that always returns identical hash codes for equal object references. However, the reverse is not true: equal hash codes do not indicate equal object references. A particular hash code value is not unique to a particular object reference; different object references can generate identical hash codes. - - This method is used by compilers. - - -## String Interning - The common language runtime (CLR) maintains an internal pool of strings and stores literals in the pool. If two strings (for example, `str1` and `str2`) are formed from an identical string literal, the CLR will set `str1` and `str2` to point to the same location on the managed heap to conserve memory. Calling on these two string objects will produce the same hash code, contrary to the second bulleted item in the previous section. - - The CLR adds only literals to the pool. Results of string operations such as concatenation are not added to the pool, unless the compiler resolves the string concatenation as a single string literal. Therefore, if `str2` was created as the result of a concatenation operation, and `str2` is identical to `str1`, using on these two string objects will not produce the same hash code. - - If you want to add a concatenated string to the pool explicitly, use the method. - - You can also use the method to check whether a string has an interned reference. - - - -## Examples - The following example demonstrates the difference between the and methods. The output from the example illustrates the following: - -- Both sets of hash codes for the first set of strings passed to the `ShowHashCodes` method are different, because the strings are completely different. - -- generates the same hash code for the second set of strings passed to the `ShowHashCodes` method, because the strings are equal. However, the method does not. The first string is defined by using a string literal and so is interned. Although the value of the second string is the same, it is not interned, because it is returned by a call to the method. - -- In the case of the third string, the hash codes produced by for both strings are identical, as are the hash codes produced by . This is because the compiler has treated the value assigned to both strings as a single string literal, and so the string variables refer to the same interned string. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/RuntimeHelpers/GetHashCode/gethashcodeex1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.runtimehelpers.gethashcode/vb/gethashcodeex1.vb" id="Snippet1"::: - - ]]> - + For more information about this API, see Supplemental API remarks for RuntimeHelpers.GetHashCode. diff --git a/xml/System.Runtime.InteropServices/Marshal.xml b/xml/System.Runtime.InteropServices/Marshal.xml index a90b73644c2..f75e9ca2699 100644 --- a/xml/System.Runtime.InteropServices/Marshal.xml +++ b/xml/System.Runtime.InteropServices/Marshal.xml @@ -2830,31 +2830,19 @@ The programmatic identifier (ProgID) of the object that was requested. Obtains a running instance of the specified object from the running object table (ROT). The object that was requested; otherwise . You can cast this object to any COM interface that it supports. - + For more information about this API, see Supplemental API remarks for Marshal.GetActiveObject. + exposes the COM [GetActiveObject](/windows/win32/api/oleauto/nf-oleauto-getactiveobject) function from OLEAUT32.DLL; however, the latter expects a class identifier (CLSID) instead of the programmatic identifier (`ProgID`) expected by this method. To obtain a running instance of a COM object without a registered `ProgID`, use platform invoke to define the COM [GetActiveObject](/windows/win32/api/oleauto/nf-oleauto-getactiveobject) function. For a description of platform invoke, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). - -## ProgID and CLSID - Keys in the HKEY_CLASSES_ROOT subtree of the registry contain a variety of subkey types. Most of the subkeys are ProgIDs, which map a user-friendly string to a CLSID. Applications often use these human-readable strings instead of the numeric CLSIDs. Often, a component has a version-independent ProgID that is mapped to the latest version of the component that is installed on the system. - - Applications and components primarily use ProgIDs to retrieve their corresponding CLSIDs. +The example calls twice. The first call tries to retrieve a reference to an instance of Microsoft Word (an instance of the `Word.Application` object). The second call tries to retrieve a reference to an instance of Microsoft Excel (an instance of an `Excel.Application` object). +The code retrieves a reference to an instance of Microsoft Word successfully. However, because Microsoft Excel is not running, the attempt to retrieve the second object raises a . - -## Examples - The following example was run on a computer that was configured with a running instance of Microsoft Word. There were no instances of Microsoft Excel running. - - The example calls twice. The first call tries to retrieve a reference to an instance of Microsoft Word (an instance of the `Word.Application` object). The second call tries to retrieve a reference to an instance of Microsoft Excel (an instance of an `Excel.Application` object). - - The code retrieves a reference to an instance of Microsoft Word successfully. However, because Microsoft Excel is not running, the attempt to retrieve the second object raises a . - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/Marshal/GetActiveObject/marshal.getactiveobject.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.marshal.getactiveobject/vb/marshal.getactiveobject.vb" id="Snippet1"::: - - ]]> - +:::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/Marshal/GetActiveObject/marshal.getactiveobject.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.marshal.getactiveobject/vb/marshal.getactiveobject.vb" id="Snippet1"::: + ]]> + The object was not found. diff --git a/xml/System.Runtime.Serialization.Formatters.Soap/SoapFormatter.xml b/xml/System.Runtime.Serialization.Formatters.Soap/SoapFormatter.xml index beac8cc4465..c85db9ba54d 100644 --- a/xml/System.Runtime.Serialization.Formatters.Soap/SoapFormatter.xml +++ b/xml/System.Runtime.Serialization.Formatters.Soap/SoapFormatter.xml @@ -313,18 +313,14 @@ TimeSpan objects are serialized according to the ISO 8601: 1998 section 5.5.3.2. The top object of the deserialized graph (root). parameter is one of two ways to return headers from a stream in SOAP Remote Procedure Call (RPC) format. The other way is to use the property. -## Remarks - Headers are used only for specific remoting applications. The parameter is one of two ways to return headers from a stream in SOAP Remote Procedure Call (RPC) format. The other way is to use the property. - - For successful deserialization, the current position in the stream must be at the beginning of the object graph. +For successful deserialization, the current position in the stream must be at the beginning of the object graph. -## TimeSpan Serialization - TimeSpan objects are serialized according to the ISO 8601: 1998 section 5.5.3.2.1 "Alternative" standard. +TimeSpan objects are serialized according to the ISO 8601: 1998 section 5.5.3.2.1 "Alternative" standard. [!INCLUDE [untrusted-data-method-note](~/includes/untrusted-data-method-note.md)] - - ]]> + ]]> is . diff --git a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml index 07b003a28af..8778112585f 100644 --- a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml +++ b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml @@ -40,16 +40,16 @@ Represents a CMS/PKCS#7 structure for enveloped data. - @@ -92,22 +92,22 @@ Initializes a new instance of the class with default values. - class has the following default property values: - -|Property|Default value| -|--------------|-------------------| -||Content Type: 1.2.840.113549.1.7.1 (data)
Length: zero| -||1.2.840.113549.3.7 (RSA_DES_EDE3_CBC) or 2.16.840.1.101.3.4.1.42 (AES-256-CBC)| - - The default for recipients is . + +|Property|Default value| +|--------------|-------------------| +||Content Type: 1.2.840.113549.1.7.1 (data)
Length: zero| +||1.2.840.113549.3.7 (RSA_DES_EDE3_CBC) or 2.16.840.1.101.3.4.1.42 (AES-256-CBC)| + + The default for recipients is . On .NET Framework, the default symmetric encryption algorithm is determined by the version of the .NET Framework that the application executable was built against. Starting with .NET Framework 4.8, the default algorithm is AES-256 in CBC mode; in prior versions, the default is TripleDES (DES3-EDE) in CBC mode. On .NET Core, the default symmetric encryption algorithm is determined by the version of the System.Security.Cryptography.Pkcs assembly that is loaded. Starting with the 4.6.0 version of the System.Security.Cryptography.Pkcs NuGet package, the default algorithm is AES-256 in CBC mode; in prior versions, the default is TripleDES (DES3-EDE) in CBC mode. - + ]]> @@ -145,17 +145,17 @@ The message content to encrypt. Initializes a new instance of the class with specified content information. - for recipients is . + for recipients is . On .NET Framework, the default symmetric encryption algorithm is determined by the version of the .NET Framework that the application executable was built against. Starting with .NET Framework 4.8, the default algorithm is AES-256 in CBC mode; in prior versions, the default is TripleDES (DES3-EDE) in CBC mode. On .NET Core, the default symmetric encryption algorithm is determined by the version of the System.Security.Cryptography.Pkcs assembly that is loaded. Starting with the 4.6.0 version of the System.Security.Cryptography.Pkcs NuGet package, the default algorithm is AES-256 in CBC mode; in prior versions, the default is TripleDES (DES3-EDE) in CBC mode. - - + + ]]> The parameter is . @@ -197,12 +197,12 @@ The identifier for the symmetric encryption algorithm to use when encrypting the message content. Initializes a new instance of the class with a specified symmetric encryption algorithm and content information. - for recipients is . - The default for recipients is . - ]]> The or parameter is . @@ -236,13 +236,13 @@ The message content to encrypt. Initializes a new instance of the class with specified content information and a subject identifier scheme when selecting recipients by UI. - The parameter is . @@ -320,13 +320,13 @@ Gets the collection of certificates associated with the enveloped CMS/PKCS#7 message. The collection of certificates associated with the enveloped CMS/PKCS#7 message. - class is being used to to encrypt data, the contents of this collection are embedded into the pending message during the call to one of the methods. Changes after the encryption operation have no effect. The value of this property is replaced with a different collection object during a call to , which then represents the certificates that were read out of the decoded message. - + ]]> @@ -364,9 +364,9 @@ Gets the identifier of the symmetric encryption algorithm associated with this message. The identifier of the symmetric encryption algorithm associated with this message. - class is being used to to encrypt data, the value of this property indicates which symmetric encryption algorithm to use to encrypt the content of . The value of this property is replaced during a call to , which then represents the symmetric encryption algorithm which was used to encrypt the decoded message. @@ -408,13 +408,13 @@ Gets the content information for the enveloped CMS/PKCS#7 message. The content information for the enveloped CMS/PKCS#7 message. - class is being used to to encrypt data, the value of this property represents the data to encrypt. It is not replaced with encrypted content after a call to an method. The value of this property is replaced during a call to , which then represents the encrypted content decoded from the message. After a successful call to a method, the value is replaced again, with the decrypted message contents. - + ]]> @@ -542,20 +542,19 @@ Decrypts the contents of the decoded enveloped CMS/PKCS#7 message via any available recipient by searching certificate stores for a matching certificate and key. - should be called before or any other method. - - The method does not search the computer My store if it is inaccessible. - -## .NET Framework Security - The following permissions are required to access the decryption key: - -- - -- - + should be called before or any other method. + +The method does not search the computer My store if it is inaccessible. + +The following permissions are required to access the decryption key on .NET Framework: + +- +- + ]]> A cryptographic operation could not be completed. @@ -598,17 +597,13 @@ The recipient info to use for decryption. Decrypts the contents of the decoded enveloped CMS/PKCS#7 message via a specified recipient info by searching certificate stores for a matching certificate and key. - - -- - + +- + ]]> The parameter is . @@ -652,17 +647,13 @@ A collection of certificates to use in addition to the certificate stores for finding a recipient certificate and private key. Decrypts the contents of the decoded enveloped CMS/PKCS#7 message via any available recipient info by searching certificate stores and a provided collection for a matching certificate and key. - - -- - + +- + ]]> The parameter was . @@ -710,11 +701,11 @@ The private key to use to decrypt the recipient-specific information. Decrypts the contents of the decoded enveloped CMS/PKCS#7 message via a specified recipient info with a specified private key. - method can be used to manually match an expected certificate to the value to evaluate the applicability of the private key to the recipient info value. - + ]]> The or parameter is . @@ -761,17 +752,13 @@ Unlike the other overloads of `Decrypt`, this overload does not search certifica A collection of certificates to use in addition to the certificate stores for finding a recipient certificate and private key. Decrypts the contents of the decoded enveloped CMS/PKCS#7 message via a specified recipient info by searching certificate stores and a provided collection for a matching certificate and key. - - -- - + +- + ]]> The or parameter is . @@ -819,11 +806,11 @@ Unlike the other overloads of `Decrypt`, this overload does not search certifica Encodes the contents of the enveloped CMS/PKCS#7 message and returns it as a byte array. A byte array representing the encoded form of the CMS/PKCS#7 message. - method. - + method. + ]]> A method call was invalid for the object's current state. @@ -864,18 +851,18 @@ Unlike the other overloads of `Decrypt`, this overload does not search certifica Encrypts the contents of the CMS/PKCS#7 message after selecting recipient certificates via a UI popup. - property is `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. - - The user interface will only present certificates that are within their validity period and that have Key Encipherment or Key Agreement included in their key usage. - -## .NET Framework Security - The following permissions are required to display the user interface: - -- - + property is `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. + +The user interface will only present certificates that are within their validity period and that have Key Encipherment or Key Agreement included in their key usage. + +The following permissions are required to display the user interface on .NET Framework: + +- + ]]> A cryptographic operation could not be completed. @@ -1001,15 +988,15 @@ Unlike the other overloads of `Decrypt`, this overload does not search certifica Gets a collection that represents the recipients list for a decoded message. The default value is an empty collection. A collection that represents the recipients list for a decoded message. The default value is an empty collection. - objects in the can be done by using their properties. - - The property is not populated as a result of calling the method nor any of the overloaded EnvelopedCms.Encrypt methods. + objects in the can be done by using their properties. + + The property is not populated as a result of calling the method nor any of the overloaded EnvelopedCms.Encrypt methods. The value of this property is replaced with a different collection object during a call to , which then represents the certificates that were read out of the decoded message. - + ]]> @@ -1047,13 +1034,13 @@ Unlike the other overloads of `Decrypt`, this overload does not search certifica Gets the collection of unprotected (unencrypted) attributes associated with the enveloped CMS/PKCS#7 message. The collection of unprotected (unencrypted) attributes associated with the enveloped CMS/PKCS#7 message. - class is being used to to encrypt data, the contents of this collection are embedded into the pending message during the call to one of the methods. Changes after the encryption operation have no effect. The value of this property is replaced with a different collection object during a call to , which then represents the attributes which were attached to the message without being encrypted. - + ]]> @@ -1091,11 +1078,11 @@ Unlike the other overloads of `Decrypt`, this overload does not search certifica Gets the version of the decoded enveloped CMS/PKCS#7 message. The version of the decoded enveloped CMS/PKCS#7 message. - , which then represents the version number contained within the message. - + ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/SignedCms.xml b/xml/System.Security.Cryptography.Pkcs/SignedCms.xml index befcbb48d17..7faf6efb8ac 100644 --- a/xml/System.Security.Cryptography.Pkcs/SignedCms.xml +++ b/xml/System.Security.Cryptography.Pkcs/SignedCms.xml @@ -38,16 +38,16 @@ The class enables signing and verifying of CMS/PKCS #7 messages. - @@ -88,20 +88,20 @@ The constructor creates an instance of the class. - class has the following default property values. - -|Property|Default value| -|--------------|-------------------| -||1.2.840.113549.1.7.1 (data)Length: zero| -||Detached state: `false` The content that is signed is included in the CMS/PKCS #7 message along with the signature information.| - - The default for signers is SubjectIdentifierType.IssuerAndSerialNumber. - - If the detached state is `false` (the default), the signed content is included in the CMS/PKCS #7 message along with the signature information. If the detached state is `true`, clients that cannot decode S/MIME messages can still see the content of the message if it is sent separately. This may be useful in an archiving application that archives message content whether the message sender can be verified for authenticity. - + class has the following default property values. + +|Property|Default value| +|--------------|-------------------| +||1.2.840.113549.1.7.1 (data)Length: zero| +||Detached state: `false` The content that is signed is included in the CMS/PKCS #7 message along with the signature information.| + + The default for signers is SubjectIdentifierType.IssuerAndSerialNumber. + + If the detached state is `false` (the default), the signed content is included in the CMS/PKCS #7 message along with the signature information. If the detached state is `true`, clients that cannot decode S/MIME messages can still see the content of the message if it is sent separately. This may be useful in an archiving application that archives message content whether the message sender can be verified for authenticity. + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -138,13 +138,13 @@ A member that specifies the default subject identifier type for signers. The constructor creates an instance of the class by using the specified subject identifier type as the default subject identifier type for signers. - . - - If the detached state is `false` (the default), the content that is signed is included in the CMS/PKCS #7 message along with the signature information. If the detached state is `true`, clients that cannot decode S/MIME messages can still see the content of the message if it is sent separately. This might be useful in an archiving application that archives message content whether the message sender can be verified for authenticity. - + . + + If the detached state is `false` (the default), the content that is signed is included in the CMS/PKCS #7 message along with the signature information. If the detached state is `true`, clients that cannot decode S/MIME messages can still see the content of the message if it is sent separately. This might be useful in an archiving application that archives message content whether the message sender can be verified for authenticity. + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -188,13 +188,13 @@ A object that specifies the content information as the inner content of the message. The constructor creates an instance of the class by using the specified content information as the inner content. - . - - If the detached state is `false` (the default), the content that is signed is included in the CMS/PKCS #7 message along with the signature information. If the detached state is `true`, clients that cannot decode S/MIME messages can still see the content of the message if it is sent separately. This might be useful in an archiving application that archives message content whether the message sender can be verified for authenticity. - + . + + If the detached state is `false` (the default), the content that is signed is included in the CMS/PKCS #7 message along with the signature information. If the detached state is `true`, clients that cannot decode S/MIME messages can still see the content of the message if it is sent separately. This might be useful in an archiving application that archives message content whether the message sender can be verified for authenticity. + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -240,13 +240,13 @@ A value that specifies whether the object is for a detached signature. If is , the signature is detached. If is , the signature is not detached. The constructor creates an instance of the class by using the specified content information as the inner content and by using the detached state. - . - - If the detached state is `false` (the default), the content that is signed is included in the CMS/PKCS #7 message along with the signature information. If the detached state is `true`, clients that cannot decode S/MIME messages can still see the content of the message if it is sent separately. This might be useful in an archiving application that archives message content whether the message sender can be verified for authenticity. - + . + + If the detached state is `false` (the default), the content that is signed is included in the CMS/PKCS #7 message along with the signature information. If the detached state is `true`, clients that cannot decode S/MIME messages can still see the content of the message if it is sent separately. This might be useful in an archiving application that archives message content whether the message sender can be verified for authenticity. + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -292,13 +292,13 @@ A object that specifies the content information as the inner content of the message. The constructor creates an instance of the class by using the specified subject identifier type as the default subject identifier type for signers and content information as the inner content. - . - - If the detached state is `false` (the default), the content that is signed is included in the CMS/PKCS #7 message along with the signature information. If the detached state is `true`, clients that cannot decode S/MIME messages can still see the content of the message if it is sent separately. This might be useful in an archiving application that archives message content whether the message sender can be verified for authenticity. - + . + + If the detached state is `false` (the default), the content that is signed is included in the CMS/PKCS #7 message along with the signature information. If the detached state is `true`, clients that cannot decode S/MIME messages can still see the content of the message if it is sent separately. This might be useful in an archiving application that archives message content whether the message sender can be verified for authenticity. + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -352,11 +352,11 @@ A value that specifies whether the object is for a detached signature. If is , the signature is detached. If detached is , the signature is not detached. The constructor creates an instance of the class by using the specified subject identifier type as the default subject identifier type for signers, the content information as the inner content, and by using the detached state. - A null reference was passed to a method that does not accept it as a valid argument. @@ -475,11 +475,11 @@ The method verifies the data integrity of the CMS/PKCS #7 message. is a specialized method used in specific security infrastructure applications that only wish to check the hash of the CMS message, rather than perform a full digital signature verification. does not authenticate the author nor sender of the message because this method does not involve verifying a digital signature. For general-purpose checking of the integrity and authenticity of a CMS/PKCS #7 message, use the or methods. - A method call was invalid for the object's current state. @@ -528,31 +528,31 @@ - A value that specifies whether only the digital signatures are verified without the signers' certificates being validated. - + A value that specifies whether only the digital signatures are verified without the signers' certificates being validated. + If is , only the digital signatures are verified. If it is , the digital signatures are verified, the signers' certificates are validated, and the purposes of the certificates are validated. The purposes of a certificate are considered valid if the certificate has no key usage or if the key usage supports digital signatures or nonrepudiation. The method verifies the digital signatures on the signed CMS/PKCS #7 message and, optionally, validates the signers' certificates. - among the steps necessary to verify the signatures on a message. In this example, the message content is not detached. The message content is included in the message. - + among the steps necessary to verify the signatures on a message. In this example, the message content is not detached. The message content is included in the message. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/mpkcs_SignedCMS/cs/Program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet1"::: - - The following example shows the placement of among the steps necessary to verify the signatures on a message. In this example, the message content is detached, so the message content must verified independently of the message. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet1"::: + + The following example shows the placement of among the steps necessary to verify the signatures on a message. In this example, the message content is detached, so the message content must verified independently of the message. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/mpkcs_SignedCMS/cs/Program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet2"::: + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -599,17 +599,17 @@ An object that can be used to validate the certificate chain. If no additional certificates are to be used to validate the certificate chain, use instead of . - A value that specifies whether only the digital signatures are verified without the signers' certificates being validated. - + A value that specifies whether only the digital signatures are verified without the signers' certificates being validated. + If is , only the digital signatures are verified. If it is , the digital signatures are verified, the signers' certificates are validated, and the purposes of the certificates are validated. The purposes of a certificate are considered valid if the certificate has no key usage or if the key usage supports digital signatures or nonrepudiation. The method verifies the digital signatures on the signed CMS/PKCS #7 message by using the specified collection of certificates and, optionally, validates the signers' certificates. - @@ -664,19 +664,16 @@ Creates a signature and adds the signature to the CMS/PKCS #7 message. - was provided as the `signerIdentifierType` argument of one of the constructor overloads. Otherwise, it throws an exception. -## .NET Framework Security - -The following permissions are required to access the signature key: - -- - -- +The following permissions are required to access the signature key on .NET Framework: + +- +- ]]> @@ -718,28 +715,24 @@ The following permissions are required to access the signature key: A object that represents the signer. Creates a signature using the specified signer and adds the signature to the CMS/PKCS #7 message. - - -- - -## Examples - The following example shows the steps to compute a signature on a message with message content that is not detached. In this case, the message content is included in the message. - + +- + +## Examples + The following example shows the steps to compute a signature on a message with message content that is not detached. In this case, the message content is included in the message. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/mpkcs_SignedCMS/cs/Program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet3"::: - - The following example shows the steps to compute a signature on a message with message content that is detached. In this case, the message content must be verified independently of the message. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet3"::: + + The following example shows the steps to compute a signature on a message with message content that is detached. In this case, the message content must be verified independently of the message. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/mpkcs_SignedCMS/cs/Program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet4"::: + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -788,22 +781,20 @@ The following permissions are required to access the signature key: .NET Core and .NET 5+ only: to request opening keys with PIN prompts disabled, where supported; otherwise, . In .NET Framework, this parameter is not used and a PIN prompt is always shown, if required. Creates a signature using the specified signer and adds the signature to the CMS/PKCS #7 message. - value is not null. The provided value controls whether or not computing the signature shows a PIN prompt. Even when the property is null and the `silent` parameter is set to `true`, some combinations of operating system and signer options can still result in a PIN prompt. - -## .NET Framework Security - The following permissions are required to display the user interface: - -- - - The following permissions are required to access the signature key: - -- - -- + +The following permissions are required to display the user interface on .NET Framework: + +- + +The following permissions are required to access the signature key on .NET Framework: + +- +- ]]> @@ -891,24 +882,24 @@ The following permissions are required to access the signature key: An array of byte values that represents the encoded CMS/PKCS#7 message to be decoded. Decodes an encoded message. - method in the process of verifying the signatures on a message. In this example, the message content is not detached, so the message content is included in the message. - + method in the process of verifying the signatures on a message. In this example, the message content is not detached, so the message content is included in the message. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/mpkcs_SignedCMS/cs/Program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet1"::: - - The following example shows the placement of the method in the process of verifying the signatures on a message. In this example, the message content is detached, so the message content must be verified independently of the message. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet1"::: + + The following example shows the placement of the method in the process of verifying the signatures on a message. In this example, the message content is detached, so the message content must be verified independently of the message. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/mpkcs_SignedCMS/cs/Program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/mpkcs_SignedCMS/vb/Program.vb" id="Snippet2"::: + ]]> @@ -1118,15 +1109,15 @@ The following permissions are required to access the signature key: To be added. A CMS/PKCS #7 message is not signed, and is invalid. - is less than zero. - - -or- - + is less than zero. + + -or- + is greater than the signature count minus 1. - The signature could not be removed. - - -or- - + The signature could not be removed. + + -or- + An internal cryptographic error occurred. @@ -1255,11 +1246,11 @@ The following permissions are required to access the signature key: The property retrieves the version of the CMS/PKCS #7 message. An int value that represents the CMS/PKCS #7 message version. - diff --git a/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml b/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml index 8126b6cc253..c3fe57d6dbf 100644 --- a/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml +++ b/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml @@ -38,15 +38,15 @@ The class represents a signer associated with a object that represents a CMS/PKCS #7 message. - class can be either over message content or a signature. The latter kind of signature is referred to as a *countersignature*. - - This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. - - This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property. - + class can be either over message content or a signature. The latter kind of signature is referred to as a *countersignature*. + + This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. + + This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property. + ]]> @@ -88,7 +88,7 @@ The ASN.1 encoded attribute to add to the document. Adds the specified attribute to the current document. - Cannot find the original signer. - + -or- ASN1 corrupted data. @@ -145,11 +145,11 @@ ASN1 corrupted data. The property retrieves the signing certificate associated with the signer information. An object that represents the signing certificate. - property, then the certificate will not be returned. - + property, then the certificate will not be returned. + ]]> @@ -197,11 +197,11 @@ ASN1 corrupted data. The method verifies the data integrity of the CMS/PKCS #7 message signer information. is a specialized method used in specific security infrastructure applications in which the subject uses the **HashOnly** member of the enumeration when setting up a object. does not authenticate the signer information because this method does not involve verifying a digital signature. For general-purpose checking of the integrity and authenticity of CMS/PKCS #7 message signer information and countersignatures, use the or methods. - A cryptographic operation could not be completed. @@ -253,13 +253,13 @@ ASN1 corrupted data. A bool value that specifies whether only the digital signature is verified. If is , only the signature is verified. If is , the digital signature is verified, the certificate chain is validated, and the purposes of the certificates are validated. The purposes of the certificate are considered valid if the certificate has no key usage or if the key usage supports digital signature or nonrepudiation. The method verifies the digital signature of the message and, optionally, validates the certificate. - object to perform custom validation. - + object to perform custom validation. + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -303,13 +303,13 @@ ASN1 corrupted data. A bool value that specifies whether only the digital signature is verified. If is , only the signature is verified. If is , the digital signature is verified, the certificate chain is validated, and the purposes of the certificates are validated. The purposes of the certificate are considered valid if the certificate has no key usage or if the key usage supports digital signature or nonrepudiation. The method verifies the digital signature of the message by using the specified collection of certificates and, optionally, validates the certificate. - object to perform custom validation. - + object to perform custom validation. + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -367,34 +367,31 @@ ASN1 corrupted data. The method prompts the user to select a signing certificate, creates a countersignature, and adds the signature to the CMS/PKCS #7 message. Countersignatures are restricted to one level. - property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. - - Signers whose certificates meet the following conditions will be displayed in the list: - -- The certificate has an associated private key. - -- The certificate is within its validity period. - -- The certificate has no key usage or a key usage that supports digital signatures or nonrepudiation. - - Signer certificates are chosen from the My store. - -## .NET Framework Security - The following permissions are required to display the user interface: - -- - - The following permissions are required to access the signature key: - -- - -- - + property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. + +Signers whose certificates meet the following conditions will be displayed in the list: + +- The certificate has an associated private key. +- The certificate is within its validity period. +- The certificate has no key usage or a key usage that supports digital signatures or nonrepudiation. + +Signer certificates are chosen from the My store. + +The following permissions are required to display the user interface on .NET Framework: + +- + +The following permissions are required to access the signature key on .NET Framework: + +- +- + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -435,18 +432,17 @@ ASN1 corrupted data. A object that represents the counter signer. The method creates a countersignature by using the specified signer and adds the signature to the CMS/PKCS #7 message. Countersignatures are restricted to one level. - - -- - + +- + ]]> A null reference was passed to a method that does not accept it as a valid argument. @@ -484,11 +480,11 @@ ASN1 corrupted data. The property retrieves the set of counter signers associated with the signer information. A collection that represents the counter signers for the signer information. If there are no counter signers, the property is an empty collection. - @@ -711,7 +707,7 @@ ASN1 corrupted data. The ASN.1 encoded attribute to remove from the document. Removes the specified attribute from the current document. - @@ -797,15 +793,15 @@ ASN1 corrupted data. The property retrieves the collection of signed attributes that is associated with the signer information. Signed attributes are signed along with the rest of the message content. A collection that represents the signed attributes. If there are no signed attributes, the property is an empty collection. - collection retrieved by the property is the signing time attribute. - - Signed attributes are signed along with the rest of the message content. This means that a party that successfully verifies the signature can have confidence that the contents of these attributes are authentic and have not been altered. - - A object and a object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. - + collection retrieved by the property is the signing time attribute. + + Signed attributes are signed along with the rest of the message content. This means that a party that successfully verifies the signature can have confidence that the contents of these attributes are authentic and have not been altered. + + A object and a object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. + ]]> @@ -899,13 +895,13 @@ ASN1 corrupted data. The property retrieves the collection of unsigned attributes that is associated with the content. Unsigned attributes can be modified without invalidating the signature. A collection that represents the unsigned attributes. If there are no unsigned attributes, the property is an empty collection. - message content. Even though a party successfully verifies the signature, the unsigned attributes may have been altered and should not be considered to have authenticity or integrity. - - An example of an unsigned attribute that might be included in the collection retrieved by the property is a countersignature. - + message content. Even though a party successfully verifies the signature, the unsigned attributes may have been altered and should not be considered to have authenticity or integrity. + + An example of an unsigned attribute that might be included in the collection retrieved by the property is a countersignature. + ]]> @@ -947,11 +943,11 @@ ASN1 corrupted data. The property retrieves the signer information version. An int value that specifies the signer information version. - diff --git a/xml/System.Security.Cryptography/AsnEncodedData.xml b/xml/System.Security.Cryptography/AsnEncodedData.xml index 5ecb45a2de3..b159b2ad4c8 100644 --- a/xml/System.Security.Cryptography/AsnEncodedData.xml +++ b/xml/System.Security.Cryptography/AsnEncodedData.xml @@ -55,22 +55,22 @@ Represents Abstract Syntax Notation One (ASN.1)-encoded data. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.AsnEncodedData/CPP/asnencodeddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: + ]]> @@ -127,15 +127,15 @@ Initializes a new instance of the class. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.AsnEncodedData/CPP/asnencodeddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: + ]]> @@ -258,20 +258,20 @@ An instance of the class. Initializes a new instance of the class using an instance of the class. - instance. - - - -## Examples - The following code example shows how to use the class. - + instance. + + + +## Examples + The following code example shows how to use the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.AsnEncodedData/CPP/asnencodeddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: + ]]> @@ -328,15 +328,15 @@ A byte array that contains Abstract Syntax Notation One (ASN.1)-encoded data. Initializes a new instance of the class using an object and a byte array. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.AsnEncodedData/CPP/asnencodeddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: + ]]> @@ -428,15 +428,15 @@ A byte array that contains Abstract Syntax Notation One (ASN.1)-encoded data. Initializes a new instance of the class using a byte array. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.AsnEncodedData/CPP/asnencodeddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: + ]]> @@ -529,20 +529,20 @@ The object to base the new object on. Copies information from an object. - object based on the specified object. - - - -## Examples - The following code example shows how to use the class. - + object based on the specified object. + + + +## Examples + The following code example shows how to use the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.AsnEncodedData/CPP/asnencodeddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: + ]]> @@ -594,29 +594,28 @@ Returns a formatted version of the Abstract Syntax Notation One (ASN.1)-encoded data as a string. A formatted string that represents the Abstract Syntax Notation One (ASN.1)-encoded data. - class. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.AsnEncodedData/CPP/asnencodeddata.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: - - ]]> + + + class. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.AsnEncodedData/CPP/asnencodeddata.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: + ]]> + @@ -678,20 +677,20 @@ Gets or sets the value for an object. An object. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.AsnEncodedData/CPP/asnencodeddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: + ]]> @@ -742,20 +741,20 @@ Gets or sets the Abstract Syntax Notation One (ASN.1)-encoded data represented in a byte array. A byte array that represents the Abstract Syntax Notation One (ASN.1)-encoded data. - object. - - - -## Examples - The following code example shows how to use the class. - + object. + + + +## Examples + The following code example shows how to use the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.AsnEncodedData/CPP/asnencodeddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.AsnEncodedData/VB/asnencodeddata.vb" id="Snippet1"::: + ]]> The value is . diff --git a/xml/System.Security.Permissions/WebBrowserPermission.xml b/xml/System.Security.Permissions/WebBrowserPermission.xml index 1a7beb905ab..f5644655ce1 100644 --- a/xml/System.Security.Permissions/WebBrowserPermission.xml +++ b/xml/System.Security.Permissions/WebBrowserPermission.xml @@ -55,7 +55,8 @@ In Windows Presentation Foundation (WPF), the Web browser control enables frames to navigate HTML. This permission uses the values of the enumerations. This class is not typically used in XAML. - ]]> + ]]> + @@ -217,17 +218,7 @@ This class is not typically used in XAML. Creates and returns an identical copy of the current permission. A copy of the current permission. - - - + A copy of a permission represents the same access to resources as the original permission. Members of this class are either not typically used in XAML, or cannot be used in XAML. @@ -264,10 +255,7 @@ This class is not typically used in XAML. @@ -308,10 +296,7 @@ This class is not typically used in XAML. @@ -354,12 +339,12 @@ This class is not typically used in XAML. @@ -402,12 +387,10 @@ This class is not typically used in XAML. method. @@ -456,12 +439,7 @@ This class is not typically used in XAML. value for the . @@ -505,10 +483,7 @@ This class is not typically used in XAML. @@ -549,10 +524,7 @@ This class is not typically used in XAML. diff --git a/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml b/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml index 4a9dd7faa9c..85c1f4b60a3 100644 --- a/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml +++ b/xml/System.Security.Permissions/WebBrowserPermissionAttribute.xml @@ -59,7 +59,8 @@ The following example shows how to demand that the calling code has unrestricted :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermissionattribute3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermissionattribute3"::: - ]]> + ]]> + Extending Metadata Using Attributes @@ -97,25 +98,15 @@ The following example shows how to demand that the calling code has unrestricted One of the values. Initializes a new instance of the class with the specified . - + Members of this class are either not typically used in XAML, or cannot be used in XAML. + . -## Remarks - The default value of the property is . - -## XAML Attribute Usage - Members of this class are either not typically used in XAML, or cannot be used in XAML. - - - -## Examples - The following example shows how to define a . - - :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermissionattribute4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermissionattribute4"::: - - ]]> - +:::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/WebBrowserPermission/.ctor/Window1.xaml.cs" id="Snippetwebbrowserpermissionattribute4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/WebBrowserPermissionsSnippets/visualbasic/window1.xaml.vb" id="Snippetwebbrowserpermissionattribute4"::: + ]]> + @@ -151,12 +142,12 @@ The following example shows how to demand that the calling code has unrestricted method is called by the security system, not by application code. - The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses the information at run time. The system uses the returned by to convert the security information of the attribute target to a serializable form stored in metadata. +The method is called by the security system, not by application code. + +The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses the information at run time. The system uses the returned by to convert the security information of the attribute target to a serializable form stored in metadata. -## XAML Attribute Usage - Members of this class are either not typically used in XAML, or cannot be used in XAML. +Members of this class are either not typically used in XAML, or cannot be used in XAML. ]]> @@ -195,17 +186,11 @@ The following example shows how to demand that the calling code has unrestricted Gets or sets the current Web browser permission level for the . - The state of the current Web browser permission level. + The state of the current Web browser permission level. The default is . . - -## XAML Attribute Usage - Members of this class are either not typically used in XAML, or cannot be used in XAML. - - +Members of this class are either not typically used in XAML, or cannot be used in XAML. ## Examples The following example shows how to demand that the calling code has permission to create a Web browser control that runs at a safe level. diff --git a/xml/System.Security.RightsManagement/UnsignedPublishLicense.xml b/xml/System.Security.RightsManagement/UnsignedPublishLicense.xml index d0c1e709f2f..f8e63600862 100644 --- a/xml/System.Security.RightsManagement/UnsignedPublishLicense.xml +++ b/xml/System.Security.RightsManagement/UnsignedPublishLicense.xml @@ -27,21 +27,17 @@ Represents an unsigned rights managed or an unsigned template. - defines security data about rights, users, and other security-related information. The license defines how a specific user on a specific computer can use specified rights-managed content. - - The publishing process begins with the document author, who defines rights information in an . Next, the authoring application calls the . method to create a signed . The signed can then be provided to the end-user client application which can call to request an end-user . The returned then allows the client application to exercise the rights that are granted to the user. - - The document author can use the class either to create a signed , or to build and serialize a template. - - As with other types, is only usable in full trust applications. - - -## XAML Text Usage - This type is not typically used in XAML. - + defines security data about rights, users, and other security-related information. The license defines how a specific user on a specific computer can use specified rights-managed content. + + The publishing process begins with the document author, who defines rights information in an . Next, the authoring application calls the . method to create a signed . The signed can then be provided to the end-user client application which can call to request an end-user . The returned then allows the client application to exercise the rights that are granted to the user. + + The document author can use the class either to create a signed , or to build and serialize a template. + + As with other types, is only usable in full trust applications. + ]]> @@ -75,11 +71,11 @@ Initializes a new instance of the class. - creates an empty and unsigned publish-license. - + creates an empty and unsigned publish-license. + ]]> @@ -108,22 +104,22 @@ The Extensible Rights Markup Language (XrML) publish-license template to use to create this license. Initializes a new instance of the class from a specified XrML publish-license template. - ` or `` elements are ignored when the is created by the (String) constructor. To specify these values for the publish license, the properties for and must be explicitly set. The following example shows how to explicitly set the and properties. - + ` or `` elements are ignored when the is created by the (String) constructor. To specify these values for the publish license, the properties for and must be explicitly set. The following example shows how to explicitly set the and properties. + :::code language="csharp" source="~/snippets/csharp/System.Security.RightsManagement/UnsignedPublishLicense/.ctor/Window1.xaml.cs" id="Snippetrmpkgpubgrants"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/UnsignedPubLicense_snip/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubgrants"::: - - - -## Examples - The following example shows how to use this constructor. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/UnsignedPubLicense_snip/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubgrants"::: + + + +## Examples + The following example shows how to use this constructor. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubunpublic"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubunpublic"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubunpublic"::: + ]]> @@ -152,11 +148,11 @@ Gets or sets the publisher-created content identifier. The publisher-created rights-managed content identifier. - to identify rights-managed content in a and a . - + to identify rights-managed content in a and a . + ]]> @@ -237,21 +233,21 @@ Gets or sets the content owner. The user who owns the published content. - specifies the user who owns the . - - is also associated with the Owner node in the issuance license Extensible Rights Markup Language (XrML). - - - -## Examples - The following example shows how to use this property to assign a . - + specifies the user who owns the . + + is also associated with the Owner node in the issuance license Extensible Rights Markup Language (XrML). + + + +## Examples + The following example shows how to use this property to assign a . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubunpublic"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubunpublic"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubunpublic"::: + ]]> @@ -281,17 +277,7 @@ Gets or sets the contact name for the author or publisher of the content. The contact name for the author or publisher of the content. - - -## XAML Text Usage - Members of this type are not typically used in XAML. - - ]]> - + To be added. @@ -319,17 +305,7 @@ Gets or sets the contact URI for the author or publisher of the content. The contact uniform resource identifier (URI) for the author or publisher of the content. - - -## XAML Text Usage - Members of this type are not typically used in XAML. - - ]]> - + To be added. @@ -364,14 +340,14 @@ Creates a signed and returns a for the document author. The signed that is created by signing this . - . - + . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/RightsManagedPackagePublish/visualbasic/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> diff --git a/xml/System.Text.RegularExpressions/Regex.xml b/xml/System.Text.RegularExpressions/Regex.xml index 1aa2866ac9e..b43ce408b96 100644 --- a/xml/System.Text.RegularExpressions/Regex.xml +++ b/xml/System.Text.RegularExpressions/Regex.xml @@ -3509,51 +3509,7 @@ For more details about `startat`, see the Remarks section of The zero-based character position at which to start the search. Searches the input string for the first occurrence of a regular expression, beginning at the specified starting position in the string. An object that contains information about the match. - - method returns the first substring that matches a regular expression pattern, starting at or after the `startat` character position, in an input string. The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](/dotnet/standard/base-types/regular-expression-language-quick-reference). - -### The `startat` parameter - - You can optionally specify a starting position in the string by using the `startat` parameter. Any matches starting before `startat` in the string are ignored. If you don't specify a starting position, the search begins at the default position, which is the left end of `input` in a left-to-right search, and the right end of `input` in a right-to-left search. Despite starting at `startat`, the index of any returned match is relative to the start of the string. - - Although the regular expression engine doesn't return any match starting before `startat`, it doesn't ignore the string before `startat`. This means that assertions such as [anchors](/dotnet/standard/base-types/anchors-in-regular-expressions) or [lookbehind assertions](/dotnet/standard/base-types/backtracking-in-regular-expressions#lookbehind-assertions) still apply to the input as a whole. For example, the following code includes a pattern with a lookbehind assertion that's satisfied even though it occurs before the `startat` index of 5 in the input string. - -:::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Regex/Match/startat.cs" interactive="try-dotnet"::: - -> [!TIP] -> -> - If a pattern starts with the `^` anchor but `startat` is greater than 0, no matches will ever be found in a single-line search since they are constrained by `^` to start at index 0. -> - The [`\G` anchor](/dotnet/standard/base-types/anchors-in-regular-expressions#contiguous-matches-g) is satisfied at `startat`. Because of this, if you want to restrict a match so that it begins exactly at a particular character position in the string, anchor the regular expression with a `\G` on the left for a left-to-right pattern. This restricts the match so it must start exactly at `startat` (or, when multiple matches are desired, so the matches are contiguous). - -### Right-to-left searches - -A right-to-left search, that is, when the regular expression pattern is constructed with the option, behaves in the following ways: - -- The scan moves in the opposite direction and the pattern is matched from back (right) to front (left). -- The default starting position is the right end of the input string. -- If `startat` is specified, the right-to-left scan begins at the character at `startat` - 1 (not `startat`). -- When the `\G` anchor is specified at the right end of a pattern, it restricts the (first) match to end exactly at `startat` - 1. - -For more information about right-to-left searches, see [Right-to-left mode](/dotnet/standard/base-types/regular-expression-options#right-to-left-mode). - -### Determine whether a match is found - - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - -### First or multiple matches - - This method returns the first substring found at or after the `startat` character position in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. - -### Time-out exceptions - - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. - - ]]> - + For more information about this API, see Supplemental API remarks for Regex.Match. is . diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index 6fd05e4501b..8adf49b092c 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -970,24 +970,7 @@ The returned 's and Gets the default encoding for this .NET implementation. The default encoding for this .NET implementation. - - [!WARNING] -> Different computers can use different encodings as the default, and the default encoding can change on a single computer. If you use the encoding to encode and decode data streamed between computers or retrieved at different times on the same computer, it may translate that data incorrectly. In addition, the encoding returned by the property uses best-fit fallback to map unsupported characters to characters supported by the code page. For these reasons, using the default encoding is not recommended. To ensure that encoded bytes are decoded properly, you should use a Unicode encoding, such as or . You could also use a higher-level protocol to ensure that the same format is used for encoding and decoding. - -### The Default property in .NET Framework - -In .NET Framework, the property always gets the system's active code page and creates a object that corresponds to it. The active code page may be an ANSI code page, which includes the ASCII character set along with additional characters that vary by code page. Because all encodings based on ANSI code pages lose data, consider using the encoding instead. UTF-8 is often identical in the U+00 to U+7F range, but can encode characters outside the ASCII range without loss. - -## The Default property on .NET Core - -On .NET Core, the property always returns the . UTF-8 is supported on all the operating systems (Windows, Linux, and macOS) on which .NET Core applications run. - - ]]> - + For more information about this API, see Supplemental API remarks for Encoding.Default. diff --git a/xml/System.Text/EncodingProvider.xml b/xml/System.Text/EncodingProvider.xml index 35970a8e887..3aea6b60f2f 100644 --- a/xml/System.Text/EncodingProvider.xml +++ b/xml/System.Text/EncodingProvider.xml @@ -201,20 +201,10 @@ The encoding that is associated with the specified code page, or if this cannot return a valid encoding that corresponds to . ) method to return the encoding or encodings supported by your subclass. When user code attempts to retrieve an encoding by calling the [GetEncoding(Int32)]() method, the method passes the `codepage` identifier to every registered encoding provider until one returns a valid encoding. If none returns a valid encoding, the [GetEncoding(Int32)]() method attempts to retrieve a cached encoding whose code page identifier is `codepage`. Because of this, if `codepage` is not the code page identifier of an encoding that you support, the method should return `null`; it should never throw an exception. - -Note that you can also choose to return a default code page if the value of the `codepage` argument is 0. - ## Notes to callers This method is called by the [Encoding.GetEncoding(Int32)]() method. You should not call it directly from user code. - - ]]> + ]]> You override the method to return the encoding or encodings supported by your subclass. When user code attempts to retrieve an encoding by calling the method, the method passes the identifier to every registered encoding provider until one returns a valid encoding. If none returns a valid encoding, the method attempts to retrieve a cached encoding whose code page identifier is . Because of this, if is not the code page identifier of an encoding that you support, the method should return ; it should never throw an exception. @@ -342,11 +332,11 @@ This method is called by the [Encoding.GetEncoding(String)](, or the `decoderExceptionFallback` argument is an instance of , the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded. +- Exception fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded. -- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. +- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. -- Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. +- Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. ]]> @@ -412,11 +402,11 @@ This method is called by the [Encoding.GetEncoding(String)](, or the `decoderExceptionFallback` argument is an instance of , the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded. +- Exception fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded. -- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. +- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. -- Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. +- Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. ]]> diff --git a/xml/System.Text/StringBuilder.xml b/xml/System.Text/StringBuilder.xml index 05bdda3efb5..4f96c2ebf99 100644 --- a/xml/System.Text/StringBuilder.xml +++ b/xml/System.Text/StringBuilder.xml @@ -4447,21 +4447,16 @@ The following example shows how to call many of the methods defined by the The Unicode character at position . . The first character in the string is at index 0. The length of a string is the number of characters it contains. The last accessible character of a instance is at index - 1. -## Remarks - The `index` parameter is the position of a character within the . The first character in the string is at index 0. The length of a string is the number of characters it contains. The last accessible character of a instance is at index - 1. - - is the default property of the class. In C#, it is an indexer. This means that individual characters can be retrieved from the property as shown in the following example, which counts the number of alphabetic, white-space, and punctuation characters in a string. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Chars/chars1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Chars/chars1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.chars/vb/chars1.vb" id="Snippet1"::: + is the default property of the class. In C#, it is an indexer. This means that individual characters can be retrieved from the property as shown in the following example, which counts the number of alphabetic, white-space, and punctuation characters in a string. -### Performance and character-based indexing +:::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Chars/chars1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Chars/chars1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.chars/vb/chars1.vb" id="Snippet1"::: [!INCLUDE[stringbuilder-performance-note](~/includes/stringbuilder-perf-note.md)] - - ]]> + ]]> is outside the bounds of this instance while setting a character. diff --git a/xml/System.Threading/Monitor.xml b/xml/System.Threading/Monitor.xml index a4f46bae80e..99ce2653a57 100644 --- a/xml/System.Threading/Monitor.xml +++ b/xml/System.Threading/Monitor.xml @@ -1343,39 +1343,7 @@ Releases the lock on an object and blocks the current thread until it reacquires the lock. If the specified time-out interval elapses, the thread enters the ready queue. This method also specifies whether the synchronization domain for the context (if in a synchronized context) is exited before the wait and reacquired afterward. if the lock was reacquired before the specified time elapsed; if the lock was reacquired after the specified time elapsed. The method does not return until the lock is reacquired. - - or method. It also moves the thread to the ready queue, bypassing other threads ahead of it in the wait queue, so that it can reacquire the lock sooner. The thread can test the return value of the method to determine whether it reacquired the lock prior to the time-out. The thread can evaluate the conditions that caused it to enter the wait, and if necessary call the method again. - - When a thread calls `Wait`, it releases the lock and enters the waiting queue. At this point, the next thread in the ready queue (if there is one) is allowed to take control of the lock. The thread that invoked `Wait` remains in the waiting queue until either a thread that holds the lock invokes , or it is the next in the queue and a thread that holds the lock invokes . However, if `millisecondsTimeout` elapses before another thread invokes this object's or method, the original thread is moved to the ready queue in order to regain the lock. - -> [!NOTE] -> If is specified for the `millisecondsTimeout` parameter, this method blocks indefinitely unless the holder of the lock calls or . If `millisecondsTimeout` equals 0, the thread that calls `Wait` releases the lock and then immediately enters the ready queue in order to regain the lock. - - The caller executes `Wait` once, regardless of the number of times has been invoked for the specified object. Conceptually, the `Wait` method stores the number of times the caller invoked on the object and invokes as many times as necessary to fully release the locked object. The caller then blocks while waiting to reacquire the object. When the caller reacquires the lock, the system calls as many times as necessary to restore the saved count for the caller. Calling `Wait` releases the lock for the specified object only; if the caller is the owner of locks on other objects, these locks are not released. - -> [!NOTE] -> A synchronized object holds several references, including a reference to the thread that currently holds the lock, a reference to the ready queue, which contains the threads that are ready to obtain the lock, and a reference to the waiting queue, which contains the threads that are waiting for notification of a change in the object's state. - - The , , and `Wait` methods must be invoked from within a synchronized block of code. - - The remarks for the method explain what happens if is called when no threads are waiting. - -## Notes on Exiting the Context - The`exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that is not derived from , like , you can be in a nondefault context if a is on your stack in the current application domain. - - When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing the method. It returns to the original nondefault context after the call to the method completes. - - This can be useful when the context-bound class has the attribute applied. In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls the method and specifies `true` for `exitContext`, the thread exits the synchronization domain, allowing a thread that is blocked on a call to any member of the object to proceed. When the method returns, the thread that made the call must wait to reenter the synchronization domain. - - ]]> - + For more information about this API, see Supplemental API remarks for Monitor.Wait. The parameter is . is not invoked from within a synchronized block of code. @@ -1438,39 +1406,7 @@ Releases the lock on an object and blocks the current thread until it reacquires the lock. If the specified time-out interval elapses, the thread enters the ready queue. Optionally exits the synchronization domain for the synchronized context before the wait and reacquires the domain afterward. if the lock was reacquired before the specified time elapsed; if the lock was reacquired after the specified time elapsed. The method does not return until the lock is reacquired. - - or method. It also moves the thread to the ready queue, bypassing other threads ahead of it in the wait queue, so that it can reacquire the lock sooner. The thread can test the return value of the method to determine whether it reacquired the lock prior to the time-out. The thread can evaluate the conditions that caused it to enter the wait, and if necessary call the method again. - - When a thread calls `Wait`, it releases the lock and enters the waiting queue. At this point, the next thread in the ready queue (if there is one) is allowed to take control of the lock. The thread that invoked `Wait` remains in the waiting queue until either a thread that holds the lock invokes , or it is the next in the queue and a thread that holds the lock invokes . However, if `timeout` milliseconds elapse before another thread invokes this object's or method, the original thread is moved to the ready queue in order to regain the lock. - -> [!NOTE] -> If a representing -1 millisecond is specified for the `timeout` parameter, this method blocks indefinitely unless the holder of the lock calls or . If `timeout` is 0 milliseconds, the thread that calls `Wait` releases the lock and then immediately enters the ready queue in order to regain the lock. - - The caller executes `Wait` once, regardless of the number of times has been invoked for the specified object. Conceptually, the `Wait` method stores the number of times the caller invoked on the object and invokes as many times as necessary to fully release the locked object. The caller then blocks while waiting to reacquire the object. When the caller reacquires the lock, the system calls as many times as necessary to restore the saved count for the caller. Calling `Wait` releases the lock for the specified object only; if the caller is the owner of locks on other objects, these locks are not released. - -> [!NOTE] -> A synchronized object holds several references, including a reference to the thread that currently holds the lock, a reference to the ready queue, which contains the threads that are ready to obtain the lock, and a reference to the waiting queue, which contains the threads that are waiting for notification of a change in the object's state. - - The , , and `Wait` methods must be invoked from within a synchronized block of code. - - The remarks for the method explain what happens if is called when no threads are waiting. - -## Notes on Exiting the Context - The`exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that is not derived from , like , you can be in a nondefault context if a is on your stack in the current application domain. - - When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing the method. It returns to the original nondefault context after the call to the method completes. - - This can be useful when the context-bound class has the attribute applied. In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls the method and specifies `true` for `exitContext`, the thread exits the synchronization domain, allowing a thread that is blocked on a call to any member of the object to proceed. When the method returns, the thread that made the call must wait to reenter the synchronization domain. - - ]]> - + For more information about this API, see Supplemental API remarks for Monitor.Wait. The parameter is . is not invoked from within a synchronized block of code. diff --git a/xml/System.Threading/ThreadPool.xml b/xml/System.Threading/ThreadPool.xml index e479d1aeee0..265dba29902 100644 --- a/xml/System.Threading/ThreadPool.xml +++ b/xml/System.Threading/ThreadPool.xml @@ -55,65 +55,65 @@ Provides a pool of threads that can be used to execute tasks, post work items, process asynchronous I/O, wait on behalf of other threads, and process timers. - or object to perform some task asynchronously, by default the task is scheduled to run on a thread pool thread. - -- Asynchronous timers use the thread pool. Thread pool threads execute callbacks from the class and raise events from the class. - -- When you use registered wait handles, a system thread monitors the status of the wait handles. When a wait operation completes, a worker thread from the thread pool executes the corresponding callback function. - -- When you call the method to queue a method for execution on a thread pool thread. You do this by passing the method a delegate. The delegate has the signature - - ```csharp - void WaitCallback(Object state) - ``` - - ```vb - Sub WaitCallback(state As Object) - ``` - - where `state` is an object that contains data to be used by the delegate. The actual data can be passed to the delegate by calling the method. - + or object to perform some task asynchronously, by default the task is scheduled to run on a thread pool thread. + +- Asynchronous timers use the thread pool. Thread pool threads execute callbacks from the class and raise events from the class. + +- When you use registered wait handles, a system thread monitors the status of the wait handles. When a wait operation completes, a worker thread from the thread pool executes the corresponding callback function. + +- When you call the method to queue a method for execution on a thread pool thread. You do this by passing the method a delegate. The delegate has the signature + + ```csharp + void WaitCallback(Object state) + ``` + + ```vb + Sub WaitCallback(state As Object) + ``` + + where `state` is an object that contains data to be used by the delegate. The actual data can be passed to the delegate by calling the method. + > [!NOTE] -> The threads in the managed thread pool are background threads. That is, their properties are `true`. This means that a thread will not keep an application running after all foreground threads have exited. - +> The threads in the managed thread pool are background threads. That is, their properties are `true`. This means that a thread will not keep an application running after all foreground threads have exited. + > [!IMPORTANT] -> When the thread pool reuses a thread, it does not clear the data in thread local storage or in fields that are marked with the attribute. Therefore, when a method examines thread local storage or fields that are marked with the attribute, the values it finds might be left over from an earlier use of the thread pool thread. - - You can also queue work items that are not related to a wait operation to the thread pool. To request that a work item be handled by a thread in the thread pool, call the method. This method takes as a parameter a reference to the method or delegate that will be called by the thread selected from the thread pool. There is no way to cancel a work item after it has been queued. - - Timer-queue timers and registered wait operations also use the thread pool. Their callback functions are queued to the thread pool. - - There is one thread pool per process. Beginning with the .NET Framework 4, the default size of the thread pool for a process depends on several factors, such as the size of the virtual address space. A process can call the method to determine the number of threads. The number of threads in the thread pool can be changed by using the method. Each thread uses the default stack size and runs at the default priority. - +> When the thread pool reuses a thread, it does not clear the data in thread local storage or in fields that are marked with the attribute. Therefore, when a method examines thread local storage or fields that are marked with the attribute, the values it finds might be left over from an earlier use of the thread pool thread. + + You can also queue work items that are not related to a wait operation to the thread pool. To request that a work item be handled by a thread in the thread pool, call the method. This method takes as a parameter a reference to the method or delegate that will be called by the thread selected from the thread pool. There is no way to cancel a work item after it has been queued. + + Timer-queue timers and registered wait operations also use the thread pool. Their callback functions are queued to the thread pool. + + There is one thread pool per process. Beginning with the .NET Framework 4, the default size of the thread pool for a process depends on several factors, such as the size of the virtual address space. A process can call the method to determine the number of threads. The number of threads in the thread pool can be changed by using the method. Each thread uses the default stack size and runs at the default priority. + > [!NOTE] -> Unmanaged code that hosts the .NET Framework can change the size of the thread pool by using the `CorSetMaxThreads` function, defined in the mscoree.h file. - - The thread pool provides new worker threads or I/O completion threads on demand until it reaches the maximum for each category. When a maximum is reached, the thread pool can create additional threads in that category or wait until some tasks complete. Beginning with the .NET Framework 4, the thread pool creates and destroys worker threads in order to optimize throughput, which is defined as the number of tasks that complete per unit of time. Too few threads might not make optimal use of available resources, whereas too many threads could increase resource contention. - +> Unmanaged code that hosts the .NET Framework can change the size of the thread pool by using the `CorSetMaxThreads` function, defined in the mscoree.h file. + + The thread pool provides new worker threads or I/O completion threads on demand until it reaches the maximum for each category. When a maximum is reached, the thread pool can create additional threads in that category or wait until some tasks complete. Beginning with the .NET Framework 4, the thread pool creates and destroys worker threads in order to optimize throughput, which is defined as the number of tasks that complete per unit of time. Too few threads might not make optimal use of available resources, whereas too many threads could increase resource contention. + > [!NOTE] -> When demand is low, the actual number of thread pool threads can fall below the minimum values. - - You can use the method to obtain these minimum values. - +> When demand is low, the actual number of thread pool threads can fall below the minimum values. + + You can use the method to obtain these minimum values. + > [!CAUTION] -> You can use the method to increase the minimum number of threads. However, unnecessarily increasing these values can cause performance problems. If too many tasks start at the same time, all of them might appear to be slow. In most cases the thread pool will perform better with its own algorithm for allocating threads. - - - -## Examples - In the following example, the main application thread queues a method named `ThreadProc` to execute on a thread pool thread, sleeps for one second, and then exits. The `ThreadProc` method simply displays a message. - +> You can use the method to increase the minimum number of threads. However, unnecessarily increasing these values can cause performance problems. If too many tasks start at the same time, all of them might appear to be slow. In most cases the thread pool will perform better with its own algorithm for allocating threads. + + + +## Examples + In the following example, the main application thread queues a method named `ThreadProc` to execute on a thread pool thread, sleeps for one second, and then exits. The `ThreadProc` method simply displays a message. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/VB/source.vb" id="Snippet1"::: - - If you comment out the call to the method, the main thread exits before method runs on the thread pool thread. The thread pool uses background threads, which do not keep the application running if all foreground threads have terminated. (This is a simple example of a race condition.) - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/VB/source.vb" id="Snippet1"::: + + If you comment out the call to the method, the main thread exits before method runs on the thread pool thread. The thread pool uses background threads, which do not keep the application running if all foreground threads have terminated. (This is a simple example of a race condition.) + ]]> This type is thread safe. @@ -191,9 +191,9 @@ if the handle is bound; otherwise, . - class. ]]> @@ -257,13 +257,13 @@ if the handle is bound; otherwise, . - class. - The `osHandle` parameter should be a , which derives from the abstract class. - + The `osHandle` parameter should be a , which derives from the abstract class. + ]]> @@ -353,21 +353,21 @@ If a thread pool implementation may have different types of work items, the coun The number of available asynchronous I/O threads. Retrieves the difference between the maximum number of thread pool threads returned by the method, and the number currently active. - returns, the variable specified by `workerThreads` contains the number of additional worker threads that can be started, and the variable specified by `completionPortThreads` contains the number of additional asynchronous I/O threads that can be started. - - If there are no available threads, additional thread pool requests remain queued until thread pool threads become available. - - - -## Examples - The following example displays the number of worker threads and I/O threads available when a simple app is started. - + returns, the variable specified by `workerThreads` contains the number of additional worker threads that can be started, and the variable specified by `completionPortThreads` contains the number of additional asynchronous I/O threads that can be started. + + If there are no available threads, additional thread pool requests remain queued until thread pool threads become available. + + + +## Examples + The following example displays the number of worker threads and I/O threads available when a simple app is started. + :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/GetAvailableThreads/Example2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetAvailableThreads/VB/Example2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetAvailableThreads/VB/Example2.vb" id="Snippet2"::: + ]]> @@ -424,26 +424,26 @@ If a thread pool implementation may have different types of work items, the coun The maximum number of asynchronous I/O threads in the thread pool. Retrieves the number of requests to the thread pool that can be active concurrently. All requests above that number remain queued until thread pool threads become available. - returns, the variable specified by `workerThreads` contains the maximum number of worker threads allowed in the thread pool, and the variable specified by `completionPortThreads` contains the maximum number of asynchronous I/O threads allowed in the thread pool. - - You can use the method to determine the actual number of threads in the thread pool at any given time. - - You can use the to set the maximum number of worker threads and asynchronous I/O threads in the thread pool. - - You can queue as many thread pool requests as system memory allows. If there are more requests than thread pool threads, the additional requests remain queued until thread pool threads become available. - - - -## Examples - The following code example shows how to retrieve a count of the maximum and available number of threads in the thread pool. A work item is queued that uses `FileStream` to asynchronously write to two files. The callback methods are timed to overlap. A worker thread handles the work item and, depending on the speed and number of processors on the computer, one or two completion port threads handle the write operations. - + returns, the variable specified by `workerThreads` contains the maximum number of worker threads allowed in the thread pool, and the variable specified by `completionPortThreads` contains the maximum number of asynchronous I/O threads allowed in the thread pool. + + You can use the method to determine the actual number of threads in the thread pool at any given time. + + You can use the to set the maximum number of worker threads and asynchronous I/O threads in the thread pool. + + You can queue as many thread pool requests as system memory allows. If there are more requests than thread pool threads, the additional requests remain queued until thread pool threads become available. + + + +## Examples + The following code example shows how to retrieve a count of the maximum and available number of threads in the thread pool. A work item is queued that uses `FileStream` to asynchronously write to two files. The callback methods are timed to overlap. A worker thread handles the work item and, depending on the speed and number of processors on the computer, one or two completion port threads handle the write operations. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetAvailableThreads/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/GetAvailableThreads/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetAvailableThreads/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetAvailableThreads/VB/source.vb" id="Snippet1"::: + ]]> @@ -500,23 +500,23 @@ If a thread pool implementation may have different types of work items, the coun When this method returns, contains the minimum number of asynchronous I/O threads that the thread pool creates on demand. Retrieves the minimum number of threads the thread pool creates on demand, as new requests are made, before switching to an algorithm for managing thread creation and destruction. - [!NOTE] -> When demand is low, the actual number of thread pool threads can fall below the minimum values. - - - -## Examples - The following example sets the minimum number of worker threads to four, and preserves the original value for the minimum number of asynchronous I/O completion threads. - +> When demand is low, the actual number of thread pool threads can fall below the minimum values. + + + +## Examples + The following example sets the minimum number of worker threads to four, and preserves the original value for the minimum number of asynchronous I/O completion threads. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetSetMinThreads/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/GetMinThreads/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetSetMinThreads/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetSetMinThreads/VB/source.vb" id="Snippet1"::: + ]]> @@ -618,28 +618,24 @@ If a thread pool implementation may have different types of work items, the coun if the method is successfully queued; is thrown if the work item could not be queued. - overload that accepts an object containing the necessary data. - + overload that accepts an object containing the necessary data. + > [!NOTE] -> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. - -## Version Information - In the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. - - - -## Examples - The following example uses the method overload to queue a task, which is represented by the `ThreadProc` method, to execute when a thread becomes available. No task information is supplied with this overload. Therefore, the information that is available to the `ThreadProc` method is limited to the object the method belongs to. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/VB/source.vb" id="Snippet1"::: - - ]]> +> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. + +The property value is propagated to worker threads queued using the method. + ]]> + + method overload to queue a task, which is represented by the `ThreadProc` method, to execute when a thread becomes available. No task information is supplied with this overload. Therefore, the information that is available to the `ThreadProc` method is limited to the object the method belongs to. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/Overview/source.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/VB/source.vb" id="Snippet1"::: + ]]> + is . The common language runtime (CLR) is hosted, and the host does not support this action. @@ -705,28 +701,23 @@ If a thread pool implementation may have different types of work items, the coun if the method is successfully queued; is thrown if the work item could not be queued. - [!NOTE] -> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. - -## Version Information - In the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. - - - -## Examples - The following example uses the .NET thread pool to calculate the `Fibonacci` result for five numbers between 20 and 40. Each `Fibonacci` result is represented by the `Fibonacci` class, which provides a method named `ThreadPoolCallback` that performs the calculation. An object that represents each `Fibonacci` value is created, and the `ThreadPoolCallback` method is passed to , which assigns an available thread in the pool to execute the method. - +> Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. + +## Examples + The following example uses the .NET thread pool to calculate the `Fibonacci` result for five numbers between 20 and 40. Each `Fibonacci` result is represented by the `Fibonacci` class, which provides a method named `ThreadPoolCallback` that performs the calculation. An object that represents each `Fibonacci` value is created, and the `ThreadPoolCallback` method is passed to , which assigns an available thread in the pool to execute the method. + Because each `Fibonacci` object is given a semi-random value to compute, and because each thread will be competing for processor time, you cannot know in advance how long it will take for all five results to be calculated. That is why each `Fibonacci` object is passed an instance of the class during construction. Each object signals the provided event object when its calculation is complete, which allows the primary thread to block execution with until all five `Fibonacci` objects have calculated a result. The `Main` method then displays each `Fibonacci` result. - + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem1/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/QueueUserWorkItem/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem1/VB/source.vb" id="Snippet1"::: + ]]> The common language runtime (CLR) is hosted, and the host does not support this action. @@ -866,31 +857,27 @@ If a thread pool implementation may have different types of work items, the coun Registers a delegate to wait for a , specifying a 32-bit signed integer for the time-out in milliseconds. The that encapsulates the native handle. - that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - - The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: - -- The specified object is in the signaled state. - -- The time-out interval elapses. - - The method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. - + that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + + The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: + +- The specified object is in the signaled state. +- The time-out interval elapses. + + The method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. + > [!IMPORTANT] -> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. - - To cancel the wait operation, call the method. - - The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. - - Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. - -## Version Information - Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. - +> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. + + To cancel the wait operation, call the method. + + The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. + + Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. + ]]> The parameter is less than -1. @@ -966,31 +953,27 @@ If a thread pool implementation may have different types of work items, the coun Registers a delegate to wait for a , specifying a 64-bit signed integer for the time-out in milliseconds. The that encapsulates the native handle. - that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - - The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: - -- The specified object is in the signaled state. - -- The time-out interval elapses. - - The method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. - + that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + + The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: + +- The specified object is in the signaled state. +- The time-out interval elapses. + + The method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. + > [!IMPORTANT] -> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. - - To cancel the wait operation, call the method. - - The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. - - Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. - -## Version Information - Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. - +> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. + + To cancel the wait operation, call the method. + + The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. + + Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. + ]]> The parameter is less than -1. @@ -1066,31 +1049,27 @@ If a thread pool implementation may have different types of work items, the coun Registers a delegate to wait for a , specifying a value for the time-out. The that encapsulates the native handle. - that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - - The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: - -- The specified object is in the signaled state. - -- The time-out interval elapses. - - The method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. - + that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + + The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: + +- The specified object is in the signaled state. +- The time-out interval elapses. + + The method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. + > [!IMPORTANT] -> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. - - To cancel the wait operation, call the method. - - The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. - - Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. - -## Version Information - Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. - +> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. + + To cancel the wait operation, call the method. + + The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. + + Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. + ]]> The parameter is less than -1. @@ -1171,46 +1150,40 @@ If a thread pool implementation may have different types of work items, the coun Registers a delegate to wait for a , specifying a 32-bit unsigned integer for the time-out in milliseconds. The that can be used to cancel the registered wait operation. - that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - - The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: - -- The specified object is in the signaled state. - -- The time-out interval elapses. - - The method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. - + that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + + The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: + +- The specified object is in the signaled state. +- The time-out interval elapses. + + The method checks the current state of the specified object's . If the object's state is unsignaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the `timeOutInterval` parameter is not 0 (zero) and the `executeOnlyOnce` parameter is `false`, the timer is reset every time the event is signaled or the time-out interval elapses. + > [!IMPORTANT] -> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. - - To cancel the wait operation, call the method. - - The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. - - Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. - -## Version Information - Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. - - - -## Examples - The following example shows how to use the method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc`, and the wait handle is an . - - The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The that is returned by the method is assigned to the `Handle` field of the `TaskInfo` object so that the callback method has access to the . - - In addition to specifying `TaskInfo` as the object to pass to the callback method, the call to the method specifies the that the task will wait for, a delegate that represents the `WaitProc` callback method, a one second time-out interval, and multiple callbacks. - - When the main thread signals the by calling its method, the delegate is invoked. The `WaitProc` method tests to determine whether a time-out occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the , stopping additional callbacks. In the case of a time-out, the task continues to wait. The `WaitProc` method ends by printing a message to the console. - +> Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. + + To cancel the wait operation, call the method. + + The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. + + Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. + +## Examples + The following example shows how to use the method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc`, and the wait handle is an . + + The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The that is returned by the method is assigned to the `Handle` field of the `TaskInfo` object so that the callback method has access to the . + + In addition to specifying `TaskInfo` as the object to pass to the callback method, the call to the method specifies the that the task will wait for, a delegate that represents the `WaitProc` callback method, a one second time-out interval, and multiple callbacks. + + When the main thread signals the by calling its method, the delegate is invoked. The `WaitProc` method tests to determine whether a time-out occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the , stopping additional callbacks. In the case of a time-out, the task continues to wait. The `WaitProc` method ends by printing a message to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool RegisterWaitForSingleObject0/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/RegisteredWaitHandle/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool RegisterWaitForSingleObject0/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool RegisterWaitForSingleObject0/VB/source.vb" id="Snippet1"::: + ]]> The parameter is less than -1. @@ -1266,19 +1239,19 @@ If a thread pool implementation may have different types of work items, the coun if the change is successful; otherwise, . - property. In addition, you cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the corresponding minimum number of worker threads or I/O completion threads. To determine the minimum thread pool size, call the method. - - If the common language runtime is hosted, for example by Internet Information Services (IIS) or SQL Server, the host can limit or prevent changes to the thread pool size. - - Use caution when changing the maximum number of threads in the thread pool. While your code might benefit, the changes might have an adverse effect on code libraries you use. - - Setting the thread pool size too large can cause performance problems. If too many threads are executing at the same time, the task switching overhead becomes a significant factor. - + + You cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the number of processors on the computer. To determine how many processors are present, retrieve the value of the property. In addition, you cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the corresponding minimum number of worker threads or I/O completion threads. To determine the minimum thread pool size, call the method. + + If the common language runtime is hosted, for example by Internet Information Services (IIS) or SQL Server, the host can limit or prevent changes to the thread pool size. + + Use caution when changing the maximum number of threads in the thread pool. While your code might benefit, the changes might have an adverse effect on code libraries you use. + + Setting the thread pool size too large can cause performance problems. If too many threads are executing at the same time, the task switching overhead becomes a significant factor. + > [!NOTE] > The thread pool may have upper limits for the maximum thread counts (such as `short.MaxValue`, depending on the implementation). The argument values are capped to the upper limit, so even when the method returns `true`, the actual maximum thread counts may be lower than requested. @@ -1340,37 +1313,37 @@ If a thread pool implementation may have different types of work items, the coun if the change is successful; otherwise, . - ), returns `false` and does not change either of the minimum values. - + + The thread pool provides new worker threads or I/O completion threads on demand until it reaches the minimum for each category. When the minimum is reached, the thread pool can create additional threads in that category or wait until some tasks complete. Beginning with the .NET Framework 4, the thread pool creates and destroys threads in order to optimize throughput, which is defined as the number of tasks that complete per unit of time. Too few threads might not make optimal use of available resources, whereas too many threads could increase resource contention. + + When demand is low, the actual number of thread pool threads can fall below the minimum values. + + If you specify a negative number or a number larger than the maximum number of active thread pool threads (obtained using ), returns `false` and does not change either of the minimum values. + By default, the minimum number of threads is set to the processor count. You can use to increase the minimum number of threads, such as to temporarily work around issues where some queued work items or tasks block thread pool threads. Those blockages sometimes lead to a situation where all worker or I/O completion threads are blocked (starvation). However, increasing the minimum number of threads might degrade performance in other ways, such as: - + - The thread pool may schedule more worker threads, even when the worker threads are not getting blocked. The oversubscription can cause threads that get scheduled-out to be significantly delayed as they wait in a long queue to get another time slice, delaying some work items or tasks. - Worker threads may take more CPU time in dequeuing work items due to having to scan more threads to steal work from. - Context switching between threads may increase CPU usage. - Garbage collection may take more CPU time in thread stack walking. - The process may consume more memory. - + > [!CAUTION] -> Using the method to increase the minimum number of threads can cause performance problems as described in the preceding text. In most cases, the thread pool will perform better with its own algorithm for allocating threads. Reducing the minimum to less than the number of processors can also hurt performance. - - - -## Examples - The following example sets the minimum number of worker threads to four, and preserves the original value for the minimum number of asynchronous I/O completion threads. - +> Using the method to increase the minimum number of threads can cause performance problems as described in the preceding text. In most cases, the thread pool will perform better with its own algorithm for allocating threads. Reducing the minimum to less than the number of processors can also hurt performance. + + + +## Examples + The following example sets the minimum number of worker threads to four, and preserves the original value for the minimum number of asynchronous I/O completion threads. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetSetMinThreads/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadPool/GetMinThreads/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetSetMinThreads/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool.GetSetMinThreads/VB/source.vb" id="Snippet1"::: + ]]> @@ -1471,14 +1444,14 @@ If a thread pool implementation may have different types of threads, the count i if the operation was successfully queued to an I/O completion port; otherwise, . - class, the structure, and the `OVERLAPPED` structure in the Win32 Platform SDK. - + class, the structure, and the `OVERLAPPED` structure in the Win32 Platform SDK. + > [!CAUTION] -> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread does not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - +> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread does not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. + ]]> @@ -1590,14 +1563,14 @@ The thread pool will invoke the work item's if the method succeeds; is thrown if the work item could not be queued. - method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. - + method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. + > [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - +> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. + ]]> The caller does not have the required permission. @@ -1739,18 +1712,18 @@ The thread pool will invoke the work item's Registers a delegate to wait for a , using a 32-bit signed integer for the time-out in milliseconds. This method does not propagate the calling stack to the worker thread. The object that can be used to cancel the registered wait operation. - method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. - + method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. + > [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - - Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. - - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - +> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. + + Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. + + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + ]]> The parameter is less than -1. @@ -1826,18 +1799,18 @@ The thread pool will invoke the work item's Registers a delegate to wait for a , specifying a 64-bit signed integer for the time-out in milliseconds. This method does not propagate the calling stack to the worker thread. The object that can be used to cancel the registered wait operation. - method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. - + method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. + > [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - - Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. - - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - +> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. + + Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. + + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + ]]> The parameter is less than -1. @@ -1913,18 +1886,18 @@ The thread pool will invoke the work item's Registers a delegate to wait for a , specifying a value for the time-out. This method does not propagate the calling stack to the worker thread. The object that can be used to cancel the registered wait operation. - method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. - + method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. + > [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - - Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. - - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - +> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. + + Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. + + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + ]]> The parameter is less than -1. @@ -2005,18 +1978,18 @@ The thread pool will invoke the work item's Registers a delegate to wait for a , specifying a 32-bit unsigned integer for the time-out in milliseconds. This method does not propagate the calling stack to the worker thread. The object that can be used to cancel the registered wait operation. - method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. - + method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. + > [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - - Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. - - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. - +> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. + + Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. + + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + ]]> The caller does not have the required permission. diff --git a/xml/System.Threading/WaitHandle.xml b/xml/System.Threading/WaitHandle.xml index 78039ec2cd7..ba1ed8b18b6 100644 --- a/xml/System.Threading/WaitHandle.xml +++ b/xml/System.Threading/WaitHandle.xml @@ -70,49 +70,49 @@ Encapsulates operating system-specific objects that wait for exclusive access to shared resources. - class encapsulates a native operating system synchronization handle and is used to represent all synchronization objects in the runtime that allow multiple wait operations. For a comparison of wait handles with other synchronization objects, see [Overview of Synchronization Primitives](/dotnet/standard/threading/overview-of-synchronization-primitives). - - The class itself is abstract. Classes derived from define a signaling mechanism to indicate taking or releasing access to a shared resource, but they use the inherited methods to block while waiting for access to shared resources. The classes derived from include: - -- The class. See [Mutexes](/dotnet/standard/threading/mutexes). - -- The class and its derived classes, and . - -- The class. See [Semaphore and SemaphoreSlim](/dotnet/standard/threading/semaphore-and-semaphoreslim). - - Threads can block on an individual wait handle by calling the instance method , which is inherited by classes derived from . - - The derived classes of differ in their thread affinity. Event wait handles (, , and ) and semaphores do not have thread affinity; any thread can signal an event wait handle or semaphore. Mutexes, on the other hand, do have thread affinity; the thread that owns a mutex must release it, and an exception is thrown if a thread calls the method on a mutex that it does not own. - - Because the class derives from , these classes can be used to synchronize the activities of threads across application domain boundaries. - - In addition to its derived classes, the class has a number of static methods that block a thread until one or more synchronization objects receive a signal. These include: - -- , which allows a thread to signal one wait handle and immediately wait on another. - -- , which allows a thread to wait until all the wait handles in an array receive a signal. - -- , which allows a thread to wait until any one of a specified set of wait handles has been signaled. - - The overloads of these methods provide timeout intervals for abandoning the wait, and the opportunity to exit a synchronization context before entering the wait, allowing other threads to use the synchronization context. - + class encapsulates a native operating system synchronization handle and is used to represent all synchronization objects in the runtime that allow multiple wait operations. For a comparison of wait handles with other synchronization objects, see [Overview of Synchronization Primitives](/dotnet/standard/threading/overview-of-synchronization-primitives). + + The class itself is abstract. Classes derived from define a signaling mechanism to indicate taking or releasing access to a shared resource, but they use the inherited methods to block while waiting for access to shared resources. The classes derived from include: + +- The class. See [Mutexes](/dotnet/standard/threading/mutexes). + +- The class and its derived classes, and . + +- The class. See [Semaphore and SemaphoreSlim](/dotnet/standard/threading/semaphore-and-semaphoreslim). + + Threads can block on an individual wait handle by calling the instance method , which is inherited by classes derived from . + + The derived classes of differ in their thread affinity. Event wait handles (, , and ) and semaphores do not have thread affinity; any thread can signal an event wait handle or semaphore. Mutexes, on the other hand, do have thread affinity; the thread that owns a mutex must release it, and an exception is thrown if a thread calls the method on a mutex that it does not own. + + Because the class derives from , these classes can be used to synchronize the activities of threads across application domain boundaries. + + In addition to its derived classes, the class has a number of static methods that block a thread until one or more synchronization objects receive a signal. These include: + +- , which allows a thread to signal one wait handle and immediately wait on another. + +- , which allows a thread to wait until all the wait handles in an array receive a signal. + +- , which allows a thread to wait until any one of a specified set of wait handles has been signaled. + + The overloads of these methods provide timeout intervals for abandoning the wait, and the opportunity to exit a synchronization context before entering the wait, allowing other threads to use the synchronization context. + > [!IMPORTANT] -> This type implements the interface. When you have finished using the type or a type derived from it, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. - - - -## Examples - The following code example shows how two threads can do background tasks while the Main thread waits for the tasks to complete using the static and methods of the class. - +> This type implements the interface. When you have finished using the type or a type derived from it, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + + implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. + + + +## Examples + The following code example shows how two threads can do background tasks while the Main thread waits for the tasks to complete using the static and methods of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/WaitHandle/cpp/WaitHandle.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/Overview/WaitHandle.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WaitHandle/VB/WaitHandle.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WaitHandle/VB/WaitHandle.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -203,16 +203,16 @@ Releases all resources held by the current . - method for the class and its derived classes. It provides a standard implementation that calls the `Dispose(Boolean)` overload with a `true` argument and then calls the method. Call this method to release all resources held by an instance of `WaitHandle` or a derived class. - - Once this method is called, references to the current instance cause undefined behavior. - + method for the class and its derived classes. It provides a standard implementation that calls the `Dispose(Boolean)` overload with a `true` argument and then calls the method. Call this method to release all resources held by an instance of `WaitHandle` or a derived class. + + Once this method is called, references to the current instance cause undefined behavior. + > [!NOTE] -> Always call or before you release your last reference to the . Otherwise, the resources it is using will not be freed. - +> Always call or before you release your last reference to the . Otherwise, the resources it is using will not be freed. + ]]> @@ -276,14 +276,14 @@ Releases all resources used by the current instance of the class. - method. - + method. + > [!NOTE] -> Always call or before you release your last reference to the . Otherwise, the resources it is using will not be freed. - +> Always call or before you release your last reference to the . Otherwise, the resources it is using will not be freed. + ]]> Cleaning Up Unmanaged Resources @@ -340,16 +340,16 @@ to release both managed and unmanaged resources; to release only unmanaged resources. When overridden in a derived class, releases the unmanaged resources used by the , and optionally releases the managed resources. - and the methods with the `explicitDisposing` parameter set to `true`. When the `explicitDisposing` parameter is `true`, this method releases all resources held by any managed objects that this object references. - + and the methods with the `explicitDisposing` parameter set to `true`. When the `explicitDisposing` parameter is `true`, this method releases all resources held by any managed objects that this object references. + ]]> - You should override the method to release resources allocated in derived classes. - + You should override the method to release resources allocated in derived classes. + The or method can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed in an earlier call to or . Implementing a Dispose Method @@ -382,7 +382,7 @@ [!NOTE] > This member has been removed from the .NET Framework version 2.0 and subsequent versions. This topic applies only to the versions listed in "Version Information" later in this topic. @@ -449,13 +449,13 @@ Application code does not call this method; it is automatically invoked during g Gets or sets the native operating system handle. An representing the native operating system handle. The default is the value of the field. - property does not close the previous handle. This can result in a leaked handle. - - Do not use this property in the .NET Framework version 2.0 or later; use the property instead. Setting this property to a valid handle also sets the property, but setting it to can result in a leaked handle. - + property does not close the previous handle. This can result in a leaked handle. + + Do not use this property in the .NET Framework version 2.0 or later; use the property instead. Setting this property to a valid handle also sets the property, but setting it to can result in a leaked handle. + ]]> @@ -500,11 +500,11 @@ Application code does not call this method; it is automatically invoked during g Represents an invalid native operating system handle. This field is read-only. - property. - + property. + ]]> @@ -566,13 +566,13 @@ Application code does not call this method; it is automatically invoked during g Gets or sets the native operating system handle. A representing the native operating system handle. - property, the previous handle will be closed when the previous object is collected. Do not manually close the handle, because this results in an when the attempts to close the handle. - - implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native handle operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. - + property, the previous handle will be closed when the previous object is collected. Do not manually close the handle, because this results in an when the attempts to close the handle. + + implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native handle operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. + ]]> @@ -630,29 +630,27 @@ Application code does not call this method; it is automatically invoked during g if both the signal and the wait complete successfully; if the wait does not complete, the method does not return. - method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. - - The example starts five threads, allows them to block on an created with the flag, and then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an created with the flag. - + method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. + + The example starts five threads, allows them to block on an created with the flag, and then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an created with the flag. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/EventResetMode/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/VB/source.vb" id="Snippet1"::: + ]]> - is . - - -or- - + is . + + -or- + is . The method was called on a thread in state. @@ -714,27 +712,23 @@ Application code does not call this method; it is automatically invoked during g if both the signal and the wait completed successfully, or if the signal completed but the wait timed out. - method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that does not derive from , like , you can be in a nondefault context if a is on your stack in the current application domain. - - When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing the method. The thread returns to the original nondefault context after the call to the method completes. - - This can be useful when the context-bound class has . In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls the method and specifies `true` for `exitContext`, the thread exits the synchronization domain, allowing a thread that is blocked on a call to any member of the object to proceed. When the method returns, the thread that made the call must wait to reenter the synchronization domain. - + - is . - - -or- - + is . + + -or- + is . The method is called on a thread in state. The cannot be signaled because it would exceed its maximum count. @@ -791,38 +785,33 @@ Application code does not call this method; it is automatically invoked during g if both the signal and the wait completed successfully, or if the signal completed but the wait timed out. - . - - If `timeout` is zero, the method does not block. It tests the state of the `toWaitOn` and returns immediately. - -## Notes on Exiting the Context - The `exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that does not derive from , like , you can be in a nondefault context if a is on your stack in the current application domain. - - When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing the method. The thread returns to the original nondefault context after the call to the method completes. - - This can be useful when the context-bound class has . In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls the method and specifies `true` for `exitContext`, the thread exits the synchronization domain, allowing a thread that is blocked on a call to any member of the object to proceed. When the method returns, the thread that made the call must wait to reenter the synchronization domain. - + . + + If `timeout` is zero, the method does not block. It tests the state of the `toWaitOn` and returns immediately. + +[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] + ]]> - is . - - -or- - + is . + + -or- + is . The method was called on a thread in state. is a semaphore, and it already has a full count. - evaluates to a negative number of milliseconds other than -1. - - -or- - + evaluates to a negative number of milliseconds other than -1. + + -or- + is greater than Int32.MaxValue. The wait completed because a thread exited without releasing a mutex. @@ -858,7 +847,7 @@ Application code does not call this method; it is automatically invoked during g to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). ]]> @@ -931,43 +920,43 @@ Calling `Dispose` allows the resources used by the when every element in has received a signal; otherwise the method never returns. - is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - + is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + The method returns when all the handles are signaled. If more than 64 handles are passed, a is thrown. If the array contains duplicates, the call fails with a . - + > [!NOTE] > The method is not supported on threads in state. - - Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. - - - -## Examples - The following code example shows how to use the thread pool to asynchronously create and write to a group of files. Each write operation is queued as a work item and signals when it is finished. The main thread waits for all the items to signal and then exits. - + + Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. + + + +## Examples + The following code example shows how to use the thread pool to asynchronously create and write to a group of files. Each write operation is queued as a work item and signals when it is finished. The main thread waits for all the items to signal and then exits. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAll1/CPP/source1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/WaitAll/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAll1/VB/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAll1/VB/source1.vb" id="Snippet1"::: + ]]> - The parameter is . -or- - - One or more of the objects in the array are . - - -or- - + The parameter is . -or- + + One or more of the objects in the array are . + + -or- + is an array with no elements and the .NET Framework version is 2.0 or later. The array contains elements that are duplicates. Note: In the .NET for Windows Store apps or the Portable Class Library, catch the base class exception, , instead. - The number of objects in is greater than the system permits. - - -or- - + The number of objects in is greater than the system permits. + + -or- + The current thread is in state, and contains more than one element. is an array with no elements and the .NET Framework version is 1.0 or 1.1. @@ -1028,36 +1017,36 @@ Note: In the .NET for when every element in has received a signal; otherwise, . - method returns when the wait terminates, which means either when all the handles are signaled or when time-out occurs. If more than 64 handles are passed, a is thrown. If there are duplicates in the array, the call fails with a . - + method returns when the wait terminates, which means either when all the handles are signaled or when time-out occurs. If more than 64 handles are passed, a is thrown. If there are duplicates in the array, the call fails with a . + > [!NOTE] > The method is not supported on threads in state. - - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. - + + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + ]]> - The parameter is . - - -or- - - One or more of the objects in the array is . - - -or- - + The parameter is . + + -or- + + One or more of the objects in the array is . + + -or- + is an array with no elements. The array contains elements that are duplicates. Note: In the .NET for Windows Store apps or the Portable Class Library, catch the base class exception, , instead. - The number of objects in is greater than the system permits. - - -or- - + The number of objects in is greater than the system permits. + + -or- + The current thread is in state, and contains more than one element. is a negative number other than -1, which represents an infinite time-out. @@ -1118,44 +1107,44 @@ Note: In the .NET for when every element in has received a signal; otherwise, . - method returns when the wait terminates, which means either all the handles are signaled or a time-out occurs. If more than 64 handles are passed, a is thrown. If the array contains duplicates, the call will fail. - + > [!NOTE] > The method is not supported on threads in state. - - The maximum value for `timeout` is . - - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. - + + The maximum value for `timeout` is . + + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + ]]> - The parameter is . - - -or- - - One or more of the objects in the array is . - - -or- - + The parameter is . + + -or- + + One or more of the objects in the array is . + + -or- + is an array with no elements. The array contains elements that are duplicates. Note: In the .NET for Windows Store apps or the Portable Class Library, catch the base class exception, , instead. - The number of objects in is greater than the system permits. - - -or- - + The number of objects in is greater than the system permits. + + -or- + The current thread is in state, and contains more than one element. - is a negative number other than -1 milliseconds, which represents an infinite time-out. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out. + + -or- + is greater than Int32.MaxValue. The wait terminated because a thread exited without releasing a mutex. The array contains a transparent proxy for a in another application domain. @@ -1214,50 +1203,44 @@ Note: In the .NET for when every element in has received a signal; otherwise, . - is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - - The method returns when the wait terminates, which means either when all the handles are signaled or when time-out occurs. If more than 64 handles are passed, a is thrown. If there are duplicates in the array, the call fails with a . - + is thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + +The method returns when the wait terminates, which means either when all the handles are signaled or when time-out occurs. If more than 64 handles are passed, a is thrown. If there are duplicates in the array, the call fails with a . + > [!NOTE] -> The method is not supported on threads in state. - -## Notes on Exiting the Context - The `exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that is not derived from , like , you can be in a nondefault context if a is on your stack in the current application domain. - - When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing the method. The thread returns to the original nondefault context after the call to the method completes. - - This can be useful when the context-bound class has the attribute. In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls the method and specifies `true` for `exitContext`, the thread exits the synchronization domain, allowing a thread that is blocked on a call to any member of the object to proceed. When the method returns, the thread that made the call must wait to reenter the synchronization domain. - - - -## Examples - The following code example shows how to use the thread pool to asynchronously create and write to a group of files. Each write operation is queued as a work item and signals when it is finished. The main thread waits for all the items to signal and then exits. - +> The method is not supported on threads in state. + +[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] + +## Examples + The following code example shows how to use the thread pool to asynchronously create and write to a group of files. Each write operation is queued as a work item and signals when it is finished. The main thread waits for all the items to signal and then exits. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAll2/CPP/source2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/WaitAll/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAll2/VB/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAll2/VB/source2.vb" id="Snippet1"::: + ]]> - The parameter is . - - -or- - - One or more of the objects in the array is . - - -or- - + The parameter is . + + -or- + + One or more of the objects in the array is . + + -or- + is an array with no elements and the .NET Framework version is 2.0 or later. The array contains elements that are duplicates. - The number of objects in is greater than the system permits. - - -or- - + The number of objects in is greater than the system permits. + + -or- + The current thread is in state, and contains more than one element. is an array with no elements and the .NET Framework version is 1.0 or 1.1. @@ -1314,60 +1297,54 @@ Note: In the .NET for when every element in has received a signal; otherwise . - is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - - The method returns when the wait terminates, which means either all the handles are signaled or a time-out occurs. If more than 64 handles are passed, a is thrown. If the array contains duplicates, the call will fail. - + is thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + +The method returns when the wait terminates, which means either all the handles are signaled or a time-out occurs. If more than 64 handles are passed, a is thrown. If the array contains duplicates, the call will fail. + > [!NOTE] -> The method is not supported on threads in state. - - The maximum value for `timeout` is . - -## Notes on Exiting the Context - The `exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that is not derived from , like , you can be in a nondefault context if a is on your stack in the current application domain. - - When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing the method. It returns to the original nondefault context after the call to the method completes. - - This can be useful when the context-bound class has . In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls the method and specifies `true` for `exitContext`, the thread exits the synchronization domain, allowing a thread that is blocked on a call to any member of the object to proceed. When the method returns, the thread that made the call must wait to reenter the synchronization domain. - - - -## Examples - The following code example shows how to use the thread pool to asynchronously create and write to a group of files. Each write operation is queued as a work item and signals when it is finished. The main thread waits for all the items to signal and then exits. - +> The method is not supported on threads in state. + +The maximum value for `timeout` is . + +[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] + +## Examples + The following code example shows how to use the thread pool to asynchronously create and write to a group of files. Each write operation is queued as a work item and signals when it is finished. The main thread waits for all the items to signal and then exits. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAll3/CPP/source3.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/WaitAll/source3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAll3/VB/source3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAll3/VB/source3.vb" id="Snippet1"::: + ]]> - The parameter is . - - -or- - - One or more of the objects in the array is . - - -or- - + The parameter is . + + -or- + + One or more of the objects in the array is . + + -or- + is an array with no elements and the .NET Framework version is 2.0 or later. The array contains elements that are duplicates. - The number of objects in is greater than the system permits. - - -or- - + The number of objects in is greater than the system permits. + + -or- + The attribute is applied to the thread procedure for the current thread, and contains more than one element. is an array with no elements and the .NET Framework version is 1.0 or 1.1. - is a negative number other than -1 milliseconds, which represents an infinite time-out. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out. + + -or- + is greater than Int32.MaxValue. The wait terminated because a thread exited without releasing a mutex. The array contains a transparent proxy for a in another application domain. @@ -1437,37 +1414,37 @@ Note: In the .NET for Waits for any of the elements in the specified array to receive a signal. The array index of the object that satisfied the wait. - is new in the .NET Framework version 2.0. In previous versions, the method returns `true` if the wait completes because a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - - The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. - + is new in the .NET Framework version 2.0. In previous versions, the method returns `true` if the wait completes because a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + + The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. + > [!NOTE] -> In versions of the .NET Framework earlier than version 2.0, if a thread exits or aborts without explicitly releasing a , and that `Mutex` is at index 0 (zero) in a `WaitAny` array on another thread, the index returned by `WaitAny` is 128 instead of 0. - +> In versions of the .NET Framework earlier than version 2.0, if a thread exits or aborts without explicitly releasing a , and that `Mutex` is at index 0 (zero) in a `WaitAny` array on another thread, the index returned by `WaitAny` is 128 instead of 0. + This method returns when any handle is signaled. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. The maximum number of the wait handles is 64, and 63 if the current thread is in state. - Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. - - - -## Examples - The following code example demonstrates calling the method. - + Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. + + + +## Examples + The following code example demonstrates calling the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/WaitHandle/cpp/WaitHandle.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/Overview/WaitHandle.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WaitHandle/VB/WaitHandle.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WaitHandle/VB/WaitHandle.vb" id="Snippet1"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + One or more of the objects in the array is . The number of objects in is greater than the system permits. @@ -1530,25 +1507,25 @@ Note: In the .NET for Waits for any of the elements in the specified array to receive a signal, using a 32-bit signed integer to specify the time interval. The array index of the object that satisfied the wait, or if no object satisfied the wait and a time interval equivalent to has passed. - method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. - + method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. + This method returns when the wait terminates, either when any of the handles are signaled or when a timeout occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. The maximum number of the wait handles is 64, and 63 if the current thread is in state. - - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. - + + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + One or more of the objects in the array is . The number of objects in is greater than the system permits. @@ -1611,34 +1588,34 @@ Note: In the .NET for Waits for any of the elements in the specified array to receive a signal, using a to specify the time interval. The array index of the object that satisfied the wait, or if no object satisfied the wait and a time interval equivalent to has passed. - method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. - + method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. + This method returns when the wait terminates, either when any of the handles are signaled or when a time-out occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. The maximum number of the wait handles is 64, and 63 if the current thread is in state. - The maximum value for `timeout` is . - - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. - + The maximum value for `timeout` is . + + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + One or more of the objects in the array is . The number of objects in is greater than the system permits. - is a negative number other than -1 milliseconds, which represents an infinite time-out. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out. + + -or- + is greater than Int32.MaxValue. The wait completed because a thread exited without releasing a mutex. @@ -1702,44 +1679,33 @@ Note: In the .NET for Waits for any of the elements in the specified array to receive a signal, using a 32-bit signed integer to specify the time interval, and specifying whether to exit the synchronization domain before the wait. The array index of the object that satisfied the wait, or if no object satisfied the wait and a time interval equivalent to has passed. - is new in the .NET Framework version 2.0. In previous versions, the method returns `true` if the wait completes because a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - - The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. - -> [!NOTE] -> In versions of the .NET Framework earlier than version 2.0, if a thread exits or aborts without explicitly releasing a , and that `Mutex` is at index 0 (zero) in a `WaitAny` array on another thread, the index returned by `WaitAny` is 128 instead of 0. - - This method returns when the wait terminates, either when any of the handles are signaled or when a timeout occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. + method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + +This method returns when the wait terminates, either when any of the handles are signaled or when a timeout occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. + +The maximum number of the wait handles is 64, and 63 if the current thread is in state. + +[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] + +## Examples + The following code example demonstrates how to use the thread pool to simultaneously search for a file on multiple disks. For space considerations, only the root directory of each disk is searched. - The maximum number of the wait handles is 64, and 63 if the current thread is in state. - -## Notes on Exiting the Context - The `exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that does not derive from , like , you can be in a nondefault context if a is on your stack in the current application domain. - - When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing the method. The thread returns to the original nondefault context after the call to the method completes. - - This can be useful when the context-bound class has . In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls the method and specifies `true` for `exitContext`, the thread exits the synchronization domain, allowing a thread that is blocked on a call to any member of the object to proceed. When the method returns, the thread that made the call must wait to reenter the synchronization domain. - - - -## Examples - The following code example demonstrates how to use the thread pool to simultaneously search for a file on multiple disks. For space considerations, only the root directory of each disk is searched. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAny2/CPP/source2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/WaitAny/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAny2/VB/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAny2/VB/source2.vb" id="Snippet1"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + One or more of the objects in the array is . The number of objects in is greater than the system permits. @@ -1804,55 +1770,44 @@ Note: In the .NET for Waits for any of the elements in the specified array to receive a signal, using a to specify the time interval and specifying whether to exit the synchronization domain before the wait. The array index of the object that satisfied the wait, or if no object satisfied the wait and a time interval equivalent to has passed. - is new in the .NET Framework version 2.0. In previous versions, the method returns `true` if the wait completes because a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - - The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. - -> [!NOTE] -> In versions of the .NET Framework earlier than version 2.0, if a thread exits or aborts without explicitly releasing a , and that `Mutex` is at index 0 (zero) in a `WaitAny` array on another thread, the index returned by `WaitAny` is 128 instead of 0. - - This method returns when the wait terminates, either when any of the handles are signaled or when a time-out occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. + state. +## Remarks + +If `timeout` is zero, the method does not block. It tests the state of the wait handles and returns immediately. + +The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + +This method returns when the wait terminates, either when any of the handles are signaled or when a time-out occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. + +The maximum number of the wait handles is 64, and 63 if the current thread is in state. + +The maximum value for `timeout` is . + +[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] + +## Examples + The following code example demonstrates how to use the thread pool to simultaneously search for a file on multiple disks. For space considerations, only the root directory of each disk is searched. - The maximum value for `timeout` is . - -## Notes on Exiting the Context - The `exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that does not derive from , like , you can be in a nondefault context if a is on your stack in the current application domain. - - When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing the method. The thread returns to the original nondefault context after the call to the method completes. - - This can be useful when the context-bound class has . In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls the method and specifies `true` for `exitContext`, the thread exits the synchronization domain, allowing a thread that is blocked on a call to any member of the object to proceed. When the method returns, the thread that made the call must wait to reenter the synchronization domain. - - - -## Examples - The following code example demonstrates how to use the thread pool to simultaneously search for a file on multiple disks. For space considerations, only the root directory of each disk is searched. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAny3/CPP/source3.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/WaitAny/source3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAny3/VB/source3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitAny3/VB/source3.vb" id="Snippet1"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + One or more of the objects in the array is . The number of objects in is greater than the system permits. is an array with no elements, and the .NET Framework version is 1.0 or 1.1. - is a negative number other than -1 milliseconds, which represents an infinite time-out. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out. + + -or- + is greater than Int32.MaxValue. The wait completed because a thread exited without releasing a mutex. @@ -1916,26 +1871,26 @@ Note: In the .NET for if the current instance receives a signal. If the current instance is never signaled, never returns. - is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - - The caller of this method blocks indefinitely until the current instance receives a signal. Use this method to block until a receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. - - Calling this method overload is equivalent to calling the method overload and specifying -1 or for the first parameter and `false` for the second parameter. - - Override this method to customize the behavior of derived classes. - - - -## Examples - The following code example shows how to use a wait handle to keep a process from terminating while it waits for a background thread to finish executing. - + is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + + The caller of this method blocks indefinitely until the current instance receives a signal. Use this method to block until a receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. + + Calling this method overload is equivalent to calling the method overload and specifying -1 or for the first parameter and `false` for the second parameter. + + Override this method to customize the behavior of derived classes. + + + +## Examples + The following code example shows how to use a wait handle to keep a process from terminating while it waits for a background thread to finish executing. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitOne1/CPP/source1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/WaitOne/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitOne1/VB/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitOne1/VB/source1.vb" id="Snippet1"::: + ]]> The current instance has already been disposed. @@ -1988,26 +1943,26 @@ Note: In the .NET for if the current instance receives a signal; otherwise, . - receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. - - Override this method to customize the behavior of derived classes. - - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. - - - -## Examples - The following code example shows how to use a wait handle to keep a process from terminating while it waits for a background thread to finish executing. - + receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. + + Override this method to customize the behavior of derived classes. + + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + + + +## Examples + The following code example shows how to use a wait handle to keep a process from terminating while it waits for a background thread to finish executing. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitOne2/CPP/source2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/WaitOne/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitOne2/VB/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitOne2/VB/source2.vb" id="Snippet1"::: + ]]> The current instance has already been disposed. @@ -2062,27 +2017,27 @@ Note: In the .NET for if the current instance receives a signal; otherwise, . - receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. - - Override this method to customize the behavior of derived classes. - - The maximum value for `timeout` is . - - Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. - + receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. + + Override this method to customize the behavior of derived classes. + + The maximum value for `timeout` is . + + Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. + ]]> The current instance has already been disposed. - is a negative number other than -1 milliseconds, which represents an infinite time-out. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out. + + -or- + is greater than Int32.MaxValue. The wait completed because a thread exited without releasing a mutex. The current instance is a transparent proxy for a in another application domain. @@ -2133,33 +2088,27 @@ Note: In the .NET for if the current instance receives a signal; otherwise, . - is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - - The caller of this method blocks until the current instance receives a signal or a time-out occurs. Use this method to block until a receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. - - Override this method to customize the behavior of derived classes. - -## Notes on Exiting the Context - The `exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that does not derive from , like , you can be in a nondefault context if a is on your stack in the current application domain. - - When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing the method. The thread returns to the original nondefault context after the call to the method completes. - - This can be useful when the context-bound class has . In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls the method and specifies `true` for `exitContext`, the thread exits the synchronization domain, allowing a thread that is blocked on a call to any member of the object to proceed. When the method returns, the thread that made the call must wait to reenter the synchronization domain. - - - -## Examples - The following example shows how the method overload behaves when it is called within a synchronization domain. First, a thread waits with `exitContext` set to `false` and blocks until the wait timeout expires. A second thread executes after the first thread terminates and waits with `exitContext` set to `true`. The call to signal the wait handle for this second thread is not blocked, and the thread completes before the wait timeout. - + is thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + +The caller of this method blocks until the current instance receives a signal or a time-out occurs. Use this method to block until a receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. + +Override this method to customize the behavior of derived classes. + +[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] + +## Examples + The following example shows how the method overload behaves when it is called within a synchronization domain. First, a thread waits with `exitContext` set to `false` and blocks until the wait timeout expires. A second thread executes after the first thread terminates and waits with `exitContext` set to `true`. The call to signal the wait handle for this second thread is not blocked, and the thread completes before the wait timeout. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.threading.waithandle.waitone4/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/WaitOne/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.waithandle.waitone4/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.waithandle.waitone4/vb/source.vb" id="Snippet1"::: + ]]> The current instance has already been disposed. @@ -2214,43 +2163,37 @@ Note: In the .NET for if the current instance receives a signal; otherwise, . - is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. - - The caller of this method blocks until the current instance receives a signal or a time-out occurs. Use this method to block until a receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. - - Override this method to customize the behavior of derived classes. - - The maximum value for `timeout` is . - -## Notes on Exiting the Context - The `exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that does not derive from , like , you can be in a nondefault context if a is on your stack in the current application domain. - - When your code is executing in a nondefault context, specifying `true` for `exitContext` causes the thread to exit the nondefault managed context (that is, to transition to the default context) before executing the method. The thread returns to the original nondefault context after the call to the method completes. - - This can be useful when the context-bound class has . In that case, all calls to members of the class are automatically synchronized, and the synchronization domain is the entire body of code for the class. If code in the call stack of a member calls the method and specifies `true` for `exitContext`, the thread exits the synchronization domain, allowing a thread that is blocked on a call to any member of the object to proceed. When the method returns, the thread that made the call must wait to reenter the synchronization domain. - - - -## Examples - The following code example shows how to use a wait handle to keep a process from terminating while it waits for a background thread to finish executing. - + is thrown. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + +The caller of this method blocks until the current instance receives a signal or a time-out occurs. Use this method to block until a receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. + +Override this method to customize the behavior of derived classes. + +The maximum value for `timeout` is . + +[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] + +## Examples + The following code example shows how to use a wait handle to keep a process from terminating while it waits for a background thread to finish executing. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitOne3/CPP/source3.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/WaitHandle/WaitOne/source3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitOne3/VB/source3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.WaitOne3/VB/source3.vb" id="Snippet1"::: + ]]> The current instance has already been disposed. - is a negative number other than -1 milliseconds, which represents an infinite time-out. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out. + + -or- + is greater than Int32.MaxValue. The wait completed because a thread exited without releasing a mutex. The current instance is a transparent proxy for a in another application domain. @@ -2297,20 +2240,20 @@ Note: In the .NET for Indicates that a operation timed out before any of the wait handles were signaled. This field is constant. - diff --git a/xml/System.Xml/XmlReader.xml b/xml/System.Xml/XmlReader.xml index 7f3cc04bb6e..77aaddb9cb5 100644 --- a/xml/System.Xml/XmlReader.xml +++ b/xml/System.Xml/XmlReader.xml @@ -454,98 +454,7 @@ The following example code shows how to use the asynchronous API to parse XML. Creates a new instance. - - overloads include a `settings` parameter that accepts an object. You can use this object to: - -- Specify which features you want supported on the object. - -- Reuse the object to create multiple readers. You can use the same settings to create multiple readers with the same functionality. Or, you can modify the settings on an instance and create a new reader with a different set of features. - -- Add features to an existing XML reader. The method can accept another object. The underlying object can be a user-defined reader, a object, or another instance that you want to add additional features to. - -- Take full advantage of features such as better conformance checking and compliance to the [XML 1.0 (fourth edition)](https://www.w3.org/TR/2006/REC-xml-20060816/) recommendation that are available only on objects created by the static method. - -> [!NOTE] -> Although the .NET Framework includes concrete implementations of the class, such as the , , and the classes, we recommend that you create instances by using the method. - -## Default settings - If you use a overload that doesn't accept a object, the following default reader settings are used: - -|Setting|Default| -|-------------|-------------| -||`true`| -||| -||`false`| -||`false`| -||`false`| -||0| -||0| -||`null`| -||| -||An empty object| -|| enabled| -||| -||A new object. Starting with the .NET Framework 4.5.2, this setting has a default value of `null`.| - -## Settings for common scenarios - Here are the properties you should set for some of the typical XML reader scenarios. - -|Requirement|Set| -|-----------------|---------| -|Data must be a well-formed XML document.| to .| -|Data must be a well-formed XML parsed entity.| to .| -|Data must be validated against a DTD.| to
to .| -|Data must be validated against an XML schema.| to
to the to use for validation. Note that doesn't support XML-Data Reduced (XDR) schema validation.| -|Data must be validated against an inline XML schema.| to
to .| -|Type support.| to
to the to use.| - - doesn't support XML-Data Reduced (XDR) schema validation. - -## Asynchronous programming - In synchronous mode, the method reads the first chunk of data from the buffer of the file, stream, or text reader. This may throw an exception if an I/O operation fails. In asynchronous mode, the first I/O operation occurs with a read operation, so exceptions that arise will be thrown when the read operation occurs. - -## Security considerations - By default, the uses an object with no user credentials to open resources. This means that, by default, the XML reader can access any location that doesn't require credentials. Use the property to control access to resources: - -- Set to an object to restrict the resources that the XML reader can access. - - -or- - -- Set to `null` to prevent the XML reader from opening any external resources. - - - -## Examples - This example creates an XML reader that strips insignificant white space, strips comments, and performs fragment-level conformance checking. - - :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlParserContext/Overview/XmlReader_Create.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlReader.Create/VB/XmlReader_Create.vb" id="Snippet11"::: - - The following example uses an with default credentials to access a file. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlReaderSettings.cctor/CPP/XmlReaderSettings.cctor.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlReader/Create/factory_rdr_cctor2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlReaderSettings.cctor/VB/factory_rdr_cctor2.vb" id="Snippet1"::: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlReaderSettings.cctor/CPP/XmlReaderSettings.cctor.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlReader/Create/factory_rdr_cctor2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlReaderSettings.cctor/VB/factory_rdr_cctor2.vb" id="Snippet2"::: - - The following code wraps a reader instance within another reader. - - :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlParserContext/Overview/XmlReader_Create.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlReader.Create/VB/XmlReader_Create.vb" id="Snippet13"::: - - This example chains readers to add DTD and XML schema validation. - - :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlParserContext/Overview/XmlReader_Create.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlReader.Create/VB/XmlReader_Create.vb" id="Snippet12"::: - - ]]> - + For more information about this API, see Supplemental API remarks for XmlReader.Close. @@ -841,11 +750,11 @@ Note: In .NET for Win > [!IMPORTANT] > You can use one of the following methods to control which resources the can access: > -> - Restrict the resources that the can access by setting the property to an object. +> - Restrict the resources that the can access by setting the property to an object. > > -or- > -> - Do not allow the to open any external resources by setting the property to `null`. +> - Do not allow the to open any external resources by setting the property to `null`. The created object expands entity references and performs XML normalization of new line characters. @@ -920,11 +829,11 @@ Note: In .NET for Win > [!IMPORTANT] > You can use one of the following methods to control which resources the can access: > -> - Restrict the resources that the can access by setting the property to an object. +> - Restrict the resources that the can access by setting the property to an object. > > -or- > -> - Do not allow the to open any external resources by setting the property to `null`. +> - Do not allow the to open any external resources by setting the property to `null`. The created object expands entity references and performs XML normalization of new line characters. @@ -1095,11 +1004,11 @@ Note: In .NET for Win > [!IMPORTANT] > You can use one of the following methods to control which resources the can access: > -> - Restrict the resources that the can access by setting the property to an object. +> - Restrict the resources that the can access by setting the property to an object. > > -or- > -> - Do not allow the to open any external resources by setting the property to `null`. +> - Do not allow the to open any external resources by setting the property to `null`. The created object expands entity references and performs XML normalization of new line characters. @@ -1197,11 +1106,11 @@ Note: In .NET for Win > [!IMPORTANT] > You can use one of the following methods to control which resources the can access: > -> - Restrict the resources that the can access by setting the property to an object. +> - Restrict the resources that the can access by setting the property to an object. > > -or- > -> - Do not allow the to open any external resources by setting the property to `null`. +> - Do not allow the to open any external resources by setting the property to `null`. The created object expands entity references and performs XML normalization of new line characters. @@ -1289,11 +1198,11 @@ Note: In .NET for Win > [!IMPORTANT] > You can use one of the following methods to control which resources the can access: > -> - Restrict the resources that the can access by setting the property to an object. +> - Restrict the resources that the can access by setting the property to an object. > > -or- > -> - Do not allow the to open any external resources by setting the property to `null`. +> - Do not allow the to open any external resources by setting the property to `null`. The created object expands entity references and performs XML normalization of new line characters. @@ -1376,11 +1285,11 @@ Note: In .NET for Win > [!IMPORTANT] > You can use one of the following methods to control which resources the can access: > -> - Restrict the resources that the can access by setting the property to an object. +> - Restrict the resources that the can access by setting the property to an object. > > -or- > -> - Do not allow the to open any external resources by setting the property to `null`. +> - Do not allow the to open any external resources by setting the property to `null`. The created object expands entity references and performs XML normalization of new line characters. @@ -1466,11 +1375,11 @@ Note: In .NET for Win > [!IMPORTANT] > You can use one of the following methods to control which resources the can access: > -> - Restrict the resources that the can access by setting the property to an object. +> - Restrict the resources that the can access by setting the property to an object. > > -or- > -> - Do not allow the to open any external resources by setting the property to `null`. +> - Do not allow the to open any external resources by setting the property to `null`. The created object expands entity references and performs XML normalization of new line characters. @@ -4370,11 +4279,11 @@ An asynchronous method was called without This method has the following behavior: -- returns the value `0` when it has reached the end of the byte stream it was operating on. The reader is positioned on the first non-content node. +- returns the value `0` when it has reached the end of the byte stream it was operating on. The reader is positioned on the first non-content node. -- If you ask for fewer, or the exact number of, bytes than are left in the stream the reader remains in its current position. +- If you ask for fewer, or the exact number of, bytes than are left in the stream the reader remains in its current position. -- is not supported on the following XML node types: `Element`, `XmlDeclaration`, `None`, `Document`, `DocumentType`, `Notation`, `Entity`, `DocumentFragment`. +- is not supported on the following XML node types: `Element`, `XmlDeclaration`, `None`, `Document`, `DocumentType`, `Notation`, `Entity`, `DocumentFragment`. For the asynchronous version of this method, see . @@ -4514,11 +4423,11 @@ An asynchronous method was called without This method has the following behavior: -- returns the value `0` when it has reached the end of the byte stream it was operating on. The reader is positioned on the first non-content node. +- returns the value `0` when it has reached the end of the byte stream it was operating on. The reader is positioned on the first non-content node. -- If you ask for fewer, or the exact number, of bytes than are left in the stream the reader remains in its current position. +- If you ask for fewer, or the exact number, of bytes than are left in the stream the reader remains in its current position. -- is not supported on the following XML node types: `Element`, `XmlDeclaration`, `None`, `Document`, `DocumentType`, `Notation, Entity`, `DocumentFragment`. +- is not supported on the following XML node types: `Element`, `XmlDeclaration`, `None`, `Document`, `DocumentType`, `Notation, Entity`, `DocumentFragment`. For the asynchronous version of this method, see . @@ -8219,15 +8128,15 @@ An asynchronous method was called without ## Remarks The property has one of the following values: -- , when the method is called. +- , when the method is called. -- , when the method has been called, and additional methods may be called on the reader. +- , when the method has been called, and additional methods may be called on the reader. -- , when the end of the XML document has been reached successfully. +- , when the end of the XML document has been reached successfully. -- , when the method is called. +- , when the method is called. -- , when an error is preventing the read operation from continuing. +- , when an error is preventing the read operation from continuing. ]]> diff --git a/xml/System.Xml/XmlReaderSettings.xml b/xml/System.Xml/XmlReaderSettings.xml index a4b19ef1454..1db0c633d69 100644 --- a/xml/System.Xml/XmlReaderSettings.xml +++ b/xml/System.Xml/XmlReaderSettings.xml @@ -558,47 +558,20 @@ If the is processing text data, it always checks tha Gets or sets a value that determines the processing of DTDs. One of the enumeration values that determines the processing of DTDs. The default is . - + For more information about this API, see Supplemental API remarks for XmlReaderSettings.DtdProcessing. + to enable DTD processing. - -- to throw an exception when a DTD is encountered. - -- to disable DTD processing without warnings or exceptions. - - To perform validation against a DTD, the uses the DTD defined in the DOCTYPE declaration of an XML document. The DOCTYPE declaration can either point to an inline DTD or can be a reference to an external DTD file. To validate an XML file against a DTD: - -- Set the property to `DtdProcessing.Parse.` - -- Set the property to `ValidationType.DTD`. - -- If the DTD is an external file stored on a network resource that requires authentication, pass an object with the necessary credentials to the method. - -> [!IMPORTANT] -> If the property is set to , the will not report the DTDs. This means that the DTD/DOCTYPE will be lost on output. +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlReaderSettings.DtdValidate/CPP/XmlReaderSettings.DtdValidate.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Xml/XmlReaderSettings/DtdProcessing/validdtd.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlReaderSettings.DtdValidate/VB/validdtd.vb" id="Snippet1"::: +The example uses the `itemDTD.xml` file as input. - -## Examples - The following example validates an XML file using a DTD file. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlReaderSettings.DtdValidate/CPP/XmlReaderSettings.DtdValidate.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlReaderSettings/DtdProcessing/validdtd.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlReaderSettings.DtdValidate/VB/validdtd.vb" id="Snippet1"::: - -## Input - The example uses the `itemDTD.xml` file as input. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlReaderSettings.DtdValidate/XML/itemDTD.xml" id="Snippet2"::: - - ]]> - +:::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlReaderSettings.DtdValidate/XML/itemDTD.xml" id="Snippet2"::: + ]]> + @@ -1376,44 +1349,24 @@ There is an error in XML document (MaxCharactersInDocument, ). Gets or sets the to use when performing schema validation. The to use when performing schema validation. The default is an empty object. - + For more information about this API, see Supplemental API remarks for XmlReaderSettings.Schemas. + object and the method to associate a schema with an XML document. The schema is added to the property of the object. The value of the property is an object. The schema is used to validate that the XML document conforms to the schema content model. Schema validation errors and warnings are handled by the defined in the object. -## Remarks - -> [!IMPORTANT] -> - Do not use schemas from unknown or untrusted sources or locations. Doing so will compromise the security of your code. -> - XML schemas (including inline schemas) are inherently vulnerable to denial of service attacks; do not accept them in untrusted scenarios. -> - Schema validation error messages and exceptions may expose sensitive information about the content model or URI paths to the schema file. Be careful not to expose this information to untrusted callers. -> - For additional information, see the "Security considerations" section. - - The class only supports XML Schema definition language (XSD) schemas. instances created by the method cannot be configured to enable XML-Data Reduced (XDR) schema validation. - -## Security considerations - -- Do not use schemas from unknown or untrusted sources. Doing so will compromise the security of your code. The class is used to resolve external schemas by default. To disable resolution of include, import, and redefine elements of a schema, set the property to `null`. - -- Exceptions raised as a result of using the class, such as the class may contain sensitive information that should not be exposed in untrusted scenarios. For example, the property of an returns the URI path to the schema file that caused the exception. The property should not be exposed in untrusted scenarios. Exceptions should be properly handled so that this sensitive information is not exposed in untrusted scenarios. - - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlSchemaSetOverall Example/CPP/xmlschemasetexample.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Xml/XmlReaderSettings/Schemas/xmlschemasetexample.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlSchemaSetOverall Example/VB/xmlschemasetexample.vb" id="Snippet1"::: -## Examples - The example below uses the object and the method to associate a schema with an XML document. The schema is added to the property of the object. The value of the property is an object. The schema is used to validate that the XML document conforms to the schema content model. Schema validation errors and warnings are handled by the defined in the object. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlSchemaSetOverall Example/CPP/xmlschemasetexample.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlReaderSettings/Schemas/xmlschemasetexample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlSchemaSetOverall Example/VB/xmlschemasetexample.vb" id="Snippet1"::: - - The example uses the books.xml file as input. +The example uses the books.xml file as input. - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlSchemaSetOverall Example/XML/books.xml" id="Snippet2"::: +:::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlSchemaSetOverall Example/XML/books.xml" id="Snippet2"::: - The example uses the books.xsd file as an input. +The example uses the books.xsd file as an input. - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlSchemaSetOverall Example/XML/books.xsd" id="Snippet3"::: - - ]]> - +:::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlSchemaSetOverall Example/XML/books.xsd" id="Snippet3"::: + ]]> + @@ -1525,13 +1478,11 @@ There is an error in XML document (MaxCharactersInDocument, ). ## Remarks > [!IMPORTANT] -> The and validation flags of an object are not set by default. When these flags are set, the of the object is used to resolve schema locations encountered in the instance document in the . If the object is `null`, schema locations are not resolved even if the and validation flags are set. +> The and validation flags of an object are not set by default. When these flags are set, the of the object is used to resolve schema locations encountered in the instance document in the . If the object is `null`, schema locations are not resolved even if the and validation flags are set. > -> Schemas added during validation add new types and can change the validation outcome of the document being validated. As a result, external schemas should only be resolved from trusted sources. +> Schemas added during validation add new types and can change the validation outcome of the document being validated. As a result, external schemas should only be resolved from trusted sources. > -> Disabling the flag (enabled by default) is recommended when validating, untrusted, large XML documents in high availability scenarios against a schema with identity constraints over a large part of the document. - - +> Disabling the flag (enabled by default) is recommended when validating, untrusted, large XML documents in high availability scenarios against a schema with identity constraints over a large part of the document. ## Examples The following example validates an XML file against an inline XML Schema by enabling the setting. The XML reader is configured to display validation warnings, so you also see the expected warning on the root element. @@ -1539,12 +1490,12 @@ There is an error in XML document (MaxCharactersInDocument, ). :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlReaderSettings/ValidationEventHandler/factory_rdr_cctor.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlReaderSettings.IgnoreInlineSchema/VB/factory_rdr_cctor.vb" id="Snippet1"::: -## Input The example uses the inlineSchema.xml file as input. :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlReaderSettings.IgnoreInlineSchema/XML/inlineSchema.xml" id="Snippet3"::: -## Output +The output is as follows: + Warning: Matching schema not found. No validation occurred. Could not find schema information for the element 'root'. Validation error: The element 'xsdHeadCount:HeadCount' has invalid child element 'division'. Expected 'ID'. diff --git a/xml/System/AppDomain.xml b/xml/System/AppDomain.xml index 2feadd467c7..649e660b028 100644 --- a/xml/System/AppDomain.xml +++ b/xml/System/AppDomain.xml @@ -9445,56 +9445,17 @@ This method overload uses the information from the Occurs when an exception is not caught. - + For more information about this API, see Supplemental API remarks for UnhandledException. + [!NOTE] -> In the .NET Framework versions 1.0 and 1.1, application termination and debugging options are reported to the user before this event is raised, rather than after. - - This event can be handled in any application domain. However, the event is not necessarily raised in the application domain where the exception occurred. An exception is unhandled only if the entire stack for the thread has been unwound without finding an applicable exception handler, so the first place the event can be raised is in the application domain where the thread originated. - -> [!NOTE] -> In the .NET Framework versions 1.0 and 1.1, this event occurs only for the default application domain that is created by the system when an application is started. If an application creates additional application domains, specifying a delegate for this event in those applications domains has no effect. - - If the event is handled in the default application domain, it is raised there for any unhandled exception in any thread, no matter what application domain the thread started in. If the thread started in an application domain that has an event handler for , the event is raised in that application domain. If that application domain is not the default application domain, and there is also an event handler in the default application domain, the event is raised in both application domains. - - For example, suppose a thread starts in application domain "AD1", calls a method in application domain "AD2", and from there calls a method in application domain "AD3", where it throws an exception. The first application domain in which the event can be raised is "AD1". If that application domain is not the default application domain, the event can also be raised in the default application domain. - -> [!NOTE] -> The common language runtime suspends thread aborts while event handlers for the event are executing. - - If the event handler has a attribute with the appropriate flags, the event handler is treated as a constrained execution region. - - Starting with the .NET Framework 4, this event is not raised for exceptions that corrupt the state of the process, such as stack overflows or access violations, unless the event handler is security-critical and has the attribute. - - In the .NET Framework versions 1.0 and 1.1, an unhandled exception that occurs in a thread other than the main application thread is caught by the runtime and therefore does not cause the application to terminate. Thus, it is possible for the event to be raised without the application terminating. Starting with the .NET Framework version 2.0, this backstop for unhandled exceptions in child threads was removed, because the cumulative effect of such silent failures included performance degradation, corrupted data, and lockups, all of which were difficult to debug. For more information, including a list of cases in which the runtime does not terminate, see [Exceptions in Managed Threads](/dotnet/standard/threading/exceptions-in-managed-threads). - - To register an event handler for this event, you must have the required permissions, or a is thrown. - - For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). - -## Other Events for Unhandled Exceptions - For certain application models, the event can be preempted by other events if the unhandled exception occurs in the main application thread. - - In applications that use Windows Forms, unhandled exceptions in the main application thread cause the event to be raised. If this event is handled, the default behavior is that the unhandled exception does not terminate the application, although the application is left in an unknown state. In that case, the event is not raised. This behavior can be changed by using the application configuration file, or by using the method to change the mode to before the event handler is hooked up. This applies only to the main application thread. The event is raised for unhandled exceptions thrown in other threads. - - Starting with Microsoft Visual Studio 2005, the Visual Basic application framework provides another event for unhandled exceptions in the main application thread. See the event. This event has an event arguments object with the same name as the event arguments object used by , but with different properties. In particular, this event arguments object has an property that allows the application to continue running, ignoring the unhandled exception (and leaving the application in an unknown state). In that case, the event is not raised. - - - -## Examples - The following example demonstrates the event. It defines an event handler, `MyHandler`, that is invoked whenever an unhandled exception is thrown in the default application domain. It then throws two exceptions. The first is handled by a **try/catch** block. The second is unhandled and invokes the `MyHandle` routine before the application terminates. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AppDomain_UnhandledException/CPP/unhandledexception.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/AppDomain/UnhandledException/unhandledexception.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/AppDomain/UnhandledException/unhandledexception.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AppDomain_UnhandledException/VB/unhandledexception.vb" id="Snippet1"::: - - ]]> - +The following example demonstrates the event. It defines an event handler, `MyHandler`, that is invoked whenever an unhandled exception is thrown in the default application domain. It then throws two exceptions. The first is handled by a **try/catch** block. The second is unhandled and invokes the `MyHandle` routine before the application terminates. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AppDomain_UnhandledException/CPP/unhandledexception.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/AppDomain/UnhandledException/unhandledexception.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/AppDomain/UnhandledException/unhandledexception.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AppDomain_UnhandledException/VB/unhandledexception.vb" id="Snippet1"::: + ]]> + @@ -9565,10 +9526,6 @@ In .NET Framework version 2.0 and later, there is a thread dedicated to unloadin The threads in `domain` are terminated using the method, which throws a in the thread. Although the thread should terminate promptly, it can continue executing for an unpredictable amount of time in a `finally` clause. -## Version compatibility - -In .NET Framework version 1.0 and 1.1, if the thread that calls is running in `domain`, another thread is started to perform the unload operation. If `domain` cannot be unloaded, a is thrown in that thread, not in the original thread that called . However, if the thread that calls is running outside `domain`, that thread receives the exception. - ## Examples The following code example shows how to unload an application domain. diff --git a/xml/System/DateTime.xml b/xml/System/DateTime.xml index 41ac6c66a53..1cfba7fbc5b 100644 --- a/xml/System/DateTime.xml +++ b/xml/System/DateTime.xml @@ -3214,37 +3214,7 @@ The value parameter is rounded to the nearest integer. A 64-bit signed integer that encodes the property in a 2-bit field and the property in a 62-bit field. Deserializes a 64-bit binary value and recreates an original serialized object. An object that is equivalent to the object that was serialized by the method. - - method to convert the value of the current object to a binary value. Subsequently, use the binary value and the method to recreate the original object. - -> [!IMPORTANT] -> In some cases, the value returned by the method is not identical to the original value supplied to the method. For more information, see the next section, "Local Time Adjustment". - -## Local Time Adjustment - A local time, which is a Coordinated Universal Time adjusted to the local time zone, is represented by a structure whose property has the value . When restoring a local value from the binary representation that is produced by the method, the method may adjust the recreated value so that it is not equal to the original value. This can occur under the following conditions: - -- If a local object is serialized in one time zone by the method, and then deserialized in a different time zone by the method, the local time represented by the resulting object is automatically adjusted to the second time zone. - - For example, consider a object that represents a local time of 3 P.M. An application that is executing in the U.S. Pacific Time zone uses the method to convert that object to a binary value. Another application that is executing in the U.S. Eastern Time zone then uses the method to convert the binary value to a new object. The value of the new object is 6 P.M., which represents the same point in time as the original 3 P.M. value, but is adjusted to local time in the Eastern Time zone. - -- If the binary representation of a local value represents an invalid time in the local time zone of the system on which is called, the time is adjusted so that it is valid. - - For example, the transition from standard time to daylight saving time occurs in the Pacific Time zone of the United States on March 14, 2010, at 2:00 A.M., when the time advances by one hour, to 3:00 A.M. This hour interval is an invalid time, that is, a time interval that does not exist in this time zone. The following example shows that when a time that falls within this range is converted to a binary value by the method and is then restored by the method, the original value is adjusted to become a valid time. You can determine whether a particular date and time value may be subject to modification by passing it to the method, as the example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System/DateTime/FromBinary/frombinary1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetime.frombinary/fs/frombinary1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.datetime.frombinary/vb/frombinary1.vb" id="Snippet1"::: - -## Version Considerations - Starting with the .NET Framework version 2.0, a structure consists of a private Kind field, which indicates whether the specified time is local time, Coordinated Universal Time (UTC), or neither, concatenated to a private Ticks field, which contains the number of 100-nanosecond ticks that specify a date and time. The number of ticks can be accessed with the property and theKind field can be accessed with the property. - - Prior to the .NET Framework 2.0, if you serialized a object manually instead of using a serialization interface such as , you needed to serialize only the Ticks data in the . Starting with the .NET Framework 2.0, you must also serialize the Kind data. - - ]]> - + For more information about this API, see Supplemental API remarks for DateTime.FromBinary. is less than DateTime.MinValue or greater than DateTime.MaxValue. @@ -8003,37 +7973,7 @@ In general, the ticks represent the time according to the time zone specified by Serializes the current object to a 64-bit binary value that subsequently can be used to recreate the object. A 64-bit signed integer that encodes the and properties. - - method to convert the value of the current object to a binary value. Subsequently, use the binary value and the method to recreate the original object. - -> [!IMPORTANT] -> In some cases, the value returned by the method is not identical to the original value supplied to the method. For more information, see the next section, "Local Time Adjustment". - -## Local Time Adjustment - A local time, which is a Coordinated Universal Time adjusted to the local time zone, is represented by a structure whose property has the value . When restoring a local value from the binary representation that is produced by the method, the method may adjust the recreated value so that it is not equal to the original value. This can occur under the following conditions: - -- If a local object is serialized in one time zone by the method, and then deserialized in a different time zone by the method, the local time represented by the resulting object is automatically adjusted to the second time zone. - - For example, consider a object that represents a local time of 3 P.M. An application that is executing in the U.S. Pacific Time zone uses the method to convert that object to a binary value. Another application that is executing in the U.S. Eastern Time zone uses the method to convert the binary value to a new object. The value of the new object is 6 P.M., which represents the same point in time as the original 3 P.M. value, but is adjusted to local time in the Eastern Time zone. - -- If the binary representation of a local value represents an invalid time in the local time zone of the system on which is called, the time is adjusted so that it is valid. - - For example, the transition from standard time to daylight saving time occurs in the U.S. Pacific Time zone on March 14, 2010, at 2:00 A.M., when the time advances by one hour, to 3:00 A.M. This hour interval is an invalid time, that is, a time interval that does not exist in this time zone. The following example shows that when a time that falls within this range is converted to a binary value by the method and is then restored by the method, the original value is adjusted to become a valid time. You can determine whether a particular date and time value may be subject to modification by passing it to the method, as the example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System/DateTime/FromBinary/frombinary1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetime.frombinary/fs/frombinary1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.datetime.frombinary/vb/frombinary1.vb" id="Snippet1"::: - -## Version Considerations - Starting with the .NET Framework version 2.0, a structure consists of a private Kind field, which indicates whether the specified time value is based on local time, Coordinated Universal Time (UTC), or neither, and a private Ticks field, which contains the number of 100-nanosecond ticks that specify a date and time. The Ticks field can be accessed with the property and the Kind field can be accessed with the property. - - Prior to the .NET Framework 2.0, if you serialized a object manually instead of using a serialization interface such as , you only needed to serialize the Ticks data in the structure. Starting with version 2.0, you must also serialize the Kind data. - - ]]> - + For more information about this API, see Supplemental API remarks for DateTime.ToBinary. @@ -9751,64 +9691,16 @@ The following example illustrates how the string representation of a Converts the specified string representation of a date and time to its equivalent using the specified culture-specific format information and formatting style, and returns a value that indicates whether the conversion succeeded. if the parameter was converted successfully; otherwise, . - + For more information about this API, see Supplemental API remarks for DateTime.TryParse. + method parses a string that can contain date, time, and time zone information. It is similar to the method, except that the method does not throw an exception if the conversion fails. - - This method attempts to ignore unrecognized data and parse `s` completely. If `s` contains a time but no date, the method by default substitutes the current date or, if `styles` includes the flag, it substitutes `DateTime.Date.MinValue`. If `s` contains a date but no time, 12:00 midnight is used as the default time. If a date is present but its year component consists of only two digits, it is converted to a year in the `provider` parameter's current calendar based on the value of the property. Any leading, inner, or trailing white space characters in `s` are ignored. The date and time can be bracketed with a pair of leading and trailing NUMBER SIGN characters ('#', U+0023), and can be trailed with one or more NULL characters (U+0000). - - Specific valid formats for date and time elements, as well as the names and symbols used in dates and times, are defined by the `provider` parameter, which can be any of the following: - -- A object that represents the culture whose formatting is used in the `s` parameter. The object returned by the property defines the formatting used in `s`. - -- A object that defines the formatting used in `s`. - -- A custom implementation. Its method returns a object that defines the formatting used in `s`. - - If `provider` is `null`, the current culture is used. - - If `s` is the string representation of a leap day in a leap year in the current calendar, the method parses `s` successfully. If `s` is the string representation of a leap day in a non-leap year in the current calendar of `provider`, the parse operation fails and the method returns `false`. - - The `styles` parameter defines the precise interpretation of the parsed string and how the parse operation should handle it. It can be one or more members of the enumeration, as described in the following table. - -|DateTimeStyles member|Description| -|---------------------------|-----------------| -||Parses `s` and, if necessary, converts it to UTC. If `s` includes a time zone offset, or if `s` contains no time zone information but `styles` includes the flag, the method parses the string, calls to convert the returned value to UTC, and sets the property to . If `s` indicates that it represents UTC, or if `s` does not contain time zone information but `styles` includes the flag, the method parses the string, performs no time zone conversion on the returned value, and sets the property to . In all other cases, the flag has no effect.| -||Although valid, this value is ignored. Inner white space is permitted in the date and time elements of `s`.| -||Although valid, this value is ignored. Leading white space is permitted in the date and time elements of `s`.| -||Although valid, this value is ignored. Trailing white space is permitted in the date and time elements of `s`.| -||Specifies that `s` may contain leading, inner, and trailing white spaces. This is the default behavior. It cannot be overridden by supplying a more restrictive enumeration value such as .| -||Specifies that if `s` lacks any time zone information, it is assumed to represent a local time. Unless the flag is present, the property of the returned value is set to .| -||Specifies that if `s` lacks any time zone information, it is assumed to represent UTC. Unless the flag is present, the method converts the returned value from UTC to local time and sets its property to .| -||Although valid, this value is ignored.| -||For strings that contain time zone information, tries to prevent the conversion of a date and time string to a value with its property set to . Typically, such a string is created by calling the method using either the "o", "r", or "u" standard format specifiers.| - - If `s` contains no time zone information, the method returns a value whose property is unless a `styles` flag indicates otherwise. If `s` includes time zone or time zone offset information, the method performs any necessary time conversion and returns one of the following: - -- A value whose date and time reflect the local time and whose property is . - -- Or, if `styles` includes the flag, a value whose date and time reflect UTC and whose property is . - - This behavior can be overridden by using the flag. - -## Parsing Custom Cultures - If you parse a date and time string generated for a custom culture, use the method instead of the method to improve the probability that the parse operation will succeed. A custom culture date and time string can be complicated and difficult to parse. The method attempts to parse a string with several implicit parse patterns, all of which might fail. In contrast, the method requires you to explicitly designate one or more exact parse patterns that are likely to succeed. - - For more information about custom cultures, see the class. - - - -## Examples - The following example illustrates the method. +The following example illustrates the method. :::code language="csharp" source="~/snippets/csharp/System/DateTime/TryParse/tryparse2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTime.TryParse/fs/tryparse2.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.TryParse/vb/tryparse2.vb" id="Snippet2"::: - - ]]> - + ]]> + is not a valid value. diff --git a/xml/System/Delegate.xml b/xml/System/Delegate.xml index c7a177e5e00..c667d63e5b5 100644 --- a/xml/System/Delegate.xml +++ b/xml/System/Delegate.xml @@ -81,63 +81,55 @@ Represents a delegate, which is a data structure that refers to a static method or to a class instance and an instance method of that class. - class is the base class for delegate types. However, only the system and compilers can derive explicitly from the class or from the class. It is also not permissible to derive a new type from a delegate type. The class is not considered a delegate type; it is a class used to derive delegate types. - - Most languages implement a `delegate` keyword, and compilers for those languages are able to derive from the class; therefore, users should use the `delegate` keyword provided by the language. - + class is the base class for delegate types. However, only the system and compilers can derive explicitly from the class or from the class. It is also not permissible to derive a new type from a delegate type. The class is not considered a delegate type; it is a class used to derive delegate types. + + Most languages implement a `delegate` keyword, and compilers for those languages are able to derive from the class; therefore, users should use the `delegate` keyword provided by the language. + > [!NOTE] -> The common language runtime provides an `Invoke` method for each delegate type, with the same signature as the delegate. You do not have to call this method explicitly from C#, Visual Basic, or Visual C++, because the compilers call it automatically. The `Invoke` method is useful in [reflection](/dotnet/framework/reflection-and-codedom/reflection) when you want to find the signature of the delegate type. - - The common language runtime provides each delegate type with `BeginInvoke` and `EndInvoke` methods, to enable asynchronous invocation of the delegate. For more information about these methods, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - - The declaration of a delegate type establishes a contract that specifies the signature of one or more methods. A delegate is an instance of a delegate type that has references to: - -- An instance method of a type and a target object assignable to that type. - -- An instance method of a type, with the hidden `this` parameter exposed in the formal parameter list. The delegate is said to be an open instance delegate. - -- A static method. - -- A static method and a target object assignable to the first parameter of the method. The delegate is said to be closed over its first argument. - - For more information on delegate binding, see the method overload. - - When a delegate represents an instance method closed over its first argument (the most common case), the delegate stores a reference to the method's entry point and a reference to an object, called the target, which is of a type assignable to the type that defined the method. When a delegate represents an open instance method, it stores a reference to the method's entry point. The delegate signature must include the hidden `this` parameter in its formal parameter list; in this case, the delegate does not have a reference to a target object, and a target object must be supplied when the delegate is invoked. - +> The common language runtime provides an `Invoke` method for each delegate type, with the same signature as the delegate. You do not have to call this method explicitly from C#, Visual Basic, or Visual C++, because the compilers call it automatically. The `Invoke` method is useful in [reflection](/dotnet/framework/reflection-and-codedom/reflection) when you want to find the signature of the delegate type. + + The common language runtime provides each delegate type with `BeginInvoke` and `EndInvoke` methods, to enable asynchronous invocation of the delegate. For more information about these methods, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + + The declaration of a delegate type establishes a contract that specifies the signature of one or more methods. A delegate is an instance of a delegate type that has references to: + +- An instance method of a type and a target object assignable to that type. + +- An instance method of a type, with the hidden `this` parameter exposed in the formal parameter list. The delegate is said to be an open instance delegate. + +- A static method. + +- A static method and a target object assignable to the first parameter of the method. The delegate is said to be closed over its first argument. + + For more information on delegate binding, see the method overload. + + When a delegate represents an instance method closed over its first argument (the most common case), the delegate stores a reference to the method's entry point and a reference to an object, called the target, which is of a type assignable to the type that defined the method. When a delegate represents an open instance method, it stores a reference to the method's entry point. The delegate signature must include the hidden `this` parameter in its formal parameter list; in this case, the delegate does not have a reference to a target object, and a target object must be supplied when the delegate is invoked. + When a delegate represents a static method, the delegate stores a reference to the method's entry point. When a delegate represents a static method closed over its first argument, the delegate stores a reference to the method's entry point and a reference to a target object assignable to the type of the method's first argument. When the delegate is invoked, the first argument of the static method receives the target object. This first argument must be a reference type. - - The invocation list of a delegate is an ordered set of delegates in which each element of the list invokes exactly one of the methods represented by the delegate. An invocation list can contain duplicate methods. During an invocation, methods are invoked in the order in which they appear in the invocation list. A delegate attempts to invoke every method in its invocation list; duplicates are invoked once for each time they appear in the invocation list. Delegates are immutable; once created, the invocation list of a delegate does not change. - - Delegates are referred to as multicast, or combinable, because a delegate can invoke one or more methods and can be used in combining operations. - - Combining operations, such as and , do not alter existing delegates. Instead, such an operation returns a new delegate that contains the results of the operation, an unchanged delegate, or `null`. A combining operation returns `null` when the result of the operation is a delegate that does not reference at least one method. A combining operation returns an unchanged delegate when the requested operation has no effect. - + + The invocation list of a delegate is an ordered set of delegates in which each element of the list invokes exactly one of the methods represented by the delegate. An invocation list can contain duplicate methods. During an invocation, methods are invoked in the order in which they appear in the invocation list. A delegate attempts to invoke every method in its invocation list; duplicates are invoked once for each time they appear in the invocation list. Delegates are immutable; once created, the invocation list of a delegate does not change. + + Delegates are referred to as multicast, or combinable, because a delegate can invoke one or more methods and can be used in combining operations. + + Combining operations, such as and , do not alter existing delegates. Instead, such an operation returns a new delegate that contains the results of the operation, an unchanged delegate, or `null`. A combining operation returns `null` when the result of the operation is a delegate that does not reference at least one method. A combining operation returns an unchanged delegate when the requested operation has no effect. + > [!NOTE] -> Managed languages use the and methods to implement delegate operations. Examples include the `AddHandler` and `RemoveHandler` statements in Visual Basic and the += and -= operators on delegate types in C#. - - Starting with the .NET Framework 4, generic delegate types can have variant type parameters. Contravariant type parameters can be used as parameter types of the delegate, and a covariant type parameter can be used as the return type. This feature allows generic delegate types that are constructed from the same generic type definition to be assignment-compatible if their type arguments are reference types with an inheritance relationship, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance). - +> Managed languages use the and methods to implement delegate operations. Examples include the `AddHandler` and `RemoveHandler` statements in Visual Basic and the += and -= operators on delegate types in C#. + + Starting with the .NET Framework 4, generic delegate types can have variant type parameters. Contravariant type parameters can be used as parameter types of the delegate, and a covariant type parameter can be used as the return type. This feature allows generic delegate types that are constructed from the same generic type definition to be assignment-compatible if their type arguments are reference types with an inheritance relationship, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance). + > [!NOTE] -> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, but the two delegates cannot be combined because the types do not match exactly. - - If an invoked method throws an exception, the method stops executing, the exception is passed back to the caller of the delegate, and remaining methods in the invocation list are not invoked. Catching the exception in the caller does not alter this behavior. - - When the signature of the methods invoked by a delegate includes a return value, the delegate returns the return value of the last element in the invocation list. When the signature includes a parameter that is passed by reference, the final value of the parameter is the result of every method in the invocation list executing sequentially and updating the parameter's value. - - The closest equivalent of a delegate in C is a function pointer. A delegate can represent a static method or an instance method. When the delegate represents an instance method, the delegate stores not only a reference to the method's entry point, but also a reference to the class instance. Unlike function pointers, delegates are object oriented and type safe. - - - -## Examples - The following example shows how to define a delegate named `myMethodDelegate`. Instances of this delegate are created for an instance method and a static method of the nested `mySampleClass` class. The delegate for the instance method requires an instance of `mySampleClass`. The `mySampleClass` instance is saved in a variable named `mySC`. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Delegate Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Delegate/Overview/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/Overview/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Delegate Example/VB/source.vb" id="Snippet1"::: +> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, but the two delegates cannot be combined because the types do not match exactly. + + If an invoked method throws an exception, the method stops executing, the exception is passed back to the caller of the delegate, and remaining methods in the invocation list are not invoked. Catching the exception in the caller does not alter this behavior. + + When the signature of the methods invoked by a delegate includes a return value, the delegate returns the return value of the last element in the invocation list. When the signature includes a parameter that is passed by reference, the final value of the parameter is the result of every method in the invocation list executing sequentially and updating the parameter's value. + + The closest equivalent of a delegate in C is a function pointer. A delegate can represent a static method or an instance method. When the delegate represents an instance method, the delegate stores not only a reference to the method's entry point, but also a reference to the class instance. Unlike function pointers, delegates are object oriented and type safe. + +For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate](/dotnet/fundamentals/runtime-libraries/system-delegate-createdelegate). ]]> @@ -208,20 +200,20 @@ The name of the instance method that the delegate represents. Initializes a delegate that invokes the specified instance method on the specified class instance. - method that specifies a method name and a target object. For example, the method overload creates a delegate for an instance method with a specified name. - - This constructor creates delegates for instance methods only. An instance method is a method that is associated with an instance of a class; a static method is a method that is associated with the class itself. - + method that specifies a method name and a target object. For example, the method overload creates a delegate for an instance method with a specified name. + + This constructor creates delegates for instance methods only. An instance method is a method that is associated with an instance of a class; a static method is a method that is associated with the class itself. + ]]> - is . - - -or- - + is . + + -or- + is . There was an error binding to the target method. @@ -280,26 +272,26 @@ The name of the static method that the delegate represents. Initializes a delegate that invokes the specified static method from the specified class. - method that specifies a method name but does not specify a target object. For example, the method overload creates a static delegate for a method with a specified name. - - This constructor creates delegates for static methods only. An instance method is a method that is associated with an instance of a class; a static method is a method that is associated with the class itself. - + method that specifies a method name but does not specify a target object. For example, the method overload creates a static delegate for a method with a specified name. + + This constructor creates delegates for static methods only. An instance method is a method that is associated with an instance of a class; a static method is a method that is associated with the class itself. + ]]> - is . - - -or- - + is . + + -or- + is . - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + represents an open generic type. @@ -352,13 +344,13 @@ Creates a shallow copy of the delegate. A shallow copy of the delegate. - , target, method, and invocation list as the original delegate. - - A shallow copy creates a new instance of the same type as the original object, and then copies the nonstatic fields of the original object. If the field is a value type, a bit-by-bit copy of the field is performed. If the field is a reference type, the reference is copied but the referred object is not; therefore, the reference in the original object and the reference in the clone point to the same object. In contrast, a deep copy of an object duplicates everything directly or indirectly referenced by the fields in the object. - + , target, method, and invocation list as the original delegate. + + A shallow copy creates a new instance of the same type as the original object, and then copies the nonstatic fields of the original object. If the field is a value type, a bit-by-bit copy of the field is performed. If the field is a reference type, the reference is copied but the referred object is not; therefore, the reference in the original object and the reference in the clone point to the same object. In contrast, a deep copy of an object duplicates everything directly or indirectly referenced by the fields in the object. + ]]> @@ -442,18 +434,18 @@ Concatenates the invocation lists of an array of delegates. A new delegate with an invocation list that concatenates the invocation lists of the delegates in the array. Returns if is , if contains zero elements, or if every entry in is . - [!NOTE] -> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance), but the two delegates cannot be combined because the types do not match exactly. - - is useful for creating event handlers that call multiple methods each time an event occurs. - +> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance), but the two delegates cannot be combined because the types do not match exactly. + + is useful for creating event handlers that call multiple methods each time an event occurs. + ]]> Not all the non-null entries in are instances of the same delegate type. @@ -523,16 +515,16 @@ Concatenates the invocation lists of two delegates. A new delegate with an invocation list that concatenates the invocation lists of and in that order. Returns if is , returns if is a null reference, and returns a null reference if both and are null references. - [!NOTE] -> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance), but the two delegates cannot be combined because the types do not match exactly. - - is useful for creating event handlers that call multiple methods each time an event occurs. - +> Generic delegates that are assignment-compatible because of variance are not necessarily combinable. To be combinable, the types must match exactly. For example, suppose that a class named `Derived` is derived from a class named `Base`. A delegate of type `Action` (`Action(Of Base)` in Visual Basic) can be assigned to a variable of type `Action`, as explained in [Covariance and Contravariance](/dotnet/standard/generics/covariance-and-contravariance), but the two delegates cannot be combined because the types do not match exactly. + + is useful for creating event handlers that call multiple methods each time an event occurs. + ]]> Both and are not , and and are not instances of the same delegate type. @@ -589,15 +581,15 @@ Concatenates the invocation lists of the specified multicast (combinable) delegate and the current multicast (combinable) delegate. A new multicast (combinable) delegate with an invocation list that concatenates the invocation list of the current multicast (combinable) delegate and the invocation list of , or the current multicast (combinable) delegate if is . - . - - The invocation list can contain duplicate entries; that is, entries that refer to the same method on the same object. - + . + + The invocation list can contain duplicate entries; that is, entries that refer to the same method on the same object. + ]]> Always thrown. @@ -657,96 +649,34 @@ Creates a delegate of the specified type to represent the specified method. A delegate of the specified type to represent the specified method. - method overload, which allows you to create all combinations of open or closed delegates for instance or static methods, and optionally to specify a first argument. - -> [!NOTE] -> This method overload should be used when the delegate is not closed over its first argument, because it is somewhat faster in that case. - - This method overload is equivalent to calling the method overload and specifying `true` for `throwOnBindFailure`. - -> [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public methods if the caller has been granted with the flag and if the grant set of the non-public methods is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - -## Compatible Parameter Types and Return Type - In the .NET Framework version 2.0, the parameter types and return type of a delegate created using this method overload must be compatible with the parameter types and return type of the method the delegate represents; the types do not have to match exactly. This represents a relaxation of the binding behavior in the .NET Framework version 1.0 and 1.1, where the types must match exactly. - - A parameter of a delegate is compatible with the corresponding parameter of a method if the type of the delegate parameter is more restrictive than the type of the method parameter, because this guarantees that an argument passed to the delegate can be passed safely to the method. - - Similarly, the return type of a delegate is compatible with the return type of a method if the return type of the method is more restrictive than the return type of the delegate, because this guarantees that the return value of the method can be cast safely to the return type of the delegate. - - For example, a delegate with a parameter of type and a return type of can represent a method with a parameter of type and a return value of type . - - - -## Examples - This section contains two code examples. The first example demonstrates the two kinds of delegates that can be created with this method overload: open over an instance method and open over a static method. - - The second code example demonstrates compatible parameter types and return types. - - **Example 1** - - The following code example demonstrates the two ways a delegate can be created using this overload of the method. - + method overload, which allows you to create all combinations of open or closed delegates for instance or static methods, and optionally to specify a first argument. + > [!NOTE] -> There are two overloads of the method that specify a but not a first argument; their functionality is the same except that one allows you to specify whether to throw on failure to bind, and the other always throws. This code example uses both overloads. - - The example declares a class `C` with a static method `M2` and an instance method `M1`, and two delegate types: `D1` takes an instance of `C` and a string, and `D2` takes a string. - - A second class named `Example` contains the code that creates the delegates. - -- A delegate of type `D1`, representing an open instance method, is created for the instance method `M1`. An instance must be passed when the delegate is invoked. - -- A delegate of type `D2`, representing an open static method, is created for the static method `M2`. - - :::code language="csharp" source="~/snippets/csharp/System/Delegate/CreateDelegate/openClosedOver.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/CreateDelegate/openClosedOver.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM/VB/openClosedOver.vb" id="Snippet1"::: - - **Example 2** - - The following code example demonstrates compatibility of parameter types and return types. - - The code example defines a base class named `Base` and a class named `Derived` that derives from `Base`. The derived class has a `static` (`Shared` in Visual Basic) method named `MyMethod` with one parameter of type `Base` and a return type of `Derived`. The code example also defines a delegate named `Example` that has one parameter of type `Derived` and a return type of `Base`. - - The code example demonstrates that the delegate named `Example` can be used to represent the method `MyMethod`. The method can be bound to the delegate because: - -- The parameter type of the delegate (`Derived`) is more restrictive than the parameter type of `MyMethod` (`Base`), so that it is always safe to pass the argument of the delegate to `MyMethod`. - -- The return type of `MyMethod` (`Derived`) is more restrictive than the parameter type of the delegate (`Base`), so that it is always safe to cast the return type of the method to the return type of the delegate. - - The code example produces no output. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Delegate/CreateDelegate/source1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/CreateDelegate/source1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/vb/source.vb" id="Snippet1"::: - - ]]> +> This method overload should be used when the delegate is not closed over its first argument, because it is somewhat faster in that case. + +For more information about this API, see [Supplemental API remarks for System.Delegate.CreateDelegate](/dotnet/fundamentals/runtime-libraries/system-delegate-createdelegate). + ]]> - is . - - -or- - + is . + + -or- + is . - does not inherit . - - -or- - - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - - cannot be bound. - - -or- - + does not inherit . + + -or- + + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + + cannot be bound. + + -or- + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). The method of is not found. The caller does not have the permissions necessary to access . @@ -808,158 +738,38 @@ Creates a delegate of the specified type that represents the specified static or instance method, with the specified first argument. A delegate of the specified type that represents the specified static or instance method. - method overload and specifying `true` for `throwOnBindFailure`. These two overloads provide the most flexible way to create delegates. You can use them to create delegates for either static or instance methods, and optionally to specify the first argument. - -> [!NOTE] -> If you do not supply a first argument, use the method overload for better performance. - - The delegate type and the method must have compatible return types. That is, the return type of `method` must be assignable to the return type of `type`. - - If `firstArgument` is supplied, it is passed to `method` every time the delegate is invoked; `firstArgument` is said to be bound to the delegate, and the delegate is said to be closed over its first argument. If `method` is `static` (`Shared` in Visual Basic), the argument list supplied when invoking the delegate includes all parameters except the first; if `method` is an instance method, then `firstArgument` is passed to the hidden instance parameter (represented by `this` in C#, or by `Me` in Visual Basic). - - If `firstArgument` is supplied, the first parameter of `method` must be a reference type, and `firstArgument` must be compatible with that type. - -> [!IMPORTANT] -> If `method` is `static` (`Shared` in Visual Basic) and its first parameter is of type or , then `firstArgument` can be a value type. In this case `firstArgument` is automatically boxed. Automatic boxing does not occur for any other arguments, as it would in a C# or Visual Basic function call. - - If `firstArgument` is a null reference and `method` is an instance method, the result depends on the signatures of the delegate type `type` and of `method`: - -- If the signature of `type` explicitly includes the hidden first parameter of `method`, the delegate is said to represent an open instance method. When the delegate is invoked, the first argument in the argument list is passed to the hidden instance parameter of `method`. - -- If the signatures of `method` and `type` match (that is, all parameter types are compatible), then the delegate is said to be closed over a null reference. Invoking the delegate is like calling an instance method on a null instance, which is not a particularly useful thing to do. - - If `firstArgument` is a null reference and `method` is static, the result depends on the signatures of the delegate type `type` and of `method`: - -- If the signature of `method` and `type` match (that is, all parameter types are compatible), the delegate is said to represent an open static method. This is the most common case for static methods. In this case, you can get slightly better performance by using the method overload. - -- If the signature of `type` begins with the second parameter of `method` and the rest of the parameter types are compatible, then the delegate is said to be closed over a null reference. When the delegate is invoked, a null reference is passed to the first parameter of `method`. - -> [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public methods if the caller has been granted with the flag and if the grant set of the non-public methods is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - -## Compatible Parameter Types and Return Type - The parameter types and return type of a delegate must be compatible with the parameter types and return type of the method the delegate represents; the types do not have to match exactly. - - A parameter of a delegate is compatible with the corresponding parameter of a method if the type of the delegate parameter is more restrictive than the type of the method parameter, because this guarantees that an argument passed to the delegate can be passed safely to the method. - - Similarly, the return type of a delegate is compatible with the return type of a method if the return type of the method is more restrictive than the return type of the delegate, because this guarantees that the return value of the method can be cast safely to the return type of the delegate. - - For example, a delegate with a parameter of type and a return type of can represent a method with a parameter of type and a return value of type . - -## Determining the Methods a Delegate Can Represent - Another useful way to think of the flexibility provided by this overload of is that any given delegate can represent four different combinations of method signature and method kind (static versus instance). Consider a delegate type `D` with one argument of type `C`. The following describes the methods `D` can represent, ignoring the return type since it must match in all cases: - -- `D` can represent any instance method that has exactly one argument of type `C`, regardless of what type the instance method belongs to. When is called, `firstArgument` is an instance of the type `method` belongs to, and the resulting delegate is said to be closed over that instance. (Trivially, `D` can also be closed over a null reference if `firstArgument` is a null reference.) - -- `D` can represent an instance method of `C` that has no arguments. When is called, `firstArgument` is a null reference. The resulting delegate represents an open instance method, and an instance of `C` must be supplied each time it is invoked. - -- `D` can represent a static method that takes one argument of type `C`, and that method can belong to any type. When is called, `firstArgument` is a null reference. The resulting delegate represents an open static method, and an instance of `C` must be supplied each time it is invoked. - -- `D` can represent a static method that belongs to type `F` and has two arguments, of type `F` and type `C`. When is called, `firstArgument` is an instance of `F`. The resulting delegate represents a static method that is closed over that instance of `F`. Note that in the case where `F` and `C` are the same type, the static method has two arguments of that type. (In this case, `D` is closed over a null reference if `firstArgument` is a null reference.) - - - -## Examples - This section contains three code examples. The first example demonstrates the four kinds of delegates that can be created: closed over an instance method, open over an instance method, open over a static method, and closed over a static method. - - The second code example demonstrates compatible parameter types and return types. - - The third code example defines a single delegate type, and shows all the methods that delegate type can represent. - - **Example 1** - - The following code example demonstrates the four ways a delegate can be created using this overload of the method. - -> [!NOTE] -> There are two overloads of the method that specify `firstArgument` and a ; their functionality is the same except that one allows you to specify whether to throw on failure to bind, and the other always throws. This code example uses both overloads. - - The example declares a class `C` with a static method `M2` and an instance method `M1`, and three delegate types: `D1` takes an instance of `C` and a string, `D2` takes a string, and `D3` has no arguments. - - A second class named `Example` contains the code that creates the delegates. - -- A delegate of type `D2`, closed over an instance of `C`, is created for the instance method `M1`. It is invoked with different strings, to show that the bound instance of `C` is always used. - -- A delegate of type `D1`, representing an open instance method, is created for the instance method `M1`. An instance must be passed when the delegate is invoked. - -- A delegate of type `D2`, representing an open static method, is created for the static method `M2`. - -- Finally, a delegate of type `D3`, closed over a string, is created for the static method `M2`. The method is invoked to show that it uses the bound string. - - :::code language="csharp" source="~/snippets/csharp/System/Delegate/CreateDelegate/openClosedOver.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/CreateDelegate/openClosedOver.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM/VB/openClosedOver.vb" id="Snippet1"::: - - **Example 2** - - The following code example demonstrates compatibility of parameter types and return types. - -> [!NOTE] -> This code example uses the method overload. The use of other overloads that take is similar. - - The code example defines a base class named `Base` and a class named `Derived` that derives from `Base`. The derived class has a `static` (`Shared` in Visual Basic) method named `MyMethod` with one parameter of type `Base` and a return type of `Derived`. The code example also defines a delegate named `Example` that has one parameter of type `Derived` and a return type of `Base`. - - The code example demonstrates that the delegate named `Example` can be used to represent the method `MyMethod`. The method can be bound to the delegate because: - -- The parameter type of the delegate (`Derived`) is more restrictive than the parameter type of `MyMethod` (`Base`), so that it is always safe to pass the argument of the delegate to `MyMethod`. - -- The return type of `MyMethod` (`Derived`) is more restrictive than the parameter type of the delegate (`Base`), so that it is always safe to cast the return type of the method to the return type of the delegate. - - The code example produces no output. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Delegate/CreateDelegate/source1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/CreateDelegate/source1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/vb/source.vb" id="Snippet1"::: - - **Example 3** - - The following code example shows all the methods a single delegate type can represent, using the method to create the delegates. - + method overload and specifying `true` for `throwOnBindFailure`. These two overloads provide the most flexible way to create delegates. You can use them to create delegates for either static or instance methods, and optionally to specify the first argument. + > [!NOTE] -> There are two overloads of the method that specify `firstArgument` and a ; their functionality is the same except that one allows you to specify whether to throw on failure to bind, and the other always throws. This code example uses both overloads. - - The code example defines two classes, `C` and `F`, and a delegate type `D` with one argument of type `C`. The classes have matching static and instance methods `M1`, `M3`, and `M4`, and class `C` also has an instance method `M2` that has no arguments. - - A third class named `Example` contains the code that creates the delegates. - -- Delegates are created for instance method `M1` of type `C` and type `F`; each is closed over an instance of the respective type. Method `M1` of type `C` displays the `ID` properties of the bound instance and of the argument. - -- A delegate is created for method `M2` of type `C`. This is an open instance delegate, in which the argument of the delegate represents the hidden first argument on the instance method. The method has no other arguments. It is called as if it were a static method. - -- Delegates are created for static method `M3` of type `C` and type `F`; these are open static delegates. - -- Finally, delegates are created for static method `M4` of type `C` and type `F`; each method has the declaring type as its first argument, and an instance of the type is supplied, so the delegates are closed over their first arguments. Method `M4` of type `C` displays the `ID` properties of the bound instance and of the argument. - - :::code language="csharp" source="~/snippets/csharp/System/Delegate/CreateDelegate/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/CreateDelegate/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM_2/vb/source.vb" id="Snippet1"::: +> If you don't supply a first argument, use the method overload for better performance. + +For more information about this API, see [Supplemental API remarks for System.Delegate.CreateDelegate](/dotnet/fundamentals/runtime-libraries/system-delegate-createdelegate). ]]> - is . - - -or- - + is . + + -or- + is . - does not inherit . - - -or- - - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - - cannot be bound. - - -or- - + does not inherit . + + -or- + + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + + cannot be bound. + + -or- + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). The method of is not found. The caller does not have the permissions necessary to access . @@ -1020,43 +830,38 @@ Creates a delegate of the specified type that represents the specified instance method to invoke on the specified class instance. A delegate of the specified type that represents the specified instance method to invoke on the specified class instance. - method overload, specifying `false` for `ignoreCase` and `true` for `throwOnBindFailure`. - -> [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public methods if the caller has been granted with the flag and if the grant set of the non-public methods is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - + method overload, specifying `false` for `ignoreCase` and `true` for `throwOnBindFailure`. + ]]> - is . - - -or- - - is . - - -or- - + is . + + -or- + + is . + + -or- + is . - does not inherit . - - -or- - - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - - is not an instance method. - - -or- - + does not inherit . + + -or- + + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + + is not an instance method. + + -or- + cannot be bound, for example because it cannot be found. The method of is not found. The caller does not have the permissions necessary to access . @@ -1118,97 +923,37 @@ Creates a delegate of the specified type to represent the specified static method, with the specified behavior on failure to bind. A delegate of the specified type to represent the specified static method. - method overload, which allows you to create all combinations of open or closed delegates for instance or static methods. - -> [!NOTE] -> This method overload should be used when the delegate is not closed over its first argument, because it is somewhat faster in that case. - -> [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public methods if the caller has been granted with the flag and if the grant set of the non-public methods is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - -## Compatible Parameter Types and Return Type - The parameter types and return type of a delegate must be compatible with the parameter types and return type of the method the delegate represents; the types do not have to match exactly. - - A parameter of a delegate is compatible with the corresponding parameter of a method if the type of the delegate parameter is more restrictive than the type of the method parameter, because this guarantees that an argument passed to the delegate can be passed safely to the method. - - Similarly, the return type of a delegate is compatible with the return type of a method if the return type of the method is more restrictive than the return type of the delegate, because this guarantees that the return value of the method can be cast safely to the return type of the delegate. - - For example, a delegate with a parameter of type and a return type of can represent a method with a parameter of type and a return value of type . - - - -## Examples - This section contains two code examples. The first example demonstrates the two kinds of delegates that can be created with this method overload: open over an instance method and open over a static method. - - The second code example demonstrates compatible parameter types and return types. - - **Example 1** - - The following code example demonstrates the two ways a delegate can be created using this overload of the method. - -> [!NOTE] -> There are two overloads of the method that specify a but not a first argument; their functionality is the same except that one allows you to specify whether to throw on failure to bind, and the other always throws. This code example uses both overloads. - - The example declares a class `C` with a static method `M2` and an instance method `M1`, and two delegate types: `D1` takes an instance of `C` and a string, and `D2` takes a string. - - A second class named `Example` contains the code that creates the delegates. - -- A delegate of type `D1`, representing an open instance method, is created for the instance method `M1`. An instance must be passed when the delegate is invoked. - -- A delegate of type `D2`, representing an open static method, is created for the static method `M2`. - - :::code language="csharp" source="~/snippets/csharp/System/Delegate/CreateDelegate/openClosedOver.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/CreateDelegate/openClosedOver.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM/VB/openClosedOver.vb" id="Snippet1"::: - - **Example 2** - - The following code example demonstrates compatibility of parameter types and return types. - + method overload, which allows you to create all combinations of open or closed delegates for instance or static methods. + > [!NOTE] -> This code example uses the method overload. The use of other overloads that take is similar. - - The code example defines a base class named `Base` and a class named `Derived` that derives from `Base`. The derived class has a `static` (`Shared` in Visual Basic) method named `MyMethod` with one parameter of type `Base` and a return type of `Derived`. The code example also defines a delegate named `Example` that has one parameter of type `Derived` and a return type of `Base`. - - The code example demonstrates that the delegate named `Example` can be used to represent the method `MyMethod`. The method can be bound to the delegate because: - -- The parameter type of the delegate (`Derived`) is more restrictive than the parameter type of `MyMethod` (`Base`), so that it is always safe to pass the argument of the delegate to `MyMethod`. - -- The return type of `MyMethod` (`Derived`) is more restrictive than the parameter type of the delegate (`Base`), so that it is always safe to cast the return type of the method to the return type of the delegate. - - The code example produces no output. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Delegate/CreateDelegate/source1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/CreateDelegate/source1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/vb/source.vb" id="Snippet1"::: - +> This method overload should be used when the delegate is not closed over its first argument, because it is somewhat faster in that case. + +For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate](/dotnet/fundamentals/runtime-libraries/system-delegate-createdelegate). + ]]> - is . - - -or- - + is . + + -or- + is . - does not inherit . - - -or- - - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - - cannot be bound, and is . - - -or- - + does not inherit . + + -or- + + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + + cannot be bound, and is . + + -or- + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). The method of is not found. The caller does not have the permissions necessary to access . @@ -1276,51 +1021,46 @@ Creates a delegate of the specified type that represents the specified static method of the specified class. A delegate of the specified type that represents the specified static method of the specified class. - method overload, specifying `false` for `ignoreCase` and `true` for `throwOnBindFailure`. - -> [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public methods if the caller has been granted with the flag and if the grant set of the non-public methods is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - + method overload, specifying `false` for `ignoreCase` and `true` for `throwOnBindFailure`. + ]]> - is . - - -or- - - is . - - -or- - + is . + + -or- + + is . + + -or- + is . - does not inherit . - - -or- - - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - - is not a . - - -or- - - is an open generic type. That is, its property is . - - -or- - - is not a method ( method in Visual Basic). - - -or- - + does not inherit . + + -or- + + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + + is not a . + + -or- + + is an open generic type. That is, its property is . + + -or- + + is not a method ( method in Visual Basic). + + -or- + cannot be bound, for example because it cannot be found, and is . The method of is not found. The caller does not have the permissions necessary to access . @@ -1391,158 +1131,37 @@ Creates a delegate of the specified type that represents the specified static or instance method, with the specified first argument and the specified behavior on failure to bind. A delegate of the specified type that represents the specified static or instance method, or if is and the delegate cannot be bound to . - method overload, which always throws on failure to bind, provide the most flexible way to create delegates. You can use them to create delegates for either static or instance methods, with or without a first argument. - -> [!NOTE] -> If you do not supply a first argument, use the method overload for better performance. - - The delegate type and the method must have compatible return types. That is, the return type of `method` must be assignable to the return type of `type`. - - If `firstArgument` is supplied, it is passed to `method` every time the delegate is invoked; `firstArgument` is said to be bound to the delegate, and the delegate is said to be closed over its first argument. If `method` is `static` (`Shared` in Visual Basic), the argument list supplied when invoking the delegate includes all parameters except the first; if `method` is an instance method, then `firstArgument` is passed to the hidden instance parameter (represented by `this` in C#, or by `Me` in Visual Basic). - - If `firstArgument` is supplied, the first parameter of `method` must be a reference type, and `firstArgument` must be compatible with that type. - -> [!IMPORTANT] -> If `method` is `static` (`Shared` in Visual Basic) and its first parameter is of type or , then `firstArgument` can be a value type. In this case `firstArgument` is automatically boxed. Automatic boxing does not occur for any other arguments, as it would in a C# or Visual Basic function call. - - If `firstArgument` is a null reference and `method` is an instance method, the result depends on the signatures of the delegate type `type` and of `method`: - -- If the signature of `type` explicitly includes the hidden first parameter of `method`, the delegate is said to represent an open instance method. When the delegate is invoked, the first argument in the argument list is passed to the hidden instance parameter of `method`. - -- If the signatures of `method` and `type` match (that is, all parameter types are compatible), then the delegate is said to be closed over a null reference. Invoking the delegate is like calling an instance method on a null instance, which is not a particularly useful thing to do. - - If `firstArgument` is a null reference and `method` is static, the result depends on the signatures of the delegate type `type` and of `method`: - -- If the signature of `method` and `type` match (that is, all parameter types are compatible), the delegate is said to represent an open static method. This is the most common case for static methods. In this case, you can get slightly better performance by using the method overload. - -- If the signature of `type` begins with the second parameter of `method` and the rest of the parameter types are compatible, then the delegate is said to be closed over a null reference. When the delegate is invoked, a null reference is passed to the first parameter of `method`. - -> [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public methods if the caller has been granted with the flag and if the grant set of the non-public methods is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - -## Compatible Parameter Types and Return Type - The parameter types and return type of a delegate must be compatible with the parameter types and return type of the method the delegate represents; the types do not have to match exactly. - - A parameter of a delegate is compatible with the corresponding parameter of a method if the type of the delegate parameter is more restrictive than the type of the method parameter, because this guarantees that an argument passed to the delegate can be passed safely to the method. - - Similarly, the return type of a delegate is compatible with the return type of a method if the return type of the method is more restrictive than the return type of the delegate, because this guarantees that the return value of the method can be cast safely to the return type of the delegate. - - For example, a delegate with a parameter of type and a return type of can represent a method with a parameter of type and a return value of type . - -## Determining the Methods a Delegate Can Represent - Another useful way to think of the flexibility provided by this overload of is that any given delegate can represent four different combinations of method signature and method kind (static versus instance). Consider a delegate type `D` with one argument of type `C`. The following describes the methods `D` can represent, ignoring the return type since it must match in all cases: - -- `D` can represent any instance method that has exactly one argument of type `C`, regardless of what type the instance method belongs to. When is called, `firstArgument` is an instance of the type `method` belongs to, and the resulting delegate is said to be closed over that instance. (Trivially, `D` can also be closed over a null reference if `firstArgument` is `null`.) - -- `D` can represent an instance method of `C` that has no arguments. When is called, `firstArgument` is a null reference. The resulting delegate represents an open instance method, and an instance of `C` must be supplied each time it is invoked. - -- `D` can represent a static method that takes one argument of type `C`, and that method can belong to any type. When is called, `firstArgument` is a null reference. The resulting delegate represents an open static method, and an instance of `C` must be supplied each time it is invoked. - -- `D` can represent a static method that belongs to type `F` and has two arguments, of type `F` and type `C`. When is called, `firstArgument` is an instance of `F`. The resulting delegate represents a static method that is closed over that instance of `F`. Note that in the case where `F` and `C` are the same type, the static method has two arguments of that type. (In this case, `D` is closed over a null reference if `firstArgument` is `null`.) - - - -## Examples - This section contains three code examples. The first example demonstrates the four kinds of delegates that can be created: closed over an instance method, open over an instance method, open over a static method, and closed over a static method. - - The second code example demonstrates compatible parameter types and return types. - - The third code example defines a single delegate type, and shows all the methods that delegate type can represent. - - **Example 1** - - The following code example demonstrates the four ways a delegate can be created using this overload of the method. - -> [!NOTE] -> There are two overloads of the method that specify `firstArgument` and a ; their functionality is the same except that one allows you to specify whether to throw on failure to bind, and the other always throws. This code example uses both overloads. - - The example declares a class `C` with a static method `M2` and an instance method `M1`, and three delegate types: `D1` takes an instance of `C` and a string, `D2` takes a string, and `D3` has no arguments. - - A second class named `Example` contains the code that creates the delegates. - -- A delegate of type `D2`, closed over an instance of `C`, is created for the instance method `M1`. It is invoked with different strings, to show that the bound instance of `C` is always used. - -- A delegate of type `D1`, representing an open instance method, is created for the instance method `M1`. An instance must be passed when the delegate is invoked. - -- A delegate of type `D2`, representing an open static method, is created for the static method `M2`. - -- Finally, a delegate of type `D3`, closed over a string, is created for the static method `M2`. The method is invoked to show that it uses the bound string. - - :::code language="csharp" source="~/snippets/csharp/System/Delegate/CreateDelegate/openClosedOver.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/CreateDelegate/openClosedOver.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM/VB/openClosedOver.vb" id="Snippet1"::: - - **Example 2** - - The following code example demonstrates compatibility of parameter types and return types. - -> [!NOTE] -> This code example uses the method overload. The use of other overloads that take is similar. - - The code example defines a base class named `Base` and a class named `Derived` that derives from `Base`. The derived class has a `static` (`Shared` in Visual Basic) method named `MyMethod` with one parameter of type `Base` and a return type of `Derived`. The code example also defines a delegate named `Example` that has one parameter of type `Derived` and a return type of `Base`. - - The code example demonstrates that the delegate named `Example` can be used to represent the method `MyMethod`. The method can be bound to the delegate because: - -- The parameter type of the delegate (`Derived`) is more restrictive than the parameter type of `MyMethod` (`Base`), so that it is always safe to pass the argument of the delegate to `MyMethod`. - -- The return type of `MyMethod` (`Derived`) is more restrictive than the parameter type of the delegate (`Base`), so that it is always safe to cast the return type of the method to the return type of the delegate. - - The code example produces no output. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Delegate/CreateDelegate/source1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/CreateDelegate/source1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegate_RelaxedFit/vb/source.vb" id="Snippet1"::: - - **Example 3** - - The following code example shows all the methods a single delegate type can represent. - + method overload, which always throws on failure to bind, provide the most flexible way to create delegates. You can use them to create delegates for either static or instance methods, with or without a first argument. + > [!NOTE] -> There are two overloads of the method that specify `firstArgument` and a ; their functionality is the same except that one allows you to specify whether to throw on failure to bind, and the other always throws. This code example uses both overloads. - - The code example defines two classes, `C` and `F`, and a delegate type `D` with one argument of type `C`. The classes have matching static and instance methods `M1`, `M3`, and `M4`, and class `C` also has an instance method `M2` that has no arguments. - - A third class named `Example` contains the code that creates the delegates. - -- Delegates are created for instance method `M1` of type `C` and type `F`; each is closed over an instance of the respective type. Method `M1` of type `C` displays the `ID` properties of the bound instance and of the argument. - -- A delegate is created for method `M2` of type `C`. This is an open instance delegate, in which the argument of the delegate represents the hidden first argument on the instance method. The method has no other arguments. - -- Delegates are created for static method `M3` of type `C` and type `F`; these are open static delegates. - -- Finally, delegates are created for static method `M4` of type `C` and type `F`; each method has the declaring type as its first argument, and an instance of the type is supplied, so the delegates are closed over their first arguments. Method `M4` of type `C` displays the `ID` properties of the bound instance and of the argument. - - :::code language="csharp" source="~/snippets/csharp/System/Delegate/CreateDelegate/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Delegate/CreateDelegate/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Delegate.CreateDelegateTOM_2/vb/source.vb" id="Snippet1"::: +> If you do not supply a first argument, use the method overload for better performance. + +For more information and examples, see [Supplemental API remarks for System.Delegate.CreateDelegate](/dotnet/fundamentals/runtime-libraries/system-delegate-createdelegate). ]]> - is . - - -or- - + is . + + -or- + is . - does not inherit . - - -or- - - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - - cannot be bound, and is . - - -or- - + does not inherit . + + -or- + + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + + cannot be bound, and is . + + -or- + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). The method of is not found. The caller does not have the permissions necessary to access . @@ -1605,43 +1224,38 @@ Creates a delegate of the specified type that represents the specified instance method to invoke on the specified class instance with the specified case-sensitivity. A delegate of the specified type that represents the specified instance method to invoke on the specified class instance. - method overload, specifying `true` for `throwOnBindFailure`. - -> [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public methods if the caller has been granted with the flag and if the grant set of the non-public methods is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - + method overload, specifying `true` for `throwOnBindFailure`. + ]]> - is . - - -or- - - is . - - -or- - + is . + + -or- + + is . + + -or- + is . - does not inherit . - - -or- - - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - - is not an instance method. - - -or- - + does not inherit . + + -or- + + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + + is not an instance method. + + -or- + cannot be bound, for example because it cannot be found. The method of is not found. The caller does not have the permissions necessary to access . @@ -1710,51 +1324,46 @@ Creates a delegate of the specified type that represents the specified static method of the specified class, with the specified case-sensitivity. A delegate of the specified type that represents the specified static method of the specified class. - method overload, specifying `true` for `throwOnBindFailure`. - -> [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public methods if the caller has been granted with the flag and if the grant set of the non-public methods is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - + method overload, specifying `true` for `throwOnBindFailure`. + ]]> - is . - - -or- - - is . - - -or- - + is . + + -or- + + is . + + -or- + is . - does not inherit . - - -or- - - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - - is not a . - - -or- - - is an open generic type. That is, its property is . - - -or- - - is not a method ( method in Visual Basic). - - -or- - + does not inherit . + + -or- + + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + + is not a . + + -or- + + is an open generic type. That is, its property is . + + -or- + + is not a method ( method in Visual Basic). + + -or- + cannot be bound, for example because it cannot be found. The method of is not found. The caller does not have the permissions necessary to access . @@ -1824,41 +1433,36 @@ Creates a delegate of the specified type that represents the specified instance method to invoke on the specified class instance, with the specified case-sensitivity and the specified behavior on failure to bind. A delegate of the specified type that represents the specified instance method to invoke on the specified class instance. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public methods if the caller has been granted with the flag and if the grant set of the non-public methods is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - + - is . - - -or- - - is . - - -or- - + is . + + -or- + + is . + + -or- + is . - does not inherit . - - -or- - - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - - is not an instance method. - - -or- - + does not inherit . + + -or- + + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + + is not an instance method. + + -or- + cannot be bound, for example because it cannot be found, and is . The method of is not found. The caller does not have the permissions necessary to access . @@ -1935,49 +1539,44 @@ Creates a delegate of the specified type that represents the specified static method of the specified class, with the specified case-sensitivity and the specified behavior on failure to bind. A delegate of the specified type that represents the specified static method of the specified class. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public methods if the caller has been granted with the flag and if the grant set of the non-public methods is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - + - is . - - -or- - - is . - - -or- - + is . + + -or- + + is . + + -or- + is . - does not inherit . - - -or- - - is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). - - -or- - - is not a . - - -or- - - is an open generic type. That is, its property is . - - -or- - - is not a method ( method in Visual Basic). - - -or- - + does not inherit . + + -or- + + is not a . See [Runtime Types in Reflection](/previous-versions/dotnet/netframework-4.0/ms172329(v=vs.100)). + + -or- + + is not a . + + -or- + + is an open generic type. That is, its property is . + + -or- + + is not a method ( method in Visual Basic). + + -or- + cannot be bound, for example because it cannot be found, and is . The method of is not found. The caller does not have the permissions necessary to access . @@ -2049,27 +1648,27 @@ - An array of objects that are the arguments to pass to the method represented by the current delegate. - - -or- - + An array of objects that are the arguments to pass to the method represented by the current delegate. + + -or- + , if the method represented by the current delegate does not require arguments. Dynamically invokes (late-bound) the method represented by the current delegate. The object returned by the method represented by the delegate. - method. - + method. + ]]> The array does not have the correct number of arguments. The elements of the array do not match the signature of the delegate. - The method represented by the delegate is an instance method and the target object is . - - -or- - + The method represented by the delegate is an instance method and the target object is . + + -or- + One of the encapsulated methods throws an exception. @@ -2128,27 +1727,27 @@ The number, order, or type of parameters listed in is i - An array of objects that are the arguments to pass to the method represented by the current delegate. - - -or- - + An array of objects that are the arguments to pass to the method represented by the current delegate. + + -or- + , if the method represented by the current delegate does not require arguments. Dynamically invokes (late-bound) the method represented by the current delegate. The object returned by the method represented by the delegate. - method. - + method. + ]]> The array does not have the correct number of arguments. The elements of the array do not match the signature of the delegate. - The method represented by the delegate is an instance method and the target object is . - - -or- - + The method represented by the delegate is an instance method and the target object is . + + -or- + One of the encapsulated methods throws an exception. @@ -2223,21 +1822,21 @@ The number, order, or type of parameters listed in is i if and the current delegate have the same targets, methods, and invocation list; otherwise, . - @@ -2286,11 +1885,11 @@ The number, order, or type of parameters listed in is i Returns a hash code for the delegate. A hash code for the delegate. - @@ -2338,22 +1937,22 @@ The number, order, or type of parameters listed in is i Returns the invocation list of the delegate. An array of delegates representing the invocation list of the current delegate. - method to get a total count of the methods assigned to the delegate, to execute the delegates in reverse order, and to execute the methods whose name do not include the substring "File". - + method to get a total count of the methods assigned to the delegate, to execute the delegates in reverse order, and to execute the methods whose name do not include the substring "File". + :::code language="csharp" source="~/snippets/csharp/System/Delegate/GetInvocationList/GetInvocationList1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/System.Delegate.GetInvocationList/fs/GetInvocationList1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Delegate.GetInvocationList/vb/GetInvocationList1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Delegate.GetInvocationList/vb/GetInvocationList1.vb" id="Snippet1"::: + ]]> @@ -2402,11 +2001,11 @@ The number, order, or type of parameters listed in is i Gets the method represented by the current delegate. A describing the method represented by the current delegate. - property. - + ]]> @@ -2586,23 +2185,23 @@ The number, order, or type of parameters listed in is i if is equal to ; otherwise, . - ]]> @@ -2663,23 +2262,23 @@ The number, order, or type of parameters listed in is i if is not equal to ; otherwise, . - ]]> @@ -2743,11 +2342,11 @@ The number, order, or type of parameters listed in is i Removes the last occurrence of the invocation list of a delegate from the invocation list of another delegate. A new delegate with an invocation list formed by taking the invocation list of and removing the last occurrence of the invocation list of , if the invocation list of is found within the invocation list of . Returns if is or if the invocation list of is not found within the invocation list of . Returns a null reference if the invocation list of is equal to the invocation list of or if is a null reference. - The delegate types do not match. @@ -2811,11 +2410,11 @@ The number, order, or type of parameters listed in is i Removes all occurrences of the invocation list of a delegate from the invocation list of another delegate. A new delegate with an invocation list formed by taking the invocation list of and removing all occurrences of the invocation list of , if the invocation list of is found within the invocation list of . Returns if is or if the invocation list of is not found within the invocation list of . Returns a null reference if the invocation list of is equal to the invocation list of , if contains only a series of invocation lists that are equal to the invocation list of , or if is a null reference. - The delegate types do not match. @@ -2867,11 +2466,11 @@ The number, order, or type of parameters listed in is i Removes the invocation list of a delegate from the invocation list of another delegate. A new delegate with an invocation list formed by taking the invocation list of the current delegate and removing the invocation list of , if the invocation list of is found within the current delegate's invocation list. Returns the current delegate if is or if the invocation list of is not found within the current delegate's invocation list. Returns if the invocation list of is equal to the current delegate's invocation list. - @@ -2931,13 +2530,13 @@ The number, order, or type of parameters listed in is i Gets the class instance on which the current delegate invokes the instance method. The object on which the current delegate invokes the instance method, if the delegate represents an instance method; if the delegate represents a static method. - diff --git a/xml/System/Double.xml b/xml/System/Double.xml index 2abbc575599..97ce4582dd4 100644 --- a/xml/System/Double.xml +++ b/xml/System/Double.xml @@ -1071,41 +1071,16 @@ This computes `arctan(x) / π` in the interval `[-0.5, +0.5]`. This instance is greater than , or this instance is a number and is not a number (). - + For more information about this API, see Double.CompareTo. + method for several value and reference types. -## Remarks - Values must be identical to be considered equal. Particularly when floating-point values depend on multiple mathematical operations, it is common for them to lose precision and for their values to be nearly identical except for their least significant digits. Because of this, the return value of the method at times may seem surprising. For example, multiplication by a particular value followed by division by the same value should produce the original value. In the following example, however, the computed value turns out to be greater than the original value. Showing all significant digits of the two values by using the "R" [standard numeric format string](/dotnet/standard/base-types/standard-numeric-format-strings) indicates that the computed value differs from the original value in its least significant digits. For information on handling such comparisons, see the Remarks section of the method. - - :::code language="csharp" source="~/snippets/csharp/System/Double/CompareTo/compareto2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Double/CompareTo/compareto2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.double.compareto/vb/compareto2.vb" id="Snippet1"::: - - This method implements the interface and performs slightly better than the method because it does not have to convert the `value` parameter to an object. - - Note that, although an object whose value is is not considered equal to another object whose value is (even itself), the interface requires that `A.CompareTo(A)` return zero. - -## Widening Conversions - Depending on your programming language, it might be possible to code a method where the parameter type has fewer bits (is narrower) than the instance type. This is possible because some programming languages perform an implicit widening conversion that represents the parameter as a type with as many bits as the instance. - - For example, suppose the instance type is and the parameter type is . The Microsoft C# compiler generates instructions to represent the value of the parameter as a object, then generates a method that compares the values of the instance and the widened representation of the parameter. - - Consult your programming language's documentation to determine if its compiler performs implicit widening conversions of numeric types. For more information, see the [Type Conversion Tables](/dotnet/standard/base-types/conversion-tables) topic. - -## Precision in Comparisons - The precision of floating-point numbers beyond the documented precision is specific to the implementation and version of the .NET Framework. Consequently, a comparison of two particular numbers might change between versions of the .NET Framework because the precision of the numbers' internal representation might change. - - - -## Examples - The following code example demonstrates generic and nongeneric versions of the method for several value and reference types. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/T.CompareTo/CPP/cat.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Boolean/CompareTo/cat.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/T.CompareTo/VB/cat.vb" id="Snippet1"::: - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/T.CompareTo/CPP/cat.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/Boolean/CompareTo/cat.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/T.CompareTo/VB/cat.vb" id="Snippet1"::: + ]]> + @@ -1173,35 +1148,16 @@ This computes `arctan(x) / π` in the interval `[-0.5, +0.5]`. This instance is equal to , or this instance and are both , , or A positive integer This instance is greater than , OR this instance is a number and is not a number (), OR is . - + For more information about this API, see Double.CompareTo. + , regardless of its value, is considered greater than `null`. - - Values must be identical to be considered equal. Particularly when floating-point values depend on multiple mathematical operations, it is common for them to lose precision and for their values to be nearly identical except for their least significant digits. Because of this, the return value of the method at times may seem surprising. For example, multiplication by a particular value followed by division by the same value should produce the original value. In the following example, however, the computed value turns out to be greater than the original value. Showing all significant digits of the two values by using the "R" [standard numeric format string](/dotnet/standard/base-types/standard-numeric-format-strings) indicates that the computed value differs from the original value in its least significant digits. For information on handling such comparisons, see the Remarks section of the method. - - :::code language="csharp" source="~/snippets/csharp/System/Double/CompareTo/compareto3.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Double/CompareTo/compareto3.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.double.compareto/vb/compareto3.vb" id="Snippet2"::: - - This method is implemented to support the interface. Note that, although a is not considered to be equal to another (even itself), the interface requires that `A.CompareTo(A)` return zero. - -## Precision in Comparisons - The precision of floating-point numbers beyond the documented precision is specific to the implementation and version of the .NET Framework. Consequently, a comparison of two particular numbers might change between versions of the .NET Framework because the precision of the numbers' internal representation might change. - - - -## Examples - The following code example illustrates the use of `CompareTo` in the context of `Double`. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Double/CPP/doublesample.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System/Double/CompareTo/doublesample.cs" id="Snippet16"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Double/CompareTo/doublesample.fs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Double/VB/doublesample.vb" id="Snippet16"::: - - ]]> - +:::code language="csharp" source="~/snippets/csharp/System/Double/CompareTo/doublesample.cs" id="Snippet16"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Double/CompareTo/doublesample.fs" id="Snippet16"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Double/VB/doublesample.vb" id="Snippet16"::: + ]]> + is not a . @@ -1650,36 +1606,7 @@ Euler's number is approximately 2.7182818284590452354. 4.94065645841247E-324 Represents the smallest positive value that is greater than zero. This field is constant. - - property reflects the smallest positive value that is significant in numeric operations or comparisons when the value of the instance is zero. For example, the following code shows that zero and are considered to be unequal values, whereas zero and half the value of are considered to be equal. - - :::code language="csharp" source="~/snippets/csharp/System/Double/Epsilon/epsilon.cs" interactive="try-dotnet" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Double/Epsilon/epsilon.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Double.Epsilon/vb/epsilon.vb" id="Snippet5"::: - - More precisely, the floating point format consists of a sign, a 52-bit mantissa or significand, and an 11-bit exponent. As the following example shows, zero has an exponent of -1022 and a mantissa of 0. has an exponent of -1022 and a mantissa of 1. This means that is the smallest positive value greater than zero and represents the smallest possible value and the smallest possible increment for a whose exponent is -1022. - - :::code language="csharp" source="~/snippets/csharp/System/Double/Epsilon/epsilon1.cs" interactive="try-dotnet" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Double/Epsilon/epsilon1.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Double.Epsilon/vb/epsilon1.vb" id="Snippet6"::: - - However, the property is not a general measure of precision of the type; it applies only to instances that have a value of zero or an exponent of -1022. - -> [!NOTE] -> The value of the property is not equivalent to machine epsilon, which represents the upper bound of the relative error due to rounding in floating-point arithmetic. - - The value of this constant is 4.94065645841247e-324. - - Two apparently equivalent floating-point numbers might not compare equal because of differences in their least significant digits. For example, the C# expression, `(double)1/3 == (double)0.33333`, does not compare equal because the division operation on the left side has maximum precision while the constant on the right side is precise only to the specified digits. If you create a custom algorithm that determines whether two floating-point numbers can be considered equal, we do not recommend that you base your algorithm on the value of the constant to establish the acceptable absolute margin of difference for the two values to be considered equal. (Typically, that margin of difference is many times greater than .) For information about comparing two double-precision floating-point values, see and . - -## Platform Notes - On ARM systems, the value of the constant is too small to be detected, so it equates to zero. You can define an alternative epsilon value that equals 2.2250738585072014E-308 instead. - - ]]> - + For more information about this API, see Supplemental API remarks for Double.Epsilon. @@ -1742,47 +1669,7 @@ Euler's number is approximately 2.7182818284590452354. Returns a value indicating whether this instance and a specified object represent the same value. if is equal to this instance; otherwise, . - - interface, and performs slightly better than because it does not have to convert the `obj` parameter to an object. - -## Widening Conversions - Depending on your programming language, it might be possible to code a method where the parameter type has fewer bits (is narrower) than the instance type. This is possible because some programming languages perform an implicit widening conversion that represents the parameter as a type with as many bits as the instance. - - For example, suppose the instance type is and the parameter type is . The Microsoft C# compiler generates instructions to represent the value of the parameter as a object, then generates a method that compares the values of the instance and the widened representation of the parameter. - - Consult your programming language's documentation to determine if its compiler performs implicit widening conversions of numeric types. For more information, see the [Type Conversion Tables](/dotnet/standard/base-types/conversion-tables) topic. - -## Precision in Comparisons - The method should be used with caution, because two apparently equivalent values can be unequal due to the differing precision of the two values. The following example reports that the value .333333 and the value returned by dividing 1 by 3 are unequal. - - :::code language="csharp" source="~/snippets/csharp/System/Double/Epsilon/Equals_25051.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Double/Epsilon/Equals_25051.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Double.Epsilon/vb/Equals_25051.vb" id="Snippet1"::: - - Rather than comparing for equality, one technique involves defining an acceptable relative margin of difference between two values (such as .001% of one of the values). If the absolute value of the difference between the two values is less than or equal to that margin, the difference is likely to be due to differences in precision and, therefore, the values are likely to be equal. The following example uses this technique to compare .33333 and 1/3, the two values that the previous code example found to be unequal. In this case, the values are equal. - - :::code language="csharp" source="~/snippets/csharp/System/Double/Epsilon/Equals_25051.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Double/Epsilon/Equals_25051.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Double.Epsilon/vb/Equals_25051.vb" id="Snippet2"::: - -> [!NOTE] -> Because defines the minimum expression of a positive value whose range is near zero, the margin of difference between two similar values must be greater than . Typically, it is many times greater than . Because of this, we recommend that you do not use when comparing values for equality. - - A second technique involves comparing the difference between two floating-point numbers with some absolute value. If the difference is less than or equal to that absolute value, the numbers are equal. If it is greater, the numbers are not equal. One alternative is to arbitrarily select an absolute value. This is problematic, however, because an acceptable margin of difference depends on the magnitude of the values. A second alternative takes advantage of a design feature of the floating-point format: The difference between the integer representation of two floating-point values indicates the number of possible floating-point values that separates them. For example, the difference between 0.0 and is 1, because is the smallest representable value when working with a whose value is zero. The following example uses this technique to compare .33333 and 1/3, which are the two values that the previous code example with the method found to be unequal. Note that the example uses the method to convert a double-precision floating-point value to its integer representation. - - :::code language="csharp" source="~/snippets/csharp/System/Double/Equals/equalsabs1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Double/Equals/equalsabs1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.double.equals/vb/equalsabs1.vb" id="Snippet1"::: - - The precision of floating-point numbers beyond the documented precision is specific to the implementation and version of the .NET Framework. Consequently, a comparison of two particular numbers might change between versions of the .NET Framework because the precision of the numbers' internal representation might change. - - If two values are tested for equality by calling the method, the method returns `true`. However, if two values are tested for equality by using the equality operator, the operator returns `false`. When you want to determine whether the value of a is not a number (NaN), an alternative is to call the method. - - ]]> - + For more information about this API, see Supplemental API remarks for Double.Equals. Compiler overload resolution may account for an apparent difference in the behavior of the two method overloads. If an implicit conversion between the argument and a is defined and the argument is not typed as an , compilers may perform an implicit conversion and call the method. Otherwise, they call the method, which always returns if its argument is not a value. The following example illustrates the difference in behavior between the two method overloads. In the case of all primitive numeric types except for and in C#, the first comparison returns because the compiler automatically performs a widening conversion and calls the method, whereas the second comparison returns because the compiler calls the method. diff --git a/xml/System/Environment.xml b/xml/System/Environment.xml index 2d300dd2025..4fde45996f6 100644 --- a/xml/System/Environment.xml +++ b/xml/System/Environment.xml @@ -616,7 +616,7 @@ Invalid argument This method terminates a process without running any active `try`/`finally` blocks or finalizers. On Windows, the `Environment.FailFast` method writes the `message` string to the Windows Application event log, creates a dump of your application, and then terminates the current process. The `message` string is also included in error reporting to Microsoft via Windows Error Reporting. For more information, see [Windows Error Reporting: Getting Started](/windows-hardware/drivers/dashboard/). - + On Unix-like systems, the message is written to the standard error stream, alongside the stack trace information. Use the `Environment.FailFast` method instead of the method to terminate your application if the state of your application is damaged beyond repair, and executing your application's `try`/`finally` blocks and finalizers will corrupt program resources. @@ -703,7 +703,7 @@ Calling the `Environment.FailFast` method to terminate execution of an applicati On Windows, the `Environment.FailFast` method writes the `message` string to the Windows Application event log, creates a dump of your application, and then terminates the current process. Information is reported to Microsoft by using Windows Error Reporting. For more information, see [Windows Error Reporting: Getting Started](/windows-hardware/drivers/dashboard/). Error reporting to Microsoft includes `message` and `exception` information, which provides details used to classify the error. Although `exception` is not handled because the process is terminated, the contextual information that raised the exception is still obtained. - + On Unix-like systems, the message is written to the standard error stream, alongside the stack trace information. If `exception` is `null`, or if `exception` is not thrown, this method operates the same as the method overload. @@ -867,55 +867,23 @@ In .NET 5 and later versions, for single-file publishing, the first element is t The name of the environment variable. Retrieves the value of an environment variable from the current process. The value of the environment variable specified by , or if the environment variable is not found. - + For more information about this API, see Supplemental API remarks for Environment.GetEnvironmentVariable. + method to retrieve the `windir` environment variable, which contains the path of the Windows directory. -## Remarks - -The method retrieves an environment variable from the environment block of the current process only. It is equivalent to calling the method with a `target` value of . - -To retrieve all environment variables along with their values, call the method. - -Environment variable names are case-sensitive on non-Windows systems but are not case-sensitive on Windows. - -### On Windows systems - - On Windows systems, the environment block of the current process includes: - -- All environment variables that are provided to it by the parent process that created it. For example, a .NET application launched from a console window inherits all of the console window's environment variables. - - If there is no parent process, per-machine and per-user environment variables are used instead. For example, a new console window has all per-machine and per-user environment variables defined at the time it was launched. - -- Any variables added to the process block while the process is running by calling either the method or the method with a `target` value of . These environment variables persist until the .NET application terminates. - -If environment variables are created after the process has started, you can use this method to retrieve only those variables that were created by calling the method or the method with a `target` value of .. +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Environment/CPP/Vars1.cpp" id="Snippet4"::: +:::code language="csharp" source="~/snippets/csharp/System/Environment/CurrentDirectory/Vars1.cs" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Environment/CurrentDirectory/Vars1.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Environment/VB/Vars1.vb" id="Snippet4"::: -### On non-Windows systems - -On non-Windows systems, the environment block of the current process includes the following environment variables: - -- All environment variables that are provided to it by the parent process that created it. For .NET applications launched from a shell, this includes all environment variables defined in the shell. - -- Any variables added to the process block while the process is running by calling either the method or the method with a `target` value of . These environment variables persist until the .NET application terminates. - -.NET on non-Windows systems does not support per-machine or per-user environment variables. - -## Examples - The following example uses the method to retrieve the `windir` environment variable, which contains the path of the Windows directory. +The following example attempts to retrieve the value of an environment variable named `Test1` from the process environment block. If the variable doesn't exist, the example creates it and retrieves its value. The example displays the value of the variable. If the example created the variable, it also calls the method with each member of the enumeration to establish that the variable can be retrieved only from the current process environment block. Finally, if the example created the variable, it deletes it. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Environment/CPP/Vars1.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System/Environment/CurrentDirectory/Vars1.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Environment/CurrentDirectory/Vars1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Environment/VB/Vars1.vb" id="Snippet4"::: - - The following example attempts to retrieve the value of an environment variable named `Test1` from the process environment block. If the variable doesn't exist, the example creates it and retrieves its value. The example displays the value of the variable. If the example created the variable, it also calls the method with each member of the enumeration to establish that the variable can be retrieved only from the current process environment block. Finally, if the example created the variable, it deletes it. - - :::code language="csharp" source="~/snippets/csharp/System/Environment/GetEnvironmentVariable/getenvironmentvariableex1.cs"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Environment/GetEnvironmentVariable/getenvironmentvariableex1.fs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.environment.getenvironmentvariable/vb/getenvironmentvariableex1.vb"::: - - ]]> - +:::code language="csharp" source="~/snippets/csharp/System/Environment/GetEnvironmentVariable/getenvironmentvariableex1.cs"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Environment/GetEnvironmentVariable/getenvironmentvariableex1.fs"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.environment.getenvironmentvariable/vb/getenvironmentvariableex1.vb"::: + ]]> + is . The caller does not have the required permission to perform this operation. @@ -975,39 +943,16 @@ On non-Windows systems, the environment block of the current process includes th One of the values. Only is supported on .NET running on Unix-based systems. Retrieves the value of an environment variable from the current process or from the Windows operating system registry key for the current user or local machine. The value of the environment variable specified by the and parameters, or if the environment variable is not found. - + For more information about this API, see Supplemental API remarks for Environment.GetEnvironmentVariable. + method. - -Environment variable names are case-sensitive on non-Windows systems but are not case-sensitive on Windows. - -### On Windows systems - -On Windows, the `target` parameter specifies whether the environment variable is retrieved from the current process or from the Windows operating system registry key for the current user or local machine. All per-user and per-machine environment variables are automatically copied into the environment block of the current process, as are any other environment variables that are available to the parent process that created the .NET process. However, environment variables added only to the environment block of the current process by calling either the method or the method with a `target` value of persist only for the duration of the process. - -### On non-Windows systems - -On non-Windows systems, the `GetEnvironmentVariable(String, EnvironmentVariableTarget)` method supports a `target` value of only. Calls with a `target` value of or are not supported and return `null`. - -Per-process environment variables are: - -- Those inherited from the parent process, typically the shell used to invoke `dotnet.exe` or to launch the .NET application. - -- Those defined by calling either the method or the method with a `target` value of . These environment variables persist only until the `dotnet` process or the .NET application terminates. - -## Examples - The following example creates environment variables for the , , and targets, checks whether the operating system registry contains the user and machine environment variables, then deletes the environment variables. Because .NET on Unix-based systems does not support per-user and per-machine environment variables, only and with a value of successfully store an environment variable to the process environment block. :::code language="csharp" source="~/snippets/csharp/System/Environment/GetEnvironmentVariable/gsev.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System/Environment/GetEnvironmentVariable/gsev.fs"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/environment.getsetenvar/VB/gsev.vb"::: - - ]]> - + ]]> + is . diff --git a/xml/System/Exception.xml b/xml/System/Exception.xml index e1456c09e47..49e765c70b2 100644 --- a/xml/System/Exception.xml +++ b/xml/System/Exception.xml @@ -449,42 +449,17 @@ Gets a collection of key/value pairs that provide additional user-defined information about the exception. An object that implements the interface and contains a collection of user-defined key/value pairs. The default is an empty collection. - + For more information about this API, see Supplemental API remarks for Exception.Data. + object returned by the property to store and retrieve supplementary information relevant to the exception. The information is in the form of an arbitrary number of user-defined key/value pairs. The key component of each key/value pair is typically an identifying string, whereas the value component of the pair can be any type of object. - -## Key/Value Pair Security - The key/value pairs stored in the collection returned by the property are not secure. If your application calls a nested series of routines, and each routine contains exception handlers, the resulting call stack contains a hierarchy of those exception handlers. If a lower-level routine throws an exception, any upper-level exception handler in the call stack hierarchy can read and/or modify the key/value pairs stored in the collection by any other exception handler. This means you must guarantee that the information in the key/value pairs is not confidential and that your application will operate correctly if the information in the key/value pairs is corrupted. - -## Key Conflicts - A key conflict occurs when different exception handlers specify the same key to access a key/value pair. Use caution when developing your application because the consequence of a key conflict is that lower-level exception handlers can inadvertently communicate with higher-level exception handlers, and this communication might cause subtle program errors. However, if you are cautious you can use key conflicts to enhance your application. - -## Avoiding Key Conflicts - Avoid key conflicts by adopting a naming convention to generate unique keys for key/value pairs. For example, a naming convention might yield a key that consists of the period-delimited name of your application, the method that provides supplementary information for the pair, and a unique identifier. - - Suppose two applications, named Products and Suppliers, each has a method named Sales. The Sales method in the Products application provides the identification number (the stock keeping unit or SKU) of a product. The Sales method in the Suppliers application provides the identification number, or SID, of a supplier. Consequently, the naming convention for this example yields the keys, "Products.Sales.SKU" and "Suppliers.Sales.SID". - -## Exploiting Key Conflicts - Exploit key conflicts by using the presence of one or more special, prearranged keys to control processing. Suppose, in one scenario, the highest level exception handler in the call stack hierarchy catches all exceptions thrown by lower-level exception handlers. If a key/value pair with a special key exists, the high-level exception handler formats the remaining key/value pairs in the object in some nonstandard way; otherwise, the remaining key/value pairs are formatted in some normal manner. - - Now suppose, in another scenario, the exception handler at each level of the call stack hierarchy catches the exception thrown by the next lower-level exception handler. In addition, each exception handler knows the collection returned by the property contains a set of key/value pairs that can be accessed with a prearranged set of keys. - - Each exception handler uses the prearranged set of keys to update the value component of the corresponding key/value pair with information unique to that exception handler. After the update process is complete, the exception handler throws the exception to the next higher-level exception handler. Finally, the highest level exception handler accesses the key/value pairs and displays the consolidated update information from all the lower-level exception handlers. - - - -## Examples - The following example demonstrates how to add and retrieve information using the property. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/exception.data/CPP/data.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Exception/Data/data.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Exception/Data/data.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/exception.data/VB/data.vb" id="Snippet1"::: - - ]]> - +The following example demonstrates how to add and retrieve information using the property. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/exception.data/CPP/data.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/Exception/Data/data.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Exception/Data/data.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/exception.data/VB/data.vb" id="Snippet1"::: + ]]> + @@ -976,29 +951,22 @@ The error message that explains the reason for the exception, or an empty string (""). property should completely describe the error and, when possible, should also explain how to correct the error. Top-level exception handlers may display the message to end-users, so you should ensure that it is grammatically correct and that each sentence of the message ends with a period. Do not use question marks or exclamation points. If your application uses localized exception messages, you should ensure that they are accurately translated. +Error messages target the developer who is handling the exception. The text of the property should completely describe the error and, when possible, should also explain how to correct the error. Top-level exception handlers may display the message to end-users, so you should ensure that it is grammatically correct and that each sentence of the message ends with a period. Do not use question marks or exclamation points. If your application uses localized exception messages, you should ensure that they are accurately translated. > [!IMPORTANT] -> Do not disclose sensitive information in exception messages without checking for the appropriate permissions. - - The value of the property is included in the information returned by . The property is set only when creating an . If no message was supplied to the constructor for the current instance, the system supplies a default message that is formatted using the current system culture. - -## Windows Runtime and .NET Framework 4.5.1 - Starting with the .NET Framework 4.5.1 and Windows 8.1, the fidelity of error messages from exceptions that are propagated from Windows Runtime types and members that are not part of the .NET Framework is improved. In particular, exception messages from Visual C++ component extensions (C++/CX) are now propagated back into .NET Framework objects. - +> Do not disclose sensitive information in exception messages without checking for the appropriate permissions. +The value of the property is included in the information returned by . The property is set only when creating an . If no message was supplied to the constructor for the current instance, the system supplies a default message that is formatted using the current system culture. ## Examples - The following code example throws and then catches an exception and displays the exception's text message using the property. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Exception.Properties/CPP/properties.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Exception/HelpLink/properties.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Exception/HelpLink/properties.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Exception.Properties/VB/properties.vb" id="Snippet1"::: +The following code example throws and then catches an exception and displays the exception's text message using the property. - ]]> +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Exception.Properties/CPP/properties.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/Exception/HelpLink/properties.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Exception/HelpLink/properties.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Exception.Properties/VB/properties.vb" id="Snippet1"::: + ]]> If you throw an exception from a property, and you need to refer in the text of to the property argument that you set or get, use "value" as the name of the property argument. diff --git a/xml/System/Memory`1.xml b/xml/System/Memory`1.xml index 6abffbb0bc7..3ea6dd1e784 100644 --- a/xml/System/Memory`1.xml +++ b/xml/System/Memory`1.xml @@ -74,10 +74,10 @@ The type of items in the . Represents a contiguous region of memory. - , `Memory` represents a contiguous region of memory. Unlike , however, `Memory` is not a [ref struct](/dotnet/csharp/language-reference/builtin-types/ref-struct). This means that `Memory` can be placed on the managed heap, whereas cannot. As a result, the `Memory` structure does not have the same restrictions as a instance. In particular: - It can be used as a field in a class. @@ -131,7 +131,7 @@ In addition to `Memory`, you can use The array from which to create the object. Creates a new object over the entirety of a specified array. - object with a `default` value. @@ -139,7 +139,7 @@ If `array` is `null`, this constructor returns a object is a reference type, and is not an array of type . - + -or- The array is covariant. @@ -188,7 +188,7 @@ The array is The number of elements to include in the new . Creates a new object that includes a specified number of elements of an array beginning at a specified index. - object with a `default` value. @@ -251,7 +251,7 @@ If `array` is `null`, this constructor returns a objec The destination object. Copies the contents of a object into a destination object. - instance to `destination` even if the contents of the current instance and `destination` overlap. @@ -347,12 +347,12 @@ This method copies all of the contents of the current i if the current instance and are equal; otherwise, . - or object. - + - Both objects point to the same array and have the same length. The `Equals(Memory)` method performs a test for reference equality; it does not compare the elements of for equality. @@ -415,10 +415,10 @@ The `Equals(Memory)` method performs a test for reference equality; it does n if the current instance and are equal; otherwise, . - objects are equal if both objects point to the same array and have the same length. Note that the test for equality does not check whether the contents are equal. - + ]]> @@ -695,19 +695,12 @@ Two objects are equal if both objects point to the same Creates a handle for the object. A handle for the object. - object is disposed. This enables you to retrieve and use the memory's address. - - - - ]]> + ]]> An instance with non-primitive (non-blittable) members cannot be pinned. + @@ -865,11 +858,11 @@ The garbage collector will not move the memory until the returned Copies the contents from the memory into a new array. An array containing the elements in the current memory. - @@ -907,7 +900,7 @@ Each call to the `ToArray` method returns a new array. Returns the string representation of this object. the string representation of this object. - `, the `ToString` method returns a that contains the characters pointed to by the . Otherwise, it returns a with the name of the type and the number of elements that the contains. @@ -958,7 +951,7 @@ For a `Memory`, the `ToString` method returns a that if the copy operation succeeds; otherwise, . - instance to `destination` even if the contents of the current instance and `destination` overlap. diff --git a/xml/System/Object.xml b/xml/System/Object.xml index 06503961538..ec57230e7f1 100644 --- a/xml/System/Object.xml +++ b/xml/System/Object.xml @@ -192,149 +192,7 @@ The following example defines a Point type derived from the Determines whether the specified object is equal to the current object. if the specified object is equal to the current object; otherwise, . - - method tests for reference equality, and a call to the method is equivalent to a call to the method. Reference equality means that the object variables that are compared refer to the same object. The following example illustrates the result of such a comparison. It defines a `Person` class, which is a reference type, and calls the `Person` class constructor to instantiate two new `Person` objects, `person1a` and `person2`, which have the same value. It also assigns `person1a` to another object variable, `person1b`. As the output from the example shows, `person1a` and `person1b` are equal because they reference the same object. However, `person1a` and `person2` are not equal, although they have the same value. - - :::code language="csharp" source="~/snippets/csharp/System/Object/Equals/equals_ref.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/Equals/equals_ref.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_ref.vb" id="Snippet2"::: - -- If the current instance is a value type, the method tests for value equality. Value equality means the following: - - - The two objects are of the same type. As the following example shows, a object that has a value of 12 does not equal an object that has a value of 12, because the two objects have different run-time types. - - :::code language="csharp" source="~/snippets/csharp/System/Object/Equals/equals_val1.cs" interactive="try-dotnet-method" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/Equals/equals_val1.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_val1.vb" id="Snippet3"::: - - - The values of the public and private fields of the two objects are equal. The following example tests for value equality. It defines a `Person` structure, which is a value type, and calls the `Person` class constructor to instantiate two new `Person` objects, `person1` and `person2`, which have the same value. As the output from the example shows, although the two object variables refer to different objects, `person1` and `person2` are equal because they have the same value for the private `personName` field. - - :::code language="csharp" source="~/snippets/csharp/System/Object/Equals/equals_val2.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/Equals/equals_val2.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equals_val2.vb" id="Snippet4"::: - - Because the class is the base class for all types in the .NET Framework, the method provides the default equality comparison for all other types. However, types often override the method to implement value equality. For more information, see the Notes for Callers and Notes for Inheritors sections. - -## Notes for the Windows Runtime - When you call the method overload on a class in the Windows Runtime, it provides the default behavior for classes that don't override . This is part of the support that the .NET Framework provides for the Windows Runtime (see [.NET Framework Support for Windows Store Apps and Windows Runtime](/dotnet/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime)). Classes in the Windows Runtime don't inherit , and currently don't implement an method. However, they appear to have , , and methods when you use them in your C# or Visual Basic code, and the .NET Framework provides the default behavior for these methods. - -> [!NOTE] -> Windows Runtime classes that are written in C# or Visual Basic can override the method overload. - -## Notes for Callers - Derived classes frequently override the method to implement value equality. In addition, types also frequently provide an additional strongly typed overload to the `Equals` method, typically by implementing the interface. When you call the `Equals` method to test for equality, you should know whether the current instance overrides and understand how a particular call to an `Equals` method is resolved. Otherwise, you may be performing a test for equality that is different from what you intended, and the method may return an unexpected value. - - The following example provides an illustration. It instantiates three objects with identical strings, and then makes four calls to `Equals` methods. The first method call returns `true`, and the remaining three return `false`. - - :::code language="csharp" source="~/snippets/csharp/System/Object/Equals/equalssb1.cs" interactive="try-dotnet" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/Equals/equalssb1.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equalssb1.vb" id="Snippet5"::: - - In the first case, the strongly typed method overload, which tests for value equality, is called. Because the strings assigned to the two objects are equal, the method returns `true`. However, does not override . Because of this, when the object is cast to an , when a instance is assigned to a variable of type , and when the method is passed two objects, the default method is called. Because is a reference type, this is equivalent to passing the two objects to the method. Although all three objects contain identical strings, they refer to three distinct objects. As a result, these three method calls return `false`. - - You can compare the current object to another object for reference equality by calling the method. In Visual Basic, you can also use the `is` keyword (for example, `If Me Is otherObject Then ...`). - -## Notes for Inheritors - When you define your own type, that type inherits the functionality defined by the `Equals` method of its base type. The following table lists the default implementation of the `Equals` method for the major categories of types in the .NET Framework. - -|Type category|Equality defined by|Comments| -|-------------------|-------------------------|--------------| -|Class derived directly from ||Reference equality; equivalent to calling .| -|Structure||Value equality; either direct byte-by-byte comparison or field-by-field comparison using reflection.| -|Enumeration||Values must have the same enumeration type and the same underlying value.| -|Delegate||Delegates must have the same type with identical invocation lists.| -|Interface||Reference equality.| - - For a value type, you should always override , because tests for equality that rely on reflection offer poor performance. You can also override the default implementation of for reference types to test for value equality instead of reference equality and to define the precise meaning of value equality. Such implementations of return `true` if the two objects have the same value, even if they are not the same instance. The type's implementer decides what constitutes an object's value, but it is typically some or all the data stored in the instance variables of the object. For example, the value of a object is based on the characters of the string; the method overrides the method to return `true` for any two string instances that contain the same characters in the same order. - - The following example shows how to override the method to test for value equality. It overrides the method for the `Person` class. If `Person` accepted its base class implementation of equality, two `Person` objects would be equal only if they referenced a single object. However, in this case, two `Person` objects are equal if they have the same value for the `Person.Id` property. - - :::code language="csharp" source="~/snippets/csharp/System/Object/Equals/equalsoverride.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/Equals/equalsoverride.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.equals/vb/equalsoverride.vb" id="Snippet6"::: - - In addition to overriding , you can implement the interface to provide a strongly typed test for equality. - - The following statements must be true for all implementations of the method. In the list, `x`, `y`, and `z` represent object references that are not **null**. - -- `x.Equals(x)` returns `true`. - -- `x.Equals(y)` returns the same value as `y.Equals(x)`. - -- `x.Equals(y)` returns `true` if both `x` and `y` are `NaN`. - -- If `(x.Equals(y) && y.Equals(z))` returns `true`, then `x.Equals(z)` returns `true`. - -- Successive calls to `x.Equals(y)` return the same value as long as the objects referenced by `x` and `y` are not modified. - -- `x.Equals(null)` returns `false`. - - Implementations of must not throw exceptions; they should always return a value. For example, if `obj` is `null`, the method should return `false` instead of throwing an . - - Follow these guidelines when overriding : - -- Types that implement must override . - -- Types that override must also override ; otherwise, hash tables might not work correctly. - -- You should consider implementing the interface to support strongly typed tests for equality. Your implementation should return results that are consistent with . - -- If your programming language supports operator overloading and you overload the equality operator for a given type, you must also override the method to return the same result as the equality operator. This helps ensure that class library code that uses (such as and ) behaves in a manner that is consistent with the way the equality operator is used by application code. - -### Guidelines for Reference Types - The following guidelines apply to overriding for a reference type: - -- Consider overriding if the semantics of the type are based on the fact that the type represents some value(s). - -- Most reference types must not overload the equality operator, even if they override . However, if you are implementing a reference type that is intended to have value semantics, such as a complex number type, you must override the equality operator. - -- You should not override on a mutable reference type. This is because overriding requires that you also override the method, as discussed in the previous section. This means that the hash code of an instance of a mutable reference type can change during its lifetime, which can cause the object to be lost in a hash table. - -### Guidelines for Value Types - The following guidelines apply to overriding for a value type: - -- If you are defining a value type that includes one or more fields whose values are reference types, you should override . The implementation provided by performs a byte-by-byte comparison for value types whose fields are all value types, but it uses reflection to perform a field-by-field comparison of value types whose fields include reference types. - -- If you override and your development language supports operator overloading, you must overload the equality operator. - -- You should implement the interface. Calling the strongly typed method avoids boxing the `obj` argument. - - - -## Examples - The following example shows a `Point` class that overrides the method to provide value equality, and a `Point3D` class that is derived from `Point`. Because `Point` overrides to test for value equality, the method is not called. However, `Point3D.Equals` calls `Point.Equals` because `Point` implements in a manner that provides value equality. - - :::code language="csharp" source="~/snippets/csharp/System/Object/Equals/equals2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/Equals/equals2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals2/VB/equals2.vb" id="Snippet1"::: - - The `Point.Equals` method checks to make sure that the `obj` argument is not **null** and that it references an instance of the same type as this object. If either check fails, the method returns `false`. - - The `Point.Equals` method calls the method to determine whether the run-time types of the two objects are identical. If the method used a check of the form `obj is Point` in C# or `TryCast(obj, Point)` in Visual Basic, the check would return `true` in cases where `obj` is an instance of a derived class of `Point`, even though `obj` and the current instance are not of the same run-time type. Having verified that both objects are of the same type, the method casts `obj` to type `Point` and returns the result of comparing the instance fields of the two objects. - - In `Point3D.Equals`, the inherited `Point.Equals` method, which overrides , is invoked before anything else is done. Because `Point3D` is a sealed class (`NotInheritable` in Visual Basic), a check in the form `obj is Point` in C# or `TryCast(obj, Point)` in Visual Basic is adequate to ensure that `obj` is a `Point3D` object. If it is a `Point3D` object, it is cast to a `Point` object and passed to the base class implementation of . Only when the inherited `Point.Equals` method returns `true` does the method compare the `z` instance fields introduced in the derived class. - - The following example defines a `Rectangle` class that internally implements a rectangle as two `Point` objects. The `Rectangle` class also overrides to provide for value equality. - - :::code language="csharp" source="~/snippets/csharp/System/Object/Equals/equals3.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/Equals/equals3.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals3/VB/equals3.vb" id="Snippet1"::: - - Some languages such as C# and Visual Basic support operator overloading. When a type overloads the equality operator, it must also override the method to provide the same functionality. This is typically accomplished by writing the method in terms of the overloaded equality operator, as in the following example. - - :::code language="csharp" source="~/snippets/csharp/System/Object/Equals/equals4.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/Equals/equals4.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ECMA-System.Object.Equals4/vb/equals4.vb" id="Snippet1"::: - - Because `Complex` is a value type, it cannot be derived from. Therefore, the override to method need not call to determine the precise run-time type of each object, but can instead use the `is` operator in C# or the `TypeOf` operator in Visual Basic to check the type of the `obj` parameter. - - ]]> - + For more information about this API, see Supplemental API remarks for Object.Equals. @@ -471,110 +329,18 @@ The following example defines a Point type derived from the Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. - + For more information about this API, see Supplemental API remarks for Object.Finalize. + method is called when an object that overrides is destroyed. Note that, in a production application, the method would be overridden to release unmanaged resources held by the object. Also note that the C# example provides a destructor instead of overriding the method. -## Remarks - The method is used to perform cleanup operations on unmanaged resources held by the current object before the object is destroyed. The method is protected and therefore is accessible only through this class or through a derived class. - - In this section: - -- [How finalization works](#How) - -- [Notes for implementers](#Notes) - -- [The SafeHandle alternative](#SafeHandle) - - -## How finalization works - The class provides no implementation for the method, and the garbage collector does not mark types derived from for finalization unless they override the method. - - If a type does override the method, the garbage collector adds an entry for each instance of the type to an internal structure called the finalization queue. The finalization queue contains entries for all the objects in the managed heap whose finalization code must run before the garbage collector can reclaim their memory. The garbage collector then calls the method automatically under the following conditions: - -- After the garbage collector has discovered that an object is inaccessible, unless the object has been exempted from finalization by a call to the method. - -- **On .NET Framework only**, during shutdown of an application domain, unless the object is exempt from finalization. During shutdown, even objects that are still accessible are finalized. - - is automatically called only once on a given instance, unless the object is re-registered by using a mechanism such as and the method has not been subsequently called. - - operations have the following limitations: - -- The exact time when the finalizer executes is undefined. To ensure deterministic release of resources for instances of your class, implement a `Close` method or provide a implementation. - -- The finalizers of two objects are not guaranteed to run in any specific order, even if one object refers to the other. That is, if Object A has a reference to Object B and both have finalizers, Object B might have already been finalized when the finalizer of Object A starts. - -- The thread on which the finalizer runs is unspecified. - - The method might not run to completion or might not run at all under the following exceptional circumstances: - -- If another finalizer blocks indefinitely (goes into an infinite loop, tries to obtain a lock it can never obtain, and so on). Because the runtime tries to run finalizers to completion, other finalizers might not be called if a finalizer blocks indefinitely. - -- If the process terminates without giving the runtime a chance to clean up. In this case, the runtime's first notification of process termination is a DLL_PROCESS_DETACH notification. - - The runtime continues to finalize objects during shutdown only while the number of finalizable objects continues to decrease. - - If or an override of throws an exception, and the runtime is not hosted by an application that overrides the default policy, the runtime terminates the process and no active `try`/`finally` blocks or finalizers are executed. This behavior ensures process integrity if the finalizer cannot free or destroy resources. - - -## Overriding the Finalize method - You should override for a class that uses unmanaged resources, such as file handles or database connections that must be released when the managed object that uses them is discarded during garbage collection. You shouldn't implement a method for managed objects because the garbage collector releases managed resources automatically. - -> [!IMPORTANT] -> If a object is available that wraps your unmanaged resource, the recommended alternative is to implement the dispose pattern with a safe handle and not override . For more information, see [The SafeHandle alternative](#SafeHandle) section. - - The method does nothing by default, but you should override only if necessary, and only to release unmanaged resources. Reclaiming memory tends to take much longer if a finalization operation runs, because it requires at least two garbage collections. In addition, you should override the method for reference types only. The common language runtime only finalizes reference types. It ignores finalizers on value types. - -The scope of the method is `protected`. You should maintain this limited scope when you override the method in your class. By keeping a method protected, you prevent users of your application from calling an object's method directly. - - Every implementation of in a derived type must call its base type's implementation of . This is the only case in which application code is allowed to call . An object's method shouldn't call a method on any objects other than that of its base class. This is because the other objects being called could be collected at the same time as the calling object, such as in the case of a common language runtime shutdown. - -> [!NOTE] -> The C# compiler does not allow you to override the method. Instead, you provide a finalizer by implementing a [destructor](/dotnet/csharp/programming-guide/classes-and-structs/destructors) for your class. A C# destructor automatically calls the destructor of its base class. -> -> Visual C++ also provides its own syntax for implementing the method. For more information, see the "Destructors and finalizers" section of [How to: Define and Consume Classes and Structs (C++/CLI)](/cpp/dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli). - - Because garbage collection is non-deterministic, you do not know precisely when the garbage collector performs finalization. To release resources immediately, you can also choose to implement the [dispose pattern](/dotnet/standard/garbage-collection/implementing-dispose) -and the interface. The implementation can be called by consumers of your class to free unmanaged resources, and you can use the method to free unmanaged resources in the event that the method is not called. - - can take almost any action, including resurrecting an object (that is, making the object accessible again) after it has been cleaned up during garbage collection. However, the object can only be resurrected once; cannot be called on resurrected objects during garbage collection. - - -## The SafeHandle alternative - Creating reliable finalizers is often difficult, because you cannot make assumptions about the state of your application, and because unhandled system exceptions such as and terminate the finalizer. Instead of implementing a finalizer for your class to release unmanaged resources, you can use an object that is derived from the class to wrap your unmanaged resources, and then implement the dispose pattern without a finalizer. The .NET Framework provides the following classes in the namespace that are derived from : - -- is a wrapper class for a file handle. - -- is a wrapper class for memory-mapped file handles. - -- is a wrapper class for a pointer to a block of unmanaged memory. - -- , , and are wrapper classes for cryptographic handles. - -- is a wrapper class for pipe handles. - -- is a wrapper class for a handle to a registry key. - -- is a wrapper class for a wait handle. +:::code language="csharp" source="~/snippets/csharp/System/Object/Finalize/finalize1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Object/Finalize/finalize1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.finalize/vb/finalize1.vb" id="Snippet1"::: - The following example uses the [dispose pattern](/dotnet/standard/garbage-collection/implementing-dispose) with safe handles instead of overriding the method. It defines a `FileAssociation` class that wraps registry information about the application that handles files with a particular file extension. The two registry handles returned as `out` parameters by Windows [RegOpenKeyEx](/windows/win32/api/winreg/nf-winreg-regopenkeyexa) function calls are passed to the constructor. The type's protected `Dispose` method then calls the `SafeRegistryHandle.Dispose` method to free these two handles. - - :::code language="csharp" source="~/snippets/csharp/System/Object/Finalize/finalize_safe.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/Finalize/finalize_safe.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.finalize/vb/finalize_safe.vb" id="Snippet2"::: - - - -## Examples - The following example verifies that the method is called when an object that overrides is destroyed. Note that, in a production application, the method would be overridden to release unmanaged resources held by the object. Also note that the C# example provides a destructor instead of overriding the method. - - :::code language="csharp" source="~/snippets/csharp/System/Object/Finalize/finalize1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/Finalize/finalize1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.finalize/vb/finalize1.vb" id="Snippet1"::: - - For an additional example that overrides the method, see the method. - - ]]> - +For an additional example that overrides the method, see the method. + ]]> + @@ -628,78 +394,7 @@ and the interface. The Serves as the default hash function. A hash code for the current object. - - class, the class, or a type derived from the class. The method provides this hash code for algorithms that need quick checks of object equality. - -> [!NOTE] -> For information about how hash codes are used in hash tables and for some additional hash code algorithms, see the [Hash Function](https://en.wikipedia.org/wiki/Hash_function) entry in Wikipedia. - - Two objects that are equal return hash codes that are equal. However, the reverse is not true: equal hash codes do not imply object equality, because different (unequal) objects can have identical hash codes. Furthermore, .NET does not guarantee the default implementation of the method, and the value this method returns may differ between .NET implementations, such as different versions of .NET Framework and .NET Core, and platforms, such as 32-bit and 64-bit platforms. For these reasons, do not use the default implementation of this method as a unique object identifier for hashing purposes. Two consequences follow from this: - -- You should not assume that equal hash codes imply object equality. - -- You should never persist or use a hash code outside the application domain in which it was created, because the same object may hash across application domains, processes, and platforms. - -> [!WARNING] -> A hash code is intended for efficient insertion and lookup in collections that are based on a hash table. A hash code is not a permanent value. For this reason: -> -> - Do not serialize hash code values or store them in databases. -> - Do not use the hash code as the key to retrieve an object from a keyed collection. -> - Do not send hash codes across application domains or processes. In some cases, hash codes may be computed on a per-process or per-application domain basis. -> - Do not use the hash code instead of a value returned by a cryptographic hashing function if you need a cryptographically strong hash. For cryptographic hashes, use a class derived from the or class. -> - Do not test for equality of hash codes to determine whether two objects are equal. (Unequal objects can have identical hash codes.) To test for equality, call the or method. - - The method can be overridden by a derived type. If is not overridden, hash codes for reference types are computed by calling the method of the base class, which computes a hash code based on an object's reference; for more information, see . In other words, two objects for which the method returns `true` have identical hash codes. If value types do not override , the method of the base class uses reflection to compute the hash code based on the values of the type's fields. In other words, value types whose fields have equal values have equal hash codes. For more information about overriding , see the "Notes to Inheritors" section. - -> [!WARNING] -> If you override the method, you should also override , and vice versa. If your overridden method returns `true` when two objects are tested for equality, your overridden method must return the same value for the two objects. - - If an object that is used as a key in a hash table does not provide a useful implementation of , you can specify a hash code provider by supplying an implementation to one of the overloads of the class constructor. - -## Notes for the Windows Runtime - When you call the method on a class in the Windows Runtime, it provides the default behavior for classes that don't override . This is part of the support that the .NET Framework provides for the Windows Runtime (see [.NET Framework Support for Windows Store Apps and Windows Runtime](/dotnet/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime)). Classes in the Windows Runtime don't inherit , and currently don't implement a . However, they appear to have , , and methods when you use them in your C# or Visual Basic code, and the .NET Framework provides the default behavior for these methods. - -> [!NOTE] -> Windows Runtime classes that are written in C# or Visual Basic can override the method. - - - -## Examples - One of the simplest ways to compute a hash code for a numeric value that has the same or a smaller range than the type is to simply return that value. The following example shows such an implementation for a `Number` structure. - - :::code language="csharp" source="~/snippets/csharp/System/Object/GetHashCode/direct1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/GetHashCode/direct1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/direct1.vb" id="Snippet1"::: - - Frequently, a type has multiple data fields that can participate in generating the hash code. One way to generate a hash code is to combine these fields using an `XOR (eXclusive OR)` operation, as shown in the following example. - - :::code language="csharp" source="~/snippets/csharp/System/Object/GetHashCode/xor1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/GetHashCode/xor1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/xor1.vb" id="Snippet2"::: - - The previous example returns the same hash code for (n1, n2) and (n2, n1), and so may generate more collisions than are desirable. A number of solutions are available so that hash codes in these cases are not identical. One is to return the hash code of a `Tuple` object that reflects the order of each field. The following example shows a possible implementation that uses the class. Note, though, that the performance overhead of instantiating a `Tuple` object may significantly impact the overall performance of an application that stores large numbers of objects in hash tables. - - :::code language="csharp" source="~/snippets/csharp/System/Object/GetHashCode/xor2.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/GetHashCode/xor2.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/xor2.vb" id="Snippet3"::: - - A second alternative solution involves weighting the individual hash codes by left-shifting the hash codes of successive fields by two or more bits. Optimally, bits shifted beyond bit 31 should wrap around rather than be discarded. Since bits are discarded by the left-shift operators in both C# and Visual Basic, this requires creating a left shift-and-wrap method like the following: - - :::code language="csharp" source="~/snippets/csharp/System/Object/GetHashCode/shift1.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/GetHashCode/shift1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/shift1.vb" id="Snippet4"::: - - The following example then uses this shift-and-wrap method to compute the hash code of the `Point` structure used in the previous examples. - - :::code language="csharp" source="~/snippets/csharp/System/Object/GetHashCode/shift1.cs" interactive="try-dotnet" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/GetHashCode/shift1.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.gethashcode/vb/shift1.vb" id="Snippet5"::: - - ]]> - + For more information about this API, see Supplemental API remarks for Object.GetHashCode. A hash function is used to quickly generate a number (hash code) that corresponds to the value of an object. Hash functions are usually specific to each type and, for uniqueness, must use at least one of the instance fields as input. Hash codes should not be computed by using the values of static fields. @@ -1068,167 +763,7 @@ and the interface. The Returns a string that represents the current object. A string that represents the current object. - - is the major formatting method in the .NET Framework. It converts an object to its string representation so that it is suitable for display. (For information about formatting support in the .NET Framework, see [Formatting Types](/dotnet/standard/base-types/formatting-types).) Default implementations of the method return the fully qualified name of the object's type. - -> [!IMPORTANT] -> You may have reached this page by following the link from the member list of another type. That is because that type does not override . Instead, it inherits the functionality of the method. - - Types frequently override the method to provide a more suitable string representation of a particular type. Types also frequently overload the method to provide support for format strings or culture-sensitive formatting. - - In this section: - - [The default Object.ToString() method](#Default) - [Overriding the Object.ToString() method](#Overriding) - [Overloading the ToString method](#Overloading) - [Extending the Object.ToString method](#Extending) - [Notes for the Windows Runtime](#WinRT) - - -## The default Object.ToString() method - The default implementation of the method returns the fully qualified name of the type of the , as the following example shows. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.object.tostring/cpp/tostring1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Object/ToString/tostring1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/ToString/tostring1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring1.vb" id="Snippet1"::: - - Because is the base class of all reference types in the .NET Framework, this behavior is inherited by reference types that do not override the method. The following example illustrates this. It defines a class named `Object1` that accepts the default implementation of all members. Its method returns the object's fully qualified type name. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.object.tostring/cpp/tostring2.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System/Object/ToString/tostring2.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/ToString/tostring2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring2.vb" id="Snippet2"::: - - -## Overriding the Object.ToString() method - Types commonly override the method to return a string that represents the object instance. For example, the base types such as , , and provide implementations that return the string form of the value that the object represents. The following example defines a class, `Object2`, that overrides the method to return the type name along with its value. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.object.tostring/cpp/tostring3.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System/Object/ToString/tostring3.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/ToString/tostring3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostring3.vb" id="Snippet3"::: - - The following table lists the type categories in .NET and indicates whether or not they override the method. - -|Type category|Overrides Object.ToString()|Behavior| -|-------------------|-----------------------------------|--------------| -|Class|n/a|n/a| -|Structure|Yes ()|Same as `Object.ToString()`| -|Enumeration|Yes ()|The member name| -|Interface|No|n/a| -|Delegate|No|n/a| - - See the Notes to Inheritors section for additional information on overriding . - - -## Overloading the ToString method - In addition to overriding the parameterless method, many types overload the `ToString` method to provide versions of the method that accept parameters. Most commonly, this is done to provide support for variable formatting and culture-sensitive formatting. - - The following example overloads the `ToString` method to return a result string that includes the value of various fields of an `Automobile` class. It defines four format strings: G, which returns the model name and year; D, which returns the model name, year, and number of doors; C, which returns the model name, year, and number of cylinders; and A, which returns a string with all four field values. - - :::code language="csharp" source="~/snippets/csharp/System/Object/ToString/tostringoverload1.cs" interactive="try-dotnet" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/ToString/tostringoverload1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostringoverload1.vb" id="Snippet4"::: - - The following example calls the overloaded method to display culture-sensitive formatting of a currency value. - - :::code language="csharp" source="~/snippets/csharp/System/Object/ToString/tostringoverload2.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/ToString/tostringoverload2.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/tostringoverload2.vb" id="Snippet5"::: - - For more information on format strings and culture-sensitive formatting, see [Formatting Types](/dotnet/standard/base-types/formatting-types). For the format strings supported by numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the format strings supported by date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). - - -## Extending the Object.ToString method - Because a type inherits the default method, you may find its behavior undesirable and want to change it. This is particularly true of arrays and collection classes. While you may expect the `ToString` method of an array or collection class to display the values of its members, it instead displays the type fully qualified type name, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System/Object/ToString/array1.cs" interactive="try-dotnet-method" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/ToString/array1.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/array1.vb" id="Snippet6"::: - - You have several options to produce the result string that you'd like. - -- If the type is an array, a collection object, or an object that implements the or interfaces, you can enumerate its elements by using the `foreach` statement in C# or the `For Each...Next` construct in Visual Basic. - -- If the class is not `sealed` (in C#) or `NotInheritable` (in Visual Basic), you can develop a wrapper class that inherits from the base class whose method you want to customize. At a minimum, this requires that you do the following: - - 1. Implement any necessary constructors. Derived classes do not inherit their base class constructors. - - 2. Override the method to return the result string that you'd like. - - The following example defines a wrapper class for the class. It overrides the method to display the value of each method of the collection rather than the fully qualified type name. - - :::code language="csharp" source="~/snippets/csharp/System/Object/ToString/customize1.cs" interactive="try-dotnet" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/ToString/customize1.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/customize1.vb" id="Snippet7"::: - -- Develop an [extension method](/dotnet/standard/design-guidelines/extension-methods) that returns the result string that you want. Note that you can't override the default method in this way (that is, your extension class (in C#) or module (in Visual Basic) cannot have a parameterless method named `ToString` that is called in place of the original type's `ToString` method. You'll have to provide some other name for your parameterless `ToString` replacement. - - The following example defines two methods that extend the class: a parameterless `ToString2` method, and a `ToString` method with a parameter that represents a format string. - - :::code language="csharp" source="~/snippets/csharp/System/Object/ToString/customize2.cs" interactive="try-dotnet" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Object/ToString/customize2.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.object.tostring/vb/customize2.vb" id="Snippet8"::: - - -## Notes for the Windows Runtime - When you call the method on a class in the Windows Runtime, it provides the default behavior for classes that don't override . This is part of the support that the .NET Framework provides for the Windows Runtime (see [.NET Framework Support for Windows Store Apps and Windows Runtime](/dotnet/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime)). Classes in the Windows Runtime don't inherit , and don't always implement a . However, they always appear to have , , and methods when you use them in your C# or Visual Basic code, and the .NET Framework provides a default behavior for these methods. - - Starting with .NET Framework 4.5.1, the common language runtime uses [IStringable.ToString](xref:Windows.Foundation.IStringable.ToString) on a Windows Runtime object before falling back to the default implementation of . - -> [!NOTE] -> Windows Runtime classes that are written in C# or Visual Basic can override the method. - -### The Windows Runtime and the IStringable Interface - Starting with Windows 8.1, the Windows Runtime includes an [IStringable](xref:Windows.Foundation.IStringable) interface whose single method, [IStringable.ToString](xref:Windows.Foundation.IStringable.ToString), provides basic formatting support comparable to that provided by . To prevent ambiguity, you should not implement [IStringable](xref:Windows.Foundation.IStringable) on managed types. - - When managed objects are called by native code or by code written in languages such as JavaScript or C++/CX, they appear to implement [IStringable](xref:Windows.Foundation.IStringable). The common language runtime automatically routes calls from [IStringable.ToString](xref:Windows.Foundation.IStringable.ToString) to if [IStringable](xref:Windows.Foundation.IStringable) is not implemented on the managed object. - -> [!WARNING] -> Because the common language runtime auto-implements [IStringable](xref:Windows.Foundation.IStringable) for all managed types in Windows Store apps, we recommend that you do not provide your own `IStringable` implementation. Implementing `IStringable` may result in unintended behavior when calling `ToString` from the Windows Runtime, C++/CX, or JavaScript. - - If you do choose to implement [IStringable](xref:Windows.Foundation.IStringable) in a public managed type that's exported in a Windows Runtime component, the following restrictions apply: - -- You can define the [IStringable](xref:Windows.Foundation.IStringable) interface only in a "class implements" relationship, as follows: - - ```csharp - public class NewClass : IStringable - ``` - - ```vb - Public Class NewClass : Implements IStringable - ``` - -- You cannot implement [IStringable](xref:Windows.Foundation.IStringable) on an interface. - -- You cannot declare a parameter to be of type [IStringable](xref:Windows.Foundation.IStringable). - -- [IStringable](xref:Windows.Foundation.IStringable) cannot be the return type of a method, property, or field. - -- You cannot hide your [IStringable](xref:Windows.Foundation.IStringable) implementation from base classes by using a method definition such as the following: - - ```csharp - - public class NewClass : IStringable - { - public new string ToString() - { - return "New ToString in NewClass"; - } - } - - ``` - - Instead, the [IStringable.ToString](xref:Windows.Foundation.IStringable.ToString) implementation must always override the base class implementation. You can hide a `ToString` implementation only by invoking it on a strongly typed class instance. - - Note that under a variety of conditions, calls from native code to a managed type that implements [IStringable](xref:Windows.Foundation.IStringable) or hides its [ToString](xref:Windows.Foundation.IStringable.ToString) implementation can produce unexpected behavior. - - ]]> - + For more information about this API, see Supplemental API remarks for Object.ToString. When you implement your own types, you should override the method to return values that are meaningful for those types. Derived classes that require more control over formatting than provides can implement the interface. Its method enables you to define format strings that control formatting and to use an object that can provide for culture-specific formatting. diff --git a/xml/System/Single.xml b/xml/System/Single.xml index a8eab177935..7cd751a7cc2 100644 --- a/xml/System/Single.xml +++ b/xml/System/Single.xml @@ -1068,35 +1068,17 @@ This computes `arctan(x) / π` in the interval `[-0.5, +0.5]`. Greater than zero This instance is greater than , OR this instance is a number and is not a number (), OR is . - + For more information about this API, see Supplemental API remarks for Single.CompareTo. + method. -## Remarks - The `value` parameter must be `null` or an instance of ; otherwise, an exception is thrown. Any instance of , regardless of its value, is considered greater than `null`. - - Values must be identical to be considered equal. Particularly when floating-point values depend on multiple mathematical operations, it is common for them to lose precision and for their values to be nearly identical except for their least significant digits. Because of this, the return value of the method may seem surprising at times. For example, multiplication by a particular value followed by division by the same value should produce the original value, but in the following example, the computed value turns out to be greater than the original value. Showing all significant digits of the two values by using the "R" [standard numeric format string](/dotnet/standard/base-types/standard-numeric-format-strings) indicates that the computed value differs from the original value in its least significant digits. For information about handling such comparisons, see the Remarks section of the method. - - :::code language="csharp" source="~/snippets/csharp/System/Single/CompareTo/compareto3.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Single/CompareTo/compareto3.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.single.compareto/vb/compareto3.vb" id="Snippet2"::: - - This method is implemented to support the interface. Note that, although a is not considered to be equal to another (even itself), the interface requires that `A.CompareTo(A)` return zero. - -## Precision in Comparisons - The precision of floating-point numbers beyond the documented precision is specific to the implementation and version of the .NET Framework. Consequently, a comparison of two particular numbers might change between versions of the .NET Framework because the precision of the numbers' internal representation might change. - - - -## Examples - The following code example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Single/CPP/singlesample.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System/Single/CompareTo/singlesample.cs" id="Snippet16"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Single/CompareTo/singlesample.fs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Single/VB/singlesample.vb" id="Snippet16"::: - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Single/CPP/singlesample.cpp" id="Snippet16"::: +:::code language="csharp" source="~/snippets/csharp/System/Single/CompareTo/singlesample.cs" id="Snippet16"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Single/CompareTo/singlesample.fs" id="Snippet16"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Single/VB/singlesample.vb" id="Snippet16"::: + ]]> + is not a . @@ -1166,42 +1148,17 @@ This computes `arctan(x) / π` in the interval `[-0.5, +0.5]`. This instance is greater than , or this instance is a number and is not a number (). - + For more information about this API, see Supplemental API remarks for Single.CompareTo. + method at times may seem surprising. For example, multiplication by any value followed by division by the same value should produce the original value. However, in the following example, the computed value turns out to be greater than the original value. Showing all significant digits of the two values by using the "R" [standard numeric format string](/dotnet/standard/base-types/standard-numeric-format-strings) indicates that the computed value differs from the original value in its least significant digits. For information about handling such comparisons, see the Remarks section of the method. - - :::code language="csharp" source="~/snippets/csharp/System/Single/CompareTo/compareto2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Single/CompareTo/compareto2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.single.compareto/vb/compareto2.vb" id="Snippet1"::: - - This method implements the interface and performs slightly better than the method because it does not have to convert the `value` parameter to an object. - - Note that, although an object whose value is is not considered equal to another object whose value is (even itself), the interface requires that `A.CompareTo(A)` return zero. - -## Widening Conversions - Depending on your programming language, it might be possible to code a method where the parameter type has fewer bits (is narrower) than the instance type. This is possible because some programming languages perform an implicit widening conversion that represents the parameter as a type with as many bits as the instance. - - For example, suppose the instance type is and the parameter type is . The Microsoft C# compiler generates instructions to represent the value of the parameter as a object, then generates a method that compares the values of the instance and the widened representation of the parameter. - - Consult your programming language's documentation to determine if its compiler performs implicit widening conversions of numeric types. For more information, see the [Type Conversion Tables](/dotnet/standard/base-types/conversion-tables) topic. - -## Precision in Comparisons - The precision of floating-point numbers beyond the documented precision is specific to the implementation and version of the .NET Framework. Consequently, a comparison of two particular numbers might change between versions of the .NET Framework because the precision of the numbers' internal representation might change. - - - -## Examples - The following code example demonstrates generic and nongeneric versions of the method for several value and reference types. +The following code example demonstrates generic and nongeneric versions of the method for several value and reference types. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/T.CompareTo/CPP/cat.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Boolean/CompareTo/cat.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Boolean/CompareTo/cat.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/T.CompareTo/VB/cat.vb" id="Snippet1"::: - - ]]> - + ]]> + @@ -1648,36 +1605,7 @@ This is known as Euler's number and is approximately 2.7182818284590452354. 1.401298E-45 Represents the smallest positive value that is greater than zero. This field is constant. - - property reflects the smallest positive value that is significant in numeric operations or comparisons when the value of the instance is zero. For example, the following code shows that zero and are considered to be unequal values, whereas zero and half the value of are considered to be equal. - - :::code language="csharp" source="~/snippets/csharp/System/Single/Epsilon/epsilon.cs" interactive="try-dotnet" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Single/Epsilon/epsilon.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Single.Epsilon/vb/epsilon.vb" id="Snippet5"::: - - More precisely, the single-precision floating-point format consists of a sign, a 23-bit mantissa or significand, and an 8-bit exponent. As the following example shows, zero has an exponent of -126 and a mantissa of 0. has an exponent of -126 and a mantissa of 1. This means that is the smallest positive value that is greater than zero and represents the smallest possible value and the smallest possible increment for a whose exponent is -126. - - :::code language="csharp" source="~/snippets/csharp/System/Single/Epsilon/epsilon1.cs" interactive="try-dotnet" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Single/Epsilon/epsilon1.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Single.Epsilon/vb/epsilon1.vb" id="Snippet6"::: - - However, the property is not a general measure of precision of the type; it applies only to instances that have a value of zero. - -> [!NOTE] -> The value of the property is not equivalent to machine epsilon, which represents the upper bound of the relative error due to rounding in floating-point arithmetic. - - The value of this constant is 1.4e-45. - - Two apparently equivalent floating-point numbers might not compare equal because of differences in their least significant digits. For example, the C# expression, `(float)1/3 == (float)0.33333`, does not compare equal because the division operation on the left side has maximum precision while the constant on the right side is precise only to the specified digits. If you create a custom algorithm that determines whether two floating-point numbers can be considered equal, you must use a value that is greater than the constant to establish the acceptable absolute margin of difference for the two values to be considered equal. (Typically, that margin of difference is many times greater than .) - -## Platform Notes - On ARM systems, the value of the constant is too small to be detected, so it equates to zero. You can define an alternative epsilon value that equals 1.175494351E-38 instead. - - ]]> - + For more information about this API, see Supplemental API remarks for Single.Epsilon. @@ -1844,47 +1772,7 @@ This is known as Euler's number and is approximately 2.7182818284590452354. Returns a value indicating whether this instance and a specified object represent the same value. if is equal to this instance; otherwise, . - - interface, and performs slightly better than because it does not have to convert the `obj` parameter to an object. - -## Widening Conversions - Depending on your programming language, it might be possible to code an method where the parameter type has fewer bits (is narrower) than the instance type. This is possible because some programming languages perform an implicit widening conversion that represents the parameter as a type with as many bits as the instance. - - For example, suppose the instance type is and the parameter type is . The Microsoft C# compiler generates instructions to represent the value of the parameter as a object, and then generates a method that compares the values of the instance and the widened representation of the parameter. - - Consult your programming language's documentation to determine if its compiler performs implicit widening conversions of numeric types. For more information, see the [Type Conversion Tables](/dotnet/standard/base-types/conversion-tables) topic. - -## Precision in Comparisons - The method should be used with caution, because two apparently equivalent values can be unequal because of the differing precision of the two values. The following example reports that the value .3333 and the returned by dividing 1 by 3 are unequal. - - :::code language="csharp" source="~/snippets/csharp/System/Single/Epsilon/SingleEquals_25051.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Single/Epsilon/SingleEquals_25051.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Single.Epsilon/vb/SingleEquals_25051.vb" id="Snippet1"::: - - One comparison technique that avoids the problems associated with comparing for equality involves defining an acceptable margin of difference between two values (such as .01% of one of the values). If the absolute value of the difference between the two values is less than or equal to that margin, the difference is likely to be an outcome of differences in precision and, therefore, the values are likely to be equal. The following example uses this technique to compare .33333 and 1/3, which are the two values that the previous code example found to be unequal. - - :::code language="csharp" source="~/snippets/csharp/System/Single/Epsilon/SingleEquals_25051.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Single/Epsilon/SingleEquals_25051.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Single.Epsilon/vb/SingleEquals_25051.vb" id="Snippet2"::: - - In this case, the values are equal. - -> [!NOTE] -> Because defines the minimum expression of a positive value whose range is near zero, the margin of difference must be greater than . Typically, it is many times greater than . Because of this, we recommend that you do not use when comparing values for equality. - - A second technique that avoids the problems associated with comparing for equality involves comparing the difference between two floating-point numbers with some absolute value. If the difference is less than or equal to that absolute value, the numbers are equal. If it is greater, the numbers are not equal. One way to do this is to arbitrarily select an absolute value. However, this is problematic, because an acceptable margin of difference depends on the magnitude of the values. A second way takes advantage of a design feature of the floating-point format: The difference between the mantissa components in the integer representations of two floating-point values indicates the number of possible floating-point values that separates the two values. For example, the difference between 0.0 and is 1, because is the smallest representable value when working with a whose value is zero. The following example uses this technique to compare .33333 and 1/3, which are the two values that the previous code example with the method found to be unequal. Note that the example uses the and methods to convert a single-precision floating-point value to its integer representation. - - :::code language="csharp" source="~/snippets/csharp/System/Single/Equals/equalsabs1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Single/Equals/equalsabs1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.single.equals/vb/equalsabs1.vb" id="Snippet1"::: - - The precision of floating-point numbers beyond the documented precision is specific to the implementation and version of the .NET Framework. Consequently, a comparison of two numbers might produce different results depending on the version of the .NET Framework, because the precision of the numbers' internal representation might change. - - ]]> - + For more information about this API, see Supplemental API remarks for Single.Equals. Compiler overload resolution may account for an apparent difference in the behavior of the two method overloads. If an implicit conversion between the argument and a is defined and the argument is not typed as an , compilers may perform an implicit conversion and call the method. Otherwise, they call the method, which always returns if its argument is not a value. The following example illustrates the difference in behavior between the two method overloads. In the case of all primitive numeric types except for in Visual Basic and except for and in C#, the first comparison returns because the compiler automatically performs a widening conversion and calls the method, whereas the second comparison returns because the compiler calls the method. diff --git a/xml/System/String.xml b/xml/System/String.xml index 2bc951d579c..e9a3dd5cf94 100644 --- a/xml/System/String.xml +++ b/xml/System/String.xml @@ -146,228 +146,7 @@ Initializes a new instance of the class. - - -## Overloaded constructor syntax - -String constructors fall into two categories: those without pointer parameters, and those with pointer parameters. The constructors that use pointers are not CLS-compliant. In addition, Visual Basic does not support the use of pointers, and C# requires code that uses pointers to run in an unsafe context. For more information, see [unsafe](/dotnet/csharp/language-reference/keywords/unsafe). - -For additional guidance on choosing an overload, see [Which method do I call?](#Tasks). - - `String(Char[] value)`\ - Initializes the new instance to the value indicated by an array of Unicode characters. This constructor copies Unicode characters([example](#Ctor2_Example)). - - `String(Char[] value, Int32 startIndex, Int32 length)`\ - Initializes the new instance to the value indicated by an array of Unicode characters, a starting character position within that array, and a length ([example](#Ctor3_Example)). - - `String(Char c, Int32 count)`\ - Initializes the new instance to the value indicated by a specified Unicode character repeated a specified number of times ([example](#Ctor3_Example)). - - `String(char* value)`\ - **(Not CLS-compliant)** Initializes the new instance to the value indicated by a pointer to an array of Unicode characters that is terminated by a null character (U+0000 or '\0'). ([example](#Ctor4_Example)). - - Permission: , requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code. - - `String(char* value, Int32 startIndex, Int32 length)`\ - **(Not CLS-compliant)** Initializes the new instance to the value indicated by a pointer to an array of Unicode characters, a starting character position within that array, and a length. The constructor copies the Unicode characters from `value` starting at index `startIndex` and ending at index `startIndex` + `length` - 1 ([example](#Ctor5_Example)). - - Permission: , requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code. - - `String(SByte* value)`\ - **(Not CLS-compliant)** Initializes the new instance to the value indicated by a pointer to an array of 8-bit signed integers. The array is assumed to represent a string encoded using the current system code page (that is, the encoding specified by ). The constructor processes characters from `value` starting from the location specified by the pointer until a null character (0x00) is reached ([example](#Ctor6_Example)). - - Permission: , requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code. - - `String(SByte* value, Int32 startIndex, Int32 length)`\ - **(Not CLS-compliant)** Initializes the new instance to the value indicated by a pointer to an array of 8-bit signed integers, a starting position within that array, and a length. The array is assumed to represent a string encoded using the current system code page (that is, the encoding specified by ). The constructor processes characters from value starting at `startIndex` and ending at `startIndex` + `length` - 1 ([example](#Ctor6_Example)). - - Permission: , requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code. - - `String(SByte* value, Int32 startIndex, Int32 length, Encoding enc)`\ - **(Not CLS-compliant)** Initializes the new instance to the value indicated by a pointer to an array of 8-bit signed integers, a starting position within that array, a length, and an object. - - Permission: , requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code. - - -## Parameters - -Here is a complete list of parameters used by constructors that don't include a pointer parameter. For the parameters used by each overload, see the overload syntax above. - -|Parameter|Type|Description| -|---------------|----------|-----------------| -|`value`|[]|An array of Unicode characters.| -|`c`||A Unicode character.| -|`startIndex`||The starting position in `value` of the first character in the new string.

Default value: 0| -|`length`||The number of characters in `value` to include in the new string.

Default value: | -|`count`||The number of times the character `c` is repeated in the new string. If `count` is zero, the value of the new object is .| - - Here is a complete list of parameters used by constructors that include a pointer parameter. For the parameters used by each overload, see the overload syntax above. - -|Parameter|Type|Description| -|---------------|----------|-----------------| -|`value`|*

-or-

\*|A pointer to a null-terminated array of Unicode characters or an array of 8-bit signed integers. If `value` is `null` or an empty array, the value of the new string is .| -|`startIndex`||The index of the array element that defines the first character in the new string.

Default value: 0| -|`length`||The number of array elements to use to create the new string. If length is zero, the constructor creates a string whose value is .

Default value: | -|`enc`||An object that specifies how the `value` array is encoded.

Default value: , or the system's current ANSI code page| - - -## Exceptions - Here's a list of exceptions thrown by constructors that don't include pointer parameters. - -|Exception|Condition|Thrown by| -|---------------|---------------|---------------| -||`value` is `null`.|| -||`startIndex`,`length`, or `count` is less than zero.

-or-

The sum of `startIndex` and `length` is greater than the number of elements in `value`.

-or-

`count` is less than zero.|

| - - Here's a list of exceptions thrown by constructors that include pointer parameters. - -|Exception|Condition|Thrown by| -|---------------|---------------|---------------| -||`value` specifies an array that contains an invalid Unicode character.

-or-

`value` or `value` + `startIndex` specifies an address that is less than 64K.

-or-

A new instance could not be initialized from the `value` byte array because `value` does not use the default code page encoding.|All constructors with pointers.| -||`value` is null.|



| -||The current process does not have read access to all the addressed characters.

-or-

`startIndex` or `length` is less than zero, `value` + `startIndex` cause a pointer overflow, or the current process does not have read access to all the addressed characters.

-or-

The length of the new string is too large to allocate.|All constructors with pointers.| -||`value`, or `value` + `startIndex` + `length` - 1, specifies an invalid address.|



| - - -## Which method do I call? - -|To|Call or use| -|--------|-----------------| -|Create a string.|Assignment from a string literal or an existing string ([example](#Ctor1_Example))| -|Create a string from an entire character array.| ([example](#Ctor2_Example))| -|Create a string from a portion of a character array.| ([example](#Ctor3_Example))| -|Create a string that repeats the same character multiple times.| ([example](#Ctor3_Example))| -|Create a string from a pointer to a Unicode or wide character array.|| -|Create a string from a portion of a Unicode or wide character array by using its pointer.|| -|Create a string from a C++ `char` array.|,

-or-

| -|Create a string from ASCII characters.|| - - -## Create strings - -The most commonly used technique for creating strings programmatically is simple assignment, as illustrated in [this example](#Ctor1_Example). The class also includes four types of constructor overloads that let you create strings from the following values: - -- From a character array (an array of UTF-16-encoded characters). You can create a new object from the characters in the entire array or a portion of it. The constructor copies all the characters in the array to the new string. The constructor copies the characters from index `startIndex` to index `startIndex` + `length` - 1 to the new string. If `length` is zero, the value of the new string is . - - If your code repeatedly instantiates strings that have the same value, you can improve application performance by using an alternate means of creating strings. For more information, see [Handling repetitive strings](#Repetitive). - -- From a single character that is duplicated zero, one, or more times, by using the constructor. If `count` is zero, the value of the new string is . - -- From a pointer to a null-terminated character array, by using the or constructor. Either the entire array or a specified range can be used to initialize the string. The constructor copies a sequence of Unicode characters starting from the specified pointer or from the specified pointer plus `startIndex` and continuing to the end of the array or for `length` characters. If `value` is a null pointer or `length` is zero, the constructor creates a string whose value is . If the copy operation proceeds to the end of the array and the array is not null-terminated, the constructor behavior is system-dependent. Such a condition might cause an access violation. - - If the array contains any embedded null characters (U+0000 or '\0') and the overload is called, the string instance contains `length` characters including any embedded nulls. The following example shows what happens when a pointer to an array of 10 elements that includes two null characters is passed to the method. Because the address is the beginning of the array and all elements in the array are to be added to the string, the constructor instantiates a string with ten characters, including two embedded nulls. On the other hand, if the same array is passed to the constructor, the result is a four-character string that does not include the first null character. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/chptrctor_null.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System/String/.ctor/chptrctor_null.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/.ctor/chptrctor_null.fs" id="Snippet5"::: - - The array must contain Unicode characters. In C++, this means that the character array must be defined either as the managed [] type or the unmanaged`wchar_t`[] type. - - If the overload is called and the array is not null-terminated, or if the overload is called and `startIndex` + `length`-1 includes a range that is outside the memory allocated for the sequence of characters, the behavior of the constructor is system-dependent, and an access violation may occur. - -- From a pointer to a signed byte array. Either the entire array or a specified range can be used to initialize the string. The sequence of bytes can be interpreted by using the default code page encoding, or an encoding can be specified in the constructor call. If the constructor tries to instantiate a string from an entire array that is not null-terminated, or if the range of the array from `value` + `startIndex` to `value` + `startIndex` + `length` -1 is outside of the memory allocated for the array, the behavior of this constructor is system-dependent, and an access violation may occur. - - The three constructors that include a signed byte array as a parameter are designed primarily to convert a C++ `char` array to a string, as shown in this example: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/sbyte_ctor1.cpp" id="Snippet4"::: - - If the array contains any null characters ('\0') or bytes whose value is 0 and the overload is called, the string instance contains `length` characters including any embedded nulls. The following example shows what happens when a pointer to an array of 10 elements that includes two null characters is passed to the method. Because the address is the beginning of the array and all elements in the array are to be added to the string, the constructor instantiates a string with ten characters, including two embedded nulls. On the other hand, if the same array is passed to the constructor, the result is a four-character string that does not include the first null character. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/ptrctor_null.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System/String/.ctor/ptrctor_null.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/.ctor/ptrctor_null.fs" id="Snippet6"::: - - Because the and constructors interpret `value` by using the default ANSI code page, calling these constructors with identical byte arrays may create strings that have different values on different systems. - - -## Handle repetitive strings - -Apps that parse or decode streams of text often use the constructor or the method to convert sequences of characters into a string. Repeatedly creating new strings with the same value instead of creating and reusing one string wastes memory. If you are likely to create the same string value repeatedly by calling the constructor, even if you don't know in advance what those identical string values may be, you can use a lookup table instead. - -For example, suppose you read and parse a stream of characters from a file that contains XML tags and attributes. When you parse the stream, you repeatedly encounter certain tokens (that is, sequences of characters that have a symbolic meaning). Tokens equivalent to the strings "0", "1", "true", and "false" are likely to occur frequently in an XML stream. - -Instead of converting each token into a new string, you can create a object to hold commonly occurring strings. The object improves performance, because it retrieves stored strings without allocating temporary memory. When you encounter a token, use the method to retrieve the token from the table. If the token exists, the method returns the corresponding string. If the token does not exist, use the method to insert the token into the table and to get the corresponding string. - - -## Example 1: Use string assignment - -The following example creates a new string by assigning it a string literal. It creates a second string by assigning the value of the first string to it. These are the two most common ways to instantiate a new object. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/assignment.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/.ctor/ctor1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/.ctor/ctor1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.ctor/vb/ctor1.vb" id="Snippet1"::: - - -## Example 2: Use a character array - -The following example demonstrates how to create a new object from a character array. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringexample1/CPP/source.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/.ctor/source.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/.ctor/source.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringexample1/VB/source.vb" id="Snippet1"::: - - -## Example 3: Use a portion of a character array and repeating a single character - -The following example demonstrates how to create a new object from a portion of a character array, and how to create a new object that contains multiple occurrences of a single character. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringexample1/CPP/source.cpp" id="Snippet3"::: -:::code language="csharp" source="~/snippets/csharp/System/String/.ctor/source.cs" interactive="try-dotnet-method" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/.ctor/source.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringexample1/VB/source.vb" id="Snippet3"::: - - -## Example 4: Use a pointer to a character array - -The following example demonstrates how to create a new object from a pointer to an array of characters. The C# example must be compiled by using the `/unsafe` compiler switch. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/char1_ctor.cpp" id="Snippet2"::: -:::code language="csharp" source="~/snippets/csharp/System/String/.ctor/ctor2.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/.ctor/ctor2.fs" id="Snippet2"::: - - -## Example 5: Instantiate a string from a pointer and a range of an array - -The following example examines the elements of a character array for either a period or an exclamation point. If one is found, it instantiates a string from the characters in the array that precede the punctuation symbol. If not, it instantiates a string with the entire contents of the array. The C# example must be compiled using the `/unsafe` compiler switch. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/char2_ctor.cpp" id="Snippet3"::: -:::code language="csharp" source="~/snippets/csharp/System/String/.ctor/char2_ctor.cs" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/.ctor/char2_ctor.fs" id="Snippet3"::: - - -## Example 6: Instantiate a string from a pointer to a signed byte array - -The following example demonstrates how you can create an instance of the class with the constructor. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringexample1/CPP/source.cpp" id="Snippet2"::: -:::code language="csharp" source="~/snippets/csharp/System/String/.ctor/source.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/.ctor/source.fs" id="Snippet2"::: - - ]]> - + For more information about this API, see Supplemental API remarks for String constructor. @@ -807,9 +586,9 @@ The following example demonstrates how you can create an instance of the or is less than zero. - -or- +-or- - The sum of and is greater than the number of elements in . +The sum of and is greater than the number of elements in . @@ -880,18 +659,18 @@ The following example demonstrates how you can create an instance of the or is less than zero. - -or- +-or- - The address specified by + is too large for the current platform; that is, the address calculation overflowed. +The address specified by + is too large for the current platform; that is, the address calculation overflowed. - -or- +-or- - The length of the new string to initialize is too large to allocate. +The length of the new string to initialize is too large to allocate. The address specified by + is less than 64K. - -or- +-or- - A new instance of could not be initialized using , assuming is encoded in ANSI. +A new instance of could not be initialized using , assuming is encoded in ANSI. , , and collectively specify an invalid address. @@ -973,18 +752,18 @@ The following example demonstrates how you can create an instance of the or is less than zero. - -or- +-or- - The address specified by + is too large for the current platform; that is, the address calculation overflowed. +The address specified by + is too large for the current platform; that is, the address calculation overflowed. - -or- +-or- - The length of the new string to initialize is too large to allocate. +The length of the new string to initialize is too large to allocate. The address specified by + is less than 64K. - -or- +-or- - A new instance of could not be initialized using , assuming is encoded as specified by . +A new instance of could not be initialized using , assuming is encoded as specified by . , , and collectively specify an invalid address. @@ -1043,23 +822,23 @@ The following example demonstrates how you can create an instance of the object at the position specified by the `index` parameter. However, a Unicode character might be represented by more than one . Use the class to work with Unicode characters instead of objects. For more information, see the "Char Objects and Unicode Characters" section in the class overview. +This property returns the object at the position specified by the `index` parameter. However, a Unicode character might be represented by more than one . Use the class to work with Unicode characters instead of objects. For more information, see the "Char Objects and Unicode Characters" section in the class overview. - In C#, the property is an indexer. In Visual Basic, it is the default property of the class. Each object in the string can be accessed by using code such as the following. +In C#, the property is an indexer. In Visual Basic, it is the default property of the class. Each object in the string can be accessed by using code such as the following. - :::code language="csharp" source="~/snippets/csharp/System/String/Chars/chars1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Chars/chars1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.chars/vb/chars1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Chars/chars1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Chars/chars1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.chars/vb/chars1.vb" id="Snippet1"::: ## Examples - The following example demonstrates how you can use this indexer in a routine to validate a string. +The following example demonstrates how you can use this indexer in a routine to validate a string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Uri_IsHexDigit/CPP/uri_ishexdigit.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Chars/uri_ishexdigit.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Chars/uri_ishexdigit.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Uri_IsHexDigit/VB/uri_ishexdigit.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Uri_IsHexDigit/CPP/uri_ishexdigit.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Chars/uri_ishexdigit.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Chars/uri_ishexdigit.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Uri_IsHexDigit/VB/uri_ishexdigit.vb" id="Snippet1"::: ]]> @@ -1114,9 +893,9 @@ The following example demonstrates how you can create an instance of the or method to create a separate object with the same value as this instance. +The return value is not an independent copy of this instance; it is simply another view of the same data. Use the or method to create a separate object with the same value as this instance. - Because the method simply returns the existing string instance, there is little reason to call it directly. +Because the method simply returns the existing string instance, there is little reason to call it directly. ]]> @@ -1138,7 +917,7 @@ The following example demonstrates how you can create an instance of the method return a 32-bit signed integer indicating the lexical relationship between the two comparands. +All overloads of the method return a 32-bit signed integer indicating the lexical relationship between the two comparands. |Value|Condition| |-----------|---------------| @@ -1212,77 +991,77 @@ The following example demonstrates how you can create an instance of the Compares two specified objects and returns an integer that indicates their relative position in the sort order. A 32-bit signed integer that indicates the lexical relationship between the two comparands. - Value + Value - Condition + Condition - Less than zero + Less than zero - precedes in the sort order. + precedes in the sort order. - Zero + Zero - occurs in the same position as in the sort order. + occurs in the same position as in the sort order. - Greater than zero + Greater than zero - follows in the sort order. + follows in the sort order. - + . +The comparison is performed using word sort rules. For more information about word, string, and ordinal sorts, see . > [!WARNING] > When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). - One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. +The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet10"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet10"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet10"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet10"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet10"::: - Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: +Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet11"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet11"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet11"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet11"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet11"::: ## Examples - The following example calls the method to compare three sets of strings. +The following example calls the method to compare three sets of strings. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/compare02.cpp" id="Snippet18"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare02.cs" interactive="try-dotnet-method" id="Snippet18"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare02.fs" id="Snippet18"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare02.vb" id="Snippet18"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/compare02.cpp" id="Snippet18"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare02.cs" interactive="try-dotnet-method" id="Snippet18"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare02.fs" id="Snippet18"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare02.vb" id="Snippet18"::: - In the following example, the `ReverseStringComparer` class demonstrates how you can evaluate two strings with the method. +In the following example, the `ReverseStringComparer` class demonstrates how you can evaluate two strings with the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ArrayList/CPP/ArrayListSample.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/ArrayListSample.cs" interactive="try-dotnet" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/ArrayListSample.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArrayList/VB/ArrayListSample.vb" id="Snippet7"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ArrayList/CPP/ArrayListSample.cpp" id="Snippet7"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/ArrayListSample.cs" interactive="try-dotnet" id="Snippet7"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/ArrayListSample.fs" id="Snippet7"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArrayList/VB/ArrayListSample.vb" id="Snippet7"::: ]]> Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a culture-sensitive comparison of "animal" with "ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare21.cs" id="Snippet21"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare21.fs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare21.vb" id="Snippet21"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare21.cs" id="Snippet21"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare21.fs" id="Snippet21"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare21.vb" id="Snippet21"::: - To recognize ignorable characters in a string comparison, call the method and supply a value of either or for the `comparisonType` parameter. +To recognize ignorable characters in a string comparison, call the method and supply a value of either or for the `comparisonType` parameter. @@ -1348,70 +1127,70 @@ The following example demonstrates how you can create an instance of the Compares two specified objects, ignoring or honoring their case, and returns an integer that indicates their relative position in the sort order. A 32-bit signed integer that indicates the lexical relationship between the two comparands. - Value + Value - Condition + Condition - Less than zero + Less than zero - precedes in the sort order. + precedes in the sort order. - Zero + Zero - occurs in the same position as in the sort order. + occurs in the same position as in the sort order. - Greater than zero + Greater than zero - follows in the sort order. + follows in the sort order. - + . +The comparison is performed using word sort rules. For more information about word, string, and ordinal sorts, see . > [!WARNING] > When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). - One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. +The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet12"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet12"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet12"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet12"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet12"::: - Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: +Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet13"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet13"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet13"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet13"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet13"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet13"::: ## Examples - The following example demonstrates that the method is equivalent to using or when comparing strings. +The following example demonstrates that the method is equivalent to using or when comparing strings. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/compare02.cpp" id="Snippet18"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare02.cs" interactive="try-dotnet-method" id="Snippet18"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare02.fs" id="Snippet18"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare02.vb" id="Snippet18"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/compare02.cpp" id="Snippet18"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare02.cs" interactive="try-dotnet-method" id="Snippet18"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare02.fs" id="Snippet18"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare02.vb" id="Snippet18"::: ]]> Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a culture-sensitive, case-insensitive comparison of "animal" with "Ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare22.cs" id="Snippet22"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare22.fs" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare22.vb" id="Snippet22"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare22.cs" id="Snippet22"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare22.fs" id="Snippet22"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare22.vb" id="Snippet22"::: - To recognize ignorable characters in a string comparison, call the method and supply a value of either or for the parameter. +To recognize ignorable characters in a string comparison, call the method and supply a value of either or for the parameter. @@ -1478,54 +1257,54 @@ The following example demonstrates how you can create an instance of the Compares two specified objects using the specified rules, and returns an integer that indicates their relative position in the sort order. A 32-bit signed integer that indicates the lexical relationship between the two comparands. - Value + Value - Condition + Condition - Less than zero + Less than zero - precedes in the sort order. + precedes in the sort order. - Zero + Zero - is in the same position as in the sort order. + is in the same position as in the sort order. - Greater than zero + Greater than zero - follows in the sort order. + follows in the sort order. - + @@ -1601,67 +1380,67 @@ The following example demonstrates how you can create an instance of the Compares two specified objects, ignoring or honoring their case, and using culture-specific information to influence the comparison, and returns an integer that indicates their relative position in the sort order. A 32-bit signed integer that indicates the lexical relationship between the two comparands. - Value + Value - Condition + Condition - Less than zero + Less than zero - precedes in the sort order. + precedes in the sort order. - Zero + Zero - occurs in the same position as in the sort order. + occurs in the same position as in the sort order. - Greater than zero + Greater than zero - follows in the sort order. + follows in the sort order. - + . +The comparison is performed using word sort rules. For more information about word, string, and ordinal sorts, see . - One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. +The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet14"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet14"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet14"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet14"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet14"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet14"::: - Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: +Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet15"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet15"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet15"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet15"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet15"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet15"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet15"::: ## Examples - The following example demonstrates how culture can affect a comparison. In Czech - Czech Republic culture, "ch" is a single character that is greater than "d". However, in English - United States culture, "ch" consists of two characters, and "c" is less than "d". +The following example demonstrates how culture can affect a comparison. In Czech - Czech Republic culture, "ch" is a single character that is greater than "d". However, in English - United States culture, "ch" consists of two characters, and "c" is less than "d". - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.comp4/CPP/string.comp4.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/string.comp4.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/string.comp4.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.comp4/VB/string.comp4.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.comp4/CPP/string.comp4.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/string.comp4.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/string.comp4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.comp4/VB/string.comp4.vb" id="Snippet1"::: ]]> Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a case-insensitive comparison of "animal" with "Ani-mal" (using a soft hyphen, or U+00AD) using the invariant culture indicates that the two strings are equivalent. - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare23.cs" id="Snippet23"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare23.fs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare23.vb" id="Snippet23"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare23.cs" id="Snippet23"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare23.fs" id="Snippet23"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare23.vb" id="Snippet23"::: - To recognize ignorable characters in a string comparison, call the method and supply a value of either or for the parameter. +To recognize ignorable characters in a string comparison, call the method and supply a value of either or for the parameter. @@ -1727,45 +1506,45 @@ The following example demonstrates how you can create an instance of the Compares two specified objects using the specified comparison options and culture-specific information to influence the comparison, and returns an integer that indicates the relationship of the two strings to each other in the sort order. A 32-bit signed integer that indicates the lexical relationship between and , as shown in the following table - Value + Value - Condition + Condition - Less than zero + Less than zero - precedes in the sort order. + precedes in the sort order. - Zero + Zero - occurs in the same position as in the sort order. + occurs in the same position as in the sort order. - Greater than zero + Greater than zero - follows in the sort order. + follows in the sort order. - + [!CAUTION] > The method is designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent (that is, when the purpose of the method call is to test for a return value of zero). To determine whether two strings are equivalent, call the method. - The comparison can be further specified by the `options` parameter, which consists of one or more members of the enumeration. However, because the purpose of this method is to conduct a culture-sensitive string comparison, the and values have no effect. +The comparison can be further specified by the `options` parameter, which consists of one or more members of the enumeration. However, because the purpose of this method is to conduct a culture-sensitive string comparison, the and values have no effect. - Either or both comparands can be `null`. By definition, any string, including , compares greater than a null reference, and two null references compare equal to each other. +Either or both comparands can be `null`. By definition, any string, including , compares greater than a null reference, and two null references compare equal to each other. - The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with the remaining characters is considered greater. +The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with the remaining characters is considered greater. ## Examples - The following example compares two strings in three different ways: Use linguistic comparison for the en-US culture; using linguistic case-sensitive comparison for the en-US culture; and using an ordinal comparison. It illustrates how the three methods of comparison produce three different results. +The following example compares two strings in three different ways: Use linguistic comparison for the en-US culture; using linguistic case-sensitive comparison for the en-US culture; and using an ordinal comparison. It illustrates how the three methods of comparison produce three different results. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/example.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/Example.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/Example.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/Example.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/example.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/Example.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/Example.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/Example.vb" id="Snippet1"::: ]]> @@ -1839,80 +1618,80 @@ The following example demonstrates how you can create an instance of the Compares substrings of two specified objects and returns an integer that indicates their relative position in the sort order. A 32-bit signed integer indicating the lexical relationship between the two comparands. - Value + Value - Condition + Condition - Less than zero + Less than zero - The substring in precedes the substring in in the sort order. + The substring in precedes the substring in in the sort order. - Zero + Zero - The substrings occur in the same position in the sort order, or is zero. + The substrings occur in the same position in the sort order, or is zero. - Greater than zero + Greater than zero - The substring in follows the substring in in the sort order. + The substring in follows the substring in in the sort order. - + . +The comparison is performed using word sort rules. For more information about word, string, and ordinal sorts, see . > [!WARNING] > When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). - One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. +The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet2"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet2"::: - Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: +Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet3"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet3"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet3"::: ## Examples - The following example compares two substrings. +The following example compares two substrings. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare3/CPP/comp3.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp3.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp3.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare3/VB/comp3.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare3/CPP/comp3.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp3.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp3.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare3/VB/comp3.vb" id="Snippet1"::: ]]> is greater than .. - -or- +-or- - is greater than .. + is greater than .. - -or- +-or- - , , or is negative. +, , or is negative. - -or- +-or- - Either or is , and is greater than zero. +Either or is , and is greater than zero. Character sets include ignorable characters. The method does not consider these characters when it performs a linguistic or culture-sensitive comparison. To recognize ignorable characters in your comparison, call the method and supply a value of or for the parameter. @@ -1980,80 +1759,80 @@ The following example demonstrates how you can create an instance of the Compares substrings of two specified objects, ignoring or honoring their case, and returns an integer that indicates their relative position in the sort order. A 32-bit signed integer that indicates the lexical relationship between the two comparands. - Value + Value - Condition + Condition - Less than zero + Less than zero - The substring in precedes the substring in in the sort order. + The substring in precedes the substring in in the sort order. - Zero + Zero - The substrings occur in the same position in the sort order, or is zero. + The substrings occur in the same position in the sort order, or is zero. - Greater than zero + Greater than zero - The substring in follows the substring in in the sort order. + The substring in follows the substring in in the sort order. - + . +The comparison is performed using word sort rules. For more information about word, string, and ordinal sorts, see . > [!WARNING] > When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). - One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. +The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet4"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet4"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet4"::: - The path name needs to be compared in an invariant manner. The correct code to do this is as follows. +The path name needs to be compared in an invariant manner. The correct code to do this is as follows. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet5"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet5"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet5"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet5"::: ## Examples - The following example performs two comparisons of two substrings that only differ in case. The first comparison ignores case and the second comparison considers case. +The following example performs two comparisons of two substrings that only differ in case. The first comparison ignores case and the second comparison considers case. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare4/CPP/comp4.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp4.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp4.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare4/VB/comp4.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare4/CPP/comp4.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp4.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare4/VB/comp4.vb" id="Snippet1"::: ]]> is greater than .. - -or- +-or- - is greater than .. + is greater than .. - -or- +-or- - , , or is negative. +, , or is negative. - -or- +-or- - Either or is , and is greater than zero. +Either or is , and is greater than zero. Character sets include ignorable characters. The method does not consider these characters when it performs a linguistic or culture-sensitive comparison. To recognize ignorable characters in your comparison, call the method and supply a value of or for the parameter. @@ -2127,75 +1906,75 @@ The following example demonstrates how you can create an instance of the Compares substrings of two specified objects using the specified rules, and returns an integer that indicates their relative position in the sort order. A 32-bit signed integer that indicates the lexical relationship between the two comparands. - Value + Value - Condition + Condition - Less than zero + Less than zero - The substring in precedes the substring in in the sort order. + The substring in precedes the substring in in the sort order. - Zero + Zero - The substrings occur in the same position in the sort order, or the parameter is zero. + The substrings occur in the same position in the sort order, or the parameter is zero. - Greater than zero + Greater than zero - The substring in follows the substring in in the sort order. + The substring in follows the substring in in the sort order. - + is greater than .. - -or- +-or- - is greater than .. + is greater than .. - -or- +-or- - , , or is negative. +, , or is negative. - -or- +-or- - Either or is , and is greater than zero. +Either or is , and is greater than zero. is not a value. @@ -2267,77 +2046,77 @@ The following example demonstrates how you can create an instance of the Compares substrings of two specified objects, ignoring or honoring their case and using culture-specific information to influence the comparison, and returns an integer that indicates their relative position in the sort order. An integer that indicates the lexical relationship between the two comparands. - Value + Value - Condition + Condition - Less than zero + Less than zero - The substring in precedes the substring in in the sort order. + The substring in precedes the substring in in the sort order. - Zero + Zero - The substrings occur in the same position in the sort order, or is zero. + The substrings occur in the same position in the sort order, or is zero. - Greater than zero + Greater than zero - The substring in follows the substring in in the sort order. + The substring in follows the substring in in the sort order. - + . +The comparison is performed using word sort rules. For more information about word, string, and ordinal sorts, see . - One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. +The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet6"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet6"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet6"::: - Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: +Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet7"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet7"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet7"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet7"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet7"::: ## Examples - The following example compares two substrings using different cultures and ignoring the case of the substrings. The choice of culture affects how the letter "I" is compared. +The following example compares two substrings using different cultures and ignoring the case of the substrings. The choice of culture affects how the letter "I" is compared. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare5/CPP/comp5.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp5.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp5.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare5/VB/comp5.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare5/CPP/comp5.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp5.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp5.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare5/VB/comp5.vb" id="Snippet1"::: ]]> is greater than .. - -or- +-or- - is greater than .. + is greater than .. - -or- +-or- - , , or is negative. +, , or is negative. - -or- +-or- - Either or is , and is greater than zero. +Either or is , and is greater than zero. Character sets include ignorable characters. The method does not consider these characters when it performs a linguistic or culture-sensitive comparison. To recognize ignorable characters in your comparison, call the method and supply a value of or for the parameter. @@ -2405,48 +2184,48 @@ The following example demonstrates how you can create an instance of the Compares substrings of two specified objects using the specified comparison options and culture-specific information to influence the comparison, and returns an integer that indicates the relationship of the two substrings to each other in the sort order. An integer that indicates the lexical relationship between the two substrings, as shown in the following table. - Value + Value - Condition + Condition - Less than zero + Less than zero - The substring in precedes the substring in in the sort order. + The substring in precedes the substring in in the sort order. - Zero + Zero - The substrings occur in the same position in the sort order, or is zero. + The substrings occur in the same position in the sort order, or is zero. - Greater than zero + Greater than zero - The substring in follows the substring in in the sort order. + The substring in follows the substring in in the sort order. - + [!CAUTION] > The method is designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two substrings are equivalent (that is, when the purpose of the method call is to test for a return value of zero). To determine whether two strings are equivalent, call the method. - One or both of `strA` and `strB` can be `null`. By definition, any string, including , compares greater than a null reference, and two null references compare equal to each other. +One or both of `strA` and `strB` can be `null`. By definition, any string, including , compares greater than a null reference, and two null references compare equal to each other. - The comparison can be further specified by the `options` parameter, which consists of one or more members of the enumeration. However, because the purpose of this method is to conduct a culture-sensitive string comparison, the and values have no effect. +The comparison can be further specified by the `options` parameter, which consists of one or more members of the enumeration. However, because the purpose of this method is to conduct a culture-sensitive string comparison, the and values have no effect. - The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with the remaining characters is considered greater. The return value is the result of the last comparison performed. +The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with the remaining characters is considered greater. The return value is the result of the last comparison performed. ## Examples - The following example uses the method to compare the last names of two people. It then lists them in alphabetical order. +The following example uses the method to compare the last names of two people. It then lists them in alphabetical order. - :::code language="csharp" source="~/snippets/csharp/System/String/Compare/Example1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/Example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare5/vb/Example.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/Example1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/Example1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare5/vb/Example.vb" id="Snippet1"::: ]]> @@ -2455,17 +2234,17 @@ The following example demonstrates how you can create an instance of the is greater than . - -or- +-or- - is greater than . + is greater than . - -or- +-or- - , , or is negative. +, , or is negative. - -or- +-or- - Either or is , and is greater than zero. +Either or is , and is greater than zero. Character sets include ignorable characters. The method does not consider these characters when it performs a linguistic or culture-sensitive comparison. To recognize ignorable characters in your comparison, supply a value of or for the parameter. @@ -2543,38 +2322,38 @@ The following example demonstrates how you can create an instance of the Compares two specified objects by evaluating the numeric values of the corresponding objects in each string. An integer that indicates the lexical relationship between the two comparands. - Value + Value - Condition + Condition - Less than zero + Less than zero - is less than . + is less than . - Zero + Zero - and are equal. + and are equal. - Greater than zero + Greater than zero - is greater than . + is greater than . - + . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . +This method performs a case-sensitive comparison using ordinal sort rules. For more information about word, string, and ordinal sorts, see . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . - Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. +Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. ## Examples - The following example performs and ordinal comparison of two strings that only differ in case. +The following example performs and ordinal comparison of two strings that only differ in case. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compareordinal/CPP/comp0.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/CompareOrdinal/comp0.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/CompareOrdinal/comp0.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compareordinal/VB/comp0.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compareordinal/CPP/comp0.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareOrdinal/comp0.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareOrdinal/comp0.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compareordinal/VB/comp0.vb" id="Snippet1"::: ]]> @@ -2651,55 +2430,55 @@ The following example demonstrates how you can create an instance of the Compares substrings of two specified objects by evaluating the numeric values of the corresponding objects in each substring. A 32-bit signed integer that indicates the lexical relationship between the two comparands. - Value + Value - Condition + Condition - Less than zero + Less than zero - The substring in is less than the substring in . + The substring in is less than the substring in . - Zero + Zero - The substrings are equal, or is zero. + The substrings are equal, or is zero. - Greater than zero + Greater than zero - The substring in is greater than the substring in . + The substring in is greater than the substring in . - + . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . +This method performs a case-sensitive comparison using ordinal sort rules. For more information about word, string, and ordinal sorts, see . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . - Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. +Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. ## Examples - This following example demonstrates that and use different sort orders. +This following example demonstrates that and use different sort orders. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringCompareOrdinal/CPP/stringcompareordinal.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/CompareOrdinal/stringcompareordinal.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/CompareOrdinal/stringcompareordinal.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringCompareOrdinal/VB/stringcompareordinal.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringCompareOrdinal/CPP/stringcompareordinal.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareOrdinal/stringcompareordinal.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareOrdinal/stringcompareordinal.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringCompareOrdinal/VB/stringcompareordinal.vb" id="Snippet1"::: ]]> is not and is greater than .. - -or- +-or- - is not and is greater than .. + is not and is greater than .. - -or- +-or- - , , or is negative. +, , or is negative. @@ -2717,7 +2496,7 @@ The following example demonstrates how you can create an instance of the method perform culture-sensitive and case-sensitive comparison. You cannot use this method to perform culture-insensitive or ordinal comparisons. For code clarity, we recommend that you avoid the method and call the method instead. +Both overloads of the method perform culture-sensitive and case-sensitive comparison. You cannot use this method to perform culture-insensitive or ordinal comparisons. For code clarity, we recommend that you avoid the method and call the method instead. ]]> @@ -2778,47 +2557,47 @@ The following example demonstrates how you can create an instance of the Compares this instance with a specified and indicates whether this instance precedes, follows, or appears in the same position in the sort order as the specified . A 32-bit signed integer that indicates whether this instance precedes, follows, or appears in the same position in the sort order as the parameter. - Value + Value - Condition + Condition - Less than zero + Less than zero - This instance precedes . + This instance precedes . - Zero + Zero - This instance has the same position in the sort order as . + This instance has the same position in the sort order as . - Greater than zero + Greater than zero - This instance follows . + This instance follows . - -or- +-or- - is . + is . - + object. +`value` must be a object. > [!CAUTION] > The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. - This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see . +This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see . - For more information about the behavior of this method, see the Remarks section of the method. +For more information about the behavior of this method, see the Remarks section of the method. ## Examples - The following example uses the method with an . Because it attempts to compare a instance to a `TestClass` object, the method throws an . +The following example uses the method with an . Because it attempts to compare a instance to a `TestClass` object, the method throws an . - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ExToString/CPP/extostring.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/extostring.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/extostring.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ExToString/VB/extostring.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ExToString/CPP/extostring.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/extostring.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/extostring.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ExToString/VB/extostring.vb" id="Snippet1"::: ]]> @@ -2827,11 +2606,11 @@ The following example demonstrates how you can create an instance of the Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a comparison of "animal" with "ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. - :::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/compareto1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/compareto1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.compareto/vb/compareto1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/compareto1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/compareto1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.compareto/vb/compareto1.vb" id="Snippet1"::: - To recognize ignorable characters in a string comparison, call the method. +To recognize ignorable characters in a string comparison, call the method. @@ -2899,65 +2678,65 @@ The following example demonstrates how you can create an instance of the Compares this instance with a specified object and indicates whether this instance precedes, follows, or appears in the same position in the sort order as the specified string. A 32-bit signed integer that indicates whether this instance precedes, follows, or appears in the same position in the sort order as the parameter. - Value + Value - Condition + Condition - Less than zero + Less than zero - This instance precedes . + This instance precedes . - Zero + Zero - This instance has the same position in the sort order as . + This instance has the same position in the sort order as . - Greater than zero + Greater than zero - This instance follows . + This instance follows . - -or- +-or- - is . + is . - + . +This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see . > [!CAUTION] > The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. - For more information about the behavior of this method, see the Remarks section of the method. +For more information about the behavior of this method, see the Remarks section of the method. - This method implements the interface and performs slightly better than the method, because it does not have to determine whether the `strB` argument is a mutable value type that must be boxed, and it does not have to cast its parameter from an to a . +This method implements the interface and performs slightly better than the method, because it does not have to determine whether the `strB` argument is a mutable value type that must be boxed, and it does not have to cast its parameter from an to a . ## Examples - The following example uses the method to compare the current string instance with another string. +The following example uses the method to compare the current string instance with another string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringCompareTo/CPP/stringcompareto.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/stringcompareto.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/stringcompareto.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringCompareTo/VB/stringcompareto.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringCompareTo/CPP/stringcompareto.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/stringcompareto.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/stringcompareto.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringCompareTo/VB/stringcompareto.vb" id="Snippet1"::: - The following example demonstrates generic and non-generic versions of the CompareTo method for several value and reference types. +The following example demonstrates generic and non-generic versions of the CompareTo method for several value and reference types. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/T.CompareTo/CPP/cat.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Boolean/CompareTo/cat.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Boolean/CompareTo/cat.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/T.CompareTo/VB/cat.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/T.CompareTo/CPP/cat.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/Boolean/CompareTo/cat.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Boolean/CompareTo/cat.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/T.CompareTo/VB/cat.vb" id="Snippet1"::: ]]> Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a comparison of "animal" with "ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. - :::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/compareto2.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/compareto2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.compareto/vb/compareto2.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/compareto2.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/compareto2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.compareto/vb/compareto2.vb" id="Snippet2"::: - To recognize ignorable characters in a string comparison, call the method. +To recognize ignorable characters in a string comparison, call the method. @@ -3044,24 +2823,24 @@ The following example demonstrates how you can create an instance of the method. +The method concatenates each object in `values`; it does not add any delimiters. To specify a delimiter between each member of `values`, call the method. - An string is used in place of any null element in `values`. +An string is used in place of any null element in `values`. - If `values` is an empty `IEnumerable(Of String)`, the method returns . If `values` is `null`, the method throws an exception. +If `values` is an empty `IEnumerable(Of String)`, the method returns . If `values` is `null`, the method throws an exception. - is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection that is returned by the method is passed to the method to display the result as a single string. + is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection that is returned by the method is passed to the method to display the result as a single string. - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat2.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat2.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat2.vb" id="Snippet3"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat2.cs" interactive="try-dotnet" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat2.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat2.vb" id="Snippet3"::: ## Examples - The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. +The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat1.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat1.cs" interactive="try-dotnet" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat1.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat1.vb" id="Snippet2"::: ]]> @@ -3125,15 +2904,15 @@ The following example demonstrates how you can create an instance of the method represents `arg0` as a string by calling its parameterless `ToString` method. +The method represents `arg0` as a string by calling its parameterless `ToString` method. ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: ]]> @@ -3201,16 +2980,16 @@ The following example demonstrates how you can create an instance of the is used in place of any null object in the array. + is used in place of any null object in the array. ## Examples - The following example demonstrates the use of the method with an array. +The following example demonstrates the use of the method with an array. - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat1/VB/stringconcat1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat1/VB/stringconcat1.vb" id="Snippet1"::: ]]> @@ -3290,17 +3069,17 @@ The following example demonstrates how you can create an instance of the string is used in place of any null object in the array. +An string is used in place of any null object in the array. ## Examples - The following example demonstrates the use of the method with a array. +The following example demonstrates the use of the method with a array. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringconcat3/CPP/stringconcat3.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat3.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat3.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat3/VB/stringconcat3.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringconcat3/CPP/stringconcat3.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat3.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat3.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat3/VB/stringconcat3.vb" id="Snippet1"::: ]]> @@ -3367,19 +3146,19 @@ The following example demonstrates how you can create an instance of the is used in place of any null argument. + is used in place of any null argument. - If either of the arguments is an array reference, the method concatenates a string representing that array, instead of its members (for example, "System.String[]"). +If either of the arguments is an array reference, the method concatenates a string representing that array, instead of its members (for example, "System.String[]"). ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: ]]> @@ -3492,17 +3271,17 @@ The following example demonstrates how you can create an instance of the string is used in place of any null argument. +An string is used in place of any null argument. ## Examples - The following example concatenates a person's first, middle, and last name. +The following example concatenates a person's first, middle, and last name. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringconcat4/CPP/stringconcat4.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat4.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat4.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat4/VB/stringconcat4.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringconcat4/CPP/stringconcat4.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat4.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat4/VB/stringconcat4.vb" id="Snippet1"::: ]]> @@ -3568,17 +3347,17 @@ The following example demonstrates how you can create an instance of the is used in place of any null argument. + is used in place of any null argument. ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: ]]> @@ -3695,15 +3474,15 @@ The following example demonstrates how you can create an instance of the method to concatenate three strings and displays the result. +The following example uses the method to concatenate three strings and displays the result. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.concat/cpp/Concat6.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/Concat6.cs" interactive="try-dotnet" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/Concat6.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/Concat6.vb" id="Snippet6"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.concat/cpp/Concat6.cpp" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/Concat6.cs" interactive="try-dotnet" id="Snippet6"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/Concat6.fs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/Concat6.vb" id="Snippet6"::: ]]> @@ -3766,19 +3545,19 @@ The following example demonstrates how you can create an instance of the [!NOTE] > This API is not CLS-compliant. The CLS-compliant alternative is . The C# and Visual Basic compilers automatically resolve a call to this method as a call to . - The method concatenates each object in the parameter list by calling its parameterless `ToString` method; it does not add any delimiters. +The method concatenates each object in the parameter list by calling its parameterless `ToString` method; it does not add any delimiters. - is used in place of any null argument. + is used in place of any null argument. > [!NOTE] > The last parameter of the method is an optional comma-delimited list of one or more additional objects to concatenate. ## Examples - The following example illustrates the use of the method to concatenate a list of variable parameters. In this case, the method is called with nine parameters. +The following example illustrates the use of the method to concatenate a list of variable parameters. In this case, the method is called with nine parameters. - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat4.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat4.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat4.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat4.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat4.vb" id="Snippet1"::: ]]> @@ -3900,14 +3679,14 @@ The following example demonstrates how you can create an instance of the method to reassemble the scrambled words. +The following example defines an array of four-letter words and stores their individual letters to a string array in order to scramble them. It then calls the method to reassemble the scrambled words. - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat4.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat4.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat4.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat4.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat4.vb" id="Snippet1"::: ]]> @@ -3977,18 +3756,18 @@ The following example demonstrates how you can create an instance of the string is used in place of any null argument. +An string is used in place of any null argument. - is a convenience method that lets you concatenate each element in an collection without first converting the elements to strings. It is particularly useful with Language-Integrated Query (LINQ) query expressions, as the example illustrates. The string representation of each object in the collection is derived by calling that object's `ToString` method. + is a convenience method that lets you concatenate each element in an collection without first converting the elements to strings. It is particularly useful with Language-Integrated Query (LINQ) query expressions, as the example illustrates. The string representation of each object in the collection is derived by calling that object's `ToString` method. ## Examples - The following example defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object to contain a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method and displayed to the console. +The following example defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object to contain a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method and displayed to the console. - :::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat3.cs" interactive="try-dotnet" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat3.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat3.vb" id="Snippet4"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat3.cs" interactive="try-dotnet" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat3.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat3.vb" id="Snippet4"::: ]]> @@ -4035,7 +3814,7 @@ The following example demonstrates how you can create an instance of the @@ -4094,7 +3873,7 @@ The following example demonstrates how you can create an instance of the extension method that includes a parameter and indicates whether a string contains a substring when using the specified form of string comparison. - :::code language="csharp" source="~/snippets/csharp/System/String/Contains/ContainsExt1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/ContainsExt1.fs" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Contains/ContainsExt1.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/ContainsExt1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Contains/ContainsExt1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/ContainsExt1.fs" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Contains/ContainsExt1.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/ContainsExt1.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb" id="Snippet2"::: - If you are interested in the position of the substring `value` in the current instance, you can call the method to get the starting position of its first occurrence, or you can call the method to get the starting position of its last occurrence. The example includes a call to the method if a substring is found in a string instance. +If you are interested in the position of the substring `value` in the current instance, you can call the method to get the starting position of its first occurrence, or you can call the method to get the starting position of its last occurrence. The example includes a call to the method if a substring is found in a string instance. ## Examples - The following example determines whether the string "fox" is a substring of a familiar quotation. If "fox" is found in the string, it also displays its starting position. +The following example determines whether the string "fox" is a substring of a familiar quotation. If "fox" is found in the string, it also displays its starting position. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.contains/CPP/cont.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Contains/cont.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/cont.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.contains/VB/cont.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.contains/CPP/cont.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Contains/cont.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/cont.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.contains/VB/cont.vb" id="Snippet1"::: ]]> @@ -4396,17 +4175,17 @@ Depending on Why you want to call the `Copy` method, there are a number of alter . +This method copies `count` characters from the `sourceIndex` position of this instance to the `destinationIndex` position of `destination` character array. This method does not resize the `destination` character array; it must have a sufficient number of elements to accommodate the copied characters or the method throws an . - `sourceIndex` and `destinationIndex` are zero-based. +`sourceIndex` and `destinationIndex` are zero-based. ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringcopyto/CPP/stringcopyto.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/CopyTo/stringcopyto.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/CopyTo/stringcopyto.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringcopyto/VB/stringcopyto.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringcopyto/CPP/stringcopyto.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CopyTo/stringcopyto.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CopyTo/stringcopyto.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringcopyto/VB/stringcopyto.vb" id="Snippet1"::: ]]> @@ -4415,21 +4194,21 @@ Depending on Why you want to call the `Copy` method, there are a number of alter , , or is negative - -or- +-or- - does not identify a position in the current instance. + does not identify a position in the current instance. - -or- +-or- - does not identify a valid index in the array. + does not identify a valid index in the array. - -or- +-or- - is greater than the length of the substring from to the end of this instance + is greater than the length of the substring from to the end of this instance - -or- +-or- - is greater than the length of the subarray from to the end of the array. + is greater than the length of the subarray from to the end of the array. @@ -4642,9 +4421,9 @@ The initial content of the destination span passed to `action` is undefined. The , use the method. +In application code, this field is most commonly used in assignments to initialize a string variable to an empty string. To test whether the value of a string is either `null` or , use the method. ]]> @@ -4757,23 +4536,23 @@ This method performs an ordinal (case-sensitive and culture-insensitive) compari method to remove HTML end tags from the end of a line. Note that the `StripEndTags` method is called recursively to ensure that multiple HTML end tags at the end of the line are removed. +The following example defines a `StripEndTags` method that uses the method to remove HTML end tags from the end of a line. Note that the `StripEndTags` method is called recursively to ensure that multiple HTML end tags at the end of the line are removed. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringendswith/CPP/stringendswith.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/stringendswith.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/stringendswith.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringendswith/VB/stringendswith.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringendswith/CPP/stringendswith.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/stringendswith.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/stringendswith.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringendswith/VB/stringendswith.vb" id="Snippet1"::: ]]> @@ -4846,15 +4625,15 @@ This method performs an ordinal (case-sensitive and culture-insensitive) compari method compares the `value` parameter to the substring at the end of this string and returns a value that indicates whether they are equal. To be equal, `value` must be a reference to this same string, must be the empty string (""), or must match the end of this string. The type of comparison performed by the method depends on the value of the `comparisonType` parameter. +The method compares the `value` parameter to the substring at the end of this string and returns a value that indicates whether they are equal. To be equal, `value` must be a reference to this same string, must be the empty string (""), or must match the end of this string. The type of comparison performed by the method depends on the value of the `comparisonType` parameter. ## Examples - The following example determines whether a string ends with a particular substring. The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed. +The following example determines whether a string ends with a particular substring. The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.EndsWithCmp/cpp/ewcmp.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/ewcmp.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/ewcmp.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.EndsWithCmp/vb/ewcmp.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.EndsWithCmp/cpp/ewcmp.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/ewcmp.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/ewcmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.EndsWithCmp/vb/ewcmp.vb" id="Snippet1"::: ]]> @@ -4922,16 +4701,16 @@ This method performs an ordinal (case-sensitive and culture-insensitive) compari method is called several times using case sensitivity, case insensitivity, and different cultures that influence the results of the search. +The following example determines whether a string occurs at the end of another string. The method is called several times using case sensitivity, case insensitivity, and different cultures that influence the results of the search. - :::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/ewci.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/ewci.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.EndsWithCI/vb/ewci.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/ewci.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/ewci.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.EndsWithCI/vb/ewci.vb" id="Snippet1"::: ]]> @@ -5061,15 +4840,15 @@ Invalid sequences are represented in the enumeration by method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.equals/CPP/equals.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.equals/VB/equals.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.equals/CPP/equals.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.equals/VB/equals.vb" id="Snippet1"::: ]]> @@ -5153,14 +4932,14 @@ Invalid sequences are represented in the enumeration by method. It compares the title-cased word "File" with an equivalent word, its lowercase equivalent, its uppercase equivalent, and a word that contains LATIN SMALL LETTER DOTLESS I (U+0131) instead of LATIN SMALL LETTER I (U+0069). Because the method performs an ordinal comparison, only the comparison with an identical word returns `true`. +The following example demonstrates the method. It compares the title-cased word "File" with an equivalent word, its lowercase equivalent, its uppercase equivalent, and a word that contains LATIN SMALL LETTER DOTLESS I (U+0131) instead of LATIN SMALL LETTER I (U+0069). Because the method performs an ordinal comparison, only the comparison with an identical word returns `true`. - :::code language="csharp" source="~/snippets/csharp/System/String/Equals/equalsex1.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equalsex1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/equalsex1.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equalsex1.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equalsex1.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/equalsex1.vb" id="Snippet2"::: ]]> @@ -5229,15 +5008,15 @@ Invalid sequences are represented in the enumeration by method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.equals/CPP/equals.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.equals/VB/equals.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.equals/CPP/equals.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.equals/VB/equals.vb" id="Snippet1"::: ]]> @@ -5312,14 +5091,14 @@ Invalid sequences are represented in the enumeration by method to compare them by using each possible enumeration value. +The following example creates a string array that consists of an uppercase "I", a lowercase "i", and a dotless "ı". It then calls the method to compare them by using each possible enumeration value. - :::code language="csharp" source="~/snippets/csharp/System/String/Equals/eqcmp.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/eqcmp.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/eqcmp.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Equals/eqcmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/eqcmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/eqcmp.vb" id="Snippet1"::: ]]> @@ -5391,14 +5170,14 @@ Invalid sequences are represented in the enumeration by enumeration. The comparisons use the conventions of the English (United States), Thai (Thailand) and Turkish (Turkey) cultures. Note that the strings "a" and "a-" are considered equivalent in the "th-TH" culture but not in the others, while "i" and "İ" are considered equivalent in the "tr-TR" culture when case is ignored but not in the other cultures. +The following example compares three sets of strings by using each member of the enumeration. The comparisons use the conventions of the English (United States), Thai (Thailand) and Turkish (Turkey) cultures. Note that the strings "a" and "a-" are considered equivalent in the "th-TH" culture but not in the others, while "i" and "İ" are considered equivalent in the "tr-TR" culture when case is ignored but not in the other cultures. - :::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals_ex3.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals_ex3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/equals_ex3.vb" id="Snippet3"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals_ex3.cs" interactive="try-dotnet" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals_ex3.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/equals_ex3.vb" id="Snippet3"::: ]]> @@ -5416,376 +5195,8 @@ Invalid sequences are represented in the enumeration by Converts the value of objects to strings based on the formats specified and inserts them into another string. - If you are new to the `String.Format` method, see the [Get started with the String.Format method](#Starting) section for a quick overview. - - See the [Remarks](#remarks-top) section for general documentation for the `String.Format` method. - - -## Remarks - -[!INCLUDE[interpolated-strings](~/includes/interpolated-strings.md)] - - In this section: - - [Get started with the String.Format method](#Starting)\ - [Which method do I call?](#FTaskList)\ - [The Format method in brief](#Format_Brief)\ - [The Format item](#FormatItem)\ - [How arguments are formatted](#HowFormatted)\ - [Format items that have the same index](#SameIndex)\ - [Formatting and culture](#Format_Culture)\ - [Custom formatting operations](#Format_Custom)\ - [String.Format Q & A](#QA) - - -## Get started with the String.Format method - Use if you need to insert the value of an object, variable, or expression into another string. For example, you can insert the value of a value into a string to display it to the user as a single string: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/starting2.cpp" id="Snippet35"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/starting2.cs" interactive="try-dotnet-method" id="Snippet35"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/starting2.fs" id="Snippet35"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting2.vb" id="Snippet35"::: - - And you can control that value's formatting: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/starting2.cpp" id="Snippet36"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/starting2.cs" id="Snippet36"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/starting2.fs" id="Snippet36"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting2.vb" id="Snippet36"::: - - Besides formatting, you can also control alignment and spacing. - - ### Insert a string - - starts with a format string, followed by one or more objects or expressions that will be converted to strings and inserted at a specified place in the format string. For example: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/starting1.cpp" id="Snippet30"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/starting1.cs" interactive="try-dotnet-method" id="Snippet30"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/starting1.fs" id="Snippet30"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting1.vb" id="Snippet30"::: - - The `{0}` in the format string is a format item. `0` is the index of the object whose string value will be inserted at that position. (Indexes start at 0.) If the object to be inserted is not a string, its `ToString` method is called to convert it to one before inserting it in the result string. - - Here's another example that uses two format items and two objects in the object list: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/starting1.cpp" id="Snippet31"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/starting1.cs" id="Snippet31"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/starting1.fs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting1.vb" id="Snippet31"::: - - You can have as many format items and as many objects in the object list as you want, as long as the index of every format item has a matching object in the object list. You also don't have to worry about which overload you call; the compiler will select the appropriate one for you. - - ### Control formatting - You can follow the index in a format item with a format string to control how an object is formatted. For example, `{0:d}` applies the "d" format string to the first object in the object list. Here is an example with a single object and two format items: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/starting1.cpp" id="Snippet32"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/starting1.cs" id="Snippet32"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/starting1.fs" id="Snippet32"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting1.vb" id="Snippet32"::: - - A number of types support format strings, including all numeric types (both [standard](/dotnet/standard/base-types/standard-numeric-format-strings) and [custom](/dotnet/standard/base-types/custom-numeric-format-strings) format strings), all dates and times (both [standard](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [custom](/dotnet/standard/base-types/custom-date-and-time-format-strings) format strings) and time intervals (both [standard](/dotnet/standard/base-types/standard-timespan-format-strings) and [custom](/dotnet/standard/base-types/custom-timespan-format-strings) format strings), all enumeration types [enumeration types](/dotnet/standard/base-types/enumeration-format-strings), and [GUIDs](xref:System.Guid.ToString(System.String)). You can also add support for format strings to your own types. - - ### Control spacing - You can define the width of the string that is inserted into the result string by using syntax such as `{0,12}`, which inserts a 12-character string. In this case, the string representation of the first object is right-aligned in the 12-character field. (If the string representation of the first object is more than 12 characters in length, though, the preferred field width is ignored, and the entire string is inserted into the result string.) - - The following example defines a 6-character field to hold the string "Year" and some year strings, as well as an 15-character field to hold the string "Population" and some population data. Note that the characters are right-aligned in the field. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/starting1.cpp" id="Snippet33"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/starting3.cs" id="Snippet33"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/starting3.fs" id="Snippet33"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting1.vb" id="Snippet33"::: - - ### Control alignment - By default, strings are right-aligned within their field if you specify a field width. To left-align strings in a field, you preface the field width with a negative sign, such as `{0,-12}` to define a 12-character left-aligned field. - - The following example is similar to the previous one, except that it left-aligns both labels and data. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/starting1.cpp" id="Snippet34"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/starting1.cs" id="Snippet34"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/starting1.fs" id="Snippet34"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/starting1.vb" id="Snippet34"::: - - makes use of the composite formatting feature. For more information, see [Composite Formatting](/dotnet/standard/base-types/composite-formatting). - - -## Which method do I call? - -|To|Call| -|--------|----------| -|Format one or more objects by using the conventions of the current culture.|Except for the overloads that include a `provider` parameter, the remaining overloads include a parameter followed by one or more object parameters. Because of this, you don't have to determine which overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that don't have a `provider` parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the method.| -|Format one or more objects by using the conventions of a specific culture.|Each overload that begins with a `provider` parameter is followed by a parameter and one or more object parameters. Because of this, you don't have to determine which specific overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that have a `provider` parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the method.| -|Perform a custom formatting operation either with an implementation or an implementation.|Any of the four overloads with a `provider` parameter. The compiler selects the appropriate overload from among the overloads that have a `provider` parameter, based on your argument list.| - - -## The Format method in brief - - Each overload of the method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to include zero-based indexed placeholders, called *format items*, in a composite format string. At run time, each format item is replaced with the string representation of the corresponding argument in a parameter list. If the value of the argument is `null`, the format item is replaced with . For example, the following call to the method includes a format string with three format items, {0}, {1}, and {2}, and an argument list with three items. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/formatoverload1.cpp" id="Snippet8"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/formatoverload1.cs" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/formatoverload1.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatoverload1.vb" id="Snippet8"::: - - -## The format item - A format item has this syntax: - -``` -{index[,alignment][:formatString]} -``` - - Brackets denote optional elements. The opening and closing braces are required. (To include a literal opening or closing brace in the format string, see the [Escaping Braces](/dotnet/standard/base-types/composite-formatting#escaping-braces) section in the [Composite Formatting](/dotnet/standard/base-types/composite-formatting) article.) - - For example, a format item to format a currency value might appear like this: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/formatsyntax1.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/formatsyntax1.cs" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/formatsyntax1.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatsyntax1.vb" id="Snippet12"::: - - A format item has the following elements: - - *index*\ - The zero-based index of the argument whose string representation is to be included at this position in the string. If this argument is `null`, an empty string will be included at this position in the string. - - *alignment*\ - Optional. A signed integer that indicates the total length of the field into which the argument is inserted and whether it is right-aligned (a positive integer) or left-aligned (a negative integer). If you omit *alignment*, the string representation of the corresponding argument is inserted in a field with no leading or trailing spaces. - - If the value of *alignment* is less than the length of the argument to be inserted, *alignment* is ignored and the length of the string representation of the argument is used as the field width. - - *formatString*\ - Optional. A string that specifies the format of the corresponding argument's result string. If you omit *formatString*, the corresponding argument's parameterless `ToString` method is called to produce its string representation. If you specify *formatString*, the argument referenced by the format item must implement the interface. Types that support format strings include: - -- All integral and floating-point types. (See [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings).) - -- and . (See [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings).) - -- All enumeration types. (See [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings).) - -- values. (See [Standard TimeSpan Format Strings](/dotnet/standard/base-types/standard-timespan-format-strings) and [Custom TimeSpan Format Strings](/dotnet/standard/base-types/custom-timespan-format-strings).) - -- GUIDs. (See the method.) - - However, note that any custom type can implement or extend an existing type's implementation. - - The following example uses the `alignment` and `formatString` arguments to produce formatted output. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/formatoverload2.cpp" id="Snippet9"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/formatoverload2.cs" interactive="try-dotnet-method" id="Snippet9"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/formatoverload2.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatoverload2.vb" id="Snippet9"::: - - -## How arguments are formatted - Format items are processed sequentially from the beginning of the string. Each format item has an index that corresponds to an object in the method's argument list. The method retrieves the argument and derives its string representation as follows: - -- If the argument is `null`, the method inserts into the result string. You don't have to be concerned with handling a for null arguments. - -- If you call the overload and the `provider` object's implementation returns a non-null implementation, the argument is passed to its method. If the format item includes a *formatString* argument, it is passed as the first argument to the method. If the implementation is available and produces a non-null string, that string is returned as the string representation of the argument; otherwise, the next step executes. - -- If the argument implements the interface, its implementation is called. - -- The argument's parameterless `ToString` method, which either overrides or inherits from a base class implementation, is called. - - For an example that intercepts calls to the method and allows you to see what information the method passes to a formatting method for each format item in a composite format string, see [Example: An intercept provider and Roman numeral formatter](#Format7_Example). - - For more information, see the [Processing Order](/dotnet/standard/base-types/composite-formatting##processing-order) section in the [Composite Formatting](/dotnet/standard/base-types/composite-formatting) article. - - -## Format items that have the same index - The method throws a exception if the index of an index item is greater than or equal to the number of arguments in the argument list. However, `format` can include more format items than there are arguments, as long as multiple format items have the same index. In the call to the method in following example, the argument list has a single argument, but the format string includes two format items: one displays the decimal value of a number, and the other displays its hexadecimal value. - - :::code language="csharp" source="~/snippets/csharp/System/String/Format/Example1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Format/Example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format2/vb/Example1.vb" id="Snippet1"::: - - -## Format and culture - Generally, objects in the argument list are converted to their string representations by using the conventions of the current culture, which is returned by the property. You can control this behavior by calling one of the overloads of that includes a `provider` parameter. The `provider` parameter is an implementation that supplies custom and culture-specific formatting information that is used to moderate the formatting process. - - The interface has a single member, , which is responsible for returning the object that provides formatting information. .NET has three implementations that provide culture-specific formatting: - -- . Its method returns a culture-specific object for formatting numeric values and a culture-specific object for formatting date and time values. - -- , which is used for culture-specific formatting of date and time values. Its method returns itself. - -- , which is used for culture-specific formatting of numeric values. Its property returns itself. - - -## Custom formatting operations - You can also call the any of the overloads of the method that have a `provider` parameter of type to perform custom formatting operations. For example, you could format an integer as an identification number or as a telephone number. To perform custom formatting, your `provider` argument must implement both the and interfaces. When the method is passed an implementation as the `provider` argument, the method calls its implementation and requests an object of type . It then calls the returned object's method to format each format item in the composite string passed to it. - - For more information about providing custom formatting solutions, see [How to: Define and Use Custom Numeric Format Providers](/dotnet/standard/base-types/how-to-define-and-use-custom-numeric-format-providers) and . For an example that converts integers to formatted custom numbers, see [Example: A custom formatting operation](#Format6_Example). For an example that converts unsigned bytes to Roman numerals, see [Example: An intercept provider and Roman numeral formatter](#Format7_Example). - - -### Example: A custom formatting operation - This example defines a format provider that formats an integer value as a customer account number in the form x-xxxxx-xx. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/formatexample2.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/FormatExample2.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/FormatExample2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/FormatExample2.vb" id="Snippet2"::: - - -### Example: An intercept provider and Roman numeral formatter - This example defines a custom format provider that implements the and interfaces to do two things: - -- It displays the parameters passed to its implementation. This enables us to see what parameters the method is passing to the custom formatting implementation for each object that it tries to format. This can be useful when you're debugging your application. - -- If the object to be formatted is an unsigned byte value that is to be formatted by using the "R" standard format string, the custom formatter formats the numeric value as a Roman numeral. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/interceptor2.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/interceptor2.cs" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/interceptor2.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/interceptor2.vb" id="Snippet11"::: - - -## String.Format Q & A - -### Why do you recommend string interpolation over calls to the `String.Format` method? - -String interpolation is: - -- More flexible. It can be used in any string without requiring a call to a method that supports composite formatting. Otherwise, you have to call the method or another method that supports composite formatting, such as or . - -- More readable. Because the expression to insert into a string appears in the interpolated expression rather than in a argument list, interpolated strings are far easier to code and to read. Because of their greater readability, interpolated strings can replace not only calls to composite format methods, but they can also be used in string concatenation operations to produce more concise, clearer code. - -A comparison of the following two code examples illustrates the superiority of interpolated strings over string concatenation and calls to composite formatting methods. The use of multiple string concatenation operations in the following example produces verbose and hard-to-read code. - -:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa-interpolated1.cs" id="SnippetQAInterpolated"::: -:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa-interpolated1.fs" id="SnippetQAInterpolated"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa-interpolated1.vb"::: - -In contrast, the use of interpolated strings in the following example produce much clearer, more concise code than the string concatenation statement and the call to the method in the previous example. - -:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa-interpolated2.cs" id="SnippetQAInterpolated2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa-interpolated2.fs" id="SnippetQAInterpolated2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa-interpolated2.vb"::: - -### Where can I find a list of the predefined format strings that can be used with format items? - -- For all integral and floating-point types, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). - -- For date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). - -- For enumeration values, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - -- For values, see [Standard TimeSpan Format Strings](/dotnet/standard/base-types/standard-timespan-format-strings) and [Custom TimeSpan Format Strings](/dotnet/standard/base-types/custom-timespan-format-strings). - -- For values, see the Remarks section of the reference page. - -### How do I control the alignment of the result strings that replace format items? - The general syntax of a format item is: - -``` -{index[,alignment][: formatString]} -``` - - where *alignment* is a signed integer that defines the field width. If this value is negative, text in the field is left-aligned. If it is positive, text is right-aligned. - -### How do I control the number of digits after the decimal separator? - All [standard numeric format strings](/dotnet/standard/base-types/standard-numeric-format-strings) except "D" (which is used with integers only), "G", "R", and "X" allow a precision specifier that defines the number of decimal digits in the result string. The following example uses standard numeric format strings to control the number of decimal digits in the result string. - - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa26.cs" id="Snippet26"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa26.fs" id="Snippet26"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa26.vb" id="Snippet26"::: - - If you're using a [custom numeric format string](/dotnet/standard/base-types/custom-numeric-format-strings), use the "0" format specifier to control the number of decimal digits in the result string, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa27.cs" interactive="try-dotnet-method" id="Snippet27"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa27.fs" id="Snippet27"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa27.vb" id="Snippet27"::: - -### How do I control the number of integral digits? - By default, formatting operations only display non-zero integral digits. If you are formatting integers, you can use a precision specifier with the "D" and "X" standard format strings to control the number of digits. - - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa29.cs" interactive="try-dotnet-method" id="Snippet29"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa29.fs" id="Snippet29"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa29.vb" id="Snippet29"::: - - You can pad an integer or floating-point number with leading zeros to produce a result string with a specified number of integral digits by using the "0" [custom numeric format specifier](/dotnet/standard/base-types/custom-numeric-format-strings), as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa28.cs" interactive="try-dotnet-method" id="Snippet28"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa28.fs" id="Snippet28"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa28.vb" id="Snippet28"::: - -### How many items can I include in the format list? - There is no practical limit. The second parameter of the method is tagged with the attribute, which allows you to include either a delimited list or an object array as your format list. - - -### How do I include literal braces ("{" and "}") in the result string? - For example, how do you prevent the following method call from throwing a exception? - - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa3.cs" id="Snippet23"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa3.fs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa3.vb" id="Snippet23"::: - - A single opening or closing brace is always interpreted as the beginning or end of a format item. To be interpreted literally, it must be escaped. You escape a brace by adding another brace ("{{" and "}}" instead of "{" and "}"), as in the following method call: - - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa3.cs" interactive="try-dotnet-method" id="Snippet24"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa3.fs" id="Snippet24"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa3.vb" id="Snippet24"::: - - However, even escaped braces are easily misinterpreted. We recommend that you include braces in the format list and use format items to insert them in the result string, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa3.cs" interactive="try-dotnet-method" id="Snippet25"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa3.fs" id="Snippet25"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa3.vb" id="Snippet25"::: - -### Why does my call to the String.Format method throw a FormatException? - The most common cause of the exception is that the index of a format item doesn't correspond to an object in the format list. Usually this indicates that you've misnumbered the indexes of format items or you've forgotten to include an object in the format list. Attempting to include an unescaped left or right brace character also throws a . Occasionally, the exception is the result of a typo; for example, a typical mistake is to mistype "[" (the left bracket) instead of "{" (the left brace). - -### If the Format(System.IFormatProvider,System.String,System.Object[]) method supports parameter arrays, why does my code throw an exception when I use an array? - For example, the following code throws a exception: - - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa11.cs" id="Snippet21"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa11.fs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa1.vb" id="Snippet21"::: - - This is a problem of compiler overload resolution. Because the compiler cannot convert an array of integers to an object array, it treats the integer array as a single argument, so it calls the method. The exception is thrown because there are four format items but only a single item in the format list. - - Because neither Visual Basic nor C# can convert an integer array to an object array, you have to perform the conversion yourself before calling the method. The following example provides one implementation. - - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa21.cs" interactive="try-dotnet-method" id="Snippet22"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa21.fs" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa2.vb" id="Snippet22"::: - -## Examples - -Numerous examples that call the method are interspersed through the [Remarks](#remarks-top) section of this article. - -You can also download a complete set of `String.Format` examples, which are included a [.NET Core project for C#](https://docs.microsoft.com/samples/dotnet/samples/string-format/). - -The following are some of the examples included in the article: - -### Create a format string - -[Inserting a string](#insert-a-string)\ -[The format item](#the-format-item)\ -[Format items that have the same index](#format-items-that-have-the-same-index) - -### Control formatted output - -[Controlling formatting](#control-formatting)\ -[Controlling spacing](#control-spacing)\ -[Controlling alignment](#control-alignment)\ -[Controlling the number of integral digits](#how-do-i-control-the-number-of-integral-digits)\ -[Controlling the number of digits after the decimal separator](#how-do-i-control-the-number-of-digits-after-the-decimal-separator)\ -[Including literal braces in a result string](#braces) - -### Make format strings culture-sensitive - -[Culture-sensitive formatting](#culture-sensitive-formatting) - -### Customize the formatting operation - -[A custom formatting operation](#example-a-custom-formatting-operation)\ -[An intercept provider and Roman numeral formatter](#example-an-intercept-provider-and-roman-numeral-formatter) - - ]]> - +If you are new to the `String.Format` method, see [Get started with the String.Format method](/dotnet/fundamentals/runtime-libraries/system-string-format#get-started-with-the-stringformat-method) for a quick overview. + For more information about this API, see Supplemental API remarks for String.Format. Formatting Types in .NET Composite Formatting Standard Date and Time Format Strings @@ -5865,16 +5276,16 @@ The following are some of the examples included in the article: This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of an expression to its string representation and to embed that representation in a string. -[!INCLUDE[simple-string-format](~/includes/simple-string-format.md)] +[!INCLUDE[simple-string-format](~/includes/remarks/System/String/simple-string-format.md)] ## Example: Formatting a single argument - The following example uses the method to embed an individual's age in the middle of a string. +The following example uses the method to embed an individual's age in the middle of a string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format7.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format7.cs" interactive="try-dotnet-method" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format7.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format7.vb" id="Snippet7"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format7.cpp" id="Snippet7"::: +:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format7.cs" interactive="try-dotnet-method" id="Snippet7"::: +:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format7.fs" id="Snippet7"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format7.vb" id="Snippet7"::: ]]> @@ -5882,9 +5293,9 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ is . The format item in is invalid. - -or- +-or- - The index of a format item is not zero. +The index of a format item is not zero. Formatting Types in .NET Composite Formatting Standard Date and Time Format Strings @@ -5970,23 +5381,23 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of four or more expressions to their string representations and to embed those representations in a string. Since the `args` parameter is marked with the attribute, you can pass the objects to the method as individual arguments or as an array. -[!INCLUDE[simple-string-format](~/includes/simple-string-format.md)] +[!INCLUDE[simple-string-format](~/includes/remarks/System/String/simple-string-format.md)] ## Example: Format more than three arguments - This example creates a string that contains data on the high and low temperature on a particular date. The composite format string has five format items in the C# example and six in the Visual Basic example. Two of the format items define the width of their corresponding value's string representation, and the first format item also includes a standard date and time format string. +This example creates a string that contains data on the high and low temperature on a particular date. The composite format string has five format items in the C# example and six in the Visual Basic example. Two of the format items define the width of their corresponding value's string representation, and the first format item also includes a standard date and time format string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format5.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format5.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format5.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format5.vb" id="Snippet5"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format5.cpp" id="Snippet5"::: +:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format5.cs" id="Snippet5"::: +:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format5.fs" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format5.vb" id="Snippet5"::: - You can also pass the objects to be formatted as an array rather than as an argument list. +You can also pass the objects to be formatted as an array rather than as an argument list. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format_paramarray1.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format_paramarray1.cs" interactive="try-dotnet" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format_paramarray1.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format_paramarray1.vb" id="Snippet10"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format_paramarray1.cpp" id="Snippet10"::: +:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format_paramarray1.cs" interactive="try-dotnet" id="Snippet10"::: +:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format_paramarray1.fs" id="Snippet10"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format_paramarray1.vb" id="Snippet10"::: ]]> @@ -5995,9 +5406,9 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ is invalid. - -or- +-or- - The index of a format item is less than zero, or greater than or equal to the length of the array. +The index of a format item is less than zero, or greater than or equal to the length of the array. Formatting Types in .NET Composite Formatting Standard Date and Time Format Strings @@ -6084,7 +5495,7 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of an expression to its string representation and to embed that representation in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts `arg0` to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. -[!INCLUDE[provider-string-format](~/includes/provider-string-format.md)] +[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] ]]> @@ -6093,9 +5504,9 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ is invalid. - -or- +-or- - The index of a format item is not zero. +The index of a format item is not zero. @@ -6187,17 +5598,17 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert four or more expressions to their string representations and to embed those representations in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts each argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. -[!INCLUDE[provider-string-format](~/includes/provider-string-format.md)] +[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] ### Example: Culture-sensitive formatting - This example uses the method to display the string representation of some date and time values and numeric values by using several different cultures. +This example uses the method to display the string representation of some date and time values and numeric values by using several different cultures. - :::code language="csharp" source="~/snippets/csharp/System/String/Format/Example2.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Format/Example2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format2/vb/Example2.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Format/Example2.cs" interactive="try-dotnet-method" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Format/Example2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format2/vb/Example2.vb" id="Snippet2"::: ]]> @@ -6206,9 +5617,9 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ is invalid. - -or- +-or- - The index of a format item is less than zero, or greater than or equal to the length of the array. +The index of a format item is less than zero, or greater than or equal to the length of the array. @@ -6409,16 +5820,16 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of two expressions to their string representations and to embed those representations in a string. -[!INCLUDE[simple-string-format](~/includes/simple-string-format.md)] +[!INCLUDE[simple-string-format](~/includes/remarks/System/String/simple-string-format.md)] ## Example: Format two arguments - This example uses the method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only two objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. +This example uses the method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only two objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/formatexample4.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/formatexample4.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/formatexample4.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatexample4.vb" id="Snippet6"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/formatexample4.cpp" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/formatexample4.cs" id="Snippet6"::: +:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/formatexample4.fs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatexample4.vb" id="Snippet6"::: ]]> @@ -6427,9 +5838,9 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ is invalid. - -or- +-or- - The index of a format item is not zero or one. +The index of a format item is not zero or one. Formatting Types in .NET Composite Formatting Standard Date and Time Format Strings @@ -6514,7 +5925,7 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert two expressions to their string representations and to embed those representations in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts each argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. -[!INCLUDE[provider-string-format](~/includes/provider-string-format.md)] +[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] ]]> @@ -6523,9 +5934,9 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ is invalid. - -or- +-or- - The index of a format item is not zero or one. +The index of a format item is not zero or one. @@ -6603,16 +6014,16 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of three expressions to their string representations and to embed those representations in a string. -[!INCLUDE[simple-string-format](~/includes/simple-string-format.md)] +[!INCLUDE[simple-string-format](~/includes/remarks/System/String/simple-string-format.md)] ## Example: Format three arguments - This example uses the method to create a string that illustrates the result of a Boolean `And` operation with two integer values. Note that the format string includes six format items, but the method has only three items in its parameter list, because each item is formatted in two different ways. +This example uses the method to create a string that illustrates the result of a Boolean `And` operation with two integer values. Note that the format string includes six format items, but the method has only three items in its parameter list, because each item is formatted in two different ways. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format4.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format4.cs" interactive="try-dotnet-method" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format4.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format4.vb" id="Snippet4"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format4.cpp" id="Snippet4"::: +:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format4.cs" interactive="try-dotnet-method" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format4.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format4.vb" id="Snippet4"::: ]]> @@ -6621,9 +6032,9 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ is invalid. - -or- +-or- - The index of a format item is less than zero, or greater than two. +The index of a format item is less than zero, or greater than two. Formatting Types in .NET Composite Formatting @@ -6703,7 +6114,7 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert three expressions to their string representations and to embed those representations in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts each argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. -[!INCLUDE[provider-string-format](~/includes/provider-string-format.md)] +[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] ]]> @@ -6712,9 +6123,9 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ is invalid. - -or- +-or- - The index of a format item is less than zero, or greater than two. +The index of a format item is less than zero, or greater than two. @@ -6963,15 +6374,15 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ > [!TIP] > Rather than calling the method to retrieve a object that you then use to enumerate a string, you should instead use your language's iteration construct (in C#, in F#, in C++/CLR, and in Visual Basic). [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) in C#, [for..in](/dotnet/fsharp/language-reference/loops-for-in-expression) in F#, [for each](/cpp/dotnet/for-each-in) in C++/CLR, and [For Each](/dotnet/visual-basic/language-reference/statements/for-each-next-statement) in Visual Basic). - This method enables you to iterate the individual characters in a string. For example, the Visual Basic `For Each`, the F# `for..in` expression, and C# `foreach` statements invoke this method to return a object that can provide read-only access to the characters in this string instance. +This method enables you to iterate the individual characters in a string. For example, the Visual Basic `For Each`, the F# `for..in` expression, and C# `foreach` statements invoke this method to return a object that can provide read-only access to the characters in this string instance. ## Examples - The following example iterates the characters in several strings and displays information about their individual characters. It uses the language iteration construct rather than a call to the method. +The following example iterates the characters in several strings and displays information about their individual characters. It uses the language iteration construct rather than a call to the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.GetEnumerator/CPP/getenumerator.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/GetEnumerator/getenumerator.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/GetEnumerator/getenumerator.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetEnumerator/VB/getenumerator.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.GetEnumerator/CPP/getenumerator.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/GetEnumerator/getenumerator.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/GetEnumerator/getenumerator.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetEnumerator/VB/getenumerator.vb" id="Snippet1"::: ]]> @@ -7035,7 +6446,7 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ is dependent on its implementation, which might change from one version of the common language runtime to another. A reason why this might happen is to improve the performance of . +The behavior of is dependent on its implementation, which might change from one version of the common language runtime to another. A reason why this might happen is to improve the performance of . > [!IMPORTANT] > If two string objects are equal, the method returns identical values. However, there is not a unique hash code value for each unique string value. Different strings can return the same hash code. @@ -7048,20 +6459,20 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ > > For more information about hash codes, see . - In .NET Framework desktop apps, you can use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element) to generate unique hash codes on a per-application domain basis. This can reduce the number of collisions and improve the overall performance of insertions and lookups that use hash tables. The following example shows how to use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element). It defines a `DisplayString` class that includes a private string constant, `s`, whose value is "This is a string." It also includes a `ShowStringHashCode` method that displays the string value and its hash code along with the name of the application domain in which the method is executing. +In .NET Framework desktop apps, you can use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element) to generate unique hash codes on a per-application domain basis. This can reduce the number of collisions and improve the overall performance of insertions and lookups that use hash tables. The following example shows how to use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element). It defines a `DisplayString` class that includes a private string constant, `s`, whose value is "This is a string." It also includes a `ShowStringHashCode` method that displays the string value and its hash code along with the name of the application domain in which the method is executing. - :::code language="csharp" source="~/snippets/csharp/System/String/GetHashCode/perdomain.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/GetHashCode/perdomain.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetHashCode/VB/perdomain.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/GetHashCode/perdomain.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/GetHashCode/perdomain.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetHashCode/VB/perdomain.vb" id="Snippet2"::: - When you run the example without supplying a configuration file, it displays output similar to the following. Note that the hash codes for the string are identical in the two application domains. +When you run the example without supplying a configuration file, it displays output similar to the following. Note that the hash codes for the string are identical in the two application domains. ``` String 'This is a string.' in domain 'PerDomain.exe': 941BCEAC String 'This is a string.' in domain 'NewDomain': 941BCEAC ``` - However, if you add the following configuration file to the example's directory and then run the example, the hash codes for the same string will differ by application domain. +However, if you add the following configuration file to the example's directory and then run the example, the hash codes for the same string will differ by application domain. ```xml @@ -7072,7 +6483,7 @@ String 'This is a string.' in domain 'NewDomain': 941BCEAC ``` - When the configuration file is present, the example displays the following output: +When the configuration file is present, the example displays the following output: ``` String 'This is a string.' in domain 'PerDomain.exe': 5435776D @@ -7082,15 +6493,15 @@ String 'This is a string.' in domain 'NewDomain': 75CC8236 > [!IMPORTANT] > Hash codes are used to insert and retrieve keyed objects from hash tables efficiently. However, hash codes don't uniquely identify strings. Identical strings have equal hash codes, but the common language runtime can also assign the same hash code to different strings. In addition, hash codes can vary by version of .NET, by platform within a single version, and by application domain. Because of this, you should not serialize or persist hash code values, nor should you use them as keys in a hash table or dictionary. - For additional information about the use of hash codes and the `GetHashCode` method, see . +For additional information about the use of hash codes and the `GetHashCode` method, see . ## Examples - The following example demonstrates the method using various input strings. +The following example demonstrates the method using various input strings. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.GetHashCode/CPP/gethashcode.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/GetHashCode/gethashcode.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/GetHashCode/gethashcode.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetHashCode/VB/gethashcode.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.GetHashCode/CPP/gethashcode.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/GetHashCode/gethashcode.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/GetHashCode/gethashcode.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetHashCode/VB/gethashcode.vb" id="Snippet1"::: ]]> @@ -7331,12 +6742,12 @@ The `GetPinnableReference` method returns a character that can be used for pinni enumerated constant for the type. +The following example displays the enumerated constant for the type. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.gettypecode/CPP/gtc.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/GetTypeCode/gtc.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/GetTypeCode/gtc.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.gettypecode/VB/gtc.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.gettypecode/CPP/gtc.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/GetTypeCode/gtc.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/GetTypeCode/gtc.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.gettypecode/VB/gtc.vb" id="Snippet1"::: ]]> @@ -7409,17 +6820,17 @@ The `GetPinnableReference` method returns a character that can be used for pinni method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example demonstrates how you can search a for a character using the method. +The following example demonstrates how you can search a for a character using the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/indexof_c.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/indexof_c.cs" interactive="try-dotnet-method" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/indexof_c.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/indexof_c.vb" id="Snippet5"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/indexof_c.cpp" id="Snippet5"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/indexof_c.cs" interactive="try-dotnet-method" id="Snippet5"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/indexof_c.fs" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/indexof_c.vb" id="Snippet5"::: ]]> @@ -7477,30 +6888,30 @@ The `GetPinnableReference` method returns a character that can be used for pinni method always returns 0 (zero) to indicate that the match is found at the beginning of the current instance. In the following example, the method is used to find three substrings (a soft hyphen (U+00AD), a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on the .NET Framework 4 or later, in each case, because the soft hyphen is an ignorable character, the result is the same as if the soft hyphen had not been included in `value`. When searching for a soft hyphen only, the method returns 0 (zero) to indicate that it has found a match at the beginning of the string. +Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. If `value` consists only of one or more ignorable characters, the method always returns 0 (zero) to indicate that the match is found at the beginning of the current instance. In the following example, the method is used to find three substrings (a soft hyphen (U+00AD), a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on the .NET Framework 4 or later, in each case, because the soft hyphen is an ignorable character, the result is the same as if the soft hyphen had not been included in `value`. When searching for a soft hyphen only, the method returns 0 (zero) to indicate that it has found a match at the beginning of the string. - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable21.cs" id="Snippet21"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable21.fs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable21.vb" id="Snippet21"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable21.cs" id="Snippet21"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable21.fs" id="Snippet21"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable21.vb" id="Snippet21"::: ## Examples - The following example searches for the "n" in "animal". Because string indexes begin at zero rather than one, the method indicates that the "n" is at position 1. +The following example searches for the "n" in "animal". Because string indexes begin at zero rather than one, the method indicates that the "n" is at position 1. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/simple1.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/simple1.cs" interactive="try-dotnet-method" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/simple1.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/simple1.vb" id="Snippet12"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/simple1.cpp" id="Snippet12"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/simple1.cs" interactive="try-dotnet-method" id="Snippet12"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/simple1.fs" id="Snippet12"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/simple1.vb" id="Snippet12"::: - The following example uses the method to determine the starting position of an animal name in a sentence. It then uses this position to insert an adjective that describes the animal into the sentence. +The following example uses the method to determine the starting position of an animal name in a sentence. It then uses this position to insert an adjective that describes the animal into the sentence. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringinsert/CPP/stringinsert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringinsert.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringinsert.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringinsert/VB/stringinsert.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringinsert/CPP/stringinsert.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringinsert.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringinsert.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringinsert/VB/stringinsert.vb" id="Snippet1"::: ]]> @@ -7572,19 +6983,19 @@ The `GetPinnableReference` method returns a character that can be used for pinni method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexof1/CPP/ixof1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ixof1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ixof1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexof1/VB/ixof1.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexof1/CPP/ixof1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ixof1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ixof1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexof1/VB/ixof1.vb" id="Snippet1"::: ]]> @@ -7698,23 +7109,23 @@ The `comparisonType` parameter is a enumeration m method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". +Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. If `value` consists only of one or more ignorable characters, the method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable22.cs" id="Snippet22"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable22.fs" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable22.vb" id="Snippet22"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable22.cs" id="Snippet22"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable22.fs" id="Snippet22"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable22.vb" id="Snippet22"::: ## Examples - The following example searches for all occurrences of a specified string within a target string. +The following example searches for all occurrences of a specified string within a target string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringindexof4/CPP/stringindexof4.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringindexof4.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringindexof4.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringindexof4/VB/stringindexof4.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringindexof4/CPP/stringindexof4.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringindexof4.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringindexof4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringindexof4/VB/stringindexof4.vb" id="Snippet1"::: ]]> @@ -7791,16 +7202,16 @@ The `comparisonType` parameter is a enumeration m method that find the first occurrence of a string within another string using different values of the enumeration. +The following example demonstrates three overloads of the method that find the first occurrence of a string within another string using different values of the enumeration. - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: ]]> @@ -7811,11 +7222,11 @@ The `comparisonType` parameter is a enumeration m Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. If consists only of one or more ignorable characters, the method always returns 0 (zero) to indicate that the match is found at the beginning of the current instance. - In the following example, the method is used to find three substrings (a soft hyphen (U+00AD), a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on the .NET Framework 4 or later, because the soft hyphen is an ignorable character, a culture-sensitive search returns the same value that it would return if the soft hyphen were not included in the search string. An ordinal search, however, successfully finds the soft hyphen in one string and reports that it is absent from the second string. +In the following example, the method is used to find three substrings (a soft hyphen (U+00AD), a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on the .NET Framework 4 or later, because the soft hyphen is an ignorable character, a culture-sensitive search returns the same value that it would return if the soft hyphen were not included in the search string. An ordinal search, however, successfully finds the soft hyphen in one string and reports that it is absent from the second string. - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable26.cs" id="Snippet26"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable26.fs" id="Snippet26"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable26.vb" id="Snippet26"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable26.cs" id="Snippet26"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable26.fs" id="Snippet26"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable26.vb" id="Snippet26"::: @@ -7877,32 +7288,32 @@ The `comparisonType` parameter is a enumeration m method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/indexofcii.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/indexofcii.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/indexofcii.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/indexofcii.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/indexofcii.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/indexofcii.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/indexofcii.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/indexofcii.vb" id="Snippet1"::: ]]> or is negative. - -or- +-or- - is greater than the length of this string. + is greater than the length of this string. - -or- +-or- - is greater than the length of this string minus . + is greater than the length of this string minus . @@ -7962,23 +7373,23 @@ The `comparisonType` parameter is a enumeration m method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting in the third through sixth character positions in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". +Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. If `value` consists only of one or more ignorable characters, the method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting in the third through sixth character positions in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable23.cs" id="Snippet23"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable23.fs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable23.vb" id="Snippet23"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable23.cs" id="Snippet23"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable23.fs" id="Snippet23"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable23.vb" id="Snippet23"::: ## Examples - The following example finds the index of all occurrences of the string "he" within a substring of another string. Note that the number of characters to be searched must be recalculated for each search iteration. +The following example finds the index of all occurrences of the string "he" within a substring of another string. Note that the number of characters to be searched must be recalculated for each search iteration. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexof8/CPP/ixof8.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ixof8.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ixof8.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexof8/VB/ixof8.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexof8/CPP/ixof8.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ixof8.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ixof8.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexof8/VB/ixof8.vb" id="Snippet1"::: ]]> @@ -7987,13 +7398,13 @@ The `comparisonType` parameter is a enumeration m or is negative. - -or- +-or- - is greater than the length of this string. + is greater than the length of this string. - -or- +-or- - is greater than the length of this string minus . + is greater than the length of this string minus . As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To use the comparison rules of the current culture to perform this operation, signal your intention explicitly by calling the method overload with a value of for its `comparisonType` parameter. If you don't need linguistic-aware comparison, consider using . @@ -8061,16 +7472,16 @@ The `comparisonType` parameter is a enumeration m method that find the first occurrence of a string within another string using different values of the enumeration. +The following example demonstrates three overloads of the method that find the first occurrence of a string within another string using different values of the enumeration. - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: ]]> @@ -8083,11 +7494,11 @@ The `comparisonType` parameter is a enumeration m Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. If consists only of one or more ignorable characters, the method always returns , which is the character position at which the search begins. - In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting with the third character position in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. +In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting with the third character position in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable25.cs" id="Snippet25"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable25.fs" id="Snippet25"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable25.vb" id="Snippet25"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable25.cs" id="Snippet25"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable25.fs" id="Snippet25"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable25.vb" id="Snippet25"::: @@ -8150,18 +7561,18 @@ The `comparisonType` parameter is a enumeration m method that find the first occurrence of a string within another string using different values of the enumeration. +The following example demonstrates three overloads of the method that find the first occurrence of a string within another string using different values of the enumeration. - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: ]]> @@ -8170,23 +7581,23 @@ The `comparisonType` parameter is a enumeration m or is negative. - -or- +-or- - is greater than the length of this instance. + is greater than the length of this instance. - -or- +-or- - is greater than the length of this string minus . + is greater than the length of this string minus . is not a valid value. Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. If consists only of one or more ignorable characters, the method always returns , which is the character position at which the search begins. - In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting in the third through sixth character positions in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. When it performs an ordinal comparison, however, it finds the substring only in the first string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m" when it performs a culture-sensitive comparison. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. +In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting in the third through sixth character positions in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. When it performs an ordinal comparison, however, it finds the substring only in the first string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m" when it performs a culture-sensitive comparison. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable24.cs" id="Snippet24"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable24.fs" id="Snippet24"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable24.vb" id="Snippet24"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable24.cs" id="Snippet24"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable24.fs" id="Snippet24"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable24.vb" id="Snippet24"::: @@ -8257,18 +7668,18 @@ The `comparisonType` parameter is a enumeration m method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example finds the first vowel in a string. +The following example finds the first vowel in a string. - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/IndexOfAny1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/IndexOfAny1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.IndexOfAny/vb/IndexOfAny1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/IndexOfAny1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/IndexOfAny1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.IndexOfAny/vb/IndexOfAny1.vb" id="Snippet1"::: ]]> @@ -8335,21 +7746,21 @@ The `comparisonType` parameter is a enumeration m method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar value are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example finds the index of the occurrence of any character of the string "is" within a substring of another string. +The following example finds the index of the occurrence of any character of the string "is" within a substring of another string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexofany2/CPP/ixany2.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/ixany2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/ixany2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexofany2/VB/ixany2.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexofany2/CPP/ixany2.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/ixany2.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/ixany2.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexofany2/VB/ixany2.vb" id="Snippet1"::: ]]> @@ -8358,9 +7769,9 @@ The `comparisonType` parameter is a enumeration m is negative. - -or- +-or- - is greater than the number of characters in this instance. + is greater than the number of characters in this instance. @@ -8427,21 +7838,21 @@ The `comparisonType` parameter is a enumeration m method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar value are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example finds the index of the occurrence of any character of the string "aid" within a substring of another string. +The following example finds the index of the occurrence of any character of the string "aid" within a substring of another string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexofany3/CPP/ixany3.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/ixany3.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/ixany3.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexofany3/VB/ixany3.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexofany3/CPP/ixany3.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/ixany3.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/ixany3.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexofany3/VB/ixany3.vb" id="Snippet1"::: ]]> @@ -8450,9 +7861,9 @@ The `comparisonType` parameter is a enumeration m or is negative. - -or- +-or- - + is greater than the number of characters in this instance. + + is greater than the number of characters in this instance. @@ -8517,26 +7928,26 @@ The `comparisonType` parameter is a enumeration m [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which `value` is inserted into the current instance. - For example, the return value of `"abc".Insert(2, "XYZ")` is "abXYZc". +For example, the return value of `"abc".Insert(2, "XYZ")` is "abXYZc". ## Examples - The following example inserts a space character in the fourth character position (the character at index 3) of a string. +The following example inserts a space character in the fourth character position (the character at index 3) of a string. - :::code language="csharp" source="~/snippets/csharp/System/String/Insert/Insert1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Insert/Insert1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Insert/vb/Insert1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Insert/Insert1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Insert/Insert1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Insert/vb/Insert1.vb" id="Snippet1"::: - The following console application prompts the users to enter one or more adjectives to describe two animals. It then calls the method to insert the text entered by the user into a string. +The following console application prompts the users to enter one or more adjectives to describe two animals. It then calls the method to insert the text entered by the user into a string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringinsert/CPP/stringinsert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringinsert.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringinsert.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringinsert/VB/stringinsert.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringinsert/CPP/stringinsert.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringinsert.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringinsert.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringinsert/VB/stringinsert.vb" id="Snippet1"::: ]]> @@ -8606,49 +8017,17 @@ The `comparisonType` parameter is a enumeration m A string to search for in the intern pool. Retrieves the system's reference to the specified . The system's reference to , if it is interned; otherwise, a new reference to a string with the value of . - + For more information about this API, see Supplemental API remarks for String.Intern. + method uses the intern pool to search for a string equal to the value of `str`. If such a string exists, its reference in the intern pool is returned. If the string does not exist, a reference to `str` is added to the intern pool, then that reference is returned. - - In the following example, the string s1, which has a value of "MyTest", is already interned because it is a literal in the program. The class generates a new string object that has the same value as s1. A reference to that string is assigned to s2. The method searches for a string that has the same value as s2. Because such a string exists, the method returns the same reference that is assigned to s1. That reference is then assigned to s3. References s1 and s2 compare unequal because they refer to different objects; references s1 and s3 compare equal because they refer to the same string. - - :::code language="csharp" source="~/snippets/csharp/System/String/Intern/Intern1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Intern/Intern1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Intern/vb/Intern1.vb" id="Snippet1"::: - - Compare this method to the method. - -## Version considerations - - In the .NET Framework 3.5 Service Pack 1, the method reverts to its behavior in .NET Framework 1.0 and 1.1 with regard to interning the empty string. In the following example, the variable `str1` is assigned a reference to , and the variable `str2` is assigned the reference to that is returned by calling the method after converting a object whose value is to a string. Then the references contained in `str1` and `str2` are compared for equality. - - :::code language="csharp" source="~/snippets/csharp/System/String/Intern/Intern2.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Intern/Intern2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Intern/vb/Intern2.vb" id="Snippet2"::: - - In the .NET Framework 2.0 Service Pack 1 and .NET Framework 3.0, `str1` and `str2` are not equal. In all other versions, `str1` and `str2` are equal. - -## Performance Considerations - If you are trying to reduce the total amount of memory your application allocates, keep in mind that interning a string has two unwanted side effects. First, the memory allocated for interned objects is not likely to be released until the common language runtime (CLR) terminates. The reason is that the CLR's reference to the interned object can persist after your application, or even your application domain, terminates. Second, to intern a string, you must first create the string. The memory used by the object must still be allocated, even though the memory will eventually be garbage collected. - -The enumeration member marks an assembly as not requiring string-literal interning. You can apply to an assembly using the attribute. Also, when you use [Ngen.exe (Native Image Generator)](/dotnet/framework/tools/ngen-exe-native-image-generator) to compile an assembly in advance of run time, strings are not interned across modules. - -## Examples - The following example uses three strings that are equal in value to determine whether a newly created string and an interned string are equal. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.intern/CPP/string_intern.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Intern/string_intern.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Intern/string_intern.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.intern/VB/string_intern.vb" id="Snippet1"::: - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.intern/CPP/string_intern.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Intern/string_intern.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Intern/string_intern.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.intern/VB/string_intern.vb" id="Snippet1"::: + ]]> + is . @@ -8705,30 +8084,30 @@ The you add programmatically by calling the method. +The common language runtime automatically maintains a table, called the intern pool, which contains a single instance of each unique literal string constant declared in a program, as well as any unique instance of you add programmatically by calling the method. - The intern pool conserves string storage. If you assign a literal string constant to several variables, each variable is set to reference the same constant in the intern pool instead of referencing several different instances of that have identical values. +The intern pool conserves string storage. If you assign a literal string constant to several variables, each variable is set to reference the same constant in the intern pool instead of referencing several different instances of that have identical values. - This method looks up `str` in the intern pool. If `str` has already been interned, a reference to that instance is returned; otherwise, `null` is returned. +This method looks up `str` in the intern pool. If `str` has already been interned, a reference to that instance is returned; otherwise, `null` is returned. - Compare this method to the method. +Compare this method to the method. - This method does not return a Boolean value. If you call the method because you want a Boolean value that indicates whether a particular string is interned, you can use code such as the following. +This method does not return a Boolean value. If you call the method because you want a Boolean value that indicates whether a particular string is interned, you can use code such as the following. - :::code language="csharp" source="~/snippets/csharp/System/String/IsInterned/isinternedex1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IsInterned/isinternedex1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isinterned/vb/isinternedex1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IsInterned/isinternedex1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IsInterned/isinternedex1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isinterned/vb/isinternedex1.vb" id="Snippet1"::: > [!NOTE] > You can override the use of the intern pool when you use [Ngen.exe (Native Image Generator)](/dotnet/framework/tools/ngen-exe-native-image-generator) to install an assembly to the native image cache on a local computer. For more information, see Performance Considerations in the Remarks section for the property. ## Examples - The following example demonstrates that literal strings are interned automatically by the compiler. +The following example demonstrates that literal strings are interned automatically by the compiler. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.isinterned/CPP/isin.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IsInterned/isin.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IsInterned/isin.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.isinterned/VB/isin.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.isinterned/CPP/isin.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IsInterned/isin.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IsInterned/isin.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.isinterned/VB/isin.vb" id="Snippet1"::: ]]> @@ -8749,12 +8128,12 @@ The @@ -8801,11 +8180,11 @@ The . +For a description of supported Unicode normalization forms, see . ]]> @@ -8866,11 +8245,11 @@ The . +For a description of supported Unicode normalization forms, see . ]]> @@ -8943,47 +8322,17 @@ The Indicates whether the specified string is or an empty string (""). if the parameter is or an empty string (""); otherwise, . - + For more information about this API, see Supplemental API remarks for String.IsNullOrEmpty. + is a convenience method that enables you to simultaneously test whether a is `null` or its value is . It is equivalent to the following code: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.isnullorempty/cpp/isnullorempty1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrEmpty/isnullorempty1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorempty/vb/isnullorempty1.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrEmpty/isnullorempty1.fs" id="Snippet1"::: - - You can use the method to test whether a string is `null`, its value is , or it consists only of white-space characters. - -## What is a null string? - -A string is `null` if it has not been assigned a value (in C++ and Visual Basic) or if it has explicitly been assigned a value of `null`. Although the [composite formatting](/dotnet/standard/base-types/composite-formatting) feature can gracefully handle a null string, as the following example shows, attempting to call one if its members throws a . - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.isnullorempty/cpp/NullString1.cpp" id="Snippet2"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrEmpty/NullString1.cs" interactive="try-dotnet-method" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorempty/vb/NullString1.vb" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrEmpty/NullString1.fs" id="Snippet2"::: - -## What is an empty string? - -A string is empty if it is explicitly assigned an empty string ("") or . An empty string has a of 0. The following example creates an empty string and displays its value and its length. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.isnullorempty/cpp/NullString1.cpp" id="Snippet3"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrEmpty/NullString1.cs" interactive="try-dotnet-method" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorempty/vb/NullString1.vb" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrEmpty/NullString2.fs" id="Snippet3"::: - -## Examples - The following example examines three strings and determines whether each string has a value, is an empty string, or is `null`. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.isNullOrEmpty/CPP/inoe.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrEmpty/inoe.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.isNullOrEmpty/VB/inoe.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrEmpty/inoe.fs" id="Snippet1"::: - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.isNullOrEmpty/CPP/inoe.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrEmpty/inoe.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.isNullOrEmpty/VB/inoe.vb" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrEmpty/inoe.fs" id="Snippet1"::: + ]]> + @@ -9048,20 +8397,20 @@ A string is empty if it is explicitly assigned an empty string ("") or is a convenience method that is similar to the following code, except that it offers superior performance: + is a convenience method that is similar to the following code, except that it offers superior performance: - :::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorwhitespace/vb/isnullorwhitespace.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorwhitespace/vb/isnullorwhitespace.vb" id="Snippet2"::: - White-space characters are defined by the Unicode standard. The method interprets any character that returns a value of `true` when it is passed to the method as a white-space character. +White-space characters are defined by the Unicode standard. The method interprets any character that returns a value of `true` when it is passed to the method as a white-space character. ## Examples - The following example creates a string array, and then passes each element of the array to the method. +The following example creates a string array, and then passes each element of the array to the method. - :::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorwhitespace/vb/isnullorwhitespace1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorwhitespace/vb/isnullorwhitespace1.vb" id="Snippet1"::: ]]> @@ -9269,20 +8618,20 @@ A string is empty if it is explicitly assigned an empty string ("") or ) is used instead. If any member of `values` is `null`, an empty string is used instead. +If `separator` is `null`, an empty string () is used instead. If any member of `values` is `null`, an empty string is used instead. - is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection returned by the method is passed to the method to display the result as a single string. + is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection returned by the method is passed to the method to display the result as a single string. - :::code language="csharp" source="~/snippets/csharp/System/String/Join/join4.cs" interactive="try-dotnet" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join4.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join4.vb" id="Snippet4"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join4.cs" interactive="try-dotnet" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join4.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join4.vb" id="Snippet4"::: ## Examples - The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. +The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. - :::code language="csharp" source="~/snippets/csharp/System/String/Join/join3.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join3.vb" id="Snippet3"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join3.cs" interactive="try-dotnet" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join3.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join3.vb" id="Snippet3"::: ]]> @@ -9373,16 +8722,16 @@ A string is empty if it is explicitly assigned an empty string ("") or ) is used instead. See the Notes for Callers section if the first element of `values` is `null`. +If `separator` is `null` or if any element of `values` other than the first element is `null`, an empty string () is used instead. See the Notes for Callers section if the first element of `values` is `null`. - is a convenience method that lets you concatenate each element in an object array without explicitly converting its elements to strings. The string representation of each object in the array is derived by calling that object's `ToString` method. + is a convenience method that lets you concatenate each element in an object array without explicitly converting its elements to strings. The string representation of each object in the array is derived by calling that object's `ToString` method. ## Examples - The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a integer array, which it then passes to the method. +The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a integer array, which it then passes to the method. - :::code language="csharp" source="~/snippets/csharp/System/String/Join/join1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join1.vb" id="Snippet1"::: ]]> @@ -9392,9 +8741,9 @@ A string is empty if it is explicitly assigned an empty string ("") or .NET Framework only: If the first element of is , the method does not concatenate the elements in but instead returns . A number of workarounds for this issue are available. The easiest is to assign a value of to the first element of the array, as the following example shows. - :::code language="csharp" source="~/snippets/csharp/System/String/Join/joinfix1.cs" interactive="try-dotnet-method" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Join/joinfix1.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/joinfix1.vb" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Join/joinfix1.cs" interactive="try-dotnet-method" id="Snippet6"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/joinfix1.fs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/joinfix1.vb" id="Snippet6"::: @@ -9475,17 +8824,17 @@ A string is empty if it is explicitly assigned an empty string ("") or ) is used instead. If any element in `value` is `null`, an empty string is used instead. +If `separator` is `null`, an empty string () is used instead. If any element in `value` is `null`, an empty string is used instead. ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringjoin/CPP/stringjoin.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Join/stringjoin.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Join/stringjoin.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringjoin/VB/stringjoin.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringjoin/CPP/stringjoin.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Join/stringjoin.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/stringjoin.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringjoin/VB/stringjoin.vb" id="Snippet1"::: ]]> @@ -9632,24 +8981,24 @@ A string is empty if it is explicitly assigned an empty string ("") or Concatenates the specified elements of a string array, using the specified separator between each element. A string that consists of elements of starting at delimited by the character. - -or- +-or- - if is zero. + if is zero. ) is used instead. If any element in `value` is `null`, an empty string is used instead. +If `separator` is `null`, an empty string () is used instead. If any element in `value` is `null`, an empty string is used instead. ## Examples - The following example concatenates two elements from an array of names of fruit. +The following example concatenates two elements from an array of names of fruit. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.join2/CPP/join2.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Join/join2.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.join2/VB/join2.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.join2/CPP/join2.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join2.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join2.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.join2/VB/join2.vb" id="Snippet1"::: ]]> @@ -9800,22 +9149,22 @@ A string is empty if it is explicitly assigned an empty string ("") or ) is used instead. If any member of `values` is `null`, an empty string is used instead. +If `separator` is `null`, an empty string () is used instead. If any member of `values` is `null`, an empty string is used instead. - is a convenience method that lets you concatenate each member of an collection without first converting them to strings. The string representation of each object in the collection is derived by calling that object's `ToString` method. + is a convenience method that lets you concatenate each member of an collection without first converting them to strings. The string representation of each object in the collection is derived by calling that object's `ToString` method. - This method is particular useful with Language-Integrated Query (LINQ) query expressions. For example, the following code defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object that contains a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method. +This method is particular useful with Language-Integrated Query (LINQ) query expressions. For example, the following code defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object that contains a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method. - :::code language="csharp" source="~/snippets/csharp/System/String/Join/join5.cs" interactive="try-dotnet" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join5.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join5.vb" id="Snippet5"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join5.cs" interactive="try-dotnet" id="Snippet5"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join5.fs" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join5.vb" id="Snippet5"::: ## Examples - The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type integer, which it then passes to the method. +The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type integer, which it then passes to the method. - :::code language="csharp" source="~/snippets/csharp/System/String/Join/join6.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join6.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join2.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join6.cs" interactive="try-dotnet" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join6.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join2.vb" id="Snippet2"::: ]]> @@ -9892,18 +9241,18 @@ A string is empty if it is explicitly assigned an empty string ("") or - 1. +Index numbering starts from zero. That is, the first character in the string is at index zero and the last is at - 1. - This method begins searching at the last character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. The search is case-sensitive. +This method begins searching at the last character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. The search is case-sensitive. - This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example defines an `ExtractFilename` method that uses the method to find the last directory separator character in a string and to extract the string's file name. If the file exists, the method returns the file name without its path. +The following example defines an `ExtractFilename` method that uses the method to find the last directory separator character in a string and to extract the string's file name. If the file exists, the method returns the file name without its path. - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/LastIndexOf_Example.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/LastIndexOf_Example.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/LastIndexOf_Example.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/LastIndexOf_Example.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/LastIndexOf_Example.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/LastIndexOf_Example.vb" id="Snippet1"::: ]]> @@ -9978,16 +9327,16 @@ Character sets include ignorable characters, which are characters that are not c In the following example, the method is used to find two substrings (a soft hyphen followed by "n" and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on .NET Framework 4 or later, in each case, because the soft hyphen is an ignorable character, the result is the same as if the soft hyphen had not been included in `value`. - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof21.cs" id="Snippet21"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof21.fs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof21.vb" id="Snippet21"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof21.cs" id="Snippet21"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof21.fs" id="Snippet21"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof21.vb" id="Snippet21"::: ## Examples - The following example removes opening and closing HTML tags from a string if the tags begin and end the string. If a string ends with a closing bracket character (">"), the example uses the method to locate the start of the end tag. +The following example removes opening and closing HTML tags from a string if the tags begin and end the string. If a string ends with a closing bracket character (">"), the example uses the method to locate the start of the end tag. - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof_example2.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof_example2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof_example2.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof_example2.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof_example2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof_example2.vb" id="Snippet2"::: ]]> @@ -10052,17 +9401,17 @@ In the following example, the - 1. This method begins searching at the `startIndex` character position of this instance and proceeds backward toward the beginning of the current instance until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. The search is case-sensitive. +Index numbering starts from zero. That is, the first character in the string is at index zero and the last is at - 1. This method begins searching at the `startIndex` character position of this instance and proceeds backward toward the beginning of the current instance until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. The search is case-sensitive. - This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example finds the index of all occurrences of a character in a string, working from the end of the string to the start of the string. +The following example finds the index of all occurrences of a character in a string, working from the end of the string to the start of the string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.lastindexof1/CPP/lastixof1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.lastindexof1/VB/lastixof1.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.lastindexof1/CPP/lastixof1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.lastindexof1/VB/lastixof1.vb" id="Snippet1"::: ]]> @@ -10124,25 +9473,25 @@ In the following example, the - 1. +Index numbering starts from zero. That is, the first character in the string is at index zero and the last is at - 1. - The search begins at the `startIndex` character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. +The search begins at the `startIndex` character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. - This method performs a word (case-sensitive and culture-sensitive) search using the current culture. +This method performs a word (case-sensitive and culture-sensitive) search using the current culture. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. In the following example, the method is used to find a substring that includes a soft hyphen (U+00AD) and that precedes or includes the final "m" in a string. If the example is run on .NET Framework 4 or later, because the soft hyphen in the search string is ignored, calling the method to find a substring that consists of the soft hyphen and "m" returns the position of the "m" in the string, whereas calling it to find a substring that consists of the soft hyphen and "n" returns the position of the "n". +Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. In the following example, the method is used to find a substring that includes a soft hyphen (U+00AD) and that precedes or includes the final "m" in a string. If the example is run on .NET Framework 4 or later, because the soft hyphen in the search string is ignored, calling the method to find a substring that consists of the soft hyphen and "m" returns the position of the "m" in the string, whereas calling it to find a substring that consists of the soft hyphen and "n" returns the position of the "n". - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof22.cs" id="Snippet22"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof22.fs" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof22.vb" id="Snippet22"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof22.cs" id="Snippet22"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof22.fs" id="Snippet22"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof22.vb" id="Snippet22"::: ## Examples - The following example finds the index of all occurrences of a string in target string, working from the end of the target string to the start of the target string. +The following example finds the index of all occurrences of a string in target string, working from the end of the target string to the start of the target string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOf7/CPP/lastixof7.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof7.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof7.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOf7/VB/lastixof7.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOf7/CPP/lastixof7.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof7.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof7.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOf7/VB/lastixof7.vb" id="Snippet1"::: ]]> @@ -10150,9 +9499,9 @@ In the following example, the is . The current instance does not equal , and is less than zero or greater than the length of the current instance. - -or- +-or- - The current instance equals , and is less than -1 or greater than zero. +The current instance equals , and is less than -1 or greater than zero. As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To find the index of a substring that precedes a particular character position by using the comparison rules of the current culture, signal your intention explicitly by calling the method overload with a value of for its parameter. If you don't need linguistic-aware comparison, consider using . @@ -10233,11 +9582,11 @@ The `comparisonType` parameter specifies to search for the `value` parameter usi The search begins at the last character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. ## Examples - The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. +The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: ]]> @@ -10248,11 +9597,11 @@ The search begins at the last character position of this instance and proceeds b Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. - In the following example, the method is used to find two substrings (a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on .NET Framework 4 or later, because the soft hyphen is an ignorable character, a culture-sensitive search returns the same value that it would return if the soft hyphen were not included in the search string. An ordinal search, however, successfully finds the soft hyphen in one string and reports that it is absent from the second string. +In the following example, the method is used to find two substrings (a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on .NET Framework 4 or later, because the soft hyphen is an ignorable character, a culture-sensitive search returns the same value that it would return if the soft hyphen were not included in the search string. An ordinal search, however, successfully finds the soft hyphen in one string and reports that it is absent from the second string. - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof26.cs" id="Snippet26"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof26.fs" id="Snippet26"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof26.vb" id="Snippet26"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof26.cs" id="Snippet26"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof26.fs" id="Snippet26"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof26.vb" id="Snippet26"::: @@ -10314,27 +9663,27 @@ The search begins at the last character position of this instance and proceeds b - 1. +Index numbering starts from zero. That is, the first character in the string is at index zero and the last is at - 1. - This method begins searching at the `startIndex` character position and proceeds backward toward the beginning of this instance until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. The search is case-sensitive. +This method begins searching at the `startIndex` character position and proceeds backward toward the beginning of this instance until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. The search is case-sensitive. - This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar value are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar value are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example finds the index of all occurrences of a character in a substring, working from the end of the substring to the start of the substring. +The following example finds the index of all occurrences of a character in a substring, working from the end of the substring to the start of the substring. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.lastindexof2/CPP/lastixof2.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof2.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.lastindexof2/VB/lastixof2.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.lastindexof2/CPP/lastixof2.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof2.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof2.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.lastindexof2/VB/lastixof2.vb" id="Snippet1"::: ]]> The current instance does not equal , and is less than zero or greater than or equal to the length of this instance. - -or- +-or- - The current instance does not equal , and - + 1 is less than zero. +The current instance does not equal , and - + 1 is less than zero. @@ -10394,27 +9743,27 @@ The search begins at the last character position of this instance and proceeds b - 1. +Index numbering starts from zero. That is, the first character in the string is at index zero and the last is at - 1. - The search begins at the `startIndex` character position of this instance and proceeds backward toward the beginning until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. +The search begins at the `startIndex` character position of this instance and proceeds backward toward the beginning until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. - This method performs a word (case-sensitive and culture-sensitive) search using the current culture. +This method performs a word (case-sensitive and culture-sensitive) search using the current culture. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. +Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" or "n" in two strings. Only one of the strings contains a soft hyphen. In the case of the string that includes the soft hyphen followed by an "m", `LastIndexOf` returns the index of the "m" when searching for the soft hyphen followed by "m". - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof23.cs" id="Snippet23"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof23.fs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof23.vb" id="Snippet23"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof23.cs" id="Snippet23"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof23.fs" id="Snippet23"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof23.vb" id="Snippet23"::: ## Examples - The following example finds the index of all occurrences of a string in substring, working from the end of the substring to the start of the substring. +The following example finds the index of all occurrences of a string in substring, working from the end of the substring to the start of the substring. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOf8/CPP/lastixof8.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof8.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof8.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOf8/VB/lastixof8.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOf8/CPP/lastixof8.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof8.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof8.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOf8/VB/lastixof8.vb" id="Snippet1"::: ]]> @@ -10423,25 +9772,25 @@ In the following example, the method is used is negative. - -or- +-or- - The current instance does not equal , and is negative. +The current instance does not equal , and is negative. - -or- +-or- - The current instance does not equal , and is greater than the length of this instance. +The current instance does not equal , and is greater than the length of this instance. - -or- +-or- - The current instance does not equal , and - + 1 specifies a position that is not within this instance. +The current instance does not equal , and - + 1 specifies a position that is not within this instance. - -or- +-or- - The current instance equals and is less than -1 or greater than zero. +The current instance equals and is less than -1 or greater than zero. - -or- +-or- - The current instance equals and is greater than 1. +The current instance equals and is greater than 1. As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To perform this operation by using the comparison rules of the current culture, signal your intention explicitly by calling the method overload with a value of for its parameter. If you don't need linguistic-aware comparison, consider using . @@ -10502,18 +9851,18 @@ In the following example, the method is used - 1. +Index numbering starts from zero. That is, the first character in the string is at index zero and the last is at - 1. - The search begins at the `startIndex` character position and proceeds backward until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. +The search begins at the `startIndex` character position and proceeds backward until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. - The `comparisonType` parameter specifies to search for the `value` parameter using the current or invariant culture, using a case-sensitive or case-insensitive search, and using word or ordinal comparison rules. +The `comparisonType` parameter specifies to search for the `value` parameter using the current or invariant culture, using a case-sensitive or case-insensitive search, and using word or ordinal comparison rules. ## Examples - The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. +The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: ]]> @@ -10521,19 +9870,19 @@ In the following example, the method is used is . The current instance does not equal , and is less than zero or greater than the length of the current instance. - -or- +-or- - The current instance equals , and is less than -1 or greater than zero. +The current instance equals , and is less than -1 or greater than zero. is not a valid value. Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. - In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m", starting with the final "m" in two strings. Only one of the strings contains the required substring. If the example is run on .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method returns the index of the "m" and not the index of the soft hyphen. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. +In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m", starting with the final "m" in two strings. Only one of the strings contains the required substring. If the example is run on .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method returns the index of the "m" and not the index of the soft hyphen. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof25.cs" id="Snippet25"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof25.fs" id="Snippet25"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof25.vb" id="Snippet25"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof25.cs" id="Snippet25"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof25.fs" id="Snippet25"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof25.vb" id="Snippet25"::: @@ -10596,22 +9945,22 @@ In the following example, the method is used - 1. +Index numbering starts from zero. That is, the first character in the string is at index zero and the last is at - 1. - The search begins at the `startIndex` character position and proceeds backward until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. +The search begins at the `startIndex` character position and proceeds backward until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. - The `comparisonType` parameter specifies to search for the `value` parameter using: +The `comparisonType` parameter specifies to search for the `value` parameter using: - The current or invariant culture. - A case-sensitive or case-insensitive search. - Word or ordinal comparison rules. ## Examples - The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. +The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: ]]> @@ -10620,35 +9969,35 @@ In the following example, the method is used is negative. - -or- +-or- - The current instance does not equal , and is negative. +The current instance does not equal , and is negative. - -or- +-or- - The current instance does not equal , and is greater than the length of this instance. +The current instance does not equal , and is greater than the length of this instance. - -or- +-or- - The current instance does not equal , and + 1 - specifies a position that is not within this instance. +The current instance does not equal , and + 1 - specifies a position that is not within this instance. - -or- +-or- - The current instance equals and is less than -1 or greater than zero. +The current instance equals and is less than -1 or greater than zero. - -or- +-or- - The current instance equals and is greater than 1. +The current instance equals and is greater than 1. is not a valid value. Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. - In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" in all but the first character position before the final "m" in two strings. Only one of the strings contains the required substring. If the example is run on .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. When it performs an ordinal comparison, however, it finds the substring only in the first string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method returns the index of the "m" when it performs a culture-sensitive comparison. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. +In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" in all but the first character position before the final "m" in two strings. Only one of the strings contains the required substring. If the example is run on .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. When it performs an ordinal comparison, however, it finds the substring only in the first string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method returns the index of the "m" when it performs a culture-sensitive comparison. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof24.cs" id="Snippet24"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof24.fs" id="Snippet24"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof24.vb" id="Snippet24"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof24.cs" id="Snippet24"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof24.fs" id="Snippet24"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof24.vb" id="Snippet24"::: @@ -10713,19 +10062,19 @@ In the following example, the method is used method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example finds the index of the last occurrence of any character in the string "is" within another string. +The following example finds the index of the last occurrence of any character in the string "is" within another string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny1/CPP/lastixany1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny1/VB/lastixany1.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny1/CPP/lastixany1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny1/VB/lastixany1.vb" id="Snippet1"::: ]]> @@ -10789,19 +10138,19 @@ In the following example, the method is used method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example finds the index of the last occurrence of any character in the string "is" within a substring of another string. +The following example finds the index of the last occurrence of any character in the string "is" within a substring of another string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny2/CPP/lastixany2.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny2/VB/lastixany2.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny2/CPP/lastixany2.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany2.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany2.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny2/VB/lastixany2.vb" id="Snippet1"::: ]]> @@ -10874,19 +10223,19 @@ In the following example, the method is used method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. ## Examples - The following example finds the index of the last occurrence of any character in the string "aid" within a substring of another string. +The following example finds the index of the last occurrence of any character in the string "aid" within a substring of another string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny3/CPP/lastixany3.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany3.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany3.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny3/VB/lastixany3.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny3/CPP/lastixany3.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany3.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany3.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny3/VB/lastixany3.vb" id="Snippet1"::: ]]> @@ -10894,9 +10243,9 @@ In the following example, the method is used is . The current instance does not equal , and or is negative. - -or- +-or- - The current instance does not equal , and minus + 1 is less than zero. +The current instance does not equal , and minus + 1 is less than zero. @@ -10955,22 +10304,22 @@ In the following example, the method is used property returns the number of objects in this instance, not the number of Unicode characters. The reason is that a Unicode character might be represented by more than one . Use the class to work with each Unicode character instead of each . +The property returns the number of objects in this instance, not the number of Unicode characters. The reason is that a Unicode character might be represented by more than one . Use the class to work with each Unicode character instead of each . - In some languages, such as C and C++, a null character indicates the end of a string. In .NET, a null character can be embedded in a string. When a string includes one or more null characters, they are included in the length of the total string. For example, in the following string, the substrings "abc" and "def" are separated by a null character. The property returns 7, which indicates that it includes the six alphabetic characters as well as the null character. +In some languages, such as C and C++, a null character indicates the end of a string. In .NET, a null character can be embedded in a string. When a string includes one or more null characters, they are included in the length of the total string. For example, in the following string, the substrings "abc" and "def" are separated by a null character. The property returns 7, which indicates that it includes the six alphabetic characters as well as the null character. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Class/cpp/system.string.class.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Overview/System.String.Class.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Overview/System.String.Class.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/System.String.Class.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Class/cpp/system.string.class.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Overview/System.String.Class.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Overview/System.String.Class.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/System.String.Class.vb" id="Snippet1"::: ## Examples - The following example demonstrates the property. +The following example demonstrates the property. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.length/CPP/length.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Length/length.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Length/length.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.length/VB/length.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.length/CPP/length.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Length/length.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Length/length.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.length/VB/length.vb" id="Snippet1"::: ]]> @@ -10989,12 +10338,12 @@ In the following example, the method is used @@ -11040,7 +10389,7 @@ In the following example, the method is used method is used - U+0061 U+0306 U+0301 - The existence of multiple representations for a single character complicates searching, sorting, matching, and other operations. +The existence of multiple representations for a single character complicates searching, sorting, matching, and other operations. - The Unicode standard defines a process called normalization that returns one binary representation when given any of the equivalent binary representations of a character. Normalization can be performed with several algorithms, called normalization forms, that obey different rules. .NET supports the four normalization forms (C, D, KC, and KD) that are defined by the Unicode standard. When two strings are represented in the same normalization form, they can be compared by using ordinal comparison. +The Unicode standard defines a process called normalization that returns one binary representation when given any of the equivalent binary representations of a character. Normalization can be performed with several algorithms, called normalization forms, that obey different rules. .NET supports the four normalization forms (C, D, KC, and KD) that are defined by the Unicode standard. When two strings are represented in the same normalization form, they can be compared by using ordinal comparison. - To normalize and compare two strings, do the following: +To normalize and compare two strings, do the following: 1. Obtain the strings to be compared from an input source, such as a file or a user input device. @@ -11062,7 +10411,7 @@ In the following example, the method is used 4. Emit the strings in the sorted output based on the order indicated by the previous step. - For a description of supported Unicode normalization forms, see . +For a description of supported Unicode normalization forms, see . ]]> @@ -11122,11 +10471,11 @@ In the following example, the method is used method is used 4. Emit the strings in the sorted output based on the order indicated by the previous step. - For a description of supported Unicode normalization forms, see . +For a description of supported Unicode normalization forms, see . ]]> @@ -11209,17 +10558,17 @@ In the following example, the method is used method defines the operation of the equality operator for the class. It enables code such as that shown in the Example section. The operator, in turn, calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. +The method defines the operation of the equality operator for the class. It enables code such as that shown in the Example section. The operator, in turn, calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. > [!NOTE] > The Visual Basic compiler does not resolve the equality operator as a call to the method. Instead, the equality operator wraps a call to the method. ## Examples - The following example demonstrates the equality operator. +The following example demonstrates the equality operator. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Equality/CPP/equalityop.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/op_Equality/equalityop.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/op_Equality/equalityop.fs" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Equality/CPP/equalityop.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/op_Equality/equalityop.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/op_Equality/equalityop.fs" id="Snippet1"::: ]]> @@ -11338,19 +10687,19 @@ In the following example, the method is used method defines the operation of the inequality operator for the class. It enables code such as that shown in the Examples section. +The method defines the operation of the inequality operator for the class. It enables code such as that shown in the Examples section. - The operator in turn calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. +The operator in turn calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. > [!NOTE] > The Visual Basic compiler does not resolve the inequality operator as a call to the method. Instead, the inequality operator wraps a call to the method. ## Examples - The following example demonstrates the inequality operator. +The following example demonstrates the inequality operator. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Inequality/CPP/inequalityop.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/op_Inequality/inequalityop.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/op_Inequality/inequalityop.fs" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Inequality/CPP/inequalityop.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/op_Inequality/inequalityop.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/op_Inequality/inequalityop.fs" id="Snippet1"::: ]]> @@ -11417,20 +10766,20 @@ In the following example, the method is used method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. +The method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. > [!NOTE] > If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with leading white space so that its total length is `totalWidth` characters. ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadLeft Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/PadLeft/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/PadLeft/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadLeft Example/VB/source.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadLeft Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/PadLeft/source.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/PadLeft/source.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadLeft Example/VB/source.vb" id="Snippet1"::: ]]> @@ -11491,18 +10840,18 @@ In the following example, the method is used method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. +The method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. > [!NOTE] > If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with leading `paddingChar` characters so that its total length is `totalWidth` characters. ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadLeft1 Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/PadLeft/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/PadLeft/source1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadLeft1 Example/VB/source.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadLeft1 Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/PadLeft/source1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/PadLeft/source1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadLeft1 Example/VB/source.vb" id="Snippet1"::: ]]> @@ -11575,20 +10924,20 @@ In the following example, the method is used method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. +The method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. > [!NOTE] > If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with trailing white space so that its total length is `totalWidth` characters. ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadRight Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/PadRight/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/PadRight/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadRight Example/VB/source.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadRight Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/PadRight/source.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/PadRight/source.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadRight Example/VB/source.vb" id="Snippet1"::: ]]> @@ -11649,18 +10998,18 @@ In the following example, the method is used method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. +The method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. > [!NOTE] > If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with trailing `paddingChar` characters so that its total length is `totalWidth` characters. ## Examples - The following example demonstrates the method. +The following example demonstrates the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadRight1 Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/PadRight/source1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/PadRight/source1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadRight1 Example/VB/source.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadRight1 Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/PadRight/source1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/PadRight/source1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadRight1 Example/VB/source.vb" id="Snippet1"::: ]]> @@ -11732,27 +11081,27 @@ In the following example, the method is used [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which all characters from position `startIndex` to the end of the original string have been removed. ## Examples - The following example demonstrates the method. The next-to-last case removes all text starting from the specified index through the end of the string. The last case removes three characters starting from the specified index. +The following example demonstrates the method. The next-to-last case removes all text starting from the specified index through the end of the string. The last case removes three characters starting from the specified index. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.remove/CPP/r.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Remove/r.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Remove/r.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.remove/VB/r.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.remove/CPP/r.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Remove/r.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Remove/r.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.remove/VB/r.vb" id="Snippet1"::: ]]> is less than zero. - -or- +-or- - specifies a position that is not within this string. + specifies a position that is not within this string. @@ -11819,26 +11168,26 @@ In the following example, the method is used [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which the number of characters specified by the `count` parameter have been removed. The characters are removed at the position specified by `startIndex`. ## Examples - The following example demonstrates how you can remove the middle name from a complete name. +The following example demonstrates how you can remove the middle name from a complete name. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringremove/CPP/stringremove.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Remove/stringremove.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Remove/stringremove.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringremove/VB/stringremove.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringremove/CPP/stringremove.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Remove/stringremove.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Remove/stringremove.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringremove/VB/stringremove.vb" id="Snippet1"::: ]]> Either or is less than zero. - -or- +-or- - plus specify a position outside this instance. + plus specify a position outside this instance. @@ -11918,24 +11267,24 @@ In the following example, the method is used [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldChar` are replaced by `newChar`. - Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. +Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. - :::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace2.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace2.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace2.cs" interactive="try-dotnet-method" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace2.vb" id="Snippet2"::: ## Examples - The following example creates a comma separated value list by substituting commas for the blanks between a series of numbers. +The following example creates a comma separated value list by substituting commas for the blanks between a series of numbers. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.replace1/CPP/string.replace1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Replace/string.replace1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/string.replace1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.replace1/VB/string.replace1.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.replace1/CPP/string.replace1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Replace/string.replace1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/string.replace1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.replace1/VB/string.replace1.vb" id="Snippet1"::: ]]> @@ -12017,26 +11366,26 @@ In the following example, the method is used [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. - This method performs an ordinal (case-sensitive and culture-insensitive) search to find `oldValue`. +This method performs an ordinal (case-sensitive and culture-insensitive) search to find `oldValue`. - Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. +Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. - :::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace1.vb" id="Snippet1"::: ## Examples - The following example demonstrates how you can use the method to correct a spelling error. +The following example demonstrates how you can use the method to correct a spelling error. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringreplace/CPP/stringreplace.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Replace/stringreplace.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/stringreplace.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringreplace/VB/stringreplace.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringreplace/CPP/stringreplace.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Replace/stringreplace.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/stringreplace.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringreplace/VB/stringreplace.vb" id="Snippet1"::: ]]> @@ -12239,13 +11588,13 @@ Because this method returns the modified string, you can chain together successi ## Remarks - This method searches for all newline sequences within the string and canonicalizes them to match the newline sequence for the current environment. For example, when running on Windows, all occurrences of non-Windows newline sequences will be replaced with the sequence CRLF. When running on Unix, all occurrences of non-Unix newline sequences will be replaced with a single LF character. +This method searches for all newline sequences within the string and canonicalizes them to match the newline sequence for the current environment. For example, when running on Windows, all occurrences of non-Windows newline sequences will be replaced with the sequence CRLF. When running on Unix, all occurrences of non-Unix newline sequences will be replaced with a single LF character. - It is not recommended that protocol parsers utilize this API. Protocol specifications often mandate specific newline sequences. For example, HTTP/1.1 (RFC 8615) mandates that the request line, status line, and headers lines end with CRLF. Since this API operates over a wide range of newline sequences, a protocol parser utilizing this API could exhibit behaviors unintended by the protocol's authors. +It is not recommended that protocol parsers utilize this API. Protocol specifications often mandate specific newline sequences. For example, HTTP/1.1 (RFC 8615) mandates that the request line, status line, and headers lines end with CRLF. Since this API operates over a wide range of newline sequences, a protocol parser utilizing this API could exhibit behaviors unintended by the protocol's authors. - This overload is equivalent to calling , passing as the replacementText parameter. +This overload is equivalent to calling , passing as the replacementText parameter. - This method is guaranteed O(n) complexity, where n is the length of the input string. +This method is guaranteed O(n) complexity, where n is the length of the input string. ]]> @@ -12286,13 +11635,13 @@ Because this method returns the modified string, you can chain together successi ## Remarks - This method searches for all newline sequences within the string and canonicalizes them to the newline sequence provided by `replacementText`. If `replacementText` is , all newline sequences within the string will be removed. +This method searches for all newline sequences within the string and canonicalizes them to the newline sequence provided by `replacementText`. If `replacementText` is , all newline sequences within the string will be removed. - It is not recommended that protocol parsers utilize this API. Protocol specifications often mandate specific newline sequences. For example, HTTP/1.1 (RFC 8615) mandates that the request line, status line, and headers lines end with CRLF. Since this API operates over a wide range of newline sequences, a protocol parser utilizing this API could exhibit behaviors unintended by the protocol's authors. +It is not recommended that protocol parsers utilize this API. Protocol specifications often mandate specific newline sequences. For example, HTTP/1.1 (RFC 8615) mandates that the request line, status line, and headers lines end with CRLF. Since this API operates over a wide range of newline sequences, a protocol parser utilizing this API could exhibit behaviors unintended by the protocol's authors. - The list of recognized newline sequences is CR (U+000D), LF (U+000A), CRLF (U+000D U+000A), NEL (U+0085), LS (U+2028), FF (U+000C), and PS (U+2029). This list is given by the Unicode Standard, Sec. 5.8, Recommendation R4 and Table 5-2. +The list of recognized newline sequences is CR (U+000D), LF (U+000A), CRLF (U+000D U+000A), NEL (U+0085), LS (U+2028), FF (U+000C), and PS (U+2029). This list is given by the Unicode Standard, Sec. 5.8, Recommendation R4 and Table 5-2. - This method is guaranteed O(n * r) complexity, where n is the length of the input string, and where r is the length of `replacementText`. +This method is guaranteed O(n * r) complexity, where n is the length of the input string, and where r is the length of `replacementText`. ]]> @@ -12582,17 +11931,17 @@ The following example demonstrates how to extract individual words from a block method returns `true` if they are passed to it. +If the `separator` parameter is `null` or contains no characters, white-space characters are assumed to be the delimiters. White-space characters are defined by the Unicode standard and the method returns `true` if they are passed to it. - Each element of `separator` defines a separate delimiter character. If two delimiters are adjacent, or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . +Each element of `separator` defines a separate delimiter character. If two delimiters are adjacent, or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . - If there are more than `count` substrings in this instance, the first `count - 1` substrings are returned in the first `count - 1` elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. +If there are more than `count` substrings in this instance, the first `count - 1` substrings are returned in the first `count - 1` elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. - If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. +If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. The following table shows some examples. @@ -12610,14 +11959,14 @@ The following table shows some examples. | Visual Basic | "Darb" & vbLf & "Smarba" | Nothing | {"Darb", "Smarba"} | ### Performance considerations - The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. - If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. +If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. ## Examples - The following example demonstrates how `count` can be used to limit the number of strings returned by . +The following example demonstrates how `count` can be used to limit the number of strings returned by . :::code language="csharp" source="~/snippets/csharp/System/String/Split/limit.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/String/Split/limit.fs" id="Snippet1"::: @@ -12735,24 +12084,24 @@ To pass `null` for the `char[] separator` parameter, you must indicate the type :::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet5"::: ### Comparison details - The method extracts the substrings in this string that are delimited by one or more of the characters in the `separator` parameter, and returns those substrings as elements of an array. +The method extracts the substrings in this string that are delimited by one or more of the characters in the `separator` parameter, and returns those substrings as elements of an array. - The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. +The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. ### Performance considerations - The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. - If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. +If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. ## Examples - The following example uses the enumeration to include or exclude substrings generated by the method. +The following example uses the enumeration to include or exclude substrings generated by the method. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.split3/CPP/omit.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/system/string.split/omit.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.split3/CPP/omit.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/omit.vb" id="Snippet1"::: ]]> @@ -12907,24 +12256,24 @@ To pass `null` for the `string[] separator` parameter, you must indicate the typ :::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet6"::: ### Comparison details - The method extracts the substrings in this string that are delimited by one or more of the strings in the `separator` parameter, and returns those substrings as elements of an array. +The method extracts the substrings in this string that are delimited by one or more of the strings in the `separator` parameter, and returns those substrings as elements of an array. - The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. +The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. - The method ignores any element of `separator` whose value is `null` or the empty string (""). +The method ignores any element of `separator` whose value is `null` or the empty string (""). - To avoid ambiguous results when strings in `separator` have characters in common, the operation proceeds from the beginning to the end of the value of the instance, and matches the first element in `separator` that is equal to a delimiter in the instance. The order in which substrings are encountered in the instance takes precedence over the order of elements in `separator`. +To avoid ambiguous results when strings in `separator` have characters in common, the operation proceeds from the beginning to the end of the value of the instance, and matches the first element in `separator` that is equal to a delimiter in the instance. The order in which substrings are encountered in the instance takes precedence over the order of elements in `separator`. - For example, consider an instance whose value is "abcdef". If the first element in `separator` was "ef" and the second element was "bcde", the result of the split operation would be a string array that contains two elements, "a" and "f". This is because the substring in the instance, "bcde", is encountered and matches an element in `separator` before the substring "f" is encountered. +For example, consider an instance whose value is "abcdef". If the first element in `separator` was "ef" and the second element was "bcde", the result of the split operation would be a string array that contains two elements, "a" and "f". This is because the substring in the instance, "bcde", is encountered and matches an element in `separator` before the substring "f" is encountered. - However, if the first element of `separator` was "bcd" and the second element was "bc", the result of the split operation would be a string array that contains two elements, "a" and "ef". This is because "bcd" is the first delimiter in `separator` that matches a delimiter in the instance. If the order of the separators was reversed so the first element was "bc" and the second element was "bcd", the result would be a string array that contains two elements, "a" and "def". +However, if the first element of `separator` was "bcd" and the second element was "bc", the result of the split operation would be a string array that contains two elements, "a" and "ef". This is because "bcd" is the first delimiter in `separator` that matches a delimiter in the instance. If the order of the separators was reversed so the first element was "bc" and the second element was "bcd", the result would be a string array that contains two elements, "a" and "def". ### Performance considerations - The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. - If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. +If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. ## Examples @@ -13079,20 +12428,20 @@ To pass `null` for the `char[] separator` parameter, you must indicate the type :::code language="fsharp" source="~/snippets/fsharp/System/String/Split/identify.fs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet3"::: - If the `count` parameter is zero, or the `options` parameter is and the length of this instance is zero, an empty array is returned. +If the `count` parameter is zero, or the `options` parameter is and the length of this instance is zero, an empty array is returned. - Each element of `separator` defines a separate delimiter character. If the `options` parameter is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . +Each element of `separator` defines a separate delimiter character. If the `options` parameter is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . - If there are more than `count` substrings in this instance, the first `count` minus 1 substrings are returned in the first `count` minus 1 elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. +If there are more than `count` substrings in this instance, the first `count` minus 1 substrings are returned in the first `count` minus 1 elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. - If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. +If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. ### Performance considerations - The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. - If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. +If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. ## Examples @@ -13249,37 +12598,37 @@ To pass `null` for the `string[] separator` parameter, you must indicate the typ :::code language="fsharp" source="~/snippets/fsharp/System/String/Split/identify.fs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet4"::: - If the `count` parameter is zero, or the `options` parameter is and the length of this instance is zero, an empty array is returned. +If the `count` parameter is zero, or the `options` parameter is and the length of this instance is zero, an empty array is returned. - Each element of `separator` defines a separate delimiter that consists of one or more characters. If the `options` parameter is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . +Each element of `separator` defines a separate delimiter that consists of one or more characters. If the `options` parameter is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . - If there are more than `count` substrings in this instance, the first `count` minus 1 substrings are returned in the first `count` minus 1 elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. +If there are more than `count` substrings in this instance, the first `count` minus 1 substrings are returned in the first `count` minus 1 elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. - If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. +If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. ### The separator array If any of the elements in `separator` consists of multiple characters, the entire substring is considered a delimiter. For example, if one of the elements in `separator` is "10", attempting to split the string "This10is10a10string." returns this four-element array: { "This", "is", "a", "string." }. ### Comparison details - The method extracts the substrings in this string that are delimited by one or more of the strings in the `separator` parameter, and returns those substrings as elements of an array. +The method extracts the substrings in this string that are delimited by one or more of the strings in the `separator` parameter, and returns those substrings as elements of an array. - The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. +The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. - The method ignores any element of `separator` whose value is `null` or the empty string (""). +The method ignores any element of `separator` whose value is `null` or the empty string (""). - To avoid ambiguous results when strings in `separator` have characters in common, the method proceeds from the beginning to the end of the value of the instance, and matches the first element in `separator` that is equal to a delimiter in the instance. The order in which substrings are encountered in the instance takes precedence over the order of elements in `separator`. +To avoid ambiguous results when strings in `separator` have characters in common, the method proceeds from the beginning to the end of the value of the instance, and matches the first element in `separator` that is equal to a delimiter in the instance. The order in which substrings are encountered in the instance takes precedence over the order of elements in `separator`. - For example, consider an instance whose value is "abcdef". If the first element in `separator` was "ef" and the second element was "bcde", the result of the split operation would be "a" and "f". This is because the substring in the instance, "bcde", is encountered and matches an element in `separator` before the substring "f" is encountered. +For example, consider an instance whose value is "abcdef". If the first element in `separator` was "ef" and the second element was "bcde", the result of the split operation would be "a" and "f". This is because the substring in the instance, "bcde", is encountered and matches an element in `separator` before the substring "f" is encountered. - However, if the first element of `separator` was "bcd" and the second element was "bc", the result of the split operation would be "a" and "ef". This is because "bcd" is the first delimiter in `separator` that matches a delimiter in the instance. If the order of the separators was reversed so the first element was "bc" and the second element was "bcd", the result would be "a" and "def". +However, if the first element of `separator` was "bcd" and the second element was "bc", the result of the split operation would be "a" and "ef". This is because "bcd" is the first delimiter in `separator` that matches a delimiter in the instance. If the order of the separators was reversed so the first element was "bc" and the second element was "bcd", the result would be "a" and "def". ### Performance considerations - The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. - If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. +If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. ## Examples @@ -13487,22 +12836,22 @@ The following example defines a `StripStartTags` method that uses the method compares the `value` parameter to the substring at the beginning of this string and returns a value that indicates whether they are equal. To be equal, `value` must be a reference to this same string, must be the empty string (""), or must match the beginning of this string. The type of comparison performed by the method depends on the value of the `comparisonType` parameter. The comparison can use the conventions of the current culture ( and ) or the invariant culture ( and ), or it can consist of a character-by-character comparison of code points ( or ). The comparison can also be case-sensitive (, , or ), or it can ignore case (, , ). +The method compares the `value` parameter to the substring at the beginning of this string and returns a value that indicates whether they are equal. To be equal, `value` must be a reference to this same string, must be the empty string (""), or must match the beginning of this string. The type of comparison performed by the method depends on the value of the `comparisonType` parameter. The comparison can use the conventions of the current culture ( and ) or the invariant culture ( and ), or it can consist of a character-by-character comparison of code points ( or ). The comparison can also be case-sensitive (, , or ), or it can ignore case (, , ). ## Examples - The following example searches for the string "the" at the beginning of a longer string that begins with the word "The". As the output from the example shows, a call to the method that performs a culture-insensitive but case-sensitive comparison fails to match the string, while a call that performs a culture- and case-insensitive comparison matches the string. +The following example searches for the string "the" at the beginning of a longer string that begins with the word "The". As the output from the example shows, a call to the method that performs a culture-insensitive but case-sensitive comparison fails to match the string, while a call that performs a culture- and case-insensitive comparison matches the string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.startswith/cpp/StartsWith2.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/StartsWith2.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/StartsWith2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.startswith/vb/StartsWith2.vb" id="Snippet2"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.startswith/cpp/StartsWith2.cpp" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/StartsWith2.cs" interactive="try-dotnet" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/StartsWith2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.startswith/vb/StartsWith2.vb" id="Snippet2"::: - The following example determines whether a string starts with a particular substring. It initializes a two-dimensional string array. The first element in the second dimension contains a string, and the second element contains the string to search for at the start of the first string. The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed. Note that when the string instance contains a ligature, culture-sensitive comparisons with its consecutive characters successfully match. +The following example determines whether a string starts with a particular substring. It initializes a two-dimensional string array. The first element in the second dimension contains a string, and the second element contains the string to search for at the start of the first string. The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed. Note that when the string instance contains a ligature, culture-sensitive comparisons with its consecutive characters successfully match. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.startswith/cpp/startswith1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/startswith1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/startswith1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.startswith/vb/startswith1.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.startswith/cpp/startswith1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/startswith1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/startswith1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.startswith/vb/startswith1.vb" id="Snippet1"::: ]]> @@ -13570,16 +12919,16 @@ The following example defines a `StripStartTags` method that uses the ), must be a reference to this same instance, or must match the beginning of this instance. +This method compares the `value` parameter to the substring at the beginning of this string that is the same length as `value`, and returns a value that indicates whether they are equal. To be equal, `value` must be an empty string (), must be a reference to this same instance, or must match the beginning of this instance. - This method performs a comparison using the specified casing and culture. +This method performs a comparison using the specified casing and culture. ## Examples - The following example determines whether a string occurs at the beginning of another string. The method is called several times using case sensitivity, case insensitivity, and different cultures that influence the results of the search. +The following example determines whether a string occurs at the beginning of another string. The method is called several times using case sensitivity, case insensitivity, and different cultures that influence the results of the search. - :::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/swci.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/swci.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.StartsWithCI/vb/swci.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/swci.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/swci.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.StartsWithCI/vb/swci.vb" id="Snippet1"::: ]]> @@ -13599,7 +12948,7 @@ The following example defines a `StripStartTags` method that uses the Retrieves a substring from this instance. - This member is overloaded. For complete information about this member, including syntax, usage, and examples, click a name in the overload list. +This member is overloaded. For complete information about this member, including syntax, usage, and examples, click a name in the overload list. @@ -13656,29 +13005,29 @@ The following example defines a `StripStartTags` method that uses the method to extract a substring from a string that begins at a specified character position and ends at the end of the string. The starting character position is zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and ends before the end of the string, call the method. +You call the method to extract a substring from a string that begins at a specified character position and ends at the end of the string. The starting character position is zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and ends before the end of the string, call the method. > [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string that begins at the `startIndex` position in the current string. - To extract a substring that begins with a particular character or character sequence, call a method such as or to get the value of `startIndex`. The second example illustrates this; it extracts a key value that begins one character position after the `=` character. +To extract a substring that begins with a particular character or character sequence, call a method such as or to get the value of `startIndex`. The second example illustrates this; it extracts a key value that begins one character position after the `=` character. - If `startIndex` is equal to zero, the method returns the original string unchanged. +If `startIndex` is equal to zero, the method returns the original string unchanged. ## Examples - The following example demonstrates obtaining a substring from a string. +The following example demonstrates obtaining a substring from a string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/System.String.Substring/cpp/Substring10.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring10.cs" interactive="try-dotnet-method" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring10.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring10.vb" id="Snippet10"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/System.String.Substring/cpp/Substring10.cpp" id="Snippet10"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring10.cs" interactive="try-dotnet-method" id="Snippet10"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring10.fs" id="Snippet10"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring10.vb" id="Snippet10"::: - The following example uses the method to separate key/value pairs that are delimited by an equals (`=`) character. +The following example uses the method to separate key/value pairs that are delimited by an equals (`=`) character. - :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring1.vb" id="Snippet1"::: - The method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. +The method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. ]]> @@ -13754,16 +13103,16 @@ The following example defines a `StripStartTags` method that uses the method to extract a substring from a string that begins at a specified character position and ends before the end of the string. The starting character position is zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and continues to the end of the string, call the method. +You call the method to extract a substring from a string that begins at a specified character position and ends before the end of the string. The starting character position is zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and continues to the end of the string, call the method. > [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string with `length` characters starting from the `startIndex` position in the current string. - The `length` parameter represents the total number of characters to extract from the current string instance. This includes the starting character found at index `startIndex`. In other words, the method attempts to extract characters from index `startIndex` to index `startIndex` + `length` - 1. +The `length` parameter represents the total number of characters to extract from the current string instance. This includes the starting character found at index `startIndex`. In other words, the method attempts to extract characters from index `startIndex` to index `startIndex` + `length` - 1. - To extract a substring that begins with a particular character or character sequence, call a method such as or to get the value of `startIndex`. +To extract a substring that begins with a particular character or character sequence, call a method such as or to get the value of `startIndex`. - If the substring should extend from `startIndex` to a specified character sequence, you can call a method such as or to get the index of the ending character or character sequence. You can then convert that value to an index position in the string as follows: +If the substring should extend from `startIndex` to a specified character sequence, you can call a method such as or to get the index of the ending character or character sequence. You can then convert that value to an index position in the string as follows: - If you've searched for a single character that is to mark the end of the substring, the `length` parameter equals `endIndex` - `startIndex` + 1, where `endIndex` is the return value of the or method. The following example extracts a continuous block of "b" characters from a string. @@ -13779,16 +13128,16 @@ The following example defines a `StripStartTags` method that uses the or method. - If `startIndex` is equal to zero and `length` equals the length of the current string, the method returns the original string unchanged. +If `startIndex` is equal to zero and `length` equals the length of the current string, the method returns the original string unchanged. ## Examples - The following example illustrates a simple call to the method that extracts two characters from a string starting at the sixth character position (that is, at index five). +The following example illustrates a simple call to the method that extracts two characters from a string starting at the sixth character position (that is, at index five). - :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring4.cs" interactive="try-dotnet-method" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring4.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring4.vb" id="Snippet4"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring4.cs" interactive="try-dotnet-method" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring4.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring4.vb" id="Snippet4"::: - The following example uses the method in the following three cases to isolate substrings within a string. In two cases the substrings are used in comparisons, and in the third case an exception is thrown because invalid parameters are specified. +The following example uses the method in the following three cases to isolate substrings within a string. In two cases the substrings are used in comparisons, and in the third case an exception is thrown because invalid parameters are specified. - It extracts the single character at the third position in the string (at index 2) and compares it with a "c". This comparison returns `true`. @@ -13796,26 +13145,26 @@ The following example defines a `StripStartTags` method that uses the exception. - :::code language="csharp" source="~/snippets/csharp/System/String/Substring/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.Substring1 Example/VB/source.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Substring/source.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/source.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.Substring1 Example/VB/source.vb" id="Snippet1"::: - The following example uses the method to separate key/value pairs that are delimited by an equals (`=`) character. +The following example uses the method to separate key/value pairs that are delimited by an equals (`=`) character. - :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring1.vb" id="Snippet1"::: - The method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. +The method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. ]]> plus indicates a position not within this instance. - -or- +-or- - or is less than zero. + or is less than zero. @@ -13866,7 +13215,7 @@ The following example defines a `StripStartTags` method that uses the instance is cast to an interface object. For more information, see the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface object. For more information, see the method. ]]> @@ -13920,7 +13269,7 @@ The following example defines a `StripStartTags` method that uses the instance is cast to an interface. For more information, see the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. For more information, see the method. ]]> @@ -14027,10 +13376,10 @@ The following example uses the method with an The following example displays the enumerated constant for the type. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.gettypecode/CPP/gtc.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/GetTypeCode/gtc.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/GetTypeCode/gtc.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.gettypecode/VB/gtc.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.gettypecode/CPP/gtc.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/GetTypeCode/gtc.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/GetTypeCode/gtc.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.gettypecode/VB/gtc.vb" id="Snippet1"::: ]]> @@ -14086,7 +13435,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14148,7 +13497,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14205,7 +13554,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14266,7 +13615,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14327,7 +13676,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14390,7 +13739,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14453,7 +13802,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14516,7 +13865,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14577,7 +13926,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14642,7 +13991,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14705,7 +14054,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14809,7 +14158,7 @@ This member is an explicit interface member implementation. It can be used only instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14877,7 +14226,7 @@ This member is an explicit interface member implementation. It can be used only instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -14944,7 +14293,7 @@ This member is an explicit interface member implementation. It can be used only instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -15011,7 +14360,7 @@ This member is an explicit interface member implementation. It can be used only instance is cast to an interface. The recommended alternative is to call the method. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -15244,11 +14593,11 @@ This member is an explicit interface member implementation. It can be used only object) in a string to a character array. The first character copied is at index zero of the returned character array; the last character copied is at index - 1. +This method copies each character (that is, each object) in a string to a character array. The first character copied is at index zero of the returned character array; the last character copied is at index - 1. - To create a string from the characters in a character array, call the constructor. +To create a string from the characters in a character array, call the constructor. - To create a byte array that contains the encoded characters in a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include the following: +To create a byte array that contains the encoded characters in a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include the following: |Encoding|Object| |--------------|------------| @@ -15258,14 +14607,14 @@ This member is an explicit interface member implementation. It can be used only |UTF-16|| |UTF-32|| - For more information, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). +For more information, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). ## Examples - The following example calls the method to extract the characters in a string to a character array. It then displays the original string and the elements in the array. +The following example calls the method to extract the characters in a string to a character array. It then displays the original string and the elements in the array. - :::code language="csharp" source="~/snippets/csharp/System/String/ToCharArray/ToCharArray1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/ToCharArray/ToCharArray1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.tochararray/vb/ToCharArray1.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/ToCharArray/ToCharArray1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToCharArray/ToCharArray1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.tochararray/vb/ToCharArray1.vb" id="Snippet1"::: ]]> @@ -15329,13 +14678,13 @@ This member is an explicit interface member implementation. It can be used only constructor. +This method copies the characters in a portion of a string to a character array. To create a string from a range of characters in a character array, call the constructor. - The `startIndex` parameter is zero-based. That is, the index of the first character in the string instance is zero. +The `startIndex` parameter is zero-based. That is, the index of the first character in the string instance is zero. - If `length` is zero, the returned array is empty and has a zero length. If this instance is `null` or an empty string (""), the returned array is empty and has a zero length. +If `length` is zero, the returned array is empty and has a zero length. If this instance is `null` or an empty string (""), the returned array is empty and has a zero length. - To create a byte array that contains the encoded characters in a portion of a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include: +To create a byte array that contains the encoded characters in a portion of a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include: |Encoding|Object| |--------------|------------| @@ -15345,24 +14694,24 @@ This member is an explicit interface member implementation. It can be used only |UTF-16|| |UTF-32|| - For more information, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). +For more information, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). ## Examples - The following example converts a substring within a string to an array of characters, then enumerates and displays the elements of the array. +The following example converts a substring within a string to an array of characters, then enumerates and displays the elements of the array. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.ToCharArray1/CPP/tocharry1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/ToCharArray/tocharry1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/ToCharArray/tocharry1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.ToCharArray1/VB/tocharry1.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.ToCharArray1/CPP/tocharry1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/ToCharArray/tocharry1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToCharArray/tocharry1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.ToCharArray1/VB/tocharry1.vb" id="Snippet1"::: ]]> or is less than zero. - -or- +-or- - plus is greater than the length of this instance. + plus is greater than the length of this instance. @@ -15426,24 +14775,26 @@ This member is an explicit interface member implementation. It can be used only [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. -## Security Considerations - The casing operation that results from calling the method takes the casing conventions of the current culture into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. This produces the same result in every culture (unlike the method) and performs more efficiently. - -## Examples - The following example converts several mixed case strings to lowercase. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringlowerupper/CPP/stringtolower.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/ToLower/stringtolower.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/ToLower/stringtolower.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringlowerupper/VB/stringtolower.vb" id="Snippet1"::: +The casing operation that results from calling the method takes the casing conventions of the current culture into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. This produces the same result in every culture (unlike the method) and performs more efficiently. ]]> + + + As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string casing methods that substitute default values and instead call methods that require parameters to be explicitly specified. To convert a character to lowercase by using the casing conventions of the current culture, signal your intention explicitly by calling the method overload with a value of for its parameter. If you don't need linguistic-aware comparison, consider using . @@ -15510,24 +14861,26 @@ This member is an explicit interface member implementation. It can be used only [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. -## Security Considerations - If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. - -## Examples - The following example converts two strings of uppercase characters to lowercase characters using the English-United States and Turkish-Turkey cultures, then compares the lowercase strings. The uppercase strings are identical except that for each occurrence of the Unicode LATIN CAPITAL LETTER I in one string, the other string contains LATIN CAPITAL LETTER I WITH DOT ABOVE. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.tolower1/CPP/tolower.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/ToLower/tolower.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/ToLower/tolower.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.tolower1/VB/tolower.vb" id="Snippet1"::: +If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. ]]> + + + @@ -15582,22 +14935,21 @@ This member is an explicit interface member implementation. It can be used only property. +The invariant culture represents a culture that is culture-insensitive. It is associated with the English language but not with a specific country or region. For more information, see the property. - If your application depends on the case of a string changing in a predictable way that is unaffected by the current culture, use the method. The method is equivalent to `ToLower(CultureInfo.InvariantCulture)`. The method is recommended when a collection of strings must appear in a predictable order in a user interface control. +If your application depends on the case of a string changing in a predictable way that is unaffected by the current culture, use the method. The method is equivalent to `ToLower(CultureInfo.InvariantCulture)`. The method is recommended when a collection of strings must appear in a predictable order in a user interface control. > [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. -## Security Considerations - If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. +If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. ## Examples - The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the lowercase array to ensure that elements appear in the same order regardless of language. +The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the lowercase array to ensure that elements appear in the same order regardless of language. - :::code language="csharp" source="~/snippets/csharp/System/String/ToLowerInvariant/tolowerinvariant.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/ToLowerInvariant/tolowerinvariant.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.tolowerinvariant/vb/tolowerinvariant.vb" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/ToLowerInvariant/tolowerinvariant.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToLowerInvariant/tolowerinvariant.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.tolowerinvariant/vb/tolowerinvariant.vb" id="Snippet1"::: ]]> @@ -15671,15 +15023,15 @@ This member is an explicit interface member implementation. It can be used only method.Note that the example does not explicitly call the method. Instead, the method is called implicitly by the [composite formatting](/dotnet/standard/base-types/composite-formatting) feature. +The following example demonstrates the method.Note that the example does not explicitly call the method. Instead, the method is called implicitly by the [composite formatting](/dotnet/standard/base-types/composite-formatting) feature. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.tostring/CPP/string.tostring.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/ToString/string.tostring.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/ToString/string.tostring.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.tostring/VB/string.tostring.vb" id="Snippet1"::: +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.tostring/CPP/string.tostring.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/ToString/string.tostring.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToString/string.tostring.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.tostring/VB/string.tostring.vb" id="Snippet1"::: ]]> @@ -15747,9 +15099,9 @@ This member is an explicit interface member implementation. It can be used only @@ -15813,26 +15165,27 @@ This member is an explicit interface member implementation. It can be used only [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. - The method is often used to convert a string to uppercase so that it can be used in a case-insensitive comparison. A better method to perform case-insensitive comparison is to call a string comparison method that has a parameter whose value you set to for a culture-sensitive, case-insensitive comparison. +The method is often used to convert a string to uppercase so that it can be used in a case-insensitive comparison. A better method to perform case-insensitive comparison is to call a string comparison method that has a parameter whose value you set to for a culture-sensitive, case-insensitive comparison. -## Security Considerations - The casing operation that results from calling the method takes the casing conventions of the current culture into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture (unlike the method) and performs more efficiently. - -## Examples - The following example calls the method to convert a series of one-character strings that contain each character in the Basic Latin, Latin-1 Supplement, and Latin Extended-A character sets. It then displays each string whose uppercase character is different from its lowercase character. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.ToUpper/cpp/ToUpperEx.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/String/ToUpper/ToUpperEx.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/ToUpper/ToUpperEx.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.ToUpper/vb/ToUpperEx.vb" id="Snippet1"::: +The casing operation that results from calling the method takes the casing conventions of the current culture into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture (unlike the method) and performs more efficiently. ]]> + + method to convert a series of one-character strings that contain each character in the Basic Latin, Latin-1 Supplement, and Latin Extended-A character sets. It then displays each string whose uppercase character is different from its lowercase character. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.ToUpper/cpp/ToUpperEx.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/ToUpper/ToUpperEx.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToUpper/ToUpperEx.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.ToUpper/vb/ToUpperEx.vb" id="Snippet1"::: + ]]> + As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string casing methods that substitute default values and instead call methods that require parameters to be explicitly specified. To convert a string to uppercase by using the casing conventions of the current culture, signal your intention explicitly by calling the method overload with a value of for its parameter. If you don't need linguistic-aware comparison, consider using . @@ -15899,23 +15252,24 @@ This member is an explicit interface member implementation. It can be used only [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. -## Security Considerations - If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. - -## Examples - The following example converts a string of lowercase characters to two strings of uppercase characters using the English-United States and Turkish-Turkey cultures, then compares the uppercase strings. The uppercase strings are identical except that for each occurrence of the Unicode LATIN CAPITAL LETTER I in one string, the other string contains LATIN CAPITAL LETTER I WITH DOT ABOVE. - - :::code language="csharp" source="~/snippets/csharp/System/String/ToUpper/toupper.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/ToUpper/toupper.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.toupper1/VB/toupper.vb" id="Snippet1"::: +If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. ]]> + + + @@ -15971,25 +15325,26 @@ This member is an explicit interface member implementation. It can be used only property. +The invariant culture represents a culture that is culture-insensitive. It is associated with the English language but not with a specific country or region. For more information, see the property. - If your application depends on the case of a string changing in a predictable way that is unaffected by the current culture, use the method. The method is equivalent to `ToUpper(CultureInfo.InvariantCulture)`. The method is recommended when a collection of strings must appear in a predictable order in a user interface control. +If your application depends on the case of a string changing in a predictable way that is unaffected by the current culture, use the method. The method is equivalent to `ToUpper(CultureInfo.InvariantCulture)`. The method is recommended when a collection of strings must appear in a predictable order in a user interface control. > [!NOTE] > This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. -## Security Considerations - If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. - -## Examples - The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the uppercase array to ensure that elements appear in the same order regardless of language. - - :::code language="csharp" source="~/snippets/csharp/System/String/ToUpperInvariant/toupperinvariant.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/ToUpperInvariant/toupperinvariant.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.toupperinvariant/vb/toupperinvariant.vb" id="Snippet1"::: +If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. ]]> + + method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the uppercase array to ensure that elements appear in the same order regardless of language. + +:::code language="csharp" source="~/snippets/csharp/System/String/ToUpperInvariant/toupperinvariant.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToUpperInvariant/toupperinvariant.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.toupperinvariant/vb/toupperinvariant.vb" id="Snippet1"::: + ]]> + diff --git a/xml/System/TimeSpan.xml b/xml/System/TimeSpan.xml index 994c166c749..1f62e8188ac 100644 --- a/xml/System/TimeSpan.xml +++ b/xml/System/TimeSpan.xml @@ -3283,52 +3283,16 @@ The value of this constant is 100. A string that specifies the time interval to convert. Converts the string representation of a time interval to its equivalent. A time interval that corresponds to . - + For more information about this API, see Supplemental API remarks for TimeSpan.Parse. + method to convert each element in a string array to a value. It changes the current system culture to Croatian - Croatia ("hr-HR") and English - United States ("en-US") to illustrate how the current system culture affects the parsing operation. -## Remarks - The `s` parameter contains a time interval specification in the form: - - [*ws*][-]{ *d* | [*d*.]*hh*:*mm*[:*ss*[.*ff*]] }[*ws*] - - Elements in square brackets ([ and ]) are optional. One selection from the list of alternatives enclosed in braces ({ and }) and separated by vertical bars (|) is required. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*ws*|Optional white space.| -|-|An optional minus sign, which indicates a negative .| -|*d*|Days, ranging from 0 to 10675199.| -|.|A culture-sensitive symbol that separates days from hours. The invariant format uses a period (".") character.| -|*hh*|Hours, ranging from 0 to 23.| -|:|The culture-sensitive time separator symbol. The invariant format uses a colon (":") character.| -|*mm*|Minutes, ranging from 0 to 59.| -|*ss*|Optional seconds, ranging from 0 to 59.| -|*.*|A culture-sensitive symbol that separates seconds from fractions of a second. The invariant format uses a period (".") character.| -|*ff*|Optional fractional seconds, consisting of one to seven decimal digits.| - -If the `s` argument is not a day value only, it must include an hours and a minutes component; other components are optional. If they are present, the values of each time component must fall within a specified range. For example, the value of *hh*, the hours component, must be between 0 and 23. Because of this, passing "23:00:00" to the method returns a time interval of 23 hours. On the other hand, passing "24:00:00" returns a time interval of 24 days. Because "24" is outside the range of the hours component, it is interpreted as the days component. - - The components of `s` must collectively specify a time interval that is greater than or equal to and less than or equal to . - - The method tries to parse `s` by using each of the culture-specific formats for the current culture. - -## Notes to callers - -When a time interval component in the string to be parsed contains more than seven digits, parsing operations in the .NET Framework 3.5 and earlier versions may behave differently from parsing operations in the .NET Framework 4 and later versions. In some cases, parsing operations that succeed in the .NET Framework 3.5 and earlier versions may fail and throw an in the .NET Framework 4 and later. In other cases, parsing operations that throw a in the .NET Framework 3.5 and earlier versions may fail and throw an in the .NET Framework 4 and later. The following example illustrates both scenarios. - -:::code language="csharp" source="~/snippets/csharp/System/TimeSpan/Parse/parsefailure1.cs" interactive="try-dotnet-method" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/TimeSpan/Parse/parsefailure1.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.timespan.parse/vb/parsefailure1.vb" id="Snippet3"::: - -## Examples - The following example uses the method to convert each element in a string array to a value. It changes the current system culture to Croatian - Croatia ("hr-HR") and English - United States ("en-US") to illustrate how the current system culture affects the parsing operation. - - :::code language="csharp" source="~/snippets/csharp/System/TimeSpan/Parse/parse1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/TimeSpan/Parse/parse1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.timespan.parse/vb/parse1.vb" id="Snippet1"::: - - ]]> - +:::code language="csharp" source="~/snippets/csharp/System/TimeSpan/Parse/parse1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/TimeSpan/Parse/parse1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.timespan.parse/vb/parse1.vb" id="Snippet1"::: + ]]> + is . @@ -3454,60 +3418,28 @@ When a time interval component in the string to be parsed contains more than sev A time interval that corresponds to , as specified by . .| -|*d*|Days, ranging from 0 to 10675199.| -|.|A culture-sensitive symbol that separates days from hours. The default value is a period (".") character.| -|*hh*|Hours, ranging from 0 to 23.| -|:|The culture-sensitive time separator symbol.| -|*mm*|Minutes, ranging from 0 to 59.| -|*ss*|Optional seconds, ranging from 0 to 59.| -|.|A culture-sensitive symbol that separates seconds from fractions of a second. The default value is a period (".") character.| -|*ff*|Optional fractional seconds, consisting of one to seven decimal digits.| - -If the `input` argument is not a day value only, it must include an hours and a minutes component; other components are optional. If they are present, the values of each time component must fall within a specified range. For example, the value of *hh*, the hours component, must be between 0 and 23. Because of this, passing "23:00:00" to the method returns a time interval of 23 hours. On the other hand, passing "24:00:00" returns a time interval of 24 days. Because "24" is outside the range of the hours component, it is interpreted as the days component. +The `formatProvider` parameter is an implementation that provides culture-specific information about the format of the returned string. The `formatProvider` parameter can be any of the following: - The components of `input` must collectively specify a time interval that is greater than or equal to and less than or equal to . +- A object that represents the culture whose formatting conventions are to be reflected in the returned string. The object returned by the property defines the formatting of the returned string. +- A object that defines the formatting of the returned string. +- A custom object that implements the interface. Its method returns a object that provides formatting information. - The method tries to parse `input` by using each of the culture-specific formats for the culture specified by `formatProvider`. +If `formatProvider` is `null`, the object that is associated with the current culture is used. - The `formatProvider` parameter is an implementation that provides culture-specific information about the format of the returned string. The `formatProvider` parameter can be any of the following: - -- A object that represents the culture whose formatting conventions are to be reflected in the returned string. The object returned by the property defines the formatting of the returned string. - -- A object that defines the formatting of the returned string. - -- A custom object that implements the interface. Its method returns a object that provides formatting information. - - If `formatProvider` is `null`, the object that is associated with the current culture is used. - -## Notes to callers - -When a time interval component in the string to be parsed contains more than seven digits, parsing operations in the .NET Framework 3.5 and earlier versions may behave differently from parsing operations in the .NET Framework 4 and later versions. In some cases, parsing operations that succeed in the .NET Framework 3.5 and earlier versions may fail and throw an in the .NET Framework 4 and later. In other cases, parsing operations that throw a in the .NET Framework 3.5 and earlier versions may fail and throw an in the .NET Framework 4 and later. The following example illustrates both scenarios. - -:::code language="csharp" source="~/snippets/csharp/System/TimeSpan/Parse/parsefailure1.cs" interactive="try-dotnet-method" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/TimeSpan/Parse/parsefailure1.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.timespan.parse/vb/parsefailure1.vb" id="Snippet3"::: - -## Examples - The following example defines an array of objects, and uses each object in calls to the method to parse the elements in a string array. The example illustrates how the conventions of a specific culture influence the formatting operation. +For more information about this API, see [Supplemental API remarks for System.TimeSpan.Parse](/dotnet/fundamentals/runtime-libraries/system-timespan-parse). + ]]> + + + objects, and uses each object in calls to the method to parse the elements in a string array. The example illustrates how the conventions of a specific culture influence the formatting operation. :::code language="csharp" source="~/snippets/csharp/System/TimeSpan/Parse/parse2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/TimeSpan/Parse/parse2.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.timespan.parse/vb/parse2.vb" id="Snippet2"::: - - ]]> - + ]]> + is . @@ -5669,51 +5601,16 @@ The property represents whole and fracti Converts the string representation of a time interval to its equivalent and returns a value that indicates whether the conversion succeeded. if was converted successfully; otherwise, . This operation returns if the parameter is or , has an invalid format, represents a time interval that is less than TimeSpan.MinValue or greater than TimeSpan.MaxValue, or has at least one days, hours, minutes, or seconds component outside its valid range. - + For more information about this API, see Supplemental API remarks for TimeSpan.TryParse. + method is like the method, except that it does not throw an exception if the conversion fails. - - The `s` parameter contains a time interval specification in the form: - - [*ws*][-]{ *d* | *d*.*hh*:*mm*[:*ss*[.*ff*]] | *hh*:*mm*[:*ss*[.*ff*]] }[*ws*] - - Elements in square brackets ([ and ]) are optional. One selection from the list of alternatives enclosed in braces ({ and }) and separated by vertical bars (|) is required. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*ws*|Optional white space.| -|-|An optional minus sign, which indicates a negative .| -|*d*|Days, ranging from 0 to 10675199.| -|.|A culture-sensitive symbol that separates days from hours. The invariant format uses a period (".") character.| -|*hh*|Hours, ranging from 0 to 23.| -|:|The culture-sensitive time separator symbol. The invariant format uses a colon (":") character.| -|*mm*|Minutes, ranging from 0 to 59.| -|*ss*|Optional seconds, ranging from 0 to 59.| -|.|A culture-sensitive symbol that separates seconds from fractions of a second. The invariant format uses a period (".") character.| -|*ff*|Optional fractional seconds, consisting of one to seven decimal digits.| - - The components of `s` must collectively specify a time interval that is greater than or equal to and less than or equal to . - - The method tries to parse `s` by using each of the culture-specific formats for the current culture. - -## Notes to callers - -In some cases, when a time interval component in the string to be parsed contains more than seven digits, parsing operations that succeed in the .NET Framework 3.5 and earlier versions may fail and throw an in the .NET Framework 4 and later versions. The following example illustrates this scenario. -:::code language="csharp" source="~/snippets/csharp/System/TimeSpan/TryParse/tryparsefailure1.cs" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/TimeSpan/TryParse/tryparsefailure1.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeSpan.TryParse/vb/tryparsefailure1.vb" id="Snippet3"::: - -## Examples - The following example uses the method to create objects from valid strings and to indicate when the parse operation has failed because the time span string is invalid. +The following example uses the method to create objects from valid strings and to indicate when the parse operation has failed because the time span string is invalid. :::code language="csharp" source="~/snippets/csharp/System/TimeSpan/TryParse/TryParse1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/TimeSpan/TryParse/TryParse1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeSpan.TryParse/vb/TryParse1.vb" id="Snippet1"::: - - ]]> - + ]]> + @@ -5829,62 +5726,16 @@ In some cases, when a time interval component in the string to be parsed contain Converts the string representation of a time interval to its equivalent by using the specified culture-specific formatting information, and returns a value that indicates whether the conversion succeeded. if was converted successfully; otherwise, . This operation returns if the parameter is or , has an invalid format, represents a time interval that is less than TimeSpan.MinValue or greater than TimeSpan.MaxValue, or has at least one days, hours, minutes, or seconds component outside its valid range. - + For more information about this API, see Supplemental API remarks for TimeSpan.TryParse. + method is like the method, except that it does not throw an exception if the conversion fails. - - The `input` parameter contains a time interval specification in the form: - - [*ws*][-]{ *d* | *d*.*hh*:*mm*[:*ss*[.*ff*]] | *hh*:*mm*[:*ss*[.*ff*]] }[*ws*] - - Elements in square brackets ([ and ]) are optional. One selection from the list of alternatives enclosed in braces ({ and }) and separated by vertical bars (|) is required. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*ws*|Optional white space.| -|-|An optional minus sign, which indicates a negative .| -|*d*|Days, ranging from 0 to 10675199.| -|.|A culture-sensitive symbol that separates days from hours. The invariant format uses a period (".") character.| -|*hh*|Hours, ranging from 0 to 23.| -|:|The culture-sensitive time separator symbol. The invariant format uses a colon (":") character.| -|*mm*|Minutes, ranging from 0 to 59.| -|*ss*|Optional seconds, ranging from 0 to 59.| -|.|A culture-sensitive symbol that separates seconds from fractions of a second. The invariant format uses a period (".") character.| -|*ff*|Optional fractional seconds, consisting of one to seven decimal digits.| - - The components of `input` must collectively specify a time interval that is greater than or equal to and less than or equal to . - - The method tries to parse `input` by using each of the culture-specific formats for the culture specified by `formatProvider`. - - The `formatProvider` parameter is an implementation that provides culture-specific information about the format of the returned string. The `formatProvider` parameter can be any of the following: - -- A object that represents the culture whose formatting conventions are to be reflected in the returned string. The object returned by the property defines the formatting of the returned string. - -- A object that defines the formatting of the returned string. - -- A custom object that implements the interface. Its method returns a object that provides formatting information. - - If `formatProvider` is `null`, the object that is associated with the current culture is used. - -## Notes to callers - -In some cases, when a time interval component in the string to be parsed contains more than seven digits, parsing operations that succeed and return `true` in the .NET Framework 3.5 and earlier versions may fail and return `false` in the.NET Framework 4 and later versions. The following example illustrates this scenario: - - :::code language="csharp" source="~/snippets/csharp/System/TimeSpan/TryParse/tryparsefailure1.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/TimeSpan/TryParse/tryparsefailure1.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeSpan.TryParse/vb/tryparsefailure1.vb" id="Snippet3"::: - -## Examples - The following example defines an array of objects, and uses each object in calls to the method to parse the elements in a string array. The example illustrates how the conventions of a specific culture influence the formatting operation. +The following example defines an array of objects, and uses each object in calls to the method to parse the elements in a string array. The example illustrates how the conventions of a specific culture influence the formatting operation. :::code language="csharp" source="~/snippets/csharp/System/TimeSpan/TryParse/tryparse2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/TimeSpan/TryParse/tryparse2.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeSpan.TryParse/vb/tryparse2.vb" id="Snippet2"::: - - ]]> - + ]]> + diff --git a/xml/System/Type.xml b/xml/System/Type.xml index bf9a44cb778..b4c058f4a2a 100644 --- a/xml/System/Type.xml +++ b/xml/System/Type.xml @@ -7831,45 +7831,17 @@ In .NET 6 and earlier versions, the method d The string containing the name of the public property to get. Searches for the public property with the specified name. An object representing the public property with the specified name, if found; otherwise, . - + For more information about this API, see Supplemental API remarks for Type.GetProperty. + | | (in Visual Basic, combine the values using ` Or `) to get it. - - If the current represents a constructed generic type, this method returns the with the type parameters replaced by the appropriate type arguments. - - If the current represents a type parameter in the definition of a generic type or generic method, this method searches the properties of the class constraint. - - Situations in which occurs include the following: - -- A type contains two indexed properties that have the same name but different numbers of parameters. To resolve the ambiguity, use an overload of the method that specifies parameter types. - -- A derived type declares a property that hides an inherited property with the same name, by using the `new` modifier (`Shadows` in Visual Basic). To resolve the ambiguity, use the method overload and add the flag to restrict the search to members that are not inherited. - -## Indexers and Default Properties - Visual Basic 2005, Visual C# 2005, and Visual C++ 2005 have simplified syntax for accessing indexed properties and allow one indexed property to be a default for its type. For example, if the variable `myList` refers to an , the syntax `myList[3]` (`myList(3)` in Visual Basic) retrieves the element with the index of 3. You can overload the property. - - In C#, this feature is called an indexer and cannot be referred to by name. By default, a C# indexer appears in metadata as an indexed property named "Item". However, a class library developer can use the attribute to change the name of the indexer in the metadata. For example, the class has an indexer named . Indexed properties created using languages other than C# can have names other than Item, as well. - - To determine whether a type has a default property, use the method to test for the attribute. If the type has , the property returns the name of the default property. - - - -## Examples - The following example retrieves the `Type` object of a user-defined class, retrieves a property of that class, and displays the property name. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Type_GetProperty1/CPP/type_getproperty1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Type/GetProperty/type_getproperty1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Type/GetProperty/type_getproperty1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Type_GetProperty1/VB/type_getproperty1.vb" id="Snippet1"::: - - Internally, this property is referred to in the metadata by the name "Item." Any attempt to get `PropertyInfo` using reflection must specify this internal name in order to correctly return the `PropertyInfo` property. - - ]]> - +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Type_GetProperty1/CPP/type_getproperty1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/Type/GetProperty/type_getproperty1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Type/GetProperty/type_getproperty1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Type_GetProperty1/VB/type_getproperty1.vb" id="Snippet1"::: + ]]> + More than one property is found with the specified name. is . @@ -7944,46 +7916,6 @@ In .NET 6 and earlier versions, the method d | | (in Visual Basic, combine the values using ` Or `) to get it. - - The following filter flags can be used to define which properties to include in the search: - -- You must specify either `BindingFlags.Instance` or `BindingFlags.Static` in order to get a return. - -- Specify `BindingFlags.Public` to include public properties in the search. - -- Specify `BindingFlags.NonPublic` to include non-public properties (that is, private, internal, and protected properties) in the search. - -- Specify `BindingFlags.FlattenHierarchy` to include `public` and `protected` static members up the hierarchy; `private` static members in inherited classes are not included. - - The following modifier flags can be used to change how the search works: - -- `BindingFlags.IgnoreCase` to ignore the case of `name`. - -- `BindingFlags.DeclaredOnly` to search only the properties declared on the , not properties that were simply inherited. - - See for more information. - - If the current represents a constructed generic type, this method returns the with the type parameters replaced by the appropriate type arguments. - - If the current represents a type parameter in the definition of a generic type or generic method, this method searches the properties of the class constraint. - - Situations in which occurs include the following: - -- A type contains two indexed properties that have the same name but different numbers of parameters. To resolve the ambiguity, use an overload of the method that specifies parameter types. - -- A derived type declares a property that hides an inherited property with the same name, using the `new` modifier (`Shadows` in Visual Basic). To resolve the ambiguity, include to restrict the search to members that are not inherited. - -## Indexers and Default Properties - Visual Basic 2005, Visual C# 2005, and Visual C++ 2005 have simplified syntax for accessing indexed properties and allow one indexed property to be a default for its type. For example, if the variable `myList` refers to an , the syntax `myList[3]` (`myList(3)` in Visual Basic) retrieves the element with the index of 3. You can overload the property. - - In C#, this feature is called an indexer and cannot be referred to by name. By default, a C# indexer appears in metadata as an indexed property named "Item". However, a class library developer can use the attribute to change the name of the indexer in the metadata. For example, the class has an indexer named . Indexed properties created using languages other than C# can have names other than Item, as well. - - To determine whether a type has a default property, use the method to test for the attribute. If the type has , the property returns the name of the default property. - - - ## Examples The following example retrieves the type of a user-defined class, retrieves a property of that class and displays the property name in accordance with the specified binding constraints. @@ -8083,15 +8015,6 @@ In .NET 6 and earlier versions, the method d If the current represents a type parameter in the definition of a generic type or generic method, this method searches the properties of the class constraint. -## Indexers and Default Properties - Visual Basic 2005, Visual C# 2005, and Visual C++ 2005 have simplified syntax for accessing indexed properties and allow one indexed property to be a default for its type. For example, if the variable `myList` refers to an , the syntax `myList[3]` (`myList(3)` in Visual Basic) retrieves the element with the index of 3. You can overload the property. - - In C#, this feature is called an indexer and cannot be referred to by name. By default, a C# indexer appears in metadata as an indexed property named "Item". However, a class library developer can use the attribute to change the name of the indexer in the metadata. For example, the class has an indexer named . Indexed properties created using languages other than C# can have names other than Item, as well. - - To determine whether a type has a default property, use the method to test for the attribute. If the type has , the property returns the name of the default property. - - - ## Examples The following example defines a class with one property and retrieves the name and type of the property. @@ -8183,15 +8106,6 @@ In .NET 6 and earlier versions, the method d If the current represents a type parameter in the definition of a generic type or generic method, this method searches the properties of the class constraint. -## Indexers and Default Properties - Visual Basic 2005, Visual C# 2005, and Visual C++ 2005 have simplified syntax for accessing indexed properties and allow one indexed property to be a default for its type. For example, if the variable `myList` refers to an , the syntax `myList[3]` (`myList(3)` in Visual Basic) retrieves the element with the index of 3. You can overload the property. - - In C#, this feature is called an indexer and cannot be referred to by name. By default, a C# indexer appears in metadata as an indexed property named "Item". However, a class library developer can use the attribute to change the name of the indexer in the metadata. For example, the class has an indexer named . Indexed properties created using languages other than C# can have names other than Item, as well. - - To determine whether a type has a default property, use the method to test for the attribute. If the type has , the property returns the name of the default property. - - - ## Examples The following example retrieves the `Type` object of a user-defined class, retrieves the property of that class, and displays the property name and type of the property as specified by the arguments passed to `GetProperty`. @@ -8299,13 +8213,6 @@ In .NET 6 and earlier versions, the method d If the current represents a type parameter in the definition of a generic type or generic method, this method searches the properties of the class constraint. -## Indexers and Default Properties - Visual Basic 2005, Visual C# 2005, and Visual C++ 2005 have simplified syntax for accessing indexed properties and allow one indexed property to be a default for its type. For example, if the variable `myList` refers to an , the syntax `myList[3]` (`myList(3)` in Visual Basic) retrieves the element with the index of 3. You can overload the property. - - In C#, this feature is called an indexer and cannot be referred to by name. By default, a C# indexer appears in metadata as an indexed property named "Item". However, a class library developer can use the attribute to change the name of the indexer in the metadata. For example, the class has an indexer named . Indexed properties created using languages other than C# can have names other than Item, as well. - - To determine whether a type has a default property, use the method to test for the attribute. If the type has , the property returns the name of the default property. - ]]> More than one property is found with the specified name and matching the specified argument types. @@ -8420,15 +8327,6 @@ In .NET 6 and earlier versions, the method d If the current represents a type parameter in the definition of a generic type or generic method, this method searches the properties of the class constraint. -## Indexers and Default Properties - Visual Basic 2005, Visual C# 2005, and Visual C++ 2005 have simplified syntax for accessing indexed properties and allow one indexed property to be a default for its type. For example, if the variable `myList` refers to an , the syntax `myList[3]` (`myList(3)` in Visual Basic) retrieves the element with the index of 3. You can overload the property. - - In C#, this feature is called an indexer and cannot be referred to by name. By default, a C# indexer appears in metadata as an indexed property named "Item". However, a class library developer can use the attribute to change the name of the indexer in the metadata. For example, the class has an indexer named . Indexed properties created using languages other than C# can have names other than Item, as well. - - To determine whether a type has a default property, use the method to test for the attribute. If the type has , the property returns the name of the default property. - - - ## Examples The following example obtains a `Type` object corresponding to `MyPropertyClass`, and the indexed property of this class is retrieved using the arguments passed to the `GetProperty` method. @@ -8556,62 +8454,7 @@ In .NET 6 and earlier versions, the method d An array of objects representing the attributes associated with the corresponding element in the array. The default binder does not process this parameter. Searches for the specified property whose parameters match the specified argument types and modifiers, using the specified binding constraints. An object representing the property that matches the specified requirements, if found; otherwise, . - - | | (in Visual Basic, combine the values using ` Or `) to get it. - - Although the default binder does not process (the `modifiers` parameter), you can use the abstract class to write a custom binder that does process `modifiers`. `ParameterModifier` is only used when calling through COM interop, and only parameters that are passed by reference are handled. - - The following table shows what members of a base class are returned by the `Get` methods when reflecting on a type. - -|Member Type|Static|Non-Static| -|-----------------|------------|-----------------| -|Constructor|No|No| -|Field|No|Yes. A field is always hide-by-name-and-signature.| -|Event|Not applicable|The common type system rule is that the inheritance is the same as that of the methods that implement the property. Reflection treats properties as hide-by-name-and-signature. See note 2 below.| -|Method|No|Yes. A method (both virtual and non-virtual) can be hide-by-name or hide-by-name-and-signature.| -|Nested Type|No|No| -|Property|Not applicable|The common type system rule is that the inheritance is the same as that of the methods that implement the property. Reflection treats properties as hide-by-name-and-signature. See note 2 below.| - -1. Hide-by-name-and-signature considers all of the parts of the signature, including custom modifiers, return types, parameter types, sentinels, and unmanaged calling conventions. This is a binary comparison. - -2. For reflection, properties and events are hide-by-name-and-signature. If you have a property with both a get and a set accessor in the base class, but the derived class has only a get accessor, the derived class property hides the base class property, and you will not be able to access the setter on the base class. - -3. Custom attributes are not part of the common type system. - - The following filter flags can be used to define which properties to include in the search: - -- You must specify either `BindingFlags.Instance` or `BindingFlags.Static` in order to get a return. - -- Specify `BindingFlags.Public` to include public properties in the search. - -- Specify `BindingFlags.NonPublic` to include non-public properties (that is, private, internal, and protected properties) in the search. - -- Specify `BindingFlags.FlattenHierarchy` to include `public` and `protected` static members up the hierarchy; `private` static members in inherited classes are not included. - - The following modifier flags can be used to change how the search works: - -- `BindingFlags.IgnoreCase` to ignore the case of `name`. - -- `BindingFlags.DeclaredOnly` to search only the properties declared on the , not properties that were simply inherited. - - See for more information. - - If the current represents a constructed generic type, this method returns the with the type parameters replaced by the appropriate type arguments. - - If the current represents a type parameter in the definition of a generic type or generic method, this method searches the properties of the class constraint. - -## Indexers and Default Properties - Visual Basic 2005, Visual C# 2005, and Visual C++ 2005 have simplified syntax for accessing indexed properties and allow one indexed property to be a default for its type. For example, if the variable `myList` refers to an , the syntax `myList[3]` (`myList(3)` in Visual Basic) retrieves the element with the index of 3. You can overload the property. - - In C#, this feature is called an indexer and cannot be referred to by name. By default, a C# indexer appears in metadata as an indexed property named "Item". However, a class library developer can use the attribute to change the name of the indexer in the metadata. For example, the class has an indexer named . Indexed properties created using languages other than C# can have names other than Item, as well. - - To determine whether a type has a default property, use the method to test for the attribute. If the type has , the property returns the name of the default property. - - ]]> - + For more information about this API, see Supplemental API remarks for Type.GetProperty. More than one property is found with the specified name and matching the specified binding constraints. is . @@ -9882,145 +9725,7 @@ Type.GetType("System.Collections.Generic.Dictionary`2[System.String,[MyType,MyAs to perform a case-insensitive search for , to perform a case-sensitive search for . Gets the type with the specified name, specifying whether to perform a case-sensitive search and whether to throw an exception if the type is not found, and optionally providing custom methods to resolve the assembly and the type. The type with the specified name. If the type is not found, the parameter specifies whether is returned or an exception is thrown. In some cases, an exception is thrown regardless of the value of . See the Exceptions section. - - and ) to replace the default implementation of the method with more flexible implementations. By providing your own methods that resolve type names and the names of the assemblies that contain them, you can do the following: - -- Control which version of an assembly a type is loaded from. - -- Provide another place to look for a type name that does not include an assembly name. - -- Load assemblies using partial assembly names. - -- Return subclasses of that are not created by the common language runtime (CLR). - - For example, in version-tolerant serialization this method enables you to search for a "best fit" assembly by using a partial name. Other overloads of the method require an assembly-qualified type name, which includes the version number. - - Alternate implementations of the type system may need to return subclasses of that are not created by the CLR; all types that are returned by other overloads of the method are runtime types. - - -## Usage Notes - This method overload and its associated overloads parse `typeName` into the name of a type and the name of an assembly, and then resolve the names. Resolution of the assembly name occurs before resolution of the type name, because a type name must be resolved in the context of an assembly. - -> [!NOTE] -> If you are unfamiliar with the concept of assembly-qualified type names, see the property. - - If `typeName` is not an assembly-qualified name, assembly resolution is skipped. Unqualified type names can be resolved in the context of mscorlib.dll/System.Private.CoreLib.dll or the currently executing assembly, or you can optionally provide an assembly in the `typeResolver` parameter. The effects of including or omitting the assembly name for different kinds of name resolution are displayed as a table in the [Mixed Name Resolution](#mixed_name_resolution) section. - - General usage notes: - -- Do not pass methods to `assemblyResolver` or `typeResolver` if they come from unknown or untrusted callers. Use only methods that you provide or that you are familiar with. - - > [!CAUTION] - > Using methods from unknown or untrusted callers could result in elevation of privilege for malicious code. - -- If you omit the `assemblyResolver` and/or `typeResolver` parameters, the value of the `throwOnError` parameter is passed to the methods that perform the default resolution. - -- If `throwOnError` is `true`, this method throws a when `typeResolver` returns `null`, and a when `assemblyResolver` returns `null`. - -- This method does not catch exceptions thrown by `assemblyResolver` and `typeResolver`. You are responsible for any exceptions that are thrown by the resolver methods. - - -### Resolving Assemblies - The `assemblyResolver` method receives an object, which is produced by parsing the string assembly name that is included in `typeName`. If `typeName` does not contain an assembly name, `assemblyResolver` is not called and `null` is passed to `typeResolver`. - - If `assemblyResolver` is not supplied, standard assembly probing is used to locate the assembly. If `assemblyResolver` is provided, the method does not do standard probing; in that case you must ensure that your `assemblyResolver` can handle all the assemblies you pass to it. - - The `assemblyResolver` method should return `null` if the assembly cannot be resolved. If `assemblyResolver` returns `null`, `typeResolver` is not called and no further processing occurs; additionally, if `throwOnError` is `true`, a is thrown. - - If the that is passed to `assemblyResolver` is a partial name, one or more of its parts are `null`. For example, if it has no version, the property is `null`. If the property, the property, and the method all return `null`, then only the simple name of the assembly was supplied. The `assemblyResolver` method can use or ignore all parts of the assembly name. - - The effects of different assembly resolution options are displayed as a table in the [Mixed Name Resolution](#mixed_name_resolution) section, for simple and assembly-qualified type names. - - -### Resolving Types - If `typeName` does not specify an assembly name, `typeResolver` is always called. If `typeName` specifies an assembly name, `typeResolver` is called only when the assembly name is successfully resolved. If `assemblyResolver` or standard assembly probing returns `null`, `typeResolver` is not called. - - The `typeResolver` method receives three arguments: - -- The assembly to search or `null` if `typeName` does not contain an assembly name. - -- The simple name of the type. In the case of a nested type, this is the outermost containing type. In the case of a generic type, this is the simple name of the generic type. - -- A Boolean value that is `true` if the case of type names is to be ignored. - - The implementation determines the way these arguments are used. The `typeResolver` method should return `null` if it cannot resolve the type. If `typeResolver` returns `null` and `throwOnError` is `true`, this overload of throws a . - - The effects of different type resolution options are displayed as a table in the [Mixed Name Resolution](#mixed_name_resolution) section, for simple and assembly-qualified type names. - -#### Resolving Nested Types - If `typeName` is a nested type, only the name of the outermost containing type is passed to `typeResolver`. When `typeResolver` returns this type, the method is called recursively until the innermost nested type has been resolved. - -#### Resolving Generic Types - The is called recursively to resolve generic types: First to resolve the generic type itself, and then to resolve its type arguments. If a type argument is generic, is called recursively to resolve its type arguments, and so on. - - The combination of `assemblyResolver` and `typeResolver` that you provide must be capable of resolving all levels of this recursion. For example, suppose you supply an `assemblyResolver` that controls the loading of `MyAssembly`. Suppose you want to resolve the generic type `Dictionary` (`Dictionary(Of String, MyType)` in Visual Basic). You might pass the following generic type name: - -``` -"System.Collections.Generic.Dictionary`2[System.String,[MyNamespace.MyType, MyAssembly]]" -``` - - Notice that `MyType` is the only assembly-qualified type argument. The names of the and classes are not assembly-qualified. Your `typeResolver` must be able handle either an assembly or `null`, because it will receive `null` for and . It can handle that case by calling an overload of the method that takes a string, because both of the unqualified type names are in mscorlib.dll/System.Private.CoreLib.dll: - - :::code language="csharp" source="~/snippets/csharp/System/Type/GetType/source.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Type/GetType/source.fs" id="Snippet1"::: - - The `assemblyResolver` method is not called for the dictionary type and the string type, because those type names are not assembly-qualified. - - Now suppose that instead of `System.String`, the first generic argument type is `YourType`, from `YourAssembly`: - -``` -"System.Collections.Generic.Dictionary`2[[YourNamespace.YourType, YourAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null], [MyNamespace.MyType, MyAssembly]]" -``` - - Because this assembly is neither mscorlib.dll/System.Private.CoreLib.dll nor the currently executing assembly, you cannot resolve `YourType` without an assembly-qualified name. Because your `assemblyResolve` will be called recursively, it must be able to handle this case. Instead of returning `null` for assemblies other than `MyAssembly`, it now performs an assembly load using the supplied object. - - :::code language="csharp" source="~/snippets/csharp/System/Type/GetType/source.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Type/GetType/source.fs" id="Snippet2"::: - - Back to [Usage Notes](#usage_notes). - -#### Resolving Type Names with Special Characters - Certain characters have special meanings in assembly-qualified names. If a simple type name contains these characters, the characters cause parsing errors when the simple name is part of an assembly-qualified name. To avoid the parsing errors, you must escape the special characters with a backslash before you can pass the assembly-qualified name to the method. For example, if a type is named `Strange]Type`, the escape character must be added ahead of the square bracket as follows: `Strange\]Type`. - -> [!NOTE] -> Names with such special characters cannot be created in Visual Basic or C#, but can be created by using Microsoft intermediate language (MSIL) or by emitting dynamic assemblies. - - The following table shows the special characters for type names. - -|Character|Meaning| -|---------------|-------------| -|`,` (comma)|Delimiter for assembly-qualified names.| -|`[]` (square brackets)|As a suffix pair, indicates an array type; as a delimiter pair, encloses generic argument lists and assembly-qualified names.| -|`&` (ampersand)|As a suffix, indicates that a type is a reference type.| -|`*` (asterisk)|As a suffix, indicates that a type is a pointer type.| -|`+` (plus)|Delimiter for nested types.| -|`\` (backslash)|Escape character.| - - Properties such as return correctly escaped strings. You must pass correctly escaped strings to the method. In turn, the method passes correctly escaped names to `typeResolver` and to the default type resolution methods. If you need to compare a name to an unescaped name in `typeResolver`, you must remove the escape characters. - - Back to [Usage Notes](#usage_notes). - - -## Mixed Name Resolution - The following table summarizes the interactions between `assemblyResolver`, `typeResolver`, and default name resolution, for all combinations of type name and assembly name in `typeName`: - -|Contents of type name|Assembly resolver method|Type resolver method|Result| -|---------------------------|------------------------------|--------------------------|------------| -|type, assembly|null|null|Equivalent to calling the method overload.| -|type, assembly|provided|null|`assemblyResolver` returns the assembly or returns `null` if it cannot resolve the assembly. If the assembly is resolved, the method overload is used to load the type from the assembly; otherwise, there is no attempt to resolve the type.| -|type, assembly|null|provided|Equivalent to converting the assembly name to an object and calling the method overload to get the assembly. If the assembly is resolved, it is passed to `typeResolver`; otherwise, `typeResolver` is not called and there is no further attempt to resolve the type.| -|type, assembly|provided|provided|`assemblyResolver` returns the assembly or returns `null` if it cannot resolve the assembly. If the assembly is resolved, it is passed to `typeResolver`; otherwise, `typeResolver` is not called and there is no further attempt to resolve the type.| -|type|null, provided|null|Equivalent to calling the method overload. Because the assembly name is not provided, only mscorlib.dll/System.Private.CoreLib.dll and the currently executing assembly are searched. If `assemblyResolver` is provided, it is ignored.| -|type|null, provided|provided|`typeResolver` is called, and `null` is passed for the assembly. `typeResolver` can provide a type from any assembly, including assemblies it loads for the purpose. If `assemblyResolver` is provided, it is ignored.| -|assembly|null, provided|null, provided|A is thrown, because the assembly name is parsed as if it were an assembly-qualified type name. This results in an invalid assembly name.| - - Back to: [Usage Notes](#usage_notes), [Resolving Assemblies](#resolving_assemblies), [Resolving Types](#resolving_types). - - ]]> - + For more information about this API, see Supplemental API remarks for Type.GetType. is . A class initializer is invoked and throws an exception. @@ -16326,80 +16031,17 @@ If the value of this property is `true` for an array type, it can be used to cre An array of types to be substituted for the type parameters of the current generic type. Substitutes the elements of an array of types for the type parameters of the current generic type definition and returns a object representing the resulting constructed type. A representing the constructed type formed by substituting the elements of for the type parameters of the current generic type. - + For more information about this API, see Supplemental API remarks for Type.MakeGenericType. + method allows you to write code that assigns specific types to the type parameters of a generic type definition, thus creating a object that represents a particular constructed type. You can use this object to create run-time instances of the constructed type. - - Types constructed with can be open, that is, some of their type arguments can be type parameters of enclosing generic methods or types. You might use such open constructed types when you emit dynamic assemblies. For example, consider the classes `Base` and `Derived` in the following code. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.type.makegenerictype/cpp/remarks.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Type/MakeGenericType/remarks.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Type/MakeGenericType/remarks.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.type.makegenerictype/vb/remarks.vb" id="Snippet1"::: - - To generate `Derived` in a dynamic assembly, it is necessary to construct its base type. To do this, call the method on a object representing the class `Base`, using the generic type arguments and the type parameter `V` from `Derived`. Because types and generic type parameters are both represented by objects, an array containing both can be passed to the method. - -> [!NOTE] -> A constructed type such as `Base` is useful when emitting code, but you cannot call the method on this type because it is not a generic type definition. To create a closed constructed type that can be instantiated, first call the method to get a object representing the generic type definition and then call with the desired type arguments. - - The object returned by is the same as the obtained by calling the method of the resulting constructed type, or the method of any constructed type that was created from the same generic type definition using the same type arguments. - -> [!NOTE] -> An array of generic types is not itself a generic type. You cannot call on an array type such as `C[]` (`Dim ac() As C(Of T)` in Visual Basic). To construct a closed generic type from `C[]`, call to obtain the generic type definition `C`; call on the generic type definition to create the constructed type; and finally call the method on the constructed type to create the array type. The same is true of pointer types and `ref` types (`ByRef` in Visual Basic). - - For a list of the invariant conditions for terms used in generic reflection, see the property remarks. - -## Nested Types - If a generic type is defined using C#, C++, or Visual Basic, then its nested types are all generic. This is true even if the nested types have no type parameters of their own, because all three languages include the type parameters of enclosing types in the type parameter lists of nested types. Consider the following classes: - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.type.makegenerictype/cpp/remarks.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System/Type/MakeGenericType/remarks.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.type.makegenerictype/vb/remarks.vb" id="Snippet2"::: - - The type parameter list of the nested class `Inner` has two type parameters, `T` and `U`, the first of which is the type parameter of its enclosing class. Similarly, the type parameter list of the nested class `Innermost1` has three type parameters, `T`, `U`, and `V`, with `T` and `U` coming from its enclosing classes. The nested class `Innermost2` has two type parameters, `T` and `U`, which come from its enclosing classes. - - If the parameter list of the enclosing type has more than one type parameter, all the type parameters in order are included in the type parameter list of the nested type. - - To construct a generic type from the generic type definition for a nested type, call the method with the array formed by concatenating the type argument arrays of all the enclosing types, beginning with the outermost generic type, and ending with the type argument array of the nested type itself, if it has type parameters of its own. To create an instance of `Innermost1`, call the method with an array containing three types, to be assigned to T, U, and V. To create an instance of `Innermost2`, call the method with an array containing two types, to be assigned to T and U. - - The languages propagate the type parameters of enclosing types in this fashion so you can use the type parameters of an enclosing type to define fields of nested types. Otherwise, the type parameters would not be in scope within the bodies of the nested types. It is possible to define nested types without propagating the type parameters of enclosing types, by emitting code in dynamic assemblies or by using the [Ilasm.exe (IL Assembler)](/dotnet/framework/tools/ilasm-exe-il-assembler). Consider the following code for the MSIL assembler: - -``` -.class public Outer { - .class nested public Inner { - .class nested public Innermost { - } - } -} -``` - - In this example, it is not possible to define a field of type `T` or `U` in class `Innermost`, because those type parameters are not in scope. The following assembler code defines nested classes that behave the way they would if defined in C++, Visual Basic, and C#: - -``` -.class public Outer { - .class nested public Inner { - .class nested public Innermost { - } - } -} -``` - - You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine nested classes defined in the high-level languages and observe this naming scheme. - - - -## Examples - The following example uses the method to create a constructed type from the generic type definition for the type. The constructed type represents a of `Test` objects with string keys. +The following example uses the method to create a constructed type from the generic type definition for the type. The constructed type represents a of `Test` objects with string keys. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Type.BindGenericParameters/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Type/MakeGenericType/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Type/MakeGenericType/source.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Type.BindGenericParameters/VB/source.vb" id="Snippet1"::: - - ]]> - + ]]> + The current type does not represent a generic type definition. That is, returns . is . diff --git a/xml/System/UnhandledExceptionEventArgs.xml b/xml/System/UnhandledExceptionEventArgs.xml index d17e46b83b5..766f5e224ae 100644 --- a/xml/System/UnhandledExceptionEventArgs.xml +++ b/xml/System/UnhandledExceptionEventArgs.xml @@ -59,13 +59,13 @@ Provides data for the event that is raised when there is an exception that is not handled in any application domain. - provides access to the exception object and a flag indicating whether the common language runtime is terminating. The is one of the parameters passed into for the event. - - For more information about event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - + provides access to the exception object and a flag indicating whether the common language runtime is terminating. The is one of the parameters passed into for the event. + + For more information about event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -157,25 +157,25 @@ Gets the unhandled exception object. The unhandled exception object. - rather than one derived from . Although the Common Language Specification requires that all exception types derive from , it is possible for methods to throw exceptions with objects not derived from . You can do the following to work with this exception: - -- Apply the attribute with a value of `true` to the assembly that contains the event handler. This wraps all exceptions not derived from the class in a object. You can then safely cast (in C#) or convert (in Visual Basic) the object returned by this property to an object, and retrieve the original exception object from the property. Note that some compilers, such as the C# and Visual Basic compilers, automatically apply this attribute. - -- Cast the object returned by this property to an object. - - - -## Examples - The following example demonstrates the event. It defines an event handler, `MyHandler`, that is invoked whenever an unhandled exception is thrown in the default application domain. It then throws two exceptions. The first is handled by a **try/catch** block. The second is unhandled and invokes the `MyHandle` routine before the application terminates. - + rather than one derived from . Although the Common Language Specification requires that all exception types derive from , it is possible for methods to throw exceptions with objects not derived from . You can do the following to work with this exception: + +- Apply the attribute with a value of `true` to the assembly that contains the event handler. This wraps all exceptions not derived from the class in a object. You can then safely cast (in C#) or convert (in Visual Basic) the object returned by this property to an object, and retrieve the original exception object from the property. Note that some compilers, such as the C# and Visual Basic compilers, automatically apply this attribute. + +- Cast the object returned by this property to an object. + + + +## Examples + The following example demonstrates the event. It defines an event handler, `MyHandler`, that is invoked whenever an unhandled exception is thrown in the default application domain. It then throws two exceptions. The first is handled by a **try/catch** block. The second is unhandled and invokes the `MyHandle` routine before the application terminates. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AppDomain_UnhandledException/CPP/unhandledexception.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/AppDomain/UnhandledException/unhandledexception.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/AppDomain/UnhandledException/unhandledexception.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AppDomain_UnhandledException/VB/unhandledexception.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AppDomain_UnhandledException/VB/unhandledexception.vb" id="Snippet1"::: + ]]> @@ -222,20 +222,10 @@ System.Boolean - Indicates whether the common language runtime is terminating. + Gets a value that indicates whether the common language runtime is terminating. if the runtime is terminating; otherwise, . - - - + This property returns `true` for most unhandled exceptions. The reason is that most unhandled exceptions in threads, including thread pool threads, are allowed to proceed naturally, which normally results in termination of the application. For more information, including a list of cases in which the runtime does not terminate, see Exceptions in Managed Threads. diff --git a/xml/System/ValueType.xml b/xml/System/ValueType.xml index e2457eba728..6db3dfc7816 100644 --- a/xml/System/ValueType.xml +++ b/xml/System/ValueType.xml @@ -64,27 +64,27 @@ Provides the base class for value types. - overrides the virtual methods from with more appropriate implementations for value types. See also , which inherits from . - - Data types are separated into value types and reference types. Value types are either stack-allocated or allocated inline in a structure. Reference types are heap-allocated. Both reference and value types are derived from the ultimate base class . In cases where it is necessary for a value type to behave like an object, a wrapper that makes the value type look like a reference object is allocated on the heap, and the value type's value is copied into it. The wrapper is marked so the system knows that it contains a value type. This process is known as boxing, and the reverse process is known as unboxing. Boxing and unboxing allow any type to be treated as an object. - - Although is the implicit base class for value types, you cannot create a class that inherits from directly. Instead, individual compilers provide a language keyword or construct (such as `struct` in C# and `Structure`…`End Structure` in Visual Basic) to support the creation of value types. - - Aside from serving as the base class for value types in the .NET Framework, the structure is generally not used directly in code. However, it can be used as a parameter in method calls to restrict possible arguments to value types instead of all objects, or to permit a method to handle a number of different value types. The following example illustrates how prevents reference types from being passed to methods. It defines a class named `Utility` that contains four methods: `IsNumeric`, which indicates whether its argument is a number; `IsInteger`, which indicates whether its argument is an integer; `IsFloat`, which indicates whether its argument is a floating-point number; and `Compare`, which indicates the relationship between two numeric values. In each case, the method parameters are of type , and reference types are prevented from being passed to the methods. - + overrides the virtual methods from with more appropriate implementations for value types. See also , which inherits from . + + Data types are separated into value types and reference types. Value types are either stack-allocated or allocated inline in a structure. Reference types are heap-allocated. Both reference and value types are derived from the ultimate base class . In cases where it is necessary for a value type to behave like an object, a wrapper that makes the value type look like a reference object is allocated on the heap, and the value type's value is copied into it. The wrapper is marked so the system knows that it contains a value type. This process is known as boxing, and the reverse process is known as unboxing. Boxing and unboxing allow any type to be treated as an object. + + Although is the implicit base class for value types, you cannot create a class that inherits from directly. Instead, individual compilers provide a language keyword or construct (such as `struct` in C# and `Structure`…`End Structure` in Visual Basic) to support the creation of value types. + + Aside from serving as the base class for value types in the .NET Framework, the structure is generally not used directly in code. However, it can be used as a parameter in method calls to restrict possible arguments to value types instead of all objects, or to permit a method to handle a number of different value types. The following example illustrates how prevents reference types from being passed to methods. It defines a class named `Utility` that contains four methods: `IsNumeric`, which indicates whether its argument is a number; `IsInteger`, which indicates whether its argument is an integer; `IsFloat`, which indicates whether its argument is a floating-point number; and `Compare`, which indicates the relationship between two numeric values. In each case, the method parameters are of type , and reference types are prevented from being passed to the methods. + :::code language="csharp" source="~/snippets/csharp/System/ValueType/Overview/example1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/ValueType/Overview/example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.valuetype.structure/vb/example1.vb" id="Snippet1"::: - - The following example illustrates calls to the methods of the `Utility` class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.valuetype.structure/vb/example1.vb" id="Snippet1"::: + + The following example illustrates calls to the methods of the `Utility` class. + :::code language="csharp" source="~/snippets/csharp/System/ValueType/Overview/example1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/ValueType/Overview/example1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.valuetype.structure/vb/example1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.valuetype.structure/vb/example1.vb" id="Snippet2"::: + ]]> @@ -190,31 +190,29 @@ if and this instance are the same type and represent the same value; otherwise, . - method overrides and provides the default implementation of value equality for all value types in the .NET Framework. - - The default implementation calls on each field of the current instance and `obj` and returns `true` if all fields are equal. - + method overrides and provides the default implementation of value equality for all value types in .NET. + +The default implementation calls on each field of the current instance and `obj` and returns `true` if all fields are equal. + > [!TIP] -> Particularly if your value type contains fields that are reference types, you should override the method. This can improve performance and enable you to more closely represent the meaning of equality for the type. - -## Notes for the Windows Runtime - When you call the method on a Windows Runtime structure, it provides the default behavior for value types that don't override . This is part of the support that the .NET Framework provides for the Windows Runtime (see [.NET Framework Support for Windows Store Apps and Windows Runtime](/dotnet/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime)). Windows Runtime structures can't override , even if they're written with C# or Visual Basic, because they can't have methods. (In addition, structures in the Windows Runtime itself don't inherit .) However, they appear to have , , and methods when you use them in your C# or Visual Basic code, and the .NET Framework provides the default behavior for these methods. - - - -## Examples - The following example demonstrates how the method can be overridden by a derived value type. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ValueType.Equals Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/ValueType/Equals/source.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/ValueType/Equals/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ValueType.Equals Example/VB/source.vb" id="Snippet1"::: - - ]]> +> Particularly if your value type contains fields that are reference types, you should override the method. This can improve performance and enable you to more closely represent the meaning of equality for the type. + +## Notes for the Windows Runtime + +When you call the method on a Windows Runtime structure, it provides the default behavior for value types that don't override . This is part of the support that .NET provides for the Windows Runtime (see [.NET Support for Windows Store Apps and Windows Runtime](/dotnet/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime)). Windows Runtime structures can't override , even if they're written with C# or Visual Basic, because they can't have methods. (In addition, structures in the Windows Runtime itself don't inherit .) However, they appear to have , , and methods when you use them in your C# or Visual Basic code, and .NET provides the default behavior for these methods. + ]]> + + method can be overridden by a derived value type. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ValueType.Equals Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/ValueType/Equals/source.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/ValueType/Equals/source.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ValueType.Equals Example/VB/source.vb" id="Snippet1"::: + ]]> + @@ -265,28 +263,26 @@ Returns the hash code for this instance. A 32-bit signed integer that is the hash code for this instance. - method applies to types derived from . One or more fields of the derived type is used to calculate the return value. If you call the derived type's `GetHashCode` method, the return value is not likely to be suitable for use as a key in a hash table. Additionally, if the value of one or more of those fields changes, the return value might become unsuitable for use as a key in a hash table. In either case, consider writing your own implementation of the method that more closely represents the concept of a hash code for the type. - - For more information, see , and . - -## Notes for the Windows Runtime - When you call the method on a Windows Runtime structure, it provides the default behavior for value types that don't override . This is part of the support that the .NET Framework provides for the Windows Runtime (see [.NET Framework Support for Windows Store Apps and Windows Runtime](/dotnet/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime)). Windows Runtime structures can't override , even if they're written with C# or Visual Basic, because they can't have methods. (In addition, structures in the Windows Runtime itself don't inherit .) However, they appear to have , , and methods when you use them in your C# or Visual Basic code, and the .NET Framework provides the default behavior for these methods. - - - -## Examples - The following example demonstrates how the method can be overridden by a derived value type. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ValueType.Equals Example/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/ValueType/Equals/source.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/ValueType/Equals/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ValueType.Equals Example/VB/source.vb" id="Snippet1"::: - - ]]> + method applies to types derived from . One or more fields of the derived type is used to calculate the return value. If you call the derived type's `GetHashCode` method, the return value is not likely to be suitable for use as a key in a hash table. Additionally, if the value of one or more of those fields changes, the return value might become unsuitable for use as a key in a hash table. In either case, consider writing your own implementation of the method that more closely represents the concept of a hash code for the type. + +For more information, see , and . + +## Notes for the Windows Runtime + +When you call the method on a Windows Runtime structure, it provides the default behavior for value types that don't override . This is part of the support that .NET provides for the Windows Runtime (see [.NET Support for Windows Store Apps and Windows Runtime](/dotnet/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime)). Windows Runtime structures can't override , even if they're written with C# or Visual Basic, because they can't have methods. (In addition, structures in the Windows Runtime itself don't inherit .) However, they appear to have , , and methods when you use them in your C# or Visual Basic code, and .NET provides the default behavior for these methods. + ]]> + + method can be overridden by a derived value type. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ValueType.Equals Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/ValueType/Equals/source.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/ValueType/Equals/source.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ValueType.Equals Example/VB/source.vb" id="Snippet1"::: + ]]> + @@ -332,22 +328,24 @@ Returns the fully qualified type name of this instance. The fully qualified type name. - method overrides the method and provides the default implementation of the `ToString` method for value types. (Value types are types defined by the `struct` keyword in C#, and by the `Structure`...`End Structure` construct in Visual Basic.) Functionally, however, the implementation is that same as that of : the method returns the fully qualified type name. - - Value types defined by the `struct` keyword in C# and the `Structure`...`End Structure` construct in Visual Basic typically override the method to provide a more meaningful string representation of the value type. The following example illustrates the difference. It defines two value types, `EmployeeA` and `EmployeeB`, creates an instance of each, and calls its `ToString` method. Because the `EmployeeA` structure does not override the method, it displays only the fully qualified type name. The `EmployeeB.ToString` method, on the other hand, provides meaningful information about the object. - + method overrides the method and provides the default implementation of the `ToString` method for value types. (Value types are types defined by the `struct` keyword in C#, and by the `Structure`...`End Structure` construct in Visual Basic.) Functionally, however, the implementation is that same as that of : the method returns the fully qualified type name. + + Value types defined by the `struct` keyword in C# and the `Structure`...`End Structure` construct in Visual Basic typically override the method to provide a more meaningful string representation of the value type. The following example illustrates the difference. It defines two value types, `EmployeeA` and `EmployeeB`, creates an instance of each, and calls its `ToString` method. Because the `EmployeeA` structure does not override the method, it displays only the fully qualified type name. The `EmployeeB.ToString` method, on the other hand, provides meaningful information about the object. + :::code language="csharp" source="~/snippets/csharp/System/ValueType/ToString/ToString2.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/ValueType/ToString/ToString2.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.ValueType.ToString/vb/ToString2.vb" id="Snippet1"::: - Note that, although enumeration types are also value types, they derive from the class, which overrides . - -## Notes for the Windows Runtime - When you call the method on a Windows Runtime structure, it provides the default behavior for value types that don't override . This is part of the support that the .NET Framework provides for the Windows Runtime (see [.NET Framework Support for Windows Store Apps and Windows Runtime](/dotnet/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime)). Windows Runtime structures can't override , even if they're written with C# or Visual Basic, because they can't have methods. (In addition, structures in the Windows Runtime itself don't inherit .) However, they appear to have , , and methods when you use them in your C# or Visual Basic code, and the .NET Framework provides the default behavior for these methods. - + Note that, although enumeration types are also value types, they derive from the class, which overrides . + +## Notes for the Windows Runtime + + When you call the method on a Windows Runtime structure, it provides the default behavior for value types that don't override . This is part of the support that .NET provides for the Windows Runtime (see [.NET Support for Windows Store Apps and Windows Runtime](/dotnet/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime)). Windows Runtime structures can't override , even if they're written with C# or Visual Basic, because they can't have methods. (In addition, structures in the Windows Runtime itself don't inherit .) However, they appear to have , , and methods when you use them in your C# or Visual Basic code, and .NET provides the default behavior for these methods. + ]]>