Reinstate supplemental remarks (various)

snippets/cpp/System/String/.ctor/sbyte_ctor1.cpp

@@ -0,0 +1,20 @@
+// SByte_Ctor1.cpp : Defines the entry point for the console application.
+//
+
+//#include "stdafx.h"
+
+// <Snippet4>
+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
+// </Snippet4>

snippets/csharp/System.Numerics/BigInteger/Overview/BigInteger_Examples.cs

@@ -0,0 +1,86 @@
+using System;
+using System.Numerics;
+
+public class Example
+{
+   public static void Main()
+   {
+      // <Snippet1>
+      BigInteger bigIntFromDouble = new BigInteger(179032.6541);
+      Console.WriteLine(bigIntFromDouble);
+      BigInteger bigIntFromInt64 = new BigInteger(934157136952);
+      Console.WriteLine(bigIntFromInt64);
+      // The example displays the following output:
+      //   179032
+      //   934157136952		
+      // </Snippet1>
+
+      Console.WriteLine();
+
+      // <Snippet2>
+      long longValue = 6315489358112;
+      BigInteger assignedFromLong = longValue;
+      Console.WriteLine(assignedFromLong);
+      // The example displays the following output:
+      //   6315489358112
+      // </Snippet2>
+
+      Console.WriteLine();
+      Console.WriteLine("Casting:");
+      // <Snippet3>
+      BigInteger assignedFromDouble = (BigInteger) 179032.6541;
+      Console.WriteLine(assignedFromDouble);
+      BigInteger assignedFromDecimal = (BigInteger) 64312.65m;
+      Console.WriteLine(assignedFromDecimal);
+      // The example displays the following output:
+      //   179032
+      //   64312
+      // </Snippet3>
+
+      Console.WriteLine();
+
+      // <Snippet4>
+      byte[] byteArray = { 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0};
+      BigInteger newBigInt = new BigInteger(byteArray);
+      Console.WriteLine($"The value of newBigInt is {newBigInt} (or 0x{newBigInt:x}).");
+      // The example displays the following output:
+      //   The value of newBigInt is 4759477275222530853130 (or 0x102030405060708090a).
+      // </Snippet4>
+
+      Console.WriteLine();
+
+      // <Snippet5>
+      string positiveString = "91389681247993671255432112000000";
+      string negativeString = "-90315837410896312071002088037140000";
+      BigInteger posBigInt = 0;
+      BigInteger negBigInt = 0;
+
+      try {
+         posBigInt = BigInteger.Parse(positiveString);
+         Console.WriteLine(posBigInt);
+      }
+      catch (FormatException)
+      {
+         Console.WriteLine($"Unable to convert the string '{positiveString}' to a BigInteger value.");
+      }
+
+      if (BigInteger.TryParse(negativeString, out negBigInt))
+        Console.WriteLine(negBigInt);
+      else
+         Console.WriteLine($"Unable to convert the string '{negativeString}' to a BigInteger value.");
+
+      // The example displays the following output:
+      //   9.1389681247993671255432112E+31
+      //   -9.0315837410896312071002088037E+34
+      // </Snippet5>
+
+      Console.WriteLine();
+
+     // <Snippet6>
+      BigInteger number = BigInteger.Pow(UInt64.MaxValue, 3);
+      Console.WriteLine(number);
+      // The example displays the following output:
+      //    6277101735386680762814942322444851025767571854389858533375
+      // </Snippet6>
+   }
+}

snippets/csharp/System.Numerics/BigInteger/Overview/ByteAndHex_Examples.cs

@@ -0,0 +1,152 @@
+using System;
+using System.Globalization;
+using System.Numerics;
+
+public class ByteHexExample
+{
+    public static void Main()
+    {
+        RoundtripBigInteger();
+        Console.WriteLine();
+        RoundtripInt16();
+        Console.WriteLine();
+        HandleSignsInByteArray();
+        Console.WriteLine();
+        RoundtripAmbiguous();
+        Console.WriteLine();
+        RoundtripWithHex();
+    }
+
+    private static void RoundtripBigInteger()
+    {
+        Console.WriteLine("Round-trip bytes");
+
+        // <Snippet1>
+        BigInteger number = BigInteger.Pow(Int64.MaxValue, 2);
+        Console.WriteLine(number);
+
+        // Write the BigInteger value to a byte array.
+        byte[] bytes = number.ToByteArray();
+
+        // Display the byte array.
+        foreach (byte byteValue in bytes)
+            Console.Write("0x{0:X2} ", byteValue);
+        Console.WriteLine();
+
+        // Restore the BigInteger value from a Byte array.
+        BigInteger newNumber = new BigInteger(bytes);
+        Console.WriteLine(newNumber);
+        // The example displays the following output:
+        //    8.5070591730234615847396907784E+37
+        //    0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0x3F
+        //
+        //    8.5070591730234615847396907784E+37
+        // </Snippet1>
+    }
+
+    private static void RoundtripInt16()
+    {
+        Console.WriteLine();
+        Console.WriteLine("Round-trip an Int16 value:");
+        // <Snippet2>
+        short originalValue = 30000;
+        Console.WriteLine(originalValue);
+
+        // Convert the Int16 value to a byte array.
+        byte[] bytes = BitConverter.GetBytes(originalValue);
+
+        // Display the byte array.
+        foreach (byte byteValue in bytes)
+            Console.Write("0x{0} ", byteValue.ToString("X2"));
+        Console.WriteLine();
+
+        // Pass byte array to the BigInteger constructor.
+        BigInteger number = new BigInteger(bytes);
+        Console.WriteLine(number);
+        // The example displays the following output:
+        //       30000
+        //       0x30 0x75
+        //       30000
+        // </Snippet2>
+    }
+
+    private static void HandleSignsInByteArray()
+    {
+        // <Snippet3>
+        int negativeNumber = -1000000;
+        uint positiveNumber = 4293967296;
+
+        byte[] negativeBytes = BitConverter.GetBytes(negativeNumber);
+        BigInteger negativeBigInt = new BigInteger(negativeBytes);
+        Console.WriteLine(negativeBigInt.ToString("N0"));
+
+        byte[] tempPosBytes = BitConverter.GetBytes(positiveNumber);
+        byte[] positiveBytes = new byte[tempPosBytes.Length + 1];
+        Array.Copy(tempPosBytes, positiveBytes, tempPosBytes.Length);
+        BigInteger positiveBigInt = new BigInteger(positiveBytes);
+        Console.WriteLine(positiveBigInt.ToString("N0"));
+        // The example displays the following output:
+        //    -1,000,000
+        //    4,293,967,296
+        // </Snippet3>
+    }
+
+    private static void RoundtripAmbiguous()
+    {
+        Console.WriteLine("Round-trip an Ambiguous Value:");
+        // <Snippet4>
+        BigInteger positiveValue = 15777216;
+        BigInteger negativeValue = -1000000;
+
+        Console.WriteLine("Positive value: " + positiveValue.ToString("N0"));
+        byte[] bytes = positiveValue.ToByteArray();
+
+        foreach (byte byteValue in bytes)
+            Console.Write("{0:X2} ", byteValue);
+        Console.WriteLine();
+        positiveValue = new BigInteger(bytes);
+        Console.WriteLine("Restored positive value: " + positiveValue.ToString("N0"));
+
+        Console.WriteLine();
+
+        Console.WriteLine("Negative value: " + negativeValue.ToString("N0"));
+        bytes = negativeValue.ToByteArray();
+        foreach (byte byteValue in bytes)
+            Console.Write("{0:X2} ", byteValue);
+        Console.WriteLine();
+        negativeValue = new BigInteger(bytes);
+        Console.WriteLine("Restored negative value: " + negativeValue.ToString("N0"));
+        // The example displays the following output:
+        //       Positive value: 15,777,216
+        //       C0 BD F0 00
+        //       Restored positive value: 15,777,216
+        //
+        //       Negative value: -1,000,000
+        //       C0 BD F0
+        //       Restored negative value: -1,000,000
+        // </Snippet4>
+    }
+
+    private static void RoundtripWithHex()
+    {
+        // <Snippet5>
+        BigInteger negativeNumber = -1000000;
+        BigInteger positiveNumber = 15777216;
+
+        string negativeHex = negativeNumber.ToString("X");
+        string positiveHex = positiveNumber.ToString("X");
+
+        BigInteger negativeNumber2, positiveNumber2;
+        negativeNumber2 = BigInteger.Parse(negativeHex,
+                                           NumberStyles.HexNumber);
+        positiveNumber2 = BigInteger.Parse(positiveHex,
+                                           NumberStyles.HexNumber);
+
+        Console.WriteLine($"Converted {negativeNumber:N0} to {negativeHex} back to {negativeNumber2:N0}.");
+        Console.WriteLine($"Converted {positiveNumber:N0} to {positiveHex} back to {positiveNumber2:N0}.");
+        // The example displays the following output:
+        //       Converted -1,000,000 to F0BDC0 back to -1,000,000.
+        //       Converted 15,777,216 to 0F0BDC0 back to 15,777,216.
+        // </Snippet5>
+    }
+}

snippets/csharp/System.Numerics/BigInteger/Overview/ByteAndHex_Examples2.cs

@@ -0,0 +1,43 @@
+// <Snippet6>
+using System;
+using System.Globalization;
+using System.Numerics;
+
+public struct HexValue
+{
+    public int Sign;
+    public string Value;
+}
+
+public class ByteHexExample2
+{
+    public static void Main()
+    {
+        uint positiveNumber = 4039543321;
+        int negativeNumber = -255423975;
+
+        // Convert the numbers to hex strings.
+        HexValue hexValue1, hexValue2;
+        hexValue1.Value = positiveNumber.ToString("X");
+        hexValue1.Sign = Math.Sign(positiveNumber);
+
+        hexValue2.Value = Convert.ToString(negativeNumber, 16);
+        hexValue2.Sign = Math.Sign(negativeNumber);
+
+        // Round-trip the hexadecimal values to BigInteger values.
+        string hexString;
+        BigInteger positiveBigInt, negativeBigInt;
+
+        hexString = (hexValue1.Sign == 1 ? "0" : "") + hexValue1.Value;
+        positiveBigInt = BigInteger.Parse(hexString, NumberStyles.HexNumber);
+        Console.WriteLine($"Converted {positiveNumber} to {hexValue1.Value} and back to {positiveBigInt}.");
+
+        hexString = (hexValue2.Sign == 1 ? "0" : "") + hexValue2.Value;
+        negativeBigInt = BigInteger.Parse(hexString, NumberStyles.HexNumber);
+        Console.WriteLine($"Converted {negativeNumber} to {hexValue2.Value} and back to {negativeBigInt}.");
+    }
+}
+// The example displays the following output:
+//       Converted 4039543321 to F0C68A19 and back to 4039543321.
+//       Converted -255423975 to f0c68a19 and back to -255423975.
+// </Snippet6>

snippets/csharp/System.Numerics/BigInteger/Overview/Mutability_Examples.cs

@@ -0,0 +1,75 @@
+using System;
+using System.Diagnostics;
+using System.Numerics;
+
+public class MutabilityEx
+{
+    public static void Main()
+    {
+        ShowSimpleAdd();
+        PerformBigIntegerOperation();
+        PerformWithIntermediary();
+    }
+
+    private static void ShowSimpleAdd()
+    {
+        // <Snippet1>
+        BigInteger number = BigInteger.Multiply(Int64.MaxValue, 3);
+        number++;
+        Console.WriteLine(number);
+        // </Snippet1>
+    }
+
+    private static void PerformBigIntegerOperation()
+    {
+        Stopwatch sw = Stopwatch.StartNew();
+
+        // <Snippet12>
+        BigInteger number = Int64.MaxValue ^ 5;
+        int repetitions = 1000000;
+        // Perform some repetitive operation 1 million times.
+        for (int ctr = 0; ctr <= repetitions; ctr++)
+        {
+            // Perform some operation. If it fails, exit the loop.
+            if (!SomeOperationSucceeds()) break;
+            // The following code executes if the operation succeeds.
+            number++;
+        }
+        // </Snippet12>
+
+        sw.Stop();
+        Console.WriteLine("Incrementing a BigInteger: " + sw.Elapsed.ToString());
+    }
+
+    private static void PerformWithIntermediary()
+    {
+        Stopwatch sw = Stopwatch.StartNew();
+
+        // <Snippet3>
+        BigInteger number = Int64.MaxValue ^ 5;
+        int repetitions = 1000000;
+        int actualRepetitions = 0;
+        // Perform some repetitive operation 1 million times.
+        for (int ctr = 0; ctr <= repetitions; ctr++)
+        {
+            // Perform some operation. If it fails, exit the loop.
+            if (!SomeOperationSucceeds()) break;
+            // The following code executes if the operation succeeds.
+            actualRepetitions++;
+        }
+        number += actualRepetitions;
+        // </Snippet3>
+
+        sw.Stop();
+        Console.WriteLine("Incrementing a BigInteger: " + sw.Elapsed.ToString());
+    }
+
+    private static bool SomeOperationSucceeds()
+    {
+        return true;
+    }
+}
+
+// <Snippet2>
+// CAPS bug: snippet2 is seen as duplicated, even though it isn't.
+// </Snippet2>

snippets/csharp/System.Numerics/BigInteger/Overview/Project.csproj

@@ -0,0 +1,8 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Library</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+  </PropertyGroup>
+
+ </Project>

snippets/csharp/System.Numerics/Complex/Overview/Program.cs

@@ -0,0 +1 @@
+CustomFormatEx.Run();